"""Shared building blocks for analysis-task response schemas. Every finding
that claims something happened carries an explicit confidence label from
this set - never presented as bare fact (spec section 16 / "Evidence and
Anti-Hallucination Requirements")."""

from __future__ import annotations

from enum import StrEnum

from pydantic import BaseModel, Field


class ConfidenceLabel(StrEnum):
    CONFIRMED = "confirmed"
    STRONGLY_INDICATED = "strongly_indicated"
    LIKELY = "likely"
    POSSIBLE = "possible"
    UNCONFIRMED = "unconfirmed"
    INSUFFICIENT_EVIDENCE = "insufficient_evidence"


class EvidenceRef(BaseModel):
    source_document_id: str | None = None
    detected_change_id: str | None = None
    url: str | None = None
    description: str = Field(description="What this piece of evidence shows, in one sentence")


class Finding(BaseModel):
    headline: str
    summary: str
    evidence: list[EvidenceRef] = Field(default_factory=list)
    confidence: ConfidenceLabel = ConfidenceLabel.UNCONFIRMED
    category: str | None = None
    date: str | None = None