@stackfactor/agent-utils 1.2.20 → 1.3.2

package/dist/cjs/tavily.js

@@ -0,0 +1,404 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.buildTavilyTools = exports.assertTavilyUsable = exports.getTavilyOptions = void 0;
+const langchain_1 = require("langchain");
+const zod_1 = require("zod");
+const const_js_1 = __importDefault(require("./const.js"));
+const errorHandling_js_1 = __importDefault(require("./errorHandling.js"));
+const logger_js_1 = __importDefault(require("./logger.js"));
+const runtimeContext_js_1 = require("./runtimeContext.js");
+const TAVILY_API_BASE = "https://api.tavily.com";
+/** Tavily list price per credit, used when the integration defines no rate. */
+const DEFAULT_CREDIT_COST_USD = 0.008;
+/**
+ * Context budgets, in characters, applied to everything a tool hands back to
+ * the model. Tavily returns whatever the page holds, and unlike a provider's
+ * native search there is nothing between its response and the context window,
+ * so these caps are the only thing standing between one `extract` call and a
+ * 100-page PDF. Roughly four characters per token: 60k ≈ 15k tokens per URL,
+ * 150k ≈ 37k tokens per call.
+ */
+const DEFAULT_MAX_CHARS_PER_URL = 60_000;
+const DEFAULT_MAX_CHARS_TOTAL = 150_000;
+/** Kept deliberately small — search finds documents, `extract` reads them. */
+const DEFAULT_MAX_RESULTS = 5;
+/** Tavily's own default when a query is supplied. */
+const DEFAULT_CHUNKS_PER_SOURCE = 3;
+/** Crawl returns full content per page, so the page count is the cost driver. */
+const DEFAULT_CRAWL_LIMIT = 10;
+/** Seconds. Tavily's own per-request default; crawls legitimately run long. */
+const DEFAULT_TIMEOUT_SECONDS = 60;
+const DEFAULT_CRAWL_TIMEOUT_SECONDS = 120;
+/**
+ * Normalizes `config.tavily` into an options object, returning `null` when the
+ * Tavily tools are off so callers can use it as the single enablement gate.
+ * @param config - The integration config object
+ * @returns Normalized options, or `null` when Tavily is not enabled
+ */
+const getTavilyOptions = (config) => {
+    const tavily = config?.tavily;
+    if (!tavily)
+        return null;
+    return tavily === true ? {} : tavily;
+};
+exports.getTavilyOptions = getTavilyOptions;
+/**
+ * Fails fast on the two ways a Tavily config cannot work. Tavily tools are
+ * executed by the agent loop in this process, so outside agentic mode the model
+ * would be handed tools whose calls nothing answers: the turn ends silently and
+ * looks like the model ignored them. Called once at config time rather than
+ * discovered per request.
+ * @param config - The integration config object
+ * @param options - Normalized options from `getTavilyOptions`
+ */
+const assertTavilyUsable = (config, options) => {
+    if (config?.agentic !== true) {
+        throw errorHandling_js_1.default.create(const_js_1.default.HTTP_CODES.BAD_REQUEST, "Tavily tools run client-side and are only executed by the agent loop; set config.agentic to true to use them.");
+    }
+    if (!config?.tavilyAPIKey) {
+        throw errorHandling_js_1.default.create(const_js_1.default.HTTP_CODES.INTERNAL_SERVER_ERROR, "Tavily tools are enabled but config.tavilyAPIKey is missing.");
+    }
+    const unknown = (options.tools || []).filter((name) => !["search", "extract", "crawl", "map"].includes(name));
+    if (unknown.length > 0) {
+        throw errorHandling_js_1.default.create(const_js_1.default.HTTP_CODES.BAD_REQUEST, `Unknown Tavily tool(s): ${unknown.join(", ")}. Valid values are search, extract, crawl, map.`);
+    }
+};
+exports.assertTavilyUsable = assertTavilyUsable;
+/** Retries for a transient (429/5xx) Tavily response before giving up. */
+const MAX_TAVILY_RETRIES = 2;
+/** Base delay for retry backoff; doubled on each subsequent attempt. */
+const RETRY_BASE_DELAY_MS = 500;
+const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+/**
+ * POSTs to one Tavily endpoint. The REST API is snake_case while the published
+ * SDK's option names are camelCase, so bodies here are written in the wire
+ * format the API actually accepts. `include_usage` is always set: the response
+ * then carries the exact credits the call consumed, which is what the tracker
+ * bills instead of an estimate. `timeout` is always set from the caller's
+ * budget so Tavily's own (shorter) per-endpoint defaults don't cut a call off
+ * before the time this library already told the caller it had.
+ *
+ * Rate-limit (429) and server (5xx) responses are retried with exponential
+ * backoff — everything else, including a caller-cancelled request, fails
+ * immediately.
+ * @param endpoint - The Tavily endpoint name, e.g. `"search"`
+ * @param body - Request body in the API's snake_case form; `undefined` values
+ *   are dropped so Tavily applies its own defaults
+ * @param apiKey - The Tavily API key
+ * @param timeoutSeconds - Per-request timeout forwarded to Tavily
+ * @returns The parsed JSON response
+ */
+const callTavily = async (endpoint, body, apiKey, timeoutSeconds) => {
+    const payload = {
+        include_usage: true,
+        timeout: timeoutSeconds,
+    };
+    for (const [key, value] of Object.entries(body)) {
+        if (value !== undefined && value !== null)
+            payload[key] = value;
+    }
+    for (let attempt = 0;; attempt++) {
+        let response;
+        try {
+            response = await fetch(`${TAVILY_API_BASE}/${endpoint}`, {
+                method: "POST",
+                headers: {
+                    "Content-Type": "application/json",
+                    Authorization: `Bearer ${apiKey}`,
+                },
+                body: JSON.stringify(payload),
+                // Honour caller cancellation the same way the LLM calls do, so an
+                // abandoned run stops paying for in-flight crawls.
+                signal: (0, runtimeContext_js_1.getAbortSignal)() ?? undefined,
+            });
+        }
+        catch (err) {
+            throw errorHandling_js_1.default.create(const_js_1.default.HTTP_CODES.INTERNAL_SERVER_ERROR, `Tavily ${endpoint} request failed: ${err?.message || String(err)}`);
+        }
+        if (response.ok)
+            return response.json();
+        const retryable = response.status === 429 || response.status >= 500;
+        if (retryable && attempt < MAX_TAVILY_RETRIES) {
+            await sleep(RETRY_BASE_DELAY_MS * 2 ** attempt);
+            continue;
+        }
+        const detail = await response.text().catch(() => "");
+        throw errorHandling_js_1.default.create(const_js_1.default.HTTP_CODES.INTERNAL_SERVER_ERROR, `Tavily ${endpoint} returned ${response.status}: ${detail.slice(0, 500)}`);
+    }
+};
+/**
+ * Adds one Tavily call's credits to the tracker and records the URLs it
+ * returned. Credits come from the response's own `usage` block, priced with the
+ * `tavily-credit-costs` constant (USD per credit) and accumulated under
+ * `tavilyCredits`. Sources land on `tracker.webSearchSources`, deduplicated by
+ * URL across the whole run, so callers have the citation list Tavily's terms
+ * require when this output is shown to end users.
+ * @param tracker - The caller's usage accumulator; no-ops when absent
+ * @param config - Config object carrying the `tavily-credit-costs` constant
+ * @param credits - Credits reported by the Tavily response
+ * @param sources - URLs (and titles where known) the call returned
+ */
+const recordTavilyUsage = (tracker, config, credits, sources) => {
+    if (!tracker)
+        return;
+    if (typeof tracker.cost !== "number")
+        tracker.cost = 0;
+    if (!tracker.tokens || typeof tracker.tokens !== "object")
+        tracker.tokens = {};
+    if (Number.isFinite(credits) && credits > 0) {
+        const configured = Number(config?.["tavily-credit-costs"]);
+        const rate = Number.isFinite(configured)
+            ? configured
+            : DEFAULT_CREDIT_COST_USD;
+        const addedCost = credits * rate;
+        if (Number.isFinite(addedCost) && addedCost > 0)
+            tracker.cost += addedCost;
+        tracker.tokens.tavilyCredits =
+            (tracker.tokens.tavilyCredits || 0) + credits;
+    }
+    if (sources.length === 0)
+        return;
+    const existing = tracker.webSearchSources || (tracker.webSearchSources = []);
+    for (const source of sources) {
+        if (!source?.url)
+            continue;
+        if (!existing.some((entry) => entry.url === source.url)) {
+            existing.push(source);
+        }
+    }
+};
+/**
+ * Trims one document to whatever the per-URL and per-call budgets allow,
+ * appending a note when anything was cut.
+ * @param text - The document text
+ * @param budget - Mutable budget for the current tool call
+ * @returns The text, truncated with an inline note when over budget
+ */
+const applyBudget = (text, budget) => {
+    const body = typeof text === "string" ? text : "";
+    if (!body)
+        return "";
+    const allowance = Math.min(budget.perUrl, budget.remaining);
+    if (allowance <= 0) {
+        return "[omitted: this call's character budget is exhausted — request fewer URLs at a time]";
+    }
+    if (body.length <= allowance) {
+        budget.remaining -= body.length;
+        return body;
+    }
+    budget.remaining -= allowance;
+    return `${body.slice(0, allowance)}\n\n[truncated: ${allowance.toLocaleString()} of ${body.length.toLocaleString()} characters shown — narrow the query or request fewer URLs to see the parts that matter]`;
+};
+/**
+ * Renders documents for the model as titled markdown sections. Tavily's own
+ * result objects carry `score`, `published_date`, `favicon` and `id` alongside
+ * the content; none of that informs an answer, so only the title, URL and text
+ * are forwarded and the rest is dropped rather than billed as input tokens.
+ * @param documents - Documents to render
+ * @param budget - Mutable budget for the current tool call
+ * @returns A markdown string, or a not-found notice when there is nothing
+ */
+const renderDocuments = (documents, budget) => {
+    const sections = [];
+    for (const document of documents) {
+        const body = applyBudget(document.text, budget);
+        if (!body)
+            continue;
+        const heading = document.title
+            ? `## ${document.title}\n${document.url}`
+            : `## ${document.url}`;
+        sections.push(`${heading}\n\n${body}`);
+    }
+    if (sections.length === 0)
+        return "No content was returned.";
+    return sections.join("\n\n---\n\n");
+};
+/**
+ * Builds the LangChain tools for the Tavily endpoints named in
+ * `options.tools`, closed over the run's config and usage tracker. Tools are
+ * created per run rather than shared, because each one bills into that run's
+ * tracker.
+ *
+ * `web_extract` covers both of the reading modes Tavily supports through one
+ * tool: with a `query` the API returns only the matching chunks of each page,
+ * and without one it returns the whole document. Splitting that into two tools
+ * would duplicate the description tokens on every request to express a
+ * distinction the API already makes with one optional field.
+ *
+ * @param config - Config object carrying `tavilyAPIKey` and cost constants
+ * @param options - Normalized options from `getTavilyOptions`
+ * @param usageTracker - Optional accumulator billed for every Tavily call
+ * @returns LangChain tool instances to append to the agent's tool list
+ */
+const buildTavilyTools = (config, options, usageTracker = null) => {
+    const apiKey = config.tavilyAPIKey;
+    const enabled = options.tools || ["search", "extract"];
+    const format = options.format || "markdown";
+    const maxCharsPerUrl = options.maxCharsPerUrl ?? DEFAULT_MAX_CHARS_PER_URL;
+    const maxCharsTotal = options.maxCharsTotal ?? DEFAULT_MAX_CHARS_TOTAL;
+    const crawlLimit = options.crawlLimit ?? DEFAULT_CRAWL_LIMIT;
+    const newBudget = () => ({
+        remaining: maxCharsTotal,
+        perUrl: maxCharsPerUrl,
+    });
+    const tools = [];
+    if (enabled.includes("search")) {
+        tools.push((0, langchain_1.tool)(async ({ query, maxResults }) => {
+            const data = await callTavily("search", {
+                query,
+                search_depth: options.searchDepth,
+                max_results: maxResults || options.maxResults || DEFAULT_MAX_RESULTS,
+                include_domains: options.includeDomains,
+                exclude_domains: options.excludeDomains,
+                // Snippets only. Full page text is `web_extract`'s job, and
+                // asking for it here would pay for every result to find one.
+                include_raw_content: false,
+            }, apiKey, DEFAULT_TIMEOUT_SECONDS);
+            const results = data?.results || [];
+            recordTavilyUsage(usageTracker, config, data?.usage?.credits || 0, results.map((result) => ({
+                url: result?.url,
+                ...(result?.title ? { title: result.title } : {}),
+            })));
+            if (results.length === 0)
+                return "No results found.";
+            const budget = newBudget();
+            return renderDocuments(results.map((result) => ({
+                url: result?.url,
+                title: result?.title,
+                text: result?.content || "",
+            })), budget);
+        }, {
+            name: "web_search",
+            description: "Search the web and return short relevant snippets with their URLs. Use this to find documents; to read one in full or to pull specific passages from it, follow up with web_extract on the URL.",
+            schema: zod_1.z.object({
+                query: zod_1.z.string().describe("The search query."),
+                maxResults: zod_1.z
+                    .number()
+                    .int()
+                    .min(1)
+                    .max(20)
+                    .optional()
+                    .describe("How many results to return. Defaults to 5."),
+            }),
+        }));
+    }
+    if (enabled.includes("extract")) {
+        tools.push((0, langchain_1.tool)(async ({ urls, query }) => {
+            const data = await callTavily("extract", {
+                urls,
+                extract_depth: options.extractDepth,
+                format,
+                // `query` switches the API from whole-document extraction to
+                // returning only the chunks that match it.
+                query: query || undefined,
+                chunks_per_source: query
+                    ? options.chunksPerSource || DEFAULT_CHUNKS_PER_SOURCE
+                    : undefined,
+            }, apiKey, DEFAULT_TIMEOUT_SECONDS);
+            const results = data?.results || [];
+            recordTavilyUsage(usageTracker, config, data?.usage?.credits || 0, results.map((result) => ({
+                url: result?.url,
+                ...(result?.title ? { title: result.title } : {}),
+            })));
+            const budget = newBudget();
+            let rendered = renderDocuments(results.map((result) => ({
+                url: result?.url,
+                title: result?.title,
+                text: result?.raw_content || "",
+            })), budget);
+            // Surface per-URL failures: the model asked for these pages, and
+            // silently returning fewer than requested invites it to treat a
+            // fetch failure as an absence of content.
+            const failed = data?.failed_results || [];
+            if (failed.length > 0) {
+                const lines = failed
+                    .map((entry) => `- ${entry?.url}: ${entry?.error}`)
+                    .join("\n");
+                rendered += `\n\n---\n\nFailed to extract:\n${lines}`;
+            }
+            return rendered;
+        }, {
+            name: "web_extract",
+            description: "Read the content of specific URLs. Pass a query to get back only the passages relevant to it — much cheaper and usually sufficient. Omit the query to retrieve the whole document, which is appropriate when you need its full structure. Long documents are truncated, and the result says so when that happens.",
+            schema: zod_1.z.object({
+                urls: zod_1.z
+                    .array(zod_1.z.string())
+                    .min(1)
+                    .max(20)
+                    .describe("The URLs to read."),
+                query: zod_1.z
+                    .string()
+                    .optional()
+                    .describe("What to look for in each page. Omit to retrieve whole documents."),
+            }),
+        }));
+    }
+    if (enabled.includes("map")) {
+        tools.push((0, langchain_1.tool)(async ({ url, instructions }) => {
+            const data = await callTavily("map", { url, instructions: instructions || undefined, limit: crawlLimit }, apiKey, DEFAULT_TIMEOUT_SECONDS);
+            const urls = data?.results || [];
+            recordTavilyUsage(usageTracker, config, data?.usage?.credits || 0, urls.map((entry) => ({ url: entry })));
+            if (urls.length === 0)
+                return "No URLs found.";
+            return `Found ${urls.length} URL(s) under ${data?.base_url || url}:\n${urls
+                .map((entry) => `- ${entry}`)
+                .join("\n")}`;
+        }, {
+            name: "web_map",
+            description: "List the URLs available under a site or section, without retrieving any page content. Use this to discover what a documentation site or document library holds, then read the ones you want with web_extract.",
+            schema: zod_1.z.object({
+                url: zod_1.z.string().describe("The site or section URL to map."),
+                instructions: zod_1.z
+                    .string()
+                    .optional()
+                    .describe("Plain-language description of the pages worth including."),
+            }),
+        }));
+    }
+    if (enabled.includes("crawl")) {
+        tools.push((0, langchain_1.tool)(async ({ url, instructions, limit }) => {
+            const data = await callTavily("crawl", {
+                url,
+                instructions: instructions || undefined,
+                limit: Math.min(limit || crawlLimit, crawlLimit),
+                extract_depth: options.extractDepth,
+                format,
+            }, apiKey, DEFAULT_CRAWL_TIMEOUT_SECONDS);
+            const results = data?.results || [];
+            recordTavilyUsage(usageTracker, config, data?.usage?.credits || 0, results.map((result) => ({ url: result?.url })));
+            const budget = newBudget();
+            return renderDocuments(results.map((result) => ({
+                url: result?.url,
+                title: result?.title,
+                text: result?.raw_content || "",
+            })), budget);
+        }, {
+            name: "web_crawl",
+            description: "Follow links from a starting URL and return the content of the pages found. This returns full page content for every page visited, so prefer web_map followed by web_extract when you only need a few pages. Use the instructions argument to describe which pages matter.",
+            schema: zod_1.z.object({
+                url: zod_1.z.string().describe("The URL to start crawling from."),
+                instructions: zod_1.z
+                    .string()
+                    .optional()
+                    .describe("Plain-language description of the pages worth following."),
+                limit: zod_1.z
+                    .number()
+                    .int()
+                    .min(1)
+                    .optional()
+                    .describe("Maximum pages to return; capped by the configured crawl limit."),
+            }),
+        }));
+    }
+    logger_js_1.default.log(null, logger_js_1.default.levels.info, `Tavily tools enabled: ${tools.map((entry) => entry.name).join(", ")}`);
+    return tools;
+};
+exports.buildTavilyTools = buildTavilyTools;
+exports.default = {
+    assertTavilyUsable: exports.assertTavilyUsable,
+    buildTavilyTools: exports.buildTavilyTools,
+    getTavilyOptions: exports.getTavilyOptions,
+};

