citeformer.verify.report

VerificationReport pydantic schema — §10.3 contract.

The schema_version is bumped any time the model’s shape changes. Current version: 3 — added citations_checked so downstream tooling can tell “no citations” apart from “all citations supported” without probing per_citation. The old support_rate = 1.0 when per_citation is empty convention is preserved for continuity; consumers that want the honest “there’s nothing to rate” signal read citations_checked now.

§10.3 ceremony: every change goes through the release-bump rubric, the snapshot tests in tests/integration/test_schemas.py, and a CHANGELOG Contracts (§10) note. See docs/reference/contracts.md.

Module Contents

Classes

CitationSupport	Entailment detail for a single citation.
UncitedClaim	An uncited sentence that NLI flags as likely needing a citation.
VerificationReport	Output of GenerationResult.verify().

API

class citeformer.verify.report.CitationSupport(/, **data: Any)

Bases: pydantic.BaseModel

Entailment detail for a single citation.

Attributes: citation_index: Position in GenerationResult.citations this entry describes. entailment_score: NLI entailment probability in [0, 1]. Computed by the configured NLI model (DeBERTa-v3-large-MNLI by default). supported: True iff entailment_score >= threshold AND the citation’s source_id resolves to an in-range source. Threshold defaults to 0.5; configurable on the Verifier.

Initialization

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

model_config

‘ConfigDict(…)’

citation_index: int

‘Field(…)’

entailment_score: float

‘Field(…)’

supported: bool

‘Field(…)’

class citeformer.verify.report.UncitedClaim(/, **data: Any)

Bases: pydantic.BaseModel

An uncited sentence that NLI flags as likely needing a citation.

Attributes: span: (start, end) char offsets of the sentence in GenerationResult.text. candidate_source_id: 1-indexed source that most strongly entails the sentence — suggested citation target if the author wanted to fix the gap. entailment_score: Entailment probability of the best-matching source, in [0, 1].

Initialization

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

model_config

‘ConfigDict(…)’

span: tuple[int, int]

‘Field(…)’

candidate_source_id: int

‘Field(…)’

entailment_score: float

‘Field(…)’

class citeformer.verify.report.VerificationReport(/, **data: Any)

Bases: pydantic.BaseModel

Output of GenerationResult.verify().

§10.3 contract: shape is locked by tests/integration/test_schemas.py.

Attributes: schema_version: Contract version. Bump on any shape change. support_rate: Fraction of citations with supported == True, in [0, 1]. Kept at 1.0 when per_citation is empty for backward compat, but consumers reporting aggregate numbers should gate on citations_checked > 0 to avoid publishing “100% supported” for runs that emitted no citations at all. citations_checked: Count of citations the verifier actually scored (equals len(per_citation)). 0 is the honest signal that the run produced no citations for NLI to check — not that everything was supported. per_citation: One CitationSupport entry per citation in the GenerationResult, in the same order. uncited_but_entailed: Sentences where the NLI coverage check flagged a missing citation — an uncited claim that one of the available sources would entail. Each entry carries the span, the best- matching source, and the entailment score.

Initialization

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

model_config

‘ConfigDict(…)’

schema_version: int

‘Field(…)’

support_rate: float

‘Field(…)’

citations_checked: int

‘Field(…)’

per_citation: list[citeformer.verify.report.CitationSupport]

‘Field(…)’

uncited_but_entailed: list[citeformer.verify.report.UncitedClaim]

‘Field(…)’