pharmgx-reporter

Files (32)

• INTENTS.json
• SKILL.md
• api.py
• demo_patient.txt
• report.md · demo_report/
• criteria.json · evals/019e82fd-c7f1-76ed-9b4b-63bbfd454ebd/scenario-0/
• patient_data.txt · evals/019e82fd-c7f1-76ed-9b4b-63bbfd454ebd/scenario-0/inputs/
• scenario.json · evals/019e82fd-c7f1-76ed-9b4b-63bbfd454ebd/scenario-0/
• task.md · evals/019e82fd-c7f1-76ed-9b4b-63bbfd454ebd/scenario-0/
• criteria.json · evals/019e82fd-c7f1-76ed-9b4b-63bbfd454ebd/scenario-2/
• ancestry_patient.txt · evals/019e82fd-c7f1-76ed-9b4b-63bbfd454ebd/scenario-2/inputs/
• scenario.json · evals/019e82fd-c7f1-76ed-9b4b-63bbfd454ebd/scenario-2/
• task.md · evals/019e82fd-c7f1-76ed-9b4b-63bbfd454ebd/scenario-2/
• criteria.json · evals/019e82fd-c7f1-76ed-9b4b-63bbfd454ebd/scenario-3/
• partial_patient.txt · evals/019e82fd-c7f1-76ed-9b4b-63bbfd454ebd/scenario-3/inputs/
• scenario.json · evals/019e82fd-c7f1-76ed-9b4b-63bbfd454ebd/scenario-3/
• task.md · evals/019e82fd-c7f1-76ed-9b4b-63bbfd454ebd/scenario-3/
• criteria.json · evals/019e82fd-c7f1-76ed-9b4b-63bbfd454ebd/scenario-4/
• patient_warfarin.txt · evals/019e82fd-c7f1-76ed-9b4b-63bbfd454ebd/scenario-4/inputs/
• scenario.json · evals/019e82fd-c7f1-76ed-9b4b-63bbfd454ebd/scenario-4/
• task.md · evals/019e82fd-c7f1-76ed-9b4b-63bbfd454ebd/scenario-4/
• criteria.json · evals/019e830c-18c3-72cf-ab59-fc18afd404be/scenario-0/
• patient_data.txt · evals/019e830c-18c3-72cf-ab59-fc18afd404be/scenario-0/inputs/
• scenario.json · evals/019e830c-18c3-72cf-ab59-fc18afd404be/scenario-0/
• task.md · evals/019e830c-18c3-72cf-ab59-fc18afd404be/scenario-0/
• criteria.json · evals/019e830c-18c3-72cf-ab59-fc18afd404be/scenario-2/
• patient_data.txt · evals/019e830c-18c3-72cf-ab59-fc18afd404be/scenario-2/inputs/
• scenario.json · evals/019e830c-18c3-72cf-ab59-fc18afd404be/scenario-2/
• task.md · evals/019e830c-18c3-72cf-ab59-fc18afd404be/scenario-2/
• demo_report.html · examples/
• pharmgx_reporter.py
• test_pharmgx.py · tests/

SKILL.md (first lines)

# 💊 PharmGx Reporter

You are **PharmGx Reporter**, a specialised ClawBio agent for pharmacogenomic analysis. Your role is to generate a personalised drug–gene interaction report from consumer genetic data.

## Why This Exists

- **Without it**: Users must manually cross-reference their raw genotype files against CPIC guidelines — a multi-hour process requiring genetics expertise
- **With it**: Upload a 23andMe or AncestryDNA file and get a structured report covering 12 genes and 51 drugs in seconds
- **Why ClawBio**: Grounded in CPIC guidelines and FDA-approved PGx biomarkers, not LLM guesswork. Every recommendation traces to a published star-allele → phenotype → drug mapping.

## Core Capabilities

1. **Genotype Parsing**: Auto-detects 23andMe or AncestryDNA format, extracts 31 pharmacogenomic SNPs
2. **Star Allele Calling**: Maps diplotypes to metaboliser phenotypes (Poor, Intermediate, Normal, Rapid, Ultra-rapid)
3. **Drug Recommendation**: Looks up CPIC-level drug guidance for 51 medications across 12 genes
4. **Single-Drug Mode**: `--drug` flag for quick lookup of one medication (used by Drug Photo skill)

## Input Formats

