@inflexa-ai/harness 0.1.1

package/dist/workflows/target-assessment/lib/approval-precedents.d.ts

@@ -0,0 +1,52 @@
+/**
+ * Approval-precedent grounding for Phase-5 synthesis.
+ *
+ * Synthesis runs single-shot forced-`submit` LLM calls and can therefore call
+ * no tool. This module does the openFDA / Drugs@FDA lookup deterministically
+ * before synthesis so the fetched precedents can be injected into the synthesis
+ * prompts as a static markdown block. The fetch, in-memory TTL cache, and
+ * mapping mirror what a per-turn tool would have done, minus the tool wrapper.
+ */
+import type { DossierV4Body } from "../../../contracts/target-dossier.js";
+export type PrecedentModality = "small_molecule" | "biologic" | "gene_therapy" | "cell_therapy";
+export interface FetchApprovalPrecedentsInput {
+    indication: string;
+    modality?: PrecedentModality;
+    mechanism?: string;
+}
+export interface Precedent {
+    application_number: string;
+    brand_name?: string;
+    generic_name?: string;
+    approval_date?: string;
+    label_section_excerpts?: Record<string, string>;
+}
+/**
+ * Query openFDA for prior approvals in a given indication. Returns
+ * NDA/BLA application numbers, generic and brand names, approval dates
+ * (label effective time), and label-section excerpts.
+ *
+ * openFDA answers a zero-match search with 404 — an expected "no precedents"
+ * outcome, returned uncached so a later, more specific query is not masked.
+ * Any other non-ok status (5xx, 429) is an unexpected failure and throws; the
+ * caller wraps the throw.
+ */
+export declare function fetchApprovalPrecedents(input: FetchApprovalPrecedentsInput): Promise<{
+    precedents: Precedent[];
+}>;
+/** Test-only — clears the in-memory cache to avoid cross-test bleed. */
+export declare function __resetApprovalPrecedentCacheForTest(): void;
+/**
+ * Pick the openFDA query term for a Phase-4 dossier: the top `indications`
+ * row by `composite_score` (only when indications coverage is available and
+ * has rows), falling back to the inferred therapeutic area, else null.
+ */
+export declare function pickIndicationForPrecedents(dossier: DossierV4Body): string | null;
+/**
+ * Render the fetched precedents as a markdown block for injection into the
+ * synthesis prompts. The block always begins with the `## FDA approval
+ * precedents` header, which the synthesis briefs reference verbatim.
+ */
+export declare function renderApprovalPrecedents(indication: string | null, result: {
+    precedents: Precedent[];
+} | null): string;

package/dist/workflows/target-assessment/lib/approval-precedents.js

