@inflexa-ai/harness 0.1.1

package/dist/tools/bio/search-dgidb.js

@@ -0,0 +1,199 @@
+/**
+ * searchDgidb tool — query drug-gene interactions via DGIdb GraphQL.
+ *
+ * DGIdb aggregates interactions from 30+ sources (ChEMBL, DrugBank, TTD,
+ * PharmGKB, GuideToPharmacology, CIViC, etc.). Free, no API key required.
+ *
+ * Two directions:
+ *   - searchType="gene": input HUGO symbols, returns drugs interacting with each.
+ *   - searchType="drug": input drug names/concept IDs, returns genes each acts on.
+ */
+import { ok } from "neverthrow";
+import { z } from "zod";
+import { defineTool } from "../define-tool.js";
+import { apiFetchValidated, describeApiError } from "../lib/api-utils.js";
+const DGIDB_GRAPHQL_URL = "https://dgidb.org/api/graphql";
+const GENE_INTERACTIONS_QUERY = `query($genes: [String!]!) {
+  genes(names: $genes) {
+    nodes {
+      name
+      interactions {
+        interactionScore
+        interactionTypes { type directionality }
+        drug { name conceptId }
+        interactionAttributes { name value }
+        publications { pmid }
+        sources { sourceDbName }
+      }
+    }
+  }
+}`;
+const DRUG_INTERACTIONS_QUERY = `query($drugs: [String!]!) {
+  drugs(names: $drugs) {
+    nodes {
+      name
+      conceptId
+      interactions {
+        interactionScore
+        interactionTypes { type directionality }
+        gene { name }
+        interactionAttributes { name value }
+        publications { pmid }
+        sources { sourceDbName }
+      }
+    }
+  }
+}`;
+// Shape of the DGIdb GraphQL payload as it arrives on the wire. Validated at
+// the fetch boundary; `mapInteraction` normalizes each record into the
+// `Interaction` we return. Most fields are optional/nullable to match GraphQL's
+// per-field nullability — but `RawNode.name` is required because we key the
+// node map on `name.toLowerCase()`; a node missing it is a contract break we
+// surface as an `invalid_response` error rather than a runtime TypeError.
+const RawInteractionSchema = z.object({
+    interactionScore: z.number().nullable().optional(),
+    interactionTypes: z.array(z.object({ type: z.string().optional(), directionality: z.string().nullable().optional() })).optional(),
+    drug: z.object({ name: z.string().optional(), conceptId: z.string().nullable().optional() }).nullable().optional(),
+    gene: z.object({ name: z.string().optional() }).nullable().optional(),
+    interactionAttributes: z.array(z.object({ name: z.string().optional(), value: z.string().optional() })).optional(),
+    publications: z.array(z.object({ pmid: z.union([z.string(), z.number()]).optional() })).optional(),
+    sources: z.array(z.object({ sourceDbName: z.string().optional() })).optional(),
+});
+const RawNodeSchema = z.object({
+    name: z.string(),
+    conceptId: z.string().nullable().optional(),
+    interactions: z.array(RawInteractionSchema).optional(),
+});
+const DgidbResponseSchema = z.object({
+    data: z
+        .object({
+        genes: z.object({ nodes: z.array(RawNodeSchema).optional() }).optional(),
+        drugs: z.object({ nodes: z.array(RawNodeSchema).optional() }).optional(),
+    })
+        .optional(),
+    errors: z.array(z.object({ message: z.string().optional() })).optional(),
+});
+function mapInteraction(raw, perspective, inputSide) {
+    const sources = (raw.sources ?? []).map((s) => s.sourceDbName ?? "").filter(Boolean);
+    const pmids = (raw.publications ?? []).map((p) => (p.pmid != null ? String(p.pmid) : "")).filter(Boolean);
+    const types = (raw.interactionTypes ?? []).map((t) => ({
+        type: t.type ?? "",
+        ...(t.directionality ? { directionality: t.directionality } : {}),
+    }));
+    const attributes = (raw.interactionAttributes ?? []).slice(0, 20).map((a) => ({
+        name: a.name ?? "",
+        value: (a.value ?? "").slice(0, 200),
+    }));
+    const geneName = perspective === "gene" ? (inputSide.geneName ?? "") : (raw.gene?.name ?? "");
+    const drugName = perspective === "drug" ? (inputSide.drugName ?? "") : (raw.drug?.name ?? "");
+    const drugConceptId = perspective === "drug" ? inputSide.drugConceptId : (raw.drug?.conceptId ?? undefined);
+    return {
+        geneName,
+        drugName,
+        ...(drugConceptId ? { drugConceptId } : {}),
+        interactionTypes: types,
+        ...(raw.interactionScore != null ? { interactionScore: raw.interactionScore } : {}),
+        sourceCount: sources.length,
+        sources,
+        publicationCount: pmids.length,
+        pmids: pmids.slice(0, 10),
+        attributes,
+    };
+}
+function applyFilters(interactions, filters) {
+    let out = interactions;
+    if (filters.interactionTypes?.length) {
+        const needles = filters.interactionTypes.map((s) => s.toLowerCase());
+        out = out.filter((i) => i.interactionTypes.some((t) => needles.some((n) => t.type.toLowerCase().includes(n))));
+    }
+    if (filters.sources?.length) {
+        const needles = filters.sources.map((s) => s.toLowerCase());
+        out = out.filter((i) => i.sources.some((s) => needles.some((n) => s.toLowerCase().includes(n))));
+    }
+    if (filters.minSources > 0) {
+        out = out.filter((i) => i.sourceCount >= filters.minSources);
+    }
+    return out;
+}
+export const searchDgidbTool = defineTool({
+    id: "search_dgidb",
+    description: "Query the Drug-Gene Interaction Database (DGIdb) for drug-gene interactions. " +
+        "DGIdb aggregates 30+ sources (ChEMBL, DrugBank, TTD, PharmGKB, GuideToPharmacology, CIViC, etc.) " +
+        "and returns source counts as a confidence signal. " +
+        "searchType='gene' returns drugs interacting with input HUGO gene symbols (most common: 'what drugs hit my gene set?'). " +
+        "searchType='drug' returns the genes each input drug is known to act on. " +
+        "Free, no API key required. Sorted by source count desc.",
+    inputSchema: z.object({
+        query: z
+            .union([z.string(), z.array(z.string()).max(50)])
+            .describe("Single identifier or list of up to 50. For searchType='gene': HUGO symbols. For searchType='drug': drug names or DGIdb concept IDs."),
+        searchType: z.enum(["gene", "drug"]).default("gene"),
+        interactionTypes: z.array(z.string()).optional().describe("Case-insensitive substring filter on interaction type. e.g. ['inhibitor', 'antagonist']"),
+        sources: z.array(z.string()).optional().describe("Restrict to interactions from these source DBs (case-insensitive substring)."),
+        minSources: z.number().int().min(1).default(1).describe("Drop interactions supported by fewer than this many sources."),
+        limit: z.number().int().min(1).max(200).default(50).describe("Max interactions per input gene/drug after filtering."),
+    }),
+    execute: async ({ query, searchType = "gene", interactionTypes, sources, minSources = 1, limit = 50 }) => {
+        const inputs = typeof query === "string" ? [query] : query;
+        if (inputs.length === 0 || inputs.every((s) => !s.trim())) {
+            throw new Error("query must contain at least one identifier");
+        }
+        const isGene = searchType === "gene";
+        const variableName = isGene ? "genes" : "drugs";
+        const queryString = isGene ? GENE_INTERACTIONS_QUERY : DRUG_INTERACTIONS_QUERY;
+        const res = await apiFetchValidated(DGIDB_GRAPHQL_URL, DgidbResponseSchema, {
+            method: "POST",
+            headers: { "Content-Type": "application/json" },
+            body: JSON.stringify({
+                query: queryString,
+                variables: { [variableName]: inputs },
+            }),
+        });
+        if (res.isErr())
+            throw new Error(describeApiError(res.error));
+        const body = res.value;
+        if (!body || !body.data)
+            throw new Error("DGIdb returned no data");
+        if (body.errors?.length) {
+            console.warn("dgidb.partial_errors", { errors: body.errors.slice(0, 3) });
+        }
+        const nodes = (isGene ? body.data.genes?.nodes : body.data.drugs?.nodes) ?? [];
+        const nodeMap = new Map();
+        for (const node of nodes) {
+            nodeMap.set(node.name.toLowerCase(), node);
+            if (!isGene && node.conceptId) {
+                nodeMap.set(node.conceptId.toLowerCase(), node);
+            }
+        }
+        const results = inputs.map((input) => {
+            const node = nodeMap.get(input.toLowerCase());
+            if (!node) {
+                return { input, found: false, interactions: [] };
+            }
+            const inputSide = isGene
+                ? { geneName: node.name }
+                : {
+                    drugName: node.name,
+                    drugConceptId: node.conceptId ?? undefined,
+                };
+            const mapped = (node.interactions ?? []).map((raw) => mapInteraction(raw, searchType, inputSide));
+            const filtered = applyFilters(mapped, {
+                interactionTypes,
+                sources,
+                minSources,
+            });
+            const sorted = filtered.sort((a, b) => {
+                if (b.sourceCount !== a.sourceCount) {
+                    return b.sourceCount - a.sourceCount;
+                }
+                return (b.interactionScore ?? 0) - (a.interactionScore ?? 0);
+            });
+            return {
+                input,
+                found: true,
+                interactions: sorted.slice(0, limit),
+            };
+        });
+        return ok({ results });
+    },
+});

