A previous release had provenance metadata, but this release does not. View details.
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/v1instead ofhttp://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:
| level | download | on disk | contains |
|---|---|---|---|
| L0 | 52 MB | 0.2 GB | top 0.5% most notable entities |
| L1 | 92 MB | 0.35 GB | top 1% |
| L2 | 159 MB | 0.6 GB | top 2% |
| L3 | 265 MB | 1.0 GB | top 4% |
| L4 | 427 MB | 1.6 GB | top 8% |
| L5 | 691 MB | 2.6 GB | top 16% |
| L6 | 1.1 GB | 4.2 GB | top 32% |
| L7 | 2.2 GB | 9.2 GB | everything |
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).
Metadata
Release files for openballast 0.3.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Loss of provenance
These files do not have provenance metadata, despite files in a prior release including this data.
We recommend further investigation before installing these files. View details.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| openballast-0.3.0.tar.gz | 37.0 kB | Without provenance | Details for openballast-0.3.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| openballast-0.3.0-py3-none-any.whl | Python 3 | none | any | Details for openballast-0.3.0-py3-none-any.whl |
Total release size: 72.9 kB
Release files / openballast-0.3.0.tar.gz
Loss of provenance
This file belongs to a release without provenance metadata, despite a prior release including this data.
We recommend further investigation before installing this file. View details.
| Download URL | openballast-0.3.0.tar.gz |
|---|---|
| Size | 37.0 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
af15e30c70d57c054b0ea5f4e78f9b71edc31276cd36e293542afb7d3cdade9b
|
|
BLAKE2b-256 checksum How to use checksums |
60c68d2dc908505ec0187c2adc3e69cb072f417e87a88ac5e99477d49b12a908
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
uv/0.12.0 {"installer":{"name":"uv","version":"0.12.0","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":null,"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":null}
|
Release files / openballast-0.3.0-py3-none-any.whl
Loss of provenance
This file belongs to a release without provenance metadata, despite a prior release including this data.
We recommend further investigation before installing this file. View details.
| Download URL | openballast-0.3.0-py3-none-any.whl |
|---|---|
| Size | 35.8 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
cf492758ab637ce8b2f22fb21d316326d8afde87c4a97ae4bc97478a83ac8c6d
|
|
BLAKE2b-256 checksum How to use checksums |
22332929ca6838a680fcf20d0043e33d84bea9a607672f42ac429122f7165741
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
uv/0.12.0 {"installer":{"name":"uv","version":"0.12.0","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":null,"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":null}
|
Security for openballast 0.3.0
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
Loss of provenance
A previous release of these files had provenance metadata, but this release does not.
While this could reflect a routine change by the project maintainers, it may also indicate that the release files have been compromised.
Release comparison
- Removed 0.1.1 2 files With provenance
- Added 0.3.0 2 files Without provenance
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.