@inflexa-ai/harness 0.1.1

package/dist/workflows/target-assessment/lib/structured-llm.js

@@ -0,0 +1,101 @@
+/**
+ * Structured-output LLM helper for the target-assessment DBOS workflow.
+ *
+ * Uses a tool-choice forcing pattern: a single Anthropic tool named `submit`
+ * carries the Zod schema as its `input_schema`, and
+ * `tool_choice: { type: "tool", name: "submit" }` forces the model to fill
+ * it. The tool's `input` IS the structured output.
+ *
+ * This intentionally does NOT pull in the harness `runAgent` loop — Phase-2
+ * decisions are zero-tool single-shot calls. Phase-5 syntheses today use
+ * regulatory-guidance + approval-precedent retrieval tools; the harness
+ * port drops those grounding tools (PR #4 ships single-shot synthesis; a
+ * follow-up may reintroduce the retrieval tools through the agent loop).
+ *
+ * Calls are routed through `runLlmStep`, so each LLM call lives in its own
+ * `DBOS.runStep({name})` cache slot and a billing-gateway 402 self-cancels the
+ * workflow rather than returning a coverage envelope.
+ */
+import { jsonSchema, tool as aiTool } from "ai";
+import { z } from "zod";
+import { runLlmStep } from "./llm-step.js";
+const SUBMIT_TOOL_NAME = "submit";
+/**
+ * Thrown when the model returned a structured-output payload that does
+ * not parse against the declared Zod schema. The caller decides whether
+ * to wrap as `coverage: "queried_no_data"` or rethrow as a hard failure.
+ */
+export class StructuredOutputParseError extends Error {
+    cause;
+    constructor(message, cause) {
+        super(message);
+        this.cause = cause;
+        this.name = "StructuredOutputParseError";
+    }
+}
+/**
+ * Convert a Zod schema to the JSON Schema shape Anthropic accepts as
+ * `tool.input_schema`. Strips `$schema` (Anthropic rejects it) and asserts
+ * a top-level `"type": "object"` (Anthropic rejects oneOf at the root).
+ */
+function schemaToJsonSchema(schema, stepName) {
+    const jsonSchema = z.toJSONSchema(schema);
+    delete jsonSchema.$schema;
+    if (jsonSchema.type !== "object") {
+        throw new Error(`structuredLlmCall(${stepName}): schema must emit top-level "type":"object", ` + `got ${JSON.stringify(jsonSchema.type)}`);
+    }
+    // `z.toJSONSchema()` returns an untyped JSON-schema object; it is structurally
+    // Anthropic's `input_schema` once the top-level `type:"object"` check above passes
+    // (the one shape Anthropic requires), which is the invariant making this cast safe.
+    return jsonSchema;
+}
+function extractToolUseInput(blocks) {
+    for (const block of blocks) {
+        const part = block;
+        if (part.type === "tool-call" && part.toolName === SUBMIT_TOOL_NAME) {
+            return part.input;
+        }
+    }
+    return undefined;
+}
+/**
+ * Run one structured-output LLM call. Forces the model to call the
+ * `submit` tool whose input schema is `opts.schema`; parses the tool
+ * input via `safeParse` and returns the typed value. A billing-gateway 402 returns
+ * the budget-exceeded sentinel; non-402 throws + parse errors throw.
+ */
+export async function structuredLlmCall(opts) {
+    const inputSchema = schemaToJsonSchema(opts.schema, opts.stepName);
+    const req = {
+        system: opts.system,
+        messages: [{ role: "user", content: opts.prompt }],
+        tools: {
+            [SUBMIT_TOOL_NAME]: aiTool({
+                description: `Submit the structured output. Call this tool exactly once with the final answer.`,
+                inputSchema: jsonSchema(inputSchema),
+            }),
+        },
+        toolChoice: { type: "tool", toolName: SUBMIT_TOOL_NAME },
+    };
+    const result = await runLlmStep({
+        stepName: opts.stepName,
+        agentId: opts.agentId,
+        provider: opts.provider,
+        req,
+        session: opts.session,
+        signal: opts.signal,
+    });
+    if (result.kind === "budget-exceeded") {
+        return result;
+    }
+    const content = result.response.message.content;
+    const raw = extractToolUseInput(Array.isArray(content) ? content : []);
+    if (raw === undefined) {
+        throw new StructuredOutputParseError(`structuredLlmCall(${opts.stepName}): model returned no submit tool_use block`);
+    }
+    const parsed = opts.schema.safeParse(raw);
+    if (!parsed.success) {
+        throw new StructuredOutputParseError(`structuredLlmCall(${opts.stepName}): submit payload failed schema validation: ${parsed.error.message}`, parsed.error);
+    }
+    return { kind: "ok", value: parsed.data };
+}

