Initial PoC codebase

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

CLAUDE.md

@@ -4,58 +4,50 @@ This file provides guidance to Claude Code (claude.ai/code) when working with co
 
 ## Project Overview
 
-TrialPath is an AI-powered clinical trial matching system for NSCLC (Non-Small Cell Lung Cancer) patients. It is currently in **pre-implementation design phase** — only design documents exist, no source code yet.
+TrialPath is an AI-powered clinical trial matching system for NSCLC (Non-Small Cell Lung Cancer) patients. Currently in **PoC phase** — models, service stubs, and UI with mock data are implemented; live AI integrations are pending.
 
 **Core idea:** Help patients understand which clinical trials they may qualify for, transform "rejection" into "actionable next steps" via gap analysis.
 
-## Design Documents
+## Architecture
 
-- `Trialpath PRD.md` — Product requirements, success metrics, HAI-DEF submission plan
-- `TrialPath AI Synergy in Digital Health Trials.md` — Technical architecture, data contracts, Parlant workflow design
+See `architecture/overview.md` for full architecture diagram, data flow, component details, and implementation status.
 
-## Architecture (5 Components)
+**5 Components**: Streamlit UI → Parlant Orchestrator → MedGemma 4B (extraction) + Gemini 3 Pro (planning) + ClinicalTrials MCP Server (search)
 
-1. **UI & Orchestrator** — Streamlit/FastAPI app embedding Parlant engine
-2. **Parlant Agent + Journey** — Single agent (`patient_trial_copilot`) with 5 states: `INGEST` → `PRESCREEN` → `VALIDATE_TRIALS` → `GAP_FOLLOWUP` → `SUMMARY`
-3. **MedGemma 4B** (HF endpoint) — Multimodal extraction from PDFs/images → `PatientProfile` + evidence spans
-4. **Gemini 3 Pro** — LLM planner: generates `SearchAnchors` from profile, reranks trials, orchestrates criterion evaluation
-5. **ClinicalTrials MCP Server** (existing, not custom) — Wraps ClinicalTrials.gov REST API v2
+**5 Data Contracts** (Pydantic v2 in `trialpath/models/`): `PatientProfile`, `SearchAnchors`, `TrialCandidate`, `EligibilityLedger`, `SearchLog`
 
-## Key Design Decisions
+## Project Structure
 
-- **No vector DB / RAG** — Uses agentic search via ClinicalTrials.gov API with iterative query refinement
-- **Reuse existing MCP** — Don't build custom trial search; use off-the-shelf ClinicalTrials MCP servers
-- **Two-stage clinical screening** — Mirrors real-world: prescreen (minimal dataset) → validation (full criterion-by-criterion)
-- **Evidence-linked** — Every decision must cite source doc/page/span
-- **Gap analysis as core differentiator** — "You'd qualify IF you had X" rather than just "No match"
-
-## Data Contracts (JSON Schemas)
-
-Four core contracts defined in the tech design doc (section 4):
-- **PatientProfile v1** — MedGemma output with demographics, diagnosis, biomarkers, labs, treatments, unknowns
-- **SearchAnchors v1** — Gemini-generated query params for MCP search
-- **TrialCandidate v1** — Normalized MCP search results
-- **EligibilityLedger v1** — Per-trial criterion-level assessment with evidence pointers and gaps
-
-## Planned Code Structure
-
-From PRD deliverables section:
 ```
-data/generate_synthetic_patients.py
-data/generate_noisy_pdfs.py
-matching/medgemma_extractor.py
-matching/agentic_search.py          # Parlant + Gemini + MCP
-evaluation/run_trec_benchmark.py
+trialpath/                  # Backend module
+  models/                   # 5 Pydantic v2 data contracts (implemented)
+  services/                 # 4 service stubs: medgemma, gemini, mcp, parlant
+  agent/                    # Parlant journey logic (not yet implemented)
+  tests/                    # Backend TDD tests (37+ model, 33 service)
+app/                        # Streamlit frontend
+  pages/                    # 5-page journey (upload → profile → matching → gaps → summary)
+  components/               # 6 reusable widgets
+  services/                 # State manager, parlant client, mock data
+  tests/                    # Frontend TDD tests (30+ component, 5 page)
+tests/                      # Integration tests (18 tests)
+architecture/               # Architecture documentation
+docs/                       # Design docs and TDD guides
 ```
 
