feat: implement 3 BE service stubs with 17 TDD tests

- MedGemmaExtractor: profile parsing, extraction prompts, criterion evaluation
- GeminiPlanner: SearchAnchors generation, eligibility evaluation via google-genai
- ClinicalTrialsMCPClient: MCP JSON-RPC wrapper for search, get_study, find_eligible
- MCPError exception class for error handling

54 total BE tests pass (37 models + 17 services). Ruff clean.

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

trialpath/services/__init__.py

@@ -0,0 +1 @@
+"""TrialPath backend services."""

trialpath/services/gemini_planner.py

@@ -0,0 +1,81 @@
+"""Gemini structured output for SearchAnchors generation and eligibility evaluation."""
+import json
+import os
+
+from google import genai
+
+from trialpath.models.eligibility_ledger import EligibilityLedger
+from trialpath.models.search_anchors import SearchAnchors
+
+MODEL = "gemini-3-pro"
+
+
+class GeminiPlanner:
+    """Orchestration layer using Gemini for structured output."""
+
+    def __init__(self, model: str = MODEL):
+        self.model = model
+        self.client = genai.Client(api_key=os.environ.get("GEMINI_API_KEY", ""))
+
+    async def generate_search_anchors(self, patient_profile: dict) -> SearchAnchors:
+        """Use Gemini structured output to generate SearchAnchors from PatientProfile."""
+        prompt = f"""
+        Given the following patient profile, generate search parameters
+        for finding relevant NSCLC clinical trials on ClinicalTrials.gov.
+
+        Patient Profile:
+        {json.dumps(patient_profile, indent=2)}
+
+        Generate SearchAnchors that:
+        1. Focus on the patient's specific cancer type, stage, and biomarkers
+        2. Include appropriate geographic filters
+        3. Consider the patient's age and performance status
+        4. Set a relaxation_order for broadening search if too few results
+        """
+
+        response = self.client.models.generate_content(
+            model=self.model,
+            contents=prompt,
+            config={
+                "response_mime_type": "application/json",
+                "response_json_schema": SearchAnchors.model_json_schema(),
+            },
+        )
+
+        return SearchAnchors.model_validate_json(response.text)
+
+    async def evaluate_eligibility(
+        self,
+        patient_profile: dict,
+        trial_candidate: dict,
+        search_log: object | None = None,
+    ) -> EligibilityLedger:
+        """Use Gemini to evaluate eligibility for a single trial."""
+        prompt = f"""
+        Evaluate this patient's eligibility for the clinical trial below.
+
+        For each inclusion/exclusion criterion:
+        1. Assign a criterion_id (inc_1, inc_2, ... or exc_1, exc_2, ...)
+        2. Determine if the criterion is met, not_met, or unknown
+        3. Provide reasoning and evidence pointers
+
+        Patient Profile:
+        {json.dumps(patient_profile, indent=2, default=str)}
+
+        Trial:
+        {json.dumps(trial_candidate, indent=2, default=str)}
+
+        Also identify gaps: criteria that are 'unknown' where additional data
+        could change the assessment.
+        """
+
+        response = self.client.models.generate_content(
+            model=self.model,
+            contents=prompt,
+            config={
+                "response_mime_type": "application/json",
+                "response_json_schema": EligibilityLedger.model_json_schema(),
+            },
+        )
+
+        return EligibilityLedger.model_validate_json(response.text)

trialpath/services/mcp_client.py

