@mate-academy/llm-gateway 8.8.0 → 8.8.2

package/README.md

@@ -124,10 +124,13 @@ params, usage, cost) at the same success/error points the metrics reporter
 already wraps — one on success, one (level `ERROR`) on failure. An assistance
 call emits one `generation` per **model round** of its tool loop, each carrying
 the conversation as it stood for that round and that round's assistant output,
-with the round's own usage and cost; the `tool` observations of a round nest
-under it, so a run reads as round, its tools, next round. The run still writes a
-single aggregate metrics point, unchanged. Calls that carry no per-call trace
-context (text-to-speech, file and chat management) emit none, on either branch.
+with the round's own usage and cost. Inside an active trace scope, a legacy
+`assistInChat` caller that runs an agent-style tool loop can pass `agentName` to
+group all of its generation and tool observations under one `agent`
+observation. The v2 `runAgent` API opens that agent observation automatically.
+The run still writes a single aggregate metrics point, unchanged. Calls that
+carry no per-call trace context (text-to-speech, file and chat management) emit
+none, on either branch.
 Observation input/output are recorded in full — the prompt and the completion
 are what a trace exists to show, so they are never truncated. All of this is
 fire-and-forget — a tracing failure never blocks or fails an LLM call.
@@ -1413,6 +1416,7 @@ Interface for chat/assistance services with file handling capabilities.
   - `schema`: Optional schema for structured output (supports type-safe JSON responses)
   - `tools`: Optional array of tool definitions (built with `LLMTool.create`) the model may call during the turn
   - `maxToolIterations`: Optional cap on the number of tool-call rounds
+  - `agentName`: Optional agent observation name for legacy agent-style tool loops; do not set it when using the v2 `runAgent` API
   - `reporterContext`: Context data passed to reporter for metrics tracking (required if reporter is configured with a defined context type)
 - `countTokens(messages, model)`: Count tokens in messages for context management
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mate-academy/llm-gateway",
-  "version": "8.8.0",
+  "version": "8.8.2",
   "description": "A gateway package for LLM services.",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",

package/dist/LLMError.d.ts

@@ -1,12 +0,0 @@
-import { type LLMProviders } from './LLMService.typedefs';
-export declare class LLMError extends Error {
-    readonly provider: LLMProviders;
-    readonly status: number | null;
-    readonly originalError: unknown;
-    constructor(options: {
-        provider: LLMProviders;
-        originalError: unknown;
-    });
-    private static extractStatus;
-}
-export declare function isLLMError(error: unknown): error is LLMError;

package/dist/LLMError.js

@@ -1,36 +0,0 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.LLMError = void 0;
-exports.isLLMError = isLLMError;
-class LLMError extends Error {
-    provider;
-    status;
-    originalError;
-    constructor(options) {
-        const message = options.originalError instanceof Error
-            ? options.originalError.message
-            : String(options.originalError);
-        super(message, { cause: options.originalError });
-        this.name = 'LLMError';
-        this.provider = options.provider;
-        this.status = LLMError.extractStatus(options.originalError);
-        this.originalError = options.originalError;
-        if (options.originalError instanceof Error) {
-            this.stack = options.originalError.stack;
-        }
-    }
-    static extractStatus(error) {
-        if (error
-            && typeof error === 'object'
-            && 'status' in error
-            && typeof error.status === 'number') {
-            return error.status;
-        }
-        return null;
-    }
-}
-exports.LLMError = LLMError;
-function isLLMError(error) {
-    return error instanceof LLMError;
-}
-//# sourceMappingURL=LLMError.js.map

