@inflexa-ai/harness 0.12.0 → 0.14.0

package/dist/tools/bio/gene-preclinical-profile.d.ts

@@ -0,0 +1,58 @@
+/**
+ * genePreclinicalProfile — the in-vivo preclinical picture of one gene: where
+ * it is expressed at baseline (Bgee) and what removing it does to a mouse
+ * (IMPC), behind one `include`.
+ *
+ * The two halves share an input exactly — ONE human gene symbol, with the
+ * per-species orthologs resolved internally — and answer one question between
+ * them: is this target expressed where it needs to act, and is a model organism
+ * a fair surrogate for it. They were two tools that were called as a pair.
+ *
+ * Neither source caps its own output: Bgee returns every annotated tissue per
+ * species and IMPC every significant phenotype term, so both halves are trimmed
+ * here rather than in the clients — the target-assessment collectors read the
+ * same clients and legitimately want full fidelity for the dossier.
+ */
+import { type SupportedSpecies, type TissueRow } from "../lib/bgee-client.js";
+import { type MpTerm, type ViabilityCall, type ViabilityCategory } from "../lib/impc-client.js";
+interface BoundedSpeciesEntry {
+    species: SupportedSpecies;
+    taxonId: number;
+    ensemblId: string;
+    tissues: TissueRow[];
+    /** Tissues Bgee annotated for this species, before `minRank` and `tissueLimit`. */
+    tissueCount: number;
+    /** Tissues that passed `minRank`, before `tissueLimit`. */
+    tissuesAboveMinRank: number;
+}
+interface ExpressionHalf {
+    humanEnsemblId: string | null;
+    bySpecies: BoundedSpeciesEntry[];
+    notFound: string[];
+}
+interface KnockoutHalf {
+    mouseMarkerSymbol: string | null;
+    mgiAccessionId: string | null;
+    viability: ViabilityCategory;
+    viabilityCalls: ViabilityCall[];
+    mpTerms: MpTerm[];
+    organSystems: string[];
+    sexDimorphic: boolean;
+    phenotypeCount: number;
+    /** True when `phenotypeLimit` trimmed `mpTerms`; `phenotypeCount` is the real total. */
+    phenotypesTrimmed: boolean;
+}
+type PreclinicalOutput = {
+    geneSymbol: string;
+    expression?: ExpressionHalf;
+    knockout?: KnockoutHalf;
+};
+export declare const genePreclinicalProfileTool: import("../define-tool.js").Tool<{
+    geneSymbol: string;
+    include?: ("expression" | "knockout")[] | undefined;
+    species?: ("homo_sapiens" | "mus_musculus" | "rattus_norvegicus" | "canis_lupus_familiaris" | "macaca_mulatta")[] | undefined;
+    minRank?: "high" | "medium" | "low" | "absent" | undefined;
+    tissueLimit?: number | undefined;
+    phenotypeLimit?: number | undefined;
+}, PreclinicalOutput>;
+export {};

package/dist/tools/bio/gene-preclinical-profile.js

