@inflexa-ai/harness 0.48.3 → 0.48.5

package/dist/tools/bio/humanbase.js

@@ -0,0 +1,180 @@
+/**
+ * humanbase — the GIANT tissue-specific functional networks of HumanBase.
+ *
+ * One database, three questions, thus one tool with an `action` (the barrel
+ * rule in `index.ts`). The input is a flat object with an `action` enum, not a
+ * `z.discriminatedUnion`, because model tool calling needs a top-level
+ * `"type":"object"`. The argument of each action is optional in the schema, and
+ * a `.refine` makes it required for its action.
+ *
+ * The GIANT version is not an input: the client derives it from the slug.
+ */
+import { ok } from "neverthrow";
+import { z } from "zod";
+import { defineTool } from "../define-tool.js";
+import { getNetwork, getRelevantContexts, HUMANBASE_MAX_NETWORK_GENES, listContexts, } from "../lib/humanbase-client.js";
+const DEFAULTS = { nodeSize: 10, networkEdges: 50, relevantContexts: 10, contexts: 20 };
+const MAX_NODE_SIZE = 50;
+const MAX_RELEVANT_GENES = 200;
+const MAX_LIMIT = 1000;
+/** How many Entrez IDs a call detail names before it switches to a count plus a sample. */
+const IDS_LISTED_IN_FULL = 8;
+const ContextOutputSchema = z.object({
+    slug: z.string(),
+    title: z.string(),
+    giantVersion: z.enum(["v1", "v3"]),
+    term: z.object({ id: z.string(), ontology: z.string() }).nullable(),
+});
+/** The ok value of each action. A script reads it as data, thus the catalog of `run_script` shows this type. */
+const outputSchema = z.union([
+    z
+        .object({
+        found: z.literal(true),
+        context: z.string(),
+        giantVersion: z.enum(["v1", "v3"]),
+        mincut: z.number().nullable(),
+        genes: z.array(z.object({
+            entrez: z.number(),
+            symbol: z.string(),
+            description: z.string(),
+            ensembl: z.string().nullable(),
+            hgnc: z.string().nullable(),
+            query: z.boolean(),
+        })),
+        edges: z.array(z.object({ geneA: z.string(), geneB: z.string(), weight: z.number() })),
+        totalEdges: z.number(),
+        notFound: z.array(z.number()),
+    })
+        .describe("action 'network'"),
+    z.object({ found: z.literal(false), context: z.string() }).describe("action 'network', no network for the request"),
+    z.object({ contexts: z.array(ContextOutputSchema.extend({ score: z.number() })), totalFound: z.number() }).describe("action 'relevant'"),
+    z.object({ contexts: z.array(ContextOutputSchema), totalFound: z.number() }).describe("action 'contexts'"),
+]);
+function listIds(ids) {
+    if (ids === undefined)
+        return "";
+    if (ids.length <= IDS_LISTED_IN_FULL)
+        return ids.join(", ");
+    return `${ids.length} genes: ${ids.slice(0, IDS_LISTED_IN_FULL).join(", ")}, …`;
+}
+const inputSchema = z
+    .object({
+    action: z
+        .enum(["network", "relevant", "contexts"])
+        .describe("'network' (needs entrez, max 30, and context) — the functional subnetwork of the genes in ONE context, plus nodeSize neighbor genes. " +
+        "'relevant' (needs entrez) — the contexts ranked by how relevant each is to the gene set, best first. " +
+        "'contexts' — the context slugs that HumanBase serves, filtered by query."),
+    entrez: z
+        .array(z.number().int().positive())
+        .min(1)
+        .max(MAX_RELEVANT_GENES)
+        .optional()
+        .describe(`Required for 'network' (max ${HUMANBASE_MAX_NETWORK_GENES}) and 'relevant' (max ${MAX_RELEVANT_GENES}). NCBI Entrez Gene IDs as ` +
+        "numbers (672 = BRCA1, 3553 = IL1B) — not symbols, not Ensembl IDs."),
+    context: z
+        .string()
+        .trim()
+        .min(1)
+        .optional()
+        .describe("Required for 'network'. A context slug, copied from a 'contexts' or a 'relevant' result ('blood', 'liver-v3')."),
+    nodeSize: z
+        .number()
+        .int()
+        .min(0)
+        .max(MAX_NODE_SIZE)
+        .optional()
+        .describe(`'network' only: the neighbor genes that HumanBase adds to the query genes (default ${DEFAULTS.nodeSize}, max ${MAX_NODE_SIZE}).`),
+    query: z
+        .string()
+        .optional()
+        .describe("'contexts' only: a case-insensitive substring of the slug or the title ('liver', 'neuron', '-v3'). Omit it to list every context."),
+    limit: z
+        .number()
+        .int()
+        .min(1)
+        .max(MAX_LIMIT)
+        .optional()
+        .describe(`Max rows returned — the edges of 'network' (default ${DEFAULTS.networkEdges}, highest weight first), the contexts of 'relevant' ` +
+        `(default ${DEFAULTS.relevantContexts}, best first), or the contexts of 'contexts' (default ${DEFAULTS.contexts}).`),
+})
+    .refine((d) => d.action === "contexts" || d.entrez !== undefined, {
+    message: "entrez is required when action is 'network' or 'relevant' — pass NCBI Entrez Gene IDs as numbers",
+    path: ["entrez"],
+})
+    .refine((d) => d.action !== "network" || d.context !== undefined, {
+    message: "context is required when action is 'network' — copy a slug from a 'contexts' or a 'relevant' result",
+    path: ["context"],
+})
+    .refine((d) => d.action !== "network" || (d.entrez?.length ?? 0) <= HUMANBASE_MAX_NETWORK_GENES, {
+    message: `action 'network' takes at most ${HUMANBASE_MAX_NETWORK_GENES} entrez IDs — rank a larger set with 'relevant'`,
+    path: ["entrez"],
+})
+    .refine((d) => d.action !== "contexts" || d.entrez === undefined, {
+    message: "entrez does not apply to action 'contexts'",
+    path: ["entrez"],
+})
+    .refine((d) => d.action === "network" || (d.context === undefined && d.nodeSize === undefined), {
+    message: "context and nodeSize apply to action 'network' only",
+    path: ["action"],
+})
+    .refine((d) => d.action === "contexts" || d.query === undefined, {
+    message: "query applies to action 'contexts' only",
+    path: ["action"],
+});
+export const humanbaseTool = defineTool({
+    id: "humanbase",
+    description: "HumanBase — the GIANT functional networks of the Flatiron Institute (Greene et al., Nature Genetics 2015): for each tissue, cell type, or " +
+        "biological process, a genome-wide network whose edge weight is the posterior probability that two genes work together IN THAT CONTEXT, " +
+        "integrated from the expression, interaction and other data of about 14,000 publications. It answers 'which genes act with my genes in the liver?' and " +
+        "'which tissues does my gene set point to?' — questions that the context-free STRING network of search_interactions cannot.\n" +
+        "'network' — the subnetwork of the query genes in one context, plus nodeSize neighbor genes. Each gene carries its Entrez ID, symbol, full name, " +
+        "Ensembl ID, HGNC ID, and `query` (false for an added neighbor). Each edge is { geneA, geneB, weight }, highest weight first; " +
+        "`totalEdges` gives the count before limit (one edge per gene pair, thus it grows with the square of the gene count). `notFound` lists " +
+        "the query IDs that the network does not hold. found: false means HumanBase holds no network for the request: an unknown context slug, " +
+        "or no query gene in the network.\n" +
+        "'relevant' — the contexts ranked by relevance to the gene set, each with a score from 0 to 1. It ranks the v1 contexts only.\n" +
+        "'contexts' — the slugs. Each context has a GIANT version: a slug that ends in '-v3' is a v3 (GIANT 3) network of a tissue or a cell type; " +
+        "every other slug is v1, which holds the tissue contexts (with a BRENDA Tissue Ontology term) and the biological-process contexts " +
+        "(with a GO term). 'global' and 'global-v3' are the networks with no context. The tool sets the version from the slug.\n" +
+        "IDENTIFIERS: NCBI Entrez Gene IDs only, as numbers (672 = BRCA1). Map a symbol or an Ensembl ID with resolve_gene_ids first: the `entrez` " +
+        "field of each of its hits is the input here. " +
+        "HUMAN genes only.\n" +
+        "An empty result (no ranked context, no matched context, found: false) is valid no-data — report it and continue, do not retry.",
+    inputSchema,
+    outputSchema,
+    view: "none",
+    // One tool, three jobs: each action names its own subject — the context and
+    // the genes, the genes, or the filter of the list.
+    describeCall: (input) => {
+        switch (input.action) {
+            case "network":
+                return `network ${input.context ?? ""}: ${listIds(input.entrez)}`;
+            case "relevant":
+                return `relevant: ${listIds(input.entrez)}`;
+            case "contexts":
+                return input.query === undefined ? "contexts" : `contexts ${input.query}`;
+        }
+    },
+    execute: async (input) => {
+        switch (input.action) {
+            case "network": {
+                if (input.entrez === undefined || input.context === undefined)
+                    throw new Error("network requires entrez and context");
+                const network = await getNetwork(input.context, input.entrez, {
+                    nodeSize: input.nodeSize ?? DEFAULTS.nodeSize,
+                    limit: input.limit ?? DEFAULTS.networkEdges,
+                });
+                if (network === null)
+                    return ok({ found: false, context: input.context });
+                return ok({ found: true, ...network });
+            }
+            case "relevant": {
+                if (input.entrez === undefined)
+                    throw new Error("relevant requires entrez");
+                return ok(await getRelevantContexts(input.entrez, { limit: input.limit ?? DEFAULTS.relevantContexts }));
+            }
+            case "contexts":
+                return ok(await listContexts({ query: input.query, limit: input.limit ?? DEFAULTS.contexts }));
+        }
+    },
+});

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

