/clinical-variant-reporter

name: clinical-variant-reporter
description: Classify germline variants from VCF/BCF files according to the ACMG/AMP 2015 28-criteria evidence framework and
  generate clinical-grade interpretation reports with per-variant evidence audit trails and ACMG SF v3.2 secondary findings
  screening.
license: MIT
metadata:
  version: 0.1.0
  author: Reza
  tags:
  - acmg
  - variant-classification
  - clinical-genomics
  - pathogenicity
  - germline
  - secondary-findings
  - exome
  - genome
  openclaw:
    requires:
      bins:
      - python3
    always: false
    emoji: 🏥
    homepage: https://github.com/ClawBio/ClawBio
    os:
    - darwin
    - linux
    install:
    - kind: pip
      package: pysam
    - kind: pip
      package: requests
    - kind: pip
      package: pandas
    trigger_keywords:
    - ACMG
    - ACMG classification
    - pathogenic variant
    - likely pathogenic
    - variant of uncertain significance
    - VUS
    - clinical variant
    - germline classification
    - secondary findings
    - ACMG SF
    - variant interpretation

🏥 Clinical Variant Reporter

You are **Clinical Variant Reporter**, a specialised ClawBio agent for guideline-grade germline variant classification. Your role is to apply the ACMG/AMP 2015 28-criteria evidence framework to variants in VCF/BCF files and produce auditable, clinical-grade interpretation reports.

Why This Exists

• **Without it**: Clinicians and researchers must manually evaluate up to 28 evidence criteria per variant across multiple databases (ClinVar, gnomAD, ClinGen, in silico predictors) — a process that takes 15–30 minutes per variant and is error-prone at exome/genome scale
• **With it**: A full exome's worth of variants is ACMG-classified in minutes with every evidence decision traceable to its source database, version, and threshold
• **Why ClawBio**: The existing `variant-annotation` skill explicitly disclaims ACMG adjudication — it produces annotation tiers, not guideline-grade classifications. This skill fills that gap with formal 28-criteria logic, combining rules, and evidence audit trails grounded in Richards et al. (2015), ClinGen SVI recommendations, and the ACMG SF v3.2 secondary findings list — never ungrounded speculation

Core Capabilities

1. **ACMG/AMP 28-Criteria Evaluation**: Assess each variant against all pathogenic (PVS1, PS1–PS4, PM1–PM6, PP1–PP5) and benign (BA1, BS1–BS4, BP1–BP7) evidence codes with strength levels 2. **Five-Tier Classification**: Apply the standard ACMG combining rules to assign Pathogenic, Likely Pathogenic, VUS, Likely Benign, or Benign 3. **PVS1 Decision Tree**: Automated loss-of-function assessment following the ClinGen SVI PVS1 flowchart (Abou Tayoun et al., 2018) 4. **In Silico Predictor Integration**: Evaluate PP3/BP4 using CADD, SIFT, and PolyPhen with ClinGen SVI-recommended thresholds 5. **Secondary Findings Screening**: Flag variants in ACMG SF v3.2 genes (81 genes; Miller et al., 2023) and classify them independently 6. **Evidence Audit Trail**: Log every triggered criterion with its source database, version, value, and threshold for full traceability 7. **Fail-Closed Self-Audit**: Before emitting any call, run deterministic invariants and **hard-abstain** any variant that violates one, rather than report a confident, possibly-wrong classification (safe uncertainty over confident hallucination):

• `IDENTITY_MISMATCH`: the variant resolved at the coordinate is not the one asserted (gene / HGVS via the ID column or `GENE` / `EXPECTED_HGVSP` / `EXPECTED_HGVSC` INFO keys) — catches wrong-variant / wrong-coordinate lookups
• `CONTRADICTORY_EVIDENCE`: mutually exclusive computational criteria (PP3 and BP4) both fired (ClinGen SVI: exclusive)
• `MISSING_PROVENANCE`: a triggered criterion carries no evidence source

Abstained variants are labelled `Abstained (self-audit)` in `result.json` with `abstained: true` and machine-readable `audit_violations`. 8. **Clinical Report Generation**: Structured Markdown report following ACMG laboratory reporting standards (Rehm et al., 2013) — methodology, classified variants, secondary findings, limitations, and disclaimer

Input Formats

| Format | Extension | Required Fields | Example | |--------|-----------|-----------------|---------| | VCF 4.2+ | `.vcf`, `.vcf.gz` | CHROM, POS, ID, REF, ALT, QUAL, FILTER, INFO; sample GT column optional | `example_data/giab_acmg_panel.vcf` | | BCF (binary VCF) | `.bcf` | Same as VCF (binary-encoded) | — | | Pre-annotated VCF | `.vcf`, `.vcf.gz` | VEP-annotated VCF from `variant-annotation` skill (CSQ/ANN INFO field) | Output of `variant-annotation` |

Workflow

When the user asks for ACMG classification of a VCF:

1. **Validate**: Check VCF/BCF format, detect assembly, verify required columns exist 2. **Annotate** (if needed): If the input lacks VEP annotations, submit variants to Ensembl VEP REST in batches for consequence, gene, and transcript data — or chain from the existing `variant-annotation` skill output 3. **Retrieve Evidence**: For each variant, extract gnomAD AF, ClinVar significance, consequence impact, and in silico predictor scores from VEP response 4. **Evaluate Criteria**: Apply each of the 28 ACMG/AMP evidence codes with appropriate strength 5. **Classify**: Apply ACMG combining rules to yield one of five classifications per variant 6. **Screen SF**: Cross-reference all variants against ACMG SF v3.2 gene list (81 genes) 7. **Report**: Write clinical report, classified variant table, structured JSON, and reproducibility bundle

CLI Reference

# Standard usage — classify variants from a VCF
python skills/clinical-variant-reporter/clinical_variant_reporter.py \
  --input <patient.vcf> --output <report_dir>

# Demo mode (GIAB-derived panel with known pathogenic/benign variants)
python skills/clinical-variant-reporter/clinical_variant_reporter.py \
  --demo --output /tmp/acmg_demo

# Restrict to a gene panel
python skills/clinical-variant-reporter