package/dist/workflows/target-assessment/lib/target-identity-filter.d.ts

@@ -0,0 +1,60 @@
+/**
+ * Trial-attribution classifier + UniProt-backed identity resolvers.
+ *
+ * `resolveOnTargetChemblIds` and `resolveFamilySiblingUniprots` replace the
+ * hand-curated ALTERNATE_CHEMBL_IDS and RELATED_FAMILY_UNIPROTS maps that
+ * previously lived here. Both fetch from authoritative sources at assembly
+ * time (UniProt for ChEMBL cross-references; IUPHAR Guide to Pharmacology
+ * for receptor-family siblings) so no per-target editing is needed when a
+ * new HGNC target is assessed.
+ *
+ * The actual loop-level checks (`isOnTargetChemblId` etc.) take the
+ * resolved arrays as plain inputs so the per-row assembly path stays
+ * synchronous after a single upfront await.
+ */
+export type TrialAttributionInput = {
+    assessmentUniprot: string;
+    /** UniProts of related family receptors (resolved from IUPHAR family siblings). */
+    familyUniprots: string[];
+    interventions: Array<{
+        drugChemblId: string | null;
+        name: string;
+    }>;
+    conditions: string[];
+    drugTargetResolver: (chemblId: string) => Promise<string[]>;
+};
+export type TrialAttributionResult = {
+    match_confidence: "high" | "low" | "off_target";
+    intervention_target_uniprots: string[];
+    related_target_uniprots: string[];
+};
+/**
+ * Classify how strongly a trial pertains to the assessment target based on
+ * the intervention drug's mechanism target.
+ */
+export declare function classifyTrialAttribution(input: TrialAttributionInput): Promise<TrialAttributionResult>;
+/**
+ * Resolve every ChEMBL target id that UniProt links to the given accession.
+ * The result is used as a positive list for on-target self-hit detection —
+ * a polypharm row whose off_target_id is in this list is the assessment
+ * target itself (alternate ChEMBL entry), not an off-target liability.
+ *
+ * Returns [] when the accession is missing or UniProt has no ChEMBL xrefs.
+ * Network failures are surfaced as an empty list so the assembler degrades
+ * to "no alternate-id filtering" rather than blocking the run.
+ */
+export declare function resolveOnTargetChemblIds(assessmentUniprot: string): Promise<string[]>;
+/**
+ * Resolve UniProt accessions of sibling receptors in the same IUPHAR family
+ * as the assessment target. Used by `classifyTrialAttribution` so a trial
+ * whose intervention hits a paralog (e.g., CALCRL when CALCR is the
+ * assessment target) lands in `related_target_trials[]` rather than the
+ * primary trials list.
+ */
+export declare function resolveFamilySiblingUniprots(uniprotOrGeneSymbol: string): Promise<string[]>;
+/**
+ * Returns true if `chemblId` is among the supplied list of on-target ChEMBL
+ * ids for the assessment protein. Caller is responsible for resolving the
+ * list once via `resolveOnTargetChemblIds` and reusing it across rows.
+ */
+export declare function isOnTargetChemblId(chemblId: string, onTargetChemblIds: string[]): boolean;

package/dist/workflows/target-assessment/lib/target-identity-filter.js

