Initial release: Beacon rare disease clinical trial finder

Conversational AI assistant that interviews patients, geocodes their location,
and searches ClinicalTrials.gov in real time to surface nearby recruiting trials.

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

README.md

@@ -113,5 +113,82 @@ license: mit
 short_description: help patients with rare disease to find clinical trials
 ---
 
+<<<<<<< HEAD
 Check out the configuration reference at https://huggingface.co/docs/hub/spaces-config-reference
 >>>>>>> 2a6ee87 (initial commit)
+=======
+# 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](https://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, location, and optional benchmark scores.
+2. **Research agent** (Claude Opus) — searches ClinicalTrials.gov via the official v2 API, retrying with synonyms or wider radii if results are sparse, then outputs a ranked trial report with eligibility notes and next steps.
+3. **LangGraph** orchestrates the two-node pipeline (intake → research).
+
+## Project setup
+
+### Prerequisites
+
+- Python 3.11+
+- [`uv`](https://docs.astral.sh/uv/) (recommended) or `pip`
+
+### 1. Clone the repo
+
+```bash
+git clone <repo-url>
+cd beacon
+```
+
+### 2. Install dependencies
+
+```bash
+uv sync
+```
+
+Or with pip:
+
+```bash
+pip install -e .
+```
+
+### 3. Configure API keys
+
+Copy the example env file and fill in your keys:
+
+```bash
+cp .env.example .env
+```
+
+Open `.env` and replace the placeholder values:
+
+```env
+ANTHROPIC_API_KEY=your_anthropic_api_key_here
+```
+
+### 4. Run
+
+```bash
+uv run python app.py
+```
+
+## 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
+```
+>>>>>>> f8d77e4 (Initial release: Beacon rare disease clinical trial finder)

pyproject.toml

@@ -10,5 +10,8 @@ dependencies = [
     "openai>=1.0.0",
     "python-dotenv>=1.2.2",
     "rich>=13.0.0",
+<<<<<<< HEAD
     "gradio>=4.0.0",
+=======
+>>>>>>> f8d77e4 (Initial release: Beacon rare disease clinical trial finder)
 ]

uv.lock

@@ -1,6 +1,7 @@
 version = 1
 revision = 3
 requires-python = ">=3.11"
+<<<<<<< HEAD
 resolution-markers = [
     "python_full_version >= '3.14' and sys_platform == 'win32'",
     "python_full_version >= '3.14' and sys_platform == 'emscripten'",
@@ -21,6 +22,8 @@ sdist = { url = "https://files.pythonhosted.org/packages/57/ba/046ceea2734456098
 wheels = [
     { url = "https://files.pythonhosted.org/packages/1e/d3/26bf1008eb3d2daa8ef4cacc7f3bfdc11818d111f7e2d0201bc6e3b49d45/annotated_doc-0.0.4-py3-none-any.whl", hash = "sha256:571ac1dc6991c450b25a9c2d84a3705e2ae7a53467b5d111c24fa8baabbed320", size = 5303, upload-time = "2025-11-10T22:07:40.673Z" },
 ]
+=======
+>>>>>>> f8d77e4 (Initial release: Beacon rare disease clinical trial finder)
 
 [[package]]
 name = "annotated-types"
@@ -64,6 +67,7 @@ wheels = [
 ]
 
 [[package]]
+<<<<<<< HEAD
 name = "audioop-lts"
 version = "0.2.2"
 source = { registry = "https://pypi.org/simple" }
@@ -120,12 +124,17 @@ wheels = [
 ]
 
 [[package]]
+=======
+>>>>>>> f8d77e4 (Initial release: Beacon rare disease clinical trial finder)
 name = "beacon"
 version = "0.1.0"
 source = { virtual = "." }
 dependencies = [
     { name = "anthropic" },
+<<<<<<< HEAD
     { name = "gradio" },
+=======
+>>>>>>> f8d77e4 (Initial release: Beacon rare disease clinical trial finder)
     { name = "langgraph" },
     { name = "openai" },
     { name = "python-dotenv" },
@@ -135,7 +144,10 @@ dependencies = [
 [package.metadata]
 requires-dist = [
     { name = "anthropic", specifier = ">=0.50.0" },
+<<<<<<< HEAD
     { name = "gradio", specifier = ">=4.0.0" },
+=======
+>>>>>>> f8d77e4 (Initial release: Beacon rare disease clinical trial finder)
     { name = "langgraph", specifier = ">=1.2.0" },
     { name = "openai", specifier = ">=1.0.0" },
     { name = "python-dotenv", specifier = ">=1.2.2" },
@@ -143,6 +155,7 @@ requires-dist = [
 ]
 
 [[package]]
+<<<<<<< HEAD
 name = "brotli"
 version = "1.2.0"
 source = { registry = "https://pypi.org/simple" }
@@ -191,6 +204,8 @@ wheels = [
 ]
 
 [[package]]
+=======
+>>>>>>> f8d77e4 (Initial release: Beacon rare disease clinical trial finder)
 name = "certifi"
 version = "2026.4.22"
 source = { registry = "https://pypi.org/simple" }
@@ -289,6 +304,7 @@ wheels = [
 ]
 
 [[package]]
+<<<<<<< HEAD
 name = "click"
 version = "8.3.3"
 source = { registry = "https://pypi.org/simple" }
@@ -301,6 +317,8 @@ wheels = [
 ]
 
 [[package]]
+=======
+>>>>>>> f8d77e4 (Initial release: Beacon rare disease clinical trial finder)
 name = "colorama"
 version = "0.4.6"
 source = { registry = "https://pypi.org/simple" }
@@ -328,6 +346,7 @@ wheels = [
 ]
 
 [[package]]
+<<<<<<< HEAD
 name = "fastapi"
 version = "0.136.1"
 source = { registry = "https://pypi.org/simple" }
@@ -426,6 +445,8 @@ wheels = [
 ]
 
 [[package]]
+=======
+>>>>>>> f8d77e4 (Initial release: Beacon rare disease clinical trial finder)
 name = "h11"
 version = "0.16.0"
 source = { registry = "https://pypi.org/simple" }
@@ -435,6 +456,7 @@ wheels = [
 ]
 
 [[package]]
+<<<<<<< HEAD
 name = "hf-gradio"
 version = "0.4.1"
 source = { registry = "https://pypi.org/simple" }
@@ -480,6 +502,8 @@ wheels = [
 ]
 
 [[package]]
+=======
+>>>>>>> f8d77e4 (Initial release: Beacon rare disease clinical trial finder)
 name = "httpcore"
 version = "1.0.9"
 source = { registry = "https://pypi.org/simple" }
@@ -508,6 +532,7 @@ wheels = [
 ]
 
 [[package]]
+<<<<<<< HEAD
 name = "huggingface-hub"
 version = "1.14.0"
 source = { registry = "https://pypi.org/simple" }
@@ -528,6 +553,8 @@ wheels = [
 ]
 
 [[package]]
+=======
+>>>>>>> f8d77e4 (Initial release: Beacon rare disease clinical trial finder)
 name = "idna"
 version = "3.14"
 source = { registry = "https://pypi.org/simple" }
@@ -537,6 +564,7 @@ wheels = [
 ]
 
 [[package]]
+<<<<<<< HEAD
 name = "jinja2"
 version = "3.1.6"
 source = { registry = "https://pypi.org/simple" }
@@ -549,6 +577,8 @@ wheels = [
 ]
 
 [[package]]
+=======
+>>>>>>> f8d77e4 (Initial release: Beacon rare disease clinical trial finder)
 name = "jiter"
 version = "0.14.0"
 source = { registry = "https://pypi.org/simple" }
@@ -780,6 +810,7 @@ wheels = [
 ]
 
 [[package]]
+<<<<<<< HEAD
 name = "markupsafe"
 version = "3.0.3"
 source = { registry = "https://pypi.org/simple" }
@@ -854,6 +885,8 @@ wheels = [
 ]
 
 [[package]]
+=======
+>>>>>>> f8d77e4 (Initial release: Beacon rare disease clinical trial finder)
 name = "mdurl"
 version = "0.1.2"
 source = { registry = "https://pypi.org/simple" }
@@ -863,6 +896,7 @@ wheels = [
 ]
 
 [[package]]
+<<<<<<< HEAD
 name = "numpy"
 version = "2.4.4"
 source = { registry = "https://pypi.org/simple" }
@@ -942,6 +976,8 @@ wheels = [
 ]
 
 [[package]]
+=======
+>>>>>>> f8d77e4 (Initial release: Beacon rare disease clinical trial finder)
 name = "openai"
 version = "2.36.0"
 source = { registry = "https://pypi.org/simple" }
@@ -1086,6 +1122,7 @@ wheels = [
 ]
 
 [[package]]
+<<<<<<< HEAD
 name = "pandas"
 version = "3.0.3"
 source = { registry = "https://pypi.org/simple" }
@@ -1233,6 +1270,8 @@ wheels = [
 ]
 
 [[package]]
+=======
+>>>>>>> f8d77e4 (Initial release: Beacon rare disease clinical trial finder)
 name = "pydantic"
 version = "2.13.4"
 source = { registry = "https://pypi.org/simple" }
@@ -1350,6 +1389,7 @@ wheels = [
 ]
 
 [[package]]
+<<<<<<< HEAD
 name = "pydub"
 version = "0.25.1"
 source = { registry = "https://pypi.org/simple" }
@@ -1359,6 +1399,8 @@ wheels = [
 ]
 
 [[package]]
+=======
+>>>>>>> f8d77e4 (Initial release: Beacon rare disease clinical trial finder)
 name = "pygments"
 version = "2.20.0"
 source = { registry = "https://pypi.org/simple" }
@@ -1368,6 +1410,7 @@ wheels = [
 ]
 
 [[package]]
+<<<<<<< HEAD
 name = "python-dateutil"
 version = "2.9.0.post0"
 source = { registry = "https://pypi.org/simple" }
@@ -1380,6 +1423,8 @@ wheels = [
 ]
 
 [[package]]
+=======
+>>>>>>> f8d77e4 (Initial release: Beacon rare disease clinical trial finder)
 name = "python-dotenv"
 version = "1.2.2"
 source = { registry = "https://pypi.org/simple" }
@@ -1389,6 +1434,7 @@ wheels = [
 ]
 
 [[package]]
+<<<<<<< HEAD
 name = "python-multipart"
 version = "0.0.28"
 source = { registry = "https://pypi.org/simple" }
@@ -1407,6 +1453,8 @@ wheels = [
 ]
 
 [[package]]
+=======
+>>>>>>> f8d77e4 (Initial release: Beacon rare disease clinical trial finder)
 name = "pyyaml"
 version = "6.0.3"
 source = { registry = "https://pypi.org/simple" }
@@ -1502,6 +1550,7 @@ wheels = [
 ]
 
 [[package]]
+<<<<<<< HEAD
 name = "safehttpx"
 version = "0.1.7"
 source = { registry = "https://pypi.org/simple" }
@@ -1541,6 +1590,8 @@ wheels = [
 ]
 
 [[package]]
+=======
+>>>>>>> f8d77e4 (Initial release: Beacon rare disease clinical trial finder)
 name = "sniffio"
 version = "1.3.1"
 source = { registry = "https://pypi.org/simple" }
@@ -1550,6 +1601,7 @@ wheels = [
 ]
 
 [[package]]
+<<<<<<< HEAD
 name = "starlette"
 version = "1.0.0"
 source = { registry = "https://pypi.org/simple" }
@@ -1563,6 +1615,8 @@ wheels = [
 ]
 
 [[package]]
+=======
+>>>>>>> f8d77e4 (Initial release: Beacon rare disease clinical trial finder)
 name = "tenacity"
 version = "9.1.4"
 source = { registry = "https://pypi.org/simple" }
@@ -1572,6 +1626,7 @@ wheels = [
 ]
 
 [[package]]
+<<<<<<< HEAD
 name = "tomlkit"
 version = "0.14.0"
 source = { registry = "https://pypi.org/simple" }
@@ -1581,6 +1636,8 @@ wheels = [
 ]
 
 [[package]]
+=======
+>>>>>>> f8d77e4 (Initial release: Beacon rare disease clinical trial finder)
 name = "tqdm"
 version = "4.67.3"
 source = { registry = "https://pypi.org/simple" }
@@ -1593,6 +1650,7 @@ wheels = [
 ]
 
 [[package]]
+<<<<<<< HEAD
 name = "typer"
 version = "0.25.1"
 source = { registry = "https://pypi.org/simple" }
@@ -1608,6 +1666,8 @@ wheels = [
 ]
 
 [[package]]
+=======
+>>>>>>> f8d77e4 (Initial release: Beacon rare disease clinical trial finder)
 name = "typing-extensions"
 version = "4.15.0"
 source = { registry = "https://pypi.org/simple" }
@@ -1629,6 +1689,7 @@ wheels = [
 ]
 
 [[package]]
+<<<<<<< HEAD
 name = "tzdata"
 version = "2026.2"
 source = { registry = "https://pypi.org/simple" }
@@ -1638,6 +1699,8 @@ wheels = [
 ]
 
 [[package]]
+=======
+>>>>>>> f8d77e4 (Initial release: Beacon rare disease clinical trial finder)
 name = "urllib3"
 version = "2.7.0"
 source = { registry = "https://pypi.org/simple" }
@@ -1747,6 +1810,7 @@ wheels = [
 ]
 
 [[package]]
+<<<<<<< HEAD
 name = "uvicorn"
 version = "0.47.0"
 source = { registry = "https://pypi.org/simple" }
@@ -1760,6 +1824,8 @@ wheels = [
 ]
 
 [[package]]
+=======
+>>>>>>> f8d77e4 (Initial release: Beacon rare disease clinical trial finder)
 name = "xxhash"
 version = "3.7.0"
 source = { registry = "https://pypi.org/simple" }