feat(cpic): CPIC pharmacogenomics POC on the V3 (part_of:is_a) GUID — ingest + reason + scan

[AdaWorldAPI]

A standalone cpic/ crate (mirrors fma/: isolated [workspace], zero impact on the q2 build) that addresses the CPIC pharmacogenomics database with the V3 canonical NodeGuid and its (part_of : is_a) tile — ingest → reason → scan, all three slices in.

POC over published CPIC rules — NOT clinical decision support (that needs full guideline text + pharmacist review). The disclaimer is in every binary's output.

The thesis held against the real data: CPIC already carries both hierarchies the tile wants — the gene→family partonomy (part_of, high byte) and the functional-status / metabolizer / ATC taxonomies (is_a, low byte) — sitting in its columns. Nothing invented.

Slice 1 — ingest (f405a90e)

Mints the 16-byte NodeGuid (byte-identical to lance_graph_contract::canonical_node::NodeGuid) for every entity. classid = pharmacogenomics domain 0x0C; each HHTL tier an 8:8 (part_of:is_a) tile via the same FNV prefix-cascade the fma converge bin uses; family = gene basin; identity = per-basin golden-ratio multiplicative mint (bijective ⇒ 0 collisions by construction). Edges: part_of, pair, recommends (via lookupkey), targets.

• 114,410 GUIDs, 0 collisions (110,346 the combinatorial diplotype layer).
• Both axes route (checked vs data): CYP2C19*2 and CYP2D6*4 (both no-function, both CYP2) share the full path c358-ec6f-f76f, only family differs.
• A real decision wires end-to-end: HLA-B *57:01 positive ──recommends──▶ [Strong] ──targets──▶ abacavir.

Slice 2 — reason (9f85c67f)

NARS reasoning over the real CPIC graph: {gene, diplotype|phenotype, drug} → phenotype → recommendation, 2-hop deduction (f=f1·f2, c=f1·f2·c1·c2) with authoritative confidence — f from recommendation.classification, c from the pair cpiclevel. Demos:

CYP2C19 *2/*2 + clopidogrel → Poor Metab → "Avoid clopidogrel… use prasugrel/ticagrelor" (f=0.95 c=0.77)
HLA-B *57:01 positive + abacavir → (1-hop) → "Abacavir is not recommended"             (c=0.89)
TPMT *3A/*3A + azathioprine → Poor Metab → "alternative nonthiopurine therapy"  ⚠ MULTI-GENE flag
CYP2C9 *1/*1 + warfarin → refuses to fabricate; surfaces CPIC's "does not follow simple translation" note

The last two matter as much as the first two — the POC flags the guidelines CPIC itself marks complex (warfarin notesonusage, multi-gene lookupkey) instead of auto-deducing a wrong answer.

Slice 3 — scan (9f85c67f)

The scalability headline. 1M-patient cohort, NodeRow = key(16) + value(496) [the canon's 512-byte node]. Query "how many are CYP2C19 Poor Metabolizer?":

key column 16 MB · value column 496 MB
  key-only (prefix-route)   10063 hits   817 M rows/s · 13.1 GB/s   [touched 16 B/row]
  value    (decode slab)    10063 hits     3 M rows/s ·  1.6 GB/s   [touched 496 B/row]
  speedup  251× wall-clock   (31× memory floor: 496/16 = the value column never read)

Both scans return the identical 10,063-patient cohort (asserted) — the canon's "key prerenders with zero value decode," where the value is the bulky consultationtext that genuinely never needs decompressing to answer the cohort question.

Engineering + honest scope

• src/lib.rs shares the GUID toolkit across all three bins; ingest refactored onto it with verified byte-identical output. All three bins clippy-clean.
• Reproducible on the 8 committed small CPIC tables (~4 MB); the 21.8 MB diplotype table + 27 MB allele_frequency (the future value column) are gitignored / fetched separately. ingest skips the diplotype layer with a notice when absent.
• maps_to (diplotype→phenotype) deferred — functionphenotypeid references a separate function_phenotype table (disjoint id space, verified 0 overlap) not in the dump. reason stands in with a transparent simple allele-function rule; confidence encodes the uncertainty; the authoritative table is a one-line join when it lands.
• Confidence weights (classification/cpiclevel → f/c) are a defensible, stated mapping — tunable, not a CPIC-published number.

Docs: cpic/docs/{INGEST,REASON,SCAN}.md + SAMPLE_GUIDS.tsv (25 curated rows showing the cascade).

🤖 Generated with Claude Code

https://claude.ai/code/session_01GJ4NVBSjq1w5h7RmTbVafb

[chatgpt-codex-connector]

You have reached your Codex usage limits for code reviews. You can see your limits in the Codex usage dashboard.
To continue using code reviews, you can upgrade your account or add credits to your account and enable them for code reviews in your settings.

[coderabbitai]

Warning

Review limit reached

@AdaWorldAPI, we couldn't start this review because you've reached your PR review rate limit.

More reviews will be available in 39 minutes and 49 seconds. Learn how PR review limits work.

Your organization has used up its prepaid credits, and credit purchases are no longer available. Enable the review add-on in the billing tab to keep reviews running — you're only billed for reviews past your plan's rate limits ($0.25/file).

⌛ How to resolve this issue?

After more reviews become available, a review can be triggered using the @coderabbitai review command as a PR comment. Alternatively, push new commits to this PR.

To avoid repeated limits, reduce automatic review volume by pausing incremental auto-reviews earlier, using label-based review opt-in, excluding WIP or generated PR titles, or requesting reviews manually when the PR is ready. If your team needs uninterrupted high-volume reviews, an organization admin can enable usage-based credits.

🚦 How do rate limits work?

CodeRabbit enforces per-developer PR review limits for each organization. Most developers receive the normal plan review availability.

For paid Pro and Pro+ PR reviews, CodeRabbit uses adaptive limits for sustained high-volume activity. When a developer's recent PR review activity reaches the 95th percentile or higher among CodeRabbit users, additional reviews become available more gradually as earlier reviews age out of the rolling window.

Please see our Fair Usage Limits Policy for further information.

ℹ️ Review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro Plus

Run ID: 6c6cbde9-8d4d-4f77-a26f-539093089680

📥 Commits

Reviewing files that changed from the base of the PR and between f405a90 and bd6d9bf.

⛔ Files ignored due to path filters (1)

• cpic/Cargo.lock is excluded by !**/*.lock

