Skip to main content
Loss of provenance

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/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:

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)

Source distribution for openballast 0.3.0
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)

Table of built distributions (wheels) for openballast 0.3.0
File Interpreter ABI Platform Actions
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.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page