package/dist/LLMError.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"LLMError.js","sourceRoot":"","sources":["../src/LLMError.ts"],"names":[],"mappings":";;;AAyCA,gCAEC;AAzCD,MAAa,QAAS,SAAQ,KAAK;IACxB,QAAQ,CAAe;IACvB,MAAM,CAAgB;IACtB,aAAa,CAAU;IAEhC,YAAY,OAGX;QACC,MAAM,OAAO,GAAG,OAAO,CAAC,aAAa,YAAY,KAAK;YACpD,CAAC,CAAC,OAAO,CAAC,aAAa,CAAC,OAAO;YAC/B,CAAC,CAAC,MAAM,CAAC,OAAO,CAAC,aAAa,CAAC,CAAC;QAElC,KAAK,CAAC,OAAO,EAAE,EAAE,KAAK,EAAE,OAAO,CAAC,aAAa,EAAE,CAAC,CAAC;QAEjD,IAAI,CAAC,IAAI,GAAG,UAAU,CAAC;QACvB,IAAI,CAAC,QAAQ,GAAG,OAAO,CAAC,QAAQ,CAAC;QACjC,IAAI,CAAC,MAAM,GAAG,QAAQ,CAAC,aAAa,CAAC,OAAO,CAAC,aAAa,CAAC,CAAC;QAC5D,IAAI,CAAC,aAAa,GAAG,OAAO,CAAC,aAAa,CAAC;QAE3C,IAAI,OAAO,CAAC,aAAa,YAAY,KAAK,EAAE,CAAC;YAC3C,IAAI,CAAC,KAAK,GAAG,OAAO,CAAC,aAAa,CAAC,KAAK,CAAC;QAC3C,CAAC;IACH,CAAC;IAEO,MAAM,CAAC,aAAa,CAAC,KAAc;QACzC,IACE,KAAK;eACF,OAAO,KAAK,KAAK,QAAQ;eACzB,QAAQ,IAAI,KAAK;eACjB,OAAO,KAAK,CAAC,MAAM,KAAK,QAAQ,EACnC,CAAC;YACD,OAAO,KAAK,CAAC,MAAM,CAAC;QACtB,CAAC;QAED,OAAO,IAAI,CAAC;IACd,CAAC;CACF;AArCD,4BAqCC;AAED,SAAgB,UAAU,CAAC,KAAc;IACvC,OAAO,KAAK,YAAY,QAAQ,CAAC;AACnC,CAAC"}

package/dist/LLMGateway.d.ts

@@ -1,30 +0,0 @@
-import { type LLMProviders, type LLMPurposes, type LLMServiceByPurpose, type LLMServiceOptions } from './LLMService.typedefs';
-import { type LLMGatewayOptions } from './LLMGateway.typedefs';
-import { type LLMReporterInterface } from './utilities/reporter';
-import { type LLMFallbackMetricDimensions, type LLMGatewayTracer, type LLMTraceContext } from './utilities/llmTracing';
-/**
- * An explicitly constructed gateway: every service it hands out is wired to the
- * tracer this instance was built with. `LLMServiceFactory` stays available for
- * call sites that want no tracing, so nothing depends on process-wide state.
- */
-export declare class LLMGateway {
-    private readonly tracer;
-    private readonly fallbackMetricEmitter;
-    constructor(options?: LLMGatewayOptions);
-    getCompletionService<Provider extends LLMProviders, Reporter extends LLMReporterInterface<any> | undefined = undefined>(options: LLMServiceOptions<Provider, Reporter>): LLMServiceByPurpose<Provider, Reporter>[LLMPurposes.Completion];
-    getAssistanceService<Provider extends LLMProviders, Reporter extends LLMReporterInterface<any> | undefined>(options: LLMServiceOptions<Provider, Reporter>): LLMServiceByPurpose<Provider, Reporter>[LLMPurposes.Assistance];
-    getSpeechToTextService<Provider extends LLMProviders, Reporter extends LLMReporterInterface<any> | undefined>(options: LLMServiceOptions<Provider, Reporter>): LLMServiceByPurpose<Provider, Reporter>[LLMPurposes.SpeechToText];
-    getTextToSpeechService<Provider extends LLMProviders, Reporter extends LLMReporterInterface<any> | undefined>(options: LLMServiceOptions<Provider, Reporter>): LLMServiceByPurpose<Provider, Reporter>[LLMPurposes.TextToSpeech];
-    getTracer(): LLMGatewayTracer;
-    /**
-     * Starts a trace around `fn`; every gateway call inside nests into it.
-     */
-    withTrace<Result>(name: string, context: LLMTraceContext, fn: () => Promise<Result>): Promise<Result>;
-    /**
-     * Flushes buffered traces. Serverless handlers call this on completion; the
-     * long-running API calls it from its shutdown hook only.
-     */
-    flush(): Promise<void>;
-    emitFallbackServed(dimensions: LLMFallbackMetricDimensions): void;
-    private traced;
-}

package/dist/LLMGateway.js