package/dist/tools/bio/search-disgenet.d.ts

@@ -0,0 +1,30 @@
+/**
+ * searchDisgenet — search DisGeNET for gene-disease associations (GDAs).
+ *
+ * Requires `DISGENET_API_KEY`. Without the key, `getDisgenetHeaders` throws
+ * on first call; the harness surfaces that as a tool `is_error` envelope.
+ */
+export declare function createSearchDisgenetTool(deps: {
+    apiKey: string;
+}): import("../define-tool.js").Tool<{
+    query: string;
+    searchType: "gene" | "disease";
+    minScore: number;
+    source: "ALL" | "CURATED" | "ANIMAL_MODELS" | "BEFREE";
+    limit: number;
+}, {
+    associations: {
+        geneSymbol: string;
+        geneName: string;
+        geneId: number;
+        diseaseName: string;
+        diseaseId: string;
+        diseaseType: string;
+        score: number;
+        evidenceIndex: number;
+        yearInitial: number | null;
+        yearFinal: number | null;
+        nPmids: number;
+        source: string;
+    }[];
+}>;

package/dist/tools/bio/search-disgenet.js

@@ -0,0 +1,84 @@
+/**
+ * searchDisgenet — search DisGeNET for gene-disease associations (GDAs).
+ *
+ * Requires `DISGENET_API_KEY`. Without the key, `getDisgenetHeaders` throws
+ * on first call; the harness surfaces that as a tool `is_error` envelope.
+ */
+import { ok } from "neverthrow";
+import { z } from "zod";
+import { defineTool } from "../define-tool.js";
+import { apiFetchValidated, describeApiError } from "../lib/api-utils.js";
+import { DISGENET_BASE, getDisgenetHeaders } from "../lib/disgenet-config.js";
+// A single schema that both validates and normalizes one DisGeNET GDA record:
+// the `.object(...)` half is the snake_case wire shape (every field optional —
+// the API omits absent values), the `.transform(...)` half maps it to the
+// camelCase `Gda` we return. Parsing IS the validation (`apiFetchValidated`
+// runs it over the JSON), and because the transform rides on the schema,
+// `z.infer` below is the OUTPUT type — no separate raw interface or mapper.
+const GdaSchema = z
+    .object({
+    gene_symbol: z.string().nullable().optional(),
+    gene_name: z.string().nullable().optional(),
+    geneid: z.number().nullable().optional(),
+    disease_name: z.string().nullable().optional(),
+    diseaseid: z.string().nullable().optional(),
+    disease_type: z.string().nullable().optional(),
+    score: z.number().nullable().optional(),
+    ei: z.number().nullable().optional(),
+    year_initial: z.number().nullable().optional(),
+    year_final: z.number().nullable().optional(),
+    pmid_count: z.number().nullable().optional(),
+    source: z.string().nullable().optional(),
+})
+    .transform((gda) => ({
+    geneSymbol: gda.gene_symbol ?? "",
+    geneName: gda.gene_name ?? "",
+    geneId: gda.geneid ?? 0,
+    diseaseName: gda.disease_name ?? "",
+    diseaseId: gda.diseaseid ?? "",
+    diseaseType: gda.disease_type ?? "",
+    score: gda.score ?? 0,
+    evidenceIndex: gda.ei ?? 0,
+    yearInitial: gda.year_initial ?? null,
+    yearFinal: gda.year_final ?? null,
+    nPmids: gda.pmid_count ?? 0,
+    source: gda.source ?? "",
+}));
+const GdaListSchema = z.array(GdaSchema);
+export function createSearchDisgenetTool(deps) {
+    return defineTool({
+        id: "search_disgenet",
+        description: "Search DisGeNET for gene-disease associations (GDAs). Returns association scores, " +
+            "evidence counts, and disease classifications. Requires DISGENET_API_KEY. " +
+            "Use for target validation — high-scoring GDAs provide genetic support for a " +
+            "therapeutic target's disease relevance.",
+        inputSchema: z.object({
+            query: z.string().describe("Gene symbol (e.g. TP53), Entrez gene ID (e.g. 7157), or disease name/UMLS CUI (e.g. C0006142 for breast cancer)"),
+            searchType: z.enum(["gene", "disease"]).describe("'gene' to find diseases for a gene, 'disease' to find genes for a disease"),
+            minScore: z.number().min(0).max(1).default(0.1).describe("Minimum GDA score (0–1). Higher = stronger evidence"),
+            source: z.enum(["ALL", "CURATED", "ANIMAL_MODELS", "BEFREE"]).default("ALL").describe("Evidence source filter"),
+            limit: z.number().int().min(1).max(100).default(25).describe("Max results to return"),
+        }),
+        execute: async ({ query, searchType, minScore = 0.1, source = "ALL", limit = 25 }) => {
+            const headers = getDisgenetHeaders(deps.apiKey);
+            let url;
+            if (searchType === "gene") {
+                const isNumeric = /^\d+$/.test(query);
+                const param = isNumeric ? `gene/${query}` : `gene/${encodeURIComponent(query)}`;
+                url = `${DISGENET_BASE}/gda/${param}?min_score=${minScore}&limit=${limit}`;
+            }
+            else {
+                url = `${DISGENET_BASE}/gda/disease/${encodeURIComponent(query)}?min_score=${minScore}&limit=${limit}`;
+            }
+            if (source !== "ALL") {
+                url += `&source=${source}`;
+            }
+            const res = await apiFetchValidated(url, GdaListSchema, { headers });
+            if (res.isErr())
+                throw new Error(describeApiError(res.error));
+            // Already validated + normalized to camelCase by GdaSchema's transform.
+            const associations = res.value;
+            return ok({ associations });
+        },
+    });
+}

