implementation_plan.md

# Clinical Trial Design Assistant — Universal
**Implementation Plan v1.0**

---

## Executive Summary

The **Clinical Trial Design Assistant (Universal)** is an AI-powered chatbot that helps clinical researchers design rigorous, regulatory-grade clinical trials for **any disease, condition, or therapeutic area**. It provides evidence-based recommendations grounded in ClinicalTrials.gov, PubMed, and regulatory guidance — serving as a strategic partner across the entire drug development continuum.

**Primary Users**: Clinical researchers designing trials across all therapeutic areas.

> [!NOTE]
> This is a **new standalone project**, distinct from the PTCL-specific [Clinical-Trial-Design-Assistant](file:///Users/hgibriel/Desktop/IG/Clinical-Trial-Design-Assistant). Same architecture, universal scope.

---

## 1. Problem & Solution Overview

| 🚨 **Current Challenges** | ✅ **Our Solution** |
|---------------------------|---------------------|
| **Information Overload** — 500,000+ trials make research slow | **Evidence-Based Recommendations** — Automated retrieval of proven trial designs |
| **Therapeutic Complexity** — Each disease area has unique design considerations | **Universal Expertise** — Adapts to any indication, from oncology to gene therapy |
| **Regulatory Uncertainty** — Unclear reasons for past FDA/EMA outcomes | **Regulatory Intelligence** — Extracts success factors across jurisdictions |
| **Statistical Rigor** — Complex specialized expertise required | **Statistical Guidance** — Sample size, power calculations, endpoint selection |

**How It Works**:
```
Clinician types: "Design a Phase 3 trial for relapsed DLBCL with a novel BTK inhibitor"

Chatbot returns:
→ Mandatory input confirmation checklist
→ Inclusion/exclusion criteria
→ Primary endpoint: PFS (with regulatory precedent)
→ Sample size: 300–400 (with power calculation)
→ Comparator: R-CHOP or investigator's choice
→ Regulatory pathway: Breakthrough Therapy + accelerated approval
→ Evidence: NCT IDs, PMIDs, regulatory citations
```

---

## 2. Architecture Overview

### High-Level Architecture

```mermaid
flowchart LR
    classDef large font-size:22px,stroke-width:2px;

    A["User Question"]:::large --> B["Claude\nwith Web Search"]:::large
    B <--> C["Real-time\nWeb Search"]:::large
    C <--> D["ClinicalTrials.gov\n+ PubMed"]:::large
    B --> E["Structured\nRecommendations"]:::large
```

### Detailed Processing Flow

```mermaid
flowchart TD
    A[User Query] -->|1. Submit question| B[Session Memory Check]
    B -->|2. Load context| C["Claude + System Prompt"]
    C -->|3. Web search queries| D["ClinicalTrials.gov\n+ PubMed + Regulatory"]
    D -->|4. Return search results| C
    C -->|5. Analyze with guardrails| E{Validation}
    E -->|Pass| F[Generate Recommendations]
    E -->|Fail: Missing context| G[Ask User for Inputs]
    E -->|Fail: Invalid data| H[Error Handler]
    G -->|Collect required info| A
    H -->|Retry or show error| I[User Notification]
    F -->|6. Format output| J[Streamlit Display]
    J -->|7. Store in session| K[Session Memory]
    K -->|8. Follow-up?| A
    K -->|Done| L[End]
    
    style C fill:#e1f5ff
    style E fill:#fff4e1
    style F fill:#e8f5e9
    style J fill:#f3e5f5
```

### Key Difference from PTCL Version

| PTCL-Specific | Universal |
|---------------|-----------|
| Hardcoded disease hierarchy (AITL > ALCL-ALK- > PTCL-NOS) | No hardcoded hierarchy — adapts to user-defined disease |
| Orphan drug fallback with predefined related diseases | "Ask first" approach — Claude requests missing context |
| Fixed comparator categories (GDP, BBv, etc.) | Dynamic comparator framework (SOC, active, placebo, synthetic) |
| PTCL-specific validation (TCL disease match check) | Universal validation (NCT format, realistic values only) |

---

### Technology Stack

> [!NOTE]
> Identical to the PTCL-specific project — same stack, same infrastructure.

| Component | Technology | Rationale |
|-----------|------------|-----------|
| **Frontend** | Streamlit | Simple chat interface, no coding required for users |
| **Memory** | `st.session_state` | Maintains conversation history across turns |
| **AI Engine** | Claude claude-sonnet-4-5-20250929 | Best-in-class medical text understanding |
| **Data Access** | Native Web Search | Claude's built-in web search tool (`web_search_20250305`) |
| **Sources** | ClinicalTrials.gov + PubMed | Real-time clinical trial and literature search |
| **Deployment** | Docker on HuggingFace Spaces | Free hosting, web-accessible |

---

### Project Structure

```
Clinical-Trial-Design-Assistant-Universal/
├── app.py                  # Main Streamlit app + Claude integration
├── requirements.txt        # Python dependencies
├── Dockerfile              # Container configuration
├── README.md               # Documentation
├── CHANGELOG.md            # Version history
├── .gitignore              # Git ignore file
├── prompts/
│   ├── __init__.py
│   └── system_prompt.py    # Disease-agnostic system prompt
├── config/
│   ├── __init__.py
│   └── settings.py         # All configuration settings
├── docs/
│   └── SYSTEM PROMPT_Clinical Trial Designer_1.docx  # Original system prompt reference
└── .streamlit/
    └── secrets.toml        # API key (gitignored)
```

---

## 3. System Prompt

The full prompt is stored in `prompts/system_prompt.py`. The original reference document is preserved in `docs/SYSTEM PROMPT_Clinical Trial Designer_1.docx`.

<details>
<summary><strong>Click to expand full system prompt</strong></summary>

```
You are an expert Clinical Trial Design Assistant with deep knowledge across all therapeutic areas, regulatory jurisdictions, and drug development paradigms.

ROLE
* Design rigorous, regulatory-grade clinical trials for any disease, condition, or therapeutic area
* Ground every recommendation in verifiable evidence: ClinicalTrials.gov (NCT IDs), peer-reviewed literature (PMIDs), and official regulatory guidance (FDA, EMA, ICH, PMDA, Health Canada)
* Serve as a strategic partner — not just a protocol generator — anticipating design pitfalls, regulatory challenges, and feasibility constraints
* Support decisions across the entire development continuum: from FIH (First-in-Human) through Phase I/II/III/IV and post-marketing commitments

NON-NEGOTIABLE RULES
1. Never fabricate data. Every trial cited must be real and verifiable. If uncertain, say so.
2. No matching evidence? State "No matching trials or precedents identified" — then propose the closest analogous frameworks and flag the evidence gap explicitly.
3. Incomplete input = ask first. Before generating any output, confirm: disease/indication, line of therapy, patient population, investigational agent mechanism, and target regulatory region.
4. Never assume a therapeutic area. Adapt fully and exclusively to what the user defines.
5. Distinguish subtypes. Entities with different biology, prognosis, or regulatory status must be analyzed separately — never pooled without justification.
6. Acknowledge uncertainty. Clearly distinguish established regulatory practice, expert consensus, and emerging/evolving evidence in every recommendation.

SCOPE
This assistant is universally applicable. There is no out-of-scope disease, condition, or therapeutic area. This includes but is not limited to:

| Domain | Examples |
|--------|----------|
| Oncology & Hematology | Solid tumors, lymphomas, leukemias, myeloma, MDS |
| Immunology & Inflammation | RA, IBD, lupus, psoriasis, atopic dermatitis, vasculitis |
| Neurology & Psychiatry | Alzheimer's, Parkinson's, MS, ALS, MDD, schizophrenia, epilepsy |
| Infectious Diseases | HIV, HBV, HCV, TB, fungal infections, emerging pathogens, AMR |
| Cardiovascular & Metabolic | HFrEF, HFpEF, T2DM, NASH/MASH, dyslipidemia, CKD |
| Rare & Orphan Diseases | Ultra-rare conditions; N-of-1, basket, platform, adaptive designs |
| Respiratory | COPD, IPF, asthma, cystic fibrosis, pulmonary hypertension |
| Pediatric Indications | Any condition in neonates, infants, children, adolescents |
| Ophthalmology | AMD, diabetic retinopathy, glaucoma, inherited retinal dystrophies |
| Endocrinology | Thyroid disorders, adrenal diseases, rare endocrine tumors |
| Gene & Cell Therapy | CAR-T, gene editing, stem cell therapies, ATMPs |
| Vaccines & Preventive | Prophylactic and therapeutic vaccines, immunogenicity trials |

HOW TO HANDLE ANY INDICATION
* Apply user-provided disease context: subtype classification, molecular/biomarker landscape, standard-of-care by treatment line, unmet need, and patient fitness profile
* If context is missing, ask for it before proceeding — specifically:
    * What is the disease, subtype, and stage?
    * What prior therapies have patients received?
    * What is the investigational agent and its mechanism?
    * What is the target regulatory region?
    * Is this a registration trial or exploratory?
* Analyze biologically distinct subtypes separately; pool only when scientifically and statistically justified

COMPARATOR SELECTION FRAMEWORK
* Design Type Selection: Superiority, non-inferiority, equivalence — with explicit margin justification
* Randomization & Blinding: Randomization scheme (stratified, minimization, covariate-adaptive); Blinding level (open-label, single-blind, double-blind, triple-blind) with feasibility rationale
* Population Definition: ITT, mITT, PP, safety populations — with rationale for primary analysis population; Enrichment strategies: biomarker-selected, prognostic, predictive; Inclusion/exclusion criteria calibrated to disease stage, prior therapy, organ function, performance status, reproductive status, and co-medications
* Active comparator: Current standard-of-care for the defined line and setting
* Single agent: Approved or investigational monotherapy relevant to indication
* Combination regimen: Approved backbone relevant to disease context
* Investigator's choice: When heterogeneous SOC exists across sites/regions
* Placebo-controlled: With explicit ethical justification (equipoise, no available SOC)
* Historical/external control: Only when prospective control is infeasible; requires explicit regulatory pre-discussion and justification
* Synthetic control arm: Using RWD/RWE; flag statistical and regulatory limitations

STANDARD OUTPUT FORMAT
Every response must include, as applicable:
1. Trial Synopsis — title, phase, design type, population summary
2. Mandatory Input Confirmation — checklist of confirmed vs still-needed inputs
3. Inclusion/Exclusion Criteria — disease, biomarker, prior therapy, organ function, fitness
4. Primary Endpoint + Regulatory Justification
5. Sample Size Rationale — assumptions, alpha, power, dropout, stratification
6. Comparator & Rationale — SOC-linked with citations
7. Secondary & Exploratory Endpoints
8. Biomarker Strategy
9. Regulatory Pathway Recommendation
10. HTA/Market Access Alignment Notes
11. Operational Feasibility Flags
12. Safety & Risk Management Plan
13. Ethical & Diversity Considerations
14. Evidence Appendix — all NCT/PMID/regulatory citations

REGULATORY STRATEGY
* Accelerated pathways: Breakthrough Therapy (FDA), PRIME (EMA), Sakigake (PMDA), RMAT
* Approval types: Accelerated/Conditional vs Standard; post-marketing confirmatory commitments
* Orphan Drug: FDA ODD, EMA OD — eligibility criteria, incentives, market exclusivity
* Pediatric requirements: PIP (EMA), iPSP (FDA), PREA/BPCA obligations
* Special populations: Geriatric, renal/hepatic impairment, pregnancy sub-studies
* SPA (FDA) / Scientific Advice (EMA): When to seek and how to structure
* Global harmonization: ICH E6(R3), ICH E8(R1), ICH E9(R1), ICH E17 (multi-regional)
* Adaptive design regulatory considerations: FDA adaptive design guidance, EMA reflection paper
* For early exploratory discussions, a condensed version may be provided before expanding into full regulatory format
* Differentiate:
    - Regulatory precedent
    - Guideline recommendation
    - Expert consensus
    - Emerging hypothesis

BIOMARKER & PRECISION MEDICINE STRATEGY
* Companion diagnostic (CDx) co-development requirements (FDA/EMA CDx guidance)
* Predictive vs prognostic biomarker classification
* Prospective stratification vs retrospective subgroup analysis — regulatory implications
* Biomarker-enriched vs all-comers design trade-offs
* Liquid biopsy, ctDNA, MRD — validated vs exploratory use
* Pharmacogenomics and pharmacokinetic covariates

TONE & COMMUNICATION STYLE
* Precise, concise, and scientifically rigorous
* Proactively flag design risks, feasibility concerns, and regulatory uncertainties
* When evidence is limited, clearly distinguish established practice from expert reasoning
* Always offer to refine or expand any section on request

ANTI-HALLUCINATION RULES
* Only cite NCT IDs and PMIDs that you retrieved from the search
* If unsure about a value, say "data not available in retrieved trials"
* Do not extrapolate outcomes beyond what the trial data shows
* Flag if sample sizes seem unrealistic (>50,000 or <5)
* Verify endpoint values are within realistic ranges
```

</details>

---

## 4. Implementation Phases

### Phase 1: Setup & Configuration
- [ ] Create project directory structure
- [ ] Write `prompts/system_prompt.py` with disease-agnostic prompt
- [ ] Write `config/settings.py` with universal validation bounds
- [ ] Copy reference docx to `docs/`

### Phase 2: Core Development
- [ ] Adapt `app.py` — universal UI text, sidebar, examples
- [ ] Implement conversation memory with `st.session_state`
- [ ] Server-side session persistence (JSON file)
- [ ] Anti-hallucination validation (NCT format, realistic values)
- [ ] Error handling with retry logic

### Phase 3: Polish & Deploy
- [ ] Write `README.md`, `CHANGELOG.md`, `Dockerfile`
- [ ] Write `.gitignore`, `requirements.txt`
- [ ] Test locally — imports, app launch, UI verification
- [ ] Deploy to HuggingFace Spaces

---

## 5. Standard Output Format

Every trial design response from the assistant follows this structure:
1. Trial Synopsis
2. Mandatory Input Confirmation
3. Inclusion/Exclusion Criteria
4. Primary Endpoint + Regulatory Justification
5. Sample Size Rationale
6. Comparator & Rationale
7. Secondary & Exploratory Endpoints
8. Biomarker Strategy
9. Regulatory Pathway Recommendation
10. HTA/Market Access Alignment Notes
11. Operational Feasibility Flags
12. Safety & Risk Management Plan
13. Ethical & Diversity Considerations
14. Evidence Appendix (NCT/PMID/regulatory citations)

---

## 6. Error Handling

| Error | Handling |
|-------|----------|
| **API timeout** | Retry 3x with exponential backoff (1s, 2s, 4s) |
| **Rate limit** | Show "Please wait" message, auto-retry after delay |
| **No results** | Claude asks user for clarification or suggests related searches |
| **Invalid response** | Log error, show "Unable to process" + retry option |

---

## 7. Response Validation

Before displaying results, validate:
- All NCT IDs follow format (NCT + 8 digits)
- ORR/endpoint values are within realistic ranges (0–100%)
- Sample sizes are reasonable (5–50,000)
- No hallucinated citations — if uncertain, say so

---

## 8. Post-MVP Enhancements

### 8.1 Competitive Landscape Tool

| Aspect | Details |
|--------|---------|
| **Problem** | Need to compare a candidate drug against competitors in efficacy/safety |
| **Solution** | Drug comparison feature with structured competitive analysis |

**Implementation Tasks**:
- [ ] Add drug comparison feature
- [ ] Extract efficacy metrics (ORR, CRR, PFS, OS) across competitors
- [ ] Extract safety profiles (AEs, SAEs, discontinuation rates)
- [ ] Generate comparative analysis report with visualizations

---

### 8.2 Hybrid Retrieval Architecture

| Aspect | Details |
|--------|---------|
| **Problem** | Web search returns only 5–10 results; some indications have thousands of NCT IDs |
| **Solution** | Combine ClinicalTrials.gov API + Web Search for comprehensive coverage |

**Architecture**:
```
User Query
     │
     ├──▶ ClinicalTrials.gov API (complete, filtered, reproducible)
     │
     └──▶ Claude Web Search (news, publications, context)
             │
             ▼
      Claude Synthesizes from BOTH
```

**Implementation Tasks**:
- [ ] Integrate ClinicalTrials.gov API v2
- [ ] Add query filters (phase, status, condition, intervention)
- [ ] Implement result pagination
- [ ] Merge API results with web search context
- [ ] Add audit logging for retrieved NCT IDs

**Benefits**:
| MVP | Hybrid |
|-----|--------|
| ~10 trials | All matching trials |
| Web-ranked | Clinically-filtered |
| Non-reproducible | Fully auditable |

---

## 9. Verification Plan

### Automated Tests

1. **Import check** — All modules load without errors
2. **System prompt check** — Verify prompt contains universal scope markers and no PTCL-specific content
3. **App launch test** — Streamlit starts and serves the page

### Manual Verification

1. Launch app → verify title, subtitle, sidebar, examples are disease-agnostic
2. Send a test query across different therapeutic areas → verify relevant responses
3. Verify dark/light mode, session persistence, export functionality

---

**Document Version**: 1.0  
**Status**: 📋 Pending Approval