@@ -11,7 +11,7 @@
  * (`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`).
+ * `pubchem`, `pubmed`, `comptox`, `opentargets`, `search_interactions`, `humanbase`).
  *
  * 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
@@ -21,8 +21,10 @@
  */
 export * from "./search-gene.js";
 export * from "./search-protein.js";
+export * from "./resolve-gene-ids.js";
 export * from "./lookup-annotation.js";
 export * from "./search-interactions.js";
+export * from "./humanbase.js";
 export * from "./alphafold-prediction.js";
 export * from "./pubmed.js";
 export * from "./chembl.js";

package/dist/tools/bio/index.js

@@ -11,7 +11,7 @@
  * (`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`).
+ * `pubchem`, `pubmed`, `comptox`, `opentargets`, `search_interactions`, `humanbase`).
  *
  * 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
@@ -22,9 +22,11 @@
 // Identifier resolution
 export * from "./search-gene.js";
 export * from "./search-protein.js";
+export * from "./resolve-gene-ids.js";
 // Functional annotation / networks
 export * from "./lookup-annotation.js";
 export * from "./search-interactions.js";
+export * from "./humanbase.js";
 // Structural biology
 export * from "./alphafold-prediction.js";
 // Literature

package/dist/tools/bio/resolve-gene-ids.d.ts

