src/core/evidence_models.py

"""
Evidence and citation models for clinical recommendations.
Bug 12.3: Explainability Layer for Clinical Recommendations
"""

from pydantic import BaseModel, Field
from typing import List, Literal, Optional


class Citation(BaseModel):
    """Represents a citation to a specific guideline or evidence source."""
    source_document: str = Field(
        description="Name of the guideline or research document (e.g., 'ADA Standards of Care 2026')"
    )
    page_number: Optional[int] = Field(None, description="Page number in the source document")
    section: Optional[str] = Field(None, description="Section or chapter title in the document")
    evidence_level: Literal["A", "B", "C"] = Field(
        description="Evidence level per ADA standards: A (Excellent), B (Good), C (Limited)"
    )
    url: Optional[str] = Field(None, description="Optional URL to the source document")


class ClinicalOutputWithEvidence(BaseModel):
    """
    Clinical specialist output with explicit evidence citations.
    This ensures transparency and allows clinician users to verify the basis of recommendations.
    """
    recommendation: str = Field(
        description="The clinical recommendation or advice provided"
    )
    explanation: str = Field(
        description="Detailed explanation of the recommendation and its rationale"
    )
    citations: List[Citation] = Field(
        description="List of guideline and evidence sources supporting this recommendation"
    )
    confidence_score: float = Field(
        ge=0.0, le=1.0,
        description="Agent's confidence score in this recommendation (0.0 to 1.0)"
    )
    disclaimer: Optional[str] = Field(
        None,
        description="Any clinical disclaimers or caveats (e.g., 'Consult with physician', 'Not for acute conditions')"
    )


class EvidenceCitation(BaseModel):
    """
    Record of an evidence citation used in the clinical pipeline.
    Used to track citations within AgentState.
    """
    recommendation_id: str = Field(description="ID of the clinical recommendation this cites")
    source_document: str = Field(description="Name of the source document")
    page_number: Optional[int] = Field(None, description="Page number in source")
    evidence_level: Literal["A", "B", "C"] = Field(description="Evidence level classification")
    agent_name: str = Field(description="Name of the agent that produced this citation")
    timestamp: str = Field(description="ISO format timestamp when citation was generated")