# Project export: Trialscope AI This document was generated by HackStack to give an AI agent context about a hackathon project. Sections are labeled with their provenance; content marked as truncated was cut to keep this document small. ## Project metadata - Hackathon: Cal Hacks 12.0 - Tagline: Your AI-driven clinical trial intelligence platform that reviews, benchmarks, and regenerates protocol drafts into USDM-ready, FDA-aligned docs: Reducing amendments, delays, and cost overruns. - Devpost: https://devpost.com/software/trialscope-ai - GitHub: https://github.com/Hilo-Hilo/cal-hacks-new - Video: https://www.youtube.com/embed/FNYlGTxhrr4?enablejsapi=1&hl=en_US&rel=0&start=&version=3&wmode=transparent - Result: winner (Regeneron: Grand Prize) - Team: 2 GitHub contributor(s) — Hanson Wen (39 commits), Cyan Ding (16 commits) ## Devpost submission (written by the team) ### Inspiration The members of the Trialscope AI team came into CalHacks with all but a singular question: "Why do SO MANY promising discoveries at the bench fail to reach the patients at the bedside?" In fact, roughly 9 in 10 clinical developments fail between starting Phase I trials and receiving regulatory approval. While many of these failures stem from biological uncertainty, a surprisingly large proportion are lost not in the lab, but in clinical trial design and operations. While wet-lab innovation races ahead, trial design still lives in sprawling word documents/PDFs - Even at leading biopharma companies. These protocols span hundreds of pages, presenting scattered trial design information. When foundational design choices are made inside such unstructured, manual systems, trials become vulnerable to avoidable operational risks: misaligned endpoints, impractical timelines, or regulatory gaps that can compromise even the most promising science. The result? Delayed trials, avoidable amendments, and millions of dollars in wasted effort. Enter TrialScope AI. Our mission? Controlling the controllables, by making clinical trial design as intelligent as the science it tests, narrowing the chasm between therapeutic discovery and approval. ### What it does TrialScope AI transforms messy, unstructured trial drafts into structured and regulator-aligned designs, followed by regenerating improved versions using AI. Upload any Phase II–III trial draft PDF doc. Upload any Phase II–III trial draft PDF doc. Convert it into a machine-readable USDM structure (Schedule of Activities, endpoints, arms, eligibility, etc.) Convert it into a machine-readable USDM structure (Schedule of Activities, endpoints, arms, eligibility, etc.) Generate insights on factors that may slow down trial progress using data from 1M+ historical clinical studies, benchmarking performance metrics such as duration, procedural burden, and amendment likelihood. Generate insights on factors that may slow down trial progress using data from 1M+ historical clinical studies, benchmarking performance metrics such as duration, procedural burden, and amendment likelihood. Identify missing regulatory elements by cross-referencing FDA guidance documents, while highlighting compliance gaps and potential design inefficiencies. Identify missing regulatory elements by cross-referencing FDA guidance documents, while highlighting compliance gaps and potential design inefficiencies. Benchmark trial performance against studies of similar drugs, mechanisms, and phases, providing justification on how design choices (e.g., endpoints, visit frequency, population scope) align with successful precedents. Benchmark trial performance against studies of similar drugs, mechanisms, and phases, providing justification on how design choices (e.g., endpoints, visit frequency, population scope) align with successful precedents. Regenerate an improved, citation-linked draft and export it as USDM-ready JSON/XML for CRO or CTMS integration. Regenerate an improved, citation-linked draft and export it as USDM-ready JSON/XML for CRO or CTMS integration. ### How we built it On Friday, we built a simple prototype of next.js frontend with a text box that communicated with a backend via an API to allow for natural language queries to the clinicaltrials.gov api. We spent the rest of the day prototyping a full-stack platform to include features such as finding similar studies to demonstrate average metrics such as cohort size, number of endpoints, etc. We also trained an xgboost ML model to predict the probability of a given protocol to go overtime, as we felt this unanticipated weeks to months led to large expenditures for companies. On Friday, we built a simple prototype of next.js frontend with a text box that communicated with a backend via an API to allow for natural language queries to the clinicaltrials.gov api. We spent the rest of the day prototyping a full-stack platform to include features such as finding similar studies to demonstrate average metrics such as cohort size, number of endpoints, etc. We also trained an xgboost ML model to predict the probability of a given protocol to go overtime, as we felt this unanticipated weeks to months led to large expenditures for companies. On Saturday morning, we met with Henry Wei of Regeneron to discuss the direction we were planning on going into and decided we wanted to build a tool to extract insights from clinical trials going from preclinical to phase 1. There, we decided to pivot to stage 2-3 clinical trial protocols, as that time-stage had the most potential to save researchers time through operation parameter changes. We also decided to include a tool to use LLMs to do compliance oversight on a protocol draft utilizing FDA guideline documents. Finally, we decided it would be critical to utilize the USDM format of trial design to standardize all internal operations. On Saturday morning, we met with Henry Wei of Regeneron to discuss the direction we were planning on going into and decided we wanted to build a tool to extract insights from clinical trials going from preclinical to phase 1. There, we decided to pivot to stage 2-3 clinical trial protocols, as that time-stage had the most potential to save researchers time through operation parameter changes. We also decided to include a tool to use LLMs to do compliance oversight on a protocol draft utilizing FDA guideline documents. Finally, we decided it would be critical to utilize the USDM format of trial design to standardize all internal operations. Saturday night, we met with Henry for the second time and gained a lot of insights as to the potential of LLM-improved clinical trials. Throughout the night, we added features such as the LLM oversight tool, a modified xgboost model to predict average time of study, additional graphs to visualize insights, and a USDM rewriting tool that showed side-by-side differences. Saturday night, we met with Henry for the second time and gained a lot of insights as to the potential of LLM-improved clinical trials. Throughout the night, we added features such as the LLM oversight tool, a modified xgboost model to predict average time of study, additional graphs to visualize insights, and a USDM rewriting tool that showed side-by-side differences. Going into Sunday morning, we had a functional product that could extract a plethora of actionable insights from protocol drafts for researchers targeting phase 2-3 clinical trial success. Going into Sunday morning, we had a functional product that could extract a plethora of actionable insights from protocol drafts for researchers targeting phase 2-3 clinical trial success. ### Challenges we ran into The main challenge we ran into was narrowing down the precise problem scope. As a group that has had minimal experience running clinical trials, we ran mock “customer discovery/insights” interviews with experts in the field (Shout Out Henry Wei, M.D. of Regeneron!) to refine the problem/needs statement and inform our solution landscape + implementation. Pivoting our technical solution based on each interview required a flexible mindset and agile implementation. The main challenge we ran into was narrowing down the precise problem scope. As a group that has had minimal experience running clinical trials, we ran mock “customer discovery/insights” interviews with experts in the field (Shout Out Henry Wei, M.D. of Regeneron!) to refine the problem/needs statement and inform our solution landscape + implementation. Pivoting our technical solution based on each interview required a flexible mindset and agile implementation. There were some technical challenges, mainly on the front-end back-end interfacing, as well as resolving merge conflicts between team members. We were able to resolve these challenges with AI assistance. There were some technical challenges, mainly on the front-end back-end interfacing, as well as resolving merge conflicts between team members. We were able to resolve these challenges with AI assistance. ### Accomplishments we're proud of We built a complete, production-ready pipeline capable of turning raw, unstructured clinical trial PDFs into optimized, regulator-aligned designs. The system processes multi-hundred-page protocols and benchmarks them against over half a million historical studies in under ten minutes. It implements CDISC USDM v3.0—the same data model used by top pharmaceutical companies—allowing seamless integration into CRO and CTMS workflows. The platform unites semantic embeddings, Claude API, MCP tools, XGBoost modeling, and rule-based validation into one coherent, automated framework. We built a complete, production-ready pipeline capable of turning raw, unstructured clinical trial PDFs into optimized, regulator-aligned designs. The system processes multi-hundred-page protocols and benchmarks them against over half a million historical studies in under ten minutes. It implements CDISC USDM v3.0—the same data model used by top pharmaceutical companies—allowing seamless integration into CRO and CTMS workflows. The platform unites semantic embeddings, Claude API, MCP tools, XGBoost modeling, and rule-based validation into one coherent, automated framework. Our most significant accomplishment wasn’t just the technical complexity, but the practicality of what we built. TrialScope AI functions as a true operational tool, capable of fitting into real biopharma workflows and addressing inefficiencies that cost companies millions. Within just 36 hours, we delivered a prototype that could realistically reduce delays, standardize design choices, and make the process of clinical trial planning as intelligent and data-driven as the science it aims to validate. Our most significant accomplishment wasn’t just the technical complexity, but the practicality of what we built. TrialScope AI functions as a true operational tool, capable of fitting into real biopharma workflows and addressing inefficiencies that cost companies millions. Within just 36 hours, we delivered a prototype that could realistically reduce delays, standardize design choices, and make the process of clinical trial planning as intelligent and data-driven as the science it aims to validate. ### What we learned Solving a hackathon required full immersion in the problem space - especially as we were working specifically to address needs in the clinical trials space. This required a full-on crash course of the landscape, as further understanding of the technicalities of each clinical trial phase resulted in us challenging and augmenting our own assumptions: whether it was the type of need to address, our entry point into the clinical trial timeline or the modality in which we implemented our solutions. Solving a hackathon required full immersion in the problem space - especially as we were working specifically to address needs in the clinical trials space. This required a full-on crash course of the landscape, as further understanding of the technicalities of each clinical trial phase resulted in us challenging and augmenting our own assumptions: whether it was the type of need to address, our entry point into the clinical trial timeline or the modality in which we implemented our solutions. Our process went beyond simply building a prototype: rather, it involved thinking like a real bio-AI software company. We dived into processes like defining our market position, identifying unmet needs, and translating technical insights into product strategy. This hands-on experience revealed how interdisciplinary problem-solving operates in practice, especially at the intersection of biology and AI. Our process went beyond simply building a prototype: rather, it involved thinking like a real bio-AI software company. We dived into processes like defining our market position, identifying unmet needs, and translating technical insights into product strategy. This hands-on experience revealed how interdisciplinary problem-solving operates in practice, especially at the intersection of biology and AI. The hackathon became less about competition and more about understanding the actual workflow, validation process, and communication style of startups in this space. It showed us how to move from concept to execution within real constraints, and provided the foundation for pursuing further research, development, and innovation in this field beyond CalHacks. The hackathon became less about competition and more about understanding the actual workflow, validation process, and communication style of startups in this space. It showed us how to move from concept to execution within real constraints, and provided the foundation for pursuing further research, development, and innovation in this field beyond CalHacks. ### What's next Short-Term (Next 3 Months) Multi-version protocol generation with A/B testing and citation tracking for every AI-generated recommendation. Track-change visualization between original and optimized drafts. Expand regulatory coverage with 50+ additional FDA guidance documents, ICH standards, and EMA compliance. Improve ML models to predict enrollment success, dropout risk, and time-to-first-patient-in. Add collaboration tools: multi-user access, role-based permissions, comment threads, and version control. Medium-Term (6–12 Months) Pilot partnerships with biotech and pharma companies to validate platform performance and reduce amendment rates. Integrate with EDC and protocol authoring systems (Veeva, Medidata, Word). Add advanced analytics modules for cost estimation, site selection, and feasibility scoring. Extend global regulatory coverage and introduce multi-language support. Long-Term (12+ Months) Implement generative protocol authoring from simple drug or mechanism prompts. Simulate trial outcomes pre-enrollment using predictive models trained on 1M+ trials. Automate regulatory submission workflows, including IND draft generation and FDA response preparation. Release open-source datasets, model weights, and benchmark frameworks for academic collaboration. Achieve <3-minute full analysis time, >0.90 ML accuracy, and scalable performance for 10,000+ concurrent users with HIPAA-compliant security. ## README (from the GitHub repository) # TrialScope AI - Clinical Trial Intelligence Platform **Cal Hacks 12.0 - Regeneron Tech Prize** **License**: MIT (Open Source) --- ## 🎤 Elevator Pitch **Your AI-driven clinical trial intelligence platform that reviews, benchmarks, and regenerates protocol drafts into USDM-ready, FDA-aligned docs: Reducing amendments, delays, and cost overruns.** --- ## 💡 Inspiration The members of the Trialscope AI team came into CalHacks with all but a singular question: "_Why do SO MANY promising discoveries at the bench fail to reach the patients at the bedside?_" In fact, roughly **9 in 10** clinical developments **fail** between starting Phase I trials and receiving regulatory approval. While many of these failures stem from biological uncertainty, a surprisingly large proportion are lost not in the lab, but in clinical trial design and operations. While wet-lab innovation races ahead, trial design still lives in sprawling word documents/PDFs - **Even at leading biopharma companies**. These protocols span hundreds of pages, presenting scattered trial design information. When foundational design choices are made inside such unstructured, manual systems, **trials become vulnerable to avoidable operational risks**: misaligned endpoints, impractical timelines, or regulatory gaps that can compromise even the most promising science. _The result?_ **Delayed trials, avoidable amendments, and millions of dollars in wasted effort.** **Enter TrialScope AI.** _Our mission?_ Controlling the controllables, by **making clinical trial design as intelligent as the science it tests**, narrowing the chasm between therapeutic discovery and approval. --- ## 🎯 What it does TrialScope AI transforms messy, unstructured trial drafts into structured and regulator-aligned designs, followed by regenerating improved versions using AI. ### Core Workflow 1. **Upload** any Phase II–III trial draft PDF doc. 2. **Convert** it into a machine-readable USDM structure (Schedule of Activities, endpoints, arms, eligibility, etc.) 3. **Generate insights** on factors that may slow down trial progress using data from **1M+ historical clinical studies**, benchmarking performance metrics such as duration, procedural burden, and amendment likelihood. 4. **Identify missing regulatory elements** by cross-referencing FDA guidance documents, while highlighting compliance gaps and potential design inefficiencies. 5. **Benchmark trial performance** against studies of similar drugs, mechanisms, and phases, providing justification on how design choices (e.g., endpoints, visit frequency, population scope) align with successful precedents. 6. **Regenerate** an improved, citation-linked draft and export it as USDM-ready JSON/XML for CRO or CTMS integration. ### Key Features #### 📄 Protocol Intelligence System - **PDF Processing**: Automatic PDF→Markdown→USDM conversion using Claude 4.5 Sonnet - **Similar Trials Discovery**: Find up to 50 similar trials using natural language matching from 556K+ completed studies - **Similarity Scoring**: Multi-factor semantic analysis (condition 35%, phase 20%, endpoints 25%, design 20%) - **Baseline Metrics**: Weighted aggregation from top-K most similar trials for realistic benchmarking - **Burden Analysis**: Rule-based complexity, recruitment difficulty, and patient burden scoring - **ML Predictions**: XGBoost models with SHAP explainability for duration overrun risk prediction - **FDA Compliance**: AI-powered regulatory guidance analysis using actual FDA PDF documents - **Protocol Optimization**: AI-powered regeneration with citations and regulatory alignment - **USDM Export**: Industry-standard CDISC format export for seamless CRO integration #### 🔍 Natural Language Trial Search - Query 556,743+ clinical trials using natural language powered by Claude AI with MCP tools - Intelligent fallback between PostgreSQL database and live ClinicalTrials.gov API **Processing Time**: 5-10 minutes for complete analysis --- ## 🏗️ How we built it ### Architecture Overview ``` ┌────────────────────────────────────────────────────────────┐ │ Frontend (Next.js 14) │ │ Trial Search | Protocol Upload | Analysis Dashboard │ │ Real-time Progress Tracking via WebSockets │ └──────────────────────────┬─────────────────────────────────┘ │ HTTP/REST + WebSockets ▼ ┌────────────────────────────────────────────────────────────┐ │ Backend API (FastAPI) │ │ Claude 4.5 | PostgreSQL | MCP Server | ML Models | FDA │ │ Async Processing | Session Management | WebSocket Updates │ └────────────────────────────────────────────────────────────┘ │ ▼ ┌────────────────────────────────────────────────────────────┐ │ Data Layer & External Services │ │ 556K Trials DB | FDA Guidance PDFs | ClinicalTrials.gov │ └────────────────────────────────────────────────────────────┘ ``` ### Technology Stack #### Backend (Python/FastAPI) - **FastAPI** - High-performance async web framework with automatic API documentation - **Claude 4.5 Sonnet** - AI processing for USDM conversion, FDA analysis, and protocol optimization - **PostgreSQL 14+** - 556K+ completed trials from ClinicalTrials.gov + session storage - **sentence-transformers** - Semantic similarity using all-MiniLM-L6-v2 (384-dim embeddings) - **XGBoost + SHAP** - ML predictions with SHAP TreeExplainer for explainability - **PyMuPDF + pdfplumber** - Hybrid PDF text extraction (NO OCR required) - **WebSockets** - Real-time progress updates during long-running analysis - **psycopg2** - PostgreSQL adapter for efficient database operations #### Frontend (Next.js/TypeScript) - **Next.js 14** - React framework with App Router for optimal performance - **TypeScript** - Type safety across the entire frontend - **Tailwind CSS** - Utility-first styling for rapid UI development - **Recharts** - Interactive data visualizations (burden charts, risk gauges, SHAP plots) - **Lucide React** - Consistent icon system - **Shadcn UI** - High-quality, accessible component library #### AI & ML Infrastructure - **Anthropic Claude API** - USDM conversion (16K token output), FDA analysis, protocol optimization - **Model Context Protocol (MCP)** - TypeScript/Bun MCP server for intelligent trial discovery - **CDISC USDM v3.0** - Industry-standard clinical study data model - **FDA Guidance Library** - 10+ regulatory PDF documents (oncology, general, genetics categories) #### Data Processing Pipeline 1. **PDF Ingestion**: Hybrid extraction using PyMuPDF + pdfplumber 2. **Markdown Conversion**: Structured text with page markers and tables 3. **USDM Transformation**: Claude AI converts unstructured text to CDISC USDM v3.0 JSON 4. **Parallel Annotation**: 20 concurrent Claude API calls for similar trial annotation 5. **Multi-Factor Scoring**: Semantic embeddings + lexical matching for 4 similarity dimensions 6. **FDA Analysis**: AI-powered document selection + compliance gap identification 7. **ML Prediction**: XGBoost ensemble with SHAP feature attribution 8. **Protocol Regeneration**: Claude extended thinking mode for optimized draft generation ### Key Technical Innovations #### 1. Two-Stage PDF Processing Pipeline - **Stage 1**: Python libraries (PyMuPDF + pdfplumber) for text extraction - NO expensive OCR - **Stage 2**: Claude AI for intelligent structure recognition and USDM conversion - **Result**: Cost-effective processing with high accuracy on complex medical documents #### 2. Semantic Similarity Engine - **Condition Matching** (35%): Sentence-BERT embeddings with cosine similarity - **Phase Alignment** (20%): Exact match + adjacent phase scoring (e.g., Phase 2 vs Phase 2/3) - **Endpoint Overlap** (25%): Hybrid semantic + lexical (Jaccard index) matching - **Design Similarity** (20%): Structural elements (randomiz [README truncated for size] ## Detected evidence (automated analysis) Indexed codebase: 127 recognized source files, 1042 KB. - Anthropic (technology) — detected in the code - CSS (language) — detected in the code - FastAPI (technology) — detected in the code - HTML (language) — detected in the code - Next.js (technology) — detected in the code - Python (language) — detected in the code - React (technology) — detected in the code - SQL (language) — detected in the code - Tailwind CSS (technology) — detected in the code - TypeScript (language) — detected in the code - PostgreSQL (technology) — claimed on Devpost, not found in the code ## Codebase structure (from repository index) ### Files (120 of 159) ``` .gitignore api_documentation/claude-api-docs/advanced/01-extended-thinking.md api_documentation/claude-api-docs/advanced/02-prompt-caching.md api_documentation/claude-api-docs/advanced/03-vision-pdf.md api_documentation/claude-api-docs/advanced/04-batch-processing.md api_documentation/claude-api-docs/core-features/01-tool-use.md api_documentation/claude-api-docs/core-features/02-mcp.md api_documentation/claude-api-docs/core-features/03-streaming.md api_documentation/claude-api-docs/core-features/04-json-mode.md api_documentation/claude-api-docs/examples/01-tool-use-examples.md api_documentation/claude-api-docs/examples/02-streaming-examples.md api_documentation/claude-api-docs/examples/03-mcp-examples.md api_documentation/claude-api-docs/examples/04-json-examples.md api_documentation/claude-api-docs/examples/05-complete-apps.md api_documentation/claude-api-docs/getting-started/01-introduction.md api_documentation/claude-api-docs/getting-started/02-quickstart.md api_documentation/claude-api-docs/getting-started/03-messages-api.md api_documentation/claude-api-docs/README.md api_documentation/claude-api-docs/reference/01-api-reference.md api_documentation/claude-api-docs/reference/02-error-handling.md api_documentation/claude-api-docs/reference/03-best-practices.md api_documentation/claude-api-docs/reference/04-models-pricing.md api_documentation/claude-api-docs/STRUCTURE.md api_documentation/ClinicalTrials.gov Data API - Complete Documentation.md backend/.gitignore backend/app/__init__.py backend/app/config.py backend/app/database/__init__.py backend/app/database/session_manager.py backend/app/main.py backend/app/ml/__init__.py backend/app/ml/baseline_ensemble_predictor.py backend/app/ml/conformal_utils.py backend/app/ml/create_demo_models.py backend/app/ml/data_extraction.py backend/app/ml/feature_engineering.py backend/app/ml/models/duration_feature_names.txt backend/app/ml/models/duration_model_metrics.json backend/app/ml/models/duration_quantile_p10.pkl backend/app/ml/models/duration_quantile_p25.pkl backend/app/ml/models/duration_quantile_p50.pkl backend/app/ml/models/duration_quantile_p75.pkl backend/app/ml/models/duration_quantile_p90.pkl backend/app/ml/models/duration_shap_p10.pkl backend/app/ml/models/duration_shap_p25.pkl backend/app/ml/models/duration_shap_p50.pkl backend/app/ml/models/duration_shap_p75.pkl backend/app/ml/models/duration_shap_p90.pkl backend/app/ml/models/feature_names.txt backend/app/ml/models/gradient_boosting.pkl backend/app/ml/models/model_metrics.json backend/app/ml/models/shap_explainer.pkl backend/app/ml/train_duration_quantile_models.py backend/app/ml/train_model.py backend/app/models/__init__.py backend/app/models/query.py backend/app/routes/__init__.py backend/app/routes/analysis.py backend/app/routes/protocol.py backend/app/routes/query.py backend/app/routes/sessions.py backend/app/services/__init__.py backend/app/services/annotation_service.py backend/app/services/baseline_generator.py backend/app/services/burden_calculator.py backend/app/services/claude.py backend/app/services/ctgov_api.py backend/app/services/fda_report_analyzer.py backend/app/services/mcp_client.py backend/app/services/mcp_tools.py backend/app/services/ml_predictor.py backend/app/services/postgres.py backend/app/services/protocol_optimizer.py backend/app/services/protocol_parser.py backend/app/services/similarity_engine.py backend/app/websocket_manager.py backend/inspect_db.py backend/README.md backend/setup_env.sh backend/tests/fixtures/sample_analysis_report.json backend/tests/fixtures/sample_protocol_usdm.json backend/tests/run_comprehensive_tests.py backend/tests/test_annotation_service.py backend/tests/test_baseline_generator.py backend/tests/test_burden_calculator_comprehensive.py backend/tests/test_burden_calculator.py backend/tests/test_curly_bracket_parsing.py backend/tests/test_fda_analyzer.py backend/tests/test_fda_report_analyzer.py backend/tests/test_feature_engineer.py backend/tests/test_indexed_selection_demo.py backend/tests/test_mcp_client_api.py backend/tests/test_ml_predictor_comprehensive.py backend/tests/test_ml_predictor.py backend/tests/test_pdf_parser.py backend/tests/test_protocol_parser.py backend/tests/test_results.json backend/tests/test_services.py backend/tests/test_similarity_engine.py backend/tests/test_status_normalization.py database/.env database/check_database.sh database/data_dictionary.csv database/install_postgres.sh database/migration_add_optimizing_status.sql database/migration_add_reasoning_column.sql database/migration_add_updated_at_column.sql database/nlm_protocol_definitions.html database/nlm_results_definitions.html database/README.md database/schema_protocol_intelligence.sql database/setup_database.sh docs/backend/backend.md docs/backend/QUICKSTART.md docs/backend/README.md fda/.DS_Store front-end/.gitignore front-end/app/globals.css front-end/app/layout.tsx front-end/app/page.tsx [39 more files omitted for size] ``` ### Dependencies - front-end/package.json: @radix-ui/react-slot@^1.2.3, @tailwindcss/postcss@^4, @tanstack/react-query@^5.17.0, @types/node@^20, @types/react@^19, @types/react-dom@^19, class-variance-authority@^0.7.1, clsx@^2.1.1, eslint@^9, eslint-config-next@16.0.0, lucide-react@^0.548.0, next@16.0.0, react@19.2.0, react-dom@19.2.0, recharts@^2.10.3, tailwind-merge@^3.3.1, tailwindcss@^4, tw-animate-css@^1.4.0, typescript@^5 - requirements.txt: anthropic@==0.39.0, fastapi@==0.115.5, httpx@==0.27.0, joblib@==1.5.2, markdownify@==0.12.1, numpy@==2.3.4, pandas@==2.3.3, pdfplumber@==0.11.7, psycopg2-binary@==2.9.10, pydantic@==2.10.1, PyMuPDF@==1.26.5, python-dotenv@==1.0.1, python-multipart@==0.0.20, scikit-learn@==1.7.2, sentence-transformers@==5.1.2, shap@==0.49.1, SQLAlchemy@==2.0.44, usdm@==0.64.0, uvicorn[standard]@==0.32.1, websockets@==15.0.1, xgboost@==3.1.1 ### Recent commits (newest first) - Remove CLAUDE.md from repository and add to .gitignore - Remove .cursor and hidden files from git tracking and update .gitignore - Clean up Regeneron track files and finalize README - Add elevator pitch to README - Update README to match pitch with comprehensive project details - Clean up temporary files and documentation - Fix FDA analyzer: correct Claude model name and resolve SDK compatibility issues - fix fda - Revert context window upgrade changes to fix timeout errors - Remove caching from analysis.py - use remote version - Merge remote changes: Resolve conflicts in session_manager and analysis routes - Critical fixes: context window upgrade and comprehensive improvements - add more pdfs, get rid of caching - feat: enhance protocol diff viewer with row-aligned layout and alphabetical sorting - Implement progressive search retry strategy and phase normalization - delete pdfs, make fda better - Merge branch 'main' of https://github.com/Hilo-Hilo/cal-hacks-new - Add protocol optimizer feature with AI-powered recommendations - Merge branch 'main' of https://github.com/Hilo-Hilo/cal-hacks-new - fix some ui bugs ## Key source files (fetched from GitHub, selected and truncated for size) ### PRD_COMPLETE.md ```markdown # Clinical Trials MVP - Product Requirements Document **Version**: 1.0 (MVP) **Date**: October 25, 2025 **Target**: Cal Hacks 12.0 - Regeneron Tech Prize **License**: MIT (Open Source) --- ## Executive Summary A simple, functional system that enables users to query clinical trials data using natural language. The system has three core components: 1. **Frontend** (Next.js) - User interface for queries 2. **MCP Server** (TypeScript/Bun) - Enables Claude AI to query PostgreSQL and ClinicalTrials.gov API 3. **Data Sources** - Local PostgreSQL database + ClinicalTrials.gov API **Key Value Proposition**: Query 556,743+ clinical trials using natural language through Claude AI, with results from both local database and live API. --- ## System Architecture ### Simple 3-Tier Architecture ``` ┌─────────────────────────────────────────────────────────────┐ │ Frontend (Next.js) │ │ User enters natural language query │ └───────────────────────────┬─────────────────────────────────┘ │ │ HTTP/REST │ ┌───────────────────────────▼─────────────────────────────────┐ │ Backend API (FastAPI) │ │ │ │ ┌────────────────────────────────────────────────────────┐ │ │ │ Claude AI Integration │ │ │ │ (Anthropic API with MCP tools) │ │ │ └────────────────────────────────────────────────────────┘ │ │ │ │ │ ┌─────────────────┴──────────────────┐ │ │ ▼ ▼ │ │ ┌──────────────┐ ┌────────────────┐ │ │ │ MCP Tools │ │ MCP Tools │ │ │ │ (Postgres) │ │ (API Client) │ │ │ └──────────────┘ └────────────────┘ │ └─────────────────────────────────────────────────────────────┘ │ │ ▼ ▼ ┌──────────────────┐ ┌──────────────────────┐ │ PostgreSQL │ │ ClinicalTrials.gov │ │ (556K trials) │ │ API │ └──────────────────┘ └──────────────────────┘ ``` ### Component Responsibilities | Component | Technology | Purpose | |-----------|-----------|----------| | **Frontend** | Next.js 14, TypeScript, Tailwind | User interface, query input | | **Backend API** | FastAPI (Python) | Route requests, integrate Claude | | **Claude AI** | Anthropic API (Sonnet 4) | Process natural language, use tools | | **MCP Tools** | Python functions | Search database, call external API | | **PostgreSQL** | PostgreSQL 14 | Local clinical trials data | | **External API** | ClinicalTrials.gov API v2 | Live data acce [truncated — 26643 more characters] ``` ### docs/backend/QUICKSTART.md ```markdown # Quick Start Guide ## 🚀 Get Started in 5 Minutes ### Prerequisites - Python 3.11+ - PostgreSQL 14+ - Anthropic API key ([Get one here](https://console.anthropic.com/)) ### Step 1: Setup Backend ```bash cd backend ./setup.sh ``` This will: - Create a virtual environment - Install all dependencies - Create a `.env` file template ### Step 2: Configure Environment Edit `.env` and add your credentials: ```bash # Required - Get from https://console.anthropic.com/ ANTHROPIC_API_KEY=sk-ant-your-actual-key-here # Required - Your PostgreSQL password POSTGRES_PASSWORD=your_postgres_password # Optional - Use defaults or customize POSTGRES_HOST=localhost POSTGRES_PORT=5432 POSTGRES_DATABASE=clinical_trials POSTGRES_USER=postgres ``` ### Step 3: Setup Database ```bash # Create database createdb clinical_trials # Restore data (choose one based on your file type) pg_restore -d clinical_trials -v ../database/postgres.dmp # OR if it's a SQL file: # psql -d clinical_trials -f ../database/postgres.dmp # Verify psql clinical_trials -c "SELECT COUNT(*) FROM studies;" ``` Expected output: ~556,743 studies ### Step 4: Run the Server ```bash ./run.sh ``` Or manually: ```bash source venv/bin/activate uvicorn app.main:app --reload --port 8000 ``` The API will be available at: http://localhost:8000 ### Step 5: Test It! #### Health Check ```bash curl http://localhost:8000/health ``` Expected response: ```json { "status": "healthy", "database": "connected", "api_key": "configured" } ``` #### Query Clinical Trials ```bash curl -X POST http://localhost:8000/api/query \ -H "Content-Type: application/json" \ -d '{"query": "Find Phase 3 lung cancer trials in California"}' ``` #### API Documentation Visit http://localhost:8000/docs for interactive API documentation. ## 🎯 Example Queries Try these natural language queries: 1. "Find all recruiting Phase 3 lung cancer trials" 2. "Show me diabetes studies in California" 3. "What are the most recent cancer immunotherapy trials?" 4. "Find studies sponsored by NIH" 5. "Show trials for COVID-19 treatments" 6. "What Phase 2 trials are recruiting in New York?" ## 🐛 Troubleshooting ### Database Connection Failed ```bash # Check PostgreSQL is running pg_isready # Test connection psql -h localhost -U postgres -d clinical_trials -c "SELECT 1" ``` ### Anthropic API Key Error ```bash # Verify key is set cat .env | grep ANTHROPIC_API_KEY # Test the key curl https://api.anthropic.com/v1/messages \ -H "x-api-key: YOUR_KEY_HERE" \ -H "Content-Type: application/json" \ -d '{"model":"claude-sonnet-4-20250514","max_tokens":10,"messages":[{"role":"user","content":"Hi"}]}' ``` ### Import Errors ```bash # Ensure virtual environment is activated source venv/bin/activate # Reinstall dependencies pip install -r requirements.txt ``` ## 📚 Next Steps - Read the [full README](README.md) for detailed documentation - Check the [API documentation](http://localhost:8000/docs) for endpoint details - Integrate wit [truncated — 506 more characters] ``` ### requirements.txt ``` fastapi==0.115.5 uvicorn[standard]==0.32.1 python-multipart==0.0.20 anthropic==0.39.0 psycopg2-binary==2.9.10 httpx==0.27.0 python-dotenv==1.0.1 pydantic==2.10.1 # PDF Processing (NO OCR - Python only) PyMuPDF==1.26.5 pdfplumber==0.11.7 markdownify==0.12.1 # CDISC USDM Standard (Official Library) usdm==0.64.0 # ML & Similarity sentence-transformers==5.1.2 scikit-learn==1.7.2 xgboost==3.1.1 shap==0.49.1 numpy==2.3.4 pandas==2.3.3 # Database SQLAlchemy==2.0.44 # Async & WebSockets websockets==15.0.1 # Additional utilities joblib==1.5.2 ``` ### front-end/package.json ``` { "name": "front-end", "version": "0.1.0", "private": true, "scripts": { "dev": "next dev", "build": "next build", "start": "next start", "lint": "eslint" }, "dependencies": { "@radix-ui/react-slot": "^1.2.3", "@tanstack/react-query": "^5.17.0", "class-variance-authority": "^0.7.1", "clsx": "^2.1.1", "lucide-react": "^0.548.0", "next": "16.0.0", "react": "19.2.0", "react-dom": "19.2.0", "recharts": "^2.10.3", "tailwind-merge": "^3.3.1" }, "devDependencies": { "@tailwindcss/postcss": "^4", "@types/node": "^20", "@types/react": "^19", "@types/react-dom": "^19", "eslint": "^9", "eslint-config-next": "16.0.0", "tailwindcss": "^4", "tw-animate-css": "^1.4.0", "typescript": "^5" } } ``` ### front-end/app/layout.tsx ```typescript import type { Metadata } from "next"; import { Geist, Geist_Mono } from "next/font/google"; import "./globals.css"; const geistSans = Geist({ variable: "--font-geist-sans", subsets: ["latin"], }); const geistMono = Geist_Mono({ variable: "--font-geist-mono", subsets: ["latin"], }); export const metadata: Metadata = { title: "TrialScope AI - Clinical Trial Intelligence", description: "AI-powered clinical trial protocol analysis and intelligence platform", }; export default function RootLayout({ children, }: Readonly<{ children: React.ReactNode; }>) { return ( {children} ); } ``` ### backend/app/main.py ```python """ Main FastAPI application for Clinical Trials search. Integrates Claude AI with MCP tools for natural language querying. """ from fastapi import FastAPI from fastapi.middleware.cors import CORSMiddleware from contextlib import asynccontextmanager import logging from .config import config from .routes import query, protocol, analysis, sessions from .services.postgres import postgres from .models.query import HealthResponse # Configure logging logging.basicConfig( level=getattr(logging, config.LOG_LEVEL.upper()), format='%(asctime)s - %(name)s - %(levelname)s - %(message)s' ) logger = logging.getLogger(__name__) # Validate configuration try: config.validate() logger.info("Configuration validated successfully") except ValueError as e: logger.error(f"Configuration error: {e}") raise @asynccontextmanager async def lifespan(app: FastAPI): """Application lifespan events""" # Startup logger.info("Starting Clinical Trials API") logger.info(f"CORS origins: {config.CORS_ORIGINS}") yield # Shutdown logger.info("Shutting down Clinical Trials API") postgres.close() # Create FastAPI app app = FastAPI( title="Clinical Trials API", description="Natural language search for clinical trials using Claude AI with MCP tools", version="1.0.0", lifespan=lifespan ) # CORS middleware for frontend app.add_middleware( CORSMiddleware, allow_origins=config.CORS_ORIGINS, allow_credentials=True, allow_methods=["*"], allow_headers=["*"], ) # Include routers app.include_router(query.router, prefix="/api", tags=["query"]) app.include_router(protocol.router, prefix="/api", tags=["protocol"]) app.include_router(analysis.router, prefix="/api", tags=["analysis"]) app.include_router(sessions.router, prefix="/api", tags=["sessions"]) @app.get("/health", response_model=HealthResponse) async def health(): """ Health check endpoint. Verifies database connection and API key configuration. """ db_status = "connected" if postgres.test_connection() else "disconnected" api_key_status = "configured" if config.ANTHROPIC_API_KEY else "missing" return { "status": "healthy" if db_status == "connected" and api_key_status == "configured" else "unhealthy", "database": db_status, "api_key": api_key_status } if __name__ == "__main__": import uvicorn uvicorn.run( "backend.app.main:app", host="0.0.0.0", port=config.PORT, reload=True ) ``` ### front-end/app/page.tsx ```typescript 'use client'; import { useState } from 'react'; import { SearchBox } from '@/components/SearchBox'; import { ResultCard } from '@/components/ResultCard'; import { LoadingSpinner } from '@/components/LoadingSpinner'; import { searchTrials, APIError } from '@/lib/api'; import { QueryResponse } from '@/lib/types'; import { AlertCircle, Database, Sparkles, ChevronDown, ChevronUp } from 'lucide-react'; import { Alert, AlertDescription, AlertTitle } from '@/components/ui/alert'; export default function Home() { const [isLoading, setIsLoading] = useState(false); const [results, setResults] = useState(null); const [error, setError] = useState(null); const [isSummaryExpanded, setIsSummaryExpanded] = useState(true); const handleSearch = async (query: string) => { setIsLoading(true); setError(null); setResults(null); try { const data = await searchTrials(query); setResults(data); } catch (err) { if (err instanceof APIError) { setError(err.message); } else { setError('An unexpected error occurred. Please try again.'); } console.error('Search error:', err); } finally { setIsLoading(false); } }; return (
{/* Header Navigation */}