@@ -0,0 +1,86 @@
+/**
+ * Trial-attribution classifier + UniProt-backed identity resolvers.
+ *
+ * `resolveOnTargetChemblIds` and `resolveFamilySiblingUniprots` replace the
+ * hand-curated ALTERNATE_CHEMBL_IDS and RELATED_FAMILY_UNIPROTS maps that
+ * previously lived here. Both fetch from authoritative sources at assembly
+ * time (UniProt for ChEMBL cross-references; IUPHAR Guide to Pharmacology
+ * for receptor-family siblings) so no per-target editing is needed when a
+ * new HGNC target is assessed.
+ *
+ * The actual loop-level checks (`isOnTargetChemblId` etc.) take the
+ * resolved arrays as plain inputs so the per-row assembly path stays
+ * synchronous after a single upfront await.
+ */
+import { withHost } from "../../../lib/host-concurrency.js";
+import { getFamilySiblingUniprots } from "../../../tools/lib/iuphar-client.js";
+import { getChemblIdsByUniProt } from "../../../tools/lib/uniprot-client.js";
+/**
+ * Classify how strongly a trial pertains to the assessment target based on
+ * the intervention drug's mechanism target.
+ */
+export async function classifyTrialAttribution(input) {
+    const interventionTargets = new Set();
+    for (const iv of input.interventions) {
+        if (!iv.drugChemblId)
+            continue;
+        const accs = await input.drugTargetResolver(iv.drugChemblId);
+        for (const a of accs)
+            interventionTargets.add(a);
+    }
+    const intervention_target_uniprots = [...interventionTargets];
+    const hitsAssessment = interventionTargets.has(input.assessmentUniprot);
+    const related_target_uniprots = [...interventionTargets].filter((a) => input.familyUniprots.includes(a) && a !== input.assessmentUniprot);
+    if (hitsAssessment) {
+        return { match_confidence: "high", intervention_target_uniprots, related_target_uniprots };
+    }
+    if (related_target_uniprots.length > 0) {
+        return { match_confidence: "off_target", intervention_target_uniprots, related_target_uniprots };
+    }
+    return { match_confidence: "low", intervention_target_uniprots, related_target_uniprots };
+}
+/**
+ * Resolve every ChEMBL target id that UniProt links to the given accession.
+ * The result is used as a positive list for on-target self-hit detection —
+ * a polypharm row whose off_target_id is in this list is the assessment
+ * target itself (alternate ChEMBL entry), not an off-target liability.
+ *
+ * Returns [] when the accession is missing or UniProt has no ChEMBL xrefs.
+ * Network failures are surfaced as an empty list so the assembler degrades
+ * to "no alternate-id filtering" rather than blocking the run.
+ */
+export async function resolveOnTargetChemblIds(assessmentUniprot) {
+    if (!assessmentUniprot)
+        return [];
+    try {
+        return await withHost("uniprot", () => getChemblIdsByUniProt(assessmentUniprot));
+    }
+    catch {
+        return [];
+    }
+}
+/**
+ * Resolve UniProt accessions of sibling receptors in the same IUPHAR family
+ * as the assessment target. Used by `classifyTrialAttribution` so a trial
+ * whose intervention hits a paralog (e.g., CALCRL when CALCR is the
+ * assessment target) lands in `related_target_trials[]` rather than the
+ * primary trials list.
+ */
+export async function resolveFamilySiblingUniprots(uniprotOrGeneSymbol) {
+    if (!uniprotOrGeneSymbol)
+        return [];
+    try {
+        return await withHost("iuphar", () => getFamilySiblingUniprots(uniprotOrGeneSymbol));
+    }
+    catch {
+        return [];
+    }
+}
+/**
+ * Returns true if `chemblId` is among the supplied list of on-target ChEMBL
+ * ids for the assessment protein. Caller is responsible for resolving the
+ * list once via `resolveOnTargetChemblIds` and reusing it across rows.
+ */
+export function isOnTargetChemblId(chemblId, onTargetChemblIds) {
+    return onTargetChemblIds.includes(chemblId);
+}

package/dist/workflows/target-assessment/lib/therapeutic-programs.d.ts

@@ -0,0 +1,20 @@
+import type { EvidenceItem } from "@inflexa-ai/harness/contracts/target-dossier.js";
+export type TherapeuticProgramRow = {
+    programId: string;
+    name: string;
+    targetSymbol: string;
+    targetUniprot: string | null;
+    modality: string;
+    sponsor: string | null;
+    mechanism: string;
+    status: string;
+    nctIds: string[];
+    pmids: string[];
+    evidence: EvidenceItem[];
+    confidence: "high" | "medium" | "low";
+};
+export type TherapeuticProgramTarget = {
+    geneSymbol: string;
+    uniprot: string | null;
+};
+export declare function findTherapeuticProgramsForTarget(target: TherapeuticProgramTarget): TherapeuticProgramRow[];

package/dist/workflows/target-assessment/lib/therapeutic-programs.js

