@mate-academy/llm-gateway 8.6.0 → 8.8.0

package/dist/services/LLMBaseService.abstract.js

@@ -5,6 +5,7 @@ const crypto_1 = require("crypto");
 const serializeError_1 = require("../utilities/serializeError");
 const LLMService_constants_1 = require("../LLMService.constants");
 const utilities_1 = require("../utilities");
+const agentRounds_1 = require("./agentRounds");
 class LLMBaseService {
     provider;
     serviceName;
@@ -173,29 +174,83 @@ class LLMBaseService {
             startedAt,
         };
     }
+    /**
+     * Opens the per-round generation stream of an agent tool loop. Every model
+     * round the loop runs is traced through the returned recorder, so the run
+     * renders as one role-labelled transcript per round instead of a single
+     * generation covering the whole loop. The run's aggregate metrics point is
+     * written separately by `writeSuccessMetrics` and is unaffected.
+     */
+    openAgentRounds(params) {
+        const { method, model, traceContext, modelParameters, } = params;
+        return new agentRounds_1.LLMAgentRounds((round) => {
+            const generationTrace = this.buildGenerationTrace({
+                method,
+                traceContext,
+                input: round.input,
+                output: round.isError
+                    ? this.describeError(round.error)
+                    : round.output,
+                modelParameters,
+                startedAt: round.startedAt,
+            });
+            if (round.isError) {
+                this.recordGenerationTrace({
+                    method,
+                    model,
+                    generationTrace,
+                    isError: true,
+                });
+                return;
+            }
+            const { tokens, costs } = this.buildGenerationAccounting({
+                model,
+                usage: round.usage ?? {},
+            });
+            this.recordGenerationTrace({
+                method,
+                model,
+                generationTrace,
+                usageDetails: tokens,
+                costDetails: {
+                    input: costs.input,
+                    output: costs.output,
+                    total: costs.total,
+                },
+            });
+        });
+    }
+    /**
+     * The generation a failed agent run falls back to when it never reached its
+     * first model round: a run that throws while assembling the request would
+     * otherwise trace nothing at all. Once a round has been recorded the
+     * transcript is already there, and no second observation is emitted for it.
+     */
+    buildUnstartedRunTrace(params) {
+        const { rounds, method, traceContext, input, modelParameters, startedAt, } = params;
+        if (rounds.hasRecordedRound) {
+            return undefined;
+        }
+        return this.buildGenerationTrace({
+            method,
+            traceContext,
+            input,
+            modelParameters,
+            startedAt,
+        });
+    }
     /**
      * Write success metrics for a specific method, and emit the matching
      * generation observation when per-call trace context is provided.
      */
     writeSuccessMetrics(params) {
-        const { method, model, usage: { inputTextTokens = 0, outputTextTokens = 0, inputAudioTokens = 0, outputAudioTokens = 0, }, writeMetrics, generationTrace, } = params;
-        const costs = (0, utilities_1.calculateCosts)(model, {
-            inputTextTokens,
-            outputTextTokens,
-            inputAudioTokens,
-            outputAudioTokens,
-        });
-        const input = inputTextTokens + inputAudioTokens;
-        const output = outputTextTokens + outputAudioTokens;
+        const { method, model, usage, writeMetrics, generationTrace, } = params;
+        const { tokens, costs } = this.buildGenerationAccounting({ model, usage });
         this.recordGenerationTrace({
             method,
             model,
             generationTrace,
-            usageDetails: {
-                input,
-                output,
-                total: input + output,
-            },
+            usageDetails: tokens,
             costDetails: {
                 input: costs.input,
                 output: costs.output,
@@ -212,13 +267,32 @@ class LLMBaseService {
             modelConfig: model?.config || null,
             method,
             status: 'success',
+            tokens,
+            costs,
+        });
+    }
+    /**
+     * Token totals and costs of one accounted call, in the shape both the metrics
+     * writer and a generation observation take.
+     */
+    buildGenerationAccounting(params) {
+        const { model, usage: { inputTextTokens = 0, outputTextTokens = 0, inputAudioTokens = 0, outputAudioTokens = 0, }, } = params;
+        const costs = (0, utilities_1.calculateCosts)(model, {
+            inputTextTokens,
+            outputTextTokens,
+            inputAudioTokens,
+            outputAudioTokens,
+        });
+        const input = inputTextTokens + inputAudioTokens;
+        const output = outputTextTokens + outputAudioTokens;
+        return {
             tokens: {
                 input,
                 output,
                 total: input + output,
             },
             costs,
-        });
+        };
     }
     /**
      * Write error metrics for a specific method, and emit the matching generation

package/dist/services/LLMBaseService.abstract.js.map

@@ -1 +1 @@
-{"version":3,"file":"LLMBaseService.abstract.js","sourceRoot":"","sources":["../../src/services/LLMBaseService.abstract.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"LLMBaseService.abstract.js","sourceRoot":"","sources":["../../src/services/LLMBaseService.abstract.ts"],"names":[],"mappings":"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"}

package/dist/services/agentRounds/LLMAgentRounds.d.ts

@@ -0,0 +1,32 @@
+import { type LLMAgentRoundSpec, type LLMAgentRoundWriter } from './agentRounds.typedefs';
+/**
+ * The per-round generation stream of a single agent run.
+ *
+ * A tool loop is a sequence of model rounds, and each of them is a generation
+ * in its own right: the conversation as it stood when the request went out, and
+ * what the model answered with. Providers put every provider call through
+ * `run`, which is what guarantees a round that throws is traced exactly like a
+ * round that succeeds, and that no round of the loop goes unrecorded.
+ *
+ * The recorder deliberately knows nothing about messages — the provider hands
+ * over its own native array as the round's input.
+ */
+export declare class LLMAgentRounds {
+    private readonly writeRound;
+    private didRecordRound;
+    constructor(writeRound: LLMAgentRoundWriter);
+    /**
+     * Whether any model round reached the tracer. A run that fails while still
+     * preparing its first request has no transcript to show, and its caller falls
+     * back to tracing the failure on its own.
+     */
+    get hasRecordedRound(): boolean;
+    /**
+     * Runs one provider call as a traced round. The provider's response is
+     * returned untouched and its failure rethrown unchanged: tracing never alters
+     * what the loop, or the caller, sees.
+     */
+    run<ProviderResponse>(round: LLMAgentRoundSpec<ProviderResponse>): Promise<ProviderResponse>;
+    private callProvider;
+    private recordSafely;
+}

