@mate-academy/llm-gateway 8.8.2 → 8.8.3

package/dist/LLMService.typedefs.js

@@ -0,0 +1,72 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.LLMToolLoopStopReasons = exports.LLMUploadFileMimeTypes = exports.LLMMessageContentType = exports.LLMRoles = exports.LLMPurposes = exports.LLMProviders = void 0;
+/**
+ * Enum of supported LLM providers.
+ */
+var LLMProviders;
+(function (LLMProviders) {
+    LLMProviders["OpenAI"] = "OpenAI";
+    LLMProviders["GoogleGenerativeAI"] = "GoogleGenerativeAI";
+    LLMProviders["LLMAPI"] = "LLMAPI";
+})(LLMProviders || (exports.LLMProviders = LLMProviders = {}));
+/**
+ * Supported service purposes/types that the LLM gateway provides.
+ */
+var LLMPurposes;
+(function (LLMPurposes) {
+    LLMPurposes["Completion"] = "completion";
+    LLMPurposes["Assistance"] = "assistance";
+    LLMPurposes["SpeechToText"] = "speech_to_text";
+    LLMPurposes["TextToSpeech"] = "text_to_speech";
+})(LLMPurposes || (exports.LLMPurposes = LLMPurposes = {}));
+/**
+ * Roles that can be assigned to messages in an LLM conversation.
+ */
+var LLMRoles;
+(function (LLMRoles) {
+    LLMRoles["User"] = "user";
+    LLMRoles["Assistant"] = "assistant";
+})(LLMRoles || (exports.LLMRoles = LLMRoles = {}));
+/**
+ * Possible content types for messages in an LLM conversation.
+ */
+var LLMMessageContentType;
+(function (LLMMessageContentType) {
+    LLMMessageContentType["TEXT"] = "text";
+    LLMMessageContentType["IMAGE_URL"] = "image_url";
+    LLMMessageContentType["AUDIO_FILE"] = "audio_file";
+})(LLMMessageContentType || (exports.LLMMessageContentType = LLMMessageContentType = {}));
+/**
+ * Supported MIME types for files that can be uploaded to LLM services.
+ */
+var LLMUploadFileMimeTypes;
+(function (LLMUploadFileMimeTypes) {
+    LLMUploadFileMimeTypes["IMAGE_PNG"] = "image/png";
+    LLMUploadFileMimeTypes["IMAGE_JPEG"] = "image/jpeg";
+    LLMUploadFileMimeTypes["IMAGE_JPG"] = "image/jpg";
+    LLMUploadFileMimeTypes["IMAGE_GIF"] = "image/gif";
+    LLMUploadFileMimeTypes["IMAGE_WEBP"] = "image/webp";
+    LLMUploadFileMimeTypes["IMAGE_SVG_XML"] = "image/svg+xml";
+    LLMUploadFileMimeTypes["IMAGE_BMP"] = "image/bmp";
+    LLMUploadFileMimeTypes["PLAIN_TEXT"] = "text/plain";
+    LLMUploadFileMimeTypes["MARKDOWN"] = "text/markdown";
+    LLMUploadFileMimeTypes["AUDIO_MP3"] = "audio/mp3";
+    LLMUploadFileMimeTypes["AUDIO_MPEG"] = "audio/mpeg";
+    LLMUploadFileMimeTypes["AUDIO_WAV"] = "audio/wav";
+    LLMUploadFileMimeTypes["AUDIO_WEBM"] = "audio/webm";
+    LLMUploadFileMimeTypes["AUDIO_OGG"] = "audio/ogg";
+})(LLMUploadFileMimeTypes || (exports.LLMUploadFileMimeTypes = LLMUploadFileMimeTypes = {}));
+/**
+ * Why a provider's model⇄tool loop stopped. `Completed` is the ordinary end
+ * (a model round returned no tool calls), `MaxIterations` means the loop hit
+ * `maxToolIterations` with tool calls still pending, and `TerminalTool` means
+ * a tool declaring `terminal` ran and ended the turn.
+ */
+var LLMToolLoopStopReasons;
+(function (LLMToolLoopStopReasons) {
+    LLMToolLoopStopReasons["Completed"] = "completed";
+    LLMToolLoopStopReasons["MaxIterations"] = "max_iterations";
+    LLMToolLoopStopReasons["TerminalTool"] = "terminal_tool";
+})(LLMToolLoopStopReasons || (exports.LLMToolLoopStopReasons = LLMToolLoopStopReasons = {}));
+//# sourceMappingURL=LLMService.typedefs.js.map