@@ -0,0 +1,125 @@
+/**
+ * genePreclinicalProfile — the in-vivo preclinical picture of one gene: where
+ * it is expressed at baseline (Bgee) and what removing it does to a mouse
+ * (IMPC), behind one `include`.
+ *
+ * The two halves share an input exactly — ONE human gene symbol, with the
+ * per-species orthologs resolved internally — and answer one question between
+ * them: is this target expressed where it needs to act, and is a model organism
+ * a fair surrogate for it. They were two tools that were called as a pair.
+ *
+ * Neither source caps its own output: Bgee returns every annotated tissue per
+ * species and IMPC every significant phenotype term, so both halves are trimmed
+ * here rather than in the clients — the target-assessment collectors read the
+ * same clients and legitimately want full fidelity for the dossier.
+ */
+import { ok } from "neverthrow";
+import { z } from "zod";
+import { defineTool } from "../define-tool.js";
+import { SUPPORTED_SPECIES, getMultiSpeciesExpression } from "../lib/bgee-client.js";
+import { getKoPhenotypeProfile } from "../lib/impc-client.js";
+/** Ordered weakest → strongest so `minRank` can be a numeric floor. */
+const RANK_ORDER = { absent: 0, low: 1, medium: 2, high: 3 };
+/** Human + mouse: the pairing that answers "is the mouse a fair surrogate?". */
+const DEFAULT_SPECIES = ["homo_sapiens", "mus_musculus"];
+const DEFAULTS = { tissueLimit: 15, phenotypeLimit: 20, minRank: "low" };
+const inputSchema = z.object({
+    geneSymbol: z
+        .string()
+        .min(1)
+        .describe("HUMAN gene symbol, e.g. 'BRCA1' — one gene per call. Ensembl IDs, mouse symbols and MGI IDs are NOT accepted; the ENSG and the per-species " +
+        "orthologs are resolved for you."),
+    include: z
+        .array(z.enum(["expression", "knockout"]))
+        .min(1)
+        .optional()
+        .describe("Default BOTH — two sides of one judgement, one request each. 'expression': Bgee baseline (healthy, untreated) expression per species and " +
+        "tissue. 'knockout': IMPC mouse loss-of-function phenotype."),
+    species: z
+        .array(z.enum(SUPPORTED_SPECIES))
+        .min(1)
+        .optional()
+        .describe("'expression' only. Default ['homo_sapiens','mus_musculus'] — the surrogate question. Add rat/dog/macaque when the cross-species comparison " +
+        "is the point; dog and macaque coverage is thin, so expect empty entries."),
+    minRank: z
+        .enum(["absent", "low", "medium", "high"])
+        .optional()
+        .describe("'expression' only. Drop tissues below this bucketed rank; default 'low' (drops only not-expressed). Use 'medium'/'high' for just the tissues " +
+        "where the gene is abundant — the usual tissue-of-action question."),
+    tissueLimit: z
+        .number()
+        .int()
+        .min(1)
+        .max(100)
+        .optional()
+        .describe(`'expression' only. Max tissues per species after minRank, highest expression first (default ${DEFAULTS.tissueLimit}, max 100). ` +
+        "`tissueCount`/`tissuesAboveMinRank` give the pre-trim counts."),
+    phenotypeLimit: z
+        .number()
+        .int()
+        .min(1)
+        .max(200)
+        .optional()
+        .describe(`'knockout' only. Max MP phenotype terms, best p-value first (default ${DEFAULTS.phenotypeLimit}, max 200). \`phenotypeCount\` gives the ` +
+        "true total; `organSystems` is never trimmed, so the top-line picture survives."),
+});
+function boundExpression(raw, minRank, tissueLimit) {
+    const floor = RANK_ORDER[minRank];
+    return {
+        humanEnsemblId: raw.humanEnsemblId,
+        bySpecies: raw.bySpecies.map((entry) => {
+            const aboveFloor = entry.tissues.filter((t) => RANK_ORDER[t.rank] >= floor);
+            const ranked = [...aboveFloor].sort((a, b) => (b.expressionScore ?? 0) - (a.expressionScore ?? 0));
+            return {
+                species: entry.species,
+                taxonId: entry.taxonId,
+                ensemblId: entry.ensemblId,
+                tissues: ranked.slice(0, tissueLimit),
+                tissueCount: entry.tissues.length,
+                tissuesAboveMinRank: aboveFloor.length,
+            };
+        }),
+        notFound: raw.notFound,
+    };
+}
+function boundKnockout(raw, phenotypeLimit) {
+    return {
+        mouseMarkerSymbol: raw.mouseMarkerSymbol,
+        mgiAccessionId: raw.mgiAccessionId,
+        viability: raw.viability,
+        viabilityCalls: raw.viabilityCalls,
+        mpTerms: raw.mpTerms.slice(0, phenotypeLimit),
+        organSystems: raw.organSystems,
+        sexDimorphic: raw.sexDimorphic,
+        phenotypeCount: raw.phenotypeCount,
+        phenotypesTrimmed: raw.mpTerms.length > phenotypeLimit,
+    };
+}
+export const genePreclinicalProfileTool = defineTool({
+    id: "gene_preclinical_profile",
+    description: "The in-vivo preclinical profile of ONE human gene — baseline expression (Bgee) and mouse-knockout phenotype (IMPC) in one call. Answers " +
+        "tissue-of-action ('where does this target act?'), model-organism suitability ('is the mouse a fair surrogate?') and essentiality ('what happens " +
+        "when this gene is lost?').\n" +
+        "Expression is BASELINE (healthy, untreated) only — differential expression between conditions is the analysis pipeline's job, never this tool.\n" +
+        "Output is trimmed by default (see `minRank`, `tissueLimit`, `phenotypeLimit`); the accompanying counts distinguish a trimmed list from a sparse one.\n" +
+        "SPARSE OUTPUT IS VALID NO-DATA, not an error — do not retry. A null humanEnsemblId means the symbol did not resolve; a null mouseMarkerSymbol " +
+        "with no phenotype terms means the gene has not been IMPC-phenotyped, which is common.",
+    inputSchema,
+    execute: async ({ geneSymbol, include, species, minRank, tissueLimit, phenotypeLimit }) => {
+        const halves = include ?? ["expression", "knockout"];
+        const wantExpression = halves.includes("expression");
+        const wantKnockout = halves.includes("knockout");
+        const [expressionRaw, knockoutRaw] = await Promise.all([
+            wantExpression ? getMultiSpeciesExpression(geneSymbol, [...(species ?? DEFAULT_SPECIES)]) : Promise.resolve(null),
+            wantKnockout ? getKoPhenotypeProfile(geneSymbol) : Promise.resolve(null),
+        ]);
+        const output = { geneSymbol };
+        if (expressionRaw) {
+            output.expression = boundExpression(expressionRaw, minRank ?? DEFAULTS.minRank, tissueLimit ?? DEFAULTS.tissueLimit);
+        }
+        if (knockoutRaw) {
+            output.knockout = boundKnockout(knockoutRaw, phenotypeLimit ?? DEFAULTS.phenotypeLimit);
+        }
+        return ok(output);
+    },
+});