package/dist/tools/bio/search-drugbank.d.ts

@@ -0,0 +1,38 @@
+/**
+ * searchDrugbank — search DrugBank for drug records and target-driven lookups.
+ *
+ * Requires `DRUGBANK_API_KEY`. Without the key, `getDrugbankHeaders` throws
+ * on first call; the harness surfaces that as a tool `is_error` envelope.
+ */
+export declare function createSearchDrugbankTool(deps: {
+    apiKey: string;
+}): import("../define-tool.js").Tool<{
+    query: string;
+    searchType: "target" | "drug";
+    limit: number;
+}, {
+    drugs: {
+        drugbankId: string;
+        name: string;
+        description: string;
+        type: string;
+        groups: string[];
+        categories: string[];
+        indication: string;
+        pharmacodynamics: string;
+        mechanismOfAction: string;
+        toxicity: string;
+        halfLife: string;
+        targets: {
+            name: string;
+            geneSymbol: string;
+            actions: string[];
+            knownAction: string;
+        }[];
+        interactions: {
+            drugbankId: string;
+            name: string;
+            description: string;
+        }[];
+    }[];
+}>;

package/dist/tools/bio/search-drugbank.js

@@ -0,0 +1,109 @@
+/**
+ * searchDrugbank — search DrugBank for drug records and target-driven lookups.
+ *
+ * Requires `DRUGBANK_API_KEY`. Without the key, `getDrugbankHeaders` throws
+ * on first call; the harness surfaces that as a tool `is_error` envelope.
+ */
+import { ok } from "neverthrow";
+import { z } from "zod";
+import { defineTool } from "../define-tool.js";
+import { apiFetchValidated, describeApiError } from "../lib/api-utils.js";
+import { DRUGBANK_BASE, getDrugbankHeaders } from "../lib/drugbank-config.js";
+// A single schema that both validates and normalizes one DrugBank record.
+// The `.object(...)` half is the snake_case wire shape (every field optional —
+// the API omits absent values); the `.transform(...)` half maps it into the
+// camelCase result we return. Parsing IS the validation: `apiFetchValidated`
+// runs this schema over the JSON, so a payload whose field TYPES drift (an
+// object where the API used to send an array, a number for a string) is
+// rejected as `invalid_response` instead of being silently mis-mapped. Because
+// the schema carries the transform, `z.infer` below is the OUTPUT (camelCase)
+// type callers receive — there is no separate raw interface or mapper to keep
+// in sync.
+const DrugResultSchema = z
+    .object({
+    drugbank_id: z.string().optional(),
+    name: z.string().optional(),
+    description: z.string().optional(),
+    type: z.string().optional(),
+    groups: z.array(z.string()).optional(),
+    categories: z.array(z.object({ category: z.string().optional() })).optional(),
+    indication: z.string().optional(),
+    pharmacodynamics: z.string().optional(),
+    mechanism_of_action: z.string().optional(),
+    toxicity: z.string().optional(),
+    half_life: z.string().optional(),
+    targets: z
+        .array(z.object({
+        name: z.string().optional(),
+        gene_name: z.string().optional(),
+        actions: z.array(z.string()).optional(),
+        known_action: z.string().optional(),
+    }))
+        .optional(),
+    drug_interactions: z
+        .array(z.object({
+        drugbank_id: z.string().optional(),
+        name: z.string().optional(),
+        description: z.string().optional(),
+    }))
+        .optional(),
+})
+    .transform((raw) => ({
+    drugbankId: raw.drugbank_id ?? "",
+    name: raw.name ?? "",
+    description: (raw.description ?? "").slice(0, 500),
+    type: raw.type ?? "",
+    groups: raw.groups ?? [],
+    categories: (raw.categories ?? []).map((c) => c.category ?? "").filter(Boolean),
+    indication: (raw.indication ?? "").slice(0, 500),
+    pharmacodynamics: (raw.pharmacodynamics ?? "").slice(0, 500),
+    mechanismOfAction: (raw.mechanism_of_action ?? "").slice(0, 500),
+    toxicity: (raw.toxicity ?? "").slice(0, 500),
+    halfLife: raw.half_life ?? "",
+    targets: (raw.targets ?? []).slice(0, 20).map((t) => ({
+        name: t.name ?? "",
+        geneSymbol: t.gene_name ?? "",
+        actions: t.actions ?? [],
+        knownAction: t.known_action ?? "",
+    })),
+    interactions: (raw.drug_interactions ?? []).slice(0, 20).map((i) => ({
+        drugbankId: i.drugbank_id ?? "",
+        name: i.name ?? "",
+        description: (i.description ?? "").slice(0, 200),
+    })),
+}));
+// The /drugs endpoint returns a single object (by-id lookup) or an array
+// (query/target lookups); accept either, transforming each element.
+const DrugResponseSchema = z.union([DrugResultSchema, z.array(DrugResultSchema)]);
+export function createSearchDrugbankTool(deps) {
+    return defineTool({
+        id: "search_drugbank",
+        description: "Search DrugBank for drug information including targets, interactions, indications, " +
+            "pharmacodynamics, and toxicity. Requires DRUGBANK_API_KEY. Use for drug repurposing " +
+            "analysis, drug-drug interaction assessment, and connecting omics targets to existing therapeutics.",
+        inputSchema: z.object({
+            query: z.string().describe("Drug name (e.g. imatinib), DrugBank ID (e.g. DB00619), or target gene symbol for reverse lookup"),
+            searchType: z.enum(["drug", "target"]).default("drug").describe("'drug' to search by drug name/ID, 'target' to find drugs for a gene target"),
+            limit: z.number().int().min(1).max(50).default(10).describe("Max results to return"),
+        }),
+        execute: async ({ query, searchType = "drug", limit = 10 }) => {
+            const headers = getDrugbankHeaders(deps.apiKey);
+            let url;
+            if (searchType === "target") {
+                url = `${DRUGBANK_BASE}/drugs?target=${encodeURIComponent(query)}&limit=${limit}`;
+            }
+            else if (query.startsWith("DB")) {
+                url = `${DRUGBANK_BASE}/drugs/${query}`;
+            }
+            else {
+                url = `${DRUGBANK_BASE}/drugs?q=${encodeURIComponent(query)}&limit=${limit}`;
+            }
+            const res = await apiFetchValidated(url, DrugResponseSchema, { headers });
+            if (res.isErr())
+                throw new Error(describeApiError(res.error));
+            // Already validated + normalized by DrugResultSchema's transform.
+            const drugs = Array.isArray(res.value) ? res.value : [res.value];
+            return ok({ drugs: drugs.slice(0, limit) });
+        },
+    });
+}