package/dist/esm/index.d.ts

@@ -9,7 +9,8 @@ export { constants };
 export { errorHandling, AppError };
 export type { ParsedError } from "./errorHandling.js";
 export { langChain };
-export type { UsageTracker, WebSearchConfig } from "./langChain.js";
+export type { UsageTracker } from "./langChain.js";
+export type { TavilyConfig, TavilyToolName } from "./tavily.js";
 export { logger };
 export { serve };
 export { callAgent };

package/dist/esm/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,SAAS,MAAM,YAAY,CAAC;AACnC,OAAO,aAAa,EAAE,EAAE,QAAQ,EAAE,MAAM,oBAAoB,CAAC;AAC7D,OAAO,SAAS,MAAM,gBAAgB,CAAC;AACvC,OAAO,MAAM,MAAM,aAAa,CAAC;AACjC,OAAO,EAAE,KAAK,EAAE,MAAM,YAAY,CAAC;AACnC,OAAO,EAAE,SAAS,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AACpD,OAAO,KAAK,cAAc,MAAM,qBAAqB,CAAC;AAEtD,OAAO,EAAE,SAAS,EAAE,CAAC;AAErB,OAAO,EAAE,aAAa,EAAE,QAAQ,EAAE,CAAC;AAEnC,YAAY,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAC;AAEtD,OAAO,EAAE,SAAS,EAAE,CAAC;AAErB,YAAY,EAAE,YAAY,EAAE,eAAe,EAAE,MAAM,gBAAgB,CAAC;AAEpE,OAAO,EAAE,MAAM,EAAE,CAAC;AAElB,OAAO,EAAE,KAAK,EAAE,CAAC;AAEjB,OAAO,EAAE,SAAS,EAAE,CAAC;AAErB,OAAO,EAAE,UAAU,EAAE,CAAC;AAEtB,YAAY,EACV,mBAAmB,EACnB,gBAAgB,EAChB,iBAAiB,EACjB,WAAW,GACZ,MAAM,aAAa,CAAC;AAErB,OAAO,EAAE,cAAc,EAAE,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,SAAS,MAAM,YAAY,CAAC;AACnC,OAAO,aAAa,EAAE,EAAE,QAAQ,EAAE,MAAM,oBAAoB,CAAC;AAC7D,OAAO,SAAS,MAAM,gBAAgB,CAAC;AACvC,OAAO,MAAM,MAAM,aAAa,CAAC;AACjC,OAAO,EAAE,KAAK,EAAE,MAAM,YAAY,CAAC;AACnC,OAAO,EAAE,SAAS,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AACpD,OAAO,KAAK,cAAc,MAAM,qBAAqB,CAAC;AAEtD,OAAO,EAAE,SAAS,EAAE,CAAC;AAErB,OAAO,EAAE,aAAa,EAAE,QAAQ,EAAE,CAAC;AAEnC,YAAY,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAC;AAEtD,OAAO,EAAE,SAAS,EAAE,CAAC;AAErB,YAAY,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAC;AAEnD,YAAY,EAAE,YAAY,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAEhE,OAAO,EAAE,MAAM,EAAE,CAAC;AAElB,OAAO,EAAE,KAAK,EAAE,CAAC;AAEjB,OAAO,EAAE,SAAS,EAAE,CAAC;AAErB,OAAO,EAAE,UAAU,EAAE,CAAC;AAEtB,YAAY,EACV,mBAAmB,EACnB,gBAAgB,EAChB,iBAAiB,EACjB,WAAW,GACZ,MAAM,aAAa,CAAC;AAErB,OAAO,EAAE,cAAc,EAAE,CAAC"}

