trialpath/agent/guidelines.py

"""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",
    },
]


async 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 = await agent.create_guideline(
            condition=spec["condition"],
            action=spec["action"],
            tools=spec["tools"],
        )
        guidelines.append(guideline)
    return guidelines