Pharmacogenomics

Pharmacogenomics

Use this skill when the user asks about medication response, PGx guidelines, drug-gene or variant-drug evidence, PGxDB, ATC codes, DrugBank IDs, PharmCAT, or pharmacogene sample evidence.

Contract

• Drug-response claims use public PGx source evidence.
• Personal drug-response statements cite separate local genotype or PGx caller support.
• External PGx lookups receive selected public targets only.
• Source-backed PGx findings can be stored as shared reviewed research.
• User-specific sample interpretations can be stored as private reviewed research.

Convention: See skills/conventions/evidence-quality.md. Convention: See skills/_output-rules.md.

Primary Flow

1. Use pharmacogenomics.review_medication for ordinary medication questions. It combines ClinPGx, FDA PGx tables, PGxDB, stored reviewed research, and optional selected sample evidence in one bounded review.
2. Inspect evidence_envelope, medication_review_matrix, evidence_matrix, target_inventory, answer_support, and unanswered_answer_components before answering. Treat each medication_review_matrix.rows[] entry as the review unit.
3. If the answer needs source review beyond returned public records, use research.list_sources, review the selected public target, then store the finding with research.record.
4. If the answer needs personal sample evidence, use the Active Genome Index only when selected or supplied in this chat. Confirm relevant alleles with variant.resolve or active_genome_index.classify_genotype_support.

Tool Choices

• pharmacogenomics.review_medication: bounded medication evidence review; public-only by default, with Active Genome Index evidence when selected.
• pharmacogenomics.fetch_clinpgx, pharmacogenomics.fetch_fda_labels, and pharmacogenomics.fetch_pgxdb: focused public PGx source retrieval when the medication review needs a source-specific follow-up.
• pharmacogenomics.describe_gene_requirements: gene-specific sample evidence requirements for named allele matching, outside calls, HLA, MT-RNR1, G6PD, and SV/CNV-sensitive genes.
• pharmacogenomics.check_pharmcat: check local PharmCAT availability.
• pharmacogenomics.preflight_pharmcat: inspect whether the selected Active Genome Index can provide a suitable PharmCAT input before running it.
• pharmacogenomics.prepare_outside_call_tsv and pharmacogenomics.validate_outside_call_tsv: prepare or validate specialized outside-call evidence for PharmCAT.
• pharmacogenomics.run_pharmcat: run broad PharmCAT calling from the selected Active Genome Index and return provenance plus sample_pgx_matrix rows projected from report, phenotype, calls-only, and matcher artifacts.
• pharmacogenomics.import_pharmcat_artifacts: import existing PharmCAT JSON, TSV, matcher, phenotype, missing-position, or output-directory artifacts and return sample_pgx_matrix.

PGx capability metadata is exposed through genomi.list_resources; there is no separate PGx capability-listing tool.

Answering

• Mention Active Genome Index evidence only when it changes the medication interpretation, limitation, blocker, or next action.
• Keep PGx language informational and recommend clinical confirmation for medication decisions.
• Do not infer medication actionability from a genotype alone; connect sample evidence to public drug-response evidence.
• Treat user-provided diplotypes, phenotypes, activity scores, and outside calls as supplied sample evidence that may need independent confirmation.

Cross-Capability Synthesis

A scope-limited result from this capability is not a final user-facing answer when other Genomi capabilities can contribute orthogonal evidence to the same question. Returning "cannot answer" while applicable capabilities remain unexamined is a host-agent failure mode.

Tools

pharmacogenomics.check_pharmcat

Check local PharmCAT availability and version provenance for broad PGx calling from an AGI-derived PharmCAT input.

Use when: The agent needs to know whether broad PharmCAT PGx calling is available before running pharmacogenomics.run_pharmcat.

Why necessary: External PGx calls need availability and version provenance before they are trusted.

Result semantics: Reports local PharmCAT executable/jar availability and version probe output for auditability before broad PGx calling.

pharmacogenomics.describe_gene_requirements

Return pharmacogene-specific sample evidence requirements for PharmCAT named allele matching, outside calls, CYP2D6 SV/CNV handling, HLA typing, MT-RNR1, and G6PD chrX representation.

Use when: The selected medication or source evidence names a pharmacogene and the agent needs to choose sample evidence, PharmCAT, outside-call, or targeted lookup handling.

Why necessary: Complex pharmacogenes require special evidence handling that a simple rsID lookup cannot provide.

Result semantics: Returns packaged source-backed pharmacogene sample-evidence requirements, candidate tools, and source references for the selected gene.

pharmacogenomics.fetch_clinpgx

Fetch traceable ClinPGx pharmacogenomic guideline, clinical annotation, and FDA label evidence for a selected drug, gene, or rsID; compact normalized records are returned by default.

Use when: The question involves medication response, adverse effects, CPIC/DPWG guidance, FDA drug-label PGx context, PharmGKB/ClinPGx annotations, or drug plus gene/rsID interpretation.

Why necessary: Guideline, clinical annotation, and label rows are separate public PGx evidence from sample genotype calls.

Result semantics: Fetches public guideline, annotation, and label rows; raw API records are opt-in with include_raw_records; personal interpretation requires separate local genotype or diplotype evidence.

pharmacogenomics.fetch_fda_labels

Fetch targeted FDA pharmacogenomic biomarker-labeling and pharmacogenetic-association table rows from official FDA pages.

Use when: The question needs FDA biomarker-labeling table context or FDA pharmacogenetic association table context for a selected drug or gene.

Why necessary: FDA biomarker and pharmacogenetic-association tables are official label evidence with their own boundaries.

Result semantics: Fetches official FDA table rows; keep biomarker-labeling rows separate from pharmacogenetic-association rows and combine with separate sample evidence for personal interpretation.

pharmacogenomics.fetch_pgxdb

Fetch targeted PGxDB pharmacogenomic evidence for a selected drug, ATC code, DrugBank ID, rsID, variant marker, or gene.

Use when: The question involves medication response, adverse effects, pharmacogenomics, PharmGKB-style evidence, a drug plus rsID, or a drug plus gene.

Why necessary: PGxDB association records provide targeted drug-variant evidence distinct from guideline recommendations.

Result semantics: Fetches public PGxDB rows; sample interpretation requires separate local genotype evidence.