Models

Claim

class Claim(BaseModel):
    id: str                    # Unique identifier
    text: str                  # The claim text
    source_document: str       # Source path/URL
    source_span: tuple[int, int] | None  # Character positions
    context: str | None        # Surrounding text
    claim_type: str            # "explicit", "implicit", "inferred"

Evidence

class Evidence(BaseModel):
    source: str                # URL or file path
    source_type: str           # "web", "filesystem", "knowledge_base"
    content: str               # Relevant excerpt
    relevance_score: float     # 0.0 to 1.0
    supports_claim: bool | None  # True/False/None
    credibility_score: float   # 0.0 to 1.0

VerificationResult

class VerificationResult(BaseModel):
    claim_id: str              # Reference to claim
    verdict: str               # "SUPPORTS", "REFUTES", "NOT_ENOUGH_INFO"
    confidence: float          # 0.0 to 1.0
    evidence: list[Evidence]   # Evidence considered
    explanation: str           # Detailed reasoning
    model_votes: dict[str, str]  # {model: verdict}

    @property
    def is_verified(self) -> bool:
        """True if SUPPORTS/REFUTES with confidence >= 0.7"""

TruthfulnessReport

class TruthfulnessReport(BaseModel):
    source_document: str
    overall_grade: str | None  # "A+", "A", "B+", etc.
    overall_confidence: float
    summary: str
    claims: list[Claim]
    verifications: list[VerificationResult]
    unvalidated_claims: list[Claim]
    statistics: TruthfulnessStatistics

    def calculate_grade(self) -> str:
        """Compute letter grade from results"""

TruthfulnessStatistics

class TruthfulnessStatistics(BaseModel):
    total_claims: int
    supported: int
    refuted: int
    not_enough_info: int
    unverifiable: int

    @property
    def verification_rate(self) -> float:
        """Fraction of claims verified"""

    @property
    def accuracy_score(self) -> float:
        """supported / (supported + refuted)"""

Usage

from truthfulness_evaluator.models import Claim, Evidence, VerificationResult

# Create claim
claim = Claim(
    id="claim_001",
    text="Python was created in 1991",
    source_document="README.md"
)

# Create evidence
evidence = Evidence(
    source="python.org",
    source_type="web",
    content="Python was created by Guido van Rossum...",
    relevance_score=0.95,
    supports_claim=True
)

# Create result
result = VerificationResult(
    claim_id=claim.id,
    verdict="SUPPORTS",
    confidence=0.9,
    evidence=[evidence],
    explanation="Multiple sources confirm...",
    model_votes={"gpt-4o": "SUPPORTS"}
)

Serialization

All models support JSON:

# To JSON
json_str = report.model_dump_json(indent=2)

# From JSON
report = TruthfulnessReport.model_validate_json(json_str)

API Reference

Claim

truthfulness_evaluator.models.Claim

Bases: BaseModel

A factual claim extracted from text.

Source code in src/truthfulness_evaluator/models/claim.py

class Claim(BaseModel):
    """A factual claim extracted from text."""

    id: str = Field(description="Unique claim identifier")
    text: str = Field(description="The claim text")
    source_document: str = Field(description="Source document path/URL")
    source_span: Optional[tuple[int, int]] = Field(
        default=None, description="Character span in source (start, end)"
    )
    context: Optional[str] = Field(default=None, description="Surrounding context for the claim")
    claim_type: Literal["explicit", "implicit", "inferred"] = Field(
        default="explicit", description="Type of claim"
    )

    def __str__(self) -> str:
        return f"Claim({self.id}): {self.text[:80]}..."

Evidence

truthfulness_evaluator.models.Evidence

Bases: BaseModel

Evidence found for or against a claim.

Source code in src/truthfulness_evaluator/models/evidence.py

class Evidence(BaseModel):
    """Evidence found for or against a claim."""

    source: str = Field(description="Evidence source (URL, file path)")
    source_type: Literal["web", "filesystem", "knowledge_base"] = Field(
        description="Type of evidence source"
    )
    content: str = Field(description="Relevant content snippet")
    relevance_score: float = Field(ge=0.0, le=1.0, description="Relevance score (0-1)")
    supports_claim: Optional[bool] = Field(
        default=None,
        description="Whether this supports (True), refutes (False), or is neutral (None)",
    )
    credibility_score: float = Field(
        default=0.5, ge=0.0, le=1.0, description="Source credibility score (0-1)"
    )

VerificationResult

truthfulness_evaluator.models.VerificationResult

Bases: BaseModel

Result of verifying a single claim (pure data container).

Source code in src/truthfulness_evaluator/models/verification.py

class VerificationResult(BaseModel):
    """Result of verifying a single claim (pure data container)."""

    claim_id: str = Field(description="ID of the claim being verified")
    verdict: Verdict = Field(description="Verification verdict")
    confidence: float = Field(ge=0.0, le=1.0, description="Confidence in the verdict (0-1)")
    evidence: list[Evidence] = Field(
        default_factory=list, description="Evidence supporting the verdict"
    )
    explanation: str = Field(description="Human-readable explanation of the verdict")
    model_votes: dict[str, Verdict] = Field(
        default_factory=dict, description="Individual model votes (model_name -> verdict)"
    )

TruthfulnessReport

truthfulness_evaluator.models.TruthfulnessReport

Bases: BaseModel

Final evaluation report (pure data container).

Use build_report() from core.grading to construct reports with computed fields.

Source code in src/truthfulness_evaluator/models/report.py

class TruthfulnessReport(BaseModel):
    """Final evaluation report (pure data container).

    Use build_report() from core.grading to construct reports with computed fields.
    """

    source_document: str = Field(description="Path/URL of source document")
    overall_grade: Optional[str] = Field(
        default=None, pattern=r"^[A-F][+-]?$", description="Letter grade (A+ to F)"
    )
    overall_confidence: float = Field(
        default=0.0, ge=0.0, le=1.0, description="Overall confidence in the evaluation"
    )
    summary: str = Field(default="", description="Executive summary of findings")
    claims: list[Claim] = Field(default_factory=list)
    verifications: list[VerificationResult] = Field(default_factory=list)
    unvalidated_claims: list[Claim] = Field(
        default_factory=list, description="Claims that could not be validated"
    )
    statistics: TruthfulnessStatistics = Field(default_factory=TruthfulnessStatistics)

TruthfulnessStatistics

truthfulness_evaluator.models.TruthfulnessStatistics

Bases: BaseModel

Statistics for a truthfulness evaluation (pure data container).

Use calculate_statistics() from core.grading to compute these values.

Source code in src/truthfulness_evaluator/models/report.py

class TruthfulnessStatistics(BaseModel):
    """Statistics for a truthfulness evaluation (pure data container).

    Use calculate_statistics() from core.grading to compute these values.
    """

    total_claims: int = Field(default=0)
    supported: int = Field(default=0)
    refuted: int = Field(default=0)
    not_enough_info: int = Field(default=0)
    unverifiable: int = Field(default=0)
    verification_rate: float = Field(default=0.0)
    accuracy_score: float = Field(default=0.0)