feat: configure Parlant guidelines

Add 11 guidelines across 5 journey phases plus 3 global guidelines.
Each has condition/action text and tool associations. Includes INGEST
extraction, PRESCREEN search/refine/relax, VALIDATE_TRIALS evaluation,
GAP_FOLLOWUP analysis, SUMMARY generation, and medical disclaimer.

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

trialpath/agent/guidelines.py

@@ -0,0 +1,138 @@
+"""Parlant guideline configuration for the TrialPath agent."""
+from parlant.sdk import Agent, Guideline
+
+from trialpath.agent.tools import (
+    analyze_gaps,
+    evaluate_trial_eligibility,
+    extract_patient_profile,
+    generate_search_anchors,
+    refine_search_query,
+    relax_search_query,
+    search_clinical_trials,
+)
+
+GUIDELINE_SPECS: list[dict] = [
+    # INGEST guidelines
+    {
+        "condition": "the patient uploads medical documents",
+        "action": (
+            "Extract a structured patient profile from the uploaded documents "
+            "using the extract_patient_profile tool"
+        ),
+        "tools": [extract_patient_profile],
+        "phase": "INGEST",
+    },
+    {
+        "condition": "the extracted patient profile is missing critical data like stage or ECOG",
+        "action": (
+            "Ask the patient to provide the missing critical information "
+            "or upload additional documents"
+        ),
+        "tools": [],
+        "phase": "INGEST",
+    },
+    # PRESCREEN guidelines
+    {
+        "condition": "the patient profile is confirmed and complete",
+        "action": (
+            "Generate search anchors from the patient profile and search "
+            "for matching clinical trials using generate_search_anchors "
+            "then search_clinical_trials"
+        ),
+        "tools": [generate_search_anchors, search_clinical_trials],
+        "phase": "PRESCREEN",
+    },
+    {
+        "condition": "the trial search returns more than 50 results",
+        "action": (
+            "Refine the search query to reduce the result set "
+            "using the refine_search_query tool"
+        ),
+        "tools": [refine_search_query],
+        "phase": "PRESCREEN",
+    },
+    {
+        "condition": "the trial search returns 0 results",
+        "action": (
+            "Relax the search query to broaden the result set "
+            "using the relax_search_query tool"
+        ),
+        "tools": [relax_search_query],
+        "phase": "PRESCREEN",
+    },
+    # VALIDATE_TRIALS guideline
+    {
+        "condition": "there are trial candidates to evaluate",
+        "action": (
+            "Evaluate each trial candidate's eligibility using the "
+            "evaluate_trial_eligibility tool with dual-model approach"
+        ),
+        "tools": [evaluate_trial_eligibility],
+        "phase": "VALIDATE_TRIALS",
+    },
+    # GAP_FOLLOWUP guideline
+    {
+        "condition": "eligibility evaluation reveals unknown criteria or gaps",
+        "action": (
+            "Analyze gaps across all evaluated trials and present actionable "
+            "next steps using the analyze_gaps tool"
+        ),
+        "tools": [analyze_gaps],
+        "phase": "GAP_FOLLOWUP",
+    },
+    # SUMMARY guideline
+    {
+        "condition": "all trials have been evaluated and gaps analyzed",
+        "action": (
+            "Generate a comprehensive summary report with eligible, uncertain, "
+            "and ineligible trial counts plus a doctor packet for export"
+        ),
+        "tools": [],
+        "phase": "SUMMARY",
+    },
+    # Global guidelines
+    {
+        "condition": "the patient asks about a specific NCT trial by ID",
+        "action": (
+            "Look up the specific trial using the search_clinical_trials tool "
+            "with the provided NCT ID"
+        ),
+        "tools": [search_clinical_trials],
+        "phase": "GLOBAL",
+    },
+    {
+        "condition": "the patient seems confused or asks for help",
+        "action": (
+            "Explain the current step in the journey, what data is needed, "
+            "and what will happen next in simple, empathetic language"
+        ),
+        "tools": [],
+        "phase": "GLOBAL",
+    },
+    {
+        "condition": "the conversation involves medical information or clinical decisions",
+        "action": (
+            "Include a disclaimer that this tool is for informational purposes only "
+            "and does not constitute medical advice. Recommend consulting with "
+            "their healthcare provider"
+        ),
+        "tools": [],
+        "phase": "GLOBAL",
+    },
+]
+
+
+def configure_guidelines(agent: Agent) -> list[Guideline]:
+    """Configure all guidelines on the given agent.
+
+    Returns the list of created Guideline objects.
+    """
+    guidelines = []
+    for spec in GUIDELINE_SPECS:
+        guideline = agent.create_guideline(
+            condition=spec["condition"],
+            action=spec["action"],
+            tools=spec["tools"],
+        )
+        guidelines.append(guideline)
+    return guidelines

