FAQ

FAQ

Do I need an API key? No. EMBED_PROVIDER and LLM_PROVIDER default to offline implementations. The whole repository, including the test suite and the evaluation harness, runs with no key and no network.

Why no LangChain or LlamaIndex? They are fine tools that hide the seven steps. The entire point here is that the steps are visible and hand-written. Build it once by hand and the frameworks become legible afterwards.

Can I use Claude for everything? No. Anthropic serves generation, not embeddings. Pair Claude with OpenAI, Voyage or Cohere for step 3. This is the most common surprise in the pipeline.

Do I need a GPU? No. Embedding and generation happen over HTTP at a provider. Nothing here runs a model locally.

Do I need Postgres? No. The JSON store is the default and handles a few thousand chunks instantly. Move when linear scanning stops being instant.

Why is my answer citing nothing? Either retrieval returned nothing useful, or the prompt allowed an uncited answer. Check retrieval first with npm run query -- --hits. auditAnswer flags this case automatically.

Why does it say it cannot find something that is clearly in my documents? Usually the chunk is too large and the meaning has been averaged away, or the question uses vocabulary the document does not. Check with --hits; if the chunk is not in the top results, it is a retrieval problem, not a prompt problem.

How much does this cost to run? Indexing is cents. Querying is two API calls per question. Cache query embeddings, cap max_tokens, and measure with docs/10-architecture.md's latency table as a template.

Can I use it commercially? Yes. MIT, and no permission is required to adopt, edit, refactor or teach from it.

Can I use this as courseware without asking? Yes. That is what it is for. No permission, no notification, no attribution required beyond the licence notice.

How do I add my own documents? Put .txt, .md or .html files in a folder and run npm run index -- ./that-folder.

Why 51 slides and 137 tests but only 12 seed documents? The corpus is deliberately small so it indexes in under a second and the evaluation runs in ten. Bring your own; the pipeline does not care.

Something is wrong and this page did not help. Open an issue with the command, expected result, actual result, Node version and the output of npm run query -- --hits.