README.md

metadata

title: Beacon Trial Finder
emoji: 📚
colorFrom: gray
colorTo: yellow
sdk: gradio
sdk_version: 6.14.0
python_version: '3.13'
app_file: app.py
pinned: false
license: mit
short_description: help patients with rare disease to find clinical trials

Beacon — Rare Disease Clinical Trial Finder

Beacon is a conversational AI assistant that helps patients with rare diseases find relevant recruiting clinical trials near them. It conducts a warm intake interview, geocodes the patient's location, queries ClinicalTrials.gov in real time, and produces a ranked report of the closest matching trials.

How it works

1. Intake agent (Claude Sonnet) — interviews the patient conversationally to collect disease, age, symptom onset date, formal diagnosis date, location, preferred trial phases, and whether they are interested in Expanded Access Programs (EAP / compassionate use).
2. Research agent (Claude Opus) — searches ClinicalTrials.gov via the official v2 API for clinical trials and/or EAP listings, retrying with synonyms or wider radii if results are sparse, then outputs a ranked report with eligibility notes and next steps.
3. LangGraph orchestrates the two-node pipeline (intake → research).

Clinical trial phases explained

Phase	Focus	Typical size
Early Phase 1	First-in-human safety; tiny doses	~10–15 people
Phase 1	Safe dosage range and side effects	20–80 people
Phase 2	Does it work? Continued safety	100–300 people
Phase 3	vs. standard of care; required for FDA approval	1,000–3,000 people
Phase 4	Post-approval long-term surveillance	Varies

Expanded Access Programs (EAP)

EAP (also called compassionate use) allows patients who do not qualify for or cannot access a clinical trial to receive an investigational drug or device outside of a formal trial. The treatment is not yet FDA-approved; a physician must submit the EAP request to the drug sponsor and obtain FDA authorization. Beacon can search for available EAP listings alongside clinical trials.

Project setup

Prerequisites

• Python 3.11+
• uv (recommended) or pip

1. Clone the repo

git clone <repo-url>
cd beacon

2. Install dependencies

uv sync

Or with pip:

pip install -e .

3. Configure API keys

Copy the example env file and fill in your keys:

cp .env.example .env

Open .env and replace the placeholder values:

ANTHROPIC_API_KEY=your_anthropic_api_key_here

4. Run

uv run python app.py

Hot-reload during development

Use the gradio CLI to automatically reload the app whenever you save a file — no manual restart needed:

uv run gradio app.py

Note: Active user sessions are reset on each reload.

Configuration

Environment variable	Default	Description
ANTHROPIC_API_KEY	(required)	Anthropic API key

Project structure

beacon/
├── app.py                   # Gradio web UI entry point
├── main.py                  # Terminal entry point
├── clinical_trials_guru.py  # Intake + research agents, LangGraph pipeline
├── llm.py                   # LLM provider abstraction
├── requirements.txt         # HuggingFace Spaces dependencies
├── pyproject.toml
└── .env                     # Local secrets — not committed