📒 Files selected for processing (8)

• cpic/.gitignore
• cpic/docs/INGEST.md
• cpic/docs/REASON.md
• cpic/docs/SCAN.md
• cpic/src/bin/ingest.rs
• cpic/src/bin/reason.rs
• cpic/src/bin/scan.rs
• cpic/src/lib.rs

📝 Walkthrough

Walkthrough

A new standalone Rust crate cpic/ is introduced. It adds committed CPIC JSON datasets (drugs, guidelines, gene results), a Rust binary ingest.rs that mints deterministic 16-byte NodeGuids via FNV-1a/cascade hashing across three tiers, builds a pharmacogenomic graph, and emits pgx_nodes.tsv and pgx_edges.tsv. Supporting documentation in INGEST.md describes the GUID layout and routing scheme.

Changes

CPIC PGx Ingest Pipeline

Layer / File(s)	Summary
Crate scaffold and gitignore cpic/Cargo.toml, cpic/.gitignore	Defines the isolated cpic Rust package with serde_json and release-profile optimizations; ignores build artifacts and large fetched data files.
Committed CPIC input datasets cpic/data/guideline.json, cpic/data/gene_result.json, cpic/data/drug.json	Adds the three committed JSON input tables (29 guidelines, 101 gene-result records, 323 drug entries) with standardized schema fields consumed by the ingest binary.
NodeGuid minting foundations and documentation cpic/docs/INGEST.md, cpic/src/bin/ingest.rs (lines 1–109)	Defines CPIC domain class IDs, FNV-1a hashing, cascade3, basin, the NodeGuid struct with canonical hex and 16-byte key16; INGEST.md documents the full GUID layout, (part_of : is_a) routing, classid domain map, edge types, and data sourcing.
Graph builder, IO, and normalization helpers cpic/src/bin/ingest.rs (lines 110–237)	Adds NodeSpec, Graph with per-(classid,family) identity counters, Graph::add for minting and collision detection, Graph::edge for TSV rows, load, norm, alpha_prefix, and func_class.
Main ingest: entity minting for all CPIC types cpic/src/bin/ingest.rs (lines 238–450)	Implements the full main pipeline: CLI arg parsing, then sequential minting of gene, drug, phenotype, allele, diplotype (optional, row-limited), recommendation, and pair nodes; creates part_of, targets, recommends, and pair edges with removal/absence skipping.
TSV output, summary, and routing demo cpic/src/bin/ingest.rs (lines 452–504)	Writes pgx_nodes.tsv and pgx_edges.tsv with headers; prints minted/collision/edge counts to stderr; emits a "both axes route" demo for fixed CYP allele examples.