trialpath/tests/test_guidelines.py

@@ -0,0 +1,92 @@
+"""TDD tests for Parlant guideline configuration."""
+from unittest.mock import MagicMock, call
+
+import pytest
+
+from trialpath.agent.guidelines import GUIDELINE_SPECS, configure_guidelines
+
+
+class TestGuidelineConfiguration:
+    """Test guideline setup."""
+
+    @pytest.fixture
+    def mock_agent(self):
+        agent = MagicMock()
+        agent.create_guideline.return_value = MagicMock()
+        return agent
+
+    def test_correct_number_of_guidelines(self, mock_agent):
+        """Should create exactly 11 guidelines."""
+        guidelines = configure_guidelines(mock_agent)
+        assert len(guidelines) == 11
+        assert mock_agent.create_guideline.call_count == 11
+
+    def test_each_guideline_has_condition_and_action(self):
+        """Each spec should have condition and action strings."""
+        for spec in GUIDELINE_SPECS:
+            assert "condition" in spec
+            assert "action" in spec
+            assert isinstance(spec["condition"], str)
+            assert isinstance(spec["action"], str)
+            assert len(spec["condition"]) > 10
+            assert len(spec["action"]) > 10
+
+    def test_ingest_guidelines_count(self):
+        """Should have 2 INGEST phase guidelines."""
+        ingest = [s for s in GUIDELINE_SPECS if s["phase"] == "INGEST"]
+        assert len(ingest) == 2
+
+    def test_prescreen_guidelines_count(self):
+        """Should have 3 PRESCREEN phase guidelines."""
+        prescreen = [s for s in GUIDELINE_SPECS if s["phase"] == "PRESCREEN"]
+        assert len(prescreen) == 3
+
+    def test_validate_trials_guidelines_count(self):
+        """Should have 1 VALIDATE_TRIALS guideline."""
+        validate = [s for s in GUIDELINE_SPECS if s["phase"] == "VALIDATE_TRIALS"]
+        assert len(validate) == 1
+
+    def test_gap_followup_guidelines_count(self):
+        """Should have 1 GAP_FOLLOWUP guideline."""
+        gap = [s for s in GUIDELINE_SPECS if s["phase"] == "GAP_FOLLOWUP"]
+        assert len(gap) == 1
+
+    def test_summary_guidelines_count(self):
+        """Should have 1 SUMMARY guideline."""
+        summary = [s for s in GUIDELINE_SPECS if s["phase"] == "SUMMARY"]
+        assert len(summary) == 1
+
+    def test_global_guidelines_count(self):
+        """Should have 3 global guidelines."""
+        global_g = [s for s in GUIDELINE_SPECS if s["phase"] == "GLOBAL"]
+        assert len(global_g) == 3
+
+    def test_tool_associations(self):
+        """Guidelines with tools should reference correct tool entries."""
+        from parlant.sdk import ToolEntry
+
+        for spec in GUIDELINE_SPECS:
+            for tool in spec["tools"]:
+                assert isinstance(tool, ToolEntry), (
+                    f"Tool {tool} in guideline '{spec['condition'][:30]}...' "
+                    f"is not a ToolEntry"
+                )
+
+    def test_medical_disclaimer_guideline_exists(self):
+        """Should have a medical disclaimer guideline."""
+        disclaimer = [
+            s for s in GUIDELINE_SPECS
+            if "disclaimer" in s["action"].lower() or "medical advice" in s["action"].lower()
+        ]
+        assert len(disclaimer) >= 1
+
+    def test_configure_passes_tools_to_agent(self, mock_agent):
+        """configure_guidelines should pass tools list to create_guideline."""
+        configure_guidelines(mock_agent)
+
+        # Check that at least one call included tools
+        calls_with_tools = [
+            c for c in mock_agent.create_guideline.call_args_list
+            if c.kwargs.get("tools")
+        ]
+        assert len(calls_with_tools) > 0