feat: implement 5 Pydantic v2 data models with 37 TDD tests

- PatientProfile with 10 sub-models + has_minimum_prescreen_data()
- SearchAnchors with GeographyFilter, TrialFilters, relaxation_order
- TrialCandidate with TrialLocation, AgeRange, EligibilityText
- EligibilityLedger with CriterionAssessment, traffic_light, gap analysis
- SearchLog with SearchStep, RefinementAction, transparency_summary

All 37 tests pass. Ruff clean.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

trialpath/models/__init__.py

@@ -0,0 +1,72 @@
+"""TrialPath data models -- Pydantic v2 data contracts."""
+from trialpath.models.eligibility_ledger import (
+    CriterionAssessment,
+    CriterionDecision,
+    EligibilityLedger,
+    GapItem,
+    OverallAssessment,
+    TemporalCheck,
+    TrialEvidencePointer,
+)
+from trialpath.models.patient_profile import (
+    Biomarker,
+    Comorbidity,
+    Demographics,
+    Diagnosis,
+    EvidencePointer,
+    ImagingSummary,
+    LabResult,
+    PatientProfile,
+    PerformanceStatus,
+    SourceDocument,
+    Treatment,
+    UnknownField,
+)
+from trialpath.models.search_anchors import (
+    GeographyFilter,
+    SearchAnchors,
+    TrialFilters,
+)
+from trialpath.models.search_log import (
+    RefinementAction,
+    SearchLog,
+    SearchStep,
+)
+from trialpath.models.trial_candidate import (
+    AgeRange,
+    EligibilityText,
+    TrialCandidate,
+    TrialLocation,
+)
+
+__all__ = [
+    "AgeRange",
+    "Biomarker",
+    "Comorbidity",
+    "CriterionAssessment",
+    "CriterionDecision",
+    "Demographics",
+    "Diagnosis",
+    "EligibilityLedger",
+    "EligibilityText",
+    "EvidencePointer",
+    "GapItem",
+    "GeographyFilter",
+    "ImagingSummary",
+    "LabResult",
+    "OverallAssessment",
+    "PatientProfile",
+    "PerformanceStatus",
+    "RefinementAction",
+    "SearchAnchors",
+    "SearchLog",
+    "SearchStep",
+    "SourceDocument",
+    "TemporalCheck",
+    "Treatment",
+    "TrialCandidate",
+    "TrialEvidencePointer",
+    "TrialFilters",
+    "TrialLocation",
+    "UnknownField",
+]

trialpath/models/eligibility_ledger.py

@@ -0,0 +1,89 @@
+"""EligibilityLedger v1 -- Per-trial criterion-level eligibility assessment."""
+from datetime import date
+from enum import Enum
+from typing import Optional
+
+from pydantic import BaseModel, Field
+
+from trialpath.models.patient_profile import EvidencePointer
+
+
+class CriterionDecision(str, Enum):
+    MET = "met"
+    NOT_MET = "not_met"
+    UNKNOWN = "unknown"
+
+
+class OverallAssessment(str, Enum):
+    LIKELY_ELIGIBLE = "likely_eligible"
+    LIKELY_INELIGIBLE = "likely_ineligible"
+    UNCERTAIN = "uncertain"
+
+
+class TrialEvidencePointer(BaseModel):
+    field: str = Field(description="e.g. 'eligibility_text.inclusion'")
+    offset_start: int
+    offset_end: int
+
+
+class TemporalCheck(BaseModel):
+    """Validates whether patient evidence falls within a required time window."""
+    required_window_days: Optional[int] = Field(
+        None, description="e.g. 14 for 'within 14 days'"
+    )
+    reference_date: Optional[date] = Field(
+        None, description="Date of the patient evidence"
+    )
+    evaluation_date: Optional[date] = Field(default_factory=date.today)
+    is_within_window: Optional[bool] = None
+
+    @property
+    def days_elapsed(self) -> Optional[int]:
+        if self.reference_date and self.evaluation_date:
+            return (self.evaluation_date - self.reference_date).days
+        return None
+
+
+class CriterionAssessment(BaseModel):
+    criterion_id: str = Field(description="e.g. 'inc_1', 'exc_3'")
+    type: str = Field(description="'inclusion' or 'exclusion'")
+    text: str = Field(description="Original criterion text from trial")
+    decision: CriterionDecision
+    patient_evidence: list[EvidencePointer] = Field(default_factory=list)
+    trial_evidence: list[TrialEvidencePointer] = Field(default_factory=list)
+    temporal_check: Optional[TemporalCheck] = None
+
+
+class GapItem(BaseModel):
+    description: str
+    recommended_action: str
+    clinical_importance: str = Field(description="high|medium|low")
+
+
+class EligibilityLedger(BaseModel):
+    patient_id: str
+    nct_id: str
+    overall_assessment: OverallAssessment
+    criteria: list[CriterionAssessment] = Field(default_factory=list)
+    gaps: list[GapItem] = Field(default_factory=list)
+
+    @property
+    def met_count(self) -> int:
+        return sum(1 for c in self.criteria if c.decision == CriterionDecision.MET)
+
+    @property
+    def not_met_count(self) -> int:
+        return sum(1 for c in self.criteria if c.decision == CriterionDecision.NOT_MET)
+
+    @property
+    def unknown_count(self) -> int:
+        return sum(1 for c in self.criteria if c.decision == CriterionDecision.UNKNOWN)
+
+    @property
+    def traffic_light(self) -> str:
+        """Return traffic light color for UI display."""
+        if self.overall_assessment == OverallAssessment.LIKELY_ELIGIBLE:
+            return "green"
+        elif self.overall_assessment == OverallAssessment.UNCERTAIN:
+            return "yellow"
+        return "red"