package/dist/tools/bio/index.d.ts

@@ -1,29 +1,36 @@
 /**
  * Bio barrel — pure external-API bioinformatics & cheminformatics lookups.
  *
- * Leaf tools with no harness dependencies: each wraps an external data source
- * (Ensembl, ChEMBL, PubChem, Open Targets, PubMed, EPA CompTox, …) behind a
- * `defineTool`. Grouped here so the conversation agent imports one barrel
- * rather than ~30 individual files.
+ * Leaf tools with no harness dependencies: each wraps one or more external data
+ * sources (Ensembl, ChEMBL, PubChem, Open Targets, PubMed, EPA CompTox, …)
+ * behind a `defineTool`. Grouped here so the conversation agent imports one
+ * barrel rather than a file per tool.
+ *
+ * The boundary is the QUESTION, not the database. Where several corpora answer
+ * the same question, the corpus is a `sources` parameter and the tool fans out
+ * (`gene_disease_evidence`, `drug_gene_interactions`, `target_safety`,
+ * `lookup_annotation`, `gene_preclinical_profile`); where one database answers
+ * several questions, the endpoint is an `action` parameter (`chembl`,
+ * `pubchem`, `pubmed`, `comptox`, `opentargets`, `search_interactions`).
+ *
+ * Every tool returns a BOUNDED result by default. A default call is sized to be
+ * read, not to be complete: limits are small, verbose fields are opt-in, and
+ * each result carries the true totals (`totalFound`, `totalInteractions`,
+ * `tissueCount`, `outline`, …) so a caller can tell a trimmed answer from a
+ * sparse one and widen deliberately.
  */
 export * from "./search-gene.js";
