File size: 2,499 Bytes
b1198f0 | 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 | """
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")
|