Sequence Diagram(s)

sequenceDiagram
  participant CLI
  participant main as ingest binary
  participant JSON as CPIC JSON files
  participant Graph as Graph builder
  participant TSV as pgx_nodes and edges TSV

  CLI->>main: data_dir, out_dir, max_diplo
  main->>JSON: load gene, drug, gene_result, allele JSON
  main->>Graph: mint gene, drug, phenotype, allele nodes via cascade3 and NodeGuid
  Graph-->>main: stored GUIDs keyed by entity id
  main->>JSON: load gene_result_diplotype.json (optional)
  main->>Graph: mint diplotype nodes up to max_diplo
  main->>JSON: load recommendation and pair JSON
  main->>Graph: mint rec nodes and add part_of, targets, recommends, pair edges
  main->>TSV: write pgx_nodes.tsv and pgx_edges.tsv
  main-->>CLI: stderr summary of minted, collisions, edges, recs

Loading

Estimated code review effort

🎯 4 (Complex) | ⏱️ ~50 minutes

Poem

🐇 A rabbit hops through gene and drug,
Minting GUIDs snug as a bug,
FNV-1a spins the hash cascade,
TSV rows in order laid.
Part_of, recommends, the edges align—
This pharmacogenomic graph is fine! 🧬

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Docstring Coverage	✅ Passed	Docstring coverage is 93.33% which is sufficient. The required threshold is 80.00%.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly reflects the CPIC V3 ingest-focused proof of concept and the new workspace/data changes.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[coderabbitai]

Actionable comments posted: 7

🧹 Nitpick comments (1)

cpic/.gitignore (1)

3-3: 📐 Maintainability & Code Quality | 🔵 Trivial

Commit cpic/Cargo.lock. Keeping the lockfile in version control will keep dependency resolution stable for this application crate.

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@cpic/.gitignore` at line 3, The .gitignore entry is excluding the application
lockfile, but this crate should keep Cargo.lock under version control for stable
dependency resolution. Remove the Cargo.lock ignore rule from the .gitignore so
the lockfile can be committed and maintained alongside the cpic package.

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@cpic/data/drug.json`:
- Line 24: The ATC cascade derivation in ingest should ignore placeholder ATC
values like "NA" instead of treating them as real codes. Update the logic around
the ATC branch handling in the ingestion flow, especially the code that reads
each drug’s atcid and builds the cascade, so rows with only placeholder values
are skipped before attaching to the N branch. Use the existing ingest path and
ATC processing symbols in cpic/src/bin/ingest.rs to locate the cascade-building
code and filter invalid atcid entries before classification.

In `@cpic/data/gene_result.json`:
- Around line 1-101: Add the missing phenotype entries to gene_result.json for
the guideline genes ADRA2C, ADRB1, ADRB2, COMT, CYP4F2, GRK4, GRK5, HTR2A,
IFNL3, OPRM1, SLC6A4, and VKORC1 so the downstream recommendation logic can
match them. Use the existing gene_result objects as the template for required
fields and naming conventions, and ensure each gene has the phenotype/result
rows needed by the CPIC guideline branches. Locate this in the gene_result
dataset, since the recomputation of recommends edges depends on these exact
gene/result combinations being present.

In `@cpic/docs/INGEST.md`:
- Line 7: The INGEST.md CLI example is using unsupported key=value syntax for
the ingest binary; update the example to show the actual positional arguments
accepted by the main ingest command so it can be copy-pasted and run correctly.
Use the ingest invocation in the docs snippet and replace the bracketed
`data_dir=...`, `out_dir=...`, and `max_diplotype_rows=...` form with the
positional form that matches the `ingest` CLI behavior, such as the `cargo run
--release --bin ingest -- ...` example.
- Around line 19-27: Add an explicit language to each fenced code block in
INGEST.md so markdownlint MD040 is satisfied; update the unlabeled fences in the
diagrams and other referenced sections to use an appropriate language such as
text or console. Use the existing fenced blocks in the document as the targets
and keep the rendered content unchanged apart from the fence labels.

