EXACT — Clinical Trial Matching Engine

EXACT (EXtracting Attributes from Clinical Trials) is a stateless search and matching engine for clinical trials. It connects to an external database that holds the trial catalog and reference data — EXACT does not own or manage that data.

Patient profiles are passed inline with each API request. They can also be retrieved from an external database that has a PatientInfo table in the form implemented by CTOMOP, which exposes a flat projection of a patient record from underlying OMOP tables.

Documentation

Doc	Description
docs/overview.md	Architecture, key components, data flow
docs/trials4patients.md	Running trial search for patients
docs/evaluator.md	Evaluating EXACT results against ground truth
docs/setup.md	Local development setup
docs/api.md	REST API reference

Running trial search for patients

To match patients from an external patient database against the trial catalog without a running web server:

export TRIALS_DATABASE_URL=postgresql://...
export PATIENT_DATABASE_URL=postgresql://...

bash scripts/trials4patients.sh

See docs/trials4patients.md for all options.

Evaluating results

To score EXACT results against a ground-truth CSV:

RESULTS_CSV=results.csv bash scripts/trials4patients.sh
bash scripts/evaluator/evaluate.sh scripts/evaluator/ground_truth.csv results.csv

See docs/evaluator.md for metrics, full workflow, and output options.

Quick start (connecting to an existing trials database)

pip install -r requirements.txt

# Local DB for auth/tokens only
python manage.py migrate

# Point to the external trials database
export TRIALS_DATABASE_URL=postgresql://readonly:secret@trials-db.example.com:5432/trials

python manage.py runserver

Quick start (standalone / local development)

When no external trials database is configured, EXACT falls back to a single local database for everything — useful for development and testing:

pip install -r requirements.txt
python manage.py migrate
python manage.py seed_reference_data
python manage.py runserver

See docs/setup.md for full instructions including database setup, environment variables, and test configuration.

Configuration & secrets

EXACT is a public repository. All runtime configuration is supplied through environment variables — never commit secret values to git.

• Local dev: copy .env.example to .env and fill in values. Everything matching .env* (except .env.example) is git-ignored.
• Secrets never enter git. .gitignore blocks .env*, Terraform state and vars (*.tfvars, *.tfstate*, .terraform/), service-account JSON (*serviceAccount*.json, *-firebase-adminsdk-*.json, *-sa-key.json, firebase-sa-key.json), and private keys (*.pem, *.key).
• Production/staging: secrets such as SECRET_KEY, database credentials, TRIALS_DATABASE_URL, and CTOMOP_SERVICE_TOKEN come from the host platform's secret store (e.g. GCP Secret Manager) and are injected as environment variables at runtime — never from files in this repo.
• When CI deployment is added, it should authenticate to the cloud keyless (GitHub OIDC / Workload Identity Federation). Do not store a long-lived service-account JSON key in the repo or in CI.