CLAUDE.md

# 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` |