In `@cpic/src/bin/ingest.rs`:
- Around line 239-242: The zero-argument defaults in the ingest argument parsing
are using repository-root-relative paths instead of the standalone crate’s
paths, causing `ingest` to look in the wrong place when launched from `cpic/`.
Update the defaults in `main` where `std::env::args()` populates `dir` and `out`
so they match the crate layout and docs (`data` and `out`), while keeping the
existing behavior for explicit CLI arguments and `max_diplo` parsing.
- Around line 366-367: The diplotype ingest path in ingest.rs currently hides
malformed gene_result_diplotype.json data by using unwrap_or_default() after
serde_json::from_str, which turns parse failures into an empty layer. Update the
logic around the dipath read/parsing block so a JSON parse error is treated as a
real failure and is surfaced or propagated instead of producing zero rows, while
keeping the successful path that builds rows from serde_json::from_str and the
surrounding fs::read_to_string handling intact.
- Around line 387-395: The diplotype node is being created without using the
returned NodeGuid, so the promised diplotype-to-gene part_of relationship is
never emitted. Update the NodeSpec insertion in the diplotype creation path to
capture the NodeGuid from gr.add and then add the corresponding part_of edge
back to the gene using the existing symbols around the diplotype handling in
ingest.rs. Make sure the linkage is added for each minted diplotype so traversal
and the documented edge contract stay consistent.

---

Nitpick comments:
In `@cpic/.gitignore`:
- Line 3: The .gitignore entry is excluding the application lockfile, but this
crate should keep Cargo.lock under version control for stable dependency
resolution. Remove the Cargo.lock ignore rule from the .gitignore so the
lockfile can be committed and maintained alongside the cpic package.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro Plus

Run ID: 138a472a-0651-4f30-ada2-3e23cfb245af

📥 Commits

Reviewing files that changed from the base of the PR and between 6a84309 and f405a90.

⛔ Files ignored due to path filters (1)

