assurance-core

Did your agent read everything it was supposed to read?

Every tool call can return 200 and the answer still be built on two thirds of the data.

Groundedness checks the output against the input. This checks the input against the question.

pip install assurance-core

from assurance_core.coverage import Coverage

Coverage.of(
    expected=["msa.md", "amendment-1.md", "amendment-2.md"],  # what the question spans
    found=["msa.md"],                                          # what your retriever returned
    where="the retrieved set",
).summary()

# '1 of 3 items — not in the retrieved set: amendment-1.md, amendment-2.md'

Zero dependencies · Python 3.10+ · no model decides any of it

Use it for

Keys are anything you can name, so the same three lines cover:

Six runnable examples in examples/, held green by CI.

A gap is six different facts, not one

Most tools give you one missing bucket. It throws away the only thing you need — what to do next.

A capped "24 of 24 — complete" is worse than no number at all, so truncated makes complete false on its own. We don't know what we didn't see is not nothing.

The wording is deliberate too: "not in this folder", never "missing". The first is a fact about a directory listing. The second is a guess about the world.

No model, and it's gated not claimed

Every module is walked by an AST test that fails on a model or service import. CI runs it on 3.10 – 3.13, then imports all sixteen modules from an installed copy and asserts nothing leaked into sys.modules.

Swap the model and the prose changes. The arithmetic doesn't.

Modules

Honest limits

• It will not derive your expected set. That's your declaration on purpose — a denominator a tool invents is one nobody can argue with
• Some modules carry I-Ops' own data as their worked example. worker.VINCI is a WorkerDefinition for our product, policy_config.default_allow_vinci() builds a rule set around it, and effects.CAPABILITY_EFFECTS is our capability table (draft, render, and what may stage a Gmail draft). They are there because this is a publication of a working system, not a clean-room SDK — but they are examples, not the interface. coverage, staleness, admission, sequence and report_period carry nothing product-specific
• Many conditions still have no verifier, so the honest answer stays complete but unverified
• Source admission is provenance-only — inert on a corpus with no tombstones or supersessions
• Staleness needs a prior artifact record, which this library does not provide
• Not a runtime, an agent framework, or anything that does something on its own

In 0.3.0

Coverage(expected=..., found=...) without missing used to report complete is True on 11 of 12. The library that exists to stop successful-looking wrong answers had an API that made one. Coverage.of() now derives the gap, unaccounted blocks completion, and read counts the intersection. If you build Coverage(...) directly, move to Coverage.of(...).

Family

assurance-cli — same checks as a command, for CI · assurance-mcp — same checks as MCP tools

Upstream is I-Ops; this repo is a publication, never a source. Apache-2.0 · Contributing · Security