trialpath/models/patient_profile.py

@@ -0,0 +1,101 @@
+"""PatientProfile v1 -- MedGemma extraction output for NSCLC patients."""
+import datetime
+from typing import Optional
+
+from pydantic import BaseModel, Field
+
+
+class EvidencePointer(BaseModel):
+    doc_id: str = Field(description="Source document identifier")
+    page: Optional[int] = Field(default=None, description="Page number")
+    span_id: Optional[str] = Field(default=None, description="Text span identifier")
+
+
+class SourceDocument(BaseModel):
+    doc_id: str
+    type: str = Field(description="clinic_letter|pathology|lab|imaging")
+    meta: dict = Field(default_factory=dict)
+
+
+class Demographics(BaseModel):
+    age: Optional[int] = None
+    sex: Optional[str] = None
+
+
+class Diagnosis(BaseModel):
+    primary_condition: str = Field(description="e.g. 'Non-Small Cell Lung Cancer'")
+    histology: Optional[str] = Field(default=None, description="e.g. 'adenocarcinoma'")
+    stage: Optional[str] = Field(default=None, description="e.g. 'IVa'")
+    diagnosis_date: Optional[datetime.date] = None
+
+
+class PerformanceStatus(BaseModel):
+    scale: str = Field(description="'ECOG' or 'KPS'")
+    value: int
+    evidence: list[EvidencePointer] = Field(default_factory=list)
+
+
+class Biomarker(BaseModel):
+    name: str = Field(description="e.g. 'EGFR', 'ALK', 'PD-L1'")
+    result: str = Field(description="e.g. 'Exon 19 deletion', 'Positive 80%'")
+    date: Optional[datetime.date] = None
+    evidence: list[EvidencePointer] = Field(default_factory=list)
+
+
+class LabResult(BaseModel):
+    name: str = Field(description="e.g. 'ANC', 'Creatinine'")
+    value: float
+    unit: str
+    date: Optional[datetime.date] = None
+    evidence: list[EvidencePointer] = Field(default_factory=list)
+
+
+class Treatment(BaseModel):
+    drug_name: str
+    start_date: Optional[datetime.date] = None
+    end_date: Optional[datetime.date] = None
+    line: Optional[int] = Field(default=None, description="Line of therapy (1, 2, 3...)")
+    evidence: list[EvidencePointer] = Field(default_factory=list)
+
+
+class Comorbidity(BaseModel):
+    name: str
+    grade: Optional[str] = None
+    evidence: list[EvidencePointer] = Field(default_factory=list)
+
+
+class ImagingSummary(BaseModel):
+    modality: str = Field(description="e.g. 'MRI brain', 'CT chest'")
+    date: Optional[datetime.date] = None
+    finding: str
+    interpretation: Optional[str] = None
+    certainty: Optional[str] = Field(default=None, description="low|medium|high")
+    evidence: list[EvidencePointer] = Field(default_factory=list)
+
+
+class UnknownField(BaseModel):
+    field: str = Field(description="Name of missing field")
+    reason: str = Field(description="Why it is unknown")
+    importance: str = Field(description="high|medium|low")
+
+
+class PatientProfile(BaseModel):
+    patient_id: str
+    source_docs: list[SourceDocument] = Field(default_factory=list)
+    demographics: Demographics = Field(default_factory=Demographics)
+    diagnosis: Optional[Diagnosis] = None
+    performance_status: Optional[PerformanceStatus] = None
+    biomarkers: list[Biomarker] = Field(default_factory=list)
+    key_labs: list[LabResult] = Field(default_factory=list)
+    treatments: list[Treatment] = Field(default_factory=list)
+    comorbidities: list[Comorbidity] = Field(default_factory=list)
+    imaging_summary: list[ImagingSummary] = Field(default_factory=list)
+    unknowns: list[UnknownField] = Field(default_factory=list)
+
+    def has_minimum_prescreen_data(self) -> bool:
+        """Check if profile has enough data for prescreening."""
+        return (
+            self.diagnosis is not None
+            and self.diagnosis.stage is not None
+            and self.performance_status is not None
+        )

