ClearMatch

A Python tool for the structured analysis of clinical trial eligibility criteria by extracting and organizing atomic criteria into logical structures.

🚀 Overview

ClearMatch processes clinical trial data from ClinicalTrials.gov, extracting structured information about eligibility criteria. It performs three key steps:

1. Identification – Extracts atomic criteria from raw text.
2. Logical Structuring – Organizes these criteria using logical relationships (AND, OR, NOT, XOR, CONDITIONAL).
3. Matching Patients to Oncological Clinical Trials – (Planned but not yet implemented).

✅ Features

• ✅ Fetches clinical trial data from the ClinicalTrials.gov API.
• ✅ Extracts and structures eligibility criteria into logical expressions.
• ✅ Persists processed data as JSON files for further analysis.
• 🚧 Upcoming: Automated patient matching system.
• 🚧 Upcoming: UI.

---

📋 Requirements

• Python 3.13+
• OpenAI API key (for GPT-4o access) 📌 Get your API key here: OpenAI API Keys

---

💾 Installation

1️⃣ Clone the repository

   gh repo clone judacas/Clinical-Trial-Prompts

This uses GitHub CLI. If you don’t have it, use:

git clone https://github.com/judacas/Clinical-Trial-Prompts.git

make sure to then cd into the root directory

cd Clinical-Trial-Prompts

2️⃣ **Set up a virtual environment (Optional but Recommended) **

python -m venv .venv
source .venv/bin/activate  # macOS/Linux
.venv\Scripts\activate     # Windows

3️⃣ Install dependencies

pip install -r requirements.txt

4️⃣ Set up environment variables Copy the example sample.env file and rename it to proper .env naming convention:

cp src/sample.env src/.env  # macOS/Linux
copy src\sample.env src\.env  # Windows

To edit the .env file in the terminal, use:

nano src/.env  # Linux/macOS
notepad src\.env  # Windows

Then, add your OpenAI API key:

OPENAI_API_KEY="your-api-key-here"

📌 Note: The .env file is ignored by Git to prevent accidental key exposure.

---

🛠 Usage

Run ClearMatch using:

python -m src.main

Follow the command-line instructions to process and structure clinical trial data.

---

📊 Data Flow

1. Fetch raw trial data from ClinicalTrials.gov.
2. Identify the atomic eligibility criteria in the selected trials.
3. Structure criteria using logical operators (AND, OR, etc.).
4. Store results as structured JSON files in output/ subdirectory for further use.

---

💡 Future Plans

• 🔹 Add automated patient-trial matching.
• 🔹 Implement an API to allow external applications to query structured trial data.
• 🔹 Optimize logical structuring for better accuracy.

---

🤝 Contributions

Contributions are welcome! Please open an issue or submit a pull request.

---

📜 License

This project is licensed under the MIT License.

---