package/dist/services/agentRounds/LLMAgentRounds.js

@@ -0,0 +1,77 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.LLMAgentRounds = void 0;
+/**
+ * The per-round generation stream of a single agent run.
+ *
+ * A tool loop is a sequence of model rounds, and each of them is a generation
+ * in its own right: the conversation as it stood when the request went out, and
+ * what the model answered with. Providers put every provider call through
+ * `run`, which is what guarantees a round that throws is traced exactly like a
+ * round that succeeds, and that no round of the loop goes unrecorded.
+ *
+ * The recorder deliberately knows nothing about messages — the provider hands
+ * over its own native array as the round's input.
+ */
+class LLMAgentRounds {
+    writeRound;
+    didRecordRound = false;
+    constructor(writeRound) {
+        this.writeRound = writeRound;
+    }
+    /**
+     * Whether any model round reached the tracer. A run that fails while still
+     * preparing its first request has no transcript to show, and its caller falls
+     * back to tracing the failure on its own.
+     */
+    get hasRecordedRound() {
+        return this.didRecordRound;
+    }
+    /**
+     * Runs one provider call as a traced round. The provider's response is
+     * returned untouched and its failure rethrown unchanged: tracing never alters
+     * what the loop, or the caller, sees.
+     */
+    async run(round) {
+        const startedAt = Date.now();
+        const response = await this.callProvider(round, startedAt);
+        try {
+            const { output, usage } = round.describeOutcome(response);
+            this.recordSafely({
+                input: round.input,
+                output,
+                usage,
+                startedAt,
+            });
+        }
+        catch {
+            return response;
+        }
+        return response;
+    }
+    async callProvider(round, startedAt) {
+        try {
+            return await round.call();
+        }
+        catch (error) {
+            this.recordSafely({
+                input: round.input,
+                startedAt,
+                error,
+                isError: true,
+            });
+            throw error;
+        }
+    }
+    recordSafely(round) {
+        try {
+            this.writeRound(round);
+            this.didRecordRound = true;
+        }
+        catch {
+            return;
+        }
+    }
+}
+exports.LLMAgentRounds = LLMAgentRounds;
+//# sourceMappingURL=LLMAgentRounds.js.map

