Vector Lab · a research instrument
Theoryscope
A renormalisation-group workbench for corpora of theoretical texts.
Theoryscope treats a corpus as a geometry. It embeds each text with an open-weight model, computes the principal eigendirections of the cloud, coarse-grains the field under a visible operator, and reports which structures survive. The gap between what a field says it is about and what its geometry says it is about is readable on screen.
01 · About
A corpus is a geometry. The instrument reads its shape.
Theoryscope ingests a corpus, embeds each document with an open-weight sentence-transformer, and provides seventeen operations for inspecting the cloud's structure. Three analytical modes sit alongside each other: Inspect reads the field at rest; Flow coarse-grains it and watches what persists; Critique asks whether the finding survives a different embedding, a one-document perturbation, a bootstrap, a translation.
Every operation runs locally. Theoryscope does not call OpenAI, Anthropic, Cohere or any other commercial embedding or generative API. The embedding models (MiniLM, MPNet, BGE) and the small generative models used by the Corpus-vs-Model Probe (SmolLM2, GPT-2) download once from HuggingFace and then run offline. The only credential it needs is a Zotero API key, so it can read your library.
Every result carries a provenance record: corpus hash, document IDs, embedding model, chunking spec, operator, timestamp. A finding that cannot be cited and re-run is not a finding. Theoryscope is open source under the GPL-3.0-or-later licence and part of the Vector Lab.
| Object | A corpus of theoretical texts (a Zotero collection, or a curated list). |
|---|---|
| Method | Open-weight sentence embeddings, PCA eigendecomposition, coarse-graining operators. |
| What you need | A Zotero account and API key. Node.js 18+. Python 3.11+. Roughly 2 GB of free disk. |
| What you do not need | Any commercial API key. All models run on your machine. |
| Licence | GPL-3.0-or-later. |
02 · The three modes
Inspect. Flow. Critique.
A short tour. The Operations guide walks each in turn with worked examples.
What does the field look like?
The Corpus Map renders every document as a point in a 3D PCA projection. Each principal component is annotated with the documents that load most positively and most negatively on it. Those paired lists are the axis. Enter the opposition the field says it is structured by, and Theoryscope reports which computed PC is most aligned with it. Debated axes and computed axes rarely match.
What survives abstraction?
Theoryscope coarse-grains the cloud under a visible operator (progressive k-means, with semantic and citation-graph operators planned) and animates the trajectory. The Fixed Point Finder reports the basins the flow terminates in. The Universality Class Finder ranks classes by ascending surface cosine, so classes whose members looked different on the surface but converged on the same basin surface at the top.
Would this result survive a different embedding?
The Embedding Dependence Probe re-embeds the corpus under a second open-weight model and reports per-component agreement. The Perturbation Test adds one out-of-field text, recomputes, reports per-component rotation. The Forgetting Curve bootstraps: twenty iterations, each dropping twenty per cent at random, and reports mean, variance and interquartile range. A finding that holds under all three is a finding you can cite.
03 · Quick start
Three commands, two terminals, one demo corpus.
The Phase 0 corpus (twenty documents in philosophy of technology) is built into the backend, so you can run Theoryscope end to end without a Zotero key.
git clone https://github.com/vector-lab-tools/theoryscope.git cd theoryscope npm install cd backend && ./setup.sh
Then, in two terminals:
# terminal 1 cd backend source .venv/bin/activate uvicorn main:app --reload --port 8000 # terminal 2 npm run dev
Open http://localhost:3000 and click Load Phase 0 Corpus. For your own corpus, follow the Zotero API key walkthrough.