backend/api/models.py

"""
models.py — Pydantic request / response models for the RareDx diagnosis API.
"""

from pydantic import BaseModel, Field
from typing import Optional


class DiagnoseRequest(BaseModel):
    note: str = Field(
        ...,
        min_length=10,
        description="Plain-text clinical note describing the patient's presentation.",
        examples=["18 year old male, extremely tall, displaced lens, heart murmur, scoliosis"],
    )
    top_n: int = Field(default=10, ge=1, le=50, description="Max candidates to return.")
    threshold: float = Field(
        default=0.55, ge=0.3, le=0.95,
        description="Minimum BioLORD cosine similarity to accept an HPO match.",
    )


class HPOMatch(BaseModel):
    phrase:  str
    hpo_id:  str
    term:    str
    score:   float


class Candidate(BaseModel):
    rank:               int
    orpha_code:         str
    name:               str
    definition:         Optional[str]
    rrf_score:          float
    graph_rank:         Optional[int]
    chroma_rank:        Optional[int]
    graph_matches:      Optional[int]    # number of HPO terms matched in graph
    chroma_sim:         Optional[float]  # cosine similarity from ChromaDB
    matched_hpo:        list[dict] = []  # HPO terms matched via graph
    hallucination_flag: bool = False
    flag_reason:        Optional[str] = None
    evidence_score:     float = 0.0


class DiagnoseResponse(BaseModel):
    note:               str
    phrases_extracted:  list[str]
    hpo_matches:        list[HPOMatch]
    hpo_ids_used:       list[str]
    candidates:         list[Candidate]  # all candidates (flag fields attached)
    passed_candidates:  list[Candidate]  # guard passed
    flagged_candidates: list[Candidate]  # guard flagged
    top_diagnosis:      Optional[Candidate]
    graph_backend:      str
    chroma_backend:     str
    elapsed_seconds:    float