package/dist/services/agentRounds/LLMAgentRounds.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"LLMAgentRounds.js","sourceRoot":"","sources":["../../../src/services/agentRounds/LLMAgentRounds.ts"],"names":[],"mappings":";;;AAMA;;;;;;;;;;;GAWG;AACH,MAAa,cAAc;IAGI;IAFrB,cAAc,GAAG,KAAK,CAAC;IAE/B,YAA6B,UAA+B;QAA/B,eAAU,GAAV,UAAU,CAAqB;IAAG,CAAC;IAEhE;;;;OAIG;IACH,IAAI,gBAAgB;QAClB,OAAO,IAAI,CAAC,cAAc,CAAC;IAC7B,CAAC;IAED;;;;OAIG;IACH,KAAK,CAAC,GAAG,CACP,KAA0C;QAE1C,MAAM,SAAS,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC;QAC7B,MAAM,QAAQ,GAAG,MAAM,IAAI,CAAC,YAAY,CAAC,KAAK,EAAE,SAAS,CAAC,CAAC;QAE3D,IAAI,CAAC;YACH,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE,GAAG,KAAK,CAAC,eAAe,CAAC,QAAQ,CAAC,CAAC;YAE1D,IAAI,CAAC,YAAY,CAAC;gBAChB,KAAK,EAAE,KAAK,CAAC,KAAK;gBAClB,MAAM;gBACN,KAAK;gBACL,SAAS;aACV,CAAC,CAAC;QACL,CAAC;QAAC,MAAM,CAAC;YACP,OAAO,QAAQ,CAAC;QAClB,CAAC;QAED,OAAO,QAAQ,CAAC;IAClB,CAAC;IAEO,KAAK,CAAC,YAAY,CACxB,KAA0C,EAC1C,SAAiB;QAEjB,IAAI,CAAC;YACH,OAAO,MAAM,KAAK,CAAC,IAAI,EAAE,CAAC;QAC5B,CAAC;QAAC,OAAO,KAAc,EAAE,CAAC;YACxB,IAAI,CAAC,YAAY,CAAC;gBAChB,KAAK,EAAE,KAAK,CAAC,KAAK;gBAClB,SAAS;gBACT,KAAK;gBACL,OAAO,EAAE,IAAI;aACd,CAAC,CAAC;YAEH,MAAM,KAAK,CAAC;QACd,CAAC;IACH,CAAC;IAEO,YAAY,CAAC,KAAoB;QACvC,IAAI,CAAC;YACH,IAAI,CAAC,UAAU,CAAC,KAAK,CAAC,CAAC;YACvB,IAAI,CAAC,cAAc,GAAG,IAAI,CAAC;QAC7B,CAAC;QAAC,MAAM,CAAC;YACP,OAAO;QACT,CAAC;IACH,CAAC;CACF;AAnED,wCAmEC"}

package/dist/services/agentRounds/agentRounds.typedefs.d.ts

@@ -0,0 +1,48 @@
+import { type LLMModelUsage } from '../../LLMService.typedefs';
+/**
+ * One model round of an agent tool loop, as its provider observed it.
+ *
+ * `input` is the provider-native message array the round was sent with. Each
+ * provider keeps its own representation, so a round carries whatever that
+ * provider actually assembled — system instructions included — rather than a
+ * shared message shape none of them speaks.
+ */
+interface LLMAgentRoundBase {
+    input: unknown;
+    /**
+     * The round's own token usage. Providers that report usage per call fill it
+     * on every round; one that only totals a run leaves it unset until the last
+     * round, which then carries the run total.
+     */
+    usage?: LLMModelUsage;
+    /** Epoch milliseconds stamped immediately before the provider call. */
+    startedAt: number;
+}
+interface LLMSuccessfulAgentRound extends LLMAgentRoundBase {
+    output: unknown;
+    error?: never;
+    isError?: false;
+}
+interface LLMFailedAgentRound extends LLMAgentRoundBase {
+    output?: never;
+    error: unknown;
+    isError: true;
+}
+export type LLMAgentRound = LLMSuccessfulAgentRound | LLMFailedAgentRound;
+/**
+ * What one round's response contributes to its generation. Produced by the
+ * provider because only the provider knows which part of its response is the
+ * assistant output and where that response reports its usage.
+ */
+export interface LLMAgentRoundOutcome {
+    output: unknown;
+    usage?: LLMModelUsage;
+}
+export interface LLMAgentRoundSpec<ProviderResponse> {
+    input: unknown;
+    call: () => Promise<ProviderResponse>;
+    describeOutcome: (response: ProviderResponse) => LLMAgentRoundOutcome;
+}
+/** Emits the generation observation of a single agent round. */
+export type LLMAgentRoundWriter = (round: LLMAgentRound) => void;
+export {};

