Deterministic checks that can overrule a confident LLM judge.
Lithrim is an open-source evaluation harness for AI-generated artifacts. An ensemble of LLM judges raises signals, deterministic grounding checks test those signals against the source of truth, and every case ends cleared, flagged, or escalated to a person, with an append-only audit record that says what backed the verdict.
Lithrim treats a judge's opinion as a lead, not a finding. Judges raise signals, grounding checks test them against the source, and every verdict says what backed it: cleared, flagged, or escalated. Never cleared by silence.
The demo needs no key and no network, and runs in about ten seconds. Clinical note review is the reference domain; the engine is domain-agnostic.
Case
A generated description, checked against the record it came from.
The value check compares every number the response states with the structured record. One stated value has no source, so the case is flagged with the value named.
One of five public, human-labeled RAGTruth cases that ship with the repo. Run make queue to replay the judges for $0 and run the checks live.
A second model's opinion is not verification.
A probabilistic reader cannot be its own evidence. Deterministic checks against a record, a schema, or a terminology service can, for the claims they are able to reach.
A judge is as fallible as what it grades
Most AI review ends at an LLM-as-judge: a second model scoring the first. It can approve a fabricated fact with confidence, or flag a correct one with the same confidence.
More judges did not fix it
The study behind this project ran five judge configurations, from a single frontier model to a six-model ensemble. None moved the needle. On clean notes the judges kept raising problems that were not there.
Confidence is not evidence
Lithrim reads per-judge confidence from token logprobs where the provider exposes them and reports None where it does not. Either way, a judge's confidence never clears a signal. Only a check does.
This is not a better judge. Judges are commodity. It is the grounded floor underneath the judge, with a map of its own limits.
How It Works
Three moves per case, and the evidence rides along.
Judges raise signals. Checks test those signals against the source of truth. The case lands in one of three states, with an audit record that says what backed it.
Judges raise signals against named flags.
You configure the roles, criteria, and models, with any mix of providers. Each judge reads the artifact and reports typed findings with evidence spans. Consensus is tiered by severity, and the consensus code is frozen and guarded by tests.
Each flag is bound to a deterministic check.
Checks run against a record, a schema, a terminology service, or a knowledge base. A check can override the judges in both directions. A check that cannot decide returns inconclusive. A failed lookup is recorded as a failed lookup, never converted into a pass.
Every verdict says what backed it.
Each case is written to an append-only record with a floor_backstopped stamp. A cleared case that rests on judges alone says so. A replay reproduces the result, or refuses because the configuration changed.
Most evaluation setups use rules as a cheap pre-filter and let the LLM judge make the final call. Lithrim inverts that: the judge screens, and the verifiable floor decides everything it can ground.
Measured limits
What it does, and what it does not.
The floor's power is bounded. The boundary was tested with a blind held-out experiment instead of being asserted.
Where the floor generalizes: structured, closed-vocabulary facts
Arithmetic, code and terminology membership, schema conformance, record presence. On RAGTruth, with human spans as gold, a value the response states but its structured record never had is a real contradiction at precision 0.78 strict, 0.94 any-label, and recall 0.82.
Where it does not: open-ended discourse
The same value check on prose sources has precision 0.10, so there the reviewer only names the value as a lead and escalates. In a blind held-out test, a serious 30-pattern lexical rule scored recall 0.375 and precision 0.75. For that class of claim, a judge or a person is the right tool.
No manufactured wins.
This is the one rule in the contributing guide. If a result is a loss, the project reports the loss.
No number without its method and data.
Every figure on this page links to the study, the repo, or the sample it was measured on.
Never cleared by silence.
A check that cannot decide returns inconclusive, and the case goes to a person.
Not a medical device.
Lithrim is a developer evaluation harness. It is not clinical decision support, and it is not HIPAA-certified, FDA-cleared, or clinically validated. All bundled sample data is synthetic.
Use the floor for grounded, structured claims. Use a judge, and a person, for open-ended discourse.
Research
We tried to prove ourselves wrong. In public.
We published our judge-versus-floor study with the full dataset. Then we found a flaw in our own corpus, one that might have excused the AI judges' false alarms. We could have stayed quiet. Instead we preregistered a correction with numeric pass/fail rules, predicting the judges would be partly vindicated, and reran all 540 grades on the corrected corpus at our own expense.
Our prediction lost, 0 for 8. The judges kept hallucinating problems on clean notes and invented new ones. The registration made publishing it mandatory either way, and we did: the refutation is version 2 of the study, live under the same concept DOI. Through all of it, the deterministic floor held its ground on the upcodes: it confirmed 15 of 22 directly from live SNOMED, declined the rest without guessing, and falsely cleared 0.
What you can reproduce from the repo: the 44 synthetic cases and every metric derived from them. Ten physician-curated cases are withheld pending attribution consent, so scorecard totals reproduce at n=44 instead of n=54. A full rerun needs your own model keys and a self-licensed SNOMED index.
Quickstart
Three commands, no key, no network.
The demo replays a captured judge baseline for $0 and runs the grounding checks live on a built-in case. Three judges raise signals, the consensus verdict is PASS, the harness rescores it to BLOCK, and the audit record says exactly what backed that.
When you want the full stack, one more command brings up the API and the UI in containers. Bring your own model key: OpenAI, Azure, Anthropic, Gemini, or any OpenAI-compatible endpoint. There is no account, no hosted inference, and no telemetry.
# offline demo: no key, no network
git clone https://github.com/lithrim-dev/lithrim
cd lithrim && pip install -e .
make demo
# then work a queue of five public cases
make queue
# full stack: API on :8787, UI on :5180
docker compose up
Contribute
Built in the open, with seams made for outside work.
Lithrim is a community release: a working harness and a runnable demo, not a finished product. The bar for changes is correctness and honesty, not breadth. These are the seams built for outside work.
Write a pack
A domain is a pack: an ontology, a taxonomy, judge role prompts, and grounding checks. Packs load from outside the repo with zero engine edits. Two sample packs ship as worked examples.
Pack drop-in guideBring a dataset
A dataset enters through an adapter and an importer manifest, never through the engine. The RAGTruth adapter is the reference implementation.
Importers how-toAdd a check or a connector
Checks and connectors are manifest entries plus an executor, with MCP as the transport. This plane is still experimental, so design feedback is as useful as code.
Connector specReport an over-claim
If a doc or an output promises more than the code proves, that is a bug. There is an issue template for it, and that includes this website.
Open an over-claim reportFrequently Asked Questions
Common questions about the project
An open-source evaluation harness for AI-generated artifacts. An ensemble of LLM judges you configure raises signals on each case, deterministic grounding checks test those signals against the source of truth, and the case ends cleared, flagged, or escalated to a person, with an append-only audit record.
That experiment was run twice and both runs are published. Five configurations, from a single frontier model to a six-model ensemble: none moved the needle. A probabilistic reader cannot be its own evidence. Deterministic checks against a record, a schema, or a terminology service can, for the claims they are able to reach.
No. Deterministic checks cover what is checkable against a source, and every verdict is stamped with whether a check or only the judges backed it. In the published study the floor confirmed 15 of 22 upcoded diagnoses directly from live terminology, declined the rest without guessing, and falsely cleared 0. On open-ended discourse it does not generalize, and the project says so with numbers.
No. Clinical note review is the reference domain and the subject of the study, but the engine is domain-agnostic. A domain is a pack that loads from outside the repo with no engine edits. The default pack is neutral, a small non-clinical sample pack ships alongside the synthetic clinical one, and the bundled queue demo runs on RAGTruth news, QA, and data-to-text cases. The non-clinical evidence so far is thinner than the clinical evidence.
The software is free under Apache-2.0 and self-hosted. The offline demo needs no key and no network. For live grading you bring your own model key, so you pay your model provider directly. There is no Lithrim account, no hosted inference, and no telemetry.
Clone the repository and run pip install -e . for the core, or use docker compose up for the API and UI. Tagged releases also publish container images. It is not on PyPI yet.
Every run stores its configuration, evidence, and typed results. Replaying it reproduces the result, or refuses because the configuration changed. The audit table is append-only: the code exposes no update or delete path. It is not a cryptographic tamper-proof log.
Partly, from the repo alone. The 44 synthetic cases and every metric derived from them are tracked and match the Zenodo deposit. Ten physician-curated cases are withheld pending attribution consent, so scorecard totals reproduce at n=44 instead of n=54. A full rerun is about 540 paid grades and needs your own model keys plus a self-licensed SNOMED index.
No. Terminology checks are optional. Without a terminology index those checks return inconclusive and the harness still grades. SNOMED is never redistributed with the project; you supply your own licensed copy if you want that check.
No, no, and not applicable by design. Lithrim is a developer evaluation harness, not a medical device and not clinical decision support. Its verdicts are signals to route human review. All bundled sample data is synthetic, and any clinical use requires qualified human oversight.
It is a community release with one maintainer so far. The judge council, the grounding-floor mechanism, the audit record, and the neutral default pack are stable. The connector plane, the conversational UI, and multi-provider councils are experimental. Authentication for exposed deployments is not included yet.
Write a pack for a new domain, bring a dataset through an importer, add a check or a connector, or file an over-claim report when a doc promises more than the code proves. The contributing guide has one rule that matters: no manufactured wins.