package/dist/tools/bio/search-faers.d.ts

@@ -0,0 +1,11 @@
+/**
+ * searchFaers — search FDA FAERS for adverse event reports for a drug.
+ */
+export declare const searchFaersTool: import("../define-tool.js").Tool<{
+    drugName: string;
+    limit: number;
+    serious: boolean;
+}, {
+    totalReports: number | undefined;
+    adverseEvents: import("../lib/openfda-client.js").AdverseEventCount[];
+}>;

package/dist/tools/bio/search-faers.js

@@ -0,0 +1,23 @@
+/**
+ * searchFaers — search FDA FAERS for adverse event reports for a drug.
+ */
+import { ok } from "neverthrow";
+import { z } from "zod";
+import { defineTool } from "../define-tool.js";
+import { getFaersByDrug } from "../lib/openfda-client.js";
+export const searchFaersTool = defineTool({
+    id: "search_faers",
+    description: "Search FDA FAERS (Adverse Event Reporting System) for adverse event reports associated with a drug. Returns the most frequently reported adverse reactions. Use to assess real-world safety signals for drugs or drug candidates targeting a specific gene/pathway.",
+    inputSchema: z.object({
+        drugName: z.string().describe("Drug generic name (e.g. imatinib, pembrolizumab)"),
+        limit: z.number().int().min(1).max(100).default(25).describe("Max adverse event types to return"),
+        serious: z.boolean().default(false).describe("Filter to serious adverse events only"),
+    }),
+    execute: async ({ drugName, limit = 25, serious = false }) => {
+        const result = await getFaersByDrug(drugName, { limit, serious });
+        return ok({
+            totalReports: result.totalReports,
+            adverseEvents: result.adverseEvents,
+        });
+    },
+});