package/dist/services/agentRounds/agentRounds.typedefs.js

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

package/dist/services/agentRounds/agentRounds.typedefs.js.map

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

package/dist/services/agentRounds/index.d.ts

@@ -0,0 +1,2 @@
+export * from './agentRounds.typedefs';
+export * from './LLMAgentRounds';

package/dist/services/agentRounds/index.js

@@ -0,0 +1,19 @@
+"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 });
+__exportStar(require("./agentRounds.typedefs"), exports);
+__exportStar(require("./LLMAgentRounds"), exports);
+//# sourceMappingURL=index.js.map

package/dist/services/agentRounds/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/services/agentRounds/index.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;AAAA,yDAAuC;AACvC,mDAAiC"}

package/dist/services/index.d.ts

@@ -1,3 +1,4 @@
+export * from './agentRounds';
 export * from './LLMBaseService.abstract';
 export * from './LLMCompletionService.abstract';
 export * from './LLMServicePurposeFactory.abstract';

package/dist/services/index.js

@@ -14,6 +14,7 @@ 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 });
+__exportStar(require("./agentRounds"), exports);
 __exportStar(require("./LLMBaseService.abstract"), exports);
 __exportStar(require("./LLMCompletionService.abstract"), exports);
 __exportStar(require("./LLMServicePurposeFactory.abstract"), exports);

package/dist/services/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/services/index.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;AAAA,4DAA0C;AAC1C,kEAAgD;AAChD,sEAAoD;AACpD,kEAAgD;AAChD,oEAAkD;AAClD,oEAAkD"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/services/index.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;AAAA,gDAA8B;AAC9B,4DAA0C;AAC1C,kEAAgD;AAChD,sEAAoD;AACpD,kEAAgD;AAChD,oEAAkD;AAClD,oEAAkD"}

package/dist/utilities/llmTracing/llmTracing.typedefs.d.ts

