Bring evidence, not just text
Ethos can use its own born-digital PDF output or a supported parser adapter. The grounding source supplies the text, pages, regions, fingerprints and capabilities behind a citation check.
Open source · Apache-2.0 · public beta v0.3.0AI citations, checked
AI citations, checked
against the source. Deterministically.
Ethos checks whether supported citation claims are grounded in the document source you supply. It returns explicit proof states, document locations, and reviewable evidence without asking another model to decide. Ethos verifies grounding, not whether an answer is relevant, complete, or correct.
- 0
- LLM calls for verification
- local
- Offline base execution
- clear
- Proof states, not scores
ethos verify · demo
Deterministic verification•Source fingerprints•Crop-level evidence•Fails closed on drift•Bring-your-own parser•Apache-2.0
The next step after parsing
A citation is useful only when you can inspect the evidence behind it.
Document retrieval and answer generation can produce a helpful answer, but neither proves that a cited claim is supported by the current document source. Ethos verifies the grounding layer. Your application still owns retrieval quality, answer relevance, synthesis and the decision to release an answer.
Check the claims you release
Ethos checks supported citation claims, such as quotes, values, table cells and page regions, against the supplied document source. It returns a clear outcome and can provide a crop reference for review.
Detect stale & missing evidence
Source fingerprints flag when a citation no longer matches the document it claims to quote. Missing, mismatched and capability-limited checks remain explicit instead of being silently passed.
Verification flow
From answer citation to an inspectable proof state.
Citations and a grounding source go in. A canonical verification report comes out, with source locations and optional crop artifacts when the available evidence supports them.
- 1
Collect claims
AI answer citations - quotes, values, page/region references - are gathered as structured claims.
- 2
Provide document evidence
Supply native Ethos JSON, or adapt a supported parser through the GroundingSource boundary. It describes the text, pages, regions, fingerprints and available evidence.
- 3
Run ethos verify
Each supported claim is checked against the document evidence. Grounded, stale, not-found and capability-limited are explicit outcomes, not confidence scores.
- 4
Return the report
A canonical verification_report.json plus optional crop descriptor and rendered crop artifact - the audit record.
proof_status
verified
Every requested check is grounded. The answer is certified by all_evidence_grounded.
partially_verified
Some checks are grounded, but the full request is not certified. Do not treat this as a release-ready answer.
unverified
No requested check is grounded. Retrieved document text and model-returned evidence IDs are not proof until they pass verification.
Deterministic by design
Verification complements answer evaluation. It does not replace it.
Retrieval scores and model confidence can tell you a passage looks relevant. They do not establish that a cited claim is supported by the cited source. Ethos performs a deterministic check over the evidence you provide: is this supported claim present at the asserted source location?
That makes Ethos a useful control alongside, not instead of, LLM-based evaluation. Use a judge or human review for relevance and reasoning quality; use Ethos when you need a repeatable answer to whether a citation binds to its source.
Ethos evidence check
LLM or human review
How it reaches a verdict
Rules over supplied document evidence
Model interpretation
Additional model call
None for verification
Typically required
Evidence returned
Explicit document page, region and proof state when available
Depends on the implementation
Source-version drift
Can flag a stale fingerprint
Requires separate controls
Best used for
Citation grounding and release gates
Semantic quality or relevance review
Honest scope
Clear about what it verifies, and what remains your responsibility.
Ethos makes its evidence boundary explicit. A grounded citation is valuable proof of source support, but it is not a guarantee that an answer is complete, relevant, or correct.
Supported today
- Citation verification over native Ethos JSON
- Born-digital PDF parsing with caller-provided PDFium
- Third-party parser grounding via a stable adapter boundary
- Verification reports, proof states and crop descriptors when source evidence supports them
- Stale-fingerprint, unsupported and capability-limited handling
- Rust crates, a Python wheel, an npm package, and macOS arm64 / Linux x64 CLI artifacts
Not yet / out of scope
- Scanned / image-only PDFs - fails with a stable ocr_required
- Answer correctness, completeness, relevance or safe final-answer release. It checks source grounding, not answer truth.
- Complex table semantics & formula/LaTeX (Release 2 enrichment)
- Windows packaged artifacts & bundled PDFium
- Hosted API or browser demo surfaces
- Claims of parser quality, speed or benchmark leadership
Repeatable evidence checks
With the same document source, citations and pinned verification profile, Ethos produces a repeatable evidence verdict. That makes review and CI decisions explainable instead of dependent on a second model's interpretation.
Designed for sensitive documents
The base build is designed for local, offline execution and does not need a network call to verify evidence. PDF parsing uses an explicit operator-provided PDFium path, so deployment controls remain with your team.
Bring your own parser
Verification is parser-agnostic at its boundary. Adapt a parser output with pages, elements, text, tables, regions, fingerprints and capabilities, then Ethos can check supported claims or explain which evidence is unavailable.
Two-minute start
Add a verification step where it matters.
Use Ethos as a Rust crate, Python wheel or npm CLI. JSON verification and evidence anchoring do not need PDFium. Only PDF parsing does, and PDFium is always caller-provided through ETHOS_PDFIUM_LIBRARY_PATH.
install
# Rust cargo add [email protected] # Python (thin wrapper over the CLI) python3 -m pip install ethos-pdf==0.3.0 # npm - vendored macOS arm64 / Linux x64 CLI npm install -g @docushell/[email protected] ethos --version # sanity check your setup ethos doctor --require-pdfium
Guides & deep dives
Learn how Ethos verifies document AI.
Fundamentals
What is Ethos? A deterministic evidence layer for document AI
Why grounding evidence - not model confidence - is the missing layer between a parsed PDF and a trustworthy answer.
How it works
How does Ethos verify AI citations against source documents?
A walk through the grounding loop: claims in, source-bound checks out, with page and region returned for inspection.
AI evaluation
Can Ethos verify RAG answers without calling another LLM?
Deterministic, source-bound citation checks - no judge-model call - and where semantic relevance still needs a separate step.
Developer guide
Can Ethos verify citations from other document parsers?
How foreign parsers plug into Ethos through GroundingSource adapters for deterministic evidence verification.
Reliability
How does Ethos detect wrong, missing, and stale AI citations?
Source fingerprints and fail-closed checks that surface drift instead of letting a bad citation slip through.
CI / release
How can developers use Ethos as a RAG release gate?
Wire --fail-on-ungrounded into CI so unverified citations block a release, not a customer.
Frequently asked questions
Ethos, answered.
Straight answers on what Ethos verifies, what it does not, and where it fits in a document-AI or RAG pipeline.
What is Ethos?
Ethos is DocuShell's open-source, deterministic evidence layer for document AI. It checks whether supported citation claims are grounded in a supplied source document and returns explicit proof states, source locations and reviewable evidence when available. Ethos is released under the Apache-2.0 license.
How does Ethos verify AI citations against a source document?
Ethos takes supported citation claims behind an AI answer and checks them against a grounding source: does the cited evidence exist, at the stated source location, and is the source fingerprint still fresh? It returns a canonical verification report with explicit outcomes and source locations, plus crop artifacts when the supplied evidence supports them.
Does Ethos need to call another LLM to verify RAG answers?
No. Ethos verification is deterministic and does not make a judge-model API call. Use it for citation grounding and release gates. Use a separate evaluator or human review for semantic relevance, completeness and answer quality.
Is Ethos free and open source?
Yes. Ethos is open source under the Apache-2.0 license. It ships as Rust crates, a Python wheel, and an npm package, with macOS arm64 and Linux x64 command-line binaries for evaluation.
Does Ethos work offline and keep private documents secure?
The base build is designed for local, offline execution and does not need a network API call to verify evidence. Your deployment configuration determines where documents are processed, so teams handling private or regulated content should operate it in their approved environment.
What is a source fingerprint and how does it catch stale citations?
A source fingerprint is a deterministic signature of the parsed document. When an AI citation is checked against a document whose fingerprint has changed, Ethos flags the citation as stale and fails closed, so answers cannot silently rely on an outdated version of a policy, contract, or report.
Can Ethos verify citations from third-party document parsers?
Ethos has a parser-neutral verification boundary. A supported adapter can map a parser's output into pages, text, tables, regions, fingerprints and capabilities. Ethos then checks supported claim types, or clearly reports when the source cannot supply enough evidence.
How do I use Ethos as a release gate for a RAG system?
Run Ethos verification with the fail-on-ungrounded flag in CI. It exits non-zero when requested checks are stale, missing, mismatched, unsupported or capability-blocked. Treat that as one release control alongside your own checks for retrieval, relevance, safety and answer quality.
Release document AI with evidence you can inspect.
Pair the DocuShell Parse API with Ethos to verify supported citations against the source before you release an answer. Keep retrieval, answer quality and release policy as separate controls.
Apache-2.0 Same input · same profile · same fingerprint