@inflexa-ai/harness 0.13.0 → 0.14.1

package/dist/tools/bio/chembl.js

@@ -18,74 +18,74 @@ import { ok } from "neverthrow";
 import { z } from "zod";
 import { defineTool } from "../define-tool.js";
 import { getBioactivity, getDrugInfo, getMechanism, searchCompounds, searchTargets } from "../lib/chembl-client.js";
-/** Per-action record caps, preserved from the five tools this one replaces. */
+/**
+ * Per-action record caps. The ceilings are what the endpoints will serve; the
+ * defaults are deliberately far below them — 500 activity rows is ~125k
+ * characters, which answers no question that the top 25 by potency does not.
+ */
 const LIMITS = {
     /** `compounds` / `bioactivity` — activity-scale reads. */
-    wide: 500,
+    wideMax: 500,
+    wideDefault: 25,
     /** `drug` / `targets` — resolution reads, where a long list is noise. */
-    narrow: 25,
+    narrowMax: 25,
+    narrowDefault: 10,
 };
 const inputSchema = z
     .object({
     action: z
         .enum(["compounds", "drug", "mechanism", "bioactivity", "targets"])
-        .describe("Which ChEMBL lookup to run — each names the params it needs and the fields it returns.\n" +
-        "'compounds' (query + searchType) — molecules by target, name, or SMILES; resolves a named compound to its ChEMBL ID " +
-        "and structure, or lists the compounds assayed against a target. Returns chemblId, preferredCompoundName, " +
-        "canonicalSmiles, molecularWeight, alogp, molecularFormula.\n" +
-        "'drug' (query) — the drug registry by drug name or disease indication: 'what drugs treat X?', 'is Y approved, and " +
-        "since when?'. Returns moleculeChemblId, preferredName, maxPhase (4 = approved), moleculeType (small molecule, " +
-        "antibody, …), firstApproval year, indication. When the drug endpoint is empty it falls back to a molecule search " +
-        "filtered to max_phase >= 4; rows from that fallback carry indication: null.\n" +
-        "'mechanism' (chemblId) — the curated mechanism of action of ONE molecule: 'how does drug X work?'. Returns " +
-        "mechanismOfAction (prose), actionType (INHIBITOR, AGONIST, ANTAGONIST, …), targetChemblId + the resolved targetName, " +
-        "moleculeChemblId. ChEMBL curates mechanisms mainly for clinical/approved molecules, so tool compounds often have none.\n" +
-        "'bioactivity' (chemblId + idType) — measured activity rows (IC50, EC50, Ki, Kd, …): the curated, quotable potency " +
-        "data for a compound or a target. Returns standardType, standardValue + standardUnits, pchemblValue (normalized " +
-        "-log10 potency), assayChemblId, assayType, compoundChemblId, targetChemblId.\n" +
-        "'targets' (query) — resolve a gene symbol or protein name to a ChEMBL target: the step that produces the target ID " +
-        "used by bioactivity (idType='target') and compounds (searchType='target'). Returns targetChemblId, preferredName, " +
-        "targetType (SINGLE PROTEIN, PROTEIN COMPLEX, …), organism, geneNames. Results span organisms — check `organism` " +
-        "before using an ID, since the top hit for a human gene symbol may be a non-human ortholog."),
+        .describe("Which ChEMBL lookup to run; each names its params and return fields.\n" +
+        "'compounds' (query + searchType) — molecules by target, name or SMILES: resolve a named compound to its ID and structure, or list " +
+        "what was assayed against a target. → chemblId, preferredCompoundName, canonicalSmiles, molecularWeight, alogp, molecularFormula.\n" +
+        "'drug' (query) — the drug registry by drug name or indication: 'what treats X?', 'is Y approved, since when?'. → moleculeChemblId, " +
+        "preferredName, maxPhase (4 = approved), moleculeType, firstApproval, indication. If the drug endpoint is empty it falls back to a " +
+        "max_phase >= 4 molecule search, whose rows carry indication: null.\n" +
+        "'mechanism' (chemblId, molecule only) — curated mechanism of ONE molecule: 'how does X work?'. → mechanismOfAction, actionType " +
+        "(INHIBITOR, AGONIST, …), targetChemblId + targetName, moleculeChemblId. Curated mainly for clinical/approved molecules, so tool " +
+        "compounds often have none.\n" +
+        "'bioactivity' (chemblId + idType) — measured activity rows: the curated, QUOTABLE potency. → standardType, standardValue + " +
+        "standardUnits, pchemblValue (normalized -log10), assayChemblId, assayType, compoundChemblId, targetChemblId.\n" +
+        "'targets' (query) — resolve a gene symbol or protein name to a ChEMBL target, producing the ID that bioactivity (idType='target') " +
+        "and compounds (searchType='target') need. → targetChemblId, preferredName, targetType, organism, geneNames. Check `organism`: the " +
+        "top hit for a human symbol may be a non-human ortholog."),
     query: z
         .string()
         .min(1)
         .optional()
-        .describe("Required for 'compounds', 'drug', 'targets'. compounds: must match searchType — a target name/gene symbol or target " +
-        "ChEMBL ID, a compound name, or a SMILES string. drug: a drug name (e.g. 'imatinib') or a disease indication " +
-        "(e.g. 'melanoma'). targets: a gene symbol (e.g. 'EGFR', 'ABL1'), a protein name, or a ChEMBL target ID."),
+        .describe("Required for 'compounds', 'drug', 'targets'. compounds: must match searchType — a target name/gene symbol or target ChEMBL ID, a " +
+        "compound name, or a SMILES. drug: a drug name ('imatinib') or an indication ('melanoma'). targets: a gene symbol ('EGFR'), a " +
+        "protein name, or a ChEMBL target ID."),
     searchType: z
         .enum(["target", "compound", "smiles"])
         .optional()
-        .describe("Required for 'compounds' — how to read `query`. 'target': resolve it to a ChEMBL target, then return the compounds " +
-        "assayed against that target. 'compound': free-text search over molecule names. 'smiles': flexible (flexmatch) " +
-        "structure search on canonical SMILES."),
+        .describe("Required for 'compounds' — how to read `query`. 'target': resolve to a ChEMBL target, then return what was assayed against it. " +
+        "'compound': free-text over molecule names. 'smiles': flexmatch structure search."),
     chemblId: z
         .string()
         .min(1)
         .optional()
-        .describe("Required for 'mechanism' and 'bioactivity'. A ChEMBL molecule ID (e.g. 'CHEMBL25' = aspirin) or — for bioactivity " +
-        "with idType='target' — a target ID (e.g. 'CHEMBL203' = EGFR). 'mechanism' takes a molecule ID only, never a target ID."),
+        .describe("Required for 'mechanism' and 'bioactivity'. A molecule ID ('CHEMBL25' = aspirin), or — for bioactivity with idType='target' — a target " +
+        "ID ('CHEMBL203' = EGFR). 'mechanism' takes a molecule ID only."),
     idType: z
         .enum(["compound", "target"])
         .optional()
-        .describe("Required for 'bioactivity' — which side of the activity table `chemblId` indexes. 'compound': chemblId is a molecule " +
-        "ID; returns everything that molecule was assayed against. 'target': chemblId is a target ID; returns every compound " +
-        "assayed against that target."),
+        .describe("Required for 'bioactivity' — which side of the activity table `chemblId` indexes. 'compound': everything that molecule was assayed " +
+        "against. 'target': every compound assayed against that target."),
     activityType: z
         .string()
         .optional()
-        .describe("'bioactivity' only. Exact ChEMBL standard_type filter, e.g. 'IC50', 'EC50', 'Ki', 'Kd'. Matched exactly " +
-        "(case-sensitive); omit to get all activity types."),
+        .describe("'bioactivity' only. Exact, case-sensitive standard_type filter — 'IC50', 'EC50', 'Ki', 'Kd'. Omit for all types."),
     limit: z
         .number()
         .int()
         .min(1)
-        .max(LIMITS.wide)
+        .max(LIMITS.wideMax)
         .optional()
-        .describe(`Max records. 'compounds'/'bioactivity': 1–${LIMITS.wide} (default ${LIMITS.wide}). 'drug'/'targets': 1–${LIMITS.narrow} ` +
-        `(default ${LIMITS.narrow}). Ignored by 'mechanism'. With searchType='target' it caps the activity rows scanned, so ` +
-        `fewer unique compounds usually come back.`),
+        .describe(`Max records. 'compounds'/'bioactivity': 1–${LIMITS.wideMax} (default ${LIMITS.wideDefault}). 'drug'/'targets': 1–${LIMITS.narrowMax} ` +
+        `(default ${LIMITS.narrowDefault}). Ignored by 'mechanism'. Rows are UNSORTED, so raising this is the only way to widen the window — ` +
+        `do it to survey an SAR series or a full assay panel, not to browse. With searchType='target' it caps the activity rows scanned, so ` +
+        `fewer unique compounds come back.`),
 })
     .refine((d) => !(d.action === "compounds" || d.action === "drug" || d.action === "targets") || (d.query !== undefined && d.query.length > 0), {
     message: "query is required when action is 'compounds', 'drug', or 'targets'",
@@ -104,35 +104,32 @@ const inputSchema = z
     message: "idType is required when action is 'bioactivity' — 'compound' if chemblId is a molecule ID, 'target' if it is a target ID",
     path: ["idType"],
 })
