feat: structured eligibility assessment with per-criterion verdicts (#14)

- Add agents/eligibility.py: two-step pipeline — bulk LLM parse of
eligibility text into structured constraints, then deterministic
code evaluation (Path A) for known patient fields; research LLM
handles unclear criteria inline (Path B, no extra call)
- Add data/criterion_keys.json: canonical key → patient/platform
field mapping; extend without touching agent code
- Add data/tools/{parse_criteria,parse_criteria_bulk,assess_eligibility}.json
- Extend models.py: CriterionVerdict, ParsedConstraint, EligibilityCriterion,
CriterionAssessment, TrialEligibilityReport
- trials_api.py: extract full fields (sex, healthy_volunteers, std_ages,
study_type, enrollment, conditions, keywords, interventions); remove
1000/500-char truncations; pageSize 200 → 1000 (fewer round trips)
- agents/intake.py: accept onset_date/diagnosis_date (YYYY-MM) and
compute months in Python — fixes LLM arithmetic drift on current date
- agents/research.py: bulk parse + strip after each search; yield
("status", msg) events for live progress (per study type)
- app.py: handle status events; colorize ✓/✗/! verdicts with inline
HTML spans (green/red/yellow); sanitize_html=False on chatbot
- prompts.py: updated research format to render eligibility checklist
from parsed_criteria + deterministic_verdicts
- design/eligibility-assessment.md: full design doc

Co-authored-by: Claude Sonnet 4.6 <noreply@anthropic.com>

CLAUDE.md

@@ -0,0 +1,100 @@
+# Beacon — Architecture Guide for Claude Code
+
+## Layer Responsibilities
+
+### `app.py` — UI wiring only
+
+`app.py` owns **Gradio state and event wiring**. Nothing else.
+
+Allowed:
+- `gr.State`, `gr.Chatbot`, `gr.Textbox`, and other Gradio components
+- Event handlers that call into `agents.*` and yield streaming updates
+- Language switching, layout, and display formatting
+
+Not allowed:
+- Direct calls to `trials_api`, `prompts`, `tools`, `models`, or `config`
+- Business rules, data transformations, or domain logic
+- Any knowledge of what a `PatientProfile` field means
+
+If you find yourself importing a non-agent module into `app.py`, that logic belongs in an agent or a business-logic module instead.
+
+---
+
+### `clinical_trials_guru.py` — business wiring only
+
+`clinical_trials_guru.py` owns **orchestration and re-exports**. It is the single public facade for CLI callers and external scripts.
+
+Allowed:
+- `BeaconState` TypedDict and LangGraph graph construction (`_build_graph`)
+- CLI entry point (`guru_main`)
+- Re-exporting symbols from internal modules so callers import one place
+
+Not allowed:
+- UI logic, Gradio imports, or display formatting
+- New business logic that belongs in `agents/`, `models.py`, `tools.py`, etc.
+- Duplicating functions that already live in `agents/`
+
+When you add a new public symbol (function, class, constant), expose it here so the rest of the codebase has one stable import surface.
+
+---
+
+### `agents/` — orchestration with streaming support
+
+Each agent module (`intake.py`, `research.py`) provides two variants:
+- A **blocking** function (`run_*`) for CLI / LangGraph nodes
+- A **streaming generator** (`stream_*`) for the Gradio web UI
+
+Keep agents free of Gradio types. They yield plain strings and return domain objects (`PatientProfile`, `str`).
+
+---
+
+## Design Principle: Load Only Necessary Context
+
+**Never inject all disease benchmarks into context when only one disease is relevant.**
+
+### Rule
+
+Context for a disease-specific benchmark set must not be loaded until the disease is identified. Once the patient's disease is known (via the `identify_disease` tool), load only that disease's profile and pass it to the LLM. Do not pre-load or concatenate profiles for other diseases.
+
+### Rationale
+
+- Each disease JSON carries benchmark definitions, ranges, and guidance text. Loading all 8+ profiles wastes tokens and dilutes the system prompt.
+- The `identify_disease` tool call is the earliest reliable signal of disease identity. Everything after that point can be scoped to one profile.
+- This keeps context proportional to the task and reduces the risk of cross-disease confusion in the LLM.
+
+### How it works today
+
+`prompts.py` eagerly reads all disease files into `_ALL_DISEASES` at module import, but `lookup_disease_profile(standardized_name)` returns **only one profile** — the matched disease. The intake agent calls this function after the `identify_disease` tool fires and injects only the returned benchmarks into the conversation.
+
+### How to stay compliant
+
+- After `identify_disease` resolves, call `lookup_disease_profile(standardized_name)` and use the returned dict exclusively.
+- Do not iterate over `_ALL_DISEASES` to build a multi-disease context block.
+- If you need to add a new disease, add its JSON under `data/diseases/` — do not hardcode benchmark lists in prompts or agents.
+- For features that genuinely need cross-disease comparison (e.g., a disease selector UI), load lazily: fetch each profile only when selected, not all at startup.
+
+---
+
+## Module Map
+
+| File | Layer | Imports allowed from |
+|---|---|---|
+| `app.py` | UI | `agents.*`, `translations`, `models` (type hints only) |
+| `clinical_trials_guru.py` | Business facade | Everything |
+| `agents/intake.py` | Agent | `models`, `prompts`, `tools`, `config`, `llm`, `translations` |
+| `agents/research.py` | Agent | `models`, `prompts`, `tools`, `config`, `llm`, `trials_api`, `translations` |
+| `models.py` | Domain model | stdlib, `requests` |
+| `prompts.py` | Prompt builder | stdlib, `data/diseases/*.json` |
+| `tools.py` | Tool schema loader | stdlib, `data/tools/*.json` |
+| `trials_api.py` | External API | stdlib, `models`, `config` |
+| `config.py` | Constants | stdlib |
+| `translations.py` | i18n | stdlib |
+
+---
+
+## Entry Points
+
+| Entry | File | UI | Flow |
+|---|---|---|---|
+| Web | `app.py` | Gradio | `intake_greeting` → `stream_intake_turn` → `stream_research_agent` |
+| CLI | `main.py` → `clinical_trials_guru.py` | Rich console | LangGraph: `run_intake_agent` → `run_research_agent` |

agents/eligibility.py

@@ -0,0 +1,441 @@
+from __future__ import annotations
+
+import json
+import operator as _op
+from pathlib import Path
+from typing import Generator
+
+import anthropic
+
+from beacon_logging import get_logger
+from config import ELIGIBILITY_MODEL
+from models import (
+    CriterionAssessment,
+    CriterionVerdict,
+    EligibilityCriterion,
+    ParsedConstraint,
+    PatientProfile,
+    TrialEligibilityReport,
+)
+from tools import ASSESS_ELIGIBILITY_TOOL, PARSE_CRITERIA_TOOL, PARSE_CRITERIA_BULK_TOOL
+
+_logger = get_logger("agents.eligibility")
+
+_KEY_MAP: dict[str, str] = json.loads(
+    (Path(__file__).parent.parent / "data" / "criterion_keys.json").read_text()
+)
+
+_PARSE_SYSTEM = """\
+You are a clinical trial eligibility parser. Given raw eligibility criteria text, \
+extract every inclusion and exclusion criterion as a structured object.
+
+For each criterion:
+- key: a snake_case canonical name that identifies the patient attribute being tested \
+  (e.g. age_years, ecog_status, prior_systemic_therapy_lines, egfr_ml_min)
+- type: "inclusion" or "exclusion"
+- description: a concise plain-English restatement of the requirement the patient must satisfy
+- raw_criteria: the verbatim criterion text from the source
+- constraint: a structured comparison if the criterion can be expressed as one; null otherwise
+
+Express constraints as the condition the patient must meet to qualify:
+  "Age 18-75" → {operator: "between", value: [18, 75]}
+  "No prior systemic therapy" → {operator: "==", value: 0}
+  "ECOG 0 or 1" → {operator: "in", value: [0, 1]}
+  "eGFR >= 60 mL/min" → {operator: ">=", value: 60, unit: "mL/min"}
+  "Adequate hepatic function per investigator" → null
+
+Set constraint to null for any criterion that is vague, subjective, compound, or \
+cannot be expressed as a single comparison against a known patient field.
+"""
+
+_ASSESS_SYSTEM = """\
+You are a clinical trial eligibility assessor. Given a list of eligibility criteria \
+that could not be evaluated deterministically, assess each one against the provided \
+patient profile.
+
+Rules:
+1. If patient data is missing for a criterion → verdict must be "unknown", never "pass"
+2. Confidence is "medium" if the criterion is clear but data is incomplete; \
+   "low" if the criterion itself is ambiguous
+3. For exclusion criteria: if patient data matches the exclusion condition → verdict is "fail"
+4. List every criterion key you could not assess in missing_data_keys
+5. Be conservative — when in doubt, use "unknown"
+"""
+
+
+def _resolve_patient_value(
+    key: str,
+    patient: PatientProfile,
+    platform_data: dict | None,
+) -> tuple[object, bool]:
+    mapped = _KEY_MAP.get(key)
+    if mapped is None:
+        return None, False
+    prefix, field = mapped.split(".", 1)
+    if prefix == "patient":
+        val = getattr(patient, field, None)
+        return val, val is not None
+    if prefix == "platform":
+        if platform_data is None:
+            return None, False
+        val = platform_data.get(field)
+        return val, val is not None
+    return None, False
+
+
+_OPERATORS = {
+    "<=":     _op.le,
+    ">=":     _op.ge,
+    "==":     _op.eq,
+    "!=":     _op.ne,
+    "in":     lambda pv, v: pv in v,
+    "not_in": lambda pv, v: pv not in v,
+    "between": lambda pv, v: v[0] <= pv <= v[1],
+}
+
+
+def _evaluate_deterministic(
+    criterion: EligibilityCriterion,
+    patient_value: object,
+) -> CriterionAssessment:
+    c = criterion.constraint
+    fn = _OPERATORS.get(c.operator)
+    try:
+        passes = fn(patient_value, c.value)
+    except (TypeError, ValueError):
+        passes = False
+
+    verdict = CriterionVerdict.PASS if passes else CriterionVerdict.FAIL
+    unit_str = f" {c.unit}" if c.unit else ""
+    reason = (
+        f"Requires {c.operator} {c.value}{unit_str}; patient value: {patient_value}"
+    )
+    return CriterionAssessment(
+        criterion=criterion,
+        verdict=verdict,
+        reason=reason,
+        patient_value=str(patient_value),
+        confidence="high",
+    )
+
+
+def _parse_criteria(client: anthropic.Anthropic, eligibility_text: str) -> list[EligibilityCriterion]:
+    if not eligibility_text.strip():
+        return []
+
+    response = client.messages.create(
+        model=ELIGIBILITY_MODEL,
+        max_tokens=4096,
+        system=_PARSE_SYSTEM,
+        tools=[PARSE_CRITERIA_TOOL],
+        tool_choice={"type": "tool", "name": "parse_criteria"},
+        messages=[{"role": "user", "content": eligibility_text}],
+    )
+
+    tool_use = next((b for b in response.content if b.type == "tool_use"), None)
+    if tool_use is None:
+        _logger.warning("parse_criteria tool not called", extra={"data": {}})
+        return []
+
+    raw_criteria: list[dict] = tool_use.input.get("criteria", [])
+    result = []
+    for rc in raw_criteria:
+        raw_constraint = rc.get("constraint")
+        constraint = None
+        if raw_constraint:
+            constraint = ParsedConstraint(
+                key=raw_constraint["key"],
+                operator=raw_constraint["operator"],
+                value=raw_constraint["value"],
+                unit=raw_constraint.get("unit"),
+            )
+        result.append(EligibilityCriterion(
+            key=rc["key"],
+            type=rc["type"],
+            description=rc["description"],
+            raw_criteria=rc["raw_criteria"],
+            constraint=constraint,
+        ))
+
+    _logger.info(
+        "Parsed eligibility criteria",
+        extra={"data": {"count": len(result)}},
+    )
+    return result
+
+
+def _assess_llm(
+    client: anthropic.Anthropic,
+    criteria: list[EligibilityCriterion],
+    patient: PatientProfile,
+    platform_data: dict | None,
+) -> list[CriterionAssessment]:
+    if not criteria:
+        return []
+
+    patient_context = {
+        "age_years": patient.age,
+        "symptom_onset_months": patient.onset_months,
+        "diagnosis_months": patient.diagnosis_months,
+        "disease": patient.disease,
+    }
+    if platform_data:
+        patient_context["platform_data"] = platform_data
+
+    criteria_payload = [
+        {"key": c.key, "type": c.type, "description": c.description, "raw_criteria": c.raw_criteria}
+        for c in criteria
+    ]
+
+    user_content = (
+        f"Patient profile:\n{json.dumps(patient_context, indent=2)}\n\n"
+        f"Criteria to assess:\n{json.dumps(criteria_payload, indent=2)}"
+    )
+
+    response = client.messages.create(
+        model=ELIGIBILITY_MODEL,
+        max_tokens=4096,
+        system=_ASSESS_SYSTEM,
+        tools=[ASSESS_ELIGIBILITY_TOOL],
+        tool_choice={"type": "tool", "name": "assess_eligibility"},
+        messages=[{"role": "user", "content": user_content}],
+    )
+
+    tool_use = next((b for b in response.content if b.type == "tool_use"), None)
+    if tool_use is None:
+        _logger.warning("assess_eligibility tool not called", extra={"data": {}})
+        return [
+            CriterionAssessment(
+                criterion=c,
+                verdict=CriterionVerdict.UNKNOWN,
+                reason="Assessment unavailable",
+                patient_value=None,
+                confidence="low",
+            )
+            for c in criteria
+        ]
+
+    criterion_by_key = {c.key: c for c in criteria}
+    assessments = []
+    for a in tool_use.input.get("assessments", []):
+        criterion = criterion_by_key.get(a["criterion_key"])
+        if criterion is None:
+            continue
+        assessments.append(CriterionAssessment(
+            criterion=criterion,
+            verdict=CriterionVerdict(a["verdict"]),
+            reason=a["reason"],
+            patient_value=a.get("patient_value"),
+            confidence=a["confidence"],
+        ))
+
+    return assessments
+
+
+def _compute_overall(assessments: list[CriterionAssessment]) -> CriterionVerdict:
+    if any(a.verdict == CriterionVerdict.FAIL for a in assessments):
+        return CriterionVerdict.FAIL
+    if any(a.verdict == CriterionVerdict.UNKNOWN for a in assessments):
+        return CriterionVerdict.UNKNOWN
+    return CriterionVerdict.PASS
+
+
+def run_eligibility_check(
+    client: anthropic.Anthropic,
+    trial: dict,
+    patient: PatientProfile,
+    platform_data: dict | None = None,
+) -> TrialEligibilityReport:
+    nct_id = trial.get("nct_id", "")
+    eligibility_text = trial.get("eligibility", "")
+
+    criteria = _parse_criteria(client, eligibility_text)
+
+    deterministic: list[CriterionAssessment] = []
+    needs_llm: list[EligibilityCriterion] = []
+
+    for c in criteria:
+        if c.constraint is not None:
+            patient_value, found = _resolve_patient_value(c.key, patient, platform_data)
+            if found:
+                deterministic.append(_evaluate_deterministic(c, patient_value))
+                continue
+        needs_llm.append(c)
+
+    llm_assessments = _assess_llm(client, needs_llm, patient, platform_data)
+
+    all_assessments = deterministic + llm_assessments
+    missing_data_keys = [
+        a.criterion.key
+        for a in llm_assessments
+        if a.verdict == CriterionVerdict.UNKNOWN
+    ]
+
+    report = TrialEligibilityReport(
+        nct_id=nct_id,
+        overall_verdict=_compute_overall(all_assessments),
+        assessments=all_assessments,
+        missing_data_keys=missing_data_keys,
+    )
+
+    _logger.info(
+        "Eligibility check complete",
+        extra={
+            "data": {
+                "nct_id": nct_id,
+                "overall": report.overall_verdict,
+                "total": len(all_assessments),
+                "deterministic": len(deterministic),
+                "llm": len(llm_assessments),
+                "missing": missing_data_keys,
+            }
+        },
+    )
+    return report
+
+
+_FIELDS_TO_STRIP_AFTER_PARSE = {"eligibility", "std_ages", "healthy_volunteers"}
+
+
+def bulk_parse_and_strip(
+    client: anthropic.Anthropic,
+    trials: list[dict],
+    patient: PatientProfile,
+    platform_data: dict | None = None,
+    top_n: int = 5,
+) -> list[dict]:
+    """
+    One LLM call to parse criteria for top_n trials.
+    Applies deterministic assessment (Path A) in code.
+    Strips raw eligibility text and redundant fields.
+    Research LLM handles Path B (unclear criteria) inline during synthesis.
+    """
+    to_parse = [t for t in trials[:top_n] if t.get("eligibility", "").strip()]
+    rest = trials[top_n:]
+
+    if not to_parse:
+        return trials
+
+    payload = [
+        {"nct_id": t["nct_id"], "eligibility_text": t["eligibility"]}
+        for t in to_parse
+    ]
+    user_content = (
+        f"Parse eligibility criteria for these {len(payload)} trials:\n"
+        + json.dumps(payload, indent=2)
+    )
+
+    try:
+        response = client.messages.create(
+            model=ELIGIBILITY_MODEL,
+            max_tokens=8192,
+            system=_PARSE_SYSTEM,
+            tools=[PARSE_CRITERIA_BULK_TOOL],
+            tool_choice={"type": "tool", "name": "parse_criteria_bulk"},
+            messages=[{"role": "user", "content": user_content}],
+        )
+        tool_use = next((b for b in response.content if b.type == "tool_use"), None)
+        parsed_by_nct: dict[str, list[dict]] = {}
+        if tool_use:
+            for entry in tool_use.input.get("trials", []):
+                parsed_by_nct[entry["nct_id"]] = entry.get("criteria", [])
+    except Exception as exc:
+        _logger.warning("Bulk parse failed", extra={"data": {"error": str(exc)}})
+        parsed_by_nct = {}
+
+    _logger.info(
+        "Bulk criteria parse complete",
+        extra={"data": {"trials_parsed": len(parsed_by_nct)}},
+    )
+
+    for trial in to_parse:
+        nct_id = trial["nct_id"]
+        raw_criteria = parsed_by_nct.get(nct_id, [])
+        criteria: list[EligibilityCriterion] = []
+        deterministic_verdicts: list[dict] = []
+
+        for rc in raw_criteria:
+            raw_constraint = rc.get("constraint")
+            constraint = None
+            if raw_constraint:
+                constraint = ParsedConstraint(
+                    key=raw_constraint["key"],
+                    operator=raw_constraint["operator"],
+                    value=raw_constraint["value"],
+                    unit=raw_constraint.get("unit"),
+                )
+            c = EligibilityCriterion(
+                key=rc["key"],
+                type=rc["type"],
+                description=rc["description"],
+                raw_criteria=rc["raw_criteria"],
+                constraint=constraint,
+            )
+            criteria.append(c)
+
+            if constraint is not None:
+                patient_value, found = _resolve_patient_value(c.key, patient, platform_data)
+                if found:
+                    assessment = _evaluate_deterministic(c, patient_value)
+                    deterministic_verdicts.append({
+                        "verdict": assessment.verdict.value,
+                        "description": c.description,
+                        "reason": assessment.reason,
+                        "confidence": assessment.confidence,
+                        "raw_criteria": c.raw_criteria,
+                    })
+
+        trial["parsed_criteria"] = [
+            {
+                "key": c.key,
+                "type": c.type,
+                "description": c.description,
+                "raw_criteria": c.raw_criteria,
+                "constraint": (
+                    {
+                        "operator": c.constraint.operator,
+                        "value": c.constraint.value,
+                        "unit": c.constraint.unit,
+                    }
+                    if c.constraint else None
+                ),
+            }
+            for c in criteria
+        ]
+        trial["deterministic_verdicts"] = deterministic_verdicts
+
+        for field in _FIELDS_TO_STRIP_AFTER_PARSE:
+            trial.pop(field, None)
+
+    return to_parse + rest
+
+
+def stream_eligibility_check(
+    client: anthropic.Anthropic,
+    trial: dict,
+    patient: PatientProfile,
+    platform_data: dict | None = None,
+) -> Generator[str, None, None]:
+    nct_id = trial.get("nct_id", "")
+    yield f"Parsing eligibility criteria for {nct_id}…\n"
+
+    report = run_eligibility_check(client, trial, patient, platform_data)
+
+    verdict_icon = {"pass": "✓", "fail": "✗", "unknown": "!"}
+    lines = []
+    for a in report.assessments:
+        icon = verdict_icon[a.verdict.value]
+        lines.append(f"  {icon}  {a.criterion.description} — {a.reason}")
+
+    lines.append("")
+    overall_label = {
+        CriterionVerdict.PASS:    "Eligible",
+        CriterionVerdict.FAIL:    "Not eligible",
+        CriterionVerdict.UNKNOWN: "Likely eligible — confirm missing info",
+    }[report.overall_verdict]
+    lines.append(f"  Overall: {overall_label}")
+
+    if report.missing_data_keys:
+        lines.append(f"  Missing information: {', '.join(report.missing_data_keys)}")
+
+    yield "\n".join(lines) + "\n"

agents/intake.py

@@ -20,6 +20,23 @@ from _console import console
 _logger = get_logger("agents.intake")
 
 
+def _months_from_date(date_str: str) -> int:
+    """Convert YYYY-MM string to elapsed months from today. Returns 0 on parse failure."""
+    try:
+        year, month = int(date_str[:4]), int(date_str[5:7])
+        today = datetime.date.today()
+        return (today.year - year) * 12 + (today.month - month)
+    except (ValueError, IndexError):
+        return 0
+
+
+def _resolve_months(data: dict, date_key: str, months_key: str) -> int:
+    """Prefer date string for exact computation; fall back to LLM-supplied integer."""
+    if data.get(date_key):
+        return _months_from_date(data[date_key])
+    return data.get(months_key) or 0
+
+
 def run_intake_agent(client: anthropic.Anthropic) -> PatientProfile:
     today = datetime.date.today().strftime("%B %d, %Y")
 
@@ -84,8 +101,8 @@ def run_intake_agent(client: anthropic.Anthropic) -> PatientProfile:
             profile = PatientProfile(
                 disease=data["disease"],
                 age=data["age"],
-                onset_months=data["onset_months"],
-                diagnosis_months=data.get("diagnosis_months", 0),
+                onset_months=_resolve_months(data, "onset_date", "onset_months"),
+                diagnosis_months=_resolve_months(data, "diagnosis_date", "diagnosis_months"),
                 benchmarks=data.get("benchmarks") or {},
                 zip_code=data["zip_code"],
                 country_code=data.get("country_code", "US"),
@@ -199,8 +216,8 @@ def stream_intake_turn(
             profile = PatientProfile(
                 disease=data["disease"],
                 age=data["age"],
-                onset_months=data["onset_months"],
-                diagnosis_months=data.get("diagnosis_months", 0),
+                onset_months=_resolve_months(data, "onset_date", "onset_months"),
+                diagnosis_months=_resolve_months(data, "diagnosis_date", "diagnosis_months"),
                 benchmarks=data.get("benchmarks") or {},
                 zip_code=data["zip_code"],
                 country_code=data.get("country_code", "US"),

agents/research.py

@@ -5,6 +5,7 @@ from typing import Generator
 
 import anthropic
 
+from agents.eligibility import bulk_parse_and_strip
 from beacon_logging import get_logger
 from config import RESEARCH_MODEL
 from models import PatientProfile
@@ -70,6 +71,7 @@ def run_research_agent(client: anthropic.Anthropic, profile: PatientProfile) ->
                         study_type=study_type,
                     )
                     ranked = _flatten_and_rank(studies, profile.lat, profile.lon)
+                    ranked = bulk_parse_and_strip(client, ranked, profile)
                 console.print(f"  [green]✓[/green] {len(ranked)} trial(s) found.")
                 content = json.dumps(ranked)
                 is_error = False
@@ -131,16 +133,24 @@ def stream_research_agent(
             if block.type != "tool_use" or block.name != "search_clinical_trials":
                 continue
             args = block.input
+            radius = args.get("radius_miles", profile.radius_miles)
+            study_type = args.get("study_type", "INTERVENTIONAL")
+            type_label = {"INTERVENTIONAL": "clinical trials", "EXPANDED_ACCESS": "expanded access programs", "OBSERVATIONAL": "observational studies"}.get(study_type, study_type.lower())
+            yield ("status", f"Searching ClinicalTrials.gov for **{args['condition']}** ({type_label}, {radius} mi radius)…")
             try:
                 studies = search_trials_api(
                     condition=args["condition"],
                     lat=args["lat"],
                     lon=args["lon"],
-                    radius_miles=args.get("radius_miles", profile.radius_miles),
+                    radius_miles=radius,
                     phases=args.get("phases") or None,
-                    study_type=args.get("study_type", "INTERVENTIONAL"),
+                    study_type=study_type,
                 )
                 ranked = _flatten_and_rank(studies, profile.lat, profile.lon)
+                n = len(ranked)
+                yield ("status", f"Found **{n}** {type_label} — checking eligibility for the {min(5, n)} closest…")
+                ranked = bulk_parse_and_strip(client, ranked, profile)
+                yield ("status", "Eligibility analysis complete — generating your report…")
                 content = json.dumps(ranked)
                 is_error = False
             except Exception as exc:

app.py

@@ -1,6 +1,7 @@
 from __future__ import annotations
 
 import dataclasses
+import re
 from typing import Generator
 
 import anthropic
@@ -17,6 +18,22 @@ load_dotenv()
 
 _logger = get_logger("app")
 
+_VERDICT_STYLE = {
+    "✓": "background:#22c55e;color:#fff;padding:2px 10px;border-radius:12px;font-weight:700;",
+    "✗": "background:#ef4444;color:#fff;padding:2px 10px;border-radius:12px;font-weight:700;",
+    "!": "background:#eab308;color:#fff;padding:2px 10px;border-radius:12px;font-weight:700;",
+}
+
+_VERDICT_RE = re.compile(r"(?m)^(\s*)(✓|✗|!)\s")
+
+
+def _colorize(text: str) -> str:
+    def _replace(m: re.Match) -> str:
+        symbol = m.group(2)
+        style = _VERDICT_STYLE[symbol]
+        return f'{m.group(1)}<span style="{style}">{symbol}</span> '
+    return _VERDICT_RE.sub(_replace, text)
+
 
 def initialize(lang: str = "en"):
     client = anthropic.Anthropic()
@@ -82,13 +99,20 @@ def respond(
                 if rev[0] == "token":
                     stream_text += rev[1]
                     yield (
-                        chat_history + [{"role": "assistant", "content": stream_text}],
+                        chat_history + [{"role": "assistant", "content": _colorize(stream_text)}],
+                        updated_msgs, new_profile, "researching",
+                        gr.update(interactive=False, placeholder=t["searching"]),
+                        gr.update(visible=False),
+                    )
+                elif rev[0] == "status":
+                    yield (
+                        chat_history + [{"role": "assistant", "content": rev[1]}],
                         updated_msgs, new_profile, "researching",
                         gr.update(interactive=False, placeholder=t["searching"]),
                         gr.update(visible=False),
                     )
                 elif rev[0] == "done":
-                    analysis = rev[1] or t["no_analysis"]
+                    analysis = _colorize(rev[1] or t["no_analysis"])
                     chat_history = chat_history + [{"role": "assistant", "content": analysis}]
                     yield (
                         chat_history, updated_msgs, new_profile, "done",
@@ -125,7 +149,7 @@ with gr.Blocks(title=UI["en"]["page_title"]) as demo:
             container=False,
         )
 
-    chatbot = gr.Chatbot(height=550, show_label=False)
+    chatbot = gr.Chatbot(height=550, show_label=False, sanitize_html=False)
     with gr.Row():
         msg_box = gr.Textbox(
             placeholder=UI["en"]["placeholder"],

config.py

@@ -1,3 +1,4 @@
 CTGOV_BASE = "https://clinicaltrials.gov/api/v2/studies"
 INTAKE_MODEL = "claude-sonnet-4-6"
 RESEARCH_MODEL = "claude-opus-4-7"
+ELIGIBILITY_MODEL = "claude-sonnet-4-6"

data/criterion_keys.json

@@ -0,0 +1,14 @@
+{
+  "age_years":                    "patient.age",
+  "symptom_onset_months":         "patient.onset_months",
+  "diagnosis_months":             "patient.diagnosis_months",
+  "sex":                          "patient.sex",
+  "ecog_status":                  "platform.ecog_status",
+  "prior_systemic_therapy_lines": "platform.prior_treatment_lines",
+  "egfr_ml_min":                  "platform.egfr_ml_min",
+  "anc_per_ul":                   "platform.anc_per_ul",
+  "hemoglobin_g_dl":              "platform.hemoglobin_g_dl",
+  "platelets_per_ul":             "platform.platelets_per_ul",
+  "bilirubin_mg_dl":              "platform.bilirubin_mg_dl",
+  "creatinine_mg_dl":             "platform.creatinine_mg_dl"
+}

data/tools/assess_eligibility.json

@@ -0,0 +1,25 @@
+{
+  "type": "object",
+  "required": ["assessments", "missing_data_keys"],
+  "properties": {
+    "assessments": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "required": ["criterion_key", "verdict", "reason", "confidence", "raw_criteria"],
+        "properties": {
+          "criterion_key":  { "type": "string" },
+          "verdict":        { "enum": ["pass", "fail", "unknown"] },
+          "reason":         { "type": "string" },
+          "patient_value":  { "type": ["string", "null"] },
+          "confidence":     { "enum": ["medium", "low"] },
+          "raw_criteria":   { "type": "string" }
+        }
+      }
+    },
+    "missing_data_keys": {
+      "type": "array",
+      "items": { "type": "string" }
+    }
+  }
+}

data/tools/parse_criteria.json

@@ -0,0 +1,34 @@
+{
+  "type": "object",
+  "required": ["criteria"],
+  "properties": {
+    "criteria": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "required": ["key", "type", "description", "raw_criteria"],
+        "properties": {
+          "key":          { "type": "string" },
+          "type":         { "enum": ["inclusion", "exclusion"] },
+          "description":  { "type": "string" },
+          "raw_criteria": { "type": "string" },
+          "constraint": {
+            "oneOf": [
+              { "type": "null" },
+              {
+                "type": "object",
+                "required": ["key", "operator", "value"],
+                "properties": {
+                  "key":      { "type": "string" },
+                  "operator": { "enum": ["<=", ">=", "==", "!=", "in", "not_in", "between"] },
+                  "value":    {},
+                  "unit":     { "type": ["string", "null"] }
+                }
+              }
+            ]
+          }
+        }
+      }
+    }
+  }
+}

data/tools/parse_criteria_bulk.json

@@ -0,0 +1,44 @@
+{
+  "type": "object",
+  "required": ["trials"],
+  "properties": {
+    "trials": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "required": ["nct_id", "criteria"],
+        "properties": {
+          "nct_id": { "type": "string" },
+          "criteria": {
+            "type": "array",
+            "items": {
+              "type": "object",
+              "required": ["key", "type", "description", "raw_criteria"],
+              "properties": {
+                "key":          { "type": "string" },
+                "type":         { "enum": ["inclusion", "exclusion"] },
+                "description":  { "type": "string" },
+                "raw_criteria": { "type": "string" },
+                "constraint": {
+                  "oneOf": [
+                    { "type": "null" },
+                    {
+                      "type": "object",
+                      "required": ["key", "operator", "value"],
+                      "properties": {
+                        "key":      { "type": "string" },
+                        "operator": { "enum": ["<=", ">=", "==", "!=", "in", "not_in", "between"] },
+                        "value":    {},
+                        "unit":     { "type": ["string", "null"] }
+                      }
+                    }
+                  ]
+                }
+              }
+            }
+          }
+        }
+      }
+    }
+  }
+}

