---
title: Clinical Trial Matcher
emoji: 🔬
colorFrom: blue
colorTo: purple
sdk: gradio
sdk_version: 6.2.0
app_file: app.py
pinned: false
license: mit
---

# 🔬 Clinical Trial Matcher

Search and filter clinical trials from [ClinicalTrials.gov](https://clinicaltrials.gov/) with AI-powered ranking.

## Features

- 🔍 **Keyword Search**: Search clinical trials by disease, condition, or treatment
- 🌍 **Country Filter**: Filter trials by country/location
- 📊 **Status Filter**: Filter by recruitment status (Recruiting, Completed, etc.)
- 🤖 **AI-Powered Ranking**: Use Hugging Face LLMs (like DeepSeek-V3.2) to intelligently rank results by relevance
- 📋 **Detailed Results**: View inclusion/exclusion criteria, sponsor information, and more

## How to Use

1. Enter search keywords (e.g., "cancer", "diabetes", "PDAC")
2. Optionally filter by country (default: Germany)
3. Optionally filter by recruitment status
4. Click "Search Clinical Trials"
5. After results appear, optionally enter ranking terms and click "Rank Results" for AI-powered relevance ranking

## AI-Powered Ranking

After your initial search, you can use AI to rank results by relevance:
- Enter specific terms you want to prioritize (e.g., "KRAS mutation", "immunotherapy")
- Click "Rank Results" to reorder studies by AI-determined relevance
- The model analyzes each study's title, summary, conditions, and inclusion criteria

## Setup for Hugging Face Spaces

### Required Files

1. **app.py** - Main Gradio application (already provided)
2. **llm_service.py** - LLM service for ranking (copy from `backend/llm_service.py`)
3. **requirements.txt** - Python dependencies (use `requirements_gradio.txt`)

### Environment Variables (Secrets)

Add these in your Space settings → Secrets:

- `HUGGINGFACE_API_TOKEN` - Your Hugging Face API token (required for ranking)
- `USE_HF_API` - Set to `true` to use Hugging Face Inference API
- `DEEPSEEK_MODEL` - Model to use (default: `deepseek-ai/DeepSeek-V3.2`)

### Getting a Hugging Face API Token

1. Go to [Hugging Face Settings](https://huggingface.co/settings/tokens)
2. Create a new token with "Read" permissions
3. Add it as a secret in your Space settings

## 📱 Install on Your iPhone/Android

This app can be installed on your phone as a Progressive Web App (PWA)!

### iPhone:
1. Open this Space in **Safari** (not Chrome)
2. Tap the **Share button** (square with arrow) at the bottom
3. Scroll down and tap **"Add to Home Screen"**
4. Tap **"Add"**

### Android:
1. Open this Space in **Chrome**
2. Tap the **menu** (three dots) → **"Add to Home screen"**
3. Confirm installation

The app will appear on your home screen and open like a native app! See [PWA_HF_SPACES.md](../PWA_HF_SPACES.md) for detailed instructions.

## Data Source

All data is sourced from [ClinicalTrials.gov](https://clinicaltrials.gov), the official database of clinical trials worldwide.

## Developer

**Dev. by Mackenzie 🧡 | mackenzie@post.harvard.edu for Qs**

## License

MIT License