fix: cache service instances in Parlant tools to avoid per-call overhead

Replace per-call instantiation of MedGemmaExtractor, GeminiPlanner, and
ClinicalTrialsMCPClient with lazy module-level singletons via _get_*()
helpers. Prevents hundreds of redundant client initializations during
evaluate_trial_eligibility's inner criterion loop.

Add autouse fixture in test_tools.py to reset singletons between tests.

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

trialpath/agent/tools.py

@@ -11,6 +11,49 @@ from trialpath.config import (
     MEDGEMMA_ENDPOINT_URL,
 )
 
+# ---------------------------------------------------------------------------
+# Lazy singletons — one instance per service, reused across tool calls.
+# ---------------------------------------------------------------------------
+
+_extractor = None
+_planner = None
+_mcp_client = None
+
+
+def _get_extractor():
+    global _extractor
+    if _extractor is None:
+        from trialpath.services.medgemma_extractor import MedGemmaExtractor
+
+        _extractor = MedGemmaExtractor(
+            endpoint_url=MEDGEMMA_ENDPOINT_URL,
+            hf_token=HF_TOKEN,
+        )
+    return _extractor
+
+
+def _get_planner():
+    global _planner
+    if _planner is None:
+        from trialpath.services.gemini_planner import GeminiPlanner
+
+        _planner = GeminiPlanner(model=GEMINI_MODEL, api_key=GEMINI_API_KEY)
+    return _planner
+
+
+def _get_mcp_client():
+    global _mcp_client
+    if _mcp_client is None:
+        from trialpath.services.mcp_client import ClinicalTrialsMCPClient
+
+        _mcp_client = ClinicalTrialsMCPClient(mcp_url=MCP_URL)
+    return _mcp_client
+
+
+# ---------------------------------------------------------------------------
+# Tools
+# ---------------------------------------------------------------------------
+
 
 @tool
 async def extract_patient_profile(
@@ -25,12 +68,7 @@ async def extract_patient_profile(
         document_urls: JSON list of document file paths.
         metadata: JSON object with known patient metadata (age, sex).
     """
-    from trialpath.services.medgemma_extractor import MedGemmaExtractor
-
-    extractor = MedGemmaExtractor(
-        endpoint_url=MEDGEMMA_ENDPOINT_URL,
-        hf_token=HF_TOKEN,
-    )
+    extractor = _get_extractor()
     urls = json.loads(document_urls)
     meta = json.loads(metadata)
     profile = await extractor.extract(urls, meta)
@@ -52,9 +90,7 @@ async def generate_search_anchors(
         context: Parlant tool context.
         patient_profile: JSON string of PatientProfile data.
     """
-    from trialpath.services.gemini_planner import GeminiPlanner
-
-    planner = GeminiPlanner(model=GEMINI_MODEL, api_key=GEMINI_API_KEY)
+    planner = _get_planner()
     profile = json.loads(patient_profile)
     anchors = await planner.generate_search_anchors(profile)
 
@@ -76,12 +112,13 @@ async def search_clinical_trials(
         search_anchors: JSON string of SearchAnchors data.
     """
     from trialpath.models.search_anchors import SearchAnchors
-    from trialpath.services.mcp_client import ClinicalTrialsMCPClient
 
-    client = ClinicalTrialsMCPClient(mcp_url=MCP_URL)
+    client = _get_mcp_client()
     anchors = SearchAnchors.model_validate(json.loads(search_anchors))
     raw_studies = await client.search(anchors)
 
+    from trialpath.services.mcp_client import ClinicalTrialsMCPClient
+
     trials = [
         ClinicalTrialsMCPClient.normalize_trial(s).model_dump()
         for s in raw_studies
@@ -107,9 +144,8 @@ async def refine_search_query(
         result_count: Number of results from last search.
     """
     from trialpath.models.search_anchors import SearchAnchors
-    from trialpath.services.gemini_planner import GeminiPlanner
 
-    planner = GeminiPlanner(model=GEMINI_MODEL, api_key=GEMINI_API_KEY)
+    planner = _get_planner()
     anchors = SearchAnchors.model_validate(json.loads(search_anchors))
     refined = await planner.refine_search(anchors, int(result_count))
 
@@ -133,9 +169,8 @@ async def relax_search_query(
         result_count: Number of results from last search.
     """
     from trialpath.models.search_anchors import SearchAnchors
-    from trialpath.services.gemini_planner import GeminiPlanner
 
-    planner = GeminiPlanner(model=GEMINI_MODEL, api_key=GEMINI_API_KEY)
+    planner = _get_planner()
     anchors = SearchAnchors.model_validate(json.loads(search_anchors))
     relaxed = await planner.relax_search(anchors, int(result_count))
 
@@ -160,17 +195,11 @@ async def evaluate_trial_eligibility(
         patient_profile: JSON string of PatientProfile data.
         trial_candidate: JSON string of TrialCandidate data.
     """
-    from trialpath.services.gemini_planner import GeminiPlanner
-    from trialpath.services.medgemma_extractor import MedGemmaExtractor
-
     profile = json.loads(patient_profile)
     trial = json.loads(trial_candidate)
 
-    planner = GeminiPlanner(model=GEMINI_MODEL, api_key=GEMINI_API_KEY)
-    extractor = MedGemmaExtractor(
-        endpoint_url=MEDGEMMA_ENDPOINT_URL,
-        hf_token=HF_TOKEN,
-    )
+    planner = _get_planner()
+    extractor = _get_extractor()
 
     # Step 1: Slice criteria into atomic items
     criteria = await planner.slice_criteria(trial)
@@ -210,9 +239,7 @@ async def analyze_gaps(
         patient_profile: JSON string of PatientProfile data.
         eligibility_ledgers: JSON list of EligibilityLedger data.
     """
-    from trialpath.services.gemini_planner import GeminiPlanner
-
-    planner = GeminiPlanner(model=GEMINI_MODEL, api_key=GEMINI_API_KEY)
+    planner = _get_planner()
     profile = json.loads(patient_profile)
     ledgers = json.loads(eligibility_ledgers)
     gaps = await planner.analyze_gaps(profile, ledgers)

trialpath/tests/test_tools.py

@@ -4,6 +4,7 @@ from unittest.mock import AsyncMock, MagicMock, patch
 
 import pytest
 
+import trialpath.agent.tools as tools_module
 from trialpath.agent.tools import (
     ALL_TOOLS,
     analyze_gaps,
@@ -16,6 +17,18 @@ from trialpath.agent.tools import (
 )
 
 
+@pytest.fixture(autouse=True)
+def _reset_singletons():
+    """Reset cached service singletons between tests."""
+    tools_module._extractor = None
+    tools_module._planner = None
+    tools_module._mcp_client = None
+    yield
+    tools_module._extractor = None
+    tools_module._planner = None
+    tools_module._mcp_client = None
+
+
 @pytest.fixture
 def mock_context():
     return MagicMock()