ballast-cli
v0.1.1
Published
Compliance-as-code for AI systems. Scan your repo, classify it against the EU AI Act, generate the paperwork, and catch governance drift in CI.
Maintainers
Readme
Ballast
Compliance-as-code for AI systems.
Ship AI with your papers in order.
In 1876, after years of campaigning by Samuel Plimsoll, British ships were required to carry a painted line on the hull. Load past it and the mark disappears underwater — visible from the dock, to anyone, without paperwork or an inspector. The limit became legible instead of arguable.
It took another fourteen years to matter. The 1876 Act let the shipowner decide where to paint the line, and some painted it on the funnel; the mark only became meaningful once its position was derived from the ship, in the Board of Trade's 1886 load line tables, and made compulsory in 1890. That second half of the story is the one this project is actually about.
Governance documentation for AI systems is currently the opposite: written once, in a document nobody opens, describing a system that has since changed nine times.
Ballast puts the line back on the hull.
npx ballast-cli demoOr replay the recorded run in your browser, no install: ballast.theogandolphe.com — the terminal there is not a video. It replays the committed cassettes and takes your input.
What it does
ballast init Answer nine questions a scanner cannot answer for you
ballast scan Find every model, SDK, prompt, tool definition and credential
ballast classify Propose a risk classification — you confirm it
ballast generate Write the risk assessment, model cards and compliance matrix
ballast check Fail CI when the code and the paperwork disagreeThe last one is the point. Everything else produces documents; check keeps them true.
── Governance drift ─────────────────────────────────────────────
! New model gpt-4o-mini is called but not declared.
src/screening.ts:42
The AI surface of this repository changed without the manifest
being updated. Review the changes, then run `ballast scan --write`
to record them, and re-run `ballast classify`.It runs with no API key, no network, and no per-run cost, because a check that bills you per pull request gets budgeted away, and one that needs a secret cannot run on forks.
Why this exists
The EU AI Act's obligations are landing in waves, and the waves keep moving. The Digital Omnibus on AI — Regulation (EU) 2026/1744, in force since 27 July 2026 — deferred high-risk obligations for standalone Annex III systems to 2 December 2027 and embedded-product systems to 2 August 2028, while leaving the Article 50 transparency duties for chatbots and generative AI on 2 August 2026 and GPAI obligations where they have been since 2 August 2025. Generative systems already on the market get until 2 December 2026 for Article 50(2)'s machine-readable marking, and nothing else moved.
So the live question for most engineering teams is not "is the AI Act coming" but the harder one: which obligation applies to this system, and when. That question is answered from the code, and the answer changes every time the code does.
Ballast is built for the engineer who was just asked whether their feature is compliant, and who is the only person who actually knows what the system does.
Ballast is late to this, and this README should say so. The commercial platforms — Credo AI, Holistic AI, OneTrust, IBM watsonx.governance — sell dashboards to a Chief Risk Officer, and the compliance-automation vendors who already own that buyer, Vanta and Drata, are adding AI modules to an install base Ballast does not have. Separately, at least five open-source tools already read code or traffic against the AI Act: Systima Comply, Regula, Warden and ArkForge's MCP scanner scan source; AIR Blackbox intercepts calls at runtime. Some are good. Systima Comply in particular detects frameworks with a real AST where Ballast currently uses line-based matching, and it ships a baseline-and-diff command of its own.
What differs is what happens after the scan. Those tools report findings and scaffold templates. Ballast drafts the actual documents — risk assessment, model cards, compliance matrix — from a dated corpus of 38 AI Act provisions and 48 obligations, through an agent pipeline with a critic that attacks the draft and a human confirmation gate that blocks generation until someone accepts the classification. Whether that is worth more than a better scanner is a fair question, and docs/business/competitive-analysis.md argues it honestly, including a table of where the alternatives are ahead.
How the agents work
classify and generate run four agents with deliberately narrow jobs.
| | | |
| --- | --- | --- |
| Surveyor | reads the code | Sandboxed read_file / list_files / grep, nothing else. Establishes what the system actually does with the models it calls. Reports what it could not determine. |
| Pilot | classifies | Reasons from the Surveyor's observations and your questionnaire answers to an EU AI Act tier and NIST AI RMF mapping. |
| Drafter | writes | Produces the documents. Every substantive claim must carry a reference to a finding, a config answer, or a provision. |
| Examiner | attacks the draft | Adversarial critic. Hunts for claims the evidence does not support — especially claims about controls that do not exist. |
Three design decisions carry most of the weight:
The model cannot invent law. The Pilot's output schema constrains citations to a closed enum built from the bundled knowledge base. A fabricated article number fails schema validation instead of reaching a document. Prompting alone does not survive contact with a confident model.
A human confirms the classification. classify writes its conclusion as proposed. generate
refuses to run until a person has accepted it, and records who and when. Machines may propose a legal
classification; people accept one.
The Examiner's unresolved objections are printed, not buried. Each document gets at most
maxCriticIterations examinations — two by default, so one redraft — and any blocking objection still
standing afterwards is printed and carried into the document's open questions. A pipeline that loops
until the critic gives up produces documents that satisfy the critic rather than documents that are
true.
Ballast also logs its own model calls, tool calls, validation retries and human sign-offs to
ballast/audit-log.jsonl — model version, token counts, request hashes, latency, and whether the call
was live or replayed. A tool that tells other teams to keep records of what their AI systems did has
no business failing to keep its own. Prompt and response content is deliberately never logged: these
files get committed, and prompts embed source code.
Install
npm install -g ballast-cliOr run it without installing: npx ballast-cli <command>. Requires Node 22 or later. scan, check and demo never call a model and need no key. classify
and generate use ANTHROPIC_API_KEY — your own key, billed to you, typically a few cents per run.
All four agents have been run against the live API end to end.
docs/example-run.md walks through it: 19 model calls, roughly $1.03, the Pilot
committing to provider and recording in the same breath that the commercial relationship "was not
specified", and the schema layer bouncing three malformed model cards before any of them reached a
document. Both transcripts and the documents they produced are committed, so the whole run replays
with no key:
ballast classify examples/resume-screener --offline assets/demo-cassettes/classify.jsonl
ballast generate examples/resume-screener --offline assets/demo-cassettes/generate.jsonlTo make the agent stages replayable offline for others, record a session once against the bundled example:
ANTHROPIC_API_KEY=... pnpm cassettes:recordThat writes transcripts to assets/demo-cassettes/, which classify --offline and generate --offline
replay. Cassettes are keyed by a hash that includes the prompt version, so editing a prompt invalidates
them and replay fails loudly rather than serving an answer to a question no longer being asked.
In CI
name: AI governance
on: pull_request
jobs:
ballast:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- uses: theogandolphe/ballast@mainThe action writes the drift report to the workflow summary and exposes a verdict output. Pin it to a
tag once one exists; @main is honest about where it currently points.
Exit codes: 0 clean, 1 material drift, 2 no committed baseline to check against.
What it writes
ballast/
├── manifest.yaml The declared AI surface. Read this one in a PR.
├── surface.json Exact scan baseline. `check` diffs against it.
├── classification.yaml The risk classification and who confirmed it.
├── risk-assessment.md Risks, mitigations, and what could not be established.
├── compliance-matrix.md Obligation → status → evidence, with dates.
├── model-cards/ One per model, describing your use of it.
└── audit-log.jsonl Every agent interaction. Not committed by default.All of it is meant to be committed. Governance artifacts outside version control cannot be reviewed, cannot be diffed, and cannot be trusted to describe the code as it shipped.
Limits, stated plainly
Ballast reads source code and a questionnaire. It cannot see your production behaviour, your training data, your evaluation results, or your operational processes, and it says so in the documents it writes rather than writing around the gap.
The knowledge base is a curated subset of the EU AI Act and NIST AI RMF, versioned and dated. It does not cover national implementing law, harmonised standards, or sector-specific regulation. Prompt and tool-definition detection is heuristic and marked as such — every finding carries a confidence tier, and the tool never claims more than it can show.
This is not legal advice. It is a way to keep an accurate, reviewable record of what your systems do, so that the conversation with someone who does give legal advice starts from facts. See docs/regulatory-notes.md for the methodology and its boundaries.
Documentation
- A complete run — all four agents against the bundled example, unedited, with both transcripts and the generated documents committed alongside
- Which obligations apply to your system, and when — a plain-English map of the four shapes most software teams actually are, generated from the same knowledge base the classifier uses, so the article and the tool cannot disagree
- Architecture — how the pieces fit
- Regulatory notes — what the knowledge base covers, and what it does not
- Decision records — why it is open source, and why it is not a dashboard
- Business documents — the strategy, shipped alongside the code
Contributing
The most useful contribution is a missing SDK. src/scanner/registry/known-sdks.ts is plain data —
add an entry, add a fixture under test/fixtures/repos/, open a pull request. Extending the knowledge
base is similarly mechanical and similarly valuable.
pnpm install
pnpm verify # lint, typecheck, test, build — the same gates CI runsCONTRIBUTING.md covers both in detail, along with the two invariants a pull request
must not break: the determinism contract behind ballast check, and the closed citation enum that
stops an agent inventing law.
License
MIT © Theo Gandolphe