@@ -0,0 +1,123 @@
+"""ClinicalTrials MCP server client wrapper."""
+import httpx
+
+from trialpath.models.search_anchors import SearchAnchors
+
+
+class MCPError(Exception):
+    """Error returned by the MCP server."""
+
+    def __init__(self, code: int, message: str):
+        self.code = code
+        self.message = message
+        super().__init__(f"MCP Error {code}: {message}")
+
+
+class ClinicalTrialsMCPClient:
+    """Client for ClinicalTrials MCP Server."""
+
+    def __init__(self, mcp_url: str = "http://localhost:3000"):
+        self.mcp_url = mcp_url
+
+    async def search(self, anchors: SearchAnchors) -> list[dict]:
+        """Convert SearchAnchors to MCP search_studies call."""
+        query_parts = [anchors.condition]
+        if anchors.subtype:
+            query_parts.append(anchors.subtype)
+        if anchors.biomarkers:
+            query_parts.extend(anchors.biomarkers)
+
+        query = " ".join(query_parts)
+
+        filters = []
+        if anchors.trial_filters.recruitment_status:
+            status_filter = " OR ".join(
+                f"AREA[OverallStatus]{s}"
+                for s in anchors.trial_filters.recruitment_status
+            )
+            filters.append(f"({status_filter})")
+
+        if anchors.trial_filters.phase:
+            phase_filter = " OR ".join(
+                f"AREA[Phase]{p}" for p in anchors.trial_filters.phase
+            )
+            filters.append(f"({phase_filter})")
+
+        if anchors.age is not None:
+            filters.append(f"AREA[MinimumAge]RANGE[MIN, {anchors.age}]")
+            filters.append(f"AREA[MaximumAge]RANGE[{anchors.age}, MAX]")
+
+        filter_str = " AND ".join(filters) if filters else None
+
+        params: dict = {
+            "query": query,
+            "pageSize": 50,
+            "sort": "LastUpdateDate:desc",
+        }
+        if filter_str:
+            params["filter"] = filter_str
+        if anchors.geography:
+            params["country"] = anchors.geography.country
+
+        result = await self._call_tool("clinicaltrials_search_studies", params)
+        return result.get("studies", [])
+
+    async def get_study(self, nct_id: str) -> dict:
+        """Fetch full study details by NCT ID."""
+        result = await self._call_tool("clinicaltrials_get_study", {
+            "nctIds": [nct_id],
+            "summaryOnly": False,
+        })
+        studies = result.get("studies", [])
+        return studies[0] if studies else {}
+
+    async def find_eligible(
+        self,
+        age: int,
+        sex: str,
+        conditions: list[str],
+        country: str,
+        max_results: int = 20,
+    ) -> dict:
+        """Use find_eligible_studies for demographic-based matching."""
+        return await self._call_tool("clinicaltrials_find_eligible_studies", {
+            "age": age,
+            "sex": sex,
+            "conditions": conditions,
+            "location": {"country": country},
+            "recruitingOnly": True,
+            "maxResults": max_results,
+        })
+
+    async def compare_studies(self, nct_ids: list[str]) -> dict:
+        """Compare 2-5 studies side by side."""
+        return await self._call_tool("clinicaltrials_compare_studies", {
+            "nctIds": nct_ids,
+            "compareFields": "all",
+        })
+
+    async def _call_tool(self, tool_name: str, params: dict) -> dict:
+        """Call an MCP tool via JSON-RPC."""
+        async with httpx.AsyncClient(timeout=30.0) as client:
+            response = await client.post(
+                f"{self.mcp_url}/mcp/v1/tools/call",
+                json={
+                    "jsonrpc": "2.0",
+                    "method": "tools/call",
+                    "params": {
+                        "name": tool_name,
+                        "arguments": params,
+                    },
+                    "id": 1,
+                },
+            )
+            response.raise_for_status()
+            data = response.json()
+
+            if "error" in data:
+                raise MCPError(
+                    code=data["error"].get("code", -1),
+                    message=data["error"].get("message", "Unknown MCP error"),
+                )
+
+            return data.get("result", {})

trialpath/services/medgemma_extractor.py