-## Planned Tech Stack
+## Documents
+
+- `docs/Trialpath PRD.md` — Product requirements, success metrics, HAI-DEF submission plan
+- `docs/TrialPath AI technical design.md` — Technical architecture, data contracts, Parlant workflow
+- `docs/tdd-guide-*.md` — TDD implementation guides (backend, frontend, data/eval)
+- `architecture/overview.md` — Architecture overview, data flow, component status
+
+## Tech Stack
 
-- Python (Streamlit or FastAPI)
-- Google Gemini 3 Pro (orchestration)
-- MedGemma 4B via Hugging Face endpoint (multimodal extraction)
-- Parlant (agentic workflow engine)
-- Synthea FHIR (synthetic patient generation)
-- TREC Clinical Trials Track 2021/2022 (benchmarking)
+- Python 3.11+ (Streamlit + Pydantic v2)
+- Google Gemini 3 Pro (orchestration) — stubbed
+- MedGemma 4B via Hugging Face endpoint (multimodal extraction) — stubbed
+- Parlant (agentic workflow engine) — client ready, agent pending
+- ClinicalTrials MCP Server (ClinicalTrials.gov API v2) — client ready
 
 ## Success Targets
 

architecture/overview.md

@@ -0,0 +1,119 @@
+# TrialPath Architecture Overview
+
+## System Architecture
+
+TrialPath is composed of 5 core components connected via async HTTP/JSON-RPC:
+
+```
+                        +---------------------+
+                        |   Streamlit UI      |
+                        |   (5-page journey)  |
+                        +----------+----------+
+                                   |
+                        +----------v----------+
+                        |  Parlant Engine      |
+                        |  (orchestrator)      |
+                        |  patient_trial_copilot|
+                        +----+-----+-----+----+
+                             |     |     |
+                +------------+  +--+--+  +------------+
+                |               |     |               |
+       +--------v-------+ +----v----+ +------v--------+
+       | MedGemma 4B    | | Gemini  | | ClinicalTrials|
+       | (HF endpoint)  | | 3 Pro   | | MCP Server    |
+       | extraction     | | planner | | (API v2)      |
+       +----------------+ +---------+ +---------------+
+```
+
+## Component Details
+
+### 1. UI & Orchestrator (Streamlit)
+
+- **Location**: `app/`, `streamlit_app.py`
+- **Role**: 5-page patient journey matching Parlant states
+- **Pages**: Upload -> Profile Review -> Trial Matching -> Gap Analysis -> Summary
+- **Components**: `app/components/` (6 reusable widgets)
+- **State**: `app/services/state_manager.py` (session-based journey state)
+
+### 2. Parlant Agent + Journey
+
+- **Location**: `trialpath/agent/` (not yet implemented)
+- **Role**: Single agent `patient_trial_copilot` with 5 states
+- **States**: `INGEST` -> `PRESCREEN` -> `VALIDATE_TRIALS` -> `GAP_FOLLOWUP` -> `SUMMARY`
+- **Client**: `trialpath/services/parlant_client.py` (async REST wrapper)
+
+### 3. MedGemma 4B (Multimodal Extraction)
+
+- **Location**: `trialpath/services/medgemma_extractor.py`
+- **Role**: Extract structured `PatientProfile` from PDFs/images
+- **Output**: Demographics, diagnosis, biomarkers, labs, treatments, unknowns + evidence spans
+- **Status**: Prompt templates ready, HF endpoint integration pending
+
+### 4. Gemini 3 Pro (LLM Planner)
+
+- **Location**: `trialpath/services/gemini_planner.py`
+- **Role**: Generate `SearchAnchors` from profile, evaluate eligibility criteria, produce `EligibilityLedger`
+- **Output**: Structured JSON via google-genai client
+- **Status**: Prompt templates and structured output calls stubbed
+
+### 5. ClinicalTrials MCP Server
+
+- **Location**: `trialpath/services/mcp_client.py`
+- **Role**: JSON-RPC client wrapping ClinicalTrials.gov REST API v2
+- **Tools**: `search_studies`, `get_study`, `find_eligible`, `compare_studies`
+- **Status**: Client wrapper implemented, needs running MCP server
+
+## Data Flow
+
+```
+Patient Document (PDF/image)
+        |
+        v
+  [MedGemma 4B] -- extracts --> PatientProfile v1
+        |
+        v
+  [Gemini 3 Pro] -- generates --> SearchAnchors v1
+        |
+        v
+  [MCP Client] -- queries --> ClinicalTrials.gov API
+        |
+        v
+  [MCP Client] -- returns --> TrialCandidate v1 (list)
+        |
+        v
+  [Gemini 3 Pro] -- evaluates --> EligibilityLedger v1 (per trial)
+        |                          (criterion-level verdicts + gaps)
+        v
+  [UI Summary] -- renders --> Doctor Packet (JSON/Markdown)
+```
+
+## Data Contracts
+
+All defined as Pydantic v2 models in `trialpath/models/`:
+
+| Contract | File | Purpose |
+|----------|------|---------|
+| `PatientProfile` | `patient_profile.py` | MedGemma output: 11 fields (demographics, diagnosis, biomarkers, labs, treatments, unknowns) |
+| `SearchAnchors` | `search_anchors.py` | Gemini-generated query params for MCP search with relaxation order |
+| `TrialCandidate` | `trial_candidate.py` | Normalized MCP search results (NCT ID, phase, locations, eligibility text) |
+| `EligibilityLedger` | `eligibility_ledger.py` | Per-trial criterion assessment with traffic-light status + gap tracking |
+| `SearchLog` | `search_log.py` | Iterative query refinement tracking (max 5 rounds) |
+
+## Current Implementation Status
+
+| Component | Models | Service Stub | UI | Tests | Live Integration |
+|-----------|--------|-------------|-----|-------|-----------------|
+| Data Models | Done | - | - | 37 tests | - |
+| MedGemma | Done | Prompts ready | Mock | 5 tests | Pending |
+| Gemini | Done | Prompts ready | Mock | 7 tests | Pending |
+| MCP Client | Done | Wrapper done | Mock | 6 tests | Pending |
+| Parlant | Done | Client done | Mock | 15 tests | Pending |
+| Streamlit UI | - | - | 5 pages, 6 components | 30+ tests | Mock data |
+
+## Key Design Decisions
+
+- **No vector DB / RAG**: Agentic search via ClinicalTrials.gov API with iterative query refinement
+- **Reuse existing MCP**: Off-the-shelf ClinicalTrials MCP server, no custom search
+- **Two-stage screening**: Prescreen (minimal dataset) -> Validation (full criterion-by-criterion)
+- **Evidence-linked**: Every decision cites source doc/page/span
+- **Gap analysis**: "You'd qualify IF you had X" rather than just "No match"