package/dist/LLMService.typedefs.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"LLMService.typedefs.js","sourceRoot":"","sources":["../src/LLMService.typedefs.ts"],"names":[],"mappings":";;;AAmCA;;GAEG;AACH,IAAY,YAIX;AAJD,WAAY,YAAY;IACtB,iCAAiB,CAAA;IACjB,yDAAyC,CAAA;IACzC,iCAAiB,CAAA;AACnB,CAAC,EAJW,YAAY,4BAAZ,YAAY,QAIvB;AAoBD;;GAEG;AACH,IAAY,WAKX;AALD,WAAY,WAAW;IACrB,wCAAyB,CAAA;IACzB,wCAAyB,CAAA;IACzB,8CAA+B,CAAA;IAC/B,8CAA+B,CAAA;AACjC,CAAC,EALW,WAAW,2BAAX,WAAW,QAKtB;AAiLD;;GAEG;AACH,IAAY,QAGX;AAHD,WAAY,QAAQ;IAClB,yBAAa,CAAA;IACb,mCAAuB,CAAA;AACzB,CAAC,EAHW,QAAQ,wBAAR,QAAQ,QAGnB;AAED;;GAEG;AACH,IAAY,qBAIX;AAJD,WAAY,qBAAqB;IAC/B,sCAAa,CAAA;IACb,gDAAuB,CAAA;IACvB,kDAAyB,CAAA;AAC3B,CAAC,EAJW,qBAAqB,qCAArB,qBAAqB,QAIhC;AAsMD;;GAEG;AACH,IAAY,sBAeX;AAfD,WAAY,sBAAsB;IAChC,iDAAuB,CAAA;IACvB,mDAAyB,CAAA;IACzB,iDAAuB,CAAA;IACvB,iDAAuB,CAAA;IACvB,mDAAyB,CAAA;IACzB,yDAA+B,CAAA;IAC/B,iDAAuB,CAAA;IACvB,mDAAyB,CAAA;IACzB,oDAA0B,CAAA;IAC1B,iDAAuB,CAAA;IACvB,mDAAyB,CAAA;IACzB,iDAAuB,CAAA;IACvB,mDAAyB,CAAA;IACzB,iDAAuB,CAAA;AACzB,CAAC,EAfW,sBAAsB,sCAAtB,sBAAsB,QAejC;AA8OD;;;;;GAKG;AACH,IAAY,sBAIX;AAJD,WAAY,sBAAsB;IAChC,iDAAuB,CAAA;IACvB,0DAAgC,CAAA;IAChC,wDAA8B,CAAA;AAChC,CAAC,EAJW,sBAAsB,sCAAtB,sBAAsB,QAIjC"}

package/dist/advanced.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Escape hatch entry point. Re-exports the internal engine — `LLMServiceFactory`,
+ * the provider services, and the model maps — for the rare call site that needs
+ * raw control the v2 client does not expose. Discouraged: prefer `createLLMClient`
+ * + the typed registry. This surface bypasses prompt management, the validation
+ * gate, and config-in-prompt routing.
+ */
+export { LLMServiceFactory } from './LLMService.factory';
+export { LLM_SERVICE_FACTORIES, LLM_SERVICE_MODELS, } from './LLMService.constants';
+export * from './providers';
+export * from './services';

package/dist/advanced.js

