Phase 8.5 — Variant-Aware KG Extension — Planning Document

Status: PARTIAL — schema landed, CIViC ingested, Phase 12 V1 patient-as-node done for Maureen. OncoKB + PharmGKB connectors coded but not ingested. Patient→variant edges are still gene-level — fix pending. Created: 2026-05-07 Last updated: 2026-05-14 (post-canonical-cutover audit) Owner: whafa Master plan reference: PDR_PIPELINE_PLAN.md § Phase 8.5 Companion writeup template: pdr_phase0_gpkg_writeup.md

This document is the seed for a dedicated planning session. It contains: (1) the problem statement and why this work matters, (2) a draft Phase 8.5 plan with checklist sub-phases, (3) context on how biomedical KG merging actually works in practice, (4) open questions to be resolved in the planning session, and (5) suggested next steps to convert this from “draft” to “executable.”

---

Status snapshot (2026-05-14, against the canonical KG mods_kg_entity / mods_kg_relation)

Audit triggered after the 2026-05-13 canonical-cutover; reality is materially ahead of the original “PLANNING” status:

• 4,124 variant entities in the canonical KG (domain='variant', biolink:SequenceVariant), all from the CIViC source. Schema is therefore first-class for variants — mods_kg_entity.biolink_category='biolink:SequenceVariant'. 8.5.1 schema work is done.
• CIViC connector is live (backend/connectors/civic_connector.py, 541 lines). Already shipped: 3,142 biolink:predicts_sensitivity_to, 1,651 biolink:predicts_resistance_to, 33 biolink:predicts_toxicity_for, 960 biolink:gene_associated_with_condition, 945 biolink:biomarker_for, 4,124 biolink:has_sequence_variant. 8.5.5 is done.
• CAID coverage on CIViC variants: 780 / 4,124 (19%) carry CAID:* CURIEs; 3,302 (80%) still on civic:civic_variant:*; 25 on CLINVAR:*; 17 on HGVS:*. The 80% un-normalized chunk is the remaining 8.5.3 polish.
• Maureen is already a patient node (MAPLE_PATIENT:maureen-1173a8db, biolink:IndividualOrganism) with 250 outbound edges: 5/48/48 sensitive/partial/resistant RGCC drugs (MAPLE:sensitive_to_drug family), 45 over_expresses + 14 under_expresses (genomics), 9+59+8 medication history, 6 phenotypes, 8 MAPLE:has_genetic_alteration_in (gene-level). Phase 12 V1 (patient-as-a-node) is therefore partially landed.
• Patient→variant gap: all 8 has_genetic_alteration_in edges point to gene entities (NCBIGene:324 APC, NCBIGene:673 BRAF, etc.) — the variant detail lives only in the edge metadata. Even when CAID:CA123643 (BRAF V600E) exists in the canonical KG, Maureen isn’t linked to it as a node. This is the lift Phase 8.5.2 was supposed to deliver and remains the open structural work for Maureen.
• OncoKB connector is coded (backend/connectors/oncokb_connector.py, 403 lines) but NOT ingested — zero oncokb rows in mods_kg_entity_source. Same for PharmGKB.
• Maureen variant inventory (run 2026-05-14): 19 variants across 8 genes from 3 source documents (Caris ×14, Guardant360 ×4, Invitae ×1). No RGCC variant rows (as expected — RGCC is drug-sensitivity, not variant calls). 100% gene symbols, 79% HGVS-p, 74% HGVS-c, 0% transcripts / hgnc_id / chromosomal coords.
• Translator/ClinGen spike result (run 2026-05-14): with HGNC-driven transcript inference + version-fallback, 10/14 eligible variants resolved to CAIDs (71.4%), passing the 8.5.3 ≥70% gate on the eligible denominator. 4 unique CAIDs across 10 row hits — including CAID:CA123643 (BRAF V600E, present in the KG) and one inherited variant NOT present in the KG (identifiers withheld; CIViC doesn’t curate it). Scripts at backend/scripts/maureen_variant_inventory.py and backend/scripts/translator_clingen_spike_v3.py. Results: runs/2026-05-14_phase8.5_spike/translator_clingen_spike_v3.json.