trialpath/services/parlant_client.py

@@ -0,0 +1,94 @@
+"""Async Parlant REST API client for TrialPath backend services."""
+
+from __future__ import annotations
+
+from typing import Optional
+
+import httpx
+
+_DEFAULT_BASE_URL = "http://localhost:8800"
+_DEFAULT_TIMEOUT = 65.0  # > long-poll wait_for_data default
+
+
+class ParlantClient:
+    """Async wrapper around the Parlant REST API."""
+
+    def __init__(
+        self,
+        base_url: str = _DEFAULT_BASE_URL,
+        *,
+        transport: Optional[httpx.AsyncBaseTransport] = None,
+        timeout: float = _DEFAULT_TIMEOUT,
+    ) -> None:
+        self.base_url = base_url
+        self._http = httpx.AsyncClient(
+            base_url=base_url,
+            timeout=timeout,
+            transport=transport,
+        )
+
+    # ------ context manager ------
+
+    async def __aenter__(self) -> ParlantClient:
+        return self
+
+    async def __aexit__(self, exc_type, exc_val, exc_tb) -> None:
+        await self.close()
+
+    # ------ sessions ------
+
+    async def create_session(
+        self, agent_id: str, customer_id: Optional[str] = None
+    ) -> str:
+        """Create a Parlant session and return the session_id."""
+        payload: dict = {"agent_id": agent_id}
+        if customer_id:
+            payload["customer_id"] = customer_id
+        resp = await self._http.post("/sessions", json=payload)
+        resp.raise_for_status()
+        return resp.json()["session_id"]
+
+    async def get_session_status(self, session_id: str) -> dict:
+        """Fetch session metadata."""
+        resp = await self._http.get(f"/sessions/{session_id}")
+        resp.raise_for_status()
+        return resp.json()
+
+    # ------ events ------
+
+    async def send_message(self, session_id: str, message: str) -> dict:
+        """Send a customer message event to a session."""
+        resp = await self._http.post(
+            f"/sessions/{session_id}/events",
+            json={"kind": "message", "source": "customer", "message": message},
+        )
+        resp.raise_for_status()
+        return resp.json()
+
+    async def poll_events(
+        self,
+        session_id: str,
+        min_offset: int = 0,
+        wait_seconds: int = 60,
+    ) -> list[dict]:
+        """Poll for new events starting from *min_offset*."""
+        resp = await self._http.get(
+            f"/sessions/{session_id}/events",
+            params={"min_offset": min_offset, "wait_for_data": wait_seconds},
+        )
+        resp.raise_for_status()
+        return resp.json()
+
+    # ------ agents ------
+
+    async def list_agents(self) -> list[dict]:
+        """List available agents."""
+        resp = await self._http.get("/agents")
+        resp.raise_for_status()
+        return resp.json()
+
+    # ------ lifecycle ------
+
+    async def close(self) -> None:
+        """Close the underlying HTTP client."""
+        await self._http.aclose()