@@ -0,0 +1,32 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.LLM_SERVICE_MODELS = exports.LLM_SERVICE_FACTORIES = exports.LLMServiceFactory = void 0;
+/**
+ * Escape hatch entry point. Re-exports the internal engine — `LLMServiceFactory`,
+ * the provider services, and the model maps — for the rare call site that needs
+ * raw control the v2 client does not expose. Discouraged: prefer `createLLMClient`
+ * + the typed registry. This surface bypasses prompt management, the validation
+ * gate, and config-in-prompt routing.
+ */
+var LLMService_factory_1 = require("./LLMService.factory");
+Object.defineProperty(exports, "LLMServiceFactory", { enumerable: true, get: function () { return LLMService_factory_1.LLMServiceFactory; } });
+var LLMService_constants_1 = require("./LLMService.constants");
+Object.defineProperty(exports, "LLM_SERVICE_FACTORIES", { enumerable: true, get: function () { return LLMService_constants_1.LLM_SERVICE_FACTORIES; } });
+Object.defineProperty(exports, "LLM_SERVICE_MODELS", { enumerable: true, get: function () { return LLMService_constants_1.LLM_SERVICE_MODELS; } });
+__exportStar(require("./providers"), exports);
+__exportStar(require("./services"), exports);
+//# sourceMappingURL=advanced.js.map

package/dist/advanced.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"advanced.js","sourceRoot":"","sources":["../src/advanced.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;;AAAA;;;;;;GAMG;AACH,2DAAyD;AAAhD,uHAAA,iBAAiB,OAAA;AAC1B,+DAGgC;AAF9B,6HAAA,qBAAqB,OAAA;AACrB,0HAAA,kBAAkB,OAAA;AAEpB,8CAA4B;AAC5B,6CAA2B"}

package/dist/client/LLMAgent.d.ts

@@ -0,0 +1,76 @@
+import { type LLMToolDefinition } from '../LLMService.typedefs';
+import { type LLMSchemaInterface } from '../utilities/schema';
+import { type LLMPromptRegistry } from '../client/defineLLMPrompts';
+import { type LLMVariableValue } from '../client/promptSnapshot.typedefs';
+import { type LLMDelegationGate, type LLMPromptVariables, type LLMSubagentVariableSource } from '../client/llmClient.typedefs';
+/**
+ * A bounded specialist the root agent may delegate to, as a plain object.
+ * `prompt` names the registry entry whose Langfuse prompt is the subagent's
+ * instructions (and whose config routes its model); `name`/`description` are
+ * what the root model sees when deciding to delegate. A plain-object subagent
+ * cannot declare its own subagents — use `LLMAgent` instances (via
+ * `llm.defineAgent`) when deeper composition is needed.
+ */
+export type LLMAgentSubagentDefinition<Registry extends LLMPromptRegistry, VariableMap extends Record<keyof Registry, string>> = {
+    [Key in keyof Registry]: {
+        prompt: Key;
+        name: string;
+        description: string;
+        tools?: LLMToolDefinition[];
+        canExecute?: LLMDelegationGate;
+        maxToolIterations?: number;
+    } & LLMSubagentVariableSource<VariableMap[Key]>;
+}[keyof Registry];
+/**
+ * Anything accepted in a `subagents` list: a plain definition object or an
+ * `LLMAgent` instance — both describe the same delegation tool.
+ */
+export type LLMAgentSubagent<Registry extends LLMPromptRegistry, VariableMap extends Record<keyof Registry, string>> = LLMAgentSubagentDefinition<Registry, VariableMap> | LLMAgent<Registry, VariableMap>;
+/**
+ * The declarative description of one agent. `prompt` names the registry entry
+ * whose Langfuse prompt is the agent's instructions (and whose config routes
+ * its model). `name`/`description` are required when the agent is used as a
+ * subagent — the name becomes the delegation tool the parent model calls.
+ * `variables` given here are a base merged under the per-run variables (for a
+ * subagent they are the only source, unless `inputSchema` lets the parent
+ * model supply more).
+ */
+export interface LLMAgentDefinition<Registry extends LLMPromptRegistry, VariableMap extends Record<keyof Registry, string>, Key extends keyof Registry> {
+    prompt: Key;
+    name?: string;
+    description?: string;
+    variables?: LLMPromptVariables<VariableMap[Key]>;
+    tools?: LLMToolDefinition[];
+    subagents?: LLMAgentSubagent<Registry, VariableMap>[];
+    /**
+     * The arguments the parent model must supply when delegating to this agent,
+     * replacing the default single `prompt` string. Each argument joins the
+     * subagent's prompt variables (over the definition's own), so the delegated
+     * prompt can reference them as `{{name}}`. Only meaningful as a subagent.
+     */
+    inputSchema?: LLMSchemaInterface;
+    /** Refuses a delegation call before it runs; see `LLMDelegationGate`. */
+    canExecute?: LLMDelegationGate;
+    maxToolIterations?: number;
+}
+/**
+ * An immutable agent definition bound to the prompt registry. Optional sugar
+ * over the plain-object `runAgent` options: build instances with
+ * `llm.defineAgent(...)` — the client factory carries the registry generics,
+ * so `prompt`, `variables`, and the `runAgent` return type stay fully typed.
+ * Agents compose: a subagent may itself be an `LLMAgent` with its own
+ * subagents; because instances are immutable, a delegation cycle cannot be
+ * constructed and nesting depth is always finite.
+ */
+export declare class LLMAgent<Registry extends LLMPromptRegistry = LLMPromptRegistry, VariableMap extends Record<keyof Registry, string> = Record<keyof Registry, string>, Key extends keyof Registry = keyof Registry> {
+    readonly prompt: Key;
+    readonly name: string | undefined;
+    readonly description: string | undefined;
+    readonly variables: Record<string, LLMVariableValue> | undefined;
+    readonly tools: LLMToolDefinition[] | undefined;
+    readonly subagents: LLMAgentSubagent<Registry, VariableMap>[] | undefined;
+    readonly inputSchema: LLMSchemaInterface | undefined;
+    readonly canExecute: LLMDelegationGate | undefined;
+    readonly maxToolIterations: number | undefined;
+    constructor(definition: LLMAgentDefinition<Registry, VariableMap, Key>);
+}