@@ -0,0 +1,68 @@
+const PROGRAM_REGISTRY = [
+    {
+        programId: "AL002",
+        name: "AL002",
+        targetSymbol: "TREM2",
+        targetUniprot: "Q9NZC2",
+        modality: "agonistic monoclonal antibody",
+        sponsor: "Alector",
+        mechanism: "TREM2 agonistic antibody intended to activate microglial TREM2 signaling",
+        status: "Phase 2 completed; negative efficacy result reported",
+        nctIds: ["NCT03635047", "NCT04592874"],
+        pmids: ["39444037", "41787076"],
+        confidence: "high",
+        evidence: [
+            {
+                source: "pubmed",
+                pmid: "39444037",
+                predicate: "phase_1_target_engagement",
+                is_human: true,
+                is_clinical: true,
+            },
+            {
+                source: "pubmed",
+                pmid: "41787076",
+                predicate: "phase_2_negative_trial",
+                is_human: true,
+                is_clinical: true,
+            },
+            {
+                source: "clinicaltrials.gov",
+                predicate: "registered_trial",
+                metadata: { nct_ids: ["NCT03635047", "NCT04592874"] },
+                is_human: true,
+                is_clinical: true,
+            },
+        ],
+    },
+    {
+        programId: "VHB937",
+        name: "VHB937",
+        targetSymbol: "TREM2",
+        targetUniprot: "Q9NZC2",
+        modality: "TREM2-stabilizing monoclonal antibody",
+        sponsor: "Novartis",
+        mechanism: "TREM2 antibody program in early Alzheimer disease",
+        status: "Phase 2 recruiting",
+        nctIds: ["NCT07094516"],
+        pmids: [],
+        confidence: "medium",
+        evidence: [
+            {
+                source: "clinicaltrials.gov",
+                predicate: "registered_trial",
+                metadata: { nct_ids: ["NCT07094516"] },
+                is_human: true,
+                is_clinical: true,
+            },
+        ],
+    },
+];
+export function findTherapeuticProgramsForTarget(target) {
+    const symbol = target.geneSymbol.toUpperCase();
+    return PROGRAM_REGISTRY.filter((program) => {
+        if (program.targetSymbol.toUpperCase() === symbol)
+            return true;
+        return Boolean(target.uniprot && program.targetUniprot === target.uniprot);
+    });
+}

package/dist/workflows/target-assessment/metrics.d.ts

@@ -0,0 +1,21 @@
+/**
+ * OpenTelemetry counters for the target-assessment DBOS workflow.
+ *
+ * Surfaces three signals:
+ *  - `cortex.harness.ta.workflow.terminal_reason` — per terminal path; the
+ *    alert in §16.5/§16.6 reads this. `reason` ∈ {completed,
+ *    target-unresolved, schema-violation, derived-invariant-violation,
+ *    unexpected-throw, suspended-on-402, operator-cancelled}.
+ *  - `cortex.harness.ta.llm.attempts` — histogram per LLM step (caller
+ *    samples on entry to detect probe-retry loops).
+ *  - billing cache_hit/_miss live in `harness/billing/target-assessment-resolver.ts`.
+ *
+ * Memoised meter so a re-imported module in tests doesn't recreate the
+ * instruments against the same MeterProvider (which would log noisy
+ * "duplicate instrument" warnings).
+ */
+export type TaTerminalReason = "completed" | "target-unresolved" | "schema-violation" | "derived-invariant-violation" | "unexpected-throw" | "suspended-on-402" | "operator-cancelled" | "deleted";
+/** Test hook — drop memoised instruments to rebind a fresh MeterProvider. */
+export declare function __resetTaWorkflowMetricsForTest(): void;
+export declare function recordTerminalReason(reason: TaTerminalReason): void;
+export declare function recordLlmAttempt(agentId: string, attempt: number): void;

package/dist/workflows/target-assessment/metrics.js

@@ -0,0 +1,42 @@
+/**
+ * OpenTelemetry counters for the target-assessment DBOS workflow.
+ *
+ * Surfaces three signals:
+ *  - `cortex.harness.ta.workflow.terminal_reason` — per terminal path; the
+ *    alert in §16.5/§16.6 reads this. `reason` ∈ {completed,
+ *    target-unresolved, schema-violation, derived-invariant-violation,
+ *    unexpected-throw, suspended-on-402, operator-cancelled}.
+ *  - `cortex.harness.ta.llm.attempts` — histogram per LLM step (caller
+ *    samples on entry to detect probe-retry loops).
+ *  - billing cache_hit/_miss live in `harness/billing/target-assessment-resolver.ts`.
+ *
+ * Memoised meter so a re-imported module in tests doesn't recreate the
+ * instruments against the same MeterProvider (which would log noisy
+ * "duplicate instrument" warnings).
+ */
+import { metrics } from "@opentelemetry/api";
+let _instruments;
+function getInstruments() {
+    if (_instruments === undefined) {
+        const meter = metrics.getMeter("cortex.harness.ta");
+        _instruments = {
+            terminalReason: meter.createCounter("cortex.harness.ta.workflow.terminal_reason", {
+                description: "TA workflow terminal dispatches by reason (alert source)",
+            }),
+            llmAttempts: meter.createHistogram("cortex.harness.ta.llm.attempts", {
+                description: "TA LLM step attempt count per call site",
+            }),
+        };
+    }
+    return _instruments;
+}
+/** Test hook — drop memoised instruments to rebind a fresh MeterProvider. */
+export function __resetTaWorkflowMetricsForTest() {
+    _instruments = undefined;
+}
+export function recordTerminalReason(reason) {
+    getInstruments().terminalReason.add(1, { reason });
+}
+export function recordLlmAttempt(agentId, attempt) {
+    getInstruments().llmAttempts.record(attempt, { agent_id: agentId });
+}