@@ -0,0 +1,119 @@
+/**
+ * Approval-precedent grounding for Phase-5 synthesis.
+ *
+ * Synthesis runs single-shot forced-`submit` LLM calls and can therefore call
+ * no tool. This module does the openFDA / Drugs@FDA lookup deterministically
+ * before synthesis so the fetched precedents can be injected into the synthesis
+ * prompts as a static markdown block. The fetch, in-memory TTL cache, and
+ * mapping mirror what a per-turn tool would have done, minus the tool wrapper.
+ */
+const cache = new Map();
+const TTL_MS = 60 * 60 * 1000;
+/**
+ * Query openFDA for prior approvals in a given indication. Returns
+ * NDA/BLA application numbers, generic and brand names, approval dates
+ * (label effective time), and label-section excerpts.
+ *
+ * openFDA answers a zero-match search with 404 — an expected "no precedents"
+ * outcome, returned uncached so a later, more specific query is not masked.
+ * Any other non-ok status (5xx, 429) is an unexpected failure and throws; the
+ * caller wraps the throw.
+ */
+export async function fetchApprovalPrecedents(input) {
+    const { indication, modality, mechanism } = input;
+    const key = JSON.stringify({
+        indication: indication.toLowerCase(),
+        modality,
+        mechanism,
+    });
+    const cached = cache.get(key);
+    if (cached && Date.now() - cached.ts < TTL_MS)
+        return cached.value;
+    const term = indication.replace(/"/g, "");
+    const url = new URL("https://api.fda.gov/drug/label.json");
+    url.searchParams.set("search", `indications_and_usage:"${term}"`);
+    url.searchParams.set("limit", "10");
+    const res = await fetch(url);
+    if (res.status === 404)
+        return { precedents: [] };
+    if (!res.ok) {
+        throw new Error(`openFDA label query failed: HTTP ${res.status}`);
+    }
+    const json = (await res.json());
+    const precedents = (json.results ?? []).slice(0, 10).map((r) => {
+        const excerpts = {};
+        if (r.boxed_warning?.[0])
+            excerpts.boxed_warning = r.boxed_warning[0].slice(0, 1000);
+        if (r.warnings_and_precautions?.[0])
+            excerpts.warnings_and_precautions = r.warnings_and_precautions[0].slice(0, 1000);
+        else if (r.warnings?.[0])
+            excerpts.warnings = r.warnings[0].slice(0, 1000);
+        if (r.contraindications?.[0])
+            excerpts.contraindications = r.contraindications[0].slice(0, 1000);
+        return {
+            application_number: r.openfda?.application_number?.[0] ?? "(unknown)",
+            brand_name: r.openfda?.brand_name?.[0],
+            generic_name: r.openfda?.generic_name?.[0],
+            approval_date: r.effective_time,
+            label_section_excerpts: Object.keys(excerpts).length > 0 ? excerpts : undefined,
+        };
+    });
+    const value = { precedents };
+    cache.set(key, { ts: Date.now(), value });
+    return value;
+}
+/** Test-only — clears the in-memory cache to avoid cross-test bleed. */
+export function __resetApprovalPrecedentCacheForTest() {
+    cache.clear();
+}
+/**
+ * Pick the openFDA query term for a Phase-4 dossier: the top `indications`
+ * row by `composite_score` (only when indications coverage is available and
+ * has rows), falling back to the inferred therapeutic area, else null.
+ */
+export function pickIndicationForPrecedents(dossier) {
+    const indications = dossier.indications;
+    if (indications.coverage === "available" && indications.data.rows.length > 0) {
+        const top = indications.data.rows.reduce((best, row) => (row.composite_score > best.composite_score ? row : best));
+        if (top.disease_name)
+            return top.disease_name;
+    }
+    return dossier.liability_summary.inferred_therapeutic_area ?? null;
+}
+/**
+ * Render the fetched precedents as a markdown block for injection into the
+ * synthesis prompts. The block always begins with the `## FDA approval
+ * precedents` header, which the synthesis briefs reference verbatim.
+ */
+export function renderApprovalPrecedents(indication, result) {
+    const header = "## FDA approval precedents";
+    if (indication === null) {
+        return [header, "", "No indication could be resolved from the dossier, so no FDA approval precedents were queried."].join("\n");
+    }
+    const precedents = result?.precedents ?? [];
+    if (precedents.length === 0) {
+        return [
+            header,
+            "",
+            `No FDA approval precedents were found for "${indication}". Do not assert class precedents that are not present in the dossier.`,
+        ].join("\n");
+    }
+    const lines = [
+        header,
+        "",
+        `Prior FDA approvals retrieved for "${indication}". Ground class-precedent and disposition claims in these records; do not invent precedents beyond this list and the dossier.`,
+        "",
+    ];
+    for (const p of precedents) {
+        const generic = p.generic_name ?? "unknown generic";
+        const brand = p.brand_name ?? "unknown brand";
+        const date = p.approval_date ?? "unknown date";
+        lines.push(`- ${generic} (${brand}), ${p.application_number}, approved ${date}`);
+        if (p.label_section_excerpts) {
+            for (const [section, excerpt] of Object.entries(p.label_section_excerpts)) {
+                lines.push(`  - ${section}: ${excerpt}`);
+            }
+        }
+    }
+    return lines.join("\n");
+}

package/dist/workflows/target-assessment/lib/citation-validator.d.ts

@@ -0,0 +1,46 @@
+export type RecommendationAuditEntry = {
+    surface: "rationale" | "key_strengths" | "key_risks" | "modality_choice";
+    path: string;
+    excerpt: string;
+} | {
+    surface: "external_missing";
+    id: string;
+    excerpt: string;
+} | {
+    surface: "organ_claim_without_probe_pass";
+    excerpt: string;
+    bullet_category: string;
+} | {
+    surface: "nct_wrong_class";
+    id: string;
+    excerpt: string;
+} | {
+    surface: "pmid_not_in_key_papers";
+    id: string;
+    excerpt: string;
+};
+export type RecommendationAudit = {
+    citations_total: number;
+    citations_unresolved: RecommendationAuditEntry[];
+    non_dossier_citations: Array<{
+        token: string;
+        source: string;
+    }>;
+};
+type KeyRiskLike = {
+    text: string;
+    category?: string;
+} | string;
+type RecLike = {
+    rationale: string;
+    key_strengths: KeyRiskLike[];
+    key_risks: KeyRiskLike[];
+    modality_choice: {
+        rationale: string;
+    };
+    external_citations?: Array<{
+        id: string;
+    }>;
+};
+export declare function validateRecommendationCitations(rec: RecLike, dossier: unknown): RecommendationAudit;
+export {};

package/dist/workflows/target-assessment/lib/citation-validator.js

@@ -0,0 +1,316 @@
+// The recommendation agent emits citations as `[dossier: path; path; …]`
+// blocks (colon-space, semicolon-separated), sometimes with a trailing
+// `external citation: id; id` segment inside the same bracket. The old
+// `dossier.path` regex never matched this in production — citations_total
+// was always 0. These patterns match the format the agent actually writes.
+// The block content may include array index notation like `[0]`, so we
+// use a pattern that allows `[digits]` inside the outer brackets.
+const DOSSIER_CITE_BLOCK_RE = /\[dossier:\s*((?:[^[\]]*(?:\[\d+\])?)*)\]/gi;
+// External citation IDs are plain strings — no array-index notation like `[n]` — so the simple [^\]]+ class suffices here instead of the array-index-aware pattern used by DOSSIER_CITE_BLOCK_RE.
+const EXTERNAL_CITE_BLOCK_RE = /\[external citation:\s*([^\]]+)\]/gi;
+// Assumes at most one `external citation:` segment per dossier block (the recommendation prompt produces at most one); a hypothetical second segment in the same block would be parsed imperfectly.
+const EXTERNAL_SEGMENT_RE = /external citation:\s*((?:[^[\]]*(?:\[\d+\])?)*)/i;
+const NCT_RE = /\bNCT\d{8}\b/g;
+const PMID_RE = /\bPMID[:\s]?(\d{6,9})\b/g;
+// Legacy inline format: `dossier.path.foo` written directly in prose, no
+// brackets. Still emitted by some recommendation outputs and exercised by
+// the regression fixtures, so BOTH this and the `[dossier: …]` block format
+// must be supported. This pattern only matches a bare `dossier.x.y` token —
+// inside a `[dossier: …]` block the word `dossier` is followed by `:`, not
+// `.`/`[`, so the two are disjoint and never double-count.
+const DOSSIER_PATH_RE = /\bdossier(?:\.[A-Za-z_][A-Za-z0-9_]*|\[\d+\])+/g;
+// Legacy bare external reference: `[ANDA215864]` — an all-caps id in
+// brackets. Disjoint from `[dossier: …]` / `[external citation: …]` blocks
+// (those start with a lowercase word) and from `[0]` array indices (digits).
+const EXTERNAL_ID_RE = /\[([A-Z]{2,}[A-Z0-9_-]+)\]/g;
+// Path prefixes the agent uses that are NOT part of the persisted dossier
+// body — they refer to the per-section synthesis inputs the agent was
+// shown. Citing them is legitimate; resolving them against the dossier is
+// not, so they go to `non_dossier_citations` instead of `unresolved`.
+const NON_DOSSIER_PREFIXES = ["per_section_synthesis"];
+const ORGAN_CATEGORIES = new Set(["high_safety_organ_expression", "broad_expression", "class_liability"]);
+/**
+ * Keyword fallback for detecting organ-level claims when the bullet has
+ * no structural `category` field (the production
+ * DossierRecommendationOutputSchema types key_risks as z.array(z.string())
+ * with no category metadata, so a category check alone would be dead
+ * code). Matches the regression-test approach in
+ * [C4] of calcr-target-assessment.test.ts.
+ */
+const ORGAN_KEYWORDS_RE = /\b(kidney|kidneys|renal|nephro\w*|cns|central\s+nervous|brain|hypothalam\w*|cardiac|cardiovascular|hepatic|liver|hepato\w*|pulmonary|respiratory|gastrointestinal)\b/i;
+/**
+ * Bullet-keyword → canonical organ class. The keys mirror the alternatives
+ * in `ORGAN_KEYWORDS_RE`; values match `target_organ_liabilities[i].organ`,
+ * which the assembler emits using the canonical safety-panel set
+ * (`cardiac` | `cns` | `hepatic` | `renal` | `gi` | `respiratory` | ...).
+ *
+ * Used to cross-match an organ-level key_risk bullet against the TOL probe
+ * pass without depending on the bullet text containing the literal JSON
+ * path `dossier.safety_profile.target_organ_liabilities` — LLM bullets are
+ * plain English so the path-based check from earlier never matched in
+ * production.
+ */
+const BULLET_KEYWORD_TO_ORGAN = [
+    { rx: /\b(kidney|kidneys|renal|nephro\w*)\b/i, organ: "renal" },
+    { rx: /\b(cns|central\s+nervous|brain|hypothalam\w*)\b/i, organ: "cns" },
+    { rx: /\b(cardiac|cardiovascular)\b/i, organ: "cardiac" },
+    { rx: /\b(hepatic|liver|hepato\w*)\b/i, organ: "hepatic" },
+    { rx: /\b(pulmonary|respiratory)\b/i, organ: "respiratory" },
+    { rx: /\b(gastrointestinal)\b/i, organ: "gi" },
+];
+function extractOrganClassesFromText(text) {
+    const result = new Set();
+    for (const { rx, organ } of BULLET_KEYWORD_TO_ORGAN) {
+        if (rx.test(text))
+            result.add(organ);
+    }
+    return result;
+}
+function resolvePath(root, path) {
+    if (!path.startsWith("dossier"))
+        return undefined;
+    const stripped = path.replace(/^dossier\.?/, "");
+    if (stripped === "")
+        return root;
+    const parts = stripped.split(/\.|\[(\d+)\]/).filter(Boolean);
+    return walkWithDataFallback(root, parts);
+}
+function walkWithDataFallback(root, parts) {
+    let cur = root;
+    for (const p of parts) {
+        if (cur == null)
+            return undefined;
+        const next = readPart(cur, p);
+        if (next !== undefined) {
+            cur = next;
+            continue;
+        }
+        // The dossier wraps every section as { coverage, data: {...} }. When a
+        // lookup misses and the current node has a `data` child, descend through
+        // it transparently — the LLM consistently writes paths without the wrapper
+        // (e.g. "translational_chain.peak_evidence_tier" instead of
+        // "translational_chain.data.peak_evidence_tier"). This mirrors how a human
+        // reader refers to the field; flagging it as unresolved produces noise.
+        if (typeof cur === "object" && "data" in cur) {
+            const viaData = readPart(cur.data, p);
+            if (viaData !== undefined) {
+                cur = viaData;
+                continue;
+            }
+        }
+        return undefined;
+    }
+    return cur;
+}
+function readPart(node, p) {
+    if (node == null)
+        return undefined;
+    if (/^\d+$/.test(p))
+        return Array.isArray(node) ? node[parseInt(p, 10)] : undefined;
+    return typeof node === "object" ? node[p] : undefined;
+}
+/**
+ * Extract dossier-path citations from `text`, supporting two formats:
+ *   - New `[dossier: path; path]` blocks — `;`-separated bare paths, a
+ *     trailing `/ID-list` suffix dropped, `external citation:` segment
+ *     excluded (picked up by `findExternalIds`).
+ *   - Legacy inline `dossier.path.foo` tokens written directly in prose.
+ *
+ * Returns `{ path, resolvable }` pairs: `path` is what surfaces in an
+ * unresolved-citation entry (bare for block tokens, `dossier.`-prefixed for
+ * legacy tokens — matching what each format's callers expect); `resolvable`
+ * is always `dossier.`-prefixed so `resolvePath` can walk it.
+ */
+function findPathTokens(text) {
+    const tokens = [];
+    // New `[dossier: …]` block format.
+    for (const block of text.matchAll(DOSSIER_CITE_BLOCK_RE)) {
+        const dossierPart = block[1].split(/external citation:/i)[0];
+        for (const raw of dossierPart.split(";")) {
+            const token = raw.trim().split("/")[0].trim();
+            if (token.length > 0)
+                tokens.push({ path: token, resolvable: `dossier.${token}` });
+        }
+    }
+    // Legacy inline `dossier.path.foo` format. The match already carries the
+    // `dossier.` prefix — keep it in `path` (callers expect the prefixed form
+    // for this format) and use it directly as `resolvable`.
+    for (const m of text.matchAll(DOSSIER_PATH_RE)) {
+        tokens.push({ path: m[0], resolvable: m[0] });
+    }
+    return tokens;
+}
+/**
+ * Extract external-citation ids. The agent writes them either as a
+ * standalone `[external citation: id; id]` block or as a trailing segment
+ * inside a `[dossier: …; external citation: id]` block.
+ */
+function findExternalIds(text) {
+    const ids = [];
+    const push = (segment) => {
+        for (const raw of segment.split(";")) {
+            const id = raw.trim();
+            if (id.length > 0)
+                ids.push(id);
+        }
+    };
+    for (const block of text.matchAll(EXTERNAL_CITE_BLOCK_RE))
+        push(block[1]);
+    for (const block of text.matchAll(DOSSIER_CITE_BLOCK_RE)) {
+        const m = block[1].match(EXTERNAL_SEGMENT_RE);
+        if (m)
+            push(m[1]);
+    }
+    // Legacy bare `[UPPERCASE_ID]` external reference (e.g. `[ANDA215864]`).
+    // NCT and PMID references in bracket form are already handled by NCT_RE /
+    // PMID_RE in the main loop — skip them here to avoid double-processing.
+    for (const m of text.matchAll(EXTERNAL_ID_RE)) {
+        const id = m[1];
+        if (/^NCT\d/.test(id) || /^PMID\d/.test(id))
+            continue;
+        ids.push(id);
+    }
+    return ids;
+}
+function normaliseBullet(b) {
+    return typeof b === "string" ? { text: b } : { text: b.text, category: b.category };
+}
+function collectClassDrugNames(dossier) {
+    const rows = dossier?.drug_interactions?.data?.rows ?? [];
+    return new Set(rows.map((r) => String(r.drug_name ?? "").toUpperCase()).filter(Boolean));
+}
+function collectKeyPaperPmids(dossier) {
+    const rows = dossier?.reference_biology?.key_papers?.data?.rows ?? [];
+    return new Set(rows.map((r) => String(r.pmid)).filter(Boolean));
+}
+/**
+ * Extract intervention names from a trial row. Handles two shapes:
+ * - Flat `interventions: string[]` — the production dossier shape assembled by
+ *   `partitionTrialsByAttribution`.
+ * - Nested `armsInterventionsModule.interventions: Array<{ name: string }>` — the
+ *   raw CT.gov v2 JSON shape that may appear in test fixtures or future collector
+ *   output before the assembler flattens it.
+ */
+function extractInterventionNames(row) {
+    // Production flat shape (priority)
+    if (Array.isArray(row.interventions)) {
+        return row.interventions.map((iv) => (typeof iv === "string" ? iv.toUpperCase() : String(iv?.name ?? "").toUpperCase()));
+    }
+    // Raw CT.gov nested shape fallback
+    const nested = row?.armsInterventionsModule?.interventions;
+    if (Array.isArray(nested)) {
+        return nested.map((iv) => String(iv?.name ?? "").toUpperCase());
+    }
+    return [];
+}
+function findTrialInterventions(dossier, nctId) {
+    const trialSets = [
+        dossier?.clinical_development?.trials?.data?.rows ?? [],
+        dossier?.clinical_development?.failed_trials?.data?.rows ?? [],
+        dossier?.analytics?.discovery_trials?.data?.rows ?? [],
+    ];
+    for (const set of trialSets) {
+        const row = set.find((t) => t.nct_id === nctId);
+        if (!row)
+            continue;
+        return extractInterventionNames(row);
+    }
+    return [];
+}
+export function validateRecommendationCitations(rec, dossier) {
+    const dossierView = dossier;
+    const unresolved = [];
+    const nonDossier = [];
+    let total = 0;
+    const externalIds = new Set((rec.external_citations ?? []).map((c) => c.id));
+    const surfaces = [
+        { surface: "rationale", text: rec.rationale },
+        { surface: "modality_choice", text: rec.modality_choice.rationale },
+        ...rec.key_strengths.map((b) => ({ surface: "key_strengths", text: normaliseBullet(b).text })),
+        ...rec.key_risks.map((b) => ({ surface: "key_risks", text: normaliseBullet(b).text })),
+    ];
+    const classDrugNames = collectClassDrugNames(dossierView);
+    const keyPmids = collectKeyPaperPmids(dossierView);
+    for (const { surface, text } of surfaces) {
+        for (const { path, resolvable } of findPathTokens(text)) {
+            total += 1;
+            // Legacy-format tokens carry a `dossier.` prefix; block-format tokens
+            // are bare. Strip the prefix so the non-dossier-prefix check works for
+            // both formats.
+            const barePath = path.startsWith("dossier.") ? path.slice("dossier.".length) : path;
+            if (NON_DOSSIER_PREFIXES.some((p) => barePath === p || barePath.startsWith(`${p}.`) || barePath.startsWith(`${p}[`))) {
+                nonDossier.push({ token: path, source: surface });
+                continue;
+            }
+            const resolved = resolvePath(dossier, resolvable);
+            if (resolved === undefined || resolved === null) {
+                unresolved.push({ surface, path, excerpt: text.slice(0, 200) });
+            }
+        }
+        for (const id of findExternalIds(text)) {
+            if (!externalIds.has(id)) {
+                unresolved.push({ surface: "external_missing", id, excerpt: text.slice(0, 200) });
+            }
+        }
+        for (const m of text.matchAll(NCT_RE)) {
+            const nctId = m[0];
+            const interventions = findTrialInterventions(dossierView, nctId);
+            // Only flag wrong-class when the trial IS present in the dossier
+            // and its interventions don't reference the class. Trials absent
+            // from the collected sets are unverifiable — flagging them would
+            // produce false positives for any on-class trial that the
+            // synthesis agent cited but the discovery collector missed.
+            if (interventions.length === 0)
+                continue;
+            // Skip when no class-drug catalog is available — without a reference
+            // set (early-stage / first-in-class targets, or drug_interactions
+            // collector returning queried_no_data) every cited trial would
+            // otherwise flag as wrong-class regardless of its actual class.
+            if (classDrugNames.size === 0)
+                continue;
+            const referencesClassDrug = interventions.some((iv) => [...classDrugNames].some((name) => iv.includes(name)));
+            if (!referencesClassDrug) {
+                unresolved.push({ surface: "nct_wrong_class", id: nctId, excerpt: text.slice(0, 200) });
+            }
+        }
+        for (const m of text.matchAll(PMID_RE)) {
+            const pmid = m[1];
+            if (!keyPmids.has(pmid)) {
+                unresolved.push({ surface: "pmid_not_in_key_papers", id: pmid, excerpt: text.slice(0, 200) });
+            }
+        }
+    }
+    const organLiabilities = dossierView?.safety_profile?.target_organ_liabilities ?? [];
+    const tolOrgans = new Set(organLiabilities
+        .map((t) => String(t?.organ ?? "")
+        .toLowerCase()
+        .trim())
+        .filter((o) => o.length > 0));
+    for (const b of rec.key_risks ?? []) {
+        const norm = normaliseBullet(b);
+        // Detect organ-level claims by structural category when available
+        // (typed bullets) OR by keyword match on the text (plain-string
+        // bullets — the production shape).
+        const isOrganClaim = (norm.category != null && ORGAN_CATEGORIES.has(norm.category)) || ORGAN_KEYWORDS_RE.test(norm.text);
+        if (!isOrganClaim)
+            continue;
+        // "Probe pass" = the TOL section has an entry whose organ matches the
+        // organ class mentioned in the bullet. Production bullets are plain
+        // English so we extract the organ class via keyword matching and
+        // cross-reference against the canonical TOL organ field.
+        const bulletOrgans = extractOrganClassesFromText(norm.text);
+        const citesTOL = bulletOrgans.size > 0 && [...bulletOrgans].some((o) => tolOrgans.has(o));
+        if (!citesTOL) {
+            unresolved.push({
+                surface: "organ_claim_without_probe_pass",
+                excerpt: norm.text.slice(0, 200),
+                bullet_category: norm.category ?? "inferred_from_text",
+            });
+        }
+    }
+    return {
+        citations_total: total,
+        citations_unresolved: unresolved,
+        non_dossier_citations: nonDossier,
+    };
+}

