@inflexa-ai/harness 0.13.0 → 0.14.0

package/dist/tools/bio/comptox.js

@@ -31,48 +31,50 @@ const inputSchema = z
     .object({
     dataset: z
         .enum(["toxcast", "hazard", "chemical", "exposure"])
-        .describe("Which CompTox dataset to query. " +
-        "'toxcast' — ToxCast/Tox21 in-vitro high-throughput screening; profiles toxicological liability across hundreds of assay endpoints (nuclear receptors, stress response, " +
-        "mitochondrial toxicity), e.g. 'is this compound an endocrine disruptor?'. Returns the resolved chemical plus assay results — endpoint name, AC50, hit call, sorted by " +
-        "AC50 ascending — alongside totalAssays, activeAssays and activeHitRate, which always describe the full tested panel rather than the returned slice. " +
-        "'hazard' — ToxValDB / ToxRefDB IN-VIVO hazard: the points of departure a safety evaluation rests on. Returns dose-response rows (toxvalType such as NOAEL/LOAEL/LD50/BMD, " +
-        "with value, units, study type and duration, species, exposure route, effect), genotoxicity assay summaries, and cancer classifications. " +
-        "'chemical' — identity and physicochemical property profile from the CompTox Chemicals Dashboard, and the way to obtain the DTXSID the other datasets key off. Returns " +
-        "DTXSID, CASRN, SMILES, InChIKey, formula and mass, plus (unless includeProperties is false) experimental and predicted property summaries — logP, water solubility, " +
-        "vapor pressure, melting/boiling point, bioconcentration factor, Henry's law constant. " +
-        "'exposure' — the exposure half of a risk assessment (e.g. pairing a ToxCast AC50 against predicted exposure for a bioactivity-exposure ratio). Returns SEEM predictions " +
-        "(production volume and per-pathway exposure probabilities — dietary, residential, pesticide, industrial; NOT a daily-intake dose), HTTK toxicokinetic parameters, " +
-        "reported functional-use categories, and consumer-product composition."),
+        .describe("Which CompTox dataset to query; each names its return fields.\n" +
+        "'toxcast' — ToxCast/Tox21 in-vitro HTS across hundreds of endpoints (nuclear receptors, stress response, mitochondrial toxicity): 'is " +
+        "this an endocrine disruptor?'. → the resolved chemical plus assay rows (endpoint, AC50, hit call; AC50 ascending), and totalAssays / " +
+        "activeAssays / activeHitRate, which always describe the FULL tested panel, not the returned slice.\n" +
+        "'hazard' — ToxValDB / ToxRefDB IN-VIVO hazard: the points of departure a safety evaluation rests on. → dose-response rows (toxvalType " +
+        "NOAEL/LOAEL/LD50/BMD with value, units, study type and duration, species, route, effect), genotoxicity summaries, cancer classifications.\n" +
+        "'chemical' — identity and physicochemical profile, and the way to get the DTXSID the other datasets key off. → DTXSID, CASRN, SMILES, " +
+        "InChIKey, formula, mass, plus (unless includeProperties is false) experimental and predicted properties — logP, water solubility, vapor " +
+        "pressure, melting/boiling point, bioconcentration factor, Henry's law constant.\n" +
+        "'exposure' — the exposure half of a risk assessment (e.g. an AC50 against predicted exposure for a bioactivity-exposure ratio). → SEEM " +
+        "predictions (production volume and per-pathway probabilities: dietary, residential, pesticide, industrial — NOT a daily-intake dose), " +
+        "HTTK toxicokinetic parameters, reported functional uses, consumer-product composition."),
     query: z
         .string()
-        .describe("Chemical identifier (all datasets). A DTXSID (e.g. 'DTXSID7020182') is used directly with no lookup; a CASRN (e.g. '80-05-7'), a chemical name (e.g. 'bisphenol A'), " +
-        "or — for dataset 'chemical' — an InChIKey is resolved by EXACT match, so a non-canonical or misspelled name yields found: false."),
+        .describe("Chemical identifier (all datasets). A DTXSID ('DTXSID7020182') is used directly; a CASRN ('80-05-7'), a name ('bisphenol A'), or — for " +
+        "dataset 'chemical' — an InChIKey is resolved by EXACT match, so a non-canonical or misspelled name yields found: false."),
     dataType: z
         .enum(["toxval", "genetox", "cancer", "seem", "httk", "functional-use", "product-data", "all"])
         .optional()
-        .describe("Which sections to fetch — datasets 'hazard' and 'exposure' only; ignored by 'toxcast' and 'chemical', which each return one dataset. Default 'all'. " +
-        "For dataset 'hazard': 'toxval' (ToxValDB dose-response values — NOAELs, LOAELs, LD50s, BMDs), 'genetox' (genotoxicity assay summaries), 'cancer' (cancer " +
-        "classifications — IARC/EPA/NTP and similar), or 'all'. " +
-        "For dataset 'exposure': 'seem' (SEEM exposure-pathway predictions and production volume), 'httk' (high-throughput toxicokinetic parameters — clearance, Css, protein " +
-        "binding, …), 'functional-use' (reported chemical use categories), 'product-data' (consumer-product composition), or 'all'. " +
-        "'all' fetches every section of that dataset concurrently."),
+        .describe("Which sections to fetch — datasets 'hazard' and 'exposure' only, ignored by the single-dataset 'toxcast' and 'chemical'. Default 'all', " +
+        "which fetches every section of that dataset concurrently. " +
+        "'hazard': 'toxval' (dose-response — NOAELs, LOAELs, LD50s, BMDs), 'genetox' (genotoxicity summaries), 'cancer' (IARC/EPA/NTP-style " +
+        "classifications). " +
+        "'exposure': 'seem' (exposure-pathway predictions + production volume), 'httk' (toxicokinetics — clearance, Css, protein binding), " +
+        "'functional-use' (reported use categories), 'product-data' (consumer-product composition)."),
     activeOnly: z
         .boolean()
         .optional()
-        .describe("Dataset 'toxcast' only. Default true — return only hit (active) assays. Set false for the whole tested panel including inactives, needed to judge selectivity or a low hit rate."),
+        .describe("'toxcast' only. Default true — hit (active) assays only. False for the whole tested panel including inactives, needed to judge selectivity " +
+        "or a low hit rate."),
     includeProperties: z
         .boolean()
         .optional()
-        .describe("Dataset 'chemical' only. Default true — also fetch the experimental/predicted property summaries. Set false to skip that second call when only identity and mass are needed."),
+        .describe("'chemical' only. Default true — also fetch experimental/predicted properties. False skips that second call when only identity and mass are needed."),
     limit: z
         .number()
         .int()
         .min(1)
         .max(200)
         .optional()
-        .describe("Max rows returned; ignored by dataset 'chemical'. Defaults and ceilings differ per dataset: 'toxcast' default 50, max 200, applied after the activeOnly filter; " +
-        "'hazard' default 30, max 100, applied to toxval and genetox only — cancer ALWAYS returns every row; 'exposure' default 25, max 100, applied to functional-use and " +
-        "product-data only — seem and httk are ALWAYS returned whole."),
+        .describe("Max rows; ignored by 'chemical'. Per dataset: 'toxcast' default 25 / max 200, applied after activeOnly and AC50-ascending so the default " +
+        "keeps the most potent hits; 'hazard' default 30 / max 100, applied to toxval and genetox only — cancer always returns every row (only " +
+        "ever a handful); 'exposure' default 25 / max 100, applied to functional-use and product-data only — seem is one record and httk a short " +
+        "parameter list, both returned whole."),
 })
     .refine((d) => (d.dataset !== "toxcast" && d.dataset !== "chemical") || d.dataType === undefined || d.dataType === "all", {
     message: "dataType applies only to dataset 'hazard' (toxval | genetox | cancer) and dataset 'exposure' (seem | httk | functional-use | product-data) — " +
@@ -96,13 +98,13 @@ const inputSchema = z
 export function createComptoxTool(deps) {
     return defineTool({
         id: "comptox",
-        description: "Query EPA's CompTox (CTX) chemical-safety databases — pick the dataset with `dataset`: 'toxcast' (in-vitro HTS bioactivity), 'hazard' (in-vivo hazard: NOAEL/LOAEL/LD50, " +
-            "genotoxicity, cancer classifications), 'chemical' (identity + physicochemical/ADMET properties), 'exposure' (SEEM exposure predictions, toxicokinetics, uses, products). " +
-            "See `dataset` for what each returns. Every dataset resolves the same `query` (DTXSID, CASRN, or exact chemical name) to a DTXSID first. " +
-            "Requires EPA_CCTE_API_KEY — a missing key fails the call terminally: do NOT retry, tell the user the key needs configuring and proceed without EPA data. " +
-            "found: false means the query did not resolve to a chemical — valid no-data, do not retry the same string; a present-but-empty section is likewise valid no-data. " +
-            "This is environmental/industrial-chemical safety data: for drug-like compounds prefer the PubChem or ChEMBL tools — dataset 'chemical' returns `detail.pubchemCid`, which " +
-            "bridges back to them.",
+        description: "EPA's CompTox (CTX) chemical-safety databases — four datasets behind `dataset`: 'toxcast' (in-vitro HTS bioactivity), 'hazard' (in-vivo: " +
+            "NOAEL/LOAEL/LD50, genotoxicity, cancer), 'chemical' (identity + physicochemical/ADMET), 'exposure' (SEEM predictions, toxicokinetics, uses, " +
+            "products). See `dataset` for what each returns; all four resolve `query` to a DTXSID first.\n" +
+            "Requires EPA_CCTE_API_KEY — a missing key fails terminally: do NOT retry, tell the user the key needs configuring and proceed without EPA data.\n" +
+            "found: false means the query did not resolve to a chemical; a present-but-empty section is likewise valid no-data. Do not retry either.\n" +
+            "This is environmental/industrial-chemical data: for drug-like compounds prefer PubChem or ChEMBL — dataset 'chemical' returns " +
+            "`detail.pubchemCid` to bridge back.",
         inputSchema,
         execute: async (input) => {
             const headers = getEpaCcteHeaders(deps.apiKey);
@@ -115,7 +117,7 @@ export function createComptoxTool(deps) {
                 case "toxcast": {
                     const bioactivity = await fetchToxcastBioactivity(dtxsid, headers, {
                         activeOnly: input.activeOnly ?? true,
-                        limit: input.limit ?? 50,
+                        limit: input.limit ?? 25,
                     });
                     return ok({ found: true, chemical: { dtxsid, preferredName, casrn, ...bioactivity } });
                 }

package/dist/tools/bio/drug-gene-interactions.d.ts

@@ -0,0 +1,76 @@
+/**
+ * drugGeneInteractions — one tool over the three drug↔gene corpora: DGIdb,
+ * DrugBank, and PharmGKB.
+ *
+ * These were three tools with the same input skeleton (`query` + a gene/drug
+ * discriminator + `limit`) answering one question in two directions: what drugs
+ * hit this gene, and what genes does this drug act on. DGIdb *aggregates* the
+ * other two (it names ChEMBL, DrugBank, PharmGKB and GuideToPharmacology among
+ * its 30+ sources), so the choice between them was never a routing decision —
+ * it is coverage, and it rides in `sources`.
+ *
+ * Unlike `gene_disease_evidence`, the default here is the AGGREGATOR ALONE:
+ * DGIdb already covers what the other two hold, so fanning out by default would
+ * mostly return the same interactions three times.
+ *
+ * Each source runs independently and reports its own outcome in `perSource`, so
+ * a missing DrugBank key degrades that corpus rather than the whole call.
+ */
+import type { Logger } from "../../lib/logger.js";
+import { type DgidbResult } from "../lib/dgidb-client.js";
+import { type DrugResult } from "../lib/drugbank-client.js";
+import { type PharmgkbAnnotation } from "../lib/pharmgkb-client.js";
+declare const SOURCES: readonly ["dgidb", "drugbank", "pharmgkb"];
+type Source = (typeof SOURCES)[number];
+interface SourceOutcome {
+    source: Source;
+    status: "ok" | "no_data" | "unavailable";
+    returned: number;
+    detail?: string;
+}
+/**
+ * A DrugBank record projected for context. `includeDrugRecord` decides whether
+ * the five prose fields arrive whole or as previews — five 500-character fields
+ * across ten records is 25k characters of narrative that a drug-vs-gene
+ * question rarely needs.
+ */
+interface ProjectedDrug {
+    drugbankId: string;
+    name: string;
+    type: string;
+    groups: string[];
+    categories: string[];
+    halfLife: string;
+    targets: DrugResult["targets"];
+    targetCount: number;
+    interactions: DrugResult["interactions"];
+    interactionCount: number;
+    description: string;
+    indication: string;
+    pharmacodynamics: string;
+    mechanismOfAction: string;
+    toxicity: string;
+    proseTruncated: boolean;
+}
+interface DrugGeneOutput {
+    direction: "gene_to_drugs" | "drug_to_genes";
+    perSource: SourceOutcome[];
+    dgidb?: DgidbResult[];
+    drugbank?: ProjectedDrug[];
+    pharmgkb?: PharmgkbAnnotation[];
+}
+export declare function createDrugGeneInteractionsTool(deps: {
+    drugbankApiKey: string;
+    logger?: Logger;
+}): import("../define-tool.js").Tool<{
+    query: string | string[];
+    direction: "gene_to_drugs" | "drug_to_genes";
+    sources?: ("dgidb" | "drugbank" | "pharmgkb")[] | undefined;
+    limit?: number | undefined;
+    interactionTypes?: string[] | undefined;
+    sourceDbs?: string[] | undefined;
+    minSources?: number | undefined;
+    includeAttributes?: boolean | undefined;
+    includeDrugRecord?: boolean | undefined;
+}, DrugGeneOutput>;
+export {};

package/dist/tools/bio/drug-gene-interactions.js

@@ -0,0 +1,175 @@
+/**
+ * drugGeneInteractions — one tool over the three drug↔gene corpora: DGIdb,
+ * DrugBank, and PharmGKB.
+ *
+ * These were three tools with the same input skeleton (`query` + a gene/drug
+ * discriminator + `limit`) answering one question in two directions: what drugs
+ * hit this gene, and what genes does this drug act on. DGIdb *aggregates* the
+ * other two (it names ChEMBL, DrugBank, PharmGKB and GuideToPharmacology among
+ * its 30+ sources), so the choice between them was never a routing decision —
+ * it is coverage, and it rides in `sources`.
+ *
+ * Unlike `gene_disease_evidence`, the default here is the AGGREGATOR ALONE:
+ * DGIdb already covers what the other two hold, so fanning out by default would
+ * mostly return the same interactions three times.
+ *
+ * Each source runs independently and reports its own outcome in `perSource`, so
+ * a missing DrugBank key degrades that corpus rather than the whole call.
+ */
+import { ok } from "neverthrow";
+import { z } from "zod";
+import { createNoopLogger } from "../../lib/console-logger.js";
+import { defineTool } from "../define-tool.js";
+import { searchDgidb } from "../lib/dgidb-client.js";
+import { searchDrugbank } from "../lib/drugbank-client.js";
+import { searchPharmgkb } from "../lib/pharmgkb-client.js";
+const SOURCES = ["dgidb", "drugbank", "pharmgkb"];
+const DEFAULT_LIMIT = 20;
+const MAX_LIMIT = 200;
+const MAX_INPUTS = 25;
+/** Prose kept per DrugBank field when the full record is not requested. */
+const PROSE_PREVIEW_CHARS = 200;
+/** Targets and interactions kept per DrugBank record. */
+const MAX_DRUG_TARGETS = 10;
+const MAX_DRUG_INTERACTIONS = 10;
+const inputSchema = z.object({
+    query: z
+        .union([z.string().min(1), z.array(z.string().min(1)).min(1).max(MAX_INPUTS)])
+        .describe(`One identifier or up to ${MAX_INPUTS} — batch rather than calling per identifier. 'gene_to_drugs': HUGO symbols. 'drug_to_genes': drug ` +
+        "names, DrugBank IDs (DB00619), or DGIdb concept IDs. Only 'dgidb' batches; the others read the FIRST and report the rest as skipped."),
+    direction: z
+        .enum(["gene_to_drugs", "drug_to_genes"])
+        .describe("'gene_to_drugs' — what drugs act on these genes ('what is druggable in my gene set?'). 'drug_to_genes' — what genes these drugs act on " +
+        "(target deconvolution, polypharmacology)."),
+    sources: z
+        .array(z.enum(SOURCES))
+        .min(1)
+        .optional()
+        .describe("Corpora to query in parallel. Default ['dgidb'] ALONE — it aggregates the other two, so add them only for what they uniquely hold. " +
+        "'dgidb': 30+ aggregated sources, per-interaction source count as confidence; the only one that batches. " +
+        "'drugbank': the curated drug RECORD (indication, pharmacodynamics, mechanism, toxicity, half-life, DDIs); needs DRUGBANK_API_KEY. " +
+        "'pharmgkb': pharmacogenomic annotations graded 1A…4 (1A guideline-backed); exact match only — 'CYP2D6' resolves, 'cytochrome P450 2D6' does not."),
+    limit: z
+        .number()
+        .int()
+        .min(1)
+        .max(MAX_LIMIT)
+        .optional()
+        .describe(`Max records per identifier per source (default ${DEFAULT_LIMIT}, max ${MAX_LIMIT}). DGIdb rows are ordered by source count descending; ` +
+        "`totalInteractions` gives the pre-trim count."),
+    interactionTypes: z.array(z.string()).optional().describe("'dgidb' only. Case-insensitive substring filter on interaction type, e.g. ['inhibitor']."),
+    sourceDbs: z.array(z.string()).optional().describe("'dgidb' only. Keep only interactions from these underlying databases (substring), e.g. ['chembl']."),
+    minSources: z.number().int().min(1).optional().describe("'dgidb' only. Drop interactions with fewer than this many supporting sources; default 1."),
+    includeAttributes: z
+        .boolean()
+        .optional()
+        .describe("'dgidb' only. Default FALSE — attributes are verbose free-text pairs. True only when you need the assay detail, not the interaction's existence."),
+    includeDrugRecord: z
+        .boolean()
+        .optional()
+        .describe(`'drugbank' only. Default FALSE — the five prose fields come back as ${PROSE_PREVIEW_CHARS}-char previews with proseTruncated: true. ` +
+        "True for full text; narrow `limit` when you do."),
+});
+function projectDrug(drug, includeFullProse) {
+    const prose = (value) => (includeFullProse ? value : value.slice(0, PROSE_PREVIEW_CHARS));
+    return {
+        drugbankId: drug.drugbankId,
+        name: drug.name,
+        type: drug.type,
+        groups: drug.groups,
+        categories: drug.categories,
+        halfLife: drug.halfLife,
+        targets: drug.targets.slice(0, MAX_DRUG_TARGETS),
+        targetCount: drug.targets.length,
+        interactions: drug.interactions.slice(0, MAX_DRUG_INTERACTIONS),
+        interactionCount: drug.interactions.length,
+        description: prose(drug.description),
+        indication: prose(drug.indication),
+        pharmacodynamics: prose(drug.pharmacodynamics),
+        mechanismOfAction: prose(drug.mechanismOfAction),
+        toxicity: prose(drug.toxicity),
+        proseTruncated: !includeFullProse,
+    };
+}
+/**
+ * Run one corpus, folding its failure into an `unavailable` outcome so a dead
+ * or unkeyed source cannot take down a call the others could answer.
+ */
+async function runSource(source, fetch) {
+    try {
+        const records = await fetch();
+        return { outcome: { source, status: records.length > 0 ? "ok" : "no_data", returned: records.length }, records };
+    }
+    catch (error) {
+        return {
+            outcome: { source, status: "unavailable", returned: 0, detail: error instanceof Error ? error.message : String(error) },
+            records: [],
+        };
+    }
+}
+export function createDrugGeneInteractionsTool(deps) {
+    const logger = (deps.logger ?? createNoopLogger()).named("drug_gene_interactions");
+    return defineTool({
+        id: "drug_gene_interactions",
+        description: "Drug↔gene interactions across DGIdb, DrugBank and PharmGKB, in one call — 'what drugs hit these genes?' and 'what genes does this drug act " +
+            "on?'. See `direction` and `sources` for the modes.\n" +
+            "It answers whether an interaction is KNOWN, by whom, and of what type. For quotable POTENCY (IC50/Ki) use chembl({action:'bioactivity'}) instead.\n" +
+            "Verbose fields (`includeAttributes`, `includeDrugRecord`) are off by default — both cost a lot of context and are rarely what the question needs.\n" +
+            "ALWAYS read `perSource` before concluding an interaction is unknown: 'no_data' means that corpus has nothing; 'unavailable' means it could " +
+            "not be reached (a missing DRUGBANK_API_KEY lands here — tell the user and proceed with DGIdb). A `found: false` entry means the identifier " +
+            "is not in DGIdb at all, usually a non-HUGO symbol or a brand name. Neither is worth retrying unchanged.",
+        inputSchema,
+        execute: async (input) => {
+            const inputs = typeof input.query === "string" ? [input.query] : input.query;
+            const selected = input.sources ?? ["dgidb"];
+            const limit = input.limit ?? DEFAULT_LIMIT;
+            const isGeneSide = input.direction === "gene_to_drugs";
+            const output = { direction: input.direction, perSource: [] };
+            const [dgidb, drugbank, pharmgkb] = await Promise.all([
+                selected.includes("dgidb")
+                    ? runSource("dgidb", () => searchDgidb(inputs, isGeneSide ? "gene" : "drug", {
+                        limit,
+                        ...(input.interactionTypes ? { interactionTypes: input.interactionTypes } : {}),
+                        ...(input.sourceDbs ? { sourceDbs: input.sourceDbs } : {}),
+                        ...(input.minSources !== undefined ? { minSources: input.minSources } : {}),
+                        ...(input.includeAttributes !== undefined ? { includeAttributes: input.includeAttributes } : {}),
+                    }, (errors) => logger.warn("dgidb partial errors alongside data", { errors })))
+                    : null,
+                selected.includes("drugbank")
+                    ? runSource("drugbank", async () => {
+                        if (!deps.drugbankApiKey)
+                            throw new Error("DRUGBANK_API_KEY is not configured");
+                        const drugs = await searchDrugbank(deps.drugbankApiKey, inputs[0], isGeneSide ? "target" : "drug", limit);
+                        return drugs.map((d) => projectDrug(d, input.includeDrugRecord ?? false));
+                    })
+                    : null,
+                selected.includes("pharmgkb")
+                    ? runSource("pharmgkb", async () => {
+                        const res = await searchPharmgkb(inputs[0], isGeneSide ? "gene" : "drug", limit);
+                        return res.annotations;
+                    })
+                    : null,
+            ]);
+            // DrugBank and PharmGKB take one identifier per call; say so on the
+            // outcome rather than letting the extra inputs vanish silently.
+            const skipped = inputs.length > 1 ? `read only '${inputs[0]}' — this source takes one identifier per call` : "";
+            const noteSkipped = (outcome) => {
+                const detail = [outcome.detail, skipped].filter(Boolean).join("; ");
+                return detail ? { ...outcome, detail } : outcome;
+            };
+            if (dgidb) {
+                output.perSource.push(dgidb.outcome);
+                output.dgidb = dgidb.records;
+            }
+            if (drugbank) {
+                output.perSource.push(noteSkipped(drugbank.outcome));
+                output.drugbank = drugbank.records;
+            }
+            if (pharmgkb) {
+                output.perSource.push(noteSkipped(pharmgkb.outcome));
+                output.pharmgkb = pharmgkb.records;
+            }
+            return ok(output);
+        },
+    });
+}

package/dist/tools/bio/gene-disease-evidence.d.ts

@@ -0,0 +1,61 @@
+/**
+ * geneDiseaseEvidence — one tool over the three gene↔disease evidence corpora:
+ * the NHGRI-EBI GWAS Catalog, DisGeNET, and NCBI ClinVar.
+ *
+ * These were three tools with the same input skeleton (`query` + a
+ * gene/disease/variant discriminator + a strength threshold + `limit`)
+ * answering the same question — what genetic evidence links this gene to this
+ * disease or trait. Picking between them was never a routing decision an agent
+ * should spend a turn on; it is corpus coverage, so it rides in `sources` and
+ * defaults to all of them. `search_pathway`'s `source: kegg | reactome | both`
+ * is the same shape.
+ *
+ * Each source runs independently and reports its own outcome in `perSource`: a
+ * missing DisGeNET key or a GWAS Catalog outage degrades that one corpus to
+ * `unavailable` instead of failing a call the other two could have answered.
+ *
+ * The input is a flat object with a `queryType` discriminator — not a
+ * `z.discriminatedUnion`, which `defineTool` rejects (model tool calling needs
+ * a top-level `"type":"object"`).
+ */
+import { type ClinvarVariant } from "../lib/clinvar-client.js";
+import { type Gda } from "../lib/disgenet-client.js";
+import { type GwasAssociation } from "../lib/gwas-catalog-client.js";
+declare const SOURCES: readonly ["gwas", "disgenet", "clinvar"];
+type Source = (typeof SOURCES)[number];
+/**
+ * Per-source outcome. `unavailable` (key absent, corpus erroring) and
+ * `not_applicable` (the corpus has no lookup for this queryType) are both
+ * normal states the caller must be able to tell apart from genuine no-data —
+ * otherwise an unkeyed DisGeNET reads as "no genetic support".
+ */
+interface SourceOutcome {
+    source: Source;
+    status: "ok" | "no_data" | "unavailable" | "not_applicable";
+    returned: number;
+    totalFound?: number;
+    detail?: string;
+}
+interface GeneDiseaseEvidenceOutput {
+    query: string;
+    queryType: "gene" | "disease" | "variant";
+    perSource: SourceOutcome[];
+    gwas?: GwasAssociation[];
+    disgenet?: Gda[];
+    clinvar?: ClinvarVariant[];
+}
+export declare function createGeneDiseaseEvidenceTool(deps: {
+    ncbiApiKey?: string;
+    disgenetApiKey: string;
+}): import("../define-tool.js").Tool<{
+    query: string;
+    queryType: "gene" | "disease" | "variant";
+    sources?: ("clinvar" | "gwas" | "disgenet")[] | undefined;
+    limit?: number | undefined;
+    pValueThreshold?: number | undefined;
+    minScore?: number | undefined;
+    disgenetSource?: "ALL" | "CURATED" | "ANIMAL_MODELS" | "BEFREE" | undefined;
+    clinicalSignificance?: "pathogenic" | "likely-pathogenic" | "benign" | "likely-benign" | "uncertain" | undefined;
+    informativeOnly?: boolean | undefined;
+}, GeneDiseaseEvidenceOutput>;
+export {};

package/dist/tools/bio/gene-disease-evidence.js

@@ -0,0 +1,187 @@
+/**
+ * geneDiseaseEvidence — one tool over the three gene↔disease evidence corpora:
+ * the NHGRI-EBI GWAS Catalog, DisGeNET, and NCBI ClinVar.
+ *
+ * These were three tools with the same input skeleton (`query` + a
+ * gene/disease/variant discriminator + a strength threshold + `limit`)
+ * answering the same question — what genetic evidence links this gene to this
+ * disease or trait. Picking between them was never a routing decision an agent
+ * should spend a turn on; it is corpus coverage, so it rides in `sources` and
+ * defaults to all of them. `search_pathway`'s `source: kegg | reactome | both`
+ * is the same shape.
+ *
+ * Each source runs independently and reports its own outcome in `perSource`: a
+ * missing DisGeNET key or a GWAS Catalog outage degrades that one corpus to
+ * `unavailable` instead of failing a call the other two could have answered.
+ *
+ * The input is a flat object with a `queryType` discriminator — not a
+ * `z.discriminatedUnion`, which `defineTool` rejects (model tool calling needs
+ * a top-level `"type":"object"`).
+ */
+import { ok } from "neverthrow";
+import { z } from "zod";
+import { defineTool } from "../define-tool.js";
+import { filterInformative, searchClinvar } from "../lib/clinvar-client.js";
+import { searchDisgenet } from "../lib/disgenet-client.js";
+import { searchGwasCatalog } from "../lib/gwas-catalog-client.js";
+const SOURCES = ["gwas", "disgenet", "clinvar"];
+const DEFAULT_LIMIT = 10;
+const MAX_LIMIT = 100;
+/** DisGeNET has no variant-level lookup; the other two do. */
+function applicableSources(queryType) {
+    return queryType === "variant" ? ["gwas", "clinvar"] : [...SOURCES];
+}
+const inputSchema = z.object({
+    query: z
+        .string()
+        .min(1)
+        .describe("The entity, matching `queryType`. gene: a HUGO symbol ('PCSK9'); DisGeNET also takes an Entrez ID. disease: a disease or trait name " +
+        "('LDL cholesterol'); DisGeNET also takes a UMLS CUI ('C0006142'). variant: a dbSNP rsID ('rs11591147')."),
+    queryType: z
+        .enum(["gene", "disease", "variant"])
+        .describe("'gene' — the diseases/traits associated with a gene. 'disease' — the genes associated with a disease or trait (the GWAS Catalog calls it a " +
+        "trait; this value covers both). 'variant' — one rsID; DisGeNET is skipped, having no variant-level lookup."),
+    sources: z
+        .array(z.enum(SOURCES))
+        .min(1)
+        .optional()
+        .describe("Corpora to query in parallel. Default ALL applicable — they carry different evidence types, and disagreement between them is itself informative. " +
+        "'gwas': population SNP-trait associations with effect sizes and p-values (common-variant / MR support). " +
+        "'disgenet': curated + text-mined gene-disease associations scored 0–1, broadest coverage; needs DISGENET_API_KEY. " +
+        "'clinvar': clinically classified germline variants — pathogenicity and review status; rare/Mendelian rather than common-variant."),
+    limit: z
+        .number()
+        .int()
+        .min(1)
+        .max(MAX_LIMIT)
+        .optional()
+        .describe(`Max records PER SOURCE (default ${DEFAULT_LIMIT}, max ${MAX_LIMIT}); all three sources at the default return at most ` +
+        `${DEFAULT_LIMIT * 3} records. Check each source's \`totalFound\` before raising it.`),
+    pValueThreshold: z
+        .number()
+        .positive()
+        .optional()
+        .describe("'gwas' only. P-value ceiling; default 5e-8 (genome-wide significance). Raise for suggestive hits."),
+    minScore: z.number().min(0).max(1).optional().describe("'disgenet' only. Minimum GDA score 0–1; default 0.1. Higher = stronger evidence."),
+    disgenetSource: z
+        .enum(["ALL", "CURATED", "ANIMAL_MODELS", "BEFREE"])
+        .optional()
+        .describe("'disgenet' only. Provenance filter; default 'ALL'. Prefer 'CURATED' for anything you will quote — 'BEFREE' is text-mined and noisy."),
+    clinicalSignificance: z
+        .enum(["pathogenic", "likely-pathogenic", "benign", "likely-benign", "uncertain"])
+        .optional()
+        .describe("'clinvar' only. Restrict to one pathogenicity classification; omit for all."),
+    informativeOnly: z
+        .boolean()
+        .optional()
+        .describe("'clinvar' only. Default TRUE — drop variants classified 'not provided', 'not specified' or 'reclassified', which carry no clinical signal."),
+});
+/**
+ * Run one corpus, folding its failure into an `unavailable` outcome. A source
+ * that throws must not take the others down — that is the whole reason three
+ * tools could become one without losing the ability to say "this corpus was
+ * not reachable" as distinct from "this corpus knows nothing".
+ */
+async function runSource(source, fetch) {
+    try {
+        const { records, totalFound } = await fetch();
+        return {
+            outcome: {
+                source,
+                status: records.length > 0 ? "ok" : "no_data",
+                returned: records.length,
+                ...(totalFound !== undefined ? { totalFound } : {}),
+            },
+            records,
+        };
+    }
+    catch (error) {
+        return {
+            outcome: {
+                source,
+                status: "unavailable",
+                returned: 0,
+                detail: error instanceof Error ? error.message : String(error),
+            },
+            records: [],
+        };
+    }
+}
+export function createGeneDiseaseEvidenceTool(deps) {
+    return defineTool({
+        id: "gene_disease_evidence",
+        description: "Genetic evidence linking a gene to a disease or trait, across the GWAS Catalog, DisGeNET and ClinVar in one call — 'is there human genetic " +
+            "support for this target in this indication?'. See `sources` for what each corpus carries.\n" +
+            "For the integrated, pre-scored view prefer opentargets({action:'target'}) FIRST — it folds genetic association together with tractability " +
+            "and the drug landscape. Reach here for the underlying records: actual SNPs, effect sizes, scores and pathogenicity calls with their studies and PMIDs.\n" +
+            "ALWAYS read `perSource` before concluding anything is absent. 'no_data' means that corpus genuinely has nothing; 'unavailable' means it " +
+            "could not be reached (a missing DISGENET_API_KEY lands here — tell the user and proceed with the other two); 'not_applicable' means that " +
+            "corpus has no lookup for this queryType. Only 'no_data' is evidence of absence, and none is worth retrying unchanged.",
+        inputSchema,
+        execute: async (input) => {
+            const applicable = applicableSources(input.queryType);
+            const requested = input.sources ?? applicable;
+            const selected = requested.filter((s) => applicable.includes(s));
+            const limit = input.limit ?? DEFAULT_LIMIT;
+            const output = {
+                query: input.query,
+                queryType: input.queryType,
+                perSource: requested
+                    .filter((s) => !applicable.includes(s))
+                    .map((source) => ({
+                    source,
+                    status: "not_applicable",
+                    returned: 0,
+                    detail: `${source} has no lookup for queryType '${input.queryType}'`,
+                })),
+            };
+            const [gwas, disgenet, clinvar] = await Promise.all([
+                selected.includes("gwas")
+                    ? runSource("gwas", async () => {
+                        const searchType = input.queryType === "gene" ? "gene" : input.queryType === "disease" ? "trait" : "variant";
+                        const res = await searchGwasCatalog(input.query, searchType, {
+                            limit,
+                            ...(input.pValueThreshold !== undefined ? { pValueThreshold: input.pValueThreshold } : {}),
+                        });
+                        return { records: res.associations, totalFound: res.totalFound };
+                    })
+                    : null,
+                selected.includes("disgenet")
+                    ? runSource("disgenet", async () => {
+                        if (!deps.disgenetApiKey)
+                            throw new Error("DISGENET_API_KEY is not configured");
+                        const records = await searchDisgenet(deps.disgenetApiKey, input.query, input.queryType === "gene" ? "gene" : "disease", {
+                            limit,
+                            ...(input.minScore !== undefined ? { minScore: input.minScore } : {}),
+                            ...(input.disgenetSource !== undefined ? { source: input.disgenetSource } : {}),
+                        });
+                        return { records };
+                    })
+                    : null,
+                selected.includes("clinvar")
+                    ? runSource("clinvar", async () => {
+                        const res = await searchClinvar(deps.ncbiApiKey, input.query, {
+                            limit,
+                            ...(input.clinicalSignificance !== undefined ? { clinicalSignificance: input.clinicalSignificance } : {}),
+                        });
+                        const variants = (input.informativeOnly ?? true) ? filterInformative(res.variants) : res.variants;
+                        return { records: variants, totalFound: res.totalFound };
+                    })
+                    : null,
+            ]);
+            if (gwas) {
+                output.perSource.push(gwas.outcome);
+                output.gwas = gwas.records;
+            }
+            if (disgenet) {
+                output.perSource.push(disgenet.outcome);
+                output.disgenet = disgenet.records;
+            }
+            if (clinvar) {
+                output.perSource.push(clinvar.outcome);
+                output.clinvar = clinvar.records;
+            }
+            return ok(output);
+        },
+    });
+}