Document AI Trust
Ethos Verification
Ethos verifies whether supported citation claims bind to trusted source evidence. It returns proof states and audit artifacts; your application remains responsible for relevance, semantic support, and answer release.
Start here
What Ethos verifies
Ethos answers one bounded question: do caller-provided citation claims bind to evidence exposed by a trusted grounding source? It can check supported quotes, values, table cells, pages, regions, and source fingerprints.
A grounded citation is necessary evidence, not a complete answer-quality verdict. Keep retrieval quality, question relevance, synthesis, calculations, and final release policy outside the verifier.
Quickstart
Verify a citation in five minutes
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 verification results as actions
Do not collapse different failure modes into one red badge. Each outcome has a different operational response.
| Outcome | Meaning | Recommended 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.
DocuShell workflow
Pair Parse PDF with Ethos
Use Parse PDF to create structured, source-aware outputs. When Ethos anchoring is available, preserve the evidence-anchor companion artifact and source fingerprint alongside the JSON, Markdown, or text that feeds retrieval.
The safe sequence is: parse and preserve provenance, retrieve from authorized artifacts, generate structured claims, verify citations, apply application-owned release policy, then show, partially show, review, or block the answer.
Limits
Know 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 user's situation.
It also does not silently fill evidence gaps. Unsupported claim kinds and missing source capabilities should remain visible as explicit outcomes.
- 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.
Advanced review
Review misleading but grounded answers
A literal quote can be grounded while the surrounding answer is misleading. For that reason, advanced integrations should surface structural provenance, bounded source context, and how dispersed the reusable evidence is across a document.
These fields make review faster. They are not a semantic truth score: a reviewer or application policy still decides whether the evidence supports the claim in context.