perf: rank trials by phase, cap at 15, strip bloat, tighten defaults (#25)

Trial ranking (Phase 4 > Phase 3 > ... > EAP > Observational) replaces
pure distance sorting so the highest-value trials surface first.

Token reduction (~60-80% of tool-result payload):
- _rank_and_slim: cap at 15 trials before LLM, strip summary/conditions/
keywords/age fields/std_ages/eligibility, reduce nearest_sites 5→3,
drop intervention descriptions
- max_tokens: research 8096→3000, bulk-parse eligibility 8192→4096

Default search radius: 100 miles → 20 miles

Co-authored-by: Claude Sonnet 4.6 <noreply@anthropic.com>

agents/eligibility.py

@@ -37,6 +37,14 @@ For each criterion:
 - raw_criteria: the verbatim criterion text from the source
 - constraint: a structured comparison if the criterion can be expressed as one; null otherwise
 
+Canonical key names — always use these exact strings for the corresponding criteria:
+  Any "time since symptom/disease/weakness/condition onset", "disease duration", \
+  "duration of symptoms" → key: "symptom_onset_months"  (value in months)
+  Any "time since diagnosis", "diagnosed within" → key: "diagnosis_months"  (value in months)
+  Age → key: "age_years"  (value in years)
+When the trial states a threshold in years for a _months key, keep the value in months \
+(e.g. "onset within 2 years" → value: 24, unit: "months").
+
 Express constraints as the condition the patient must meet to qualify:
   "Age 18-75" → {operator: "between", value: [18, 75]}
   "No prior systemic therapy" → {operator: "==", value: 0}
@@ -93,22 +101,36 @@ _OPERATORS = {
     "between": lambda pv, v: v[0] <= pv <= v[1],
 }
 
+_MONTHS_KEYS = {"symptom_onset_months", "diagnosis_months"}
+
+
+def _normalize_to_patient_units(
+    key: str, value: object, unit: str | None
+) -> tuple[object, str | None]:
+    """Convert constraint value to the same unit as the patient field (always months for time keys)."""
+    if key in _MONTHS_KEYS and unit == "years":
+        if isinstance(value, list):
+            return [int(v * 12) for v in value], "months"
+        return int(value * 12), "months"
+    return value, unit
+
 
 def _evaluate_deterministic(
     criterion: EligibilityCriterion,
     patient_value: object,
 ) -> CriterionAssessment:
     c = criterion.constraint
+    norm_value, norm_unit = _normalize_to_patient_units(c.key, c.value, c.unit)
     fn = _OPERATORS.get(c.operator)
     try:
-        passes = fn(patient_value, c.value)
+        passes = fn(patient_value, norm_value)
     except (TypeError, ValueError):
         passes = False
 
     verdict = CriterionVerdict.PASS if passes else CriterionVerdict.FAIL
-    unit_str = f" {c.unit}" if c.unit else ""
+    unit_str = f" {norm_unit}" if norm_unit else ""
     reason = (
-        f"Requires {c.operator} {c.value}{unit_str}; patient value: {patient_value}"
+        f"Requires {c.operator} {norm_value}{unit_str}; patient value: {patient_value}"
     )
     return CriterionAssessment(
         criterion=criterion,
@@ -328,7 +350,7 @@ def bulk_parse_and_strip(
     try:
         response = client.messages.create(
             model=ELIGIBILITY_MODEL,
-            max_tokens=8192,
+            max_tokens=4096,
             system=_PARSE_SYSTEM,
             tools=[PARSE_CRITERIA_BULK_TOOL],
             tool_choice={"type": "tool", "name": "parse_criteria_bulk"},

agents/intake.py

@@ -109,7 +109,7 @@ def run_intake_agent(client: anthropic.Anthropic) -> PatientProfile:
                 country_code=data.get("country_code", "US"),
                 lat=lat,
                 lon=lon,
-                radius_miles=data.get("radius_miles", 100),
+                radius_miles=data.get("radius_miles", 20),
                 phases=data.get("phases") or [],
                 include_eap=data.get("include_eap", False),
                 include_observational=data.get("include_observational", False),
@@ -224,7 +224,7 @@ def stream_intake_turn(
                 country_code=data.get("country_code", "US"),
                 lat=lat,
                 lon=lon,
-                radius_miles=data.get("radius_miles", 100),
+                radius_miles=data.get("radius_miles", 20),
                 phases=data.get("phases") or [],
                 include_eap=data.get("include_eap", False),
                 include_observational=data.get("include_observational", False),

agents/research.py

@@ -18,6 +18,61 @@ from _console import console
 
 _logger = get_logger("agents.research")
 
+_MAX_TRIALS_FOR_LLM = 15
+
+# Fields with no synthesis value once eligibility is parsed; stripping them
+# shrinks the tool-result payload significantly (nearest_sites alone is ~250 tokens/trial).
+_STRIP_BEFORE_LLM = {
+    "summary",       # LLM writes its own plain-language summary
+    "conditions",    # patient already knows their disease
+    "keywords",
+    "min_age", "max_age", "sex", "healthy_volunteers",  # in parsed_criteria after bulk parse
+    "std_ages",
+    "eligibility",   # raw text; replaced by parsed_criteria for top-5
+}
+
+
+_PHASE_PRIORITY: dict[str, int] = {
+    "PHASE4": 1,
+    "PHASE3": 2,
+    "PHASE2": 3,
+    "PHASE1": 4,
+    "EARLY_PHASE1": 5,
+    "NA": 6,
+}
+
+
+def _phase_rank(trial: dict) -> int:
+    """Lower = higher priority. Phase 4 > Phase 3 > ... > EAP > Observational."""
+    study_type = trial.get("study_type", "")
+    if study_type == "EXPANDED_ACCESS":
+        return 7
+    if study_type == "OBSERVATIONAL":
+        return 8
+    phase_str = trial.get("phase", "N/A")
+    phases = [p.strip() for p in phase_str.replace(" ", "").split(",") if p.strip()]
+    return min((_PHASE_PRIORITY.get(p, 6) for p in phases), default=6)
+
+
+def _rank_and_slim(trials: list[dict]) -> list[dict]:
+    """Sort by phase priority then distance, cap at _MAX_TRIALS_FOR_LLM, strip bloat."""
+    ranked = sorted(
+        trials,
+        key=lambda t: (_phase_rank(t), t.get("closest_site_miles") or float("inf")),
+    )
+    slimmed = []
+    for t in ranked[:_MAX_TRIALS_FOR_LLM]:
+        t = {k: v for k, v in t.items() if k not in _STRIP_BEFORE_LLM}
+        if "nearest_sites" in t:
+            t["nearest_sites"] = t["nearest_sites"][:3]
+        if "interventions" in t:
+            t["interventions"] = [
+                {"type": iv.get("type", ""), "name": iv.get("name", "")}
+                for iv in t["interventions"]
+            ]
+        slimmed.append(t)
+    return slimmed
+
 
 def run_research_agent(client: anthropic.Anthropic, profile: PatientProfile) -> str:
     messages: list[anthropic.types.MessageParam] = [
@@ -33,7 +88,7 @@ def run_research_agent(client: anthropic.Anthropic, profile: PatientProfile) ->
     while True:
         response = client.messages.create(
             model=RESEARCH_MODEL,
-            max_tokens=8096,
+            max_tokens=3000,
             system=cached_system(RESEARCH_SYSTEM),
             tools=cached_tools(RESEARCH_TOOLS),
             messages=messages,
@@ -74,7 +129,7 @@ def run_research_agent(client: anthropic.Anthropic, profile: PatientProfile) ->
                     ranked = _flatten_and_rank(studies, profile.lat, profile.lon)
                     ranked = bulk_parse_and_strip(client, ranked, profile)
                 console.print(f"  [green]✓[/green] {len(ranked)} trial(s) found.")
-                content = json.dumps(ranked)
+                content = json.dumps(_rank_and_slim(ranked))
                 is_error = False
             except Exception as exc:
                 console.print(f"[red bold]API error:[/red bold] {exc}")
@@ -113,7 +168,7 @@ def stream_research_agent(
         stream_text = ""
         with client.messages.stream(
             model=RESEARCH_MODEL,
-            max_tokens=8096,
+            max_tokens=3000,
             system=cached_system(LANGUAGE_DIRECTIVE[profile.lang] + RESEARCH_SYSTEM),
             tools=cached_tools(RESEARCH_TOOLS),
             messages=messages,
@@ -152,7 +207,7 @@ def stream_research_agent(
                 yield ("status", f"Found **{n}** {type_label} — checking eligibility for the {min(5, n)} closest…")
                 ranked = bulk_parse_and_strip(client, ranked, profile)
                 yield ("status", "Eligibility analysis complete — generating your report…")
-                content = json.dumps(ranked)
+                content = json.dumps(_rank_and_slim(ranked))
                 is_error = False
             except Exception as exc:
                 content = f"API request failed: {exc}. The ClinicalTrials.gov endpoint may be temporarily unavailable."

data/tools/submit_profile.json

@@ -34,7 +34,7 @@
     },
     "radius_miles": {
       "type": "integer",
-      "description": "Search radius in miles from patient location (default 100)"
+      "description": "Search radius in miles from patient location (default 20)"
     },
     "phases": {
       "type": "array",

models.py

@@ -19,7 +19,7 @@ class PatientProfile:
     country_code: str = "US"
     lat: float = 0.0
     lon: float = 0.0
-    radius_miles: int = 100
+    radius_miles: int = 20
     phases: list[str] = field(default_factory=list)
     include_eap: bool = False
     include_observational: bool = False

tests/agents/test_eligibility.py

@@ -177,6 +177,37 @@ class TestEvaluateDeterministic:
         a = _evaluate_deterministic(c, 52)
         assert a.verdict == CriterionVerdict.FAIL
 
+    # --- unit normalization: years → months ---
+
+    def test_onset_years_converted_to_months_fails_correctly(self):
+        # Trial says "onset >= 18 years"; patient has 20 months — should FAIL (20 < 216)
+        c = make_criterion(key="symptom_onset_months", operator=">=", value=18, unit="years")
+        a = _evaluate_deterministic(c, 20)
+        assert a.verdict == CriterionVerdict.FAIL
+        assert "216" in a.reason
+        assert "months" in a.reason
+
+    def test_onset_months_unit_unchanged(self):
+        # Trial says "onset >= 18 months"; patient has 20 months — should PASS, value stays 18
+        c = make_criterion(key="symptom_onset_months", operator=">=", value=18, unit="months")
+        a = _evaluate_deterministic(c, 20)
+        assert a.verdict == CriterionVerdict.PASS
+        assert "18 months" in a.reason
+
+    def test_diagnosis_years_converted_to_months(self):
+        # Trial says "diagnosis >= 2 years"; patient has 18 months — should FAIL (18 < 24)
+        c = make_criterion(key="diagnosis_months", operator=">=", value=2, unit="years")
+        a = _evaluate_deterministic(c, 18)
+        assert a.verdict == CriterionVerdict.FAIL
+        assert "24" in a.reason
+
+    def test_between_years_normalized_to_months(self):
+        # Trial says "onset between 1 and 2 years" → [12, 24] months; patient 20 months → PASS
+        c = make_criterion(key="symptom_onset_months", operator="between", value=[1, 2], unit="years")
+        a = _evaluate_deterministic(c, 20)
+        assert a.verdict == CriterionVerdict.PASS
+        assert "12" in a.reason and "24" in a.reason
+
 
 # ---------------------------------------------------------------------------
 # _resolve_patient_value
@@ -193,6 +224,12 @@ class TestResolvePatientValue:
         assert found is True
         assert val == 18
 
+    def test_non_canonical_onset_key_not_found(self, als_patient):
+        # "weakness_onset_months" is not in _KEY_MAP — confirms the parser must use
+        # the canonical "symptom_onset_months" key for deterministic evaluation to work
+        _, found = _resolve_patient_value("weakness_onset_months", als_patient, None)
+        assert found is False
+
     def test_patient_diagnosis_months_resolves(self, als_patient):
         val, found = _resolve_patient_value("diagnosis_months", als_patient, None)
         assert found is True

tests/agents/test_research.py

@@ -12,11 +12,77 @@ from unittest.mock import MagicMock, patch
 
 import pytest
 
-from agents.research import run_research_agent, stream_research_agent
+from agents.research import run_research_agent, stream_research_agent, _phase_rank, _rank_and_slim
 from models import PatientProfile
 from tests.conftest import FakeStream, make_message, make_text_block, make_tool_use_block
 
 
+# ---------------------------------------------------------------------------
+# _phase_rank and _rank_and_slim
+# ---------------------------------------------------------------------------
+
+def _trial(study_type="INTERVENTIONAL", phase="PHASE3", distance=10.0, **extra):
+    return {"study_type": study_type, "phase": phase, "closest_site_miles": distance, **extra}
+
+
+class TestPhaseRank:
+    def test_phase4_beats_phase3(self):
+        assert _phase_rank(_trial(phase="PHASE4")) < _phase_rank(_trial(phase="PHASE3"))
+
+    def test_phase3_beats_phase2(self):
+        assert _phase_rank(_trial(phase="PHASE3")) < _phase_rank(_trial(phase="PHASE2"))
+
+    def test_phase2_beats_phase1(self):
+        assert _phase_rank(_trial(phase="PHASE2")) < _phase_rank(_trial(phase="PHASE1"))
+
+    def test_phase1_beats_eap(self):
+        assert _phase_rank(_trial(phase="PHASE1")) < _phase_rank(_trial(study_type="EXPANDED_ACCESS", phase=""))
+
+    def test_eap_beats_observational(self):
+        assert _phase_rank(_trial(study_type="EXPANDED_ACCESS", phase="")) < _phase_rank(_trial(study_type="OBSERVATIONAL", phase=""))
+
+    def test_na_phase_interventional_between_phase1_and_eap(self):
+        rank_na = _phase_rank(_trial(phase="NA"))
+        assert _phase_rank(_trial(phase="PHASE1")) < rank_na
+        assert rank_na < _phase_rank(_trial(study_type="EXPANDED_ACCESS", phase=""))
+
+
+class TestRankAndSlim:
+    def test_phase4_sorted_before_phase3(self):
+        trials = [_trial(phase="PHASE3", nct_id="B"), _trial(phase="PHASE4", nct_id="A")]
+        result = _rank_and_slim(trials)
+        assert result[0]["nct_id"] == "A"
+
+    def test_within_same_phase_closer_first(self):
+        trials = [_trial(phase="PHASE3", distance=50.0, nct_id="far"), _trial(phase="PHASE3", distance=5.0, nct_id="near")]
+        result = _rank_and_slim(trials)
+        assert result[0]["nct_id"] == "near"
+
+    def test_capped_at_max_trials(self):
+        trials = [_trial(phase="PHASE2", nct_id=str(i)) for i in range(20)]
+        result = _rank_and_slim(trials)
+        assert len(result) <= 15
+
+    def test_strips_summary_and_conditions(self):
+        trials = [_trial(phase="PHASE3", summary="long text", conditions=["ALS"])]
+        result = _rank_and_slim(trials)
+        assert "summary" not in result[0]
+        assert "conditions" not in result[0]
+
+    def test_nearest_sites_capped_at_3(self):
+        sites = [{"label": f"Site {i}"} for i in range(5)]
+        trials = [_trial(phase="PHASE3", nearest_sites=sites)]
+        result = _rank_and_slim(trials)
+        assert len(result[0]["nearest_sites"]) == 3
+
+    def test_intervention_description_stripped(self):
+        iv = [{"type": "DRUG", "name": "DrugX", "description": "long description text"}]
+        trials = [_trial(phase="PHASE3", interventions=iv)]
+        result = _rank_and_slim(trials)
+        assert "description" not in result[0]["interventions"][0]
+        assert result[0]["interventions"][0]["name"] == "DrugX"
+
+
 PATCH_SEARCH = "agents.research.search_trials_api"
 PATCH_FLATTEN = "agents.research._flatten_and_rank"
 PATCH_BULK = "agents.research.bulk_parse_and_strip"