grounded

An offline question-answering appliance for document-heavy work. It runs on a machine inside the business, answers from a fixed corpus of authoritative documents, and attaches a citation to every claim it makes so the answer can be checked against the source. No network calls leave the box.

Written in JavaScript on Node, with a local model served by Ollama.

How it works

One engine, plus a pack per subject area. A pack supplies the corpus, the configuration, and a small code interface; the engine is the same for every deployment. The pack in this repo is US immigration law, built from the Immigration and Nationality Act.

The engine has three parts worth naming:

• Retrieval (engine/search.mjs, engine/corpus.mjs) — ranks passages from the corpus and passes them to the model as numbered references.
• Governance (engine/governance.mjs) — deny-by-default, and it inspects the model's output before it is returned: quotes are checked against the retrieved passages, references the model invented are flagged, and unverifiable text is not passed through as fact.
• Audit (engine/audit.mjs) — every answer and the passages behind it are recorded.

There is also an answer-audit layer (engine/support.mjs) that decomposes an answer into individual claims and checks each one against the retrieved sources.

Running it

There is no package.json and nothing to install — the engine uses only the Node standard library, and the tests use the built-in test runner. Verified on Node 24.16.

node --test engine/*.test.mjs      # 18 tests

Serving requires two things the repo does not contain: a corpus and a model.

# corpus.json is gitignored — supply one at packs/immigration-law/corpus.json
node grounded.mjs serve immigration-law     # http://localhost:8888

PORT and OLLAMA_URL override the defaults (8888, http://localhost:11434). The corpus format is an array of documents with id, type, title, citation, and text; the pack interface is specified in primer/specs/pack-interface.md.

Status

Working: the engine, retrieval, the governance layer, the audit log, and the immigration-law pack. The answer-audit layer is newer and has a local model behind its claim-checking seam.

Not built: the control panel for per-box administration, and the fleet management backend for provisioning and monitoring boxes. Both are described in the primer as intended work rather than existing code.

Documentation

primer/01-overview.md through primer/06-glossary.md cover the design. CLAUDE.md is configuration for working on the repo with Claude Code, and doubles as the current status note.