@inflexa-ai/harness 0.1.1

package/dist/tools/lib/identifier-resolver.js

@@ -0,0 +1,333 @@
+/**
+ * Identifier resolver — combines HGNC, UniProt, Ensembl, and ChEMBL gene-name
+ * fields into a single canonical entity payload with synonyms.
+ *
+ * Used by Phase 0 of the target-assessment workflow to resolve a user-
+ * supplied target string (gene symbol, alias, UniProt accession, Ensembl
+ * id, ChEMBL target id) to a canonical entity that downstream collectors
+ * can key off.
+ *
+ * Resolution order:
+ *   1. If the input matches a known id pattern (ENSG, UniProt 6-char,
+ *      CHEMBL\d+), use that as the seed.
+ *   2. Otherwise treat as a gene symbol and resolve via HGNC, then enrich
+ *      with UniProt, Ensembl, and ChEMBL.
+ *
+ * This is the only step in the workflow allowed to throw — a hard
+ * resolution failure aborts the assessment with `error.kind:
+ * "target-unresolved"` (per design §6).
+ */
+import { z } from "zod";
+import { apiFetchValidated } from "./api-utils.js";
+import { resolveSymbolToEnsemblId } from "./ensembl-client.js";
+import { searchTargets as searchChemblTargets } from "./chembl-client.js";
+import { normalizeProteinFamily } from "./protein-family-normalize.js";
+const HGNC_BASE = "https://rest.genenames.org/fetch";
+const UNIPROT_BASE = "https://rest.uniprot.org/uniprotkb/search";
+const HGNC_HEADERS = { Accept: "application/json" };
+const UNIPROT_HEADERS = { Accept: "application/json" };
+const ENSG_RE = /^ENSG\d{11}$/;
+const UNIPROT_RE = /^[A-Z][0-9][A-Z0-9]{3}[0-9](-\d+)?$/;
+const CHEMBL_RE = /^CHEMBL\d+$/;
+const HGNC_RE = /^HGNC:\d+$/;
+// HGNC search payload, validated at the fetch boundary. Every field is optional
+// because the API omits absent values; each read below is optional-chained /
+// defaulted, so a missing field degrades gracefully rather than throwing.
+const HgncResponseSchema = z.object({
+    response: z
+        .object({
+        docs: z
+            .array(z.object({
+            symbol: z.string().optional(),
+            name: z.string().optional(),
+            hgnc_id: z.string().optional(),
+            ensembl_gene_id: z.string().optional(),
+            uniprot_ids: z.array(z.string()).optional(),
+            entrez_id: z.string().optional(),
+            alias_symbol: z.array(z.string()).optional(),
+            prev_symbol: z.array(z.string()).optional(),
+        }))
+            .optional(),
+    })
+        .optional(),
+});
+// UniProt search payload, validated at the fetch boundary. Every field is
+// optional because the API omits absent values.
+const UniprotResponseSchema = z.object({
+    results: z
+        .array(z.object({
+        primaryAccession: z.string().optional(),
+        proteinDescription: z
+            .object({
+            recommendedName: z.object({ fullName: z.object({ value: z.string().optional() }).optional() }).optional(),
+            alternativeNames: z.array(z.object({ fullName: z.object({ value: z.string().optional() }).optional() })).optional(),
+        })
+            .optional(),
+        genes: z
+            .array(z.object({
+            geneName: z.object({ value: z.string().optional() }).optional(),
+            synonyms: z.array(z.object({ value: z.string().optional() })).optional(),
+        }))
+            .optional(),
+        proteinFamily: z.string().optional(),
+        extraAttributes: z.object({ uniParcId: z.string().optional() }).optional(),
+        keywords: z.array(z.object({ name: z.string().optional() })).optional(),
+    }))
+        .optional(),
+});
+async function fetchHgncBy(field, value) {
+    const url = `${HGNC_BASE}/${field}/${encodeURIComponent(value)}`;
+    const res = await apiFetchValidated(url, HgncResponseSchema, { headers: HGNC_HEADERS });
+    if (res.isErr())
+        return null;
+    const docs = res.value.response?.docs ?? [];
+    return docs[0] ?? null;
+}
+async function fetchUniprotByAccession(accession) {
+    const url = `${UNIPROT_BASE}?query=accession:${encodeURIComponent(accession)}&format=json&size=1`;
+    const res = await apiFetchValidated(url, UniprotResponseSchema, { headers: UNIPROT_HEADERS });
+    if (res.isErr())
+        return null;
+    return res.value.results?.[0] ?? null;
+}
+async function fetchUniprotBySymbol(symbol) {
+    const query = `gene_exact:${symbol} AND organism_id:9606 AND reviewed:true`;
+    const url = `${UNIPROT_BASE}?query=${encodeURIComponent(query)}&format=json&size=1`;
+    const res = await apiFetchValidated(url, UniprotResponseSchema, { headers: UNIPROT_HEADERS });
+    if (res.isErr())
+        return null;
+    return res.value.results?.[0] ?? null;
+}
+function extractProteinFamily(uniprotKeywords) {
+    if (!uniprotKeywords)
+        return null;
+    for (const kw of uniprotKeywords) {
+        const norm = normalizeProteinFamily(kw.name ?? null);
+        if (!norm)
+            continue;
+        if (norm.includes("kinase") ||
+            norm.includes("g protein-coupled receptor") ||
+            norm.includes("ion channel") ||
+            norm.includes("protease") ||
+            norm.includes("nuclear receptor") ||
+            norm.includes("transcription factor") ||
+            norm.includes("phosphatase") ||
+            norm.includes("transporter") ||
+            norm.includes("transferase")) {
+            return kw.name ?? null; // preserve original UniProt text on the entity for traceability
+        }
+    }
+    return uniprotKeywords[0]?.name ?? null;
+}
+/**
+ * Resolve a free-form target identifier to a canonical entity.
+ *
+ * @throws when the input cannot be mapped to any human gene/protein.
+ */
+export async function resolveTarget(input) {
+    const trimmed = input.trim();
+    if (!trimmed)
+        throw new Error("Target identifier is required");
+    let seedSymbol = null;
+    let seedHgncId = null;
+    let seedEnsemblId = null;
+    let seedUniprot = null;
+    let seedChembl = null;
+    if (ENSG_RE.test(trimmed)) {
+        seedEnsemblId = trimmed;
+    }
+    else if (HGNC_RE.test(trimmed)) {
+        seedHgncId = trimmed;
+    }
+    else if (UNIPROT_RE.test(trimmed)) {
+        seedUniprot = trimmed;
+    }
+    else if (CHEMBL_RE.test(trimmed)) {
+        seedChembl = trimmed;
+    }
+    else {
+        seedSymbol = trimmed.toUpperCase();
+    }
+    // Step 1: HGNC anchor.
+    // `hgncDoc` holds a single doc from the HGNC search payload (all fields are
+    // optional on `HgncDoc`); every read below is optional-chained / defaulted, so
+    // a missing or renamed field degrades to null rather than throwing — the
+    // resolver never relies on any single HGNC field being present.
+    let hgncDoc = null;
+    if (seedSymbol) {
+        hgncDoc = await fetchHgncBy("symbol", seedSymbol);
+        if (!hgncDoc) {
+            hgncDoc = await fetchHgncBy("alias_symbol", seedSymbol);
+        }
+        if (!hgncDoc) {
+            hgncDoc = await fetchHgncBy("prev_symbol", seedSymbol);
+        }
+    }
+    else if (seedHgncId) {
+        hgncDoc = await fetchHgncBy("hgnc_id", seedHgncId.replace(/^HGNC:/, ""));
+    }
+    else if (seedEnsemblId) {
+        hgncDoc = await fetchHgncBy("ensembl_gene_id", seedEnsemblId);
+    }
+    else if (seedUniprot) {
+        hgncDoc = await fetchHgncBy("uniprot_ids", seedUniprot);
+    }
+    // Step 2: UniProt
+    let uniprotDoc = null;
+    const uniprotFromHgnc = hgncDoc?.uniprot_ids?.[0] ?? null;
+    const uniprotSeed = seedUniprot ?? uniprotFromHgnc ?? null;
+    if (uniprotSeed) {
+        uniprotDoc = await fetchUniprotByAccession(uniprotSeed);
+    }
+    else if (hgncDoc?.symbol) {
+        uniprotDoc = await fetchUniprotBySymbol(hgncDoc.symbol);
+    }
+    else if (seedSymbol) {
+        uniprotDoc = await fetchUniprotBySymbol(seedSymbol);
+    }
+    // Backfill HGNC if it was empty but UniProt produced a primary gene name.
+    const uniprotPrimaryGene = uniprotDoc?.genes?.[0]?.geneName?.value ?? null;
+    if (!hgncDoc && uniprotPrimaryGene) {
+        hgncDoc = await fetchHgncBy("symbol", uniprotPrimaryGene);
+    }
+    // Step 3: Ensembl
+    let ensemblId = seedEnsemblId ?? hgncDoc?.ensembl_gene_id ?? null;
+    const symbolForEnsembl = hgncDoc?.symbol ?? uniprotPrimaryGene ?? seedSymbol;
+    if (!ensemblId && symbolForEnsembl) {
+        ensemblId = await resolveSymbolToEnsemblId(symbolForEnsembl);
+    }
+    // Step 4: ChEMBL
+    let chemblId = seedChembl;
+    if (!chemblId && symbolForEnsembl) {
+        const targets = await searchChemblTargets(symbolForEnsembl, 5).catch(() => []);
+        const human = targets.find((t) => t.organism === "Homo sapiens");
+        chemblId = (human ?? targets[0])?.targetChemblId ?? null;
+    }
+    // Final canonical anchor — HGNC preferred, then Ensembl.
+    const hgncId = hgncDoc?.hgnc_id ?? null;
+    const finalSymbol = hgncDoc?.symbol ?? uniprotPrimaryGene ?? seedSymbol;
+    if (!finalSymbol) {
+        throw new Error(`Could not resolve target "${trimmed}" to a canonical human gene/protein identity`);
+    }
+    const finalName = uniprotDoc?.proteinDescription?.recommendedName?.fullName?.value ?? hgncDoc?.name ?? finalSymbol;
+    // The canonicalOntology field is the entity-resolution anchor for
+    // downstream collectors — falling back to a ChEMBL id (or worse, the
+    // raw input string) while labelling it "ensembl" would silently route
+    // every cross-reference through the wrong ontology. Require at least
+    // one of HGNC / Ensembl to anchor the row.
+    const canonicalId = hgncId ?? ensemblId;
+    const canonicalOntology = hgncId ? "hgnc" : "ensembl";
+    if (!canonicalId) {
+        throw new Error(`Resolved "${trimmed}" to symbol "${finalSymbol}" but could not anchor to HGNC or Ensembl — ChEMBL/UniProt-only matches cannot serve as the canonical entity id`);
+    }
+    const synonyms = new Set();
+    for (const s of hgncDoc?.alias_symbol ?? [])
+        synonyms.add(String(s));
+    for (const s of hgncDoc?.prev_symbol ?? [])
+        synonyms.add(String(s));
+    for (const g of uniprotDoc?.genes ?? []) {
+        for (const syn of g.synonyms ?? []) {
+            if (syn.value)
+                synonyms.add(syn.value);
+        }
+    }
+    synonyms.delete(finalSymbol);
+    const proteinSynonyms = new Set();
+    for (const alt of uniprotDoc?.proteinDescription?.alternativeNames ?? []) {
+        if (alt.fullName?.value)
+            proteinSynonyms.add(alt.fullName.value);
+    }
+    return {
+        canonicalId,
+        canonicalOntology,
+        geneSymbol: finalSymbol,
+        approvedName: finalName,
+        ids: {
+            hgnc: hgncId,
+            ensembl: ensemblId,
+            uniprot: uniprotDoc?.primaryAccession ?? uniprotSeed,
+            chembl: chemblId,
+            entrez: hgncDoc?.entrez_id ?? null,
+        },
+        synonyms: [...synonyms].filter(Boolean).sort(),
+        proteinSynonyms: [...proteinSynonyms].filter(Boolean).sort(),
+        proteinFamily: extractProteinFamily(uniprotDoc?.keywords) ?? null,
+        resolutionCoverage: {
+            hgnc: !!hgncDoc,
+            uniprot: !!uniprotDoc,
+            ensembl: !!ensemblId,
+            chembl: !!chemblId,
+        },
+    };
+}
+/**
+ * Resolve a single gene-symbol query for the autocomplete UI by fanning
+ * out HGNC + UniProt + Ensembl in parallel and merging into one canonical
+ * candidate. Per `target-assessment/spec.md` "Autocomplete returns
+ * canonical identifiers" — three identifiers populated on one row, not
+ * three separate rows.
+ *
+ * Returns `null` when none of the upstream sources find a match. Throws
+ * never — failures of individual sources degrade to `null` for that field.
+ *
+ * Symbol handling mirrors `resolveTarget` so both entry points behave the
+ * same on edge cases:
+ *   - The query is upper-cased before hitting upstream APIs (HGNC's
+ *     `symbol` index is case-sensitive; `tp53` would miss).
+ *   - HGNC is queried with a `symbol` → `alias_symbol` → `prev_symbol`
+ *     fallback ladder so deprecated symbols still resolve.
+ */
+export async function searchTargetByName(symbol) {
+    const trimmed = symbol.trim();
+    if (!trimmed)
+        return null;
+    const upper = trimmed.toUpperCase();
+    async function lookupHgnc() {
+        return ((await fetchHgncBy("symbol", upper).catch(() => null)) ??
+            (await fetchHgncBy("alias_symbol", upper).catch(() => null)) ??
+            (await fetchHgncBy("prev_symbol", upper).catch(() => null)));
+    }
+    const [hgncDoc, uniprotDoc, ensemblId] = await Promise.all([
+        lookupHgnc(),
+        fetchUniprotBySymbol(upper).catch(() => null),
+        resolveSymbolToEnsemblId(upper).catch(() => null),
+    ]);
+    if (!hgncDoc && !uniprotDoc && !ensemblId)
+        return null;
+    const symbolFromHgnc = hgncDoc?.symbol;
+    const uniprotGene = uniprotDoc?.genes?.[0]?.geneName?.value;
+    const resolvedSymbol = symbolFromHgnc ?? uniprotGene ?? upper;
+    // Case-insensitive synonym dedup — UniProt and HGNC normalize differently
+    // (e.g., HGNC "ERBB" vs. UniProt "Erbb"), and we don't want both shapes
+    // landing in the synonyms list.
+    const seenLower = new Set([resolvedSymbol.toLowerCase()]);
+    const synonyms = [];
+    const addSynonym = (raw) => {
+        if (!raw)
+            return;
+        const key = raw.toLowerCase();
+        if (seenLower.has(key))
+            return;
+        seenLower.add(key);
+        synonyms.push(raw);
+    };
+    for (const s of hgncDoc?.alias_symbol ?? [])
+        addSynonym(s);
+    for (const s of hgncDoc?.prev_symbol ?? [])
+        addSynonym(s);
+    // Pull synonyms from every UniProt gene record — read-through transcripts
+    // and multi-gene entries surface aliases beyond the primary record.
+    for (const g of uniprotDoc?.genes ?? []) {
+        for (const s of g.synonyms ?? [])
+            addSynonym(s.value);
+    }
+    const hgncEnsembl = hgncDoc?.ensembl_gene_id;
+    return {
+        symbol: resolvedSymbol,
+        displayName: hgncDoc?.name ?? uniprotDoc?.proteinDescription?.recommendedName?.fullName?.value ?? null,
+        hgncId: hgncDoc?.hgnc_id ?? null,
+        ensemblId: ensemblId ?? hgncEnsembl ?? null,
+        uniprotId: uniprotDoc?.primaryAccession ?? null,
+        synonyms: synonyms.sort((a, b) => a.localeCompare(b)),
+    };
+}