package/dist/tools/bio/search-gene.d.ts

@@ -0,0 +1,11 @@
+/**
+ * searchGene — look up gene information via the Ensembl REST API.
+ */
+export declare const searchGeneTool: import("../define-tool.js").Tool<{
+    symbols: string[];
+    species: string;
+    expand: boolean;
+}, {
+    genes: import("../lib/ensembl-client.js").GeneInfo[];
+    notFound: string[];
+}>;

package/dist/tools/bio/search-gene.js

@@ -0,0 +1,19 @@
+/**
+ * searchGene — look up gene information via the Ensembl REST API.
+ */
+import { ok } from "neverthrow";
+import { z } from "zod";
+import { defineTool } from "../define-tool.js";
+import { lookupGenes } from "../lib/ensembl-client.js";
+export const searchGeneTool = defineTool({
+    id: "search_gene",
+    description: "Look up gene information from Ensembl by gene symbol. " +
+        "Returns Ensembl IDs, genomic coordinates, biotype, and descriptions. " +
+        "Supports batch lookups of up to 200 symbols at once.",
+    inputSchema: z.object({
+        symbols: z.array(z.string()).min(1).max(200).describe("Gene symbols to look up (e.g. ['BRCA1', 'TP53'])"),
+        species: z.string().default("homo_sapiens").describe("Species name (e.g. 'homo_sapiens', 'mus_musculus')"),
+        expand: z.boolean().default(false).describe("Include transcript/exon details in the response"),
+    }),
+    execute: async ({ symbols, species, expand }) => ok(await lookupGenes(symbols, { species, expand })),
+});

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