-    .refine((d) => !(d.action === "drug" || d.action === "targets") || d.limit === undefined || d.limit <= LIMITS.narrow, {
-    message: `limit is capped at ${LIMITS.narrow} for action 'drug' and 'targets' (only 'compounds' and 'bioactivity' reach ${LIMITS.wide})`,
+    .refine((d) => !(d.action === "drug" || d.action === "targets") || d.limit === undefined || d.limit <= LIMITS.narrowMax, {
+    message: `limit is capped at ${LIMITS.narrowMax} for action 'drug' and 'targets' (only 'compounds' and 'bioactivity' reach ${LIMITS.wideMax})`,
     path: ["limit"],
 });
 export const chemblTool = defineTool({
     id: "chembl",
-    description: "ChEMBL — the manually curated database of drug-like bioactives (~2.4M compounds), the targets they were measured " +
-        "against, their mechanisms, and their approval status. One tool, five lookups; pick with `action` (its description gives " +
-        "each action's params and return fields).\n" +
-        "IDs are resolved, never guessed: a `chemblId` comes from a prior action='compounds'/'drug' (molecule IDs) or action='targets' " +
-        "(target IDs) call, or from pubchem action='crossrefs' — a compound or gene name is not a ChEMBL ID.\n" +
-        "ChEMBL is curated, so prefer it over PubChem for anything you will quote or build on: use action='bioactivity' rather than " +
-        "pubchem action='assays' whenever you will quote a number (PubChem assay summaries are broader HTS screening outcomes), and resolve " +
-        "compounds here first. If ChEMBL does not find the compound, resolve it in PubChem with pubchem action='compound' and bridge back " +
-        "to a ChEMBL ID via pubchem action='crossrefs'.\n" +
-        "An empty array is a valid 'no match' / no-data answer, not an error — do not retry the same call.",
+    description: "ChEMBL — the manually curated database of drug-like bioactives (~2.4M compounds), the targets they were measured against, their mechanisms and " +
+        "their approval status. Five lookups; pick with `action`, which gives each one's params and return fields.\n" +
+        "IDs are resolved, never guessed: a `chemblId` comes from a prior action='compounds'/'drug' (molecules) or action='targets' (targets), or from " +
+        "pubchem action='crossrefs'. A compound or gene name is not a ChEMBL ID.\n" +
+        "Being curated, ChEMBL is what you quote from: prefer action='bioactivity' over pubchem action='assays' for any number you will cite, and resolve " +
+        "compounds here first. If ChEMBL misses the compound, resolve it via pubchem action='compound' and bridge back with pubchem action='crossrefs'.\n" +
+        "An empty array is valid no-data, not an error — do not retry the same call.",
     inputSchema,
     execute: async ({ action, query, searchType, chemblId, idType, activityType, limit }) => {
         switch (action) {
             case "compounds":
-                return ok({ compounds: await searchCompounds(query, searchType, limit ?? LIMITS.wide) });
+                return ok({ compounds: await searchCompounds(query, searchType, limit ?? LIMITS.wideDefault) });
             case "drug":
-                return ok({ drugs: await getDrugInfo(query, limit ?? LIMITS.narrow) });
+                return ok({ drugs: await getDrugInfo(query, limit ?? LIMITS.narrowDefault) });
             case "mechanism":
                 return ok({ mechanisms: await getMechanism(chemblId) });
             case "bioactivity":
-                return ok({ activities: await getBioactivity(chemblId, idType, { activityType, limit: limit ?? LIMITS.wide }) });
+                return ok({ activities: await getBioactivity(chemblId, idType, { activityType, limit: limit ?? LIMITS.wideDefault }) });
             case "targets":
-                return ok({ targets: await searchTargets(query, limit ?? LIMITS.narrow) });
+                return ok({ targets: await searchTargets(query, limit ?? LIMITS.narrowDefault) });
         }
     },
 });

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 {};