package/dist/tools/lib/impc-client.d.ts

@@ -0,0 +1,44 @@
+/**
+ * Pure async client functions for the IMPC (International Mouse Phenotyping
+ * Consortium) Solr API.
+ *
+ * Used by §3.10.1 (Knockout phenotype card).
+ */
+export interface MpTerm {
+    id: string;
+    term: string;
+    bestPValue: number | null;
+}
+export interface PhenotypeProfile {
+    mpTerms: MpTerm[];
+    organSystems: string[];
+    sexDimorphic: boolean;
+    phenotypeCount: number;
+}
+export interface ViabilityCall {
+    zygosity: string;
+    parameterStableId: string;
+    mpTerm: {
+        id: string;
+        name: string;
+    } | null;
+}
+export type ViabilityCategory = "lethal_pre_weaning" | "subviable" | "viable" | null;
+export interface KoPhenotypeProfile {
+    geneSymbol: string;
+    mouseMarkerSymbol: string | null;
+    mgiAccessionId: string | null;
+    viability: ViabilityCategory;
+    viabilityCalls: ViabilityCall[];
+    mpTerms: MpTerm[];
+    organSystems: string[];
+    sexDimorphic: boolean;
+    phenotypeCount: number;
+    phenotypeDocsTotal: number;
+    phenotypesTruncated: boolean;
+}
+export declare function parsePhenotypeResponse(raw: unknown): PhenotypeProfile;
+export declare function buildViabilityCalls(docsB: unknown, docsC: unknown): ViabilityCall[];
+export declare function derivedViability(calls: ViabilityCall[]): ViabilityCategory;
+/** Full KO phenotype profile for a human gene. */
+export declare function getKoPhenotypeProfile(geneSymbol: string): Promise<KoPhenotypeProfile>;