@@ -0,0 +1,20 @@
+/**
+ * searchGeoDatasets — search NCBI GEO for public gene expression datasets.
+ */
+export declare const searchGeoDatasetsTool: import("../define-tool.js").Tool<{
+    query: string;
+    datasetType: "gse" | "gds";
+    limit: number;
+    organism?: string | undefined;
+}, {
+    totalFound: number;
+    datasets: {
+        accession: string;
+        title: string;
+        summary: string;
+        platform: string | null;
+        sampleCount: number | null;
+        organism: string | null;
+        pubmedIds: (string | number)[];
+    }[];
+}>;

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

@@ -0,0 +1,86 @@
+/**
+ * searchGeoDatasets — search NCBI GEO for public gene expression datasets.
+ */
+import { ok } from "neverthrow";
+import { z } from "zod";
+import { defineTool } from "../define-tool.js";
+import { apiFetchValidated, describeApiError } from "../lib/api-utils.js";
+const ESEARCH_BASE = "https://eutils.ncbi.nlm.nih.gov/entrez/eutils";
+// NCBI E-utilities wire shapes, validated at the fetch boundary. Every field is
+// 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({
+    esearchresult: z
+        .object({
+        idlist: z.array(z.string()).optional(),
+        count: z.string().optional(),
+    })
+        .optional(),
+});
+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(),
+});
+// 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({
+    result: z.record(z.string(), GeoDatasetSummarySchema.optional().catch(undefined)).optional(),
+});
+export const searchGeoDatasetsTool = defineTool({
+    id: "search_geo_datasets",
+    description: "Search NCBI GEO for public gene expression datasets by disease, tissue, or experimental condition. Returns dataset accessions and metadata for identifying external validation cohorts. Note: sandbox containers cannot download GEO data directly — use this tool to identify relevant datasets, then reference accessions in analysis plans.",
+    inputSchema: z.object({
+        query: z.string().describe("Search terms (e.g. 'breast cancer RNA-seq responder', 'NSCLC pembrolizumab')"),
+        organism: z.string().optional().describe("Filter by organism (e.g. 'Homo sapiens')"),
+        datasetType: z.enum(["gds", "gse"]).default("gse").describe("GDS (curated datasets) or GSE (series, more numerous)"),
+        limit: z.number().int().min(1).max(50).default(15).describe("Max results"),
+    }),
+    execute: async ({ query, organism, datasetType = "gse", limit = 15 }) => {
+        let searchQuery = query;
+        if (organism)
+            searchQuery += ` AND "${organism.replace(/"/g, '\\"')}"[Organism]`;
+        const db = "gds";
+        const typeFilter = datasetType === "gse" ? " AND gse[Entry Type]" : " AND gds[Entry Type]";
+        searchQuery += typeFilter;
+        const searchUrl = `${ESEARCH_BASE}/esearch.fcgi?db=${db}&term=${encodeURIComponent(searchQuery)}&retmax=${limit}&retmode=json`;
+        const searchRes = await apiFetchValidated(searchUrl, GeoEsearchResponseSchema);
+        if (searchRes.isErr())
+            throw new Error(describeApiError(searchRes.error));
+        const ids = searchRes.value?.esearchresult?.idlist ?? [];
+        if (ids.length === 0)
+            return ok({ totalFound: 0, datasets: [] });
+        const summaryUrl = `${ESEARCH_BASE}/esummary.fcgi?db=${db}&id=${ids.join(",")}&retmode=json`;
+        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, 500),
+                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 totalFound = Number(searchRes.value?.esearchresult?.count) || datasets.length;
+        return ok({ totalFound, datasets });
+    },
+});