Setup

Install and run.

Theoryscope is a two-process application: a FastAPI backend that owns the embedding model and the corpus cache, and a Next.js frontend that owns the visualisation. Both run locally.

01 · Prerequisites

What you need before you begin.

Node.js	Version 18 or newer. nodejs.org, or nvm install 20.
Python	Version 3.11 or newer. The backend uses features introduced in 3.11.
Disk space	Around 2 GB free, for the Python virtual environment and the first embedding model download.
Zotero account	Only for analysing your own corpus; the Phase 0 demo does not need one. See the Zotero API key walkthrough.

02 · Install

Clone and bootstrap.

Clone the repository

git clone https://github.com/vector-lab-tools/theoryscope.git
cd theoryscope

Install the frontend
```
npm install
```
Pulls Next.js, React, Three.js, Plotly, and the rest. One or two minutes.
Set up the Python backend
```
cd backend
./setup.sh
```
setup.sh creates a local .venv and installs FastAPI, uvicorn, sentence-transformers, scikit-learn, umap-learn, and pyzotero. The default embedding model (all-MiniLM-L6-v2, around 90 MB) downloads on first use rather than at install time.

03 · Run

Two terminals.

Keep both running while you use Theoryscope. The frontend proxies every /api/backend/* request to the backend on localhost:8000, so the order they come up in does not matter.

Terminal 1 — backend

cd backend
source .venv/bin/activate
uvicorn main:app --reload --port 8000

Terminal 2 — frontend

npm run dev

Open http://localhost:3000.

Screenshot pending · the Theoryscope landing page in a browser.

04 · First run

The Phase 0 demo.

Click Load Phase 0 Corpus. Theoryscope embeds the twenty-document philosophy-of-technology corpus built into the backend (no Zotero needed) and renders the Corpus Map. The first run takes roughly thirty seconds while the embedding model downloads; subsequent runs are a couple of seconds.

Screenshot pending · the Corpus Map after loading Phase 0.

The deep-dive panel at the bottom of the Corpus Map shows the full provenance record — corpus hash, document IDs, embedding model, chunking spec, operator, timestamp. Every exported result carries this record.

05 · Your own corpus

Pointing Theoryscope at Zotero.

Open the Corpus Source panel on the left and choose Zotero. Theoryscope asks for three fields: library ID, library type, API key. The Zotero key walkthrough covers each one, with the gotcha that trips every first-time user.

Zotero API key, step by step Operations guide