package/dist/client/LLMAgent.js

@@ -0,0 +1,36 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.LLMAgent = void 0;
+/**
+ * An immutable agent definition bound to the prompt registry. Optional sugar
+ * over the plain-object `runAgent` options: build instances with
+ * `llm.defineAgent(...)` — the client factory carries the registry generics,
+ * so `prompt`, `variables`, and the `runAgent` return type stay fully typed.
+ * Agents compose: a subagent may itself be an `LLMAgent` with its own
+ * subagents; because instances are immutable, a delegation cycle cannot be
+ * constructed and nesting depth is always finite.
+ */
+class LLMAgent {
+    prompt;
+    name;
+    description;
+    variables;
+    tools;
+    subagents;
+    inputSchema;
+    canExecute;
+    maxToolIterations;
+    constructor(definition) {
+        this.prompt = definition.prompt;
+        this.name = definition.name;
+        this.description = definition.description;
+        this.variables = definition.variables;
+        this.tools = definition.tools;
+        this.subagents = definition.subagents;
+        this.inputSchema = definition.inputSchema;
+        this.canExecute = definition.canExecute;
+        this.maxToolIterations = definition.maxToolIterations;
+    }
+}
+exports.LLMAgent = LLMAgent;
+//# sourceMappingURL=LLMAgent.js.map