data/tools/submit_profile.json

@@ -6,13 +6,21 @@
       "description": "Full medical name (e.g. 'Amyotrophic Lateral Sclerosis')"
     },
     "age": { "type": "integer" },
+    "onset_date": {
+      "type": "string",
+      "description": "Date of first symptom onset in YYYY-MM format (preferred over onset_months)"
+    },
     "onset_months": {
       "type": "integer",
-      "description": "Months since first symptom onset"
+      "description": "Months since first symptom onset — only use if exact date is unknown"
+    },
+    "diagnosis_date": {
+      "type": "string",
+      "description": "Date of formal diagnosis in YYYY-MM format (preferred over diagnosis_months)"
     },
     "diagnosis_months": {
       "type": "integer",
-      "description": "Months since formal/official diagnosis"
+      "description": "Months since formal/official diagnosis — only use if exact date is unknown"
     },
     "benchmarks": {
       "type": "object",

design/eligibility-assessment.md

@@ -0,0 +1,364 @@
+# Eligibility Assessment — Design Document
+
+## Background
+
+Currently, Beacon fetches raw eligibility text from ClinicalTrials.gov but drops most of it — criteria are truncated at 1000 characters, and structured fields (sex, age groups, healthy volunteers) are never extracted. The research agent passes the truncated blob to the LLM and lets it synthesize a free-form summary. There is no per-criterion verdict, no structured representation of why a patient does or does not qualify, and no seam for external data to plug into.
+
+This document covers two related changes:
+1. **Stop discarding data** — extract all useful fields from the API response we already receive as JSON format
+2. **Eligibility assessment** — structured per-criterion judgment with a defined UI representation
+
+---
+
+## Part 1: Complete the API Extraction (`trials_api.py`)
+
+### Problem
+
+`_flatten_and_rank` currently:
+- Truncates `eligibilityCriteria` at 1000 chars (criteria routinely run 3–5x that, cutting off key exclusions)
+- Truncates `briefSummary` at 500 chars
+- Reads 6 protocol modules but uses only a fraction of each
+- Never reads `conditionsModule` or `armsInterventionsModule`
+
+No extra network calls are needed — all of this is already in the paginated response.
+
+### Fields to add
+
+| Field | Source module | Key | Notes |
+|---|---|---|---|
+| `sex` | `eligibilityModule` | `sex` | `"ALL"`, `"FEMALE"`, `"MALE"` |
+| `healthy_volunteers` | `eligibilityModule` | `healthyVolunteers` | `"Yes"` / `"No"` |
+| `std_ages` | `eligibilityModule` | `stdAges` | e.g. `["ADULT", "OLDER_ADULT"]` |
+| `study_type` | `designModule` | `studyType` | `"INTERVENTIONAL"` etc. |
+| `enrollment` | `designModule` | `enrollmentInfo.count` | expected participant count |
+| `conditions` | `conditionsModule` | `conditions` | list of condition strings |
+| `keywords` | `conditionsModule` | `keywords` | list of keyword strings |
+| `interventions` | `armsInterventionsModule` | `interventions[*]` | `{type, name, description}` per entry |
+
+### Truncation removal
+
+- `eligibilityCriteria`: remove `[:1000]` — pass full text
+- `briefSummary`: remove `[:500]` — pass full text
+
+### File changed
+
+`trials_api.py` — `_flatten_and_rank` only (lines 99–162)
+
+---
+
+## Part 2: Eligibility Assessment
+
+### Goal
+
+For each trial returned to a patient, produce a per-criterion verdict:
+- `pass` — patient meets this criterion (show ✓)
+- `fail` — patient does not meet this criterion (show ✗ + reason)
+- `unknown` — insufficient data to assess (show ! + what data would resolve it)
+
+**Core principle: robustness over optimism.** When data is missing, the verdict is `unknown`, never an assumed `pass`.
+
+### Data the patient provides today
+
+| Field | Source |
+|---|---|
+| Age | `PatientProfile.age` |
+| Disease | `PatientProfile.disease` |
+| Time since diagnosis | `PatientProfile.diagnosis_months` |
+| Time since symptom onset | `PatientProfile.onset_months` |
+| Phases acceptable | `PatientProfile.phases` |
+| Location | `PatientProfile.location` |
+
+### Data the integration partner could provide
+
+| Field | Maps to common trial criteria |
+|---|---|
+| ECOG / performance status | Performance status requirements |
+| Prior lines of therapy | Prior treatment exclusions |
+| Lab values (eGFR, ANC, Hgb, platelets, etc.) | Lab-based inclusion/exclusion |
+| Current medications | Drug interaction exclusions |
+| Comorbidities | Disease-based exclusion criteria |
+
+These map to the most common failure points in trial eligibility. Providing them moves criteria from `unknown` to `pass` or `fail`.
+
+### Criteria parsing (Step 1 of 2)
+
+Before assessment, raw eligibility text is parsed into structured criterion objects. This is a separate LLM call using a `parse_criteria` tool.
+
+**Example:**
+
+| Raw text | Parsed constraint |
+|---|---|
+| `"Patients must have symptom onset within 24 months"` | `{"key": "symptom_onset_months", "operator": "<=", "value": 24, "unit": "months"}` |
+| `"Age 18 to 75 years"` | `{"key": "age_years", "operator": "between", "value": [18, 75], "unit": "years"}` |
+| `"ECOG performance status 0 or 1"` | `{"key": "ecog_status", "operator": "in", "value": [0, 1], "unit": null}` |
+| `"No prior systemic therapy"` | `{"key": "prior_systemic_therapy_lines", "operator": "==", "value": 0, "unit": null}` |
+| `"Adequate hepatic function as per investigator"` | `null` — not parseable, falls back to LLM judgment |
+
+When a criterion cannot be expressed as a structured constraint (vague language, compound logic, subjective assessments), `constraint` is `null`. Assessment for those falls back to LLM judgment, which will produce `unknown` if patient data is insufficient.
+
+**Tool schema** (`data/tools/parse_criteria.json`):
+
+```json
+{
+  "type": "object",
+  "required": ["criteria"],
+  "properties": {
+    "criteria": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "required": ["key", "type", "description", "raw_criteria"],
+        "properties": {
+          "key":          { "type": "string" },
+          "type":         { "enum": ["inclusion", "exclusion"] },
+          "description":  { "type": "string" },
+          "raw_criteria": { "type": "string" },
+          "constraint": {
+            "oneOf": [
+              { "type": "null" },
+              {
+                "type": "object",
+                "required": ["key", "operator", "value"],
+                "properties": {
+                  "key":      { "type": "string" },
+                  "operator": { "enum": ["<=", ">=", "==", "!=", "in", "not_in", "between"] },
+                  "value":    {},
+                  "unit":     { "type": ["string", "null"] }
+                }
+              }
+            ]
+          }
+        }
+      }
+    }
+  }
+}
+```
+
+**Key mapping** — canonical `key` values that map to patient profile fields (`data/criterion_keys.json`):
+
+| Criterion key | Resolves to |
+|---|---|
+| `age_years` | `PatientProfile.age` |
+| `symptom_onset_months` | `PatientProfile.onset_months` |
+| `diagnosis_months` | `PatientProfile.diagnosis_months` |
+| `sex` | `PatientProfile.sex` *(field to be added to PatientProfile)* |
+| `ecog_status` | `platform_data["ecog_status"]` |
+| `prior_systemic_therapy_lines` | `platform_data["prior_treatment_lines"]` |
+| `egfr_ml_min` | `platform_data["egfr_ml_min"]` |
+| `anc_per_ul` | `platform_data["anc_per_ul"]` |
+| `hemoglobin_g_dl` | `platform_data["hemoglobin_g_dl"]` |
+| `platelets_per_ul` | `platform_data["platelets_per_ul"]` |
+| `bilirubin_mg_dl` | `platform_data["bilirubin_mg_dl"]` |
+| `creatinine_mg_dl` | `platform_data["creatinine_mg_dl"]` |
+
+Any `key` not in this table and not in `platform_data` produces verdict `unknown`. Add new keys to `data/criterion_keys.json` without touching agent code.
+
+---
+
+### New data model (`models.py`)
+
+```python
+class CriterionVerdict(str, Enum):
+    PASS    = "pass"
+    FAIL    = "fail"
+    UNKNOWN = "unknown"
+
+@dataclass
+class ParsedConstraint:
+    key: str               # canonical patient field name
+    operator: str          # "<=", ">=", "==", "!=", "in", "not_in", "between"
+    value: int | float | str | list
+    unit: str | None       # "months", "years", "mL/min" — for display and mismatch detection
+
+@dataclass
+class EligibilityCriterion:
+    key: str               # e.g. "age_years", "prior_systemic_therapy_lines"
+    type: str              # "inclusion" | "exclusion"
+    description: str       # original human-readable criterion text
+    raw_criteria: str      # verbatim criterion bullet preserved for patient transparency
+    constraint: ParsedConstraint | None   # None → LLM judgment required
+
+@dataclass
+class CriterionAssessment:
+    criterion: EligibilityCriterion
+    verdict: CriterionVerdict
+    reason: str            # what the trial requires vs. what we know
+    patient_value: str | None   # patient's value for this criterion key
+    confidence: str        # "high" | "medium" | "low"
+
+@dataclass
+class TrialEligibilityReport:
+    nct_id: str
+    overall_verdict: CriterionVerdict
+    assessments: list[CriterionAssessment]
+    missing_data_keys: list[str]   # fields needed but unavailable
+```
+
+Overall verdict logic:
+- `FAIL` if any criterion is `fail`
+- `UNKNOWN` if no `fail` but any `unknown`
+- `PASS` only if every criterion is `pass`
+
+### New agent (`agents/eligibility.py`)
+
+Three public functions:
+
+```python
+def run_eligibility_check(
+    client: anthropic.Anthropic,
+    trial: dict,                    # flattened trial record from trials_api
+    patient: PatientProfile,
+    platform_data: dict | None = None,
+) -> TrialEligibilityReport: ...
+
+def check_trials_inline(
+    client: anthropic.Anthropic,
+    trials: list[dict],
+    patient: PatientProfile,
+    platform_data: dict | None = None,
+    top_n: int = 10,                # cap to avoid excessive LLM calls
+) -> list[dict]: ...                # returns trials with "eligibility_report" key added
+
+def stream_eligibility_check(
+    client: anthropic.Anthropic,
+    trial: dict,
+    patient: PatientProfile,
+    platform_data: dict | None = None,
+) -> Generator[str, None, None]: ...
+```
+
+`check_trials_inline` is the function called by `agents/research.py` — it runs eligibility on the top N trials (by distance) and embeds a serialized report under `trial["eligibility_report"]` so the research LLM can incorporate verdicts into its synthesis.
+
+`platform_data` is the integration seam — partner-supplied values resolve criteria that would otherwise be `unknown`.
+
+Internal flow of `run_eligibility_check`:
+1. **Parse step** — LLM call with `parse_criteria` tool on `trial["eligibility"]` → `list[EligibilityCriterion]`
+2. Load `data/criterion_keys.json` (loaded once at module import as `_KEY_MAP`)
+3. **Assess step** per criterion:
+   - **Path A (deterministic)**: constraint not None + patient value known → evaluate in code → `confidence: "high"`
+   - **Path B (LLM)**: constraint None or patient value missing → batched `assess_eligibility` tool call → `confidence: "medium"` or `"low"`
+4. Collect `missing_data_keys`, compute overall verdict, return `TrialEligibilityReport`
+
+`eligibility_report` embedded in each trial dict:
+```json
+{
+  "overall": "fail",
+  "assessments": [
+    {
+      "verdict": "pass",
+      "description": "Age meets requirement",
+      "reason": "Requires between [18, 75]; patient value: 42",
+      "confidence": "high",
+      "raw_criteria": "Age 18 to 75 years"
+    },
+    {
+      "verdict": "unknown",
+      "description": "eGFR >= 60 mL/min",
+      "reason": "Lab value not on file",
+      "confidence": "medium",
+      "raw_criteria": "Adequate renal function: eGFR >= 60 mL/min"
+    }
+  ],
+  "missing_data_keys": ["egfr_ml_min"]
+}
+```
+
+### New tool schema (`data/tools/assess_eligibility.json`)
+
+The LLM uses a structured tool call to emit verdicts — no free-form text output for verdicts.
+
+```json
+{
+  "type": "object",
+  "required": ["assessments", "missing_data_keys"],
+  "properties": {
+    "assessments": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "required": ["criterion_key", "verdict", "reason", "confidence"],
+        "properties": {
+          "criterion_key":  { "type": "string" },
+          "verdict":        { "enum": ["pass", "fail", "unknown"] },
+          "reason":         { "type": "string" },
+          "patient_value":  { "type": ["string", "null"] },
+          "confidence":     { "enum": ["medium", "low"] },
+          "raw_criteria":   { "type": "string" }
+        }
+      }
+    },
+    "missing_data_keys": {
+      "type": "array",
+      "items": { "type": "string" }
+    }
+  }
+}
+```
+
+### Assessment pipeline (Step 2 of 2)
+
+Assessment is a two-path process per criterion:
+
+**Path A — deterministic** (when `constraint` is not null and patient value is known):
+- Evaluate `patient_value <operator> constraint.value` directly in code — no LLM needed
+- Verdict is `pass` or `fail` with `confidence: "high"`
+- Example: `onset_months=18`, constraint `<= 24` → `pass`
+
+**Path B — LLM judgment** (when `constraint` is null, or patient value is missing):
+- Pass criterion description + available patient context to the LLM via `assess_eligibility` tool
+- If patient value is missing → verdict must be `unknown`, never assumed `pass`
+- LLM sets `confidence: "medium"` or `"low"` based on criterion clarity
+
+### Judgment rules (system prompt constraints for Path B)
+
+1. If data to assess a criterion is missing → `unknown`, never assume `pass`
+2. Confidence is `high` only for deterministic Path A evaluations — LLM assessments are at most `medium`
+3. For exclusion criteria: if patient value matches the exclusion → `fail` with explicit reason
+4. `missing_data_keys` must list every criterion key the agent could not assess due to missing patient data
+
+### UI rendering (`app.py`)
+
+```
+Trial NCT123456 — Phase 2 — Sponsor X
+
+  ✓  Age 42 — meets requirement (≥ 16 and ≤ 64)
+  ✓  Disease confirmed — meets inclusion criteria
+  ✗  Prior chemotherapy — trial excludes ≥ 2 prior lines (patient has 3)
+  !  eGFR — trial requires ≥ 60 mL/min — lab value not on file
+
+  Overall: Not eligible
+  Missing information: eGFR — ask your care team
+```
+
+Rendering rules:
+- ✓ green, ✗ red, ! amber
+- `fail` reasons always visible — never collapsed
+- `unknown` items show what data would resolve them
+- Overall badge: red "Not eligible" / amber "Likely eligible — missing info" / green "Eligible"
+
+---
+
+## Integration seam for the external platform
+
+`PatientProfile` gets one new optional field:
+
+```python
+platform_data: dict | None = None
+# e.g. {"prior_treatment_lines": 2, "ecog_status": 1, "egfr_ml_min": 55}
+```
+
+The eligibility agent maps known platform keys → criterion keys at assessment time. When a platform value is present, the criterion moves from `unknown` to a real verdict. This is the value-add for the integration partner — their data directly reduces the number of `!` items shown to the patient.
+
+
+---
+
+## Decisions
+
+**Eligibility runs inline** — no extra API call. Triggered automatically for the top 10 closest trials after each `search_clinical_trials` tool call. All results shown to patient; clinician and patient decide whether to pursue.
+
+**`raw_criteria` is always preserved** — verbatim criterion text is stored in every `EligibilityCriterion` and echoed in the report. Trust requires traceability: the patient can see exactly what the trial says, not just our interpretation.
+
+**After parsing, raw eligibility blob is not stored** — the structured `eligibility_report` replaces it. Unstructured fields like experiment description are not carried forward.
+
+**Key mapping lives in `data/criterion_keys.json`** — add new platform fields there without touching agent code.

models.py

@@ -2,6 +2,8 @@ from __future__ import annotations
 
 import math
 from dataclasses import dataclass, field
+from enum import Enum
+from typing import Union
 
 import httpx
 
@@ -55,6 +57,46 @@ class PatientProfile:
         return "\n".join(lines)
 
 
+class CriterionVerdict(str, Enum):
+    PASS    = "pass"
+    FAIL    = "fail"
+    UNKNOWN = "unknown"
+
+
+@dataclass
+class ParsedConstraint:
+    key: str
+    operator: str       # "<=", ">=", "==", "!=", "in", "not_in", "between"
+    value: Union[int, float, str, list]
+    unit: str | None
+
+
+@dataclass
+class EligibilityCriterion:
+    key: str
+    type: str           # "inclusion" | "exclusion"
+    description: str
+    raw_criteria: str   # verbatim criterion text preserved for patient transparency
+    constraint: ParsedConstraint | None
+
+
+@dataclass
+class CriterionAssessment:
+    criterion: EligibilityCriterion
+    verdict: CriterionVerdict
+    reason: str
+    patient_value: str | None
+    confidence: str     # "high" (deterministic) | "medium" | "low" (LLM)
+
+
+@dataclass
+class TrialEligibilityReport:
+    nct_id: str
+    overall_verdict: CriterionVerdict
+    assessments: list[CriterionAssessment]
+    missing_data_keys: list[str]
+
+
 def geocode_zip(zip_code: str, country_code: str = "US") -> tuple[float, float]:
     resp = httpx.get(
         "https://nominatim.openstreetmap.org/search",

prompts.py

@@ -35,8 +35,8 @@ Collect the following through a warm, conversational interview — do NOT presen
 REQUIRED:
   • Disease/condition (standardize: "Lou Gehrig's" → "Amyotrophic Lateral Sclerosis")
   • Patient age
-  • Months since first symptom onset (convert dates/years as needed)
-  • Months since formal/official diagnosis (convert dates/years as needed; may differ from onset)
+  • Date of first symptom onset (ask for month and year; submit as onset_date in YYYY-MM format)
+  • Date of formal/official diagnosis (ask for month and year; submit as diagnosis_date in YYYY-MM format; may differ from onset)
   • ZIP/postal code and country for geographic search
 
 OPTIONAL (disease-specific benchmarks):
@@ -73,7 +73,7 @@ OPTIONAL (disease-specific benchmarks):
         but may be an option when no approved treatments remain.
       - Or any combination; or all types (default if no preference)
 
-Ask naturally. You may infer disease synonyms and convert dates to months, but never infer or skip the ZIP/postal code — always ask the patient for it directly. Once you have every required field confirmed by the patient, call submit_profile.\
+Ask naturally. You may infer disease synonyms. For onset and diagnosis dates, always submit the raw YYYY-MM date strings (onset_date, diagnosis_date) — never compute months yourself. Never infer or skip the ZIP/postal code — always ask the patient for it directly. Once you have every required field confirmed by the patient, call submit_profile.\
 """
 
 
@@ -110,9 +110,18 @@ Workflow:
    **Contact:** [Phone number] | [Email address] (use "Not listed" for any missing field)
    **Summary:** [2–3 sentence plain-language description of what the trial/program is testing
                and why it may matter for this patient]
-   **Qualification criteria:** [Key inclusion AND exclusion criteria relevant to this patient,
-                               including age range, functional score thresholds, FVC cutoffs,
-                               and any red flags. Be specific — use exact numbers from the data.]
+   **Eligibility:** Build a checklist from the trial's parsed_criteria and deterministic_verdicts.
+   For each criterion in parsed_criteria:
+     - If it appears in deterministic_verdicts, use that verdict directly (confidence: high).
+     - Otherwise assess it yourself using the patient profile. If patient data is missing → use !.
+   Use one line per criterion:
+     ✓ [description] — [reason]          ← patient meets this criterion
+     ✗ [description] — [reason]          ← patient does not meet this criterion
+     ! [description] — [reason]          ← insufficient data to confirm
+   After the checklist add one bold summary line:
+     **Overall: Eligible** / **Overall: Not eligible** / **Overall: Likely eligible — confirm missing info**
+   If any ! criteria exist, add: *Missing info: [list what data would resolve each] — ask your care team.*
+   If parsed_criteria is absent for a trial, omit this section entirely.
    **Link:** https://clinicaltrials.gov/study/[NCT_ID]
 
    ---

tools.py

@@ -45,5 +45,41 @@ SEARCH_TRIALS_TOOL: anthropic.types.ToolParam = {
     "input_schema": _load("search_trials"),
 }
 
+PARSE_CRITERIA_BULK_TOOL: anthropic.types.ToolParam = {
+    "name": "parse_criteria_bulk",
+    "description": (
+        "Parse raw eligibility criteria text for multiple trials in one call. "
+        "For each trial, extract every inclusion and exclusion criterion. "
+        "Produce a structured constraint where possible (numeric ranges, enums, comparisons); "
+        "set constraint to null for vague, subjective, or compound criteria."
+    ),
+    "input_schema": _load("parse_criteria_bulk"),
+}
+
+PARSE_CRITERIA_TOOL: anthropic.types.ToolParam = {
+    "name": "parse_criteria",
+    "description": (
+        "Parse raw eligibility criteria text into structured criterion objects. "
+        "For each criterion, extract a canonical key, inclusion/exclusion type, "
+        "and a structured constraint where possible (numeric ranges, enums, comparisons). "
+        "Set constraint to null for vague, subjective, or compound criteria that cannot "
+        "be expressed as a single structured comparison."
+    ),
+    "input_schema": _load("parse_criteria"),
+}
+
+ASSESS_ELIGIBILITY_TOOL: anthropic.types.ToolParam = {
+    "name": "assess_eligibility",
+    "description": (
+        "Assess whether a patient meets eligibility criteria that cannot be evaluated "
+        "deterministically. Only called for criteria where a structured constraint is "
+        "unavailable or patient data is missing. "
+        "Use verdict 'unknown' when patient data is insufficient — never assume 'pass'. "
+        "Confidence is 'medium' or 'low' only; 'high' is reserved for deterministic evaluation."
+    ),
+    "input_schema": _load("assess_eligibility"),
+}
+
 INTAKE_TOOLS: list[anthropic.types.ToolParam] = [SUBMIT_PROFILE_TOOL, IDENTIFY_DISEASE_TOOL]
 RESEARCH_TOOLS: list[anthropic.types.ToolParam] = [SEARCH_TRIALS_TOOL]
+ELIGIBILITY_TOOLS: list[anthropic.types.ToolParam] = [PARSE_CRITERIA_TOOL, ASSESS_ELIGIBILITY_TOOL]

trials_api.py

@@ -26,7 +26,7 @@ def search_trials_api(
         "query.cond": condition,
         "filter.overallStatus": "AVAILABLE" if is_eap else "RECRUITING",
         "filter.geo": f"distance({lat},{lon},{radius_miles}mi)",
-        "pageSize": 200,
+        "pageSize": 1000,
         "format": "json",
     }
     # aggFilters supports comma-separated keys (e.g. "studyType:exp,phase:3 4").
@@ -106,6 +106,8 @@ def _flatten_and_rank(studies: list[dict], patient_lat: float, patient_lon: floa
         contacts_mod = proto.get("contactsLocationsModule", {})
         sponsor_mod = proto.get("sponsorCollaboratorsModule", {})
         design_mod = proto.get("designModule", {})
+        conditions_mod = proto.get("conditionsModule", {})
+        arms_mod = proto.get("armsInterventionsModule", {})
 
         central_contacts = contacts_mod.get("centralContacts", [])
         central_phone = next((c.get("phone", "") for c in central_contacts if c.get("phone")), "")
@@ -150,10 +152,25 @@ def _flatten_and_rank(studies: list[dict], patient_lat: float, patient_lon: floa
             "principal_investigator": pi,
             "contact_phone": central_phone,
             "contact_email": central_email,
-            "summary": desc_mod.get("briefSummary", "")[:500],
-            "eligibility": elig_mod.get("eligibilityCriteria", "")[:1000],
+            "summary": desc_mod.get("briefSummary", ""),
+            "eligibility": elig_mod.get("eligibilityCriteria", ""),
             "min_age": elig_mod.get("minimumAge", ""),
             "max_age": elig_mod.get("maximumAge", ""),
+            "sex": elig_mod.get("sex", "ALL"),
+            "healthy_volunteers": elig_mod.get("healthyVolunteers", ""),
+            "std_ages": elig_mod.get("stdAges", []),
+            "study_type": design_mod.get("studyType", ""),
+            "enrollment": design_mod.get("enrollmentInfo", {}).get("count"),
+            "conditions": conditions_mod.get("conditions", []),
+            "keywords": conditions_mod.get("keywords", []),
+            "interventions": [
+                {
+                    "type": iv.get("type", ""),
+                    "name": iv.get("name", ""),
+                    "description": iv.get("description", ""),
+                }
+                for iv in arms_mod.get("interventions", [])
+            ],
             "closest_site_miles": round(closest_dist, 1) if closest_dist is not None else None,
             "nearest_sites": [info for _, info in sites_with_dist[:5]],
         })