Data contracts
Five project-agnostic Pydantic models (status, citation, extraction, comparison, finding) that every check produces, and how each product maps them to its own output.
The platform’s contracts are deliberately few. Five models, in one file, imported by everything. They encode the four-step shape and nothing else: no comparison logic, no domain vocabulary.
class CheckStatus(str, Enum): # assigned by deterministic code, never by a model
PASS = "pass" # present, and consistent with the source of truth
FAIL = "fail" # present, but inconsistent
REVIEW = "review" # missing / low confidence / no citation → a human
NA = "na" # not applicable to this subject
class Citation(BaseModel): # where a conclusion came from
source_doc_id | page | bbox[x0, y0, x1, y1] | text_span | db_reference
class ExtractionField(BaseModel): # one extracted data point, with its evidence
field, raw, normalized, citation, ocr_confidence, extraction_confidence, review_required
class FieldComparison(BaseModel): # one document value vs one source-of-truth value
field, doc_value, source_value, source_system, rule, result: CheckStatus, citation
class VerificationFinding(BaseModel):# the output of any completed check
check_id, subject_id, status: CheckStatus,
comparisons: list[FieldComparison], extractions: list[ExtractionField],
missing_evidence: list[str], reasons: list[str], citations: list[Citation]What each one is for
CheckStatus has four values, and the fourth matters. Not applicable is distinct from pass: a check that doesn’t apply to this product or jurisdiction must not count as passed, or the roll-up silently inflates.
Citation is either a location in a document or a reference into a database: the same type for both, so a finding can cite “the balance on page 3 of this statement” and “the balance field on this account” in one list. The rule across both products is that a conclusion without a citation is rendered as an unverified suggestion, styled differently, never as a result.
ExtractionField carries two confidences because they fail differently. OCR confidence says how legible the source was; extraction confidence says how sure the model was about the value given what it read. Either can trip the review flag, and the fallback trigger for the OCR tier uses the first.
FieldComparison is the generalisation of what the first product needed (“does this document value match the system of record”) with the source system as a field rather than an assumption, so the same object works whether the source is the warehouse, a document management index, or another document.
VerificationFinding is the lingua franca. Its status roll-up is fixed: any fail → fail, any review or any missing evidence → review, else pass. It carries the comparisons and the extractions they were built on, so a reviewer can walk from a verdict back through the comparison to the value to the page without leaving the object.
How projects map them
Neither product consumes a finding raw.
The disputes system folds findings from its documentation, verification and flags checks into a case pack: one status chip per component, one evidence appendix, and a native classification result from stage one that predates the platform and was kept as-is.
The records system maps CheckStatus onto its own three-valued verdict, specialises FieldComparison into a comparison against its particular system of record, and stores ExtractionField lists directly on its account verdict. The proof the pattern generalises is that the second mapping cost a few dozen lines.
What’s not here
No thresholds. No tolerances. No required-document sets. No field names. Anything a business owner might need to change lives in versioned config, validated against a separate registry schema, and is read by the components rather than baked into the contracts. The contracts describe the shape of evidence; the config describes the rules.