@@ -0,0 +1,13 @@
+/**
+ * resolveGeneIds — map gene identifiers across the HGNC symbol, the Entrez Gene
+ * ID, the Ensembl gene ID, and the UniProt accession, through MyGene.info.
+ *
+ * `search_gene` answers with Ensembl records only. A source keyed on Entrez IDs
+ * (`humanbase`) needs the mapping step that this tool gives, and in a script the
+ * `entrez` field of a hit goes straight into the `entrez` argument of such a tool.
+ */
+import { type GeneIdResolution } from "../lib/mygene-client.js";
+export declare const resolveGeneIdsTool: import("../define-tool.js").Tool<{
+    identifiers: string[];
+    species: string;
+}, GeneIdResolution>;

package/dist/tools/bio/resolve-gene-ids.js

@@ -0,0 +1,67 @@
+/**
+ * resolveGeneIds — map gene identifiers across the HGNC symbol, the Entrez Gene
+ * ID, the Ensembl gene ID, and the UniProt accession, through MyGene.info.
+ *
+ * `search_gene` answers with Ensembl records only. A source keyed on Entrez IDs
+ * (`humanbase`) needs the mapping step that this tool gives, and in a script the
+ * `entrez` field of a hit goes straight into the `entrez` argument of such a tool.
+ */
+import { ok } from "neverthrow";
+import { z } from "zod";
+import { defineTool } from "../define-tool.js";
+import { MYGENE_HITS_PER_ID, resolveGeneIds } from "../lib/mygene-client.js";
+const MAX_IDENTIFIERS = 200;
+/**
+ * How many identifiers a detail names before it switches to a count plus a
+ * sample. Eight identifiers of typical length stay well inside the emit-site
+ * cap, so the listed form is never the thing that trips it.
+ */
+const IDENTIFIERS_LISTED_IN_FULL = 8;
+/** The ok value. A script reads it as data, thus the catalog of `run_script` shows this type. */
+const outputSchema = z.object({
+    genes: z.array(z.object({
+        query: z.string(),
+        symbol: z.string().nullable(),
+        name: z.string().nullable(),
+        entrez: z.number().nullable(),
+        ensembl: z.array(z.string()),
+        uniprot: z.array(z.string()),
+    })),
+    notFound: z.array(z.string()),
+    ambiguous: z.array(z.string()),
+    truncated: z.array(z.string()),
+});
+export const resolveGeneIdsTool = defineTool({
+    id: "resolve_gene_ids",
+    description: "Map gene identifiers across the HGNC symbol, the NCBI Entrez Gene ID, the Ensembl gene ID and the reviewed UniProt accession, through " +
+        "MyGene.info — the ID step for a tool keyed on an ID that search_gene does not give, such as the Entrez IDs of humanbase.\n" +
+        "ACCEPTED IDENTIFIERS, mixed freely in one call of up to 200: a current symbol ('BRCA1', any case), an Entrez ID ('672'), an Ensembl gene " +
+        "ID ('ENSG00000012048'), or a UniProt accession ('P38398'). An old or informal symbol does not resolve, because an alias can name several " +
+        "current genes: resolve it to its current HGNC symbol first.\n" +
+        "Each hit carries the `query` that it answers, `symbol`, `name` (the full gene name), `entrez` (a number, or null for a gene with no " +
+        "Entrez record), `ensembl` and `uniprot` (arrays: several Ensembl IDs mean copies on alternate haplotypes or strains, and their order " +
+        "carries no rank). `notFound` lists each identifier with no gene. `ambiguous` lists each identifier with more than one gene, and each of " +
+        "those genes is in `genes` — a UniProt accession shared by a family of genes gives every member. An identifier gives at most " +
+        `${MYGENE_HITS_PER_ID} genes, and \`truncated\` lists each identifier that had more.\n` +
+        "`species` takes a common name ('human', the default, 'mouse', 'rat', 'zebrafish') or an NCBI Taxonomy ID as a string ('9606').\n" +
+        "notFound is valid no-data — report it and continue, do not retry unchanged.",
+    inputSchema: z.object({
+        identifiers: z
+            .array(z.string())
+            .min(1)
+            .max(MAX_IDENTIFIERS)
+            .describe(`Gene identifiers to map, mixed freely, max ${MAX_IDENTIFIERS} (e.g. ['BRCA1', '7157', 'ENSG00000146648', 'P38398']).`),
+        species: z.string().trim().min(1).default("human").describe("A common name ('human', 'mouse') or an NCBI Taxonomy ID as a string ('9606')."),
+    }),
+    outputSchema,
+    view: "none",
+    // The identifiers are the call. A large batch is summarized here rather than
+    // left to the emit-site cap: that cap cuts at a character, so a 200-symbol
+    // join arrives ending in `TP5` — a fragment that reads as a real symbol and
+    // says nothing about how many were dropped. The count leads, so a batch is
+    // legible as a batch even when the sample after it is itself trimmed.
+    describeCall: ({ identifiers }) => identifiers.length <= IDENTIFIERS_LISTED_IN_FULL
+        ? identifiers.join(", ")
+        : `${identifiers.length} genes: ${identifiers.slice(0, IDENTIFIERS_LISTED_IN_FULL).join(", ")}, …`,
+    execute: async ({ identifiers, species }) => ok(await resolveGeneIds(identifiers, species)),
+});