@@ -92,6 +92,7 @@ export interface LLMGatewayTracer {
     withTrace<Result>(name: string, context: LLMTraceContext, fn: () => Promise<Result>): Promise<Result>;
     recordGeneration(generation: LLMGenerationTraceRecord): void;
     withToolObservation<Result>(name: string, input: unknown, fn: () => Promise<Result>): Promise<Result>;
+    withAgentObservation<Result>(name: string, input: unknown, fn: () => Promise<Result>): Promise<Result>;
     /**
      * Updates the active trace of this tracer only (name/input replace, metadata
      * merges). A no-op outside an active scope. Isolated per tracer so it can

package/dist/utilities/llmTracing/noopLLMTracing.js

@@ -12,6 +12,9 @@ class NoopLLMGatewayTracer {
     async withToolObservation(_name, _input, fn) {
         return fn();
     }
+    async withAgentObservation(_name, _input, fn) {
+        return fn();
+    }
     updateActiveTrace() {
         // no-op when disabled
     }

package/dist/utilities/llmTracing/noopLLMTracing.js.map

@@ -1 +1 @@
-{"version":3,"file":"noopLLMTracing.js","sourceRoot":"","sources":["../../../src/utilities/llmTracing/noopLLMTracing.ts"],"names":[],"mappings":";;;AAMA,MAAM,oBAAoB;IACf,SAAS,GAAG,KAAK,CAAC;IAE3B,KAAK,CAAC,SAAS,CACb,KAAa,EACb,QAAyB,EACzB,EAAyB;QAEzB,OAAO,EAAE,EAAE,CAAC;IACd,CAAC;IAED,gBAAgB;QACd,sBAAsB;IACxB,CAAC;IAED,KAAK,CAAC,mBAAmB,CACvB,KAAa,EACb,MAAe,EACf,EAAyB;QAEzB,OAAO,EAAE,EAAE,CAAC;IACd,CAAC;IAED,iBAAiB;QACf,sBAAsB;IACxB,CAAC;IAED,qBAAqB;QACnB,OAAO,SAAS,CAAC;IACnB,CAAC;IAED,KAAK,CAAC,KAAK;QACT,sBAAsB;IACxB,CAAC;IAED,KAAK,CAAC,QAAQ;QACZ,sBAAsB;IACxB,CAAC;CACF;AAEY,QAAA,oBAAoB,GAAqB,IAAI,oBAAoB,EAAE,CAAC;AAE1E,MAAM,yBAAyB,GAA6B,GAAG,EAAE;IACtE,oCAAoC;AACtC,CAAC,CAAC;AAFW,QAAA,yBAAyB,6BAEpC"}
+{"version":3,"file":"noopLLMTracing.js","sourceRoot":"","sources":["../../../src/utilities/llmTracing/noopLLMTracing.ts"],"names":[],"mappings":";;;AAMA,MAAM,oBAAoB;IACf,SAAS,GAAG,KAAK,CAAC;IAE3B,KAAK,CAAC,SAAS,CACb,KAAa,EACb,QAAyB,EACzB,EAAyB;QAEzB,OAAO,EAAE,EAAE,CAAC;IACd,CAAC;IAED,gBAAgB;QACd,sBAAsB;IACxB,CAAC;IAED,KAAK,CAAC,mBAAmB,CACvB,KAAa,EACb,MAAe,EACf,EAAyB;QAEzB,OAAO,EAAE,EAAE,CAAC;IACd,CAAC;IAED,KAAK,CAAC,oBAAoB,CACxB,KAAa,EACb,MAAe,EACf,EAAyB;QAEzB,OAAO,EAAE,EAAE,CAAC;IACd,CAAC;IAED,iBAAiB;QACf,sBAAsB;IACxB,CAAC;IAED,qBAAqB;QACnB,OAAO,SAAS,CAAC;IACnB,CAAC;IAED,KAAK,CAAC,KAAK;QACT,sBAAsB;IACxB,CAAC;IAED,KAAK,CAAC,QAAQ;QACZ,sBAAsB;IACxB,CAAC;CACF;AAEY,QAAA,oBAAoB,GAAqB,IAAI,oBAAoB,EAAE,CAAC;AAE1E,MAAM,yBAAyB,GAA6B,GAAG,EAAE;IACtE,oCAAoC;AACtC,CAAC,CAAC;AAFW,QAAA,yBAAyB,6BAEpC"}

package/package.json

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

package/dist/client/codegen/extractVariables.d.ts

@@ -1,7 +0,0 @@
-/**
- * Extracts the plain variable names a prompt references, matching the runtime
- * compile path (only `{{var}}` survives the conditional drop, see plan §1.3).
- * Section/closer tokens (`{{#cond}}`, `{{/cond}}`) are excluded so the generated
- * required-variable set agrees with what the validation gate counts as provided.
- */
-export declare function extractRequiredVariables(promptText: string): string[];

package/dist/client/codegen/extractVariables.js

@@ -1,21 +0,0 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.extractRequiredVariables = extractRequiredVariables;
-const VARIABLE_PATTERN = /{{\s*([\w.]+)\s*}}/g;
-/**
- * Extracts the plain variable names a prompt references, matching the runtime
- * compile path (only `{{var}}` survives the conditional drop, see plan §1.3).
- * Section/closer tokens (`{{#cond}}`, `{{/cond}}`) are excluded so the generated
- * required-variable set agrees with what the validation gate counts as provided.
- */
-function extractRequiredVariables(promptText) {
-    const names = new Set();
-    for (const match of promptText.matchAll(VARIABLE_PATTERN)) {
-        const token = match[1];
-        if (!token.startsWith('#') && !token.startsWith('/')) {
-            names.add(token);
-        }
-    }
-    return [...names].sort();
-}
-//# sourceMappingURL=extractVariables.js.map

package/dist/client/codegen/extractVariables.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"extractVariables.js","sourceRoot":"","sources":["../../../src/client/codegen/extractVariables.ts"],"names":[],"mappings":";;AAQA,4DAYC;AApBD,MAAM,gBAAgB,GAAG,qBAAqB,CAAC;AAE/C;;;;;GAKG;AACH,SAAgB,wBAAwB,CAAC,UAAkB;IACzD,MAAM,KAAK,GAAG,IAAI,GAAG,EAAU,CAAC;IAEhC,KAAK,MAAM,KAAK,IAAI,UAAU,CAAC,QAAQ,CAAC,gBAAgB,CAAC,EAAE,CAAC;QAC1D,MAAM,KAAK,GAAG,KAAK,CAAC,CAAC,CAAC,CAAC;QAEvB,IAAI,CAAC,KAAK,CAAC,UAAU,CAAC,GAAG,CAAC,IAAI,CAAC,KAAK,CAAC,UAAU,CAAC,GAAG,CAAC,EAAE,CAAC;YACrD,KAAK,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC;QACnB,CAAC;IACH,CAAC;IAED,OAAO,CAAC,GAAG,KAAK,CAAC,CAAC,IAAI,EAAE,CAAC;AAC3B,CAAC"}