package/dist/client/LLMAgent.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"LLMAgent.js","sourceRoot":"","sources":["../../src/client/LLMAgent.ts"],"names":[],"mappings":";;;AA2EA;;;;;;;;GAQG;AACH,MAAa,QAAQ;IAMV,MAAM,CAAM;IAEZ,IAAI,CAAqB;IAEzB,WAAW,CAAqB;IAEhC,SAAS,CAA+C;IAExD,KAAK,CAAkC;IAEvC,SAAS,CAAwD;IAEjE,WAAW,CAAiC;IAE5C,UAAU,CAAgC;IAE1C,iBAAiB,CAAqB;IAE/C,YAAY,UAA0D;QACpE,IAAI,CAAC,MAAM,GAAG,UAAU,CAAC,MAAM,CAAC;QAChC,IAAI,CAAC,IAAI,GAAG,UAAU,CAAC,IAAI,CAAC;QAC5B,IAAI,CAAC,WAAW,GAAG,UAAU,CAAC,WAAW,CAAC;QAC1C,IAAI,CAAC,SAAS,GAAG,UAAU,CAAC,SAAS,CAAC;QACtC,IAAI,CAAC,KAAK,GAAG,UAAU,CAAC,KAAK,CAAC;QAC9B,IAAI,CAAC,SAAS,GAAG,UAAU,CAAC,SAAS,CAAC;QACtC,IAAI,CAAC,WAAW,GAAG,UAAU,CAAC,WAAW,CAAC;QAC1C,IAAI,CAAC,UAAU,GAAG,UAAU,CAAC,UAAU,CAAC;QACxC,IAAI,CAAC,iBAAiB,GAAG,UAAU,CAAC,iBAAiB,CAAC;IACxD,CAAC;CACF;AAnCD,4BAmCC"}

package/dist/client/LLMClientEngine.d.ts