trialpath/tests/test_parlant.py

@@ -0,0 +1,230 @@
+"""Tests for trialpath.services.parlant_client — async Parlant REST wrapper."""
+
+import httpx
+import pytest
+
+from trialpath.services.parlant_client import ParlantClient
+
+
+def _mock_transport(handler):
+    """Create an httpx.MockTransport from a handler function."""
+    return httpx.MockTransport(handler)
+
+
+# ---------- create_session ----------
+
+
+class TestCreateSession:
+    @pytest.mark.asyncio
+    async def test_sends_post_and_returns_session_id(self):
+        async def handler(request: httpx.Request) -> httpx.Response:
+            assert request.method == "POST"
+            assert request.url.path == "/sessions"
+            import json
+
+            body = json.loads(request.content)
+            assert body["agent_id"] == "agent-123"
+            return httpx.Response(200, json={"session_id": "sess-abc"})
+
+        client = ParlantClient(
+            base_url="http://test", transport=_mock_transport(handler)
+        )
+        result = await client.create_session("agent-123")
+        assert result == "sess-abc"
+        await client.close()
+
+    @pytest.mark.asyncio
+    async def test_passes_customer_id_when_provided(self):
+        async def handler(request: httpx.Request) -> httpx.Response:
+            import json
+
+            body = json.loads(request.content)
+            assert body["customer_id"] == "cust-456"
+            return httpx.Response(200, json={"session_id": "sess-def"})
+
+        client = ParlantClient(
+            base_url="http://test", transport=_mock_transport(handler)
+        )
+        result = await client.create_session("agent-123", customer_id="cust-456")
+        assert result == "sess-def"
+        await client.close()
+
+    @pytest.mark.asyncio
+    async def test_raises_on_server_error(self):
+        async def handler(request: httpx.Request) -> httpx.Response:
+            return httpx.Response(500, json={"error": "internal"})
+
+        client = ParlantClient(
+            base_url="http://test", transport=_mock_transport(handler)
+        )
+        with pytest.raises(httpx.HTTPStatusError):
+            await client.create_session("agent-123")
+        await client.close()
+
+
+# ---------- send_message ----------
+
+
+class TestSendMessage:
+    @pytest.mark.asyncio
+    async def test_sends_correct_payload(self):
+        async def handler(request: httpx.Request) -> httpx.Response:
+            assert request.method == "POST"
+            assert "/sessions/sess-1/events" in request.url.path
+            import json
+
+            body = json.loads(request.content)
+            assert body["kind"] == "message"
+            assert body["source"] == "customer"
+            assert body["message"] == "Hello"
+            return httpx.Response(200, json={"event_id": "evt-1", "offset": 0})
+
+        client = ParlantClient(
+            base_url="http://test", transport=_mock_transport(handler)
+        )
+        result = await client.send_message("sess-1", "Hello")
+        assert result["event_id"] == "evt-1"
+        await client.close()
+
+    @pytest.mark.asyncio
+    async def test_raises_on_not_found(self):
+        async def handler(request: httpx.Request) -> httpx.Response:
+            return httpx.Response(404, json={"error": "session not found"})
+
+        client = ParlantClient(
+            base_url="http://test", transport=_mock_transport(handler)
+        )
+        with pytest.raises(httpx.HTTPStatusError):
+            await client.send_message("bad-sess", "Hello")
+        await client.close()
+
+
+# ---------- poll_events ----------
+
+
+class TestPollEvents:
+    @pytest.mark.asyncio
+    async def test_fetches_with_offset_param(self):
+        async def handler(request: httpx.Request) -> httpx.Response:
+            assert request.method == "GET"
+            assert "/sessions/sess-1/events" in request.url.path
+            assert request.url.params["min_offset"] == "5"
+            return httpx.Response(
+                200,
+                json=[
+                    {"offset": 5, "kind": "message", "source": "ai_agent", "message": "Hi"},
+                    {"offset": 6, "kind": "status", "data": "ready"},
+                ],
+            )
+
+        client = ParlantClient(
+            base_url="http://test", transport=_mock_transport(handler)
+        )
+        events = await client.poll_events("sess-1", min_offset=5)
+        assert len(events) == 2
+        assert events[0]["offset"] == 5
+        await client.close()
+
+    @pytest.mark.asyncio
+    async def test_default_offset_is_zero(self):
+        async def handler(request: httpx.Request) -> httpx.Response:
+            assert request.url.params["min_offset"] == "0"
+            return httpx.Response(200, json=[])
+
+        client = ParlantClient(
+            base_url="http://test", transport=_mock_transport(handler)
+        )
+        events = await client.poll_events("sess-1")
+        assert events == []
+        await client.close()
+
+    @pytest.mark.asyncio
+    async def test_passes_wait_seconds(self):
+        async def handler(request: httpx.Request) -> httpx.Response:
+            assert request.url.params["wait_for_data"] == "30"
+            return httpx.Response(200, json=[])
+
+        client = ParlantClient(
+            base_url="http://test", transport=_mock_transport(handler)
+        )
+        await client.poll_events("sess-1", wait_seconds=30)
+        await client.close()
+
+
+# ---------- get_session_status ----------
+
+
+class TestGetSessionStatus:
+    @pytest.mark.asyncio
+    async def test_returns_session_info(self):
+        async def handler(request: httpx.Request) -> httpx.Response:
+            assert request.method == "GET"
+            assert request.url.path == "/sessions/sess-1"
+            return httpx.Response(
+                200,
+                json={
+                    "session_id": "sess-1",
+                    "agent_id": "agent-1",
+                    "status": "active",
+                },
+            )
+
+        client = ParlantClient(
+            base_url="http://test", transport=_mock_transport(handler)
+        )
+        status = await client.get_session_status("sess-1")
+        assert status["session_id"] == "sess-1"
+        assert status["status"] == "active"
+        await client.close()
+
+
+# ---------- list_agents ----------
+
+
+class TestListAgents:
+    @pytest.mark.asyncio
+    async def test_returns_agents_list(self):
+        async def handler(request: httpx.Request) -> httpx.Response:
+            assert request.method == "GET"
+            assert request.url.path == "/agents"
+            return httpx.Response(
+                200,
+                json=[
+                    {"agent_id": "agent-1", "name": "patient_trial_copilot"},
+                ],
+            )
+
+        client = ParlantClient(
+            base_url="http://test", transport=_mock_transport(handler)
+        )
+        agents = await client.list_agents()
+        assert len(agents) == 1
+        assert agents[0]["agent_id"] == "agent-1"
+        await client.close()
+
+
+# ---------- lifecycle ----------
+
+
+class TestLifecycle:
+    @pytest.mark.asyncio
+    async def test_client_close(self):
+        async def handler(request: httpx.Request) -> httpx.Response:
+            return httpx.Response(200, json={})
+
+        client = ParlantClient(
+            base_url="http://test", transport=_mock_transport(handler)
+        )
+        await client.close()
+        assert client._http.is_closed
+
+    @pytest.mark.asyncio
+    async def test_async_context_manager(self):
+        async def handler(request: httpx.Request) -> httpx.Response:
+            return httpx.Response(200, json={"session_id": "sess-ctx"})
+
+        transport = _mock_transport(handler)
+        async with ParlantClient(base_url="http://test", transport=transport) as client:
+            result = await client.create_session("agent-1")
+            assert result == "sess-ctx"
+        assert client._http.is_closed