package/dist/tools/lib/humanbase-client.d.ts

@@ -0,0 +1,215 @@
+/**
+ * Pure async client functions for HumanBase (Flatiron Institute), which serves
+ * the GIANT functional networks: one network for each tissue, cell type, or
+ * biological-process context (Greene et al., Nature Genetics 2015).
+ *
+ * Absence policy: HumanBase keeps the key of an absent value and sends an
+ * explicit `null` — `mincut` of a v3 network, and `term` and `version` of a
+ * context. Thus a maybe-absent field carries `.nullable()`, not `.optional()`.
+ *
+ * HumanBase asks for no key and no caller identity. The shared
+ * `HARNESS_USER_AGENT` of `apiFetch` names the caller.
+ *
+ * The GIANT version is a property of the slug: each v3 slug ends in `-v3`, and
+ * no v1 slug does. The network endpoint refuses a `giant_version` that disagrees
+ * with the slug (a 400 for a v3 slug under v1, a 404 for a v1 slug under v3),
+ * thus the client derives the version from the slug and no caller states it.
+ *
+ * Only an HTTP 404 is an expected absence (an unknown slug, or no queried gene in
+ * the network). A 400 carries the message of a refused request, thus it is not
+ * read as "nothing there" — `isUnexpectedApiError` would read every 4xx that way.
+ */
+import { z } from "zod";
+/** The network endpoint refuses a larger query gene set with a 400. */
+export declare const HUMANBASE_MAX_NETWORK_GENES = 30;
+export type GiantVersion = "v1" | "v3";
+/** The GIANT version of a context slug. */
+export declare function giantVersionOf(slug: string): GiantVersion;
+export type HumanBaseContext = {
+    /** The key of the network endpoint: 'blood', 'liver-v3', 'double-strand-break-repair'. */
+    slug: string;
+    title: string;
+    giantVersion: GiantVersion;
+    /**
+     * The ontology term of a v1 context: a BRENDA Tissue Ontology term for a tissue,
+     * or a GO biological-process term for a process. A v3 context carries none.
+     */
+    term: {
+        id: string;
+        ontology: string;
+    } | null;
+};
+export type HumanBaseScoredContext = HumanBaseContext & {
+    score: number;
+};
+export type HumanBaseGene = {
+    entrez: number;
+    symbol: string;
+    description: string;
+    ensembl: string | null;
+    hgnc: string | null;
+    /** True for a gene of the query, false for a neighbor that HumanBase added. */
+    query: boolean;
+};
+export type HumanBaseEdge = {
+    geneA: string;
+    geneB: string;
+    /** The posterior probability of a functional relationship in this context. */
+    weight: number;
+};
+export type HumanBaseNetwork = {
+    context: string;
+    giantVersion: GiantVersion;
+    /** The `mincut` value of HumanBase for the subnetwork. Null for a v3 network. */
+    mincut: number | null;
+    genes: HumanBaseGene[];
+    edges: HumanBaseEdge[];
+    /** The edge count before `limit`. */
+    totalEdges: number;
+    /** The queried Entrez IDs that the answer does not hold. */
+    notFound: number[];
+};
+/** One row of `GET /api/integrations/`. */
+export declare const HumanBaseIntegrationSchema: z.ZodPipe<z.ZodObject<{
+    slug: z.ZodString;
+    context: z.ZodObject<{
+        title: z.ZodString;
+        term: z.ZodNullable<z.ZodObject<{
+            identifier: z.ZodString;
+            database: z.ZodObject<{
+                name: z.ZodString;
+            }, z.core.$strip>;
+        }, z.core.$strip>>;
+        version: z.ZodNullable<z.ZodObject<{
+            identifier: z.ZodString;
+        }, z.core.$strip>>;
+    }, z.core.$strip>;
+}, z.core.$strip>, z.ZodTransform<HumanBaseContext, {
+    slug: string;
+    context: {
+        title: string;
+        term: {
+            identifier: string;
+            database: {
+                name: string;
+            };
+        } | null;
+        version: {
+            identifier: string;
+        } | null;
+    };
+}>>;
+/** One row of `POST /api/integrations/relevant/`. */
+export declare const HumanBaseRelevantSchema: z.ZodPipe<z.ZodObject<{
+    slug: z.ZodString;
+    context: z.ZodObject<{
+        title: z.ZodString;
+        term: z.ZodNullable<z.ZodObject<{
+            identifier: z.ZodString;
+            database: z.ZodObject<{
+                name: z.ZodString;
+            }, z.core.$strip>;
+        }, z.core.$strip>>;
+        version: z.ZodNullable<z.ZodObject<{
+            identifier: z.ZodString;
+        }, z.core.$strip>>;
+    }, z.core.$strip>;
+    score: z.ZodNumber;
+}, z.core.$strip>, z.ZodTransform<HumanBaseScoredContext, {
+    slug: string;
+    context: {
+        title: string;
+        term: {
+            identifier: string;
+            database: {
+                name: string;
+            };
+        } | null;
+        version: {
+            identifier: string;
+        } | null;
+    };
+    score: number;
+}>>;
+/** The body of `GET /api/integrations/{slug}/network/`, with each edge resolved to the symbols of its genes. */
+export declare const HumanBaseNetworkSchema: z.ZodPipe<z.ZodObject<{
+    mincut: z.ZodNullable<z.ZodNumber>;
+    genes: z.ZodArray<z.ZodObject<{
+        entrez: z.ZodNumber;
+        standard_name: z.ZodString;
+        description: z.ZodString;
+        xrefs: z.ZodArray<z.ZodObject<{
+            xrid: z.ZodString;
+            crossrefdb: z.ZodObject<{
+                name: z.ZodString;
+            }, z.core.$strip>;
+        }, z.core.$strip>>;
+        query: z.ZodBoolean;
+    }, z.core.$strip>>;
+    edges: z.ZodArray<z.ZodObject<{
+        source: z.ZodNumber;
+        target: z.ZodNumber;
+        weight: z.ZodNumber;
+    }, z.core.$strip>>;
+}, z.core.$strip>, z.ZodTransform<{
+    mincut: number | null;
+    genes: HumanBaseGene[];
+    edges: HumanBaseEdge[];
+}, {
+    mincut: number | null;
+    genes: {
+        entrez: number;
+        standard_name: string;
+        description: string;
+        xrefs: {
+            xrid: string;
+            crossrefdb: {
+                name: string;
+            };
+        }[];
+        query: boolean;
+    }[];
+    edges: {
+        source: number;
+        target: number;
+        weight: number;
+    }[];
+}>>;
+/**
+ * Each context that HumanBase serves, filtered by a case-insensitive substring of
+ * the slug or the title. The list holds about 600 rows, thus `limit` trims it and
+ * `totalFound` reports the count of the filtered list.
+ */
+export declare function listContexts(options?: {
+    query?: string;
+    limit?: number;
+}): Promise<{
+    contexts: HumanBaseContext[];
+    totalFound: number;
+}>;
+/**
+ * The contexts ranked by their relevance to a gene set, best first.
+ *
+ * HumanBase ranks the v1 contexts only, and it gives an empty list when it knows
+ * none of the genes. The endpoint takes each Entrez ID as a JSON string and
+ * answers a JSON number with a 500.
+ */
+export declare function getRelevantContexts(entrez: readonly number[], options?: {
+    limit?: number;
+}): Promise<{
+    contexts: HumanBaseScoredContext[];
+    totalFound: number;
+}>;
+/**
+ * The functional subnetwork of the query genes in one context, plus `nodeSize`
+ * neighbor genes that HumanBase adds. The answer holds an edge for each gene
+ * pair, thus the edge count grows with the square of the gene count: `limit`
+ * trims the weight-sorted edges, and `totalEdges` reports the true count.
+ *
+ * Gives `null` on an HTTP 404: the slug is unknown, or no query gene is in the
+ * network.
+ */
+export declare function getNetwork(slug: string, entrez: readonly number[], options?: {
+    nodeSize?: number;
+    limit?: number;
+}): Promise<HumanBaseNetwork | null>;