Content
# touchdesigner-wiki-rag
Search the entire TouchDesigner documentation from your AI agent — with real
citations.
This tool builds a local search index over the official TouchDesigner wiki
([docs.derivative.ca](https://docs.derivative.ca/), ~2,270 articles) and
exposes it to AI agents over [MCP](https://modelcontextprotocol.io/) (Claude
Code, Claude Desktop, Cursor, and any other MCP client). Every answer carries
a `Page § Section` citation with a clickable URL, so you can verify what the
agent tells you instead of trusting a model's memory of TouchDesigner — which
is exactly how you end up with hallucinated parameter names.
**You build the index yourself, on your machine, from the live wiki.** This
repo ships no documentation content — the docs belong to
[Derivative](https://derivative.ca/) and are fetched by each user directly
from docs.derivative.ca. The build takes ~45 minutes of unattended fetching
(politely rate-limited) plus a few minutes of indexing, and can run entirely
free with no API keys.
## Why not just let the agent browse the wiki?
Three reasons this beats live browsing: hybrid retrieval (exact-term BM25 +
semantic vectors, fused and reranked) finds sections a keyword search misses;
the index knows TouchDesigner's operator-family trap — **Noise TOP, Noise
CHOP, Noise SOP, and Noise POP are four different operators**, and results
warn when same-named siblings exist in other families; and answers are
grounded in retrieved text with citations rather than model memory.
## Requirements
- Python 3.12+ and [uv](https://docs.astral.sh/uv/)
- ~1.5 GB disk for the index
- **No API keys required** for the default fully-local setup
- Optional (better retrieval): an [OpenAI](https://platform.openai.com/) key
for stronger embeddings (about $1–2 one-time build cost) and HyDE query
expansion; a [Cohere](https://dashboard.cohere.com/) key for stronger
reranking (about $2 per 1,000 searches; free trial keys work)
## Quickstart
```bash
git clone https://github.com/johnnyvincentvitale/touchdesigner-wiki-rag
cd touchdesigner-wiki-rag
uv sync
cp .env.example .env # optional: add API keys; works fine empty
uv run python fetch.py # ~45 min, fetches the wiki via its public API
uv run python ingest.py --rebuild # chunks + embeds + indexes
# try it from the terminal
uv run python query.py "how do I add noise to a texture"
```
The embedding backend is chosen at build time — local
[bge-base](https://huggingface.co/BAAI/bge-base-en-v1.5) (free, no account)
by default, OpenAI `text-embedding-3-large` if `OPENAI_API_KEY` is set — and
stamped into the index so queries always use the matching model. See
`.env.example` for the details.
### Already have the docs? Skip the fetch
TouchDesigner installs bundle an **Offline Help** mirror of the wiki. If you
have it, import it instead of fetching (seconds instead of ~45 minutes):
```bash
# Windows (default install location):
uv run python fetch.py --offline-help "C:/Program Files/Derivative/TouchDesigner/Samples/Learn/OfflineHelp/https.docs.derivative.ca"
# then optionally pull only the pages edited since your mirror was generated:
uv run python fetch.py --update
uv run python ingest.py --rebuild
```
Notes: the mirror snapshots the wiki at your TouchDesigner release date —
`--update` tops it up from the live API. Recent **macOS** builds ship the
Offline Help folder empty (a known TouchDesigner issue), so Mac users should
use the plain API fetch.
## Configuration — what goes in `.env`
**Nothing is required.** With an empty (or absent) `.env`, everything runs on
free local models. Keys only upgrade individual stages:
| Variable | What it enables | Without it |
|---|---|---|
| `OPENAI_API_KEY` | `text-embedding-3-large` embeddings (stronger dense retrieval) + HyDE query expansion | local bge embeddings; HyDE disabled |
| `COHERE_API_KEY` | Cohere Rerank scoring | local ms-marco cross-encoder reranks |
| `EMBED_BACKEND` | force `local` or `openai` embeddings explicitly | inferred: `openai` if a key is set, else `local` |
| `EMBED_MODEL` | different OpenAI embedding model (e.g. `-3-small`, cheaper/weaker) | `text-embedding-3-large` |
| `COHERE_RERANK_MODEL` | different Cohere rerank model | `rerank-v3.5` |
| `HYDE_MODEL` | different HyDE model | `gpt-4o-mini` |
| `OPENAI_BASE_URL` | route OpenAI-client calls to any compatible server (see below) | api.openai.com |
Two behaviors worth knowing: the embedding backend is **stamped into the
index at build time** and queries auto-detect it, so you can't accidentally
query with the wrong model — but switching backends means rebuilding
(`ingest.py --rebuild`). And every API stage **degrades visibly, never
silently**: no Cohere key falls back to the local reranker, an unreachable
embedding API drops that search to keyword-only and says so in the response.
### Going fully local (including HyDE)
The default keyless setup is already local except HyDE, which simply disables
itself. To run HyDE on a local model, point the OpenAI client at any
OpenAI-compatible server — [Ollama](https://ollama.com/) or LM Studio:
```bash
# .env
OPENAI_API_KEY=anything-nonempty # satisfies the client; never sent anywhere real
OPENAI_BASE_URL=http://localhost:11434/v1
HYDE_MODEL=llama3.2 # any model you've pulled locally
EMBED_BACKEND=local # keeps embeddings on bge — required!
```
`EMBED_BACKEND=local` is load-bearing here: without it, setting
`OPENAI_API_KEY` flips embeddings to the OpenAI backend, which would then be
aimed at your local server expecting a model it doesn't serve. A small local
HyDE model is rougher than gpt-4o-mini, but HyDE only fires on low-scoring
searches and only keeps its result when it scores better — so the downside is
bounded. (This recipe follows the OpenAI SDK's documented `OPENAI_BASE_URL`
behavior but hasn't been exercised against a live Ollama by the author —
issue reports welcome.)
"Local" models still download once from Hugging Face on first use (no
account needed) and are cached after that; the wiki fetch itself needs the
network once. After the index is built, the keyless setup searches fully
offline.
## Hook it up to your agent
**Claude Code:**
```bash
claude mcp add --scope user touchdesigner-manual -- uv run --directory /ABSOLUTE/PATH/TO/touchdesigner-wiki-rag python server.py
```
**Any other MCP client** — stdio server config:
```json
{
"mcpServers": {
"touchdesigner-manual": {
"command": "uv",
"args": ["run", "--directory", "/ABSOLUTE/PATH/TO/touchdesigner-wiki-rag", "python", "server.py"]
}
}
}
```
### What the agent gets
| Tier | Tool | Returns |
|---|---|---|
| L0 | `browse_manual(query, family, limit)` | section map — cheap orientation, discovers the wiki's own vocabulary |
| L1 | `search_manual(query, family, limit)` | reranked passages with `Page § Section` + URL citations |
| L2 | `read_page(title, section)` | full page as markdown |
Plus resources: `manual://index` (corpus stats and freshness) and
`manual://operators/{family}` (operator roster per family).
`family` accepts TOP, CHOP, SOP, DAT, MAT, COMP, or POP to scope a search to
one operator family.
## How retrieval works
1. **BM25** over SQLite FTS5, Porter-stemmed — exact operator and parameter
names
2. **Dense vector search** over Chroma — paraphrased and conceptual questions
3. **Reciprocal Rank Fusion** combines both rankings
4. **Rerank** — Cohere Rerank if a key is configured, local ms-marco
cross-encoder otherwise (automatic fallback, works offline)
5. **Adaptive HyDE** — if the top rerank score is low (a reliable "retrieval
missed" signal), an LLM writes a hypothetical answer in the wiki's
vocabulary and retrieval re-runs on that. Fires only when needed, only
with an OpenAI key, and only keeps the result if it scores better.
Two guardrails ship in every response: a **family warning** when a result's
operator has same-named siblings in other families, and a **low-confidence
warning** when scores suggest retrieval missed — so an agent reports "not
found" instead of inventing an answer, and never concludes a feature doesn't
exist just because retrieval came back empty.
## Keeping the index fresh
The wiki changes continuously. Responses warn when pages have been edited
since your index was built (checked against the wiki's `recentchanges` feed,
cached hourly, skipped silently when offline). To update:
```bash
uv run python fetch.py --update # re-fetches only pages edited since last fetch
uv run python ingest.py --rebuild # rebuilds the index
```
## Known issues
- Every operator page carries an identical "Common Operator Info Channels"
boilerplate section; those chunks can pollute results on hard queries.
- The `--offline-help` importer is tested against synthetic MediaWiki static
pages, not yet against a real TouchDesigner install's mirror (the author's
macOS build ships it empty). If the import misses pages on your install,
please open an issue with a sample HTML file.
- Four title-variant pages (e.g. `Palette:webRTC Ext` vs `Palette:WebRTC
Ext`) collide in the page cache on case-insensitive filesystems; their
partner pages are indexed, so coverage impact is negligible.
- Rerank/HyDE score thresholds were calibrated on a small held-out query set;
they're adjustable in `retrieval.py` (`THRESHOLDS`).
- `ingest.py` is full-rebuild-only; with OpenAI embeddings that re-costs
~$1–2 per rebuild. The local backend rebuilds for free.
## Content ownership
All documentation content belongs to Derivative. This repository contains no
wiki content — only code that fetches it from the public API into a private,
local index, the same way a browser or TouchDesigner's built-in help fetches
it. Please keep the polite rate limits in `fetch.py` intact.
## License
MIT — see [LICENSE](LICENSE). Applies to the code in this repository only,
not to TouchDesigner or its documentation.