package/dist/esm/langChain.d.ts

@@ -10,11 +10,10 @@ export type UsageTracker = {
         [tokenKey: string]: number;
     };
     /**
-     * Sources returned by native web search, deduplicated by URL across every
-     * call in the run. Only present once a search has actually run. Anthropic and
-     * Google both require the original sources to be cited when their output is
-     * shown to end users, so they are surfaced here rather than discarded with
-     * the rest of the non-text content blocks.
+     * URLs returned by the Tavily tools, deduplicated across every call in the
+     * run. Only present once a web tool has actually run. Tavily's terms require
+     * the original sources to be cited when its content is shown to end users, so
+     * they are surfaced here rather than left buried in the tool messages.
      */
     webSearchSources?: {
         url: string;
@@ -22,64 +21,31 @@ export type UsageTracker = {
     }[];
 };
 /**
- * Caller-facing options for the providers' native web search tools. Enable web
- * search by setting `config.webSearch` to `true` (provider defaults) or to one
- * of these objects. Every field is optional and is only forwarded to the
- * providers that accept it — see `buildWebSearchTool` for the mapping.
+ * Instantiates and returns the appropriate LangChain chat model based on the model
+ * name prefix. `claude-` maps to `ChatAnthropic`, `gemini-` maps to
+ * `ChatGoogleGenerativeAI`, and `gpt-` maps to `ChatOpenAI`. DeepSeek (`deepseek-`),
+ * Kimi/Moonshot (`kimi-`, `moonshot-`), and GLM/Zhipu (`glm-`) models are routed
+ * through `ChatOpenAI` against each provider's OpenAI-compatible endpoint. When a Zod
+ * `schema` is provided, native structured output is configured per provider: OpenAI
+ * via `response_format` with `json_schema`, Anthropic via `output_config.format`, and
+ * Gemini via JSON mode (`json: true`) plus `responseSchema`. In every case the model
+ * emits JSON as the message text, so the caller's parse/validate pipeline is unchanged.
+ * The schema is ignored for the OpenAI-compatible providers (DeepSeek/Kimi/GLM), which
+ * have no native structured-output support here. Throws a `BAD_REQUEST` error for
+ * unrecognised model names.
+ * @param modelName - The model identifier, e.g. `"gpt-4o"`, `"claude-3-5-sonnet"`,
+ *   `"gemini-1.5-pro"`, `"deepseek-chat"`, `"kimi-k2-0905-preview"`, `"glm-4.6"`
+ * @param config - Configuration object containing API keys (`openAIAPIKey`,
+ *   `anthropicAPIKey`, `googleAPIKey`, `deepSeekAPIKey`, `kimiAPIKey`, `glmAPIKey`),
+ *   optional `maxTokens`, and optional `temperature`
+ * @param schema - Optional Zod schema used to configure native structured JSON output
+ *   for GPT / Claude / Gemini models; ignored for OpenAI-compatible providers
+ * @returns A configured LangChain chat model (or bound runnable) instance
  */