TrialScope AI

{isLoading && } {error && (
Error {error}
)} {results && !isLoading && (
{/* Claude's Response */} {results.claude_response && (
{isSummaryExpanded && (

{results.claude_response}

)}
)} {/* Results Summary */} {results.results && (

{results.results.totalCount === 0 ? 'No studies found' : `Found ${results.results.totalCount} ${results.results.totalCount === 1 ? 'study' : 'studies'}` }

{results.tool_used && (
via {results.tool_used}
)}
)} {/* Results List */} {results.results && results.results.studies.length > 0 && (
{results.results.studies.map((study) => ( ))}
)} {/* No Results */} {results.results && results.results.totalCount === 0 && (

No clinical trials found matching your query.

Try adjusting your search terms or using different keywords.

)}
)} {/* Footer */} {!isLoading && !results && (
Powered by Claude AI + PostgreSQL + ClinicalTrials.gov API

{ const colors: Record = { 'created': 'bg-slate-500', 'parsing': 'bg-blue-500', 'querying': 'bg-indigo-500', 'annotating': 'bg-purple-500', 'analyzing': 'bg-violet-500', 'complete': 'bg-green-500', 'error': 'bg-red-500', }; return colors[status] || 'bg-gray-500'; }; if (isLoading && sessions.length === 0) { console.log('🔄 Rendering loading state...'); return (

Protocol Analysis Sessions

Loading your sessions...

This should only take a moment
); } console.log('✓ Rendering sessions:', sessions.length, 'sessions found'); return (
{/* Header */}

Protocol Analysis Sessions

View and manage your protocol analysis sessions