@@ -0,0 +1,110 @@
+import { type LLMCallTraceContext, type LLMToolResult } from '../LLMService.typedefs';
+import { type LLMReporterInterface } from '../utilities/reporter';
+import { type LLMSchemaInterface } from '../utilities/schema';
+import { type LLMPromptBinding, type LLMPromptRegistry } from '../client/defineLLMPrompts';
+import { type LLMAgentInlineRunOptions, type LLMAgentRunResult } from '../client/agentRun.typedefs';
+import { LLMAgent, type LLMAgentDefinition } from '../client/LLMAgent';
+import { type LLMAgentCallServices, type LLMPromptResolutionCall } from '../client/agentRunner';
+import { type LLMClientCallContext, type LLMClientEngineConfig, type LLMGenerateOptions, type LLMGenerateResult, type LLMPlainMessage, type LLMPromptDescription, type LLMProviderServiceScope, type LLMToolResultContext, type LLMTraceContextScope } from '../client/llmClient.typedefs';
+import { type LLMVariableValue } from '../client/promptSnapshot.typedefs';
+import { type ResolvedPrompt } from '../client/promptRegistry.runtime';
+/**
+ * The client's single implementation. `createLLMClient` owns its construction
+ * and exposes only the `LLMClient` surface, so every call path — `generate`,
+ * `countTokens`, `runAgent`, `describePrompt` — shares one prompt resolution,
+ * one credentials lookup, one reporter/trace context, and one error taxonomy.
+ */
+export declare class LLMClientEngine<Registry extends LLMPromptRegistry> implements LLMAgentCallServices {
+    private readonly gateway;
+    private readonly registry;
+    private readonly runtime;
+    private readonly credentials;
+    private readonly reporter;
+    private readonly buildReporterContextFor;
+    private readonly logger;
+    private readonly staticContext;
+    private readonly mode;
+    private readonly toolResultNormalizer;
+    private readonly agentRunner;
+    constructor(config: LLMClientEngineConfig<Registry>);
+    generate<Key extends keyof Registry, Schema extends LLMSchemaInterface = never>(prompt: Key, options: LLMGenerateOptions<Record<string, LLMVariableValue>, Schema>): Promise<unknown>;
+    defineAgent<Key extends keyof Registry>(definition: LLMAgentDefinition<Registry, Record<keyof Registry, string>, Key>): LLMAgent<Registry, Record<keyof Registry, string>, Key>;
+    runAgent<Key extends keyof Registry>(promptOrAgent: Key | LLMAgent<Registry, Record<keyof Registry, string>>, options: LLMAgentInlineRunOptions<Record<string, LLMVariableValue>, Registry, Record<keyof Registry, string>>): Promise<LLMAgentRunResult<LLMGenerateResult<Registry[Key]>>>;
+    countTokens<Key extends keyof Registry>(prompt: Key, options: {
+        variables: Record<string, LLMVariableValue>;
+        history?: LLMPlainMessage[];
+    }): Promise<number>;
+    describePrompt<Key extends keyof Registry>(prompt: Key): Promise<LLMPromptDescription>;
+    resolvePrompt(promptName: string, binding: LLMPromptBinding, variables: Record<string, LLMVariableValue>, call: LLMPromptResolutionCall): Promise<ResolvedPrompt>;
+    /**
+     * The single place a tool's return value becomes what the model reads. The
+     * package's own coercion always runs first, so a client-supplied normalizer
+     * never sees a malformed value and cannot reintroduce one.
+     */
+    normalizeToolResult(context: LLMToolResultContext): LLMToolResult;
+    withAgentObservation<Result>(name: string, input: unknown, fn: () => Promise<Result>): Promise<Result>;
+    private runCompletion;
+    /**
+     * Builds the provider message envelope from the resolved prompt. A `text`
+     * prompt is one user message. A `chat` prompt preserves the structure the
+     * prompt declares: a leading `system` message maps to `instructions`, the final
+     * `user` message is the request, and any messages between them join the
+     * call-supplied history in order.
+     */
+    private buildMessageEnvelope;
+    private findLastUserIndex;
+    private callProvider;
+    unwrapResult(resolved: ResolvedPrompt, schema: LLMSchemaInterface | undefined, sendResult: {
+        text?: string;
+        data?: unknown;
+        parseError?: string;
+    }): unknown;
+    toTaxonomyError(error: unknown, resolved: ResolvedPrompt, abortSignal?: AbortSignal): Error;
+    buildAssistanceService(options: LLMProviderServiceScope): Promise<import("..").LLMAssistanceService<import("../LLMService.typedefs").LLMProviders, LLMReporterInterface<any>>>;
+    getBinding(promptName: string): LLMPromptBinding | undefined;
+    private buildCompletionService;
+    /**
+     * Resolves credentials for the product this call belongs to. The per-call
+     * context wins over the static one: the client is built once per process, so
+     * its static product is only ever the one its builder knew, while a call site
+     * that resolves the product from its own subject knows better.
+     */
+    private resolveProviderOptions;
+    private buildUserMessage;
+    private buildHistory;
+    private toCompletionMessage;
+    /**
+     * Delegates the reporter's payload to the composition root. The gateway never
+     * shapes it: those fields are a downstream contract (DWH columns and the
+     * dashboards built on their exact values), so inventing a key or a string
+     * here would silently break analytics rather than fail a build.
+     *
+     * The active trace scope's context travels along as `scopeContext`, so the
+     * composition root can fall back to what the surrounding operation declared
+     * when the call itself names nothing.
+     */
+    buildReporterContext(resolved: ResolvedPrompt, callContext: LLMClientCallContext | undefined): unknown;
+    /**
+     * Builds the per-call trace context every client path threads into the gateway
+     * service. The structural `prompt` names the observation and carries the
+     * managed prompt version, so the generation the service records on success and
+     * on error is the single one Langfuse links to that prompt — the client never
+     * records a second observation of its own.
+     *
+     * `userId`, `sessionId` and `tags` travel as typed trace fields and never
+     * through `serializeCallContext`, which is the metadata path. The user
+     * therefore appears twice — typed here and, as it always has, inside the
+     * metadata bag the existing dashboards read.
+     */
+    buildTraceContext(scope: LLMTraceContextScope): LLMCallTraceContext;
+    /**
+     * The call context holds the user as whatever the application uses for its
+     * own ids, while Langfuse holds it as a string. Absent stays absent, so a
+     * call that names no user leaves the trace's user field for the scope to fill.
+     */
+    private toTraceUserId;
+    private assertOverridesAllowed;
+    private serializeCallContext;
+    private extractStatus;
+    private isRetryableStatus;
+}