Net read: Phase 8.5 is roughly half-landed. What’s left: (a) OncoKB + PharmGKB ingest, (b) patient→variant resolver fix in mods_patient_kg_service.py::_resolve_variant_canonical + variant-upsert path so we can connect Maureen to CAIDs that the public KBs don’t carry, (c) CAID back-normalization for the 80% civic-internal CURIEs (defer), (d) 8.5.9 retrain — currently underway on Maureen-noded + CIViC + PrimeKG (no OncoKB yet).

---

1. Problem statement

What we have

PrimeKG and GP-KG operate at gene-level granularity. Variant-specific information exists in PrimeKG only as free text inside drug and disease description fields. Verified counts in docs/References/PrimeKG/:

• drug_features.csv: 6 mentions of “V600” (in vemurafenib, cobimetinib, encorafenib, dabrafenib descriptions)
• disease_features.csv: 4 mentions of “V600” (in BRAF-driven disease descriptions)
• nodes.csv: zero variant-typed nodes — none of PrimeKG’s 10 node types is variant or mutation
• edges.csv: zero variant-keyed edges — none of PrimeKG’s 30 relation types operates at variant granularity

What this costs us

The CompGCN+ConvE and ULTRA models we train see node IDs and edge types — not text. So variant signals from drug descriptions are invisible to the link-prediction model. Concretely, the graph cannot reason about:

1. Mechanism-coupled drug selection. Maureen’s inherited variant raises a mechanism-coupled drug question (a nuanced call). The graph would need to traverse Maureen → variant → gene → pathway → drug class. Without variant nodes, the inference path collapses at the gene level.

2. Combinatorial filtering. Maureen has KRAS / BRAF / MSI / MLH1 / MSH2 status from her Caris and RGCC reports, plus 73 expression genes and 224 drug sensitivities (112 drugs x 2 draws). Hand-coding a rule for every combination (“if BRAF wild-type AND KRAS wild-type AND MSS then EGFR inhibitors are eligible”) is brittle. Graph reasoning composes naturally.

3. Subtype-specific drug sensitivity. PrimeKG knows “vemurafenib treats melanoma” but not “vemurafenib treats BRAF V600E-positive cancers.” With BRAF_V600E as a graph entity, the model could surface vemurafenib for any V600E-positive tumor, including CRC subtypes.

4. Pharmacogenomic safety filtering. DPYD-deficient patients can have fatal toxicity to 5-FU and capecitabine. UGT1A1*28 homozygotes have severe irinotecan toxicity. Both are CRC chemotherapy concerns. Without variant-keyed contraindication edges, the graph ranks these drugs without regard to patient genotype — currently mitigated only by patient-side filtering, which is fragile.

Workarounds that exist (and what they recover)

• Text embedders (Phase 7.6/7.7) pick up V600E and similar mentions from drug descriptions. They can recover variant-aware ranking via post-hoc combination, but only as good as the description text — sparse for non-cancer variants and absent for most PGx.
• Patient-side filtering against mods_genomic_alteration can hard-filter or hard-promote at inference time. Real and useful, but ad hoc and doesn’t scale across patients or new evidence sources.
• RAG / LLM re-ranking can layer variant context on top of the model’s top candidates. Limited because the LLM doesn’t see graph structure.

These together recover meaningful practical value, but they are workarounds. Variant-as-graph-entity is the principled architecture.

Why now

• Phase 9 (Maureen personalization) becomes more powerful with variant nodes. Without them, every variant has to be hand-engineered into a scalar feature vector, losing all the public evidence linking variants to drugs.
• Phase 12 (patient-as-node) makes the same gene-level mistake. Its DYSREGULATED_GENE patient→gene edges can’t distinguish BRAF V600E from BRAF V600K, even though the drug response differs.
• The schema work (8.5.1, 8.5.2) is model-independent and can proceed in parallel with whatever PDR1/PDR2 training is happening.

Why not now

• Engineering cost is real — see § 4 cost estimate. 6-18 weeks depending on path.
• PrimeKG’s own authors didn’t include variants by design. We’re forking the philosophy as well as the data. Worth being deliberate about this.
• Phase 11 (PDR2/ULTRA) makes 8.5.9 retraining cheaper. If PDR2 is on track, we may want to schedule the retrain step after Phase 11 closes.

---

2. Closure criteria (aggregate)