package/dist/workflows/target-assessment/lib/clinical-consequence-annotator.d.ts

@@ -0,0 +1,62 @@
+/**
+ * Per-row LLM clinical-consequence annotator with Postgres caching.
+ *
+ * Any off-target row missing a `clinical_consequence` gets annotated by a
+ * focused tool-less LLM specialist that returns ONE sentence + provenance.
+ * Results are cached in `cortex_off_target_annotations` keyed by
+ * (primary_target_gene, off_target_key) so repeat assessments reuse prior
+ * work.
+ *
+ * Cache miss path: when a `deps` bundle is supplied, build a compact JSON
+ * prompt, run a single-shot harness agent loop (no tools, max 2 iterations),
+ * parse JSON out of the final assistant text, INSERT on success, return the
+ * consequence. With no `deps`, the function returns null on cache miss
+ * (no LLM call). Cache hit path: a single primary-key lookup, no LLM call.
+ * Per-row failures (LLM, schema validation, DB) are swallowed — annotation
+ * is supplementary; the dossier renders fine with null.
+ */
+import { z } from "zod";
+import type { Pool } from "pg";
+import type { AgentSession } from "../../../auth/types.js";
+import type { ChatProvider } from "../../../providers/types.js";
+export declare const OffTargetAnnotationSchema: z.ZodObject<{
+    clinical_consequence: z.ZodString;
+    provenance: z.ZodString;
+}, z.core.$strip>;
+export type OffTargetAnnotation = z.infer<typeof OffTargetAnnotationSchema>;
+export interface ClinicalConsequenceAnnotatorDeps {
+    readonly provider: ChatProvider;
+    readonly session: AgentSession;
+    readonly model: string;
+}
+export interface AnnotationInput {
+    primaryTargetGene: string;
+    offTargetId: string | null;
+    offTargetName: string;
+    offTargetAccession: string | null;
+    pchembl: number;
+    /** Optional one-line family-relationship hint (e.g., "obligate cofactor"). */
+    context?: string;
+}
+/**
+ * Annotate a single off-target row. Returns null on any failure (cache
+ * miss + no deps, cache miss + LLM unavailable, schema validation failure,
+ * DB unreachable, etc.) — callers must treat null as "no annotation" and
+ * leave `clinical_consequence` as their original fallback.
+ */
+export declare function annotateClinicalConsequence(pool: Pool, input: AnnotationInput, deps?: ClinicalConsequenceAnnotatorDeps): Promise<OffTargetAnnotation | null>;
+/**
+ * Annotate every row in an off-target panel whose `clinical_consequence`
+ * is currently null. Mutates the supplied arrays in-place. Pure assembly-
+ * time helper — no return value.
+ *
+ * Per-row LLM calls are bounded by the "annotation-llm" host budget (4 in
+ * flight). Cache hits skip the LLM entirely and consume only a cheap
+ * Postgres lookup, so the budget gate is held briefly for those rows.
+ * Without `deps`, the panel is annotated cache-only — rows missing a
+ * cached entry remain with their original fallback.
+ */
+export declare function annotateOffTargetPanel(pool: Pool, panel: {
+    rows: Array<Record<string, unknown>>;
+    excluded_rows: Array<Record<string, unknown>>;
+}, primaryTargetGene: string, deps?: ClinicalConsequenceAnnotatorDeps): Promise<void>;