@@ -0,0 +1,119 @@
+"""MedGemma HF endpoint integration for patient profile extraction."""
+import json
+import re
+
+
+class MedGemmaExtractor:
+    """Extract patient profiles from medical documents using MedGemma.
+
+    For PoC, this is interface-first: the parsing and prompt methods are
+    fully implemented, but the actual model call requires a HuggingFace
+    Inference Endpoint or local GPU with MedGemma loaded.
+    """
+
+    def __init__(self, endpoint_url: str | None = None, hf_token: str | None = None):
+        self.endpoint_url = endpoint_url
+        self.hf_token = hf_token
+        self.pipe = None  # Initialized lazily when model is available
+
+    def _system_prompt(self) -> str:
+        return (
+            "You are an expert medical data extractor specializing in oncology. "
+            "Extract structured patient information from medical documents. "
+            "Always cite the source document and location for each extracted fact. "
+            "If information is unclear or missing, explicitly note it as unknown."
+        )
+
+    def _build_extraction_prompt(self, metadata: dict) -> str:
+        return f"""
+        Extract a structured patient profile from the following medical documents.
+
+        Known metadata: age={metadata.get('age', 'unknown')}, sex={metadata.get('sex', 'unknown')}
+
+        Extract the following fields in JSON format:
+        - diagnosis (primary_condition, histology, stage, diagnosis_date)
+        - performance_status (scale, value, evidence)
+        - biomarkers (name, result, date, evidence for each)
+        - key_labs (name, value, unit, date, evidence for each)
+        - treatments (drug_name, start_date, end_date, line, evidence)
+        - comorbidities (name, grade, evidence)
+        - imaging_summary (modality, date, finding, interpretation, certainty, evidence)
+        - unknowns (field, reason, importance for each missing critical field)
+
+        For each evidence reference, include: doc_id (filename), page number, span_id.
+
+        Return ONLY valid JSON matching the PatientProfile schema.
+        """
+
+    def _parse_profile(self, raw_text: str, metadata: dict) -> dict:
+        """Parse MedGemma output into PatientProfile structure."""
+        try:
+            profile = json.loads(raw_text)
+        except json.JSONDecodeError:
+            json_match = re.search(r"```(?:json)?\s*(.*?)\s*```", raw_text, re.DOTALL)
+            if json_match:
+                profile = json.loads(json_match.group(1))
+            else:
+                raise ValueError(
+                    f"Could not parse MedGemma output as JSON: {raw_text[:200]}"
+                )
+
+        if "demographics" not in profile:
+            profile["demographics"] = {}
+        profile["demographics"].update(metadata)
+
+        return profile
+
+    async def extract(self, document_urls: list[str], metadata: dict) -> dict:
+        """Extract PatientProfile from documents via MedGemma.
+
+        Requires self.pipe to be initialized with a HuggingFace pipeline.
+        """
+        if self.pipe is None:
+            raise RuntimeError(
+                "MedGemma pipeline not initialized. "
+                "Set up a HF Inference Endpoint or load model locally."
+            )
+
+        content = [
+            {"type": "text", "text": self._build_extraction_prompt(metadata)},
+        ]
+        # In production, images would be loaded from document_urls
+        messages = [
+            {"role": "system", "content": [{"type": "text", "text": self._system_prompt()}]},
+            {"role": "user", "content": content},
+        ]
+
+        output = self.pipe(text=messages, max_new_tokens=2048)
+        raw_text = output[0]["generated_text"][-1]["content"]
+        return self._parse_profile(raw_text, metadata)
+
+    async def evaluate_medical_criterion(
+        self,
+        criterion_text: str,
+        patient_profile: object,
+        evidence_docs: list,
+    ) -> dict:
+        """Evaluate a single medical criterion against patient evidence.
+
+        Stub for PoC -- requires MedGemma pipeline.
+        """
+        if self.pipe is None:
+            raise RuntimeError("MedGemma pipeline not initialized.")
+
+        prompt = f"""
+        Evaluate whether the patient meets this clinical trial criterion:
+        CRITERION: {criterion_text}
+
+        Respond with JSON:
+        {{"decision": "met|not_met|unknown", "reasoning": "...", "confidence": 0.0-1.0}}
+        """
+
+        messages = [
+            {"role": "system", "content": [{"type": "text", "text": self._system_prompt()}]},
+            {"role": "user", "content": [{"type": "text", "text": prompt}]},
+        ]
+
+        output = self.pipe(text=messages, max_new_tokens=1024)
+        raw_text = output[0]["generated_text"][-1]["content"]
+        return json.loads(raw_text)

trialpath/tests/test_gemini.py