1. Schema supports variant entity type and at least three new relation types covering predict-response, predict-toxicity, and variant-of-gene.
2. All of Maureen’s parsed variants from mods_genomic_alteration are present as graph nodes with edges to the appropriate gene nodes.
3. At least one public variant-evidence KB (OncoKB or CIViC for cancer; PharmGKB for PGx) is ingested and connected to the variant nodes.
4. A retrained or fine-tuned model on the variant-extended KG meets two regression gates:
   • (a) Phase 7.5 RGCC validation numbers do not degrade.
   • (b) At least one validation track shows ≥ 0.03 AUROC or ≥ 0.05 Spearman ρ improvement.
5. Documentation captures the identifier-normalization decisions, the merge methodology, and the architectural choice for retrain vs fine-tune.

---

3. Sub-phases

8.5.1 — Schema extension (low cost, immediate value) — DONE in canonical schema

The canonical schema (mods_kg_entity / mods_kg_entity_source / mods_kg_relation, migrations 071–078) supports variants natively. The original plan targeted the legacy schema’s entity_type='variant' on mods_kg_node; the canonical equivalent is domain='variant' + biolink_category='biolink:SequenceVariant', which already exists and is populated.

• Variant entity type — domain='variant', biolink_category='biolink:SequenceVariant'. 4,124 rows present.
• HGVS / CAID / etc. live in mods_kg_entity.metadata (JSONB) — schema-free; connectors populate at ingest time.
• New relation types: biolink:has_sequence_variant (=variant_of_gene), biolink:predicts_sensitivity_to (=predicts_response_to), biolink:predicts_resistance_to, biolink:predicts_toxicity_for, biolink:biomarker_for, biolink:gene_associated_with_condition. All present.
• Evidence and source attribution via mods_kg_relation.evidence JSONB + source_id FK. CIViC evidence levels (A/B/C/D/E) land in evidence JSONB.

8.5.2 — Internal variant ingestion (Maureen’s data into the graph) — PARTIAL (gene-level done, variant-level open)

• Patient-as-a-Node materialization service is live at backend/mods_patient_kg_service.py (materialize_patient_kg). Maureen has 250 outbound canonical relations including 8 MAPLE:has_genetic_alteration_in rows from mods_genomic_alteration.
• Variant-level edges still gene-level. Her 8 alteration rows resolve only to gene entities (NCBIGene:*) because _resolve_variant_canonical looks for {gene} {variant} name matches and her HGVS-p strings carry the p. prefix while CIViC names them without it. Fix planned: thread the v3 spike’s HGNC+ClinGen resolver into _resolve_variant_canonical, then upsert the variant entity into maple_patient source if no public-source variant matches.
• CAID resolution rate measured on Maureen’s variants: 10/14 eligible (71.4%) — passes the 8.5.3 ≥70% gate on the HGVS-c-equipped subset. Failure modes documented: 5 variants are HGVS-p-only (3 might be derivable with Mutalyzer), 2 are CNVs (need separate handling), 2 are novel indels not in ClinGen.
• Cache resolved CAIDs in a mods_variant_normalization table (deferred — current spike caches in-memory + JSON; durable cache is a polish item).
• Maureen’s variants are the only patient set today; multi-patient scope deferred until V2.

8.5.3 — Identifier normalization layer (the cross-source key) — PARTIAL (clients built, in-line use proven; back-normalization of CIViC variants pending)

• Normalization clients exist at backend/kg_normalize/:
  • node_normalizer_client.py — Translator Node Normalizer (gene/drug/disease CURIEs)
  • clingen_allele_registry_client.py — ClinGen Allele Registry (variant → CAID)
  • predicate_mapper.py — source-predicate → Biolink predicate
  • entity_resolver.py — orchestrates all three at ingest time
• Translator + ClinGen + HGNC pipeline validated end-to-end on Maureen’s 19 variants (backend/scripts/translator_clingen_spike_v3.py). Gene CURIE normalization: 8/8 (100%). Variant CAID resolution: 10/14 eligible (71.4%). Failure modes catalogued.
• Back-normalization of 3,302 civic-internal variant CURIEs to CAID — still open. Today CIViC variants land with their civic:civic_variant:NNN CURIE if Node Normalizer can’t resolve them through the chain. Worth a polish pass once OncoKB lands so cross-source dedup operates on the same CAID key.
• Track normalization failures per source. EntityResolver already emits per-call status; surface as a daily audit metric.

8.5.4 — Public KB connector — OncoKB (highest priority for Maureen) — CODE READY, NOT INGESTED

