@inflexa-ai/harness 0.30.3 → 0.31.1

package/dist/tools/bio/chembl.js

@@ -38,9 +38,10 @@ const inputSchema = z
         .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" +
+        "'drug' (query) — approved drugs by indication or by drug name: 'what treats X?', 'is Y approved, since when?'. → moleculeChemblId, " +
+        "preferredName, maxPhase (4 = approved), moleculeType, firstApproval, indication. A disease term reads the curated indication " +
+        "registry, highest phase first; a query that matches no disease term reads the approved molecules (max_phase >= 4) instead, and " +
+        "their indications come back with them.\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" +

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

@@ -18,7 +18,6 @@
  */
 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];
@@ -30,26 +29,15 @@ interface SourceOutcome {
 }
 /**
  * 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.
+ * the description arrives whole or as a preview — a 500-character field across
+ * ten records is 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 {

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

@@ -29,9 +29,6 @@ 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)])
@@ -47,7 +44,8 @@ const inputSchema = z.object({
         .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. " +
+        "'drugbank': the curated drug RECORD of the Discovery API (name, description, modality type, approval groups); it carries no indication, " +
+        "pharmacodynamics, mechanism, toxicity, half-life or drug-drug interaction, because that API serves none of them. 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()
@@ -56,7 +54,7 @@ const inputSchema = z.object({
         .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."),
+        "`totalInteractions` gives the pre-trim count. DrugBank serves one page of at most 50 records, thus a larger limit still returns at most 50 there."),
     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."),
@@ -67,33 +65,27 @@ const inputSchema = z.object({
     includeDrugRecord: z
         .boolean()
         .optional()
-        .describe(`'drugbank' only. Default FALSE — the five prose fields come back as ${PROSE_PREVIEW_CHARS}-char previews with proseTruncated: true. ` +
+        .describe(`'drugbank' only. Default FALSE — the description comes back as a ${PROSE_PREVIEW_CHARS}-char preview 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),
+        description: includeFullProse ? drug.description : drug.description.slice(0, PROSE_PREVIEW_CHARS),
         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.
+ *
+ * `unavailable` reports that the corpus was not reached. An empty result is a
+ * complete answer, thus it reports `no_data`. ClinPGx encodes "no annotation" as
+ * an HTTP 404, and its client maps that miss to an empty list before it arrives
+ * here. As a result an unannotated gene reads as `no_data`, not as an outage.
  */
 async function runSource(source, fetch) {
     try {

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

@@ -24,6 +24,7 @@
  * — an accession of that corpus — marks the others `not_applicable` rather
  * than sending them a query they cannot read.
  */
+import type { Logger } from "../../lib/logger.js";
 import { type MutationFrequency } from "../lib/cbioportal-client.js";
 import { type ClinvarVariant } from "../lib/clinvar-client.js";
 import { type Gda } from "../lib/disgenet-client.js";
@@ -57,6 +58,7 @@ interface GeneDiseaseEvidenceOutput {
 export declare function createGeneDiseaseEvidenceTool(deps: {
     ncbiApiKey?: string;
     disgenetApiKey: string;
+    logger?: Logger;
 }): import("../define-tool.js").Tool<{
     query: string;
     queryType: "gene" | "disease" | "variant" | "gwas_study" | "clinvar_accession";
@@ -64,7 +66,7 @@ export declare function createGeneDiseaseEvidenceTool(deps: {
     limit?: number | undefined;
     pValueThreshold?: number | undefined;
     minScore?: number | undefined;
-    disgenetSource?: "ALL" | "CURATED" | "ANIMAL_MODELS" | "BEFREE" | undefined;
+    disgenetSource?: "ALL" | "BIOBANK" | "CHEMBL" | "CLINICALTRIALS" | "CLINGEN" | "CLINPGX" | "CLINVAR" | "CURATED" | "FINNGEN" | "GENCC" | "GWASCAT" | "HPO" | "INFERRED" | "MGD_HUMAN" | "MGD_MOUSE" | "MODELS" | "ORPHANET" | "PHEWASCAT" | "PSYGENET" | "RGD_HUMAN" | "RGD_RAT" | "TEXTMINING_HUMAN" | "TEXTMINING_MODELS" | "UKBIOBANK" | "UNIPROT" | undefined;
     clinicalSignificance?: "pathogenic" | "likely-pathogenic" | "benign" | "likely-benign" | "uncertain" | undefined;
     informativeOnly?: boolean | undefined;
 }, GeneDiseaseEvidenceOutput>;

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

@@ -29,7 +29,7 @@ import { z } from "zod";
 import { defineTool } from "../define-tool.js";
 import { getSomaticMutationFrequencies } from "../lib/cbioportal-client.js";
 import { filterInformative, searchClinvar } from "../lib/clinvar-client.js";
-import { searchDisgenet } from "../lib/disgenet-client.js";
+import { DISGENET_SOURCES, searchDisgenet } from "../lib/disgenet-client.js";
 import { searchGwasCatalog } from "../lib/gwas-catalog-client.js";
 const SOURCES = ["gwas", "disgenet", "clinvar", "cbioportal"];
 const QUERY_TYPES = ["gene", "disease", "variant", "gwas_study", "clinvar_accession"];
@@ -69,7 +69,8 @@ const inputSchema = z.object({
         .string()
         .min(1)
         .describe("The entity, matching `queryType`. gene: a HUGO symbol ('PCSK9'); DisGeNET also takes an Entrez ID, and cBioPortal takes the symbol " +
-        "directly. disease: a disease or trait name ('LDL cholesterol'); DisGeNET also takes a UMLS CUI ('C0006142'). variant: a dbSNP rsID " +
+        "directly. disease: a disease or trait name ('asthma'); the GWAS Catalog needs the exact EFO trait label, and DisGeNET also takes a UMLS " +
+        "CUI ('C0006142'). variant: a dbSNP rsID " +
         "('rs11591147'). gwas_study: a GWAS Catalog study accession ('GCST000392'). clinvar_accession: a ClinVar accession ('VCV000012345', " +
         "'RCV000009910') or a bare variation ID."),
     queryType: z
@@ -106,9 +107,10 @@ const inputSchema = z.object({
         .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"])
+        .enum(DISGENET_SOURCES)
         .optional()
-        .describe("'disgenet' only. Provenance filter; default 'ALL'. Prefer 'CURATED' for anything you will quote — 'BEFREE' is text-mined and noisy."),
+        .describe("'disgenet' only. Provenance filter; default 'ALL'. Prefer 'CURATED' for anything you will quote — 'TEXTMINING_HUMAN' and " +
+        "'TEXTMINING_MODELS' are text-mined and noisy, and 'MODELS' is animal-model evidence."),
     clinicalSignificance: z
         .enum(["pathogenic", "likely-pathogenic", "benign", "likely-benign", "uncertain"])
         .optional()
@@ -158,8 +160,10 @@ export function createGeneDiseaseEvidenceTool(deps) {
             "and the drug landscape. Reach here for the underlying records: actual SNPs, effect sizes, scores, pathogenicity calls and somatic mutation " +
             "frequencies with their studies and PMIDs.\n" +
             "ACCEPTED IDENTIFIERS, each named by its `queryType`: a HUGO gene symbol or an Entrez ID ('PCSK9', '5008'); a disease or trait name or a UMLS " +
-            "CUI ('LDL cholesterol', 'C0006142'); a dbSNP rsID ('rs11591147'); a GWAS Catalog study accession ('GCST000392'); and a ClinVar accession " +
-            "('VCV000012345'). The last two read one record back by the accession that an earlier result of this same tool reported.\n" +
+            "CUI ('asthma', 'C0006142'); a dbSNP rsID ('rs11591147'); a GWAS Catalog study accession ('GCST000392'); and a ClinVar accession " +
+            "('VCV000012345'). The last two read one record back by the accession that an earlier result of this same tool reported. " +
+            "The GWAS Catalog matches the EXACT EFO trait label (case-insensitive): 'asthma' resolves, a paraphrase such as 'LDL cholesterol' reads as " +
+            "no_data there ('low density lipoprotein cholesterol measurement' is the label) while the other corpora still answer it.\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 others); 'not_applicable' means that " +
             "corpus has no lookup for this queryType. Only 'no_data' is evidence of absence, and none is worth retrying unchanged.",
@@ -197,12 +201,11 @@ export function createGeneDiseaseEvidenceTool(deps) {
                     ? 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", {
+                        return 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 };
+                        }, deps.logger);
                     })
                     : null,
                 selected.includes("clinvar")

package/dist/tools/bio/keys.js

@@ -30,6 +30,7 @@ export function createChemDbTools(keys, deps = {}) {
         geneDiseaseEvidence: createGeneDiseaseEvidenceTool({
             disgenetApiKey: keys.disgenet,
             ...(keys.ncbi ? { ncbiApiKey: keys.ncbi } : {}),
+            ...(deps.logger ? { logger: deps.logger } : {}),
         }),
         drugGeneInteractions: createDrugGeneInteractionsTool({
             drugbankApiKey: keys.drugbank,

package/dist/tools/bio/lookup-annotation.d.ts

@@ -13,7 +13,12 @@
  * schema and made conditionally required by `.refine`, so a malformed call
  * fails at the loop boundary naming the missing field instead of reaching an
  * API request that cannot be built.
+ *
+ * Absence policy: QuickGO gives each key and sends an explicit `null` for an
+ * absent value. Thus a maybe-absent QuickGO field carries `.nullable()`, and
+ * `pathway-client.ts` holds the policy of KEGG and Reactome.
  */
+import { z } from "zod";
 import { type Pathway } from "../lib/pathway-client.js";
 interface GoTerm {
     id: string;
@@ -29,6 +34,44 @@ interface GoAnnotation {
     evidenceCode?: string;
     qualifier?: string;
 }
+export declare const GoTermResponseSchema: z.ZodPipe<z.ZodObject<{
+    results: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        id: z.ZodOptional<z.ZodString>;
+        name: z.ZodOptional<z.ZodString>;
+        definition: z.ZodOptional<z.ZodNullable<z.ZodObject<{
+            text: z.ZodOptional<z.ZodString>;
+        }, z.core.$strip>>>;
+        aspect: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>>;
+}, z.core.$strip>, z.ZodTransform<GoTerm[], {
+    results?: {
+        id?: string | undefined;
+        name?: string | undefined;
+        definition?: {
+            text?: string | undefined;
+        } | null | undefined;
+        aspect?: string | undefined;
+    }[] | undefined;
+}>>;
+export declare const GoAnnotationResponseSchema: z.ZodPipe<z.ZodObject<{
+    results: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        geneProductId: z.ZodOptional<z.ZodString>;
+        goId: z.ZodOptional<z.ZodString>;
+        goName: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        goAspect: z.ZodOptional<z.ZodString>;
+        goEvidence: z.ZodOptional<z.ZodString>;
+        qualifier: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>>;
+}, z.core.$strip>, z.ZodTransform<GoAnnotation[], {
+    results?: {
+        geneProductId?: string | undefined;
+        goId?: string | undefined;
+        goName?: string | null | undefined;
+        goAspect?: string | undefined;
+        goEvidence?: string | undefined;
+        qualifier?: string | undefined;
+    }[] | undefined;
+}>>;
 type AnnotationOutput = {
     terms?: GoTerm[];
     annotations?: GoAnnotation[];

package/dist/tools/bio/lookup-annotation.js

@@ -13,6 +13,10 @@
  * schema and made conditionally required by `.refine`, so a malformed call
  * fails at the loop boundary naming the missing field instead of reaching an
  * API request that cannot be built.
+ *
+ * Absence policy: QuickGO gives each key and sends an explicit `null` for an
+ * absent value. Thus a maybe-absent QuickGO field carries `.nullable()`, and
+ * `pathway-client.ts` holds the policy of KEGG and Reactome.
  */
 import { ok } from "neverthrow";
 import { z } from "zod";
@@ -22,11 +26,19 @@ import { getPathwayById, searchPathways } from "../lib/pathway-client.js";
 const QUICKGO_BASE = "https://www.ebi.ac.uk/QuickGO/services";
 const HEADERS = { Accept: "application/json" };
 const DEFAULT_LIMIT = 10;
+/**
+ * The fields that the annotation search must name.
+ *
+ * QuickGO serves the label of a GO term only when the request asks for it. A
+ * request that does not ask gets `"goName": null` on each row, thus every
+ * annotation reads as an identifier with no name.
+ */
+const ANNOTATION_INCLUDE_FIELDS = "goName";
 // QuickGO term response, validated at the fetch boundary. The `.transform`
 // carries the (context-free) rename from the raw wire fields to the `GoTerm[]`
 // we return, so parsing IS both the validation and the normalization — there
 // is no separate raw interface or mapper to keep in sync.
-const GoTermResponseSchema = z
+export const GoTermResponseSchema = z
     .object({
     results: z
         .array(z.object({
@@ -43,13 +55,16 @@ const GoTermResponseSchema = z
     definition: t.definition?.text ?? undefined,
     aspect: t.aspect ?? undefined,
 })));
-const GoAnnotationResponseSchema = z
+// QuickGO answers a `goName` with an explicit `null` on each row unless the
+// request names the field. `ANNOTATION_INCLUDE_FIELDS` names it, and `goName`
+// stays nullable because the wire can still send the null.
+export const GoAnnotationResponseSchema = z
     .object({
     results: z
         .array(z.object({
         geneProductId: z.string().optional(),
         goId: z.string().optional(),
-        goName: z.string().optional(),
+        goName: z.string().nullable().optional(),
         goAspect: z.string().optional(),
         goEvidence: z.string().optional(),
         qualifier: z.string().optional(),
@@ -177,7 +192,7 @@ export const lookupAnnotationTool = defineTool({
         }
         if (geneProductId) {
             tasks.push((async () => {
-                const params = new URLSearchParams({ geneProductId, limit: String(cap) });
+                const params = new URLSearchParams({ geneProductId, limit: String(cap), includeFields: ANNOTATION_INCLUDE_FIELDS });
                 if (taxonId)
                     params.set("taxonId", String(taxonId));
                 const res = await apiFetchValidated(`${QUICKGO_BASE}/annotation/search?${params}`, GoAnnotationResponseSchema, { headers: HEADERS });

package/dist/tools/bio/pubchem.js

@@ -21,9 +21,11 @@ const inputSchema = z
         .describe("Which PubChem lookup to run. " +
         "'compound' — resolve `query` (in the namespace named by `searchBy`) to a compound. Returns results[]: identity (cid, canonicalSmiles, inchi, inchiKey, iupacName, " +
         "molecularFormula) and computed properties (molecularWeight, xlogp, tpsa, hbondDonorCount, hbondAcceptorCount, rotatableBondCount, complexity). " +
-        "'crossrefs' — external registry ids for a `cid`. Returns crossRefs[]: a flat list of { source, id } pairs across ChEMBL, DrugBank, KEGG, PDB and many other " +
-        "registries; filter by `source` for the one you want. This is the bridge out of PubChem. " +
-        "'assays' — bioassay screening summaries for a `cid`; answers 'has this compound ever been screened, and against what?'. Returns assays[]: aid, assayName, targetName, " +
+        "'crossrefs' — external registry ids for a `cid`. Returns crossRefs[]: a flat list of { source, id } entries. `source` names the registry that the id pattern " +
+        "identifies — ChEMBL, ChEBI, DrugBank, KEGG, HMDB, CAS, PDB or UNII — and it is null for an id of any other registry; filter by `source` for the one you want. " +
+        "This is the bridge out of PubChem. " +
+        "'assays' — bioassay screening summaries for a `cid`; answers 'has this compound ever been screened, and against what?'. Returns assays[]: aid, assayName, targetName " +
+        "(the target accession, for example a UniProt or PDB id), " +
         "activityOutcome (Active / Inactive / Inconclusive / Unspecified), activityValue. Broad HTS screening coverage, NOT curated potency — for numbers you intend to quote " +
         "(IC50/Ki), prefer chembl action='bioactivity'."),
     query: z

package/dist/tools/bio/search-clinical-trials.js

@@ -26,8 +26,8 @@ export const searchClinicalTrialsTool = defineTool({
         "read a result, as opposed to finding a trial.\n" +
         "ACCEPTED IDENTIFIERS: `query` is free text matched across the whole study record, so a gene symbol ('KRAS'), a drug or brand name ('imatinib', " +
         "'Gleevec'), a condition ('melanoma') or an NCT ID ('NCT00000102') all work. `nctId` takes one NCT ID and nothing else.\n" +
-        "`phase` and `status` are optional server-side filters — omit them to see the full landscape; totalFound reports the true match count even when it " +
-        "exceeds the page returned.\n" +
+        "`status` is an optional server-side filter and `phase` narrows the returned page. Omit both to see the full landscape. totalFound reports the true " +
+        "match count of `query` plus `status`, thus it can exceed the trials that a phase-narrowed answer carries.\n" +
         "ABSENCE IS NORMAL. An empty trials array is a valid 'nothing matched' (often an over-narrow filter) and a null trial from 'details' means the " +
         "registry holds no such NCT ID — report it and move on, do not retry the identical call. A trial with no posted results carries empty outcomes " +
         "and adverse events, which means unreported, never zero.",
@@ -45,8 +45,9 @@ export const searchClinicalTrialsTool = defineTool({
         phase: z
             .enum(["EARLY_PHASE1", "PHASE1", "PHASE2", "PHASE3", "PHASE4"])
             .optional()
-            .describe("'search' only. Optional exact phase filter. Omit for all phases (observational and expanded-access studies carry no phase and are " +
-            "excluded when this is set)."),
+            .describe("'search' only. Optional exact phase filter, applied to the returned page rather than to the whole query. Omit for all phases " +
+            "(observational and expanded-access studies carry no phase and are excluded when this is set). A narrow phase over a broad query " +
+            "can give fewer trials than `limit` asks for, even when the registry holds more."),
         status: z
             .enum(["RECRUITING", "ACTIVE_NOT_RECRUITING", "COMPLETED", "NOT_YET_RECRUITING", "TERMINATED", "WITHDRAWN", "SUSPENDED"])
             .optional()

package/dist/tools/bio/search-geo-datasets.d.ts

@@ -1,6 +1,44 @@
 /**
  * searchGeoDatasets — search NCBI GEO for public gene expression datasets.
  */
+import { z } from "zod";
+export declare const GeoEsearchResponseSchema: z.ZodObject<{
+    esearchresult: z.ZodOptional<z.ZodObject<{
+        idlist: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        count: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+/** One dataset row, as the tool returns it. */
+export interface GeoDataset {
+    accession: string;
+    title: string;
+    summary: string;
+    platform: string | null;
+    sampleCount: number | null;
+    organism: string | null;
+    pubmedIds: (string | number)[];
+}
+export declare const GeoEsummaryResponseSchema: z.ZodObject<{
+    result: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodCatch<z.ZodOptional<z.ZodObject<{
+        accession: z.ZodOptional<z.ZodString>;
+        gse: z.ZodOptional<z.ZodString>;
+        title: z.ZodOptional<z.ZodString>;
+        summary: z.ZodOptional<z.ZodString>;
+        gpl: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        n_samples: z.ZodOptional<z.ZodUnion<readonly [z.ZodString, z.ZodNumber]>>;
+        taxon: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+        pubmedids: z.ZodOptional<z.ZodArray<z.ZodUnion<readonly [z.ZodString, z.ZodNumber]>>>;
+        error: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>>>>;
+}, z.core.$strip>;
+/**
+ * Map one esummary answer onto the dataset rows.
+ *
+ * `ids` is the id list of the search, and it names the order of the rows. The
+ * function is pure, thus the golden-fixture table exercises it against a stored
+ * payload.
+ */
+export declare function mapGeoDatasets(ids: string[], summary: z.infer<typeof GeoEsummaryResponseSchema>): GeoDataset[];
 export declare const searchGeoDatasetsTool: import("../define-tool.js").Tool<{
     query: string;
     datasetType: "gse" | "gds";
@@ -8,13 +46,5 @@ export declare const searchGeoDatasetsTool: import("../define-tool.js").Tool<{
     organism?: string | undefined;
 }, {
     totalFound: number;
-    datasets: {
-        accession: string;
-        title: string;
-        summary: string;
-        platform: string | null;
-        sampleCount: number | null;
-        organism: string | null;
-        pubmedIds: (string | number)[];
-    }[];
+    datasets: GeoDataset[];
 }>;

package/dist/tools/bio/search-geo-datasets.js

@@ -10,7 +10,7 @@ const ESEARCH_BASE = "https://eutils.ncbi.nlm.nih.gov/entrez/eutils";
 // optional because the API omits absent values; the mapping in `execute` keys
 // off the esearch `idlist` (request context) and reshapes each summary, so the
 // schemas model only the raw wire.
-const GeoEsearchResponseSchema = z.object({
+export const GeoEsearchResponseSchema = z.object({
     esearchresult: z
         .object({
         idlist: z.array(z.string()).optional(),
@@ -18,24 +18,58 @@ const GeoEsearchResponseSchema = z.object({
     })
         .optional(),
 });
+// `gpl` is the platform accession, as a bare number string ("20301"). esummary
+// serves no `platform` key at any level. `error` marks the 200-with-error form:
+// esummary answers HTTP 200 for an unknown uid and puts `{"uid": …, "error": …}`
+// under that key, which carries no dataset.
 const GeoDatasetSummarySchema = z.object({
     accession: z.string().optional(),
     gse: z.string().optional(),
     title: z.string().optional(),
     summary: z.string().optional(),
     gpl: z.string().nullable().optional(),
-    platform: z.string().nullable().optional(),
     n_samples: z.union([z.string(), z.number()]).optional(),
     taxon: z.string().nullable().optional(),
     pubmedids: z.array(z.union([z.string(), z.number()])).optional(),
+    error: z.string().optional(),
 });
 // The esummary `result` object mixes a `uids` string array in with the
 // numeric-keyed dataset summaries; `.catch(undefined)` on the record value lets
 // that `uids` entry (and any drifted summary) fall through as undefined rather
 // than rejecting the whole response — the mapping reads only the numeric ids.
-const GeoEsummaryResponseSchema = z.object({
+export const GeoEsummaryResponseSchema = z.object({
     result: z.record(z.string(), GeoDatasetSummarySchema.optional().catch(undefined)).optional(),
 });
+/**
+ * Map one esummary answer onto the dataset rows.
+ *
+ * `ids` is the id list of the search, and it names the order of the rows. The
+ * function is pure, thus the golden-fixture table exercises it against a stored
+ * payload.
+ */
+export function mapGeoDatasets(ids, summary) {
+    const result = summary?.result ?? {};
+    const datasets = [];
+    for (const id of ids) {
+        const r = result[id];
+        if (!r)
+            continue;
+        // An error record carries no dataset. Without this guard it becomes a
+        // row of empty strings with a fabricated accession.
+        if (r.error !== undefined)
+            continue;
+        datasets.push({
+            accession: r.accession ?? r.gse ?? `GDS${id}`,
+            title: r.title ?? "",
+            summary: (r.summary ?? "").slice(0, 300),
+            platform: r.gpl ?? null,
+            sampleCount: r.n_samples ? Number(r.n_samples) : null,
+            organism: r.taxon ?? null,
+            pubmedIds: r.pubmedids ?? [],
+        });
+    }
+    return datasets;
+}
 export const searchGeoDatasetsTool = defineTool({
     id: "search_geo_datasets",
     description: "Search the NCBI Gene Expression Omnibus (GEO) — the public functional-genomics repository of the U.S. National Library of Medicine — for " +
@@ -88,23 +122,7 @@ export const searchGeoDatasetsTool = defineTool({
         const summaryRes = await apiFetchValidated(summaryUrl, GeoEsummaryResponseSchema);
         if (summaryRes.isErr())
             throw new Error(describeApiError(summaryRes.error));
-        const result = summaryRes.value?.result ?? {};
-        const datasets = ids
-            .map((id) => {
-            const r = result[id];
-            if (!r)
-                return null;
-            return {
-                accession: r.accession ?? r.gse ?? `GDS${id}`,
-                title: r.title ?? "",
-                summary: (r.summary ?? "").slice(0, 300),
-                platform: r.gpl ?? r.platform ?? null,
-                sampleCount: r.n_samples ? Number(r.n_samples) : null,
-                organism: r.taxon ?? null,
-                pubmedIds: r.pubmedids ?? [],
-            };
-        })
-            .filter((d) => d !== null);
+        const datasets = mapGeoDatasets(ids, summaryRes.value);
         const totalFound = Number(searchRes.value?.esearchresult?.count) || datasets.length;
         return ok({ totalFound, datasets });
     },

package/dist/tools/lib/api-utils.d.ts

@@ -1,7 +1,8 @@
 /**
  * Shared HTTP fetch helper for bioinformatics API tools.
  *
- * Provides retry-with-backoff for rate-limited APIs (429/503), request
+ * Provides retry-with-backoff for a rate-limited or a transiently-broken API
+ * (429/502/503/504), request
  * timeouts, and tab-delimited text parsing. `apiFetch` is the external-call
  * boundary, so it is where a throw becomes a `Result`: it returns a
  * `ResultAsync<T, ApiError>` rather than throwing — callers branch on
@@ -35,7 +36,7 @@ export type ApiError = {
     readonly issues: string;
 };
 /**
- * Fetch a URL with retry on 429/503, exponential backoff, and timeout.
+ * Fetch a URL with retry on 429/502/503/504, exponential backoff, and timeout.
  * `err` carries the structured failure; a non-ok HTTP status is reported as
  * `http_status` so callers can branch on a concrete code (a 404 is usually an
  * expected "not found" → a data variant; see `isUnexpectedApiError`).
@@ -73,6 +74,30 @@ export declare function describeApiError(e: ApiError): string;
  * throwing (or returning `err`).
  */
 export declare function isUnexpectedApiError(e: ApiError): boolean;
+/**
+ * Read a number that a provider serializes as a JSON string.
+ *
+ * A Tastypie `decimal` field (ChEMBL `max_phase`, `standard_value`,
+ * `pchembl_value`) and the eutils `esearch` counts arrive as strings, and the
+ * same value arrives as a number from a different serializer of the same
+ * provider. One helper answers for both encodings, thus no call site invents its
+ * own rule.
+ *
+ * A value that is not a finite number gives `null`. As a result a caller never
+ * sees `NaN`, which compares false against itself and poisons every downstream
+ * threshold.
+ */
+export declare function parseWireNumber(value: string | number | null | undefined): number | null;
+/**
+ * The schema form of `parseWireNumber`, for a field that a provider serializes
+ * as a string or as a number.
+ *
+ * The helper accepts neither `null` nor an omission, because absence is a
+ * per-provider policy and no field is widened without evidence. A caller
+ * composes `.nullable()`, `.optional()`, or both, per the policy of its
+ * provider.
+ */
+export declare const zWireNumber: z.ZodPipe<z.ZodUnion<readonly [z.ZodString, z.ZodNumber]>, z.ZodTransform<number | null, string | number>>;
 /**
  * Parse tab-separated text into rows of columns (e.g., KEGG responses).
  * Filters out empty lines.