-export * from "./search-pathway.js";
-export * from "./lookup-go-term.js";
+export * from "./lookup-annotation.js";
 export * from "./search-interactions.js";
 export * from "./pubmed.js";
 export * from "./chembl.js";
 export * from "./pubchem.js";
 export * from "./opentargets.js";
-export * from "./search-pharmgkb.js";
-export * from "./search-faers.js";
+export * from "./gene-disease-evidence.js";
+export * from "./drug-gene-interactions.js";
+export * from "./gene-preclinical-profile.js";
 export * from "./search-clinical-trials.js";
 export * from "./search-geo-datasets.js";
-export * from "./search-dgidb.js";
-export * from "./search-clinvar.js";
-export * from "./search-disgenet.js";
-export * from "./search-drugbank.js";
-export * from "./search-gwas-catalog.js";
-export * from "./search-bgee-expression.js";
-export * from "./get-impc-ko-profile.js";
-export * from "./check-safety-panel.js";
+export * from "./search-faers.js";
+export * from "./target-safety.js";
 export * from "./comptox.js";

package/dist/tools/bio/index.js

@@ -1,36 +1,43 @@
 /**
  * Bio barrel — pure external-API bioinformatics & cheminformatics lookups.
  *
- * Leaf tools with no harness dependencies: each wraps an external data source
- * (Ensembl, ChEMBL, PubChem, Open Targets, PubMed, EPA CompTox, …) behind a
- * `defineTool`. Grouped here so the conversation agent imports one barrel
- * rather than ~30 individual files.
+ * Leaf tools with no harness dependencies: each wraps one or more external data
+ * sources (Ensembl, ChEMBL, PubChem, Open Targets, PubMed, EPA CompTox, …)
+ * behind a `defineTool`. Grouped here so the conversation agent imports one
+ * barrel rather than a file per tool.
+ *
+ * The boundary is the QUESTION, not the database. Where several corpora answer
+ * the same question, the corpus is a `sources` parameter and the tool fans out
+ * (`gene_disease_evidence`, `drug_gene_interactions`, `target_safety`,
+ * `lookup_annotation`, `gene_preclinical_profile`); where one database answers
+ * several questions, the endpoint is an `action` parameter (`chembl`,
+ * `pubchem`, `pubmed`, `comptox`, `opentargets`, `search_interactions`).
+ *
+ * Every tool returns a BOUNDED result by default. A default call is sized to be
+ * read, not to be complete: limits are small, verbose fields are opt-in, and
+ * each result carries the true totals (`totalFound`, `totalInteractions`,
+ * `tissueCount`, `outline`, …) so a caller can tell a trimmed answer from a
+ * sparse one and widen deliberately.
  */
-// Genomics / pathways / ontology
+// Identifier resolution
 export * from "./search-gene.js";
-export * from "./search-pathway.js";
-export * from "./lookup-go-term.js";
+// Functional annotation / networks
+export * from "./lookup-annotation.js";
 export * from "./search-interactions.js";
 // Literature
 export * from "./pubmed.js";
-// ChEMBL
+// Cheminformatics
 export * from "./chembl.js";
-// PubChem
 export * from "./pubchem.js";
-// Translational medicine
+// Target assessment
 export * from "./opentargets.js";
-export * from "./search-pharmgkb.js";
-export * from "./search-faers.js";
+export * from "./gene-disease-evidence.js";
+export * from "./drug-gene-interactions.js";
+export * from "./gene-preclinical-profile.js";
+// Clinical / public-data landscape
 export * from "./search-clinical-trials.js";
 export * from "./search-geo-datasets.js";