• cpic/docs/SAMPLE_GUIDS.tsv is excluded by !**/*.tsv

📒 Files selected for processing (12)

• cpic/.gitignore
• cpic/Cargo.toml
• cpic/data/allele.json
• cpic/data/allele_definition.json
• cpic/data/drug.json
• cpic/data/gene.json
• cpic/data/gene_result.json
• cpic/data/guideline.json
• cpic/data/pair.json
• cpic/data/recommendation.json
• cpic/docs/INGEST.md
• cpic/src/bin/ingest.rs

[coderabbitai]

🗄️ Data Integrity & Integration | 🟠 Major

🧩 Analysis chain

🏁 Script executed:

#!/bin/bash
python - <<'PY'
import json
from pathlib import Path

guidelines = json.loads(Path("cpic/data/guideline.json").read_text())
gene_results = json.loads(Path("cpic/data/gene_result.json").read_text())

guideline_genes = sorted({g for row in guidelines for g in row.get("genes", [])})
result_genes = sorted({row["genesymbol"] for row in gene_results})
missing = sorted(set(guideline_genes) - set(result_genes))

print("guideline genes:", guideline_genes)
print("gene_result genes:", result_genes)
print("missing from gene_result:", missing)
PY

Repository: AdaWorldAPI/q2

Length of output: 793

---

🏁 Script executed:

#!/bin/bash
set -euo pipefail

# Inspect the ingestion logic that links guideline genes to phenotype entries.
grep -n "pheno_by_gr\|recommends\|genesymbol\|gene_result" -n cpic/src/bin/ingest.rs
sed -n '405,450p' cpic/src/bin/ingest.rs

# Show the guideline gene list shape to confirm the gene names are taken directly from guideline.json.
python3 - <<'PY'
import json
from pathlib import Path
guidelines = json.loads(Path("cpic/data/guideline.json").read_text())
print("rows:", len(guidelines))
print("sample row keys:", sorted(guidelines[0].keys()))
print("sample genes field type:", type(guidelines[0].get("genes")).__name__)
print("sample genes:", guidelines[0].get("genes"))
PY

Repository: AdaWorldAPI/q2

Length of output: 3182

---

🏁 Script executed:

#!/bin/bash
set -euo pipefail

# Inspect the ingestion logic that links guideline genes to phenotype entries.
grep -n "pheno_by_gr\|recommends\|genesymbol\|gene_result" -n cpic/src/bin/ingest.rs
sed -n '405,450p' cpic/src/bin/ingest.rs

# Show the guideline gene list shape to confirm the gene names are taken directly from guideline.json.
python3 - <<'PY'
import json
from pathlib import Path
guidelines = json.loads(Path("cpic/data/guideline.json").read_text())
print("rows:", len(guidelines))
print("sample row keys:", sorted(guidelines[0].keys()))
print("sample genes field type:", type(guidelines[0].get("genes")).__name__)
print("sample genes:", guidelines[0].get("genes"))
PY

Repository: AdaWorldAPI/q2

Length of output: 3182

---

🏁 Script executed:

#!/bin/bash
set -euo pipefail

grep -n "pheno_by_gr\|recommends\|genesymbol\|gene_result" cpic/src/bin/ingest.rs
sed -n '405,450p' cpic/src/bin/ingest.rs

python3 - <<'PY'
import json
from pathlib import Path
guidelines = json.loads(Path("cpic/data/guideline.json").read_text())
print("rows:", len(guidelines))
print("sample row keys:", sorted(guidelines[0].keys()))
print("sample genes field type:", type(guidelines[0].get("genes")).__name__)
print("sample genes:", guidelines[0].get("genes"))
PY

Repository: AdaWorldAPI/q2

Length of output: 3182

---

Add phenotype rows for the missing guideline genes. cpic/data/gene_result.json has no entries for ADRA2C, ADRB1, ADRB2, COMT, CYP4F2, GRK4, GRK5, HTR2A, IFNL3, OPRM1, SLC6A4, or VKORC1. Those guideline branches won’t emit recommends edges unless matching gene/result rows exist.

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@cpic/data/gene_result.json` around lines 1 - 101, Add the missing phenotype
entries to gene_result.json for the guideline genes ADRA2C, ADRB1, ADRB2, COMT,
CYP4F2, GRK4, GRK5, HTR2A, IFNL3, OPRM1, SLC6A4, and VKORC1 so the downstream
recommendation logic can match them. Use the existing gene_result objects as the
template for required fields and naming conventions, and ensure each gene has
the phenotype/result rows needed by the CPIC guideline branches. Locate this in
the gene_result dataset, since the recomputation of recommends edges depends on
these exact gene/result combinations being present.

[AdaWorldAPI]

Addressed the CodeRabbit review in bd6d9bfb — verified each finding against current code first.

Applied (6):

• Commit Cargo.lock (bin crate → stable resolution); removed from .gitignore.
• Drug ATC validation — 8 drugs carry placeholder atcid:["NA"] (methylene blue, dabrafenib, trametinib, …) that were being mis-filed under ATC main group "N". Now gated on a real ATC shape (letter + 2 digits).
• Default paths — ingest now auto-detects crate-relative vs repo-relative dirs (matching reason/scan), so a no-arg run from cpic/ works.
• Diplotype parse — propagate a JSON parse error instead of unwrap_or_default() silently emptying the layer.
• Diplotype part_of edge — the documented diplotype→gene edge is now emitted for recorded diplotypes (part_of 1450 → 5450; edges 6000 → 10000).
• Docs — positional-arg CLI example + text language on all fenced blocks (MD040), across INGEST/REASON/SCAN.

Skipped (1), deliberately: the suggestion to add phenotype rows to gene_result.json for ADRA2C/ADRB1/ADRB2/COMT/CYP4F2/GRK4/GRK5/HTR2A/IFNL3/OPRM1/SLC6A4/VKORC1. Those are modifier / allele-status / non-phenotype-lookup genes that genuinely have no gene_result rows in the CPIC dump — inventing phenotype data for them is exactly what this POC must not do (it's a reasoning POC over published CPIC rules, not a data-authoring tool). Their recommendations correctly receive no recommends edge; the absence is faithful to the source.

---

Generated by Claude Code