@@ -1,56 +0,0 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.LLMGateway = void 0;
-const LLMService_factory_1 = require("./LLMService.factory");
-const llmTracing_1 = require("./utilities/llmTracing");
-/**
- * An explicitly constructed gateway: every service it hands out is wired to the
- * tracer this instance was built with. `LLMServiceFactory` stays available for
- * call sites that want no tracing, so nothing depends on process-wide state.
- */
-class LLMGateway {
-    tracer;
-    fallbackMetricEmitter;
-    constructor(options = {}) {
-        this.tracer = options.tracer ?? llmTracing_1.noopLLMGatewayTracer;
-        this.fallbackMetricEmitter
-            = options.fallbackMetricEmitter ?? llmTracing_1.noopFallbackMetricEmitter;
-    }
-    getCompletionService(options) {
-        return this.traced(LLMService_factory_1.LLMServiceFactory.getCompletionService(options));
-    }
-    getAssistanceService(options) {
-        return this.traced(LLMService_factory_1.LLMServiceFactory.getAssistanceService(options));
-    }
-    getSpeechToTextService(options) {
-        return this.traced(LLMService_factory_1.LLMServiceFactory.getSpeechToTextService(options));
-    }
-    getTextToSpeechService(options) {
-        return this.traced(LLMService_factory_1.LLMServiceFactory.getTextToSpeechService(options));
-    }
-    getTracer() {
-        return this.tracer;
-    }
-    /**
-     * Starts a trace around `fn`; every gateway call inside nests into it.
-     */
-    withTrace(name, context, fn) {
-        return this.tracer.withTrace(name, context, fn);
-    }
-    /**
-     * Flushes buffered traces. Serverless handlers call this on completion; the
-     * long-running API calls it from its shutdown hook only.
-     */
-    flush() {
-        return this.tracer.flush();
-    }
-    emitFallbackServed(dimensions) {
-        this.fallbackMetricEmitter(dimensions);
-    }
-    traced(service) {
-        service.initTracer(this.tracer);
-        return service;
-    }
-}
-exports.LLMGateway = LLMGateway;
-//# sourceMappingURL=LLMGateway.js.map

package/dist/LLMGateway.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"LLMGateway.js","sourceRoot":"","sources":["../src/LLMGateway.ts"],"names":[],"mappings":";;;AAMA,6DAAyD;AAGzD,uDAOgC;AAMhC;;;;GAIG;AACH,MAAa,UAAU;IACJ,MAAM,CAAmB;IAEzB,qBAAqB,CAA2B;IAEjE,YAAY,UAA6B,EAAE;QACzC,IAAI,CAAC,MAAM,GAAG,OAAO,CAAC,MAAM,IAAI,iCAAoB,CAAC;QACrD,IAAI,CAAC,qBAAqB;cACtB,OAAO,CAAC,qBAAqB,IAAI,sCAAyB,CAAC;IACjE,CAAC;IAED,oBAAoB,CAIlB,OAA8C;QAE9C,OAAO,IAAI,CAAC,MAAM,CAAC,sCAAiB,CAAC,oBAAoB,CAAC,OAAO,CAAC,CAAC,CAAC;IACtE,CAAC;IAED,oBAAoB,CAIlB,OAA8C;QAE9C,OAAO,IAAI,CAAC,MAAM,CAAC,sCAAiB,CAAC,oBAAoB,CAAC,OAAO,CAAC,CAAC,CAAC;IACtE,CAAC;IAED,sBAAsB,CAIpB,OAA8C;QAE9C,OAAO,IAAI,CAAC,MAAM,CAAC,sCAAiB,CAAC,sBAAsB,CAAC,OAAO,CAAC,CAAC,CAAC;IACxE,CAAC;IAED,sBAAsB,CAIpB,OAA8C;QAE9C,OAAO,IAAI,CAAC,MAAM,CAAC,sCAAiB,CAAC,sBAAsB,CAAC,OAAO,CAAC,CAAC,CAAC;IACxE,CAAC;IAED,SAAS;QACP,OAAO,IAAI,CAAC,MAAM,CAAC;IACrB,CAAC;IAED;;OAEG;IACH,SAAS,CACP,IAAY,EACZ,OAAwB,EACxB,EAAyB;QAEzB,OAAO,IAAI,CAAC,MAAM,CAAC,SAAS,CAAC,IAAI,EAAE,OAAO,EAAE,EAAE,CAAC,CAAC;IAClD,CAAC;IAED;;;OAGG;IACH,KAAK;QACH,OAAO,IAAI,CAAC,MAAM,CAAC,KAAK,EAAE,CAAC;IAC7B,CAAC;IAED,kBAAkB,CAAC,UAAuC;QACxD,IAAI,CAAC,qBAAqB,CAAC,UAAU,CAAC,CAAC;IACzC,CAAC;IAEO,MAAM,CAAmC,OAAgB;QAC/D,OAAO,CAAC,UAAU,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;QAEhC,OAAO,OAAO,CAAC;IACjB,CAAC;CACF;AA/ED,gCA+EC"}

package/dist/LLMGateway.typedefs.d.ts

@@ -1,5 +0,0 @@
-import { type LLMFallbackMetricEmitter, type LLMGatewayTracer } from './utilities/llmTracing';
-export interface LLMGatewayOptions {
-    tracer?: LLMGatewayTracer;
-    fallbackMetricEmitter?: LLMFallbackMetricEmitter;
-}

package/dist/LLMGateway.typedefs.js

@@ -1,3 +0,0 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-//# sourceMappingURL=LLMGateway.typedefs.js.map

package/dist/LLMGateway.typedefs.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"LLMGateway.typedefs.js","sourceRoot":"","sources":["../src/LLMGateway.typedefs.ts"],"names":[],"mappings":""}