trialpath/models/search_anchors.py

@@ -0,0 +1,33 @@
+"""SearchAnchors v1 -- Gemini-generated query parameters for ClinicalTrials MCP search."""
+from __future__ import annotations
+
+from typing import Optional
+
+from pydantic import BaseModel, Field
+
+
+class GeographyFilter(BaseModel):
+    country: str = Field(description="ISO country code or full name")
+    max_distance_km: Optional[int] = None
+
+
+class TrialFilters(BaseModel):
+    recruitment_status: list[str] = Field(
+        default=["Recruiting", "Not yet recruiting"]
+    )
+    phase: list[str] = Field(default=["Phase 2", "Phase 3"])
+
+
+class SearchAnchors(BaseModel):
+    condition: str = Field(description="Primary condition for search")
+    subtype: Optional[str] = Field(default=None, description="Cancer subtype")
+    biomarkers: list[str] = Field(default_factory=list)
+    stage: Optional[str] = None
+    geography: Optional[GeographyFilter] = None
+    age: Optional[int] = None
+    performance_status_max: Optional[int] = None
+    trial_filters: TrialFilters = Field(default_factory=TrialFilters)
+    relaxation_order: list[str] = Field(
+        default=["phase", "distance", "biomarker_strictness"],
+        description="Order in which to relax criteria if too few results",
+    )

trialpath/models/search_log.py

@@ -0,0 +1,74 @@
+"""SearchLog v1 -- Iterative query refinement tracking."""
+from datetime import datetime, timezone
+from enum import Enum
+
+from pydantic import BaseModel, Field
+
+
+class RefinementAction(str, Enum):
+    INITIAL = "initial"
+    REFINE = "refine"
+    RELAX = "relax"
+    SHORTLIST = "shortlist"
+    ABORT = "abort"
+
+
+class SearchStep(BaseModel):
+    step_number: int
+    query_params: dict = Field(description="SearchAnchors snapshot used for this query")
+    result_count: int
+    action_taken: RefinementAction
+    action_reason: str = Field(description="Human-readable why this action was chosen")
+    timestamp: datetime = Field(default_factory=lambda: datetime.now(timezone.utc))
+    nct_ids_sample: list[str] = Field(
+        default_factory=list,
+        description="Sample of NCT IDs returned (up to 10 for transparency)",
+    )
+
+
+class SearchLog(BaseModel):
+    session_id: str
+    patient_id: str
+    steps: list[SearchStep] = Field(default_factory=list)
+    final_shortlist_nct_ids: list[str] = Field(default_factory=list)
+    total_refinement_rounds: int = 0
+    max_refinement_rounds: int = Field(
+        default=5, description="Safety cap to prevent infinite loops"
+    )
+
+    @property
+    def is_refinement_exhausted(self) -> bool:
+        return self.total_refinement_rounds >= self.max_refinement_rounds
+
+    def add_step(
+        self,
+        query_params: dict,
+        result_count: int,
+        action: RefinementAction,
+        reason: str,
+        nct_ids_sample: list[str] | None = None,
+    ) -> None:
+        step = SearchStep(
+            step_number=len(self.steps) + 1,
+            query_params=query_params,
+            result_count=result_count,
+            action_taken=action,
+            action_reason=reason,
+            nct_ids_sample=nct_ids_sample or [],
+        )
+        self.steps.append(step)
+        if action in (RefinementAction.REFINE, RefinementAction.RELAX):
+            self.total_refinement_rounds += 1
+
+    def to_transparency_summary(self) -> list[dict]:
+        """Generate human-readable search process for FE display."""
+        return [
+            {
+                "step": s.step_number,
+                "query": s.query_params,
+                "found": s.result_count,
+                "action": s.action_taken.value,
+                "reason": s.action_reason,
+            }
+            for s in self.steps
+        ]