-export * from "./search-dgidb.js";
-export * from "./search-clinvar.js";
-export * from "./search-disgenet.js";
-export * from "./search-drugbank.js";
-export * from "./search-gwas-catalog.js";
-// Preclinical
-export * from "./search-bgee-expression.js";
-export * from "./get-impc-ko-profile.js";
-// Off-target liability / EPA CompTox
-export * from "./check-safety-panel.js";
+export * from "./search-faers.js";
+// Safety / toxicology
+export * from "./target-safety.js";
 export * from "./comptox.js";

package/dist/tools/bio/keys.d.ts

@@ -1,3 +1,4 @@
+import type { Logger } from "../../lib/logger.js";
 import type { Tool } from "../define-tool.js";
 /**
  * API keys for the external bio/chem data sources. Threaded from the
@@ -14,23 +15,29 @@ export interface BioToolKeys {
     readonly github?: string;
 }
 /**
- * The NCBI-backed literature tools, built from the shared key slice.
+ * The NCBI-backed literature tool, built from the shared key slice.
  *
  * `pubmed` is the consolidated literature tool (search / details / fulltext
- * behind one `action`); `searchClinvar` remains its own single-endpoint tool.
+ * behind one `action`). ClinVar is no longer its own tool — it is one of the
+ * corpora behind `gene_disease_evidence`, which also needs the NCBI key.
  */
 export declare function createNcbiTools(keys: BioToolKeys): {
     pubmed: Tool;
-    searchClinvar: Tool;
 };
 /**
- * The DrugBank / DisGeNET / EPA CompTox tools, built from the key slice.
+ * The keyed multi-source tools.
  *
- * `comptox` is the consolidated EPA CTX tool (toxcast / hazard / chemical /
- * exposure behind one `dataset`), built over the shared EPA_CCTE key.
+ * Each of these fans out over several corpora and needs more than one key, so
+ * they are built together from the whole slice rather than per source:
+ * `geneDiseaseEvidence` spans the GWAS Catalog (public), DisGeNET (keyed) and
+ * ClinVar (NCBI key), and `drugGeneInteractions` spans DGIdb (public), DrugBank
+ * (keyed) and PharmGKB (public). A tool whose key is absent degrades that one
+ * corpus to `unavailable` in its `perSource` report rather than failing.
  */