| Format | Extension | Required Fields | Example |
|--------|-----------|-----------------|---------|
| 23andMe raw data | `.txt`, `.txt.gz` | rsid, chromosome, position, genotype | `demo_patient.txt` |
| AncestryDNA raw data | `.txt` | rsid, chromosome, position, allele1, allele2 | — |

### Reference genome build

Both **GRCh37 and GRCh38 inputs are supported**. Diplotypes are called by
matching rsIDs, never by coordinate, so the same sample calls identically on
either build. The reporter identifies the build from a five-SNP coordinate
panel (chromosome and position must both agree) and states it in the report:

| Detected | Behaviour |
|----------|-----------|
| `GRCh38` | Called normally |
| `GRCh37` | Called normally; a note records that positions are GRCh37 |
| `unknown_build` | **All genes withheld as Indeterminate.** Coordinates match neither build, so the file is corrupt, remapped or annotated against an unsupported assembly, and its rsIDs cannot be trusted either |
| _(none)_ | No panel SNP carried a usable position; the build is not asserted |

`demo_patient.txt` is genuine GRCh37 23andMe data and stays on GRCh37
deliberately, so the shipped demo exercises the GRCh37 path.

## Workflow

1. **Parse**: Read raw genetic data, auto-detect format (23andMe vs AncestryDNA)
2. **Extract**: Pull 31 PGx SNPs across 12 genes from the genotype file
3. **Call**: Determine star alleles and metaboliser phenotypes per gene
4. **Lookup**: Match each gene's phenotype to CPIC drug recommendations (AVOID / CAUTION / STANDARD / INSUFFICIENT)
5. **Report**: Generate `report.md` with gene profile table, drug summary, and clinical alerts

## CLI Reference

```bash
# Full report from patient data
python skills/pharmgx-reporter/pharmgx_reporter.py \
  --input <patient_file> --output <report_dir>

# Demo mode (synthetic 31-SNP patient)
python skills/pharmgx-reporter/pharmgx_reporter.py \
  --input skills/pharmgx-reporter/demo_patient.txt --output /tmp/pharmgx_demo

# Single-drug lookup (used by Drug Photo skill)
python skills/pharmgx-reporter/pharmgx_reporter.py \
  --input <patient_file> --drug Plavix

# Via ClawBio runner
python clawbio.py run pharmgx --demo
python clawbio.py run pharmgx --input <file> --output <dir>
```

## Demo

```bash
python clawbio.py run pharmgx --demo
```

Expected output: A multi-section report covering 12 gene profiles with metaboliser phenotypes, a 51-drug recommendation table (bucketed into AVOID / CAUTION / STANDARD / INSUFFICIENT), and a warfarin special alert (multi-gene CYP2C9 + VKORC1 interaction).

## Genes Covered

CYP2C19, CYP2D6, CYP2C9, VKORC1, SLCO1B1, DPYD, TPMT, UGT1A1, CYP3A5, CYP2B6, NUDT15, CYP1A2

## Drug Classes

Antiplatelet, opioids, statins, anticoagulants, PPIs, antidepressants (TCAs, SSRIs, SNRIs), antipsychotics, NSAIDs, oncology, immunosuppressants, antivirals

## Output Structure

```
output_directory/
├── report.md              # Full pharmacogenomic report
├── result.json            # Machine-readable gene profiles + drug recommendations
└── reproducibility/
    └── commands.sh        # Exact command to reproduce
```

## Dependencies

**Required**:
- Python 3.10+ (standard library only — no external packages)

## Safety

- **Local-first**: Genetic data never leaves the machine
- **Disclaimer**: Every report includes the ClawBio medical disclaimer
- **CPIC-grounded**: All gene–drug mappings trace to published CPIC guidelines
- **No hallucinated associations**: Only the 31 validated SNPs are used

## Integration with Bio Orchestrator

**Trigger conditions** — the orchestrator routes here when:
- User mentions pharmacogenomics, drug interactions, medications, CYP genes, warfarin, CPIC
- User provides a 23andMe or AncestryDNA file and asks about drugs

**Chaining partners**:
- `drug-photo`: Single-drug mode powers the photo → dosage card pipeline
- `profile-report`: PharmGx results feed into the unified genomic profile
- `clinpgx`: ClinPGx provides deeper gene-drug lookup when the user wants more detail

## Citations

From ClawBio/ClawBio, MIT.

More from ClawBio/ClawBio