Keyross

Ready-to-use verifiers for your agent loop. Official rules compiled into checks your agent must pass before it acts — pinned, deterministic, replayable.

The reference layer autonomous agents must pass before they act.

pip install "keyross[einvoice]"
keyross add einvoice          # the official EN 16931 rules, as a gauge
keyross check invoice.xml     # green / yellow / red — exit 0 / 1 / 2

Not a guardrail. A guardrail judges, probabilistically. A gauge runs the rule and returns its id. Not a test suite either: if pytest can test it, use pytest — Keyross verifies what leaves the agent.

Measured on one standard: e-invoices

EN 16931 is the European standard for electronic invoices, the base of the mandates rolling out across the EU (France since September 2026). CEN publishes its rules as official validation artefacts — 1,562 rule ids, such as BR-CO-10 the sum of the invoice lines equals the line total. The einvoice gauge runs them unmodified, offline, pinned by SHA-256; Keyross rewrites none of them. Its delta oracles add what the standard cannot know: the invoice against its order.

A pre-registered benchmark — the same agent with one model (Claude Haiku 4.5), 300 runs on 23 September 2026, graded by judges that are not Keyross:

Protocol, raw data, every delivered invoice, a blind human review (21/21 agree with the judges): bench/einvoice · the page, with a cost model: keyross-oss.github.io/keyross/bench.

On the shelf

Want one that is not here? Open a discussion in Wanted verifier: the document your agent got wrong, and where the truth lives. More in GAUGES.md.

Where it plugs in

Nothing requires an account, a cloud or a cluster; no model and no network run during a check.

Three words: gauge, yoke, flags

from keyross.yoke import Yoke
agent = create_deep_agent(..., middleware=[Yoke(gauge="einvoice")])   # Deep Agents / LangChain

A gauge is not a skill, a prompt or a CLAUDE.md: those are text a model reads and may follow. A gauge is code the harness runs and the model never sees. A skill asks. A gauge measures.

Five minutes

pip install "keyross[einvoice]"
keyross init                  # keyross.yaml, oracles/, badset/
keyross add einvoice          # the EN 16931 gauge: the official CEN rules, pinned
keyross check invoice.xml     # an EN 16931 invoice (UBL / CII) → green / yellow / red, exit 0 / 1 / 2
keyross check quote.xlsx      # a quote or any priced table → the core gauge
keyross test                  # does every oracle catch its bad case? (tests for the tests)
keyross lint                  # refuse any oracle that calls a model or the network
keyross lock                  # pin the oracles: the answer to "what verified this run?"

Every check writes a report; the lock pins what ran; keyross gate replays it all outside the agent. A real example to replay: docs/audit-trail.md.

Status and roadmap

0.1.2 (this release) — the front page: the stack diagram, the GitHub Action, the audit trail, Discussions. Planned next, in this order — an order, not a promise of dates:

• 0.1.3 — rules: your AGENTS.md / CLAUDE.md rules enforced on every commit, and the pre-commit hook
• 0.1.4 — payments in packages/; the Claude Code hook
• 0.2 — keyross add copies packages from this repository's index; the XML schema step in einvoice; native hooks for Codex CLI and Gemini CLI; a benchmark of rules across coding agents
• Later — comments, pr and expense; keyross new (write a verifier, prove it on its bad cases); an MCP server

This repository verifies itself: on every commit, its CI runs the tests (one checks the table above against the benchmark's raw results), keyross test, keyross lint, keyross lock --check and the GitHub Action.

Going further

• docs/audit-trail.md — what was verified, and how a third party replays it
• docs/CONCEPTS.md — invariants, contracts and sentinels; the flags; writing an oracle
• docs/ARCHITECTURE.md — where the gauges run, what comes out of every door
• MANIFESTO.md · GAUGES.md · CONTRIBUTING.md · GOVERNANCE.md · SECURITY.md

Who maintains this

Keyross is written and maintained by Wassim Amri, a practitioner who builds agents for documents where an error costs money. Issues and Discussions are read; security reports go through SECURITY.md.

License

Apache-2.0. The engine and the public gauges are open, and stay open; contributions under the Developer Certificate of Origin (git commit -s), no CLA. Cite it: 10.5281/zenodo.22938584.