• Connector built at backend/connectors/oncokb_connector.py (403 lines). Supports two modes: JSON file (default at ./data/kg/oncokb/actionable_variants.json) and live API (when ONCOKB_API_TOKEN env var is set).
• License posture noted on the manifest: “Commercial (free academic tier)” + biolink_compliant=False. Per-composition human-reviewer call on inclusion.
• Maps OncoKB Level 1/2/3A/3B/4 → biolink:predicts_sensitivity_to; R1/R2 → biolink:predicts_resistance_to. variant_of_gene + variant→drug + variant→disease (biomarker_for) edges per row.
• Run the ingest. Blocked on: needs ONCOKB_API_TOKEN (academic registration at https://www.oncokb.org/account/register) OR a manually-placed actionable_variants.json. Run via python backend/scripts/ingest_kg_connector.py --connector oncokb.
• Closure gate: at least one Maureen-relevant variant (BRAF V600E confirmed in CIViC already; the inherited variant only resolvable in OncoKB or further-curated source) gets an OncoKB-sourced edge.

8.5.5 — Public KB connector — CIViC — DONE

• Connector at backend/connectors/civic_connector.py (541 lines). Reads CIViC’s monthly TSV releases (variants + evidence + clinical assertions), produces variant / gene / drug / disease entities + evidence-leveled relations.
• Ingested. 4,124 variants, 4,138 entities from civic source. 3,142 sensitivity / 1,651 resistance / 33 toxicity edges. Variant-of-gene relations carry CIViC evidence level (evidence.civic_level).
• OncoKB/CIViC overlap-resolution policy (prefer OncoKB level for ranking; preserve CIViC as corroborating flag) — designed-but-not-implemented; will need explicit cross-source xref query when OncoKB lands.

8.5.6 — Public KB connector — PharmGKB (for chemo safety) — CODE READY, NOT INGESTED

• Connector at backend/connectors/pharmgkb_connector.py (357 lines). Ingests CPIC-leveled variant→drug-response rows. Star-allele / haplotype handling per the connector’s _row_to_relations.
• Run the ingest. Same script: python backend/scripts/ingest_kg_connector.py --connector pharmgkb_variants.
• Closure gate: DPYD variants are linked to capecitabine and 5-fluorouracil with CPIC level A; UGT1A1*28 is linked to irinotecan. Relevant only if Maureen ever has DPYD / UGT1A1 testing — neither is in her current mods_genomic_alteration rows; check Caris reports for whether PGx was ordered.

8.5.7 — Public KB connector — ClinVar (optional, requires filtering)

• Massive coverage but variable quality. Defer until 8.5.4–8.5.6 prove the architecture; then add ClinVar filtered to “Pathogenic” + “Likely pathogenic” with at least 2 stars.
• Ingest as has_significance edges to a controlled vocabulary node set.

8.5.8 — KG merge strategy and validation

• Merge happens via shared identifier space, not via graph operations. Genes and drugs already in PrimeKG get their NCBI / DrugBank IDs reused; new variants get added with CAIDs; new edges connect them.
• Audit cross-KB conflicts. When OncoKB says variant X predicts response to drug Y but CIViC says no evidence, do not collapse; preserve both as separate edges with provenance.
• Run a sanity-check query before retraining: pick 10 well-known variant-drug pairs (BRAF V600E ↔ vemurafenib, DPYD c.1905+1G>A ↔ capecitabine, BRCA2 mutations ↔ olaparib, etc.). Verify each produces an edge with the expected provenance.
• Document collision rates: how many variant nodes did we end up with? How many had ≥ 1 evidence edge from at least one source? How many were Maureen-relevant?

8.5.9 — Retrain or fine-tune the model — TRAINING IN PROGRESS (2026-05-14)

• Underway. Maureen-noded retrain on CIViC + PrimeKG (OncoKB not yet ingested at training time). Architecture and config TBD-from-train-log. This validates the chain end-to-end without OncoKB; OncoKB-augmented retrain is a follow-up run.
• Decision parallel to Phase 12.3. Two options:
  • Option A (full retrain): train PDR1 / PDR2 from scratch on the variant-extended PrimeKG. Most rigorous; the relation encoder learns the new relation types from the start.
  • Option B (fine-tune): start from the existing PrimeKG checkpoint, add variant nodes + edges, fine-tune for ~30 epochs.
• PDR2 / ULTRA-specific note: ULTRA’s relation-from-topology design absorbs new relation types without retraining the foundation. If Phase 11 has closed by the time we get here, Option B is much cheaper on PDR2 than on PDR1. This is a strong reason to schedule 8.5 after Phase 11 closes if PDR2 is on track — but the schema and ingestion work (8.5.1–8.5.7) is model-independent and can proceed in parallel.
• Note (added 2026-05-14): The in-progress training uses Maureen’s gene-level alteration edges (MAPLE:has_genetic_alteration_in → gene), not variant-level. Once 8.5.2 fix lands and her edges include biolink:has_variant → variant CAIDs, the next retrain will see her connected directly to BRAF V600E (CA123643) and other variants rather than only to the BRAF gene with HGVS in the edge metadata. That’s the actual signal lift Phase 8.5 was designed to deliver.

8.5.10 — Validation

• Regression gate: re-run Phase 7.5 RGCC validation tiers on the variant-extended checkpoint. Numbers must not degrade. If they do, investigate before proceeding.
• Lift gate: at least one validation metric improves measurably:
  • Tier 1 ρ (continuous correlation between model score and RGCC % cell death) improves by ≥ 0.05, OR
  • Tier 2 AUROC (high-sensitivity vs non-sensitive RGCC drugs) improves by ≥ 0.03
• Maureen-specific anchor test: for each of her clinically actionable variants (ATM, KRAS / BRAF if present, MSI status, MLH1/MSH2, DPYD if tested, UGT1A1 if tested), verify the model now ranks the corresponding evidence-supported drugs in the top decile of CRC candidates. Pre-register the expected rankings before running.
• Cross-validation on held-out variants: hold out 5% of OncoKB variant-drug edges; verify the model can predict them from the rest of the graph. This is the link-prediction analog of leave-one-out.

8.5.11 — Documentation and publishability

• Document the schema extension, the connector set, the normalization choices, and the merge methodology in a standalone writeup following the pdr_phase0_gpkg_writeup.md template (Purpose / M&M / Procedure / Results / Discussion).
• Note: a variant-extended PrimeKG is itself publishable — the PrimeKG authors did not include variants by design, so this is a real contribution rather than a fork.

---

4. KG merging in practice — context for the planning session

The Phase 8.5 plan above understates how hard KG merging is. Adding rows to tables is the trivial 20%. The hard 80% is identifier alignment, schema harmonization, provenance tracking, and update lifecycle. This section captures the field’s state of the art so we can choose the right tooling.

4.1 The four hard problems

(1) Identifier alignment. Every database uses different IDs for the same entities. PrimeKG uses NCBI gene IDs (9796 = PHYHIP), OncoKB uses HGNC symbols (BRAF), CIViC uses Entrez IDs, ClinVar uses gene symbols + RefSeq. For drugs it’s worse: DrugBank, ChEMBL, PubChem CID, RxNorm, NCIt, KEGG, ATC — and the same drug routinely has different IDs in different sources. Variants are the worst case: HGVS notation has multiple equivalent forms, dbSNP IDs change between builds, ClinGen’s CAID is canonical but coverage is incomplete.

(2) Schema harmonization. PrimeKG is a binary KG: every fact is a (head, relation, tail) triple. OncoKB has hyperedges with metadata: (variant, drug, evidence_level, indication_context, citation, level_of_evidence). To merge, you either (a) flatten into multiple triples and lose information, or (b) extend the schema with edge attributes. Both have downsides.

(3) Provenance and conflict resolution. When two sources disagree (OncoKB says Level 2 evidence, CIViC says no evidence), which wins? Best practice: preserve both, mark each with source, and let downstream consumers decide. But this means every node and edge needs a provenance attribute, which most KGs don’t have natively.

(4) Update lifecycle. OncoKB updates monthly. CIViC has continuous community curation. PrimeKG is a single-version dataset release. Synchronizing updates across heterogeneous cadences is a real engineering problem — usually solved by re-deriving the merged KG on a schedule rather than incremental updates.

4.2 The Biolink + NCATS Translator ecosystem (the canonical answer in our space)

This is the closest thing to a solved problem for biomedical KG integration:

• Biolink Model — a controlled hierarchy of node and edge types, with explicit semantics. e.g., biolink:Gene, biolink:Drug, biolink:Variant, biolink:treats, biolink:contraindicated_for. Every concept maps to a Biolink class.
• TRAPI (Translator Reasoner API) — a JSON-RPC standard for querying KGs. Each Knowledge Provider exposes their KB through TRAPI, regardless of internal storage.
• SRI Node Normalizer — a hosted REST service that maps any biomedical identifier (NCBI Gene, HGNC, DrugBank, MONDO, UMLS, etc.) to a canonical CURIE plus a Biolink class. This is the answer to identifier alignment for ~95% of biomedical entities.
• NCATS Translator itself — operates 13+ Knowledge Providers (RTX-KG2, ROBOKOP, Multi-Omics Provider, etc.) behind a unified TRAPI layer. We already have a connector at backend/connectors/translator_connector.py.

Practical implication: instead of building four bespoke connectors for OncoKB / CIViC / PharmGKB / ClinVar, much of the variant-evidence content is already accessible through Translator’s MolePro and BTE Knowledge Providers. We’d query Translator with normalized variant CURIEs and pull back evidence edges already harmonized to Biolink. Where coverage gaps exist (OncoKB specifically isn’t in Translator due to licensing), we build direct connectors.

4.3 Pre-integrated biomedical KGs (fork rather than build)

KG	Sources merged	License	Variants?
RTX-KG2	~70 sources via Biolink (UCSF/Translator)	Open	Partial — via ClinVar
SPOKE	30+ sources, used clinically (UCSF)	Restricted (academic)	Limited
ROBOKOP	~40 sources via Biolink	Open	Yes — multiple variant connectors
Hetionet	Older, smaller, foundational	Open	No
Monarch KG	Phenotype-centric integration	Open	Yes — extensive variant coverage

ROBOKOP and Monarch KG are the most promising starting points if we want to skip the per-source connector work. The trade-off is loss of control: we’d be downstream of someone else’s integration decisions.

4.4 Identifier mapping services (the “use don’t build” tier)

• SRI Node Normalizer (https://nodenorm.transltr.io) — generic biomedical entity normalizer
• MyGene.info / MyVariant.info / MyChem.info / MyDisease.info — BioThings APIs aggregating cross-references
• HGNC REST API — gene symbol authority
• UMLS Metathesaurus — broadest cross-vocabulary mapping but requires UMLS license
• ClinGen Allele Registry — canonical variant IDs (CAID)

4.5 Cost estimate

Honest sizing per sub-phase, with merging difficulty priced in:

Sub-phase	Effort	Why
8.5.1 schema extension	~3-5 days	Migrations, model classes, validation. Self-contained.
8.5.2 Maureen ingestion	~3-5 days	Reuses existing parsers; mostly ETL plumbing.
8.5.3 normalization layer	~1-2 weeks	Wrapping Translator Node Normalizer + ClinGen Allele Registry. Caching layer. Failure handling.
8.5.4 OncoKB connector	~2-3 weeks	Direct connector — OncoKB API + auth + normalization + ingestion. Includes back-and-forth on edge cases.
8.5.5 CIViC connector	~2 weeks	Open API, similar pattern but slightly different schema.
8.5.6 PharmGKB connector	~2-3 weeks	More complex schema (haplotypes, star alleles, diplotypes, CPIC guidelines). The hardest of the three.
8.5.7 ClinVar (deferred)	~3-4 weeks if we do it	Volume + quality filtering.
8.5.8 merge validation	~1 week	Audit queries, conflict resolution, sanity checks.
8.5.9 retrain/fine-tune	~1-2 weeks	Compute-bound. PDR2 fine-tune is cheaper than PDR1 retrain.
8.5.10 validation suite	~1 week	Re-run Phase 7.5 + variant-specific anchors.
8.5.11 writeup	~3-5 days	Following the writeup template.

Total: 12-18 weeks of focused work on the per-source-connector path. 6-10 weeks if we leverage Translator / ROBOKOP rather than building bespoke connectors.

---

5. Open questions for the planning session

Status as of 2026-05-14 (post-audit). RESOLVED items kept for the audit trail.

1. Build vs leverage existing integration. ✅ RESOLVED — hybrid landed: Translator Node Normalizer + ClinGen Allele Registry power the resolver chain in kg_normalize/; bespoke connectors built for CIViC (live), OncoKB (ready), PharmGKB (ready). Spike at backend/scripts/translator_clingen_spike_v3.py validates the leverage path resolves 71% of Maureen’s eligible variants without per-source curation.

2. PDR1 vs PDR2 as the retrain target. ✅ RESOLVED for this round — current training (in progress 2026-05-14) is on PDR1-style stack with Maureen-noded + CIViC + PrimeKG. PDR2 reproduction (Phase 11) still has open work; deferred to a follow-up retrain.

3. ROBOKOP / Monarch as a starting point. ❌ NOT NEEDED — leveraging Translator + ClinGen + bespoke OncoKB+PharmGKB+CIViC delivered Phase 8.5 schema and one fully-loaded source. Fork-ROBOKOP path effectively bypassed.

4. Edge-attribute design. ✅ RESOLVED — connectors emit single Biolink predicate per direction (predicts_sensitivity_to vs predicts_resistance_to) with evidence level on mods_kg_relation.evidence JSONB. Option (a) of the original question.

5. Patient-as-node interaction. ✅ RESOLVED — Phase 12 V1 landed alongside 8.5 work. Maureen is MAPLE_PATIENT:maureen-1173a8db; outbound edges use mixed MAPLE:* and biolink:* predicates. Open gap: her has_genetic_alteration_in edges target gene entities, not variants. That’s the 8.5.2 remaining work.

6. Validation ground truth for Maureen. ⚠️ DEFERRED — the in-progress training did NOT pre-hold-out RGCC drugs. The model can see all 224 sensitivities as training edges (MAPLE:sensitive_to_drug / _partially_sensitive_to_drug / _resistant_to_drug). For clean lift measurement against the variant-extended retrain, a future training run should hold out ≥5% of RGCC high-sensitivity drugs stratified by drug class. Not a blocker for the current run — but tag the result accordingly.

7. Licensing audit. PARTIAL — OncoKB connector documents the “Commercial (free academic tier)” posture on its manifest; per-composition reviewer call is the policy. Full audit (CIViC ✓ open, ClinVar ✓ public domain, PharmGKB ⚠ attribution, OncoKB ⚠ academic-only, COSMIC ✗ restrictive) wants a one-page summary in KG_CATALOG.md — TODO.

8. Caching and update cadence. OPEN — the connectors are one-shot file-based today (actionable_variants.json for OncoKB, monthly TSV for CIViC). Re-ingest is manual. Worker-task-scheduled re-pull is a polish item; not blocking.

9. Variant aggregation. EMPIRICAL RESULT — same variant from different reports collapses to the same CAID once resolved (BRAF V600E ×3 rows in Maureen’s data → CA123643; the inherited variant ×4 rows → a single CAID). De-dup happens naturally at the CAID step. But: 80% of CIViC variants are still on civic:civic_variant:* CURIEs because Node Normalizer didn’t resolve them; that’s why CIViC-loaded variants haven’t fully merged with the 780 CAID-keyed ones. Back-normalization pass needed.

10. Maureen-specific scope. ✅ RESOLVED — 19 variants total is small enough to ingest everything. No need to triage to an “actionable subset.” All her variants from all reports go in.

---

6. Suggested next steps for the planning session

1. Resolve the build-vs-leverage question (open question #1). This is the highest-leverage decision because it gates the per-sub-phase costs. Spend the first session on this.
2. Inventory Maureen’s variants from mods_genomic_alteration. Concrete count of what we have to ingest, broken down by source (Caris, Invitae, Guardant360, RGCC). Drives sizing of 8.5.2.
3. Spike on Translator Node Normalizer and ClinGen Allele Registry. Run both APIs against 10-20 of Maureen’s variants. Document failure rates. This validates the normalization layer (8.5.3) before committing to it.
4. Draft the schema migration. A concrete migration is the easiest way to surface schema design tensions. Write migration_NNN_variant_kg, review, iterate.
5. Finalize the architectural decision for retrain (Option A vs B). This depends on PDR2 status — coordinate with Phase 11 timeline.
6. Convert this document into a phased execution plan. Each sub-phase (8.5.1 through 8.5.11) gets a target date, owner, and concrete deliverable. Track progress in PDR_PIPELINE_PLAN.md.

---

7. Cross-references

• PDR_PIPELINE_PLAN.md — master plan; Phase 8.5 stub points here.
• pdr_phase0_gpkg_writeup.md — writeup template; used at 8.5.11.
• backend/connectors/translator_connector.py — existing Translator integration to leverage.
• mods_genomic_alteration table — Maureen’s parsed variants, populated by genomic report parsers.
• an internal note on knowledge-graph strategy — dual-KG strategy (GP-KG vs PrimeKG); variant extension affects the production graph (PrimeKG).