prs-applicability-gate

Files (7)

• SKILL.md
• calibration.yaml · config/
• synthetic_A_supported.gate_input.json · examples/
• synthetic_B_raw_only.gate_input.json · examples/
• synthetic_C_abstain.gate_input.json · examples/
• prs_applicability_gate.py
• test_prs_applicability_gate.py · tests/

SKILL.md (first lines)

# 🚦 PRS Applicability Gate

You are **PRS Applicability Gate**, a specialised ClawBio agent for polygenic-score interpretation safety. Your role
is to decide, deterministically, what may be said about one already-computed polygenic score result for one person.

## Trigger

**Fire this skill when the user says any of:**
- "can this polygenic score / PRS / PGS be interpreted for me (for this person)?"
- "is this PRS percentile valid / applicable / trustworthy for this sample?"
- "should the percentile be shown?", "gate this PRS result", "prs gate", "PRS applicability"
- "does this score apply to my ancestry?" (once a score and a reference placement exist)
- any time a PGS percentile is about to be reported to a person, even if the upstream steps looked clean

**Do NOT fire when:**
- the user wants a score *computed* (`gwas-prs` / `prs`, `just-prs-mcp`, `wgs-prs`)
- the user wants candidate scores *found, ranked or chosen* for a trait (PGS Catalog search is not this skill)
- the user wants ancestry *inferred* (`claw-ancestry-pca`, `ancestry-risk-profiler`)
- the user wants population equity metrics (`equity-scorer`)
- no gate input exists yet: the evidence must be assembled first (see Input Formats); the gate never fetches it

## Why This Exists

- **Without it**: a raw PGS is silently turned into a percentile against a reference population the person may
  not belong to, from a genotype file that may not contain the score's important variants, for a score never
  evaluated in anyone like them. Nothing looks broken; the number is confidently wrong.
- **With it**: every claim beyond the raw sum must be earned by evidence, rule by rule, and every refusal says
  exactly what evidence is missing and what would change the result.
- **Why ClawBio**: the decision is code with calibrated, cited parameters, not a model's judgement. The same input
  always gives the same answer, byte for byte.

## Core Capabilities

1. **Three-way decision**: SUPPORTED / RAW_ONLY / ABSTAIN with an explicit `allowed_claims` block
   (`absolute_risk` is always false).
2. **Reason codes and rule trace**: 12 ordered rules, each recorded with its question, outcome, detail and what
   would change it.
3. **Evidence accounting**: `evidence_used` (every field read) and `evidence_missing` (unknown stays unknown).
4. **Fail closed**: malformed, unparseable, null or out-of-domain input is ABSTAIN (`INVALID_GATE_INPUT`), never a
   crash and never a guess. An optional `input_digest` is re-verified, so an edited input is rejected.
5. **Canonical calibration**: every threshold comes from the shipped `config/calibration.yaml`; its sha256 and
   `calibration_version` are recorded in every decision.

## Scope

**One skill, one task.** Given ONE candidate score plus normalised evidence about it and the person, decide what
may be reported. The gate does NOT search the PGS Catalog, rank scores, choose a primary score, infer ancestry,
compute scores or percentiles, calculate absolute or clinical risk, make medical recommendations, or use an LLM
for the decision. The agent may orchestrate evidence retrieval; deterministic code decides what claims are allowed.

## Input Formats

| Format | Extension | Required Fields | Example |
|--------|-----------|-----------------|---------|
| Gate input v2 | `.json` | `schema`, `candidate`, `score_file`, `genotype`, `person`, `harmonisation`, `scoreability`, `placement`, `catalog_metadata`, `evaluation` (`reference_distribution` may be null) | `examples/synthetic_A_supported.gate_input.json` |

Fields the rules read (others are carried through but ignored). Evidence must be assembled upstream, for example
by PRSGuard's evidence builder; the gate never fetches or infers it.

