/clinical-trial-finder

name: clinical-trial-finder
description: Find clinical trials for a gene, variant, or condition from ClinicalTrials.gov + EUCTR, with FHIR R4 output
license: MIT
metadata:
  version: 0.1.0
  author: Duvet05 <gonzalo.galvezc@pucp.edu.pe>
  domain: clinical
  tags:
  - clinical-trials
  - genomics
  - drug-discovery
  - clinical
  - precision-medicine
  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
    description: Direct search query string (alternative to input_file)
    required: false
  - name: gene
    type: string
    description: Gene symbol (e.g. BRCA1) — enriched via OpenTargets gene-to-disease mapping
    required: false
  - name: rsid
    type: string
    description: dbSNP rsID (e.g. rs3798220) — resolved via GWAS Catalog to disease traits, then queried against CT.gov
    required: false
  - name: demo
    type: flag
    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'
  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}
  openclaw:
    requires:
      bins:
      - python3
    always: false
    emoji: 🏥
    homepage: https://github.com/ClawBio/ClawBio
    os:
    - darwin
    - linux
    trigger_keywords:
    - clinical trial
    - clinical trials
    - trial finder
    - FHIR
    - ResearchStudy
    - NCT
    - ClinicalTrials.gov
    - GWAS
    - rsID
    - variant

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, `https://www.healthit.gov/cures/sites/default/files/cures/2020-03/ONCCuresActFinalRule.pdf`.

• **FHIR resource type**: `ResearchStud