@@ -0,0 +1,124 @@
+"""TDD tests for Gemini planner service."""
+from unittest.mock import MagicMock, patch
+
+import pytest
+
+from trialpath.models.eligibility_ledger import EligibilityLedger, OverallAssessment
+from trialpath.models.search_anchors import SearchAnchors
+from trialpath.services.gemini_planner import GeminiPlanner
+
+
+class TestGeminiSearchAnchorsGeneration:
+    """Test Gemini structured output for SearchAnchors generation."""
+
+    @pytest.fixture
+    def sample_profile(self):
+        return {
+            "patient_id": "P001",
+            "demographics": {"age": 52, "sex": "female"},
+            "diagnosis": {
+                "primary_condition": "Non-Small Cell Lung Cancer",
+                "histology": "adenocarcinoma",
+                "stage": "IVa",
+            },
+            "biomarkers": [
+                {"name": "EGFR", "result": "Exon 19 deletion"},
+            ],
+            "performance_status": {"scale": "ECOG", "value": 1},
+        }
+
+    @pytest.mark.asyncio
+    async def test_search_anchors_has_correct_condition(self, sample_profile):
+        """Generated SearchAnchors should reference NSCLC."""
+        with patch("google.genai.Client") as MockClient:
+            mock_response = MagicMock()
+            mock_response.text = SearchAnchors(
+                condition="Non-Small Cell Lung Cancer",
+                subtype="adenocarcinoma",
+                biomarkers=["EGFR exon 19 deletion"],
+                stage="IV",
+                age=52,
+                performance_status_max=1,
+            ).model_dump_json()
+
+            MockClient.return_value.models.generate_content = MagicMock(
+                return_value=mock_response
+            )
+
+            planner = GeminiPlanner()
+            anchors = await planner.generate_search_anchors(sample_profile)
+
+            assert "lung" in anchors.condition.lower() or "nsclc" in anchors.condition.lower()
+            assert anchors.age == 52
+
+    @pytest.mark.asyncio
+    async def test_search_anchors_includes_biomarkers(self, sample_profile):
+        """SearchAnchors should include patient biomarkers."""
+        with patch("google.genai.Client") as MockClient:
+            mock_response = MagicMock()
+            mock_response.text = SearchAnchors(
+                condition="NSCLC",
+                biomarkers=["EGFR exon 19 deletion"],
+            ).model_dump_json()
+
+            MockClient.return_value.models.generate_content = MagicMock(
+                return_value=mock_response
+            )
+
+            planner = GeminiPlanner()
+            anchors = await planner.generate_search_anchors(sample_profile)
+
+            assert len(anchors.biomarkers) > 0
+            assert any("EGFR" in b for b in anchors.biomarkers)
+
+    @pytest.mark.asyncio
+    async def test_search_anchors_json_schema_passed(self, sample_profile):
+        """Verify that Gemini is called with response_json_schema."""
+        with patch("google.genai.Client") as MockClient:
+            mock_response = MagicMock()
+            mock_response.text = SearchAnchors(condition="NSCLC").model_dump_json()
+
+            mock_generate = MagicMock(return_value=mock_response)
+            MockClient.return_value.models.generate_content = mock_generate
+
+            planner = GeminiPlanner()
+            await planner.generate_search_anchors(sample_profile)
+
+            call_args = mock_generate.call_args
+            config = call_args.kwargs.get("config", call_args[1].get("config", {}))
+            assert config.get("response_mime_type") == "application/json"
+            assert "response_json_schema" in config
+
+
+class TestGeminiEligibilityEvaluation:
+    """Test Gemini eligibility evaluation output."""
+
+    @pytest.mark.asyncio
+    async def test_ledger_has_all_required_fields(self):
+        """EligibilityLedger from Gemini should have patient_id, nct_id, assessment."""
+        mock_ledger = EligibilityLedger(
+            patient_id="P001",
+            nct_id="NCT01234567",
+            overall_assessment=OverallAssessment.UNCERTAIN,
+            criteria=[],
+            gaps=[],
+        )
+
+        assert mock_ledger.patient_id == "P001"
+        assert mock_ledger.nct_id == "NCT01234567"
+        assert mock_ledger.overall_assessment in OverallAssessment
+
+    @pytest.mark.asyncio
+    async def test_error_handling_invalid_json(self):
+        """Should raise error on invalid Gemini JSON response."""
+        with patch("google.genai.Client") as MockClient:
+            mock_response = MagicMock()
+            mock_response.text = "not valid json"
+
+            MockClient.return_value.models.generate_content = MagicMock(
+                return_value=mock_response
+            )
+
+            planner = GeminiPlanner()
+            with pytest.raises(Exception):
+                await planner.evaluate_eligibility({}, {}, None)

trialpath/tests/test_mcp.py