-export declare function createChemDbTools(keys: BioToolKeys): {
-    searchDrugbank: Tool;
-    searchDisgenet: Tool;
+export declare function createChemDbTools(keys: BioToolKeys, deps?: {
+    readonly logger?: Logger;
+}): {
+    geneDiseaseEvidence: Tool;
+    drugGeneInteractions: Tool;
     comptox: Tool;
 };

package/dist/tools/bio/keys.js

@@ -1,30 +1,39 @@
-import { createPubMedTool } from "./pubmed.js";
-import { createSearchClinvarTool } from "./search-clinvar.js";
-import { createSearchDrugbankTool } from "./search-drugbank.js";
-import { createSearchDisgenetTool } from "./search-disgenet.js";
 import { createComptoxTool } from "./comptox.js";
+import { createDrugGeneInteractionsTool } from "./drug-gene-interactions.js";
+import { createGeneDiseaseEvidenceTool } from "./gene-disease-evidence.js";
+import { createPubMedTool } from "./pubmed.js";
 /**
- * The NCBI-backed literature tools, built from the shared key slice.
+ * The NCBI-backed literature tool, built from the shared key slice.
  *
  * `pubmed` is the consolidated literature tool (search / details / fulltext
- * behind one `action`); `searchClinvar` remains its own single-endpoint tool.
+ * behind one `action`). ClinVar is no longer its own tool — it is one of the
+ * corpora behind `gene_disease_evidence`, which also needs the NCBI key.
  */
 export function createNcbiTools(keys) {
     return {
         pubmed: createPubMedTool({ ncbiApiKey: keys.ncbi }),
-        searchClinvar: createSearchClinvarTool({ ncbiApiKey: keys.ncbi }),
     };
 }
 /**
- * The DrugBank / DisGeNET / EPA CompTox tools, built from the key slice.
+ * The keyed multi-source tools.
  *
- * `comptox` is the consolidated EPA CTX tool (toxcast / hazard / chemical /
- * exposure behind one `dataset`), built over the shared EPA_CCTE key.
+ * Each of these fans out over several corpora and needs more than one key, so
+ * they are built together from the whole slice rather than per source:
+ * `geneDiseaseEvidence` spans the GWAS Catalog (public), DisGeNET (keyed) and
+ * ClinVar (NCBI key), and `drugGeneInteractions` spans DGIdb (public), DrugBank
+ * (keyed) and PharmGKB (public). A tool whose key is absent degrades that one
+ * corpus to `unavailable` in its `perSource` report rather than failing.
  */
-export function createChemDbTools(keys) {
+export function createChemDbTools(keys, deps = {}) {
     return {
-        searchDrugbank: createSearchDrugbankTool({ apiKey: keys.drugbank }),
-        searchDisgenet: createSearchDisgenetTool({ apiKey: keys.disgenet }),
+        geneDiseaseEvidence: createGeneDiseaseEvidenceTool({
+            disgenetApiKey: keys.disgenet,
+            ...(keys.ncbi ? { ncbiApiKey: keys.ncbi } : {}),
+        }),
+        drugGeneInteractions: createDrugGeneInteractionsTool({
+            drugbankApiKey: keys.drugbank,
+            ...(deps.logger ? { logger: deps.logger } : {}),
+        }),
         comptox: createComptoxTool({ apiKey: keys.epaCcte }),
     };
 }

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

@@ -0,0 +1,48 @@
+/**
+ * lookupAnnotation — one tool over the functional-annotation vocabularies:
+ * Gene Ontology (QuickGO) and the pathway databases (KEGG, Reactome).
+ *
+ * These were two tools asking one question — "what is this gene or term known
+ * to do?" — against different vocabularies. `search_pathway` already treated
+ * the corpus as a parameter (`source: kegg | reactome | both`) rather than a
+ * tool boundary; this extends the same shape to GO.
+ *
+ * The input is a flat object with a `vocabulary` discriminator — not a
+ * `z.discriminatedUnion`, which `defineTool` rejects (model tool calling needs
+ * a top-level `"type":"object"`). Per-vocabulary parameters are optional in the
+ * 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.
+ */
+import { type Pathway } from "../lib/pathway-client.js";
+interface GoTerm {
+    id: string;
+    name: string;
+    definition?: string;
+    aspect?: string;
+}
+interface GoAnnotation {
+    geneProductId: string;
+    goId: string;
+    goName: string;
+    aspect?: string;
+    evidenceCode?: string;
+    qualifier?: string;
+}
+type AnnotationOutput = {
+    terms?: GoTerm[];
+    annotations?: GoAnnotation[];
+} | {
+    pathways: Pathway[];
+};
+export declare const lookupAnnotationTool: import("../define-tool.js").Tool<{
+    vocabulary: "kegg" | "reactome" | "go" | "pathways";
+    query?: string | undefined;
+    goId?: string | undefined;
+    geneProductId?: string | undefined;
+    taxonId?: number | undefined;
+    organism?: string | undefined;
+    includeGenes?: boolean | undefined;
+    limit?: number | undefined;
+}, AnnotationOutput>;
+export {};

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

@@ -0,0 +1,173 @@
+/**
+ * lookupAnnotation — one tool over the functional-annotation vocabularies:
+ * Gene Ontology (QuickGO) and the pathway databases (KEGG, Reactome).
+ *
+ * These were two tools asking one question — "what is this gene or term known
+ * to do?" — against different vocabularies. `search_pathway` already treated
+ * the corpus as a parameter (`source: kegg | reactome | both`) rather than a
+ * tool boundary; this extends the same shape to GO.
+ *
+ * The input is a flat object with a `vocabulary` discriminator — not a
+ * `z.discriminatedUnion`, which `defineTool` rejects (model tool calling needs
+ * a top-level `"type":"object"`). Per-vocabulary parameters are optional in the
+ * 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.
+ */
+import { ok } from "neverthrow";
+import { z } from "zod";
+import { defineTool } from "../define-tool.js";
+import { apiFetchValidated, describeApiError } from "../lib/api-utils.js";
+import { 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;
+// 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
+    .object({
+    results: z
+        .array(z.object({
+        id: z.string().optional(),
+        name: z.string().optional(),
+        definition: z.object({ text: z.string().optional() }).nullable().optional(),
+        aspect: z.string().optional(),
+    }))
+        .optional(),
+})
+    .transform((res) => (res.results ?? []).map((t) => ({
+    id: t.id ?? "",
+    name: t.name ?? "",
+    definition: t.definition?.text ?? undefined,
+    aspect: t.aspect ?? undefined,
+})));
+const GoAnnotationResponseSchema = z
+    .object({
+    results: z
+        .array(z.object({
+        geneProductId: z.string().optional(),
+        goId: z.string().optional(),
+        goName: z.string().optional(),
+        goAspect: z.string().optional(),
+        goEvidence: z.string().optional(),
+        qualifier: z.string().optional(),
+    }))
+        .optional(),
+})
+    .transform((res) => (res.results ?? []).map((a) => ({
+    geneProductId: a.geneProductId ?? "",
+    goId: a.goId ?? "",
+    goName: a.goName ?? "",
+    aspect: a.goAspect ?? undefined,
+    evidenceCode: a.goEvidence ?? undefined,
+    qualifier: a.qualifier ?? undefined,
+})));
+const inputSchema = z
+    .object({
+    vocabulary: z
+        .enum(["go", "kegg", "reactome", "pathways"])
+        .describe("'go' — Gene Ontology via QuickGO (EBI); needs ONE of goId, query, or geneProductId. Returns terms[] { id, name, definition, aspect } " +
+        "and/or annotations[] { geneProductId, goId, goName, aspect, evidenceCode, qualifier }. " +
+        "'kegg' / 'reactome' — one pathway database; needs query. 'pathways' — both, in parallel; needs query. " +
+        "Returns pathways[] { id, name, source, url, genes? }."),
+    query: z
+        .string()
+        .min(1)
+        .optional()
+        .describe("Free-text term. Required for the pathway vocabularies ('apoptosis', 'MAPK signaling'); for 'go' it is one of the three accepted inputs."),
+    goId: z
+        .string()
+        .regex(/^GO:\d{7}$/)
+        .optional()
+        .describe("'go' only. A specific GO term ID, e.g. 'GO:0008150'."),
+    geneProductId: z.string().min(1).optional().describe("'go' only. A UniProt accession, e.g. 'P04637', for that protein's GO annotations."),
+    taxonId: z.number().int().optional().describe("'go' only, with geneProductId. NCBI Taxon ID filter (9606 = human, 10090 = mouse)."),
+    organism: z.string().optional().describe("Pathway vocabularies only. KEGG organism code — 'hsa' (human, default), 'mmu' (mouse); mapped for Reactome."),
+    includeGenes: z
+        .boolean()
+        .optional()
+        .describe("Pathway vocabularies only. Default FALSE — member-gene lists cost one request per pathway and run to hundreds of symbols. True only when " +
+        "you need the members, not the pathway identities."),
+    limit: z
+        .number()
+        .int()
+        .min(1)
+        .max(100)
+        .optional()
+        .describe(`Max records per vocabulary queried (default ${DEFAULT_LIMIT}, max 100); with 'pathways' it applies to KEGG and Reactome separately.`),
+})
+    .refine((d) => d.vocabulary === "go" || (d.query !== undefined && d.query.trim().length > 0), {
+    message: "query is required for vocabulary 'kegg', 'reactome' and 'pathways' — the pathway term to search for",
+    path: ["query"],
+})
+    .refine((d) => d.vocabulary !== "go" || d.goId !== undefined || d.query !== undefined || d.geneProductId !== undefined, {
+    message: "vocabulary 'go' needs at least one of goId (term by ID), query (free-text term search), or geneProductId (a protein's annotations)",
+    path: ["goId"],
+})
+    .refine((d) => d.vocabulary === "go" || (d.goId === undefined && d.geneProductId === undefined && d.taxonId === undefined), {
+    message: "goId, geneProductId and taxonId belong to vocabulary 'go' — the pathway vocabularies take query + organism",
+    path: ["vocabulary"],
+})
+    .refine((d) => d.vocabulary !== "go" || (d.organism === undefined && d.includeGenes === undefined), {
+    message: "organism and includeGenes belong to the pathway vocabularies — vocabulary 'go' filters annotations with taxonId instead",
+    path: ["vocabulary"],
+});
+export const lookupAnnotationTool = defineTool({
+    id: "lookup_annotation",
+    description: "Functional annotation for a gene, protein or term — Gene Ontology (QuickGO) and the pathway databases (KEGG, Reactome) behind one `vocabulary`. " +
+        "Names what a gene is known to do, resolves a GO or pathway identifier, or finds the pathways a term belongs to.\n" +
+        "This is annotation LOOKUP, not enrichment: to test whether a gene SET is over-represented in GO/KEGG/Reactome terms use " +
+        "search_interactions({action:'enrichment'}), which does the statistics.\n" +
+        "An empty terms / annotations / pathways array is valid no-data — do not retry the same input.",
+    inputSchema,
+    execute: async ({ vocabulary, query, goId, geneProductId, taxonId, organism, includeGenes, limit }) => {
+        const cap = limit ?? DEFAULT_LIMIT;
+        if (vocabulary !== "go") {
+            const pathways = await searchPathways(query, {
+                source: vocabulary === "pathways" ? "both" : vocabulary,
+                organism: organism ?? "hsa",
+                includeGenes: includeGenes ?? false,
+                maxResults: cap,
+            });
+            return ok({ pathways });
+        }
+        const tasks = [];
+        let terms;
+        let annotations;
+        if (goId) {
+            tasks.push((async () => {
+                const res = await apiFetchValidated(`${QUICKGO_BASE}/ontology/go/terms/${encodeURIComponent(goId)}`, GoTermResponseSchema, {
+                    headers: HEADERS,
+                });
+                if (res.isErr())
+                    throw new Error(`GO lookup: ${describeApiError(res.error)}`);
+                terms = res.value;
+            })());
+        }
+        if (query) {
+            tasks.push((async () => {
+                const params = new URLSearchParams({ query, limit: String(cap) });
+                const res = await apiFetchValidated(`${QUICKGO_BASE}/ontology/go/search?${params}`, GoTermResponseSchema, { headers: HEADERS });
+                if (res.isErr())
+                    throw new Error(`GO search: ${describeApiError(res.error)}`);
+                const searchTerms = res.value;
+                terms = terms ? [...terms, ...searchTerms] : searchTerms;
+            })());
+        }
+        if (geneProductId) {
+            tasks.push((async () => {
+                const params = new URLSearchParams({ geneProductId, limit: String(cap) });
+                if (taxonId)
+                    params.set("taxonId", String(taxonId));
+                const res = await apiFetchValidated(`${QUICKGO_BASE}/annotation/search?${params}`, GoAnnotationResponseSchema, { headers: HEADERS });
+                if (res.isErr())
+                    throw new Error(`Annotations: ${describeApiError(res.error)}`);
+                annotations = res.value;
+            })());
+        }
+        await Promise.all(tasks);
+        return ok({ terms, annotations });
+    },
+});