package/dist/tools/lib/impc-client.js

@@ -0,0 +1,239 @@
+/**
+ * Pure async client functions for the IMPC (International Mouse Phenotyping
+ * Consortium) Solr API.
+ *
+ * Used by §3.10.1 (Knockout phenotype card).
+ */
+import { z } from "zod";
+import { apiFetchValidated, describeApiError, isUnexpectedApiError } from "./api-utils.js";
+const IMPC_BASE = "https://www.ebi.ac.uk/mi/impc/solr";
+const PHENOTYPE_ROW_CAP = 500;
+const VIABILITY_PROCEDURE = "Viability Primary Screen";
+const ORGAN_SYSTEM_MAP = {
+    "cardiovascular system phenotype": "cardiovascular",
+    "digestive/alimentary phenotype": "gastrointestinal",
+    "endocrine/exocrine gland phenotype": "endocrine",
+    "hematopoietic system phenotype": "hematologic",
+    "hearing/vestibular/ear phenotype": "auditory",
+    "homeostasis/metabolism phenotype": "metabolic",
+    "immune system phenotype": "immune",
+    "integument phenotype": "skin",
+    "liver/biliary system phenotype": "hepatic",
+    "muscle phenotype": "musculoskeletal",
+    "nervous system phenotype": "cns",
+    "renal/urinary system phenotype": "renal",
+    "reproductive system phenotype": "reproductive",
+    "respiratory system phenotype": "respiratory",
+    "skeleton phenotype": "skeleton",
+    "vision/eye phenotype": "vision",
+    "adipose tissue phenotype": "metabolic",
+    "behavior/neurological phenotype": "cns",
+    "growth/size/body region phenotype": "growth",
+    "mortality/aging": "mortality",
+    "craniofacial phenotype": "craniofacial",
+    "limbs/digits/tail phenotype": "musculoskeletal",
+    "pigmentation phenotype": "skin",
+    "embryo phenotype": "growth",
+};
+// A single IMPC Solr document — fields vary by core; all optional. `top_level_mp_term_name`
+// and `sex` are `z.unknown()` because the code reads them defensively (`Array.isArray`,
+// `typeof === "string"`) rather than trusting a wire type.
+const ImpcSolrDocSchema = z.object({
+    mp_term_id: z.string().optional(),
+    mp_term_name: z.string().optional(),
+    p_value: z.number().optional(),
+    top_level_mp_term_name: z.unknown().optional(),
+    sex: z.unknown().optional(),
+    parameter_stable_id: z.string().optional(),
+    parameter_name: z.string().optional(),
+    marker_symbol: z.string().optional(),
+    mgi_accession_id: z.string().optional(),
+});
+// The `response` envelope shared by every IMPC Solr core, validated at the fetch boundary.
+const ImpcSolrResponseSchema = z.object({
+    response: z.object({ docs: z.array(ImpcSolrDocSchema).optional(), numFound: z.number().optional() }).optional(),
+});
+function escapeSolrValue(value) {
+    return value.replace(/([+\-&|!(){}[\]^"~*?:\\/\s])/g, "\\$1");
+}
+export function parsePhenotypeResponse(raw) {
+    // `raw` is the untyped IMPC Solr response; we reach `.response.docs` defensively
+    // (optional-chained, defaulted to []) and treat each doc's fields as optional below.
+    const docs = raw?.response?.docs ?? [];
+    if (!Array.isArray(docs) || docs.length === 0) {
+        return { mpTerms: [], organSystems: [], sexDimorphic: false, phenotypeCount: 0 };
+    }
+    const byMp = new Map();
+    const organCounts = new Map();
+    const mpToSexes = new Map();
+    const allSexes = new Set();
+    for (const doc of docs) {
+        const mpId = doc.mp_term_id;
+        if (!mpId)
+            continue;
+        const newP = typeof doc.p_value === "number" && Number.isFinite(doc.p_value) ? doc.p_value : null;
+        const existing = byMp.get(mpId);
+        if (!existing) {
+            byMp.set(mpId, { id: mpId, term: doc.mp_term_name ?? "", bestPValue: newP });
+        }
+        else if (newP !== null && (existing.bestPValue === null || newP < existing.bestPValue)) {
+            existing.bestPValue = newP;
+        }
+        const tops = doc.top_level_mp_term_name;
+        if (Array.isArray(tops)) {
+            for (const t of tops) {
+                const key = typeof t === "string" ? t.toLowerCase() : "";
+                const bucket = ORGAN_SYSTEM_MAP[key];
+                if (bucket)
+                    organCounts.set(bucket, (organCounts.get(bucket) ?? 0) + 1);
+            }
+        }
+        const sex = typeof doc.sex === "string" ? doc.sex.toLowerCase() : "";
+        if (sex) {
+            allSexes.add(sex);
+            if (!mpToSexes.has(mpId))
+                mpToSexes.set(mpId, new Set());
+            mpToSexes.get(mpId).add(sex);
+        }
+    }
+    const mpTerms = [...byMp.values()].sort((a, b) => {
+        const ap = a.bestPValue ?? 1;
+        const bp = b.bestPValue ?? 1;
+        return ap - bp;
+    });
+    const organSystems = [...organCounts.entries()].sort((a, b) => b[1] - a[1]).map(([k]) => k);
+    const bothSexesTested = allSexes.has("male") && allSexes.has("female");
+    const sexDimorphic = bothSexesTested && [...mpToSexes.values()].some((sexes) => (sexes.has("male") && !sexes.has("female")) || (sexes.has("female") && !sexes.has("male")));
+    return { mpTerms, organSystems, sexDimorphic, phenotypeCount: byMp.size };
+}
+export function buildViabilityCalls(docsB, docsC) {
+    // `docsB`/`docsC` are untyped IMPC Solr responses; the `.response.docs` reach is
+    // optional-chained + defaulted, so a shape mismatch degrades to an empty result.
+    const bDocs = docsB?.response?.docs ?? [];
+    const cDocs = docsC?.response?.docs ?? [];
+    const seen = new Set();
+    const out = [];
+    for (const d of bDocs) {
+        const pid = d.parameter_stable_id;
+        if (!pid || seen.has(pid))
+            continue;
+        seen.add(pid);
+        out.push({
+            zygosity: d.parameter_name ?? "",
+            parameterStableId: pid,
+            mpTerm: d.mp_term_id && d.mp_term_name ? { id: d.mp_term_id, name: d.mp_term_name } : null,
+        });
+    }
+    for (const d of cDocs) {
+        const pid = d.parameter_stable_id;
+        if (!pid || seen.has(pid))
+            continue;
+        seen.add(pid);
+        out.push({
+            zygosity: d.parameter_name ?? "",
+            parameterStableId: pid,
+            mpTerm: null,
+        });
+    }
+    return out;
+}
+export function derivedViability(calls) {
+    if (calls.length === 0)
+        return null;
+    if (calls.some((c) => c.mpTerm?.id === "MP:0011100"))
+        return "lethal_pre_weaning";
+    if (calls.some((c) => c.mpTerm?.id === "MP:0011110"))
+        return "subviable";
+    return "viable";
+}
+async function resolveImpcGene(humanSymbol) {
+    const q = `human_gene_symbol:${escapeSolrValue(humanSymbol)}`;
+    const url = `${IMPC_BASE}/gene/select?q=${encodeURIComponent(q)}` + `&rows=1&fl=marker_symbol,mgi_accession_id&wt=json`;
+    const res = await apiFetchValidated(url, ImpcSolrResponseSchema);
+    if (res.isErr()) {
+        if (isUnexpectedApiError(res.error))
+            throw new Error(describeApiError(res.error));
+        return null;
+    }
+    const docs = res.value?.response?.docs ?? [];
+    if (!Array.isArray(docs) || docs.length === 0)
+        return null;
+    const doc = docs[0];
+    if (!doc.marker_symbol || !doc.mgi_accession_id)
+        return null;
+    return {
+        mouseMarkerSymbol: String(doc.marker_symbol),
+        mgiAccessionId: String(doc.mgi_accession_id),
+    };
+}
+async function fetchPhenotypes(mouseSym) {
+    const q = `marker_symbol:${escapeSolrValue(mouseSym)}`;
+    const url = `${IMPC_BASE}/genotype-phenotype/select?q=${encodeURIComponent(q)}` + `&rows=${PHENOTYPE_ROW_CAP}&wt=json`;
+    const res = await apiFetchValidated(url, ImpcSolrResponseSchema);
+    if (res.isErr()) {
+        if (isUnexpectedApiError(res.error))
+            throw new Error(describeApiError(res.error));
+        return { raw: { response: { docs: [] } }, numFound: 0 };
+    }
+    const numFound = Number(res.value?.response?.numFound ?? 0);
+    return { raw: res.value, numFound };
+}
+async function fetchAssignedViability(mouseSym) {
+    const q = `marker_symbol:${escapeSolrValue(mouseSym)} AND procedure_name:"${VIABILITY_PROCEDURE}"`;
+    const url = `${IMPC_BASE}/genotype-phenotype/select?q=${encodeURIComponent(q)}` + `&rows=20&wt=json`;
+    const res = await apiFetchValidated(url, ImpcSolrResponseSchema);
+    if (res.isErr()) {
+        if (isUnexpectedApiError(res.error))
+            throw new Error(describeApiError(res.error));
+        return { response: { docs: [] } };
+    }
+    return res.value;
+}
+async function fetchScreenRan(mouseSym) {
+    const q = `marker_symbol:${escapeSolrValue(mouseSym)} AND parameter_stable_id:IMPC_VIA_*`;
+    const url = `${IMPC_BASE}/statistical-result/select?q=${encodeURIComponent(q)}` + `&rows=50&fl=parameter_stable_id,parameter_name&wt=json`;
+    const res = await apiFetchValidated(url, ImpcSolrResponseSchema);
+    if (res.isErr()) {
+        if (isUnexpectedApiError(res.error))
+            throw new Error(describeApiError(res.error));
+        return { response: { docs: [] } };
+    }
+    return res.value;
+}
+/** Full KO phenotype profile for a human gene. */
+export async function getKoPhenotypeProfile(geneSymbol) {
+    const empty = {
+        geneSymbol,
+        mouseMarkerSymbol: null,
+        mgiAccessionId: null,
+        viability: null,
+        viabilityCalls: [],
+        mpTerms: [],
+        organSystems: [],
+        sexDimorphic: false,
+        phenotypeCount: 0,
+        phenotypeDocsTotal: 0,
+        phenotypesTruncated: false,
+    };
+    const gene = await resolveImpcGene(geneSymbol);
+    if (!gene)
+        return empty;
+    const [pheno, viaAssigned, viaRan] = await Promise.all([
+        fetchPhenotypes(gene.mouseMarkerSymbol),
+        fetchAssignedViability(gene.mouseMarkerSymbol),
+        fetchScreenRan(gene.mouseMarkerSymbol),
+    ]);
+    const profile = parsePhenotypeResponse(pheno.raw);
+    const viabilityCalls = buildViabilityCalls(viaAssigned, viaRan);
+    const viability = derivedViability(viabilityCalls);
+    return {
+        geneSymbol,
+        mouseMarkerSymbol: gene.mouseMarkerSymbol,
+        mgiAccessionId: gene.mgiAccessionId,
+        viability,
+        viabilityCalls,
+        ...profile,
+        phenotypeDocsTotal: pheno.numFound,
+        phenotypesTruncated: pheno.numFound > PHENOTYPE_ROW_CAP,
+    };
+}

package/dist/tools/lib/iuphar-client.d.ts

@@ -0,0 +1,75 @@
+/**
+ * Pure async client functions for the IUPHAR Guide to Pharmacology
+ * (https://www.guidetopharmacology.org/services/) REST API.
+ *
+ * Used to discover, for any HGNC target or UniProt accession, the obligate
+ * heterodimer complexes that share the same primary protein (e.g., AMY1/
+ * AMY2/AMY3 amylin receptors share the CT receptor protein with the
+ * calcitonin receptor and differ only by their RAMP accessory). Powers
+ * data-driven heterodimer filtering in target-assessment so off-target
+ * panels never list a sibling receptor-complex as a developable hit.
+ */
+import { z } from "zod";
+declare const IupharTargetSchema: z.ZodObject<{
+    targetId: z.ZodNumber;
+    name: z.ZodString;
+    type: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    familyIds: z.ZodArray<z.ZodNumber>;
+    subunitIds: z.ZodOptional<z.ZodArray<z.ZodNumber>>;
+    complexIds: z.ZodArray<z.ZodNumber>;
+    subunitType: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export type IupharTarget = z.infer<typeof IupharTargetSchema>;
+export interface IupharHeterodimer {
+    /** Complex target record (e.g., the AMY1 receptor). */
+    complex: IupharTarget;
+    /** All subunits of the complex, including the primary protein and accessory(ies). */
+    subunits: IupharTarget[];
+    /** Accessory-protein subunits only (type === "AccessoryProtein"). */
+    accessories: IupharTarget[];
+}
+export declare function findTargetByGeneSymbol(geneSymbol: string): Promise<IupharTarget | null>;
+export declare function findTargetByUniprot(accession: string): Promise<IupharTarget | null>;
+/**
+ * Resolve a target by either a UniProt accession or HGNC gene symbol.
+ * Tries the format that matches the input shape first, then falls back.
+ */
+export declare function resolveTarget(uniprotOrGeneSymbol: string): Promise<IupharTarget | null>;
+export declare function getSubunits(complexId: number): Promise<IupharTarget[]>;
+/**
+ * Get the heterodimer / family complexes that contain the primary target
+ * (e.g., for CALCR → the AMY1/AMY2/AMY3 amylin receptors, each carrying a
+ * RAMP1/2/3 accessory). Names are stripped of IUPHAR's HTML subscript markup.
+ *
+ * Returns [] when the target isn't resolvable in GtoPdb or has no
+ * registered complexes.
+ */
+export declare function getFamilyHeterodimers(uniprotOrGeneSymbol: string): Promise<IupharHeterodimer[]>;
+/**
+ * Distinct accessory-protein gene symbols across all heterodimer complexes
+ * containing the primary target. Used to build a runtime regex alternation
+ * for heterodimer-name filtering instead of hardcoding RAMP/MRAP/RGS.
+ *
+ * Example: getAccessoryProteinNames("CALCR") → ["RAMP1", "RAMP2", "RAMP3"].
+ */
+export declare function getAccessoryProteinNames(uniprotOrGeneSymbol: string): Promise<string[]>;
+declare const IupharFamilySchema: z.ZodObject<{
+    familyId: z.ZodOptional<z.ZodNumber>;
+    name: z.ZodOptional<z.ZodString>;
+    targetIds: z.ZodArray<z.ZodNumber>;
+    parentFamilyIds: z.ZodOptional<z.ZodArray<z.ZodNumber>>;
+    subFamilyIds: z.ZodOptional<z.ZodArray<z.ZodNumber>>;
+}, z.core.$strip>;
+export type IupharFamily = z.infer<typeof IupharFamilySchema>;
+export declare function getFamily(familyId: number): Promise<IupharFamily | null>;
+/** Fetch the UniProtKB cross-references (human only) for an IUPHAR target. */
+export declare function getTargetHumanUniprots(targetId: number): Promise<string[]>;
+/**
+ * UniProt accessions of sibling primary-GPCR targets in the same IUPHAR
+ * family as the input (excludes the input target itself and any target
+ * registered as a complex with subunits). For CALCR this returns the
+ * CALCRL accession; the AMY1/2/3 complexes are excluded because they are
+ * heterodimers, not separate primary proteins.
+ */
+export declare function getFamilySiblingUniprots(uniprotOrGeneSymbol: string): Promise<string[]>;
+export {};