test(wave-3): deterministic eligibility and trials_api tests (#18)

tests/agents/test_eligibility.py (37 tests):
- _evaluate_deterministic: every operator (<=, >=, ==, !=, in, not_in,
between) × pass/fail; output shape (confidence=high, patient_value
stringified, reason format, unit inclusion, TypeError→FAIL)
- _resolve_patient_value: patient.* fields, platform.* with/without data,
unknown key
- _compute_overall: precedence rule FAIL>UNKNOWN>PASS, empty list→PASS

tests/test_trials_api.py (30 tests):
- _flatten_and_rank: sort order, None-distance sorts last, nearest_sites
capped at 5, central-contact phone fallback, required key presence
- search_trials_api aggFilters: all 8 case-matrix branches from the
inline comment in trials_api.py
- search_trials_api pagination: nextPageToken forwarded, multi-page
accumulation, empty response
- search_trials_api retry: succeeds after 1 failure, raises after 3

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

tests/agents/test_eligibility.py

@@ -0,0 +1,251 @@
+"""Tests for deterministic logic in agents/eligibility.py.
+
+Covers _evaluate_deterministic, _resolve_patient_value, and _compute_overall.
+No mocks needed — all three functions are pure computation.
+"""
+from __future__ import annotations
+
+import pytest
+
+from agents.eligibility import (
+    _compute_overall,
+    _evaluate_deterministic,
+    _resolve_patient_value,
+)
+from models import (
+    CriterionAssessment,
+    CriterionVerdict,
+    EligibilityCriterion,
+    ParsedConstraint,
+    PatientProfile,
+)
+
+
+# ---------------------------------------------------------------------------
+# Helpers
+# ---------------------------------------------------------------------------
+
+def make_criterion(
+    key: str = "age_years",
+    operator: str = ">=",
+    value=18,
+    unit: str | None = None,
+    ctype: str = "inclusion",
+    description: str = "Test criterion",
+    raw_criteria: str = "Raw criterion text",
+) -> EligibilityCriterion:
+    return EligibilityCriterion(
+        key=key,
+        type=ctype,
+        description=description,
+        raw_criteria=raw_criteria,
+        constraint=ParsedConstraint(key=key, operator=operator, value=value, unit=unit),
+    )
+
+
+def make_assessment(verdict: CriterionVerdict) -> CriterionAssessment:
+    c = make_criterion()
+    return CriterionAssessment(
+        criterion=c,
+        verdict=verdict,
+        reason="test",
+        patient_value="42",
+        confidence="high",
+    )
+
+
+# ---------------------------------------------------------------------------
+# _evaluate_deterministic — every operator × pass/fail
+# ---------------------------------------------------------------------------
+
+class TestEvaluateDeterministic:
+    # --- >= ---
+    def test_gte_passes_when_equal(self):
+        a = _evaluate_deterministic(make_criterion(operator=">=", value=18), 18)
+        assert a.verdict == CriterionVerdict.PASS
+
+    def test_gte_passes_when_above(self):
+        a = _evaluate_deterministic(make_criterion(operator=">=", value=18), 52)
+        assert a.verdict == CriterionVerdict.PASS
+
+    def test_gte_fails_when_below(self):
+        a = _evaluate_deterministic(make_criterion(operator=">=", value=18), 16)
+        assert a.verdict == CriterionVerdict.FAIL
+
+    # --- <= ---
+    def test_lte_passes_when_equal(self):
+        a = _evaluate_deterministic(make_criterion(operator="<=", value=75), 75)
+        assert a.verdict == CriterionVerdict.PASS
+
+    def test_lte_passes_when_below(self):
+        a = _evaluate_deterministic(make_criterion(operator="<=", value=75), 52)
+        assert a.verdict == CriterionVerdict.PASS
+
+    def test_lte_fails_when_above(self):
+        a = _evaluate_deterministic(make_criterion(operator="<=", value=75), 80)
+        assert a.verdict == CriterionVerdict.FAIL
+
+    # --- == ---
+    def test_eq_passes(self):
+        a = _evaluate_deterministic(make_criterion(operator="==", value=0), 0)
+        assert a.verdict == CriterionVerdict.PASS
+
+    def test_eq_fails(self):
+        a = _evaluate_deterministic(make_criterion(operator="==", value=0), 1)
+        assert a.verdict == CriterionVerdict.FAIL
+
+    # --- != ---
+    def test_ne_passes(self):
+        a = _evaluate_deterministic(make_criterion(operator="!=", value=0), 1)
+        assert a.verdict == CriterionVerdict.PASS
+
+    def test_ne_fails(self):
+        a = _evaluate_deterministic(make_criterion(operator="!=", value=0), 0)
+        assert a.verdict == CriterionVerdict.FAIL
+
+    # --- in ---
+    def test_in_passes(self):
+        a = _evaluate_deterministic(make_criterion(operator="in", value=[0, 1]), 1)
+        assert a.verdict == CriterionVerdict.PASS
+
+    def test_in_fails(self):
+        a = _evaluate_deterministic(make_criterion(operator="in", value=[0, 1]), 2)
+        assert a.verdict == CriterionVerdict.FAIL
+
+    # --- not_in ---
+    def test_not_in_passes(self):
+        a = _evaluate_deterministic(make_criterion(operator="not_in", value=[2, 3]), 1)
+        assert a.verdict == CriterionVerdict.PASS
+
+    def test_not_in_fails(self):
+        a = _evaluate_deterministic(make_criterion(operator="not_in", value=[2, 3]), 2)
+        assert a.verdict == CriterionVerdict.FAIL
+
+    # --- between ---
+    def test_between_passes_at_lower_bound(self):
+        a = _evaluate_deterministic(make_criterion(operator="between", value=[18, 75]), 18)
+        assert a.verdict == CriterionVerdict.PASS
+
+    def test_between_passes_at_upper_bound(self):
+        a = _evaluate_deterministic(make_criterion(operator="between", value=[18, 75]), 75)
+        assert a.verdict == CriterionVerdict.PASS
+
+    def test_between_passes_mid(self):
+        a = _evaluate_deterministic(make_criterion(operator="between", value=[18, 75]), 52)
+        assert a.verdict == CriterionVerdict.PASS
+
+    def test_between_fails_below(self):
+        a = _evaluate_deterministic(make_criterion(operator="between", value=[18, 75]), 17)
+        assert a.verdict == CriterionVerdict.FAIL
+
+    def test_between_fails_above(self):
+        a = _evaluate_deterministic(make_criterion(operator="between", value=[18, 75]), 76)
+        assert a.verdict == CriterionVerdict.FAIL
+
+    # --- output shape ---
+    def test_confidence_is_high(self):
+        a = _evaluate_deterministic(make_criterion(operator=">=", value=18), 52)
+        assert a.confidence == "high"
+
+    def test_patient_value_stringified(self):
+        a = _evaluate_deterministic(make_criterion(operator=">=", value=18), 52)
+        assert a.patient_value == "52"
+
+    def test_reason_contains_operator_and_value(self):
+        a = _evaluate_deterministic(make_criterion(operator=">=", value=18), 52)
+        assert ">=" in a.reason
+        assert "18" in a.reason
+
+    def test_reason_includes_unit_when_present(self):
+        c = make_criterion(operator=">=", value=60, unit="mL/min")
+        a = _evaluate_deterministic(c, 65)
+        assert "mL/min" in a.reason
+
+    def test_type_error_in_comparison_yields_fail(self):
+        # Comparing int to a list value that can't be compared numerically
+        c = make_criterion(operator=">=", value="not-a-number")
+        a = _evaluate_deterministic(c, 52)
+        assert a.verdict == CriterionVerdict.FAIL
+
+
+# ---------------------------------------------------------------------------
+# _resolve_patient_value
+# ---------------------------------------------------------------------------
+
+class TestResolvePatientValue:
+    def test_patient_age_resolves(self, als_patient):
+        val, found = _resolve_patient_value("age_years", als_patient, None)
+        assert found is True
+        assert val == 52
+
+    def test_patient_onset_months_resolves(self, als_patient):
+        val, found = _resolve_patient_value("symptom_onset_months", als_patient, None)
+        assert found is True
+        assert val == 18
+
+    def test_patient_diagnosis_months_resolves(self, als_patient):
+        val, found = _resolve_patient_value("diagnosis_months", als_patient, None)
+        assert found is True
+        assert val == 12
+
+    def test_unknown_key_returns_not_found(self, als_patient):
+        val, found = _resolve_patient_value("nonexistent_key_xyz", als_patient, None)
+        assert found is False
+        assert val is None
+
+    def test_platform_key_returns_not_found_without_data(self, als_patient):
+        val, found = _resolve_patient_value("ecog_status", als_patient, None)
+        assert found is False
+
+    def test_platform_key_resolves_with_data(self, als_patient):
+        platform = {"ecog_status": 1}
+        val, found = _resolve_patient_value("ecog_status", als_patient, platform)
+        assert found is True
+        assert val == 1
+
+    def test_platform_key_missing_from_dict_returns_not_found(self, als_patient):
+        platform = {"other_field": 99}
+        val, found = _resolve_patient_value("ecog_status", als_patient, platform)
+        assert found is False
+
+
+# ---------------------------------------------------------------------------
+# _compute_overall
+# ---------------------------------------------------------------------------
+
+class TestComputeOverall:
+    def test_all_pass_returns_pass(self):
+        assessments = [make_assessment(CriterionVerdict.PASS)] * 3
+        assert _compute_overall(assessments) == CriterionVerdict.PASS
+
+    def test_any_fail_returns_fail(self):
+        assessments = [
+            make_assessment(CriterionVerdict.PASS),
+            make_assessment(CriterionVerdict.FAIL),
+            make_assessment(CriterionVerdict.UNKNOWN),
+        ]
+        assert _compute_overall(assessments) == CriterionVerdict.FAIL
+
+    def test_fail_takes_precedence_over_unknown(self):
+        assessments = [
+            make_assessment(CriterionVerdict.UNKNOWN),
+            make_assessment(CriterionVerdict.FAIL),
+        ]
+        assert _compute_overall(assessments) == CriterionVerdict.FAIL
+
+    def test_unknown_without_fail_returns_unknown(self):
+        assessments = [
+            make_assessment(CriterionVerdict.PASS),
+            make_assessment(CriterionVerdict.UNKNOWN),
+        ]
+        assert _compute_overall(assessments) == CriterionVerdict.UNKNOWN
+
+    def test_empty_list_returns_pass(self):
+        # No criteria → no objections → eligible
+        assert _compute_overall([]) == CriterionVerdict.PASS
+
+    def test_single_fail_returns_fail(self):
+        assert _compute_overall([make_assessment(CriterionVerdict.FAIL)]) == CriterionVerdict.FAIL
+
+    def test_single_unknown_returns_unknown(self):
+        assert _compute_overall([make_assessment(CriterionVerdict.UNKNOWN)]) == CriterionVerdict.UNKNOWN

tests/test_trials_api.py

@@ -0,0 +1,268 @@
+"""Tests for trials_api.py.
+
+_flatten_and_rank: pure dict reshaping — no mocks.
+search_trials_api: HTTP is mocked with pytest-httpx.
+"""
+from __future__ import annotations
+
+import json
+
+import httpx
+import pytest
+
+from trials_api import _flatten_and_rank, search_trials_api
+
+
+# ---------------------------------------------------------------------------
+# Minimal study builder
+# ---------------------------------------------------------------------------
+
+def make_study(
+    nct_id: str = "NCT00000001",
+    title: str = "Test Trial",
+    phase: list[str] | None = None,
+    sponsor: str = "ACME Pharma",
+    locations: list[dict] | None = None,
+    eligibility_criteria: str = "Inclusion:\n- Age 18-75",
+) -> dict:
+    return {
+        "protocolSection": {
+            "identificationModule": {"nctId": nct_id, "briefTitle": title},
+            "descriptionModule": {"briefSummary": "A test trial."},
+            "eligibilityModule": {
+                "eligibilityCriteria": eligibility_criteria,
+                "minimumAge": "18 Years",
+                "maximumAge": "75 Years",
+                "sex": "ALL",
+                "healthyVolunteers": "No",
+                "stdAges": ["ADULT"],
+            },
+            "contactsLocationsModule": {
+                "centralContacts": [{"phone": "617-555-0100", "email": "pi@hospital.org"}],
+                "overallOfficials": [{"name": "Dr. Smith", "role": "PRINCIPAL_INVESTIGATOR"}],
+                "locations": locations or [],
+            },
+            "sponsorCollaboratorsModule": {"leadSponsor": {"name": sponsor}},
+            "designModule": {
+                "studyType": "INTERVENTIONAL",
+                "phases": phase or ["PHASE2"],
+                "enrollmentInfo": {"count": 50},
+            },
+            "conditionsModule": {"conditions": ["ALS"], "keywords": ["motor neuron"]},
+            "armsInterventionsModule": {"interventions": []},
+        }
+    }
+
+
+def make_location(lat: float, lon: float, city: str = "Boston", state: str = "MA") -> dict:
+    return {
+        "facility": f"{city} Medical Center",
+        "city": city,
+        "state": state,
+        "geoPoint": {"lat": lat, "lon": lon},
+        "contacts": [{"phone": "617-555-0200", "email": "site@hospital.org"}],
+    }
+
+
+# ---------------------------------------------------------------------------
+# _flatten_and_rank — pure logic, no HTTP
+# ---------------------------------------------------------------------------
+
+class TestFlattenAndRank:
+    PATIENT_LAT = 42.3370
+    PATIENT_LON = -71.1061  # Boston
+
+    def test_empty_input_returns_empty(self):
+        assert _flatten_and_rank([], self.PATIENT_LAT, self.PATIENT_LON) == []
+
+    def test_nct_id_extracted(self):
+        studies = [make_study(nct_id="NCT12345678")]
+        result = _flatten_and_rank(studies, self.PATIENT_LAT, self.PATIENT_LON)
+        assert result[0]["nct_id"] == "NCT12345678"
+
+    def test_title_extracted(self):
+        studies = [make_study(title="My Trial")]
+        result = _flatten_and_rank(studies, self.PATIENT_LAT, self.PATIENT_LON)
+        assert result[0]["title"] == "My Trial"
+
+    def test_sponsor_extracted(self):
+        studies = [make_study(sponsor="Test Corp")]
+        result = _flatten_and_rank(studies, self.PATIENT_LAT, self.PATIENT_LON)
+        assert result[0]["sponsor"] == "Test Corp"
+
+    def test_no_locations_yields_none_closest(self):
+        studies = [make_study()]
+        result = _flatten_and_rank(studies, self.PATIENT_LAT, self.PATIENT_LON)
+        assert result[0]["closest_site_miles"] is None
+
+    def test_location_distance_computed(self):
+        loc = make_location(lat=42.3370, lon=-71.1061)  # same as patient
+        studies = [make_study(locations=[loc])]
+        result = _flatten_and_rank(studies, self.PATIENT_LAT, self.PATIENT_LON)
+        assert result[0]["closest_site_miles"] == 0.0
+
+    def test_sorted_by_closest_distance(self):
+        near_loc = make_location(lat=42.3370, lon=-71.1061, city="Boston")   # 0 mi
+        far_loc = make_location(lat=40.7128, lon=-74.0060, city="NewYork")  # ~190 mi
+        near_study = make_study(nct_id="NCT00000001", locations=[near_loc])
+        far_study = make_study(nct_id="NCT00000002", locations=[far_loc])
+        # Pass far first to confirm sort works
+        result = _flatten_and_rank([far_study, near_study], self.PATIENT_LAT, self.PATIENT_LON)
+        assert result[0]["nct_id"] == "NCT00000001"
+        assert result[1]["nct_id"] == "NCT00000002"
+
+    def test_no_location_sorts_last(self):
+        loc = make_location(lat=42.3370, lon=-71.1061)
+        study_with = make_study(nct_id="NCT00000001", locations=[loc])
+        study_without = make_study(nct_id="NCT00000002", locations=[])
+        result = _flatten_and_rank([study_without, study_with], self.PATIENT_LAT, self.PATIENT_LON)
+        assert result[0]["nct_id"] == "NCT00000001"
+        assert result[1]["nct_id"] == "NCT00000002"
+
+    def test_nearest_sites_capped_at_five(self):
+        locs = [make_location(lat=42.3370 + i * 0.01, lon=-71.1061, city=f"City{i}") for i in range(8)]
+        studies = [make_study(locations=locs)]
+        result = _flatten_and_rank(studies, self.PATIENT_LAT, self.PATIENT_LON)
+        assert len(result[0]["nearest_sites"]) == 5
+
+    def test_site_label_contains_city_and_distance(self):
+        loc = make_location(lat=42.3370, lon=-71.1061, city="Boston")
+        studies = [make_study(locations=[loc])]
+        result = _flatten_and_rank(studies, self.PATIENT_LAT, self.PATIENT_LON)
+        label = result[0]["nearest_sites"][0]["label"]
+        assert "Boston" in label
+        assert "mi" in label
+
+    def test_central_contact_phone_fallback(self):
+        # Site has no phone — should fall back to central contact
+        loc = {
+            "facility": "No-Phone Clinic",
+            "city": "Cambridge",
+            "state": "MA",
+            "geoPoint": {"lat": 42.37, "lon": -71.10},
+            "contacts": [],
+        }
+        studies = [make_study(locations=[loc])]
+        result = _flatten_and_rank(studies, self.PATIENT_LAT, self.PATIENT_LON)
+        assert result[0]["nearest_sites"][0]["phone"] == "617-555-0100"
+
+    def test_required_keys_present(self):
+        studies = [make_study()]
+        result = _flatten_and_rank(studies, self.PATIENT_LAT, self.PATIENT_LON)
+        row = result[0]
+        for key in ("nct_id", "title", "phase", "sponsor", "summary", "eligibility",
+                    "closest_site_miles", "nearest_sites", "interventions"):
+            assert key in row, f"missing key: {key}"
+
+
+# ---------------------------------------------------------------------------
+# search_trials_api — aggFilters param construction
+# ---------------------------------------------------------------------------
+
+def _api_response(studies: list[dict], next_token: str | None = None) -> dict:
+    body: dict = {"studies": studies}
+    if next_token:
+        body["nextPageToken"] = next_token
+    return body
+
+
+class TestSearchTrialsApiAggFilters:
+    BASE_URL = "https://clinicaltrials.gov/api/v2/studies"
+
+    def _get_params(self, httpx_mock, **kwargs) -> dict:
+        """Call search_trials_api with given kwargs, return query params of the captured request."""
+        httpx_mock.add_response(json=_api_response([]))
+        search_trials_api(condition="ALS", lat=42.33, lon=-71.10, **kwargs)
+        return dict(httpx_mock.get_requests()[0].url.params)
+
+    def test_default_interventional_all_phases(self, httpx_mock):
+        params = self._get_params(httpx_mock)
+        assert params["aggFilters"] == "studyType:int"
+
+    def test_interventional_specific_phases(self, httpx_mock):
+        params = self._get_params(httpx_mock, phases=["2", "3"])
+        assert params["aggFilters"] == "phase:2 3"
+
+    def test_interventional_na_only_maps_to_int(self, httpx_mock):
+        # "na" is not a numbered phase — falls through to studyType:int
+        params = self._get_params(httpx_mock, phases=["na"])
+        assert params["aggFilters"] == "studyType:int"
+
+    def test_interventional_mixed_phases_strips_na(self, httpx_mock):
+        params = self._get_params(httpx_mock, phases=["2", "na"])
+        assert params["aggFilters"] == "phase:2"
+
+    def test_observational_study_type(self, httpx_mock):
+        params = self._get_params(httpx_mock, study_type="OBSERVATIONAL")
+        assert params["aggFilters"] == "studyType:obs"
+
+    def test_eap_no_phases(self, httpx_mock):
+        params = self._get_params(httpx_mock, study_type="EXPANDED_ACCESS")
+        assert params["aggFilters"] == "studyType:exp"
+
+    def test_eap_with_numbered_phases(self, httpx_mock):
+        params = self._get_params(httpx_mock, study_type="EXPANDED_ACCESS", phases=["2", "3"])
+        assert params["aggFilters"] == "studyType:exp,phase:2 3"
+
+    def test_eap_with_na_only_no_phase_filter(self, httpx_mock):
+        params = self._get_params(httpx_mock, study_type="EXPANDED_ACCESS", phases=["na"])
+        assert params["aggFilters"] == "studyType:exp"
+
+    def test_status_filter_recruiting_for_interventional(self, httpx_mock):
+        params = self._get_params(httpx_mock)
+        assert params["filter.overallStatus"] == "RECRUITING"
+
+    def test_status_filter_available_for_eap(self, httpx_mock):
+        params = self._get_params(httpx_mock, study_type="EXPANDED_ACCESS")
+        assert params["filter.overallStatus"] == "AVAILABLE"
+
+    def test_geo_filter_formatted(self, httpx_mock):
+        params = self._get_params(httpx_mock, radius_miles=50)
+        assert params["filter.geo"] == "distance(42.33,-71.1,50mi)"
+
+    def test_condition_passed_through(self, httpx_mock):
+        params = self._get_params(httpx_mock)
+        assert params["query.cond"] == "ALS"
+
+
+class TestSearchTrialsApiPagination:
+    def test_follows_next_page_token(self, httpx_mock):
+        page1 = _api_response([make_study("NCT00000001")], next_token="token-abc")
+        page2 = _api_response([make_study("NCT00000002")])
+        httpx_mock.add_response(json=page1)
+        httpx_mock.add_response(json=page2)
+
+        results = search_trials_api("ALS", lat=42.33, lon=-71.10)
+        assert len(results) == 2
+
+    def test_second_request_includes_page_token(self, httpx_mock):
+        page1 = _api_response([make_study()], next_token="token-xyz")
+        page2 = _api_response([])
+        httpx_mock.add_response(json=page1)
+        httpx_mock.add_response(json=page2)
+
+        search_trials_api("ALS", lat=42.33, lon=-71.10)
+        second_req = httpx_mock.get_requests()[1]
+        assert second_req.url.params["pageToken"] == "token-xyz"
+
+    def test_empty_response_returns_empty_list(self, httpx_mock):
+        httpx_mock.add_response(json=_api_response([]))
+        results = search_trials_api("ALS", lat=42.33, lon=-71.10)
+        assert results == []
+
+
+class TestSearchTrialsApiRetry:
+    def test_retries_on_http_error_then_succeeds(self, httpx_mock):
+        httpx_mock.add_response(status_code=500)
+        httpx_mock.add_response(json=_api_response([make_study()]))
+
+        results = search_trials_api("ALS", lat=42.33, lon=-71.10)
+        assert len(results) == 1
+        assert len(httpx_mock.get_requests()) == 2
+
+    def test_raises_after_three_failures(self, httpx_mock):
+        for _ in range(3):
+            httpx_mock.add_response(status_code=503)
+
+        with pytest.raises(httpx.HTTPStatusError):
+            search_trials_api("ALS", lat=42.33, lon=-71.10)