Document AI Trust
Ethos Verification
Ethos answers one bounded question: do caller-provided citation claims bind to evidence exposed by a trusted grounding source? It returns proof states and audit artifacts. Relevance, synthesis, and answer release stay with your application.
Quickstart
Verify A Citation
This local fixture path exercises citation verification without PDF parsing.
Verify grounded evidence
bash
git clone https://github.com/docushell/ethos.git
cd ethos
cargo build --locked -p ethos-cli
./target/debug/ethos verify schemas/examples/document.example.json \
--citations examples/verify/native_grounded_citations.json \
--fail-on-ungroundedInterpretation
Read Results As Actions
Each outcome has a different operational response. Do not collapse them into one red badge.
| Outcome | Meaning | Next step |
|---|---|---|
grounded | The supported claim binds to supplied source evidence. | Continue to application relevance and claim-support review. |
mismatch | The target resolved, but the cited evidence does not match. | Block the claim and inspect the generator or source mapping. |
not_found | A required target or locator could not be resolved. | Refresh the index or correct the citation contract. |
stale_fingerprint | The citation belongs to a different source version. | Re-parse, re-index, and regenerate before release. |
capability_limited | The source cannot prove the requested evidence kind. | Obtain stronger source evidence or route to review. |
Application policy
Use Ethos As A Release Gate
Generate structured claims, resolve their evidence references through trusted source artifacts, run Ethos verification, retain the canonical report, then apply your own relevance, synthesis, and claim-support policy.
A conservative first policy releases only direct source facts with grounded citations, direct relevance, and claim support marked supported. Partial evidence is disclosed or reviewed. Unverified, stale, unsupported, contradicted, or unevaluated claims do not release as final text.
- Treat model-returned citation IDs as candidates, not trusted file or network paths.
- Keep
verification_report.jsonas the audit artifact. - Make
claim_support: not_evaluateda review or block state, never implicit approval.
Limits
What Ethos Does Not Decide
Ethos does not determine whether a grounded passage answers the user's question, whether a synthesis follows from several facts, whether arithmetic is correct, or whether a source is authoritative for the situation. It also does not silently fill evidence gaps.
A literal quote can be grounded while the surrounding answer is misleading. Advanced integrations should surface structural provenance and bounded source context so a reviewer can judge the claim in context — those fields speed up review, they are not a semantic truth score.
- Scanned or image-only PDFs require OCR outside the base Ethos path.
- A foreign parser can be verified only to the fidelity of its declared pages, text, geometry, tables, fingerprints, and capabilities.
- Semantic review, when used, belongs in a separately named application or human-review layer.