trialpath/models/trial_candidate.py

@@ -0,0 +1,33 @@
+"""TrialCandidate v1 -- Normalized ClinicalTrials MCP search results."""
+from __future__ import annotations
+
+from typing import Optional
+
+from pydantic import BaseModel, Field
+
+
+class TrialLocation(BaseModel):
+    country: str
+    city: Optional[str] = None
+
+
+class AgeRange(BaseModel):
+    min: Optional[int] = None
+    max: Optional[int] = None
+
+
+class EligibilityText(BaseModel):
+    inclusion: str
+    exclusion: str
+
+
+class TrialCandidate(BaseModel):
+    nct_id: str = Field(description="NCT identifier e.g. 'NCT01234567'")
+    title: str
+    conditions: list[str] = Field(default_factory=list)
+    phase: Optional[str] = None
+    status: Optional[str] = None
+    locations: list[TrialLocation] = Field(default_factory=list)
+    age_range: Optional[AgeRange] = None
+    fingerprint_text: str = Field(description="Short text for Gemini reranking")
+    eligibility_text: Optional[EligibilityText] = None

trialpath/tests/test_models.py

@@ -0,0 +1,616 @@
+"""TDD tests for TrialPath data models (RED phase — write tests first)."""
+from __future__ import annotations
+
+from datetime import date
+
+
+class TestPatientProfile:
+    """PatientProfile v1 validation and helper tests."""
+
+    def test_minimal_valid_profile(self):
+        """A profile with only patient_id should be valid."""
+        from trialpath.models.patient_profile import PatientProfile
+
+        profile = PatientProfile(patient_id="P001")
+        assert profile.patient_id == "P001"
+        assert profile.unknowns == []
+
+    def test_complete_nsclc_profile(self):
+        """Full NSCLC patient profile should serialize/deserialize correctly."""
+        from trialpath.models.patient_profile import (
+            Biomarker,
+            Demographics,
+            Diagnosis,
+            EvidencePointer,
+            PatientProfile,
+            PerformanceStatus,
+            UnknownField,
+        )
+
+        profile = PatientProfile(
+            patient_id="P001",
+            demographics=Demographics(age=52, sex="female"),
+            diagnosis=Diagnosis(
+                primary_condition="Non-Small Cell Lung Cancer",
+                histology="adenocarcinoma",
+                stage="IVa",
+                diagnosis_date=date(2025, 11, 15),
+            ),
+            performance_status=PerformanceStatus(
+                scale="ECOG", value=1,
+                evidence=[EvidencePointer(doc_id="clinic_1", page=2, span_id="s_17")],
+            ),
+            biomarkers=[
+                Biomarker(
+                    name="EGFR", result="Exon 19 deletion",
+                    date=date(2026, 1, 10),
+                    evidence=[EvidencePointer(doc_id="path_egfr", page=1, span_id="s_3")],
+                ),
+            ],
+            unknowns=[
+                UnknownField(field="PD-L1", reason="Not found in documents", importance="medium"),
+            ],
+        )
+
+        data = profile.model_dump()
+        restored = PatientProfile.model_validate(data)
+        assert restored.patient_id == "P001"
+        assert restored.diagnosis.stage == "IVa"
+        assert len(restored.biomarkers) == 1
+        assert restored.biomarkers[0].name == "EGFR"
+
+    def test_has_minimum_prescreen_data_true(self):
+        """Profile with diagnosis + stage + ECOG satisfies prescreen requirements."""
+        from trialpath.models.patient_profile import (
+            Diagnosis,
+            PatientProfile,
+            PerformanceStatus,
+        )
+
+        profile = PatientProfile(
+            patient_id="P001",
+            diagnosis=Diagnosis(
+                primary_condition="NSCLC", stage="IV",
+            ),
+            performance_status=PerformanceStatus(scale="ECOG", value=1),
+        )
+        assert profile.has_minimum_prescreen_data() is True
+
+    def test_has_minimum_prescreen_data_false_no_stage(self):
+        """Profile without stage should fail prescreen check."""
+        from trialpath.models.patient_profile import (
+            Diagnosis,
+            PatientProfile,
+            PerformanceStatus,
+        )
+
+        profile = PatientProfile(
+            patient_id="P001",
+            diagnosis=Diagnosis(primary_condition="NSCLC"),
+            performance_status=PerformanceStatus(scale="ECOG", value=1),
+        )
+        assert profile.has_minimum_prescreen_data() is False
+
+    def test_has_minimum_prescreen_data_false_no_ecog(self):
+        """Profile without performance status should fail prescreen check."""
+        from trialpath.models.patient_profile import (
+            Diagnosis,
+            PatientProfile,
+        )
+
+        profile = PatientProfile(
+            patient_id="P001",
+            diagnosis=Diagnosis(primary_condition="NSCLC", stage="IV"),
+        )
+        assert profile.has_minimum_prescreen_data() is False
+
+    def test_json_roundtrip(self):
+        """Profile should survive JSON serialization roundtrip."""
+        from trialpath.models.patient_profile import (
+            Demographics,
+            Diagnosis,
+            PatientProfile,
+        )
+
+        profile = PatientProfile(
+            patient_id="P001",
+            demographics=Demographics(age=65, sex="male"),
+            diagnosis=Diagnosis(
+                primary_condition="NSCLC",
+                histology="squamous",
+                stage="IIIb",
+            ),
+        )
+        json_str = profile.model_dump_json()
+        restored = PatientProfile.model_validate_json(json_str)
+        assert restored == profile
+
+    def test_source_docs_default_empty(self):
+        """source_docs should default to empty list."""
+        from trialpath.models.patient_profile import PatientProfile
+
+        profile = PatientProfile(patient_id="P001")
+        assert profile.source_docs == []
+
+    def test_source_doc_creation(self):
+        """SourceDocument with all fields."""
+        from trialpath.models.patient_profile import PatientProfile, SourceDocument
+
+        profile = PatientProfile(
+            patient_id="P001",
+            source_docs=[
+                SourceDocument(doc_id="doc1", type="pathology", meta={"pages": 3}),
+            ],
+        )
+        assert len(profile.source_docs) == 1
+        assert profile.source_docs[0].type == "pathology"
+
+    def test_lab_result(self):
+        """LabResult with value, unit, date, and evidence."""
+        from trialpath.models.patient_profile import (
+            EvidencePointer,
+            LabResult,
+            PatientProfile,
+        )
+
+        profile = PatientProfile(
+            patient_id="P001",
+            key_labs=[
+                LabResult(
+                    name="ANC", value=1.8, unit="10^9/L",
+                    date=date(2026, 1, 28),
+                    evidence=[EvidencePointer(doc_id="labs_jan", page=1, span_id="tbl_anc")],
+                ),
+            ],
+        )
+        assert profile.key_labs[0].value == 1.8
+        assert profile.key_labs[0].unit == "10^9/L"
+
+    def test_treatment(self):
+        """Treatment with drug_name, dates, and line of therapy."""
+        from trialpath.models.patient_profile import PatientProfile, Treatment
+
+        profile = PatientProfile(
+            patient_id="P001",
+            treatments=[
+                Treatment(
+                    drug_name="Pembrolizumab",
+                    start_date=date(2024, 6, 1),
+                    end_date=date(2024, 11, 30),
+                    line=1,
+                ),
+            ],
+        )
+        assert profile.treatments[0].drug_name == "Pembrolizumab"
+        assert profile.treatments[0].line == 1
+
+    def test_comorbidity(self):
+        """Comorbidity with name and grade."""
+        from trialpath.models.patient_profile import Comorbidity, PatientProfile
+
+        profile = PatientProfile(
+            patient_id="P001",
+            comorbidities=[
+                Comorbidity(name="CKD", grade="Stage 3"),
+            ],
+        )
+        assert profile.comorbidities[0].name == "CKD"
+
+    def test_imaging_summary(self):
+        """ImagingSummary with modality, finding, interpretation, certainty."""
+        from trialpath.models.patient_profile import ImagingSummary, PatientProfile
+
+        profile = PatientProfile(
+            patient_id="P001",
+            imaging_summary=[
+                ImagingSummary(
+                    modality="MRI brain",
+                    date=date(2026, 1, 20),
+                    finding="Stable 3mm left frontal lesion",
+                    interpretation="likely inactive scar",
+                    certainty="low",
+                ),
+            ],
+        )
+        assert profile.imaging_summary[0].modality == "MRI brain"
+        assert profile.imaging_summary[0].certainty == "low"
+
+
+class TestSearchAnchors:
+    """SearchAnchors v1 validation tests."""
+
+    def test_minimal_anchors(self):
+        from trialpath.models.search_anchors import SearchAnchors
+
+        anchors = SearchAnchors(condition="NSCLC")
+        assert anchors.condition == "NSCLC"
+        assert anchors.trial_filters.recruitment_status == ["Recruiting", "Not yet recruiting"]
+
+    def test_full_anchors(self):
+        from trialpath.models.search_anchors import SearchAnchors, TrialFilters
+
+        anchors = SearchAnchors(
+            condition="Non-Small Cell Lung Cancer",
+            subtype="adenocarcinoma",
+            biomarkers=["EGFR exon 19 deletion"],
+            stage="IV",
+            age=52,
+            performance_status_max=1,
+            trial_filters=TrialFilters(
+                recruitment_status=["Recruiting"],
+                phase=["Phase 3"],
+            ),
+            relaxation_order=["phase", "distance"],
+        )
+        assert len(anchors.biomarkers) == 1
+        assert anchors.trial_filters.phase == ["Phase 3"]
+
+    def test_default_relaxation_order(self):
+        from trialpath.models.search_anchors import SearchAnchors
+
+        anchors = SearchAnchors(condition="NSCLC")
+        assert anchors.relaxation_order == ["phase", "distance", "biomarker_strictness"]
+
+    def test_default_trial_filters(self):
+        from trialpath.models.search_anchors import SearchAnchors
+
+        anchors = SearchAnchors(condition="NSCLC")
+        assert anchors.trial_filters.phase == ["Phase 2", "Phase 3"]
+
+    def test_geography_filter(self):
+        from trialpath.models.search_anchors import GeographyFilter, SearchAnchors
+
+        anchors = SearchAnchors(
+            condition="NSCLC",
+            geography=GeographyFilter(country="DE", max_distance_km=200),
+        )
+        assert anchors.geography.country == "DE"
+        assert anchors.geography.max_distance_km == 200
+
+    def test_json_roundtrip(self):
+        from trialpath.models.search_anchors import SearchAnchors
+
+        anchors = SearchAnchors(
+            condition="NSCLC", stage="IV", age=55,
+        )
+        json_str = anchors.model_dump_json()
+        restored = SearchAnchors.model_validate_json(json_str)
+        assert restored == anchors
+
+
+class TestTrialCandidate:
+    """TrialCandidate v1 tests."""
+
+    def test_trial_with_eligibility_text(self):
+        from trialpath.models.trial_candidate import EligibilityText, TrialCandidate
+
+        trial = TrialCandidate(
+            nct_id="NCT01234567",
+            title="Phase 3 Study of Osimertinib",
+            conditions=["NSCLC"],
+            phase="Phase 3",
+            status="Recruiting",
+            fingerprint_text="Osimertinib EGFR+ NSCLC Phase 3",
+            eligibility_text=EligibilityText(
+                inclusion="Histologically confirmed NSCLC stage IV",
+                exclusion="Prior EGFR TKI therapy",
+            ),
+        )
+        assert trial.nct_id == "NCT01234567"
+        assert trial.eligibility_text.inclusion.startswith("Histologically")
+
+    def test_minimal_trial(self):
+        from trialpath.models.trial_candidate import TrialCandidate
+
+        trial = TrialCandidate(
+            nct_id="NCT99999999",
+            title="Test Trial",
+            fingerprint_text="test",
+        )
+        assert trial.conditions == []
+        assert trial.locations == []
+        assert trial.eligibility_text is None
+
+    def test_trial_with_locations(self):
+        from trialpath.models.trial_candidate import TrialCandidate, TrialLocation
+
+        trial = TrialCandidate(
+            nct_id="NCT01234567",
+            title="Test Trial",
+            fingerprint_text="test",
+            locations=[
+                TrialLocation(country="DE", city="Berlin"),
+                TrialLocation(country="DE", city="Hamburg"),
+            ],
+        )
+        assert len(trial.locations) == 2
+        assert trial.locations[0].city == "Berlin"
+
+    def test_trial_with_age_range(self):
+        from trialpath.models.trial_candidate import AgeRange, TrialCandidate
+
+        trial = TrialCandidate(
+            nct_id="NCT01234567",
+            title="Test Trial",
+            fingerprint_text="test",
+            age_range=AgeRange(min=18, max=75),
+        )
+        assert trial.age_range.min == 18
+        assert trial.age_range.max == 75
+
+    def test_json_roundtrip(self):
+        from trialpath.models.trial_candidate import TrialCandidate
+
+        trial = TrialCandidate(
+            nct_id="NCT01234567",
+            title="Test",
+            fingerprint_text="test fp",
+            phase="Phase 2",
+        )
+        json_str = trial.model_dump_json()
+        restored = TrialCandidate.model_validate_json(json_str)
+        assert restored == trial
+
+
+class TestEligibilityLedger:
+    """EligibilityLedger v1 tests."""
+
+    def test_traffic_light_green(self):
+        from trialpath.models.eligibility_ledger import (
+            EligibilityLedger,
+            OverallAssessment,
+        )
+
+        ledger = EligibilityLedger(
+            patient_id="P001",
+            nct_id="NCT01234567",
+            overall_assessment=OverallAssessment.LIKELY_ELIGIBLE,
+        )
+        assert ledger.traffic_light == "green"
+
+    def test_traffic_light_yellow(self):
+        from trialpath.models.eligibility_ledger import (
+            EligibilityLedger,
+            OverallAssessment,
+        )
+
+        ledger = EligibilityLedger(
+            patient_id="P001",
+            nct_id="NCT01234567",
+            overall_assessment=OverallAssessment.UNCERTAIN,
+        )
+        assert ledger.traffic_light == "yellow"
+
+    def test_traffic_light_red(self):
+        from trialpath.models.eligibility_ledger import (
+            EligibilityLedger,
+            OverallAssessment,
+        )
+
+        ledger = EligibilityLedger(
+            patient_id="P001",
+            nct_id="NCT01234567",
+            overall_assessment=OverallAssessment.LIKELY_INELIGIBLE,
+        )
+        assert ledger.traffic_light == "red"
+
+    def test_criterion_counts(self):
+        from trialpath.models.eligibility_ledger import (
+            CriterionAssessment,
+            CriterionDecision,
+            EligibilityLedger,
+            GapItem,
+            OverallAssessment,
+        )
+
+        ledger = EligibilityLedger(
+            patient_id="P001",
+            nct_id="NCT01234567",
+            overall_assessment=OverallAssessment.UNCERTAIN,
+            criteria=[
+                CriterionAssessment(
+                    criterion_id="inc_1", type="inclusion",
+                    text="Stage IV NSCLC", decision=CriterionDecision.MET,
+                ),
+                CriterionAssessment(
+                    criterion_id="inc_2", type="inclusion",
+                    text="ECOG 0-1", decision=CriterionDecision.MET,
+                ),
+                CriterionAssessment(
+                    criterion_id="exc_1", type="exclusion",
+                    text="No prior immunotherapy", decision=CriterionDecision.NOT_MET,
+                ),
+                CriterionAssessment(
+                    criterion_id="inc_3", type="inclusion",
+                    text="EGFR mutation", decision=CriterionDecision.UNKNOWN,
+                ),
+            ],
+            gaps=[
+                GapItem(
+                    description="EGFR mutation status unknown",
+                    recommended_action="Order EGFR mutation test",
+                    clinical_importance="high",
+                ),
+            ],
+        )
+        assert ledger.met_count == 2
+        assert ledger.not_met_count == 1
+        assert ledger.unknown_count == 1
+        assert len(ledger.gaps) == 1
+
+    def test_empty_criteria_counts(self):
+        from trialpath.models.eligibility_ledger import (
+            EligibilityLedger,
+            OverallAssessment,
+        )
+
+        ledger = EligibilityLedger(
+            patient_id="P001",
+            nct_id="NCT01234567",
+            overall_assessment=OverallAssessment.UNCERTAIN,
+        )
+        assert ledger.met_count == 0
+        assert ledger.not_met_count == 0
+        assert ledger.unknown_count == 0
+
+    def test_json_roundtrip(self):
+        from trialpath.models.eligibility_ledger import (
+            EligibilityLedger,
+            OverallAssessment,
+        )
+
+        ledger = EligibilityLedger(
+            patient_id="P001",
+            nct_id="NCT01234567",
+            overall_assessment=OverallAssessment.LIKELY_ELIGIBLE,
+        )
+        json_str = ledger.model_dump_json()
+        restored = EligibilityLedger.model_validate_json(json_str)
+        assert restored.patient_id == "P001"
+        assert restored.overall_assessment == OverallAssessment.LIKELY_ELIGIBLE
+
+
+class TestTemporalCheck:
+    """TemporalCheck validation for time-windowed criteria."""
+
+    def test_within_window(self):
+        """Evidence 7 days old should be within a 14-day window."""
+        from trialpath.models.eligibility_ledger import TemporalCheck
+
+        check = TemporalCheck(
+            required_window_days=14,
+            reference_date=date(2026, 1, 20),
+            evaluation_date=date(2026, 1, 27),
+            is_within_window=True,
+        )
+        assert check.days_elapsed == 7
+        assert check.is_within_window is True
+
+    def test_outside_window(self):
+        """Evidence 21 days old should be outside a 14-day window."""
+        from trialpath.models.eligibility_ledger import TemporalCheck
+
+        check = TemporalCheck(
+            required_window_days=14,
+            reference_date=date(2026, 1, 1),
+            evaluation_date=date(2026, 1, 22),
+            is_within_window=False,
+        )
+        assert check.days_elapsed == 21
+        assert check.is_within_window is False
+
+    def test_no_reference_date(self):
+        """Missing reference date should yield None for days_elapsed."""
+        from trialpath.models.eligibility_ledger import TemporalCheck
+
+        check = TemporalCheck(
+            required_window_days=14,
+            reference_date=None,
+        )
+        assert check.days_elapsed is None
+        assert check.is_within_window is None
+
+    def test_criterion_with_temporal_check(self):
+        """CriterionAssessment should accept an optional temporal_check."""
+        from trialpath.models.eligibility_ledger import (
+            CriterionAssessment,
+            CriterionDecision,
+            TemporalCheck,
+        )
+
+        assessment = CriterionAssessment(
+            criterion_id="inc_5",
+            type="inclusion",
+            text="ANC >= 1.5 x 10^9/L within 14 days of enrollment",
+            decision=CriterionDecision.MET,
+            temporal_check=TemporalCheck(
+                required_window_days=14,
+                reference_date=date(2026, 1, 20),
+                evaluation_date=date(2026, 1, 27),
+                is_within_window=True,
+            ),
+        )
+        assert assessment.temporal_check is not None
+        assert assessment.temporal_check.days_elapsed == 7
+        assert assessment.temporal_check.is_within_window is True
+
+
+class TestSearchLog:
+    """SearchLog v1 -- iterative query refinement tracking tests."""
+
+    def test_add_step_increments_count(self):
+        """Adding a refinement step should increment total_refinement_rounds."""
+        from trialpath.models.search_log import RefinementAction, SearchLog
+
+        log = SearchLog(session_id="S001", patient_id="P001")
+        assert log.total_refinement_rounds == 0
+
+        log.add_step(
+            query_params={"condition": "NSCLC"},
+            result_count=75,
+            action=RefinementAction.REFINE,
+            reason="Too many results, adding phase filter",
+        )
+        assert log.total_refinement_rounds == 1
+        assert len(log.steps) == 1
+
+    def test_refinement_exhausted_at_max(self):
+        """After 5 refinement rounds, is_refinement_exhausted should be True."""
+        from trialpath.models.search_log import RefinementAction, SearchLog
+
+        log = SearchLog(session_id="S001", patient_id="P001")
+
+        for i in range(5):
+            log.add_step(
+                query_params={"condition": "NSCLC", "round": i},
+                result_count=0,
+                action=RefinementAction.RELAX,
+                reason=f"Relaxation round {i + 1}",
+            )
+
+        assert log.total_refinement_rounds == 5
+        assert log.is_refinement_exhausted is True
+
+    def test_transparency_summary_format(self):
+        """to_transparency_summary should return list of dicts with expected keys."""
+        from trialpath.models.search_log import RefinementAction, SearchLog
+
+        log = SearchLog(session_id="S001", patient_id="P001")
+
+        log.add_step(
+            query_params={"condition": "NSCLC"},
+            result_count=100,
+            action=RefinementAction.REFINE,
+            reason="Too many results",
+        )
+        log.add_step(
+            query_params={"condition": "NSCLC", "phase": "Phase 3"},
+            result_count=25,
+            action=RefinementAction.SHORTLIST,
+            reason="Right-sized result set",
+        )
+
+        summary = log.to_transparency_summary()
+        assert len(summary) == 2
+        assert summary[0]["step"] == 1
+        assert summary[0]["found"] == 100
+        assert summary[0]["action"] == "refine"
+        assert summary[1]["step"] == 2
+        assert summary[1]["found"] == 25
+        assert summary[1]["action"] == "shortlist"
+
+    def test_initial_search_no_refinement_count(self):
+        """An INITIAL action should not increment the refinement counter."""
+        from trialpath.models.search_log import RefinementAction, SearchLog
+
+        log = SearchLog(session_id="S001", patient_id="P001")
+
+        log.add_step(
+            query_params={"condition": "NSCLC"},
+            result_count=30,
+            action=RefinementAction.INITIAL,
+            reason="First search",
+        )
+
+        assert log.total_refinement_rounds == 0
+        assert len(log.steps) == 1