ballast

Pull a quantized knowledge corpus — or build one from your own documents — and ground any local model. Works with Ollama and every OpenAI-compatible or MCP-capable client. Includes model profiling and a three-arm grounding benchmark, all CPU-only.

uvx openballast pull --level 3
uvx openballast serve

(Live on PyPI: pip install openballast also works.)

• Ollama users: point your client's base URL at http://localhost:11435/v1 instead of http://localhost:11434/v1 — done. Every chat request is grounded with corpus facts before your model sees it. No tool calling needed, works with any model size.

• MCP users (Claude Desktop, LM Studio, Cline, Goose): add to your MCP config:

  { "ballast": { "command": "uvx", "args": ["openballast", "mcp"] } }
  

• Smoke test:

  uvx openballast lookup "Where was Douglas Adams born?"
  

What you're downloading

Ballast T0: 25.4M entities and 197M facts from Wikidata (CC0), quantized into nested levels — pick your knowledge size like you pick a GGUF quant:

Levels are nested: pull --level 5 after pull --level 3 downloads only the new buckets. Everything runs offline after the pull — no network at answer time.

Measured effect (details: thesis): a 2B model + ~180 MB of ballast exceeds a 12B model's factual accuracy; hallucination on factual probes drops ~3×.

Commands

ballast pull  --level 3      # download / upgrade the corpus
ballast build ./docs -n team # build a corpus from YOUR documents (see below)
ballast serve                # OpenAI grounding proxy :11435 + MCP http :11436
ballast mcp                  # MCP on stdio (for client configs)
ballast lookup "question"    # print the evidence blocks for a question
ballast profile -m qwen3:8b  # where does this model's knowledge run out?
ballast eval    -m qwen3:8b  # three-arm benchmark: what does grounding buy?
ballast status               # installed corpora, levels, and sizes

BALLAST_HOME overrides the storage location (default ~/.ballast).

Bring your own corpus

ballast build turns a directory of .md / .txt files (and/or parquet with a text column, optional title and rank) into a servable corpus with the same layout as the published one:

ballast build ./handbook --name handbook
ballast lookup --corpus handbook "What is our deploy freeze policy?"
ballast serve  --corpus handbook

Documents are addressed by title; each becomes passage chunks the linker can attach to a question. A rank column (0..1, 1 = most important) spreads documents across nested levels so --level keeps the top slice; without ranks everything lands in one level.

Profile a model, then size the corpus for it

ballast profile -m qwen3:8b --limit 2000 --budget 2GB

Probes the model ungrounded against the public evalset, reports its accuracy per corpus region (head → tail), fits a grounding competence profile (.gcp.json), and — given a byte budget — recommends the corpus level where grounding still buys accuracy for THIS model. The profile carries a reliability AUC against a 0.58 gate; below the gate the recommendation falls back to the generic ordering.

Measure what grounding actually delivers

ballast eval -m qwen3:8b --limit 500

Every probe is asked three ways: ungrounded (U), with realized retrieval (R), and with oracle-entity evidence (S). The report is the delivery ratio (R − U) / (S − U) — the fraction of the reachable knowledge gap today's retrieval closes — plus coverage-conditional splits. Arms checkpoint to parquet and resume after interruption.

How it works

serve intercepts POST /v1/chat/completions, mines entity mentions from your last message, resolves them against the local corpus (normalized label/alias match), and prepends the matching facts as a system message. Everything else — including streaming — passes through untouched. The MCP server exposes the same three tools (resolve, evidence, lookup) as the hosted demo endpoint (mcp.openballast.org).

Apache-2.0. Corpus data: CC0 (Wikidata contributors).