Case study / 04

Trial Unity

Explainable clinical-trial matching with eligibility, relevance, and representation in view.

Trial Unity’s revamped design starts with normalized ClinicalTrials.gov studies and deterministic eligibility constraints, then uses embedding-based retrieval and reranking to surface relevant candidates. A separate ESR signal incorporates socioeconomic, sex, and race representation into prioritization without overriding eligibility. The aim is an inspectable path from patient profile to ranked matches, with reasoning traceable to study criteria and source records. It supports trial discovery and review, not diagnosis or treatment selection.

Python
FastAPI
Pydantic
JavaScript
ClinicalTrials.gov API
Docker

GitHub Demo

Deterministic eligibilityRetrieval + rerankingRepresentation-aware priority

Current product demo · chips describe the revamped design.

Eligibility First

Hard constraints define the candidate set before relevance ranking.

Semantic Retrieval

Embeddings recover relevant studies beyond exact keyword overlap.

Reranked Matches

A separate stage refines the ordering of retrieved candidates.

Representation Stays Separate

ESR can influence priority; it cannot override eligibility.

System architecture

Revamped design: ClinicalTrials.gov ingestion and normalization, deterministic eligibility, embedding retrieval, reranking, separate ESR prioritization, then explainable matches. Evaluation is future work. — View full diagram
**Eligibility → relevance → representation.** These are separate decisions. Passing encoded constraints is a screening result, not confirmation of clinical eligibility.
The diagram describes the revamped design. The repository currently provides normalized trial records, baseline ranking, and source-linked explanations; the new eligibility gate, embeddings, reranker, and ESR stage remain unverified in code.

Engineering decisions

Decision	Why	Tradeoff
Deterministic eligibility before semantic ranking.	Similarity cannot replace inclusion and exclusion constraints.	Criteria need explicit, machine-checkable rules and validation.
Retrieval followed by reranking.	Candidate discovery and final ordering serve different purposes.	Another stage to evaluate and tune against labeled matches.
ESR independent from eligibility.	Representation can affect priority without changing the eligibility decision.	Weighting and interpretation need transparent validation.

Under the hood

Ingestion / Normalization

Verified foundation

ClinicalTrials.gov API v2 study ingestion
Pydantic Trial schema with normalized fields
Source eligibility text, age, and sex fields retained

Matching

Revamped design target

Deterministic constraints admit candidates
Embedding retrieval discovers relevant studies
A distinct reranker refines the ordering

Representation / Explanation

Revamped design target

ESR: Socioeconomic + Sex + Race
Representation affects post-eligibility priority
Trace reasoning back to criteria and study records

Technical deep dives

Eligibility → Retrieval → Reranking

View full diagram

Must qualify ≠ semantically similar. Retrieve only within the candidate set admitted by hard constraints.

Design boundary: embeddings measure relevance, not eligibility. Final study-team review remains necessary; the diagram does not establish medical qualification.

Proposed socioeconomic, sex, and race representation signal influences prioritization of eligible and relevant candidates without changing eligibility. — ESR Representation Logic
View full diagram
Socioeconomic + Sex + Race form a separate representation signal applied after eligibility and relevance.
Design boundary: ESR cannot reinstate excluded trials. No formula, weights, or measured equity improvements are verified; representation effects require evaluation.

Traceability by design

Match
Eligibility evidence
Semantic relevance
Representation context
Explanation

Keep the study identifier and source criteria attached to the reasoning at every stage.

System checks

Verified in the current code and test assertions.

API v2 normalization retains study IDs and source links.
Ranking returns the underlying trial record with each match.
Explanations include matched terms and ranking rationale.
Available study criteria produce eligibility review notes.

Inspect existing tests

Implement and test the revamped eligibility, retrieval, reranking, and ESR boundaries. Formalize evaluation with labeled match sets, ESR sensitivity analysis, and subgroup-level error analysis before claiming improved relevance or representation.