@@ -0,0 +1,134 @@
+"""TDD tests for ClinicalTrials MCP client."""
+from unittest.mock import AsyncMock, MagicMock, patch
+
+import pytest
+
+from trialpath.models.search_anchors import GeographyFilter, SearchAnchors, TrialFilters
+from trialpath.services.mcp_client import ClinicalTrialsMCPClient, MCPError
+
+
+class TestMCPClient:
+    """Test ClinicalTrials MCP client."""
+
+    @pytest.fixture
+    def client(self):
+        return ClinicalTrialsMCPClient(mcp_url="http://localhost:3000")
+
+    @pytest.fixture
+    def sample_anchors(self):
+        return SearchAnchors(
+            condition="Non-Small Cell Lung Cancer",
+            subtype="adenocarcinoma",
+            biomarkers=["EGFR exon 19 deletion"],
+            stage="IV",
+            age=52,
+            geography=GeographyFilter(country="United States"),
+            trial_filters=TrialFilters(
+                recruitment_status=["Recruiting"],
+                phase=["Phase 3"],
+            ),
+        )
+
+    def _mock_httpx(self, MockHTTP, response_data):
+        mock_response = MagicMock()
+        mock_response.json.return_value = response_data
+        mock_response.raise_for_status = MagicMock()
+
+        mock_client = AsyncMock()
+        mock_client.post.return_value = mock_response
+
+        mock_ctx = MagicMock()
+        mock_ctx.__aenter__ = AsyncMock(return_value=mock_client)
+        mock_ctx.__aexit__ = AsyncMock(return_value=None)
+        MockHTTP.return_value = mock_ctx
+        return mock_client
+
+    @pytest.mark.asyncio
+    async def test_search_builds_correct_query(self, client, sample_anchors):
+        """Search should combine condition, subtype, and biomarkers into query."""
+        with patch("httpx.AsyncClient") as MockHTTP:
+            mock_client = self._mock_httpx(MockHTTP, {"result": {"studies": []}})
+
+            await client.search(sample_anchors)
+
+            call_args = mock_client.post.call_args
+            body = call_args.kwargs.get("json", call_args[1].get("json", {}))
+            query = body["params"]["arguments"]["query"]
+
+            assert "Non-Small Cell Lung Cancer" in query
+            assert "adenocarcinoma" in query
+
+    @pytest.mark.asyncio
+    async def test_search_includes_country_filter(self, client, sample_anchors):
+        """Search should pass country as a parameter."""
+        with patch("httpx.AsyncClient") as MockHTTP:
+            mock_client = self._mock_httpx(MockHTTP, {"result": {"studies": []}})
+
+            await client.search(sample_anchors)
+
+            call_args = mock_client.post.call_args
+            body = call_args.kwargs.get("json", call_args[1].get("json", {}))
+            args = body["params"]["arguments"]
+
+            assert args.get("country") == "United States"
+
+    @pytest.mark.asyncio
+    async def test_search_includes_recruitment_status_filter(self, client, sample_anchors):
+        """Search should include recruitment status in filter expression."""
+        with patch("httpx.AsyncClient") as MockHTTP:
+            mock_client = self._mock_httpx(MockHTTP, {"result": {"studies": []}})
+
+            await client.search(sample_anchors)
+
+            call_args = mock_client.post.call_args
+            body = call_args.kwargs.get("json", call_args[1].get("json", {}))
+            filter_str = body["params"]["arguments"].get("filter", "")
+
+            assert "OverallStatus" in filter_str
+            assert "Recruiting" in filter_str
+
+    @pytest.mark.asyncio
+    async def test_get_study_by_nct_id(self, client):
+        """Should call get_study tool with correct NCT ID."""
+        with patch("httpx.AsyncClient") as MockHTTP:
+            self._mock_httpx(MockHTTP, {
+                "result": {
+                    "studies": [{"nctId": "NCT01234567", "title": "Test Trial"}]
+                }
+            })
+
+            result = await client.get_study("NCT01234567")
+            assert result["nctId"] == "NCT01234567"
+
+    @pytest.mark.asyncio
+    async def test_mcp_error_handling(self, client):
+        """Should raise MCPError on MCP server error response."""
+        with patch("httpx.AsyncClient") as MockHTTP:
+            self._mock_httpx(MockHTTP, {
+                "error": {"code": -32600, "message": "Invalid request"}
+            })
+
+            with pytest.raises(MCPError, match="Invalid request"):
+                await client.get_study("NCT00000000")
+
+    @pytest.mark.asyncio
+    async def test_find_eligible_passes_demographics(self, client):
+        """find_eligible should pass patient demographics correctly."""
+        with patch("httpx.AsyncClient") as MockHTTP:
+            mock_client = self._mock_httpx(MockHTTP, {
+                "result": {"eligibleStudies": [], "totalMatches": 0}
+            })
+
+            await client.find_eligible(
+                age=52, sex="Female",
+                conditions=["NSCLC"],
+                country="United States",
+            )
+
+            call_args = mock_client.post.call_args
+            body = call_args.kwargs.get("json", call_args[1].get("json", {}))
+            args = body["params"]["arguments"]
+
+            assert args["age"] == 52
+            assert args["sex"] == "Female"
+            assert args["conditions"] == ["NSCLC"]

