clinical-trial-finder

name	clinical-trial-finder
version	0.1.0
author	Duvet05 <[e-mail]>
domain	clinical
description	Find clinical trials for a gene, variant, or condition from ClinicalTrials.gov + EUCTR, with FHIR R4 output
license	MIT
inputs	[{"name":"input_file","type":"file","format":["txt"],"description":"Text file with one search term per line (gene name, condition, or drug)","required":false},{"name":"query","type":"string","format":[],"description":"Direct search query string (alternative to input_file)","required":false},{"name":"gene","type":"string","format":[],"description":"Gene symbol (e.g. BRCA1) — enriched via OpenTargets gene-to-disease mapping","required":false},{"name":"rsid","type":"string","format":[],"description":"dbSNP rsID (e.g. rs3798220) — resolved via GWAS Catalog to disease traits, then queried against CT.gov","required":false},{"name":"demo","type":"flag","format":[],"description":"Run with built-in demo data (BRCA1 breast cancer)","required":false}]
outputs	[{"name":"report","type":"file","format":"md","description":"Markdown report with matched trials, status, phase, and links to ClinicalTrials.gov"},{"name":"summary","type":"file","format":"json","description":"Machine-readable trial data for programmatic use"},{"name":"fhir_bundle","type":"file","format":"json","description":"FHIR R4 Bundle of ResearchStudy resources with MeSH-coded conditions (written with --fhir)"},{"name":"phase_distribution","type":"file","format":"png","description":"Stacked bar chart of trial counts by phase, coloured by recruitment status (figures/phase_distribution.png)"},{"name":"commands","type":"file","format":"sh","description":"Exact CLI invocation to reproduce this run (commands.sh)"},{"name":"checksums","type":"file","format":"txt","description":"SHA-256 digests of all generated outputs (checksums.sha256)"},{"name":"html_report","type":"file","format":"html","description":"Interactive HTML report with JS filters (status, phase, text search) and coloured trial cards (report.html)"},{"name":"csv_table","type":"file","format":"csv","description":"Trial data as CSV for import into Excel, R, or pandas (tables/trials.csv)"}]
dependencies	{"python":">=3.11","packages":[]}
tags	["clinical-trials","genomics","drug-discovery","clinical","precision-medicine"]
metadata	{"openclaw":{"requires":{"bins":["python3"],"env":[],"config":[]},"always":false,"emoji":"🏥","homepage":"https://github.com/ClawBio/ClawBio","os":["darwin","linux"],"install":[],"trigger_keywords":["clinical trial","clinical trials","trial finder","FHIR","ResearchStudy","NCT","ClinicalTrials.gov","GWAS","rsID","variant"]}}
demo_data	[{"path":"demo_input.txt","description":"Synthetic query for BRCA1 breast cancer trials — exercises recruiting and completed status paths"}]
endpoints	{"cli_gene":"python skills/clinical-trial-finder/clinical_trial_finder.py --gene {gene} --output {output_dir}","cli_rsid":"python skills/clinical-trial-finder/clinical_trial_finder.py --rsid {rsid} --output {output_dir}","cli_query":"python skills/clinical-trial-finder/clinical_trial_finder.py --query \"{query}\" --output {output_dir}","cli_file":"python skills/clinical-trial-finder/clinical_trial_finder.py --input {input_file} --output {output_dir}","cli_demo":"python skills/clinical-trial-finder/clinical_trial_finder.py --demo --output {output_dir}"}

Domain Decisions

• Source database: ClinicalTrials.gov API v2 (https://clinicaltrials.gov/api/v2) — the authoritative US registry mandated by FDAAA 801 (2007) and mirrored by WHO ICTRP. Chosen over EudraCT/EUCTR because it covers the largest global trial volume (>500 000 studies), provides a stable versioned REST API, and is the primary registry for FDA-regulated interventions. Reference: Zarin et al., NEJM 2011; 364:852–860.

• Query field: query.cond (condition/disease field), not query.term (free-text across all fields). query.cond is indexed against MeSH descriptors by the NLM indexing pipeline, giving substantially better recall for condition queries than unstructured text search. Reference: ClinicalTrials.gov API v2 specification, https://clinicaltrials.gov/data-api/api.

• MeSH condition coding: MeSH IDs are read from derivedSection.conditionBrowseModule.meshes — the NLM-curated MeSH mapping that ClinicalTrials.gov computes internally during study indexing. This avoids a separate NLM API call and uses the same vocabulary that query.cond is indexed against, ensuring query/result consistency. Reference: NLM Medical Subject Headings, https://www.nlm.nih.gov/mesh/.

• Max results: 20 trials per query by default (configurable with --max-results). Clinical actionability does not scale with result volume — a clinician reviewing >20 trials without eligibility pre-screening is unlikely to act on any. The default balances coverage with usability.

• Status display: All statuses returned are shown — no pre-filtering. Recruiting trials are highlighted; TERMINATED and WITHDRAWN trials are flagged with a distinct visual indicator and never omitted. Selective display of only active trials would introduce reporting bias and obscure negative evidence. Reference: Chan et al., PLoS Med 2004; 1:e62 (trial publication bias).

• Phase reporting: Phases are reported verbatim from the API and mapped to HL7 FHIR R4 ResearchStudy.phase codes. No lay-term substitution is made to preserve accuracy and avoid misrepresentation.

• FHIR version: FHIR R4, not R5. The ONC 21st Century Cures Act Final Rule (2020) mandates FHIR R4 for certified EHR systems in the US, making R4 the de facto standard for EHR interoperability with Epic, Cerner, and Oracle Health. R5 is in early adoption as of 2026 — using R5 would reduce compatibility with deployed infrastructure. Reference: 45 CFR Part 170, .