-export type WebSearchConfig = {
-    /** Anthropic only: hard cap on searches per request (`max_uses`). */
-    maxUses?: number;
-    /** Anthropic (`allowed_domains`) and OpenAI (`filters.allowed_domains`). */
-    allowedDomains?: string[];
-    /** Anthropic only (`blocked_domains`); cannot be combined with `allowedDomains`. */
-    blockedDomains?: string[];
-    /** Anthropic and OpenAI: approximate location used to localize results. */
-    userLocation?: {
-        city?: string;
-        region?: string;
-        /** Two-letter ISO 3166-1 alpha-2 code, e.g. `"US"`. */
-        country?: string;
-        /** IANA timezone ID, e.g. `"America/Los_Angeles"`. */
-        timezone?: string;
-    };
-    /**
-     * OpenAI only: how much of the context window search results may consume.
-     * OpenAI's default is `"medium"`; `"low"` minimizes context at some cost to
-     * answer quality, `"high"` is the expensive end.
-     */
-    searchContextSize?: "low" | "medium" | "high";
-    /** Gemini only: RFC 3339 window the search is restricted to. */
-    timeRange?: {
-        startTime: string;
-        endTime: string;
-    };
-    /**
-     * Anthropic only: opt out of dynamic filtering by forcing the search to be
-     * called directly (`allowed_callers: ["direct"]`). Defaults to `true` on
-     * models that support it — see `supportsAnthropicDynamicFiltering`. Turning
-     * this off means every raw search result lands in the context window.
-     */
-    dynamicFiltering?: boolean;
-    /**
-     * Anthropic only: whether search result blocks consumed by dynamic filtering
-     * are echoed back in the response. Defaults to `"excluded"`, which drops them
-     * and cuts the output tokens billed for content nothing downstream reads.
-     */
-    responseInclusion?: "full" | "excluded";
-    /**
-     * Anthropic only: pin the dated tool version instead of letting
-     * `buildWebSearchTool` pick per model. `web_search_20250305` is basic search,
-     * `web_search_20260209` adds dynamic filtering, `web_search_20260318` adds
-     * response-inclusion control. Pinning a filtering version on a model that
-     * cannot do programmatic tool calling returns a 400 unless
-     * `dynamicFiltering: false` is also set.
-     */
-    toolVersion?: string;
-};
+export declare const getLLMModel: (modelName: string, config: any, schema?: any) => any;
 declare const _default: {
     checkIfAIProviderConfigured: (config: any) => void;
-    createAgent: (name: string, modelName: string, systemPrompt: string, tools: any[], responseFormat: any, config: any) => any;
+    createAgent: (name: string, modelName: string, systemPrompt: string, tools: any[], responseFormat: any, config: any, usageTracker?: UsageTracker | null) => any;
     runAgent: (agent: any, prompt: string, config: any, onProgress?: Function | null, usageTracker?: UsageTracker | null) => Promise<any>;
     runPromptWithModel: (modelName: string, config: any, prompt: any, onProgressReport: any, minPercent?: number, maxPercent?: number, expectsJsonResponse?: boolean, schema?: any, agentName?: string, tools?: any[], usageTracker?: UsageTracker | null) => Promise<any>;
     runPromptWithModelForImageGeneration: (modelName: string, config: any, prompt: string, options?: any, usageTracker?: UsageTracker | null) => Promise<any>;

package/dist/esm/langChain.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"langChain.d.ts","sourceRoot":"","sources":["../../src/langChain.ts"],"names":[],"mappings":"AAuGA;;;;;GAKG;AACH,MAAM,MAAM,YAAY,GAAG;IACzB,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE;QAAE,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,CAAA;KAAE,CAAC;IACvC;;;;;;OAMG;IACH,gBAAgB,CAAC,EAAE;QAAE,GAAG,EAAE,MAAM,CAAC;QAAC,KAAK,CAAC,EAAE,MAAM,CAAA;KAAE,EAAE,CAAC;CACtD,CAAC;AAskBF;;;;;GAKG;AACH,MAAM,MAAM,eAAe,GAAG;IAC5B,qEAAqE;IACrE,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,4EAA4E;IAC5E,cAAc,CAAC,EAAE,MAAM,EAAE,CAAC;IAC1B,oFAAoF;IACpF,cAAc,CAAC,EAAE,MAAM,EAAE,CAAC;IAC1B,2EAA2E;IAC3E,YAAY,CAAC,EAAE;QACb,IAAI,CAAC,EAAE,MAAM,CAAC;QACd,MAAM,CAAC,EAAE,MAAM,CAAC;QAChB,uDAAuD;QACvD,OAAO,CAAC,EAAE,MAAM,CAAC;QACjB,sDAAsD;QACtD,QAAQ,CAAC,EAAE,MAAM,CAAC;KACnB,CAAC;IACF;;;;OAIG;IACH,iBAAiB,CAAC,EAAE,KAAK,GAAG,QAAQ,GAAG,MAAM,CAAC;IAC9C,gEAAgE;IAChE,SAAS,CAAC,EAAE;QAAE,SAAS,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAA;KAAE,CAAC;IACnD;;;;;OAKG;IACH,gBAAgB,CAAC,EAAE,OAAO,CAAC;IAC3B;;;;OAIG;IACH,iBAAiB,CAAC,EAAE,MAAM,GAAG,UAAU,CAAC;IACxC;;;;;;;OAOG;IACH,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB,CAAC;;0CAxnB2C,GAAG,KAAG,IAAI;wBAujC/C,MAAM,aACD,MAAM,gBACH,MAAM,SACb,GAAG,EAAE,kBACI,GAAG,UACX,GAAG,KACV,GAAG;sBAiCG,GAAG,UACF,MAAM,UACN,GAAG,eACC,QAAQ,GAAG,IAAI,iBACb,YAAY,GAAG,IAAI,KAChC,OAAO,CAAC,GAAG,CAAC;oCA0YF,MAAM,UACT,GAAG,UACH,GAAG,oBACO,GAAG,eACT,MAAM,eACN,MAAM,wBACG,OAAO,WACpB,GAAG,cACA,MAAM,UACV,GAAG,EAAE,iBACE,YAAY,GAAG,IAAI,KAChC,OAAO,CAAC,GAAG,CAAC;sDAuuBF,MAAM,UACT,GAAG,UACH,MAAM,YACL,GAAG,iBACE,YAAY,GAAG,IAAI,KAChC,OAAO,CAAC,GAAG,CAAC;0CAjhC8B,GAAG,KAAG,MAAM;+CAviC9C,YAAY,GAAG,IAAI,GAAG,SAAS,aAC7B,MAAM,kBACD,MAAM,UACd,GAAG,KACV,IAAI;mCAujCU,MAAM,mBACJ,MAAM,EAAE,KACxB,MAAM;;AAwjCT,wBASE"}
+{"version":3,"file":"langChain.d.ts","sourceRoot":"","sources":["../../src/langChain.ts"],"names":[],"mappings":"AA4GA;;;;;GAKG;AACH,MAAM,MAAM,YAAY,GAAG;IACzB,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE;QAAE,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,CAAA;KAAE,CAAC;IACvC;;;;;OAKG;IACH,gBAAgB,CAAC,EAAE;QAAE,GAAG,EAAE,MAAM,CAAC;QAAC,KAAK,CAAC,EAAE,MAAM,CAAA;KAAE,EAAE,CAAC;CACtD,CAAC;AA2lBF;;;;;;;;;;;;;;;;;;;;;GAqBG;AAGH,eAAO,MAAM,WAAW,GACtB,WAAW,MAAM,EACjB,QAAQ,GAAG,EACX,SAAQ,GAAU,KACjB,GAoHF,CAAC;;0CAzuB2C,GAAG,KAAG,IAAI;wBA4vB/C,MAAM,aACD,MAAM,gBACH,MAAM,SACb,GAAG,EAAE,kBACI,GAAG,UACX,GAAG,iBACG,YAAY,GAAG,IAAI,KAChC,GAAG;sBAoCG,GAAG,UACF,MAAM,UACN,GAAG,eACC,QAAQ,GAAG,IAAI,iBACb,YAAY,GAAG,IAAI,KAChC,OAAO,CAAC,GAAG,CAAC;oCAkYF,MAAM,UACT,GAAG,UACH,GAAG,oBACO,GAAG,eACT,MAAM,eACN,MAAM,wBACG,OAAO,WACpB,GAAG,cACA,MAAM,UACV,GAAG,EAAE,iBACE,YAAY,GAAG,IAAI,KAChC,OAAO,CAAC,GAAG,CAAC;sDA0tBF,MAAM,UACT,GAAG,UACH,MAAM,YACL,GAAG,iBACE,YAAY,GAAG,IAAI,KAChC,OAAO,CAAC,GAAG,CAAC;0CApgC8B,GAAG,KAAG,MAAM;+CAzuB9C,YAAY,GAAG,IAAI,GAAG,SAAS,aAC7B,MAAM,kBACD,MAAM,UACd,GAAG,KACV,IAAI;mCAyvBU,MAAM,mBACJ,MAAM,EAAE,KACxB,MAAM;;AA2iCT,wBASE"}