# OpenMedicine v1.0 — "UpToDate for Agents"

## Vision

Make OpenMedicine capable of transforming any MCP-connected agent into a super medical agent with UpToDate-level context at minimal latency and maximal accuracy. OpenMedicine remains the infrastructure layer (MCP server); agents build on top.

## Priority Order

| Priority | Feature | Approach |
|----------|---------|---------|
| D | Clinical workflow tools | Differential diagnosis + Treatment pathways |
| C | Smarter retrieval | Semantic search via pre-computed embeddings |
| A | Clinical reasoning orchestration | Routing engine — recommends tools, agent executes |
| B | Depth of content | Grow organically (lowest priority) |

## Phase 1: Clinical Workflow Tools (D)

### Differential Diagnosis (D2)

Two new MCP tools: `search_differential_diagnosis` and `get_differential_diagnosis`.

**Input:** Symptoms, findings, patient demographics (structured Pydantic model).

**Output:** Ranked list of diagnoses, each with:
- Likelihood category (common / less common / must-not-miss)
- Key distinguishing features
- Recommended tests/calculators to narrow down
- Red flags
- DOI-backed evidence
- Links to relevant OpenMedicine guidelines

**Content storage:** Structured data files (JSON), curated per clinical presentation. Follows the same registry pattern as calculators.

### Treatment Pathways (D4)

Two new MCP tools: `search_treatment_pathways` and `get_treatment_pathway`.

**Input:** Diagnosis + patient context (comorbidities, contraindications).

**Output:** Structured decision tree:
- First-line -> second-line -> escalation
- At each node: medication/intervention, dosing, monitoring, contraindications
- Guideline citations (DOI) at every decision point
- Cross-references to relevant calculators (e.g., "calculate renal function before dosing")

**Content storage:** Structured JSON/data files per diagnosis, following the same registry pattern.

## Phase 2: Semantic Search (C)

### Architecture

**Build time (release):** Embed all content (calculator descriptions, guideline titles/topics/summaries, differential/pathway tags) via embedding API. Store as `embeddings.json` in the package.

**Runtime (per query):** One API call to embed the query, then local cosine similarity against pre-computed embeddings. No vector DB.

### Key Details

- **Embedding scope:** One embedding per "searchable unit" (calculator, guideline, differential, pathway).
- **Storage:** Single `embeddings.json` file. ~500 entries x 1536 dims = ~3MB.
- **Runtime dependency:** One embedding API call per search. Provider configurable (OpenAI default, swappable).
- **Fallback:** No API key configured -> existing substring search still works.
- **Build tool:** `generate_embeddings.py` CLI reads all registries, calls embedding API, writes `embeddings.json`. Run once per release.

### Tool Changes

- `search_clinical_calculators` and `search_guidelines` upgrade to semantic search transparently (fallback to substring).
- New unified tool: `search_medical_knowledge` — searches across all content types (calculators, guidelines, differentials, pathways) in a single call. Primary entry point for agents.

## Phase 3: Clinical Routing Engine (A)

### assess_clinical_scenario

One new MCP tool.

**Input:** Structured clinical description with free-text description + structured context (age, sex, conditions, medications).

**Output:** Prioritized action plan — what tools to run, in what order, and why. Includes:
- Ordered list of recommended actions (calculators, guidelines, pathways, differentials)
- Parameter hints where determinable from context
- Clinical warnings
- Evidence

### How It Works

- **Rule-based routing, not LLM-based.** Deterministic mapping: condition -> relevant calculators + guidelines + pathways. No AI inference inside OpenMedicine.
- **Routing rules stored as structured data** (JSON/Python), same registry pattern.
- **Agent stays in control.** Receives recommendations, decides what to execute. OpenMedicine is the clinical librarian, not the clinician.

## Complete MCP Tool Surface (10 tools)

### Existing (upgraded)

| Tool | Change |
|------|--------|
| `search_clinical_calculators` | Semantic search when embeddings available |
| `execute_clinical_calculator` | No change |
| `search_guidelines` | Semantic search when embeddings available |
| `retrieve_guideline` | No change |

### New

| Tool | Phase | Purpose |
|------|-------|---------|
| `search_medical_knowledge` | 2 | Unified semantic search across all content types |
| `search_differential_diagnosis` | 1 | Find differentials by symptoms/presentation |
| `get_differential_diagnosis` | 1 | Retrieve full differential with evidence |
| `search_treatment_pathways` | 1 | Find pathways by diagnosis |
| `get_treatment_pathway` | 1 | Retrieve structured treatment decision tree |
| `assess_clinical_scenario` | 3 | Clinical routing — recommends what tools to run |

## Design Principles

1. **Deterministic over probabilistic.** No LLM inference inside OpenMedicine. Rule-based routing, structured data, DOI-backed evidence.
2. **MCP-native.** Every capability is an MCP tool. Agents integrate by connecting to the server.
3. **Independently shippable phases.** Each phase delivers standalone value.
4. **Graceful degradation.** Semantic search falls back to substring. New tools coexist with old ones.
5. **Same patterns.** New content types follow the existing registry + structured data + Pydantic model conventions.