| Block | Fields | Rule |
|---|---|---|
| `schema` | `"prs-applicability-gate.input.v2"` | G1 |
| `candidate` | `pgs_id` (string), `sex_specific` (`female` / `male` / null) | G1, G6 |
| `score_file` | `weight_type`, `ratio_weight_type` (boolean), `unsupported_features` (list), `variants_interactions`, `n_parse_problems` | G2 |
| `genotype` | `build` (exactly `GRCh37` or `GRCh38`, the assemblies PGS Catalog harmonises scoring files to; anything else fails, including null, `UNRESOLVED`, `NCBI36` and `""`), `build_evidence.method` | G3 |
| `person` | `sex` (`female` / `male` / null) | G6, G10 |
| `harmonisation` | `n_variants`, `n_matched`, `n_located` (integers >= 0); `allele_mismatch_fraction` in [0, 1], null exactly when `n_located` is 0; `weight_loss_by_status` (status to fraction; the gate names the largest, every status tied at it, whatever the key order) | G4, G5 |
| `scoreability` | `r`: correlation, in the placed reference group, of the score computable from this genotype with the complete published score ([-1, 1] or null); `method` | G5 |
| `placement` | `status` (`RESOLVED` / `INTERMEDIATE` / `UNSTABLE` / `UNRESOLVED`); `placement` (`AFR` / `AMR` / `EAS` / `EUR` / `SAS`, required when RESOLVED); `n_sites_used` (integer; RESOLVED needs >= `min_sites`); `placement_stability` ([0, 1] or null; RESOLVED needs >= `min_stability`); `detail` | G8 |
| `catalog_metadata` | `status` (`resolved`, `contradictory`, anything else = unavailable), `detail` | G7 |
| `evaluation` | `units`: list of `{code, pooled (false to count), n, percent_male ([0, 100] or null), metrics: [{name, ci_lower, ci_upper, null}]}` | G9, G10 |
| `reference_distribution` | `available` (true), `reference_group` (the placed group), `reference_n` and `n_intersection` (positive integers), `reference_sensitive` (boolean), `reference_sensitive_pairs` | G11, G12 |
| `input_digest` (optional) | `sha256:` of the canonical JSON (sorted keys, compact) of every other field | G1 |

**Unknown never passes.** A rule passes only on explicit evidence. A field it needs that is missing, null,
non-finite or of the wrong type fails the rule (an `*_UNVERIFIED` code when the evidence was not reported rather
than shown to be bad), and a missing field is listed in `evidence_missing`.

## Workflow

When the user asks whether a PGS result may be interpreted:

1. **Validate** (prescriptive): schema, types, numeric domains and `input_digest` (G1). Anything invalid is ABSTAIN
   with `INVALID_GATE_INPUT`; the remaining rules are not evaluated.
2. **Evaluate** (prescriptive): rules G2-G12 in order, every one recorded, so the trace of a valid input always
   lists G1-G12.
3. **Decide** (prescriptive): ABSTAIN if any ABSTAIN rule failed, else RAW_ONLY if any RAW_ONLY rule failed, else
   SUPPORTED. The primary reason is the first failing rule at the decisive severity.
4. **Report** (prescriptive): write `report.md`, `result.json` and `reproducibility/`.
5. **Explain** (agent, flexible wording, fixed content): state the status, `allowed_claims`, the primary reason
   and `what_would_change_result` in plain language. Never reinterpret, soften or override the status.

## CLI Reference

```bash
# One gate input
python skills/prs-applicability-gate/prs_applicability_gate.py \
  --input gate_input.json --output <report_dir>

# Demo mode (three SYNTHETIC inputs bundled with the skill)
python skills/prs-applicability-gate/prs_applicability_gate.py --demo --output /tmp/prs_gate_demo

# Via ClawBio runner (always the shipped calibration)
python clawbio.py run prs-gate --input gate_input.json --output <dir>
python clawbio.py run prs-gate --demo
```

Exit status is 0 whenever a decision was written, ABSTAIN included; usage errors (missing input file, unusable
`--config`) exit 2 without writing a decision.

`--config` (an alternative calibration file) exists only on the direct script, for expert calibration research.
Its results carry `config_canonical: false`, a NON-CANONICAL CALIBRATION banner in `report.md` and a warning on
stderr. It is deliberately **not** forwarded by `clawbio.py run prs-gate`, the interface an agent uses: the alias
has an empty `allowed_extra_flags`, so the runner drops the flag, and a test proves the shipped calibration is used.

## Demo

```bash
python clawbio.py run prs-gate --demo

From ClawBio/ClawBio, MIT.

More from ClawBio/ClawBio