trialpath/tests/test_medgemma.py

@@ -0,0 +1,82 @@
+"""TDD tests for MedGemma extraction service."""
+import pytest
+
+from trialpath.services.medgemma_extractor import MedGemmaExtractor
+
+
+class TestMedGemmaExtraction:
+    """Test MedGemma extraction pipeline."""
+
+    def test_parse_valid_json_output(self):
+        """Should parse well-formed JSON from MedGemma."""
+        extractor = MedGemmaExtractor.__new__(MedGemmaExtractor)
+
+        raw_output = """
+        {
+            "patient_id": "P001",
+            "diagnosis": {
+                "primary_condition": "Non-Small Cell Lung Cancer",
+                "histology": "adenocarcinoma",
+                "stage": "IVa"
+            },
+            "performance_status": {
+                "scale": "ECOG",
+                "value": 1,
+                "evidence": [{"doc_id": "clinic_1", "page": 2, "span_id": "s_17"}]
+            },
+            "biomarkers": [],
+            "unknowns": [
+                {"field": "EGFR", "reason": "No clear mention", "importance": "high"}
+            ]
+        }
+        """
+
+        result = extractor._parse_profile(raw_output, {"age": 52, "sex": "female"})
+        assert result["diagnosis"]["primary_condition"] == "Non-Small Cell Lung Cancer"
+        assert result["demographics"]["age"] == 52
+
+    def test_parse_json_in_code_block(self):
+        """Should extract JSON from markdown code blocks."""
+        extractor = MedGemmaExtractor.__new__(MedGemmaExtractor)
+
+        raw_output = """Here is the extracted data:
+        ```json
+        {"patient_id": "P001", "diagnosis": {"primary_condition": "NSCLC", "stage": "IV"}}
+        ```
+        """
+
+        result = extractor._parse_profile(raw_output, {})
+        assert result["diagnosis"]["primary_condition"] == "NSCLC"
+
+    def test_parse_invalid_output_raises(self):
+        """Should raise ValueError on unparseable output."""
+        extractor = MedGemmaExtractor.__new__(MedGemmaExtractor)
+
+        with pytest.raises(ValueError, match="Could not parse"):
+            extractor._parse_profile("This is not JSON at all.", {})
+
+    def test_system_prompt_mentions_oncology(self):
+        """System prompt should reference oncology expertise."""
+        extractor = MedGemmaExtractor.__new__(MedGemmaExtractor)
+        prompt = extractor._system_prompt()
+        assert "oncology" in prompt.lower()
+
+    def test_extraction_prompt_includes_all_fields(self):
+        """Extraction prompt should request all PatientProfile fields."""
+        extractor = MedGemmaExtractor.__new__(MedGemmaExtractor)
+        prompt = extractor._build_extraction_prompt({"age": 52, "sex": "female"})
+
+        required_fields = [
+            "diagnosis", "performance_status", "biomarkers",
+            "key_labs", "treatments", "comorbidities",
+            "imaging_summary", "unknowns",
+        ]
+        for field in required_fields:
+            assert field in prompt
+
+    def test_extraction_prompt_includes_metadata(self):
+        """Extraction prompt should include provided metadata."""
+        extractor = MedGemmaExtractor.__new__(MedGemmaExtractor)
+        prompt = extractor._build_extraction_prompt({"age": 65, "sex": "male"})
+        assert "65" in prompt
+        assert "male" in prompt