@mate-academy/llm-gateway 8.8.2 → 8.8.3

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

@@ -0,0 +1,4 @@
+export { InMemoryFileStorage } from './InMemoryFileStorage';
+export { FileStorageToolExecutor } from './FileStorageToolExecutor';
+export { getFileStorageToolsForChatCompletions, FileStorageToolName, } from './fileStorageTools';
+export type { SearchFilesArgs, ReadFileArgs, ReadFileLinesArgs, } from './fileStorageTools';

package/dist/services/fileStorage/index.js

@@ -0,0 +1,11 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.FileStorageToolName = exports.getFileStorageToolsForChatCompletions = exports.FileStorageToolExecutor = exports.InMemoryFileStorage = void 0;
+var InMemoryFileStorage_1 = require("./InMemoryFileStorage");
+Object.defineProperty(exports, "InMemoryFileStorage", { enumerable: true, get: function () { return InMemoryFileStorage_1.InMemoryFileStorage; } });
+var FileStorageToolExecutor_1 = require("./FileStorageToolExecutor");
+Object.defineProperty(exports, "FileStorageToolExecutor", { enumerable: true, get: function () { return FileStorageToolExecutor_1.FileStorageToolExecutor; } });
+var fileStorageTools_1 = require("./fileStorageTools");
+Object.defineProperty(exports, "getFileStorageToolsForChatCompletions", { enumerable: true, get: function () { return fileStorageTools_1.getFileStorageToolsForChatCompletions; } });
+Object.defineProperty(exports, "FileStorageToolName", { enumerable: true, get: function () { return fileStorageTools_1.FileStorageToolName; } });
+//# sourceMappingURL=index.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/services/fileStorage/index.ts"],"names":[],"mappings":";;;AAAA,6DAA4D;AAAnD,0HAAA,mBAAmB,OAAA;AAC5B,qEAAoE;AAA3D,kIAAA,uBAAuB,OAAA;AAChC,uDAG4B;AAF1B,yIAAA,qCAAqC,OAAA;AACrC,uHAAA,mBAAmB,OAAA"}

package/dist/services/index.d.ts

@@ -0,0 +1,7 @@
+export * from './agentRounds';
+export * from './LLMBaseService.abstract';
+export * from './LLMCompletionService.abstract';
+export * from './LLMServicePurposeFactory.abstract';
+export * from './LLMAssistanceService.abstract';
+export * from './LLMSpeechToTextService.abstract';
+export * from './LLMTextToSpeechService.abstract';

package/dist/services/index.js

@@ -0,0 +1,24 @@
+"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"), exports);
+__exportStar(require("./LLMBaseService.abstract"), exports);
+__exportStar(require("./LLMCompletionService.abstract"), exports);
+__exportStar(require("./LLMServicePurposeFactory.abstract"), exports);
+__exportStar(require("./LLMAssistanceService.abstract"), exports);
+__exportStar(require("./LLMSpeechToTextService.abstract"), exports);
+__exportStar(require("./LLMTextToSpeechService.abstract"), exports);
+//# sourceMappingURL=index.js.map

package/dist/services/index.js.map

@@ -0,0 +1 @@
+{"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/calculateCosts.d.ts

@@ -0,0 +1,4 @@
+import { type LLMProviders, type LLMModel, type LLMModelUsage, type LLMCostsResult } from '../LLMService.typedefs';
+export type { LLMModelUsage, LLMCostsResult } from '../LLMService.typedefs';
+export declare function addUsage(first: LLMModelUsage, second: LLMModelUsage): LLMModelUsage;
+export declare const calculateCosts: <Provider extends LLMProviders>(model: LLMModel<Provider> | null, usage: LLMModelUsage) => LLMCostsResult;

package/dist/utilities/calculateCosts.js

@@ -0,0 +1,56 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.calculateCosts = void 0;
+exports.addUsage = addUsage;
+const USAGE_TOKEN_KEY_MAP = {
+    inputTextTokens: true,
+    outputTextTokens: true,
+    inputAudioTokens: true,
+    outputAudioTokens: true,
+    inputCachedTextTokens: true,
+    inputCachedAudioTokens: true,
+    outputReasoningTokens: true,
+};
+const USAGE_TOKEN_KEYS = Object.keys(USAGE_TOKEN_KEY_MAP);
+function addUsage(first, second) {
+    return USAGE_TOKEN_KEYS.reduce((accumulated, tokenKey) => {
+        const total = (first[tokenKey] ?? 0) + (second[tokenKey] ?? 0);
+        if (total === 0) {
+            return accumulated;
+        }
+        return { ...accumulated, [tokenKey]: total };
+    }, {});
+}
+const calculateCosts = (model, usage) => {
+    const { inputTextTokens = 0, outputTextTokens = 0, inputAudioTokens = 0, outputAudioTokens = 0, inputCachedTextTokens = 0, inputCachedAudioTokens = 0, outputReasoningTokens = 0, } = usage;
+    if (!model) {
+        return {
+            input: 0,
+            output: 0,
+            total: 0,
+            currency: 'USD',
+        };
+    }
+    const { pricing } = model;
+    // Regular input costs
+    const regularInputCost = (pricing.getPriceForTextInput(inputTextTokens)
+        + pricing.getPriceForAudioInput(inputAudioTokens));
+    // Cached input costs (use discounted rate if available, otherwise fall back to regular rate)
+    const cachedInputCost = ((pricing.getPriceForCachedTextInput?.(inputCachedTextTokens)
+        ?? pricing.getPriceForTextInput(inputCachedTextTokens))
+        + (pricing.getPriceForCachedAudioInput?.(inputCachedAudioTokens)
+            ?? pricing.getPriceForAudioInput(inputCachedAudioTokens)));
+    // Output costs (reasoning tokens are charged as output tokens)
+    const outputCost = (pricing.getPriceForTextOutput(outputTextTokens + outputReasoningTokens)
+        + pricing.getPriceForAudioOutput(outputAudioTokens));
+    const totalInputCost = regularInputCost + cachedInputCost;
+    const totalCost = totalInputCost + outputCost;
+    return {
+        input: Number(totalInputCost.toFixed(6)),
+        output: Number(outputCost.toFixed(6)),
+        total: Number(totalCost.toFixed(6)),
+        currency: model.pricing.currency,
+    };
+};
+exports.calculateCosts = calculateCosts;
+//# sourceMappingURL=calculateCosts.js.map

package/dist/utilities/calculateCosts.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"calculateCosts.js","sourceRoot":"","sources":["../../src/utilities/calculateCosts.ts"],"names":[],"mappings":";;;AAuBA,4BAgBC;AA9BD,MAAM,mBAAmB,GAAG;IAC1B,eAAe,EAAE,IAAI;IACrB,gBAAgB,EAAE,IAAI;IACtB,gBAAgB,EAAE,IAAI;IACtB,iBAAiB,EAAE,IAAI;IACvB,qBAAqB,EAAE,IAAI;IAC3B,sBAAsB,EAAE,IAAI;IAC5B,qBAAqB,EAAE,IAAI;CAC0B,CAAC;AAExD,MAAM,gBAAgB,GAAG,MAAM,CAAC,IAAI,CAClC,mBAAmB,CACO,CAAC;AAE7B,SAAgB,QAAQ,CACtB,KAAoB,EACpB,MAAqB;IAErB,OAAO,gBAAgB,CAAC,MAAM,CAC5B,CAAC,WAAW,EAAE,QAAQ,EAAE,EAAE;QACxB,MAAM,KAAK,GAAG,CAAC,KAAK,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAC,GAAG,CAAC,MAAM,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAC,CAAC;QAE/D,IAAI,KAAK,KAAK,CAAC,EAAE,CAAC;YAChB,OAAO,WAAW,CAAC;QACrB,CAAC;QAED,OAAO,EAAE,GAAG,WAAW,EAAE,CAAC,QAAQ,CAAC,EAAE,KAAK,EAAE,CAAC;IAC/C,CAAC,EACD,EAAE,CACH,CAAC;AACJ,CAAC;AAEM,MAAM,cAAc,GAAG,CAC5B,KAAgC,EAChC,KAAoB,EACJ,EAAE;IAClB,MAAM,EACJ,eAAe,GAAG,CAAC,EACnB,gBAAgB,GAAG,CAAC,EACpB,gBAAgB,GAAG,CAAC,EACpB,iBAAiB,GAAG,CAAC,EACrB,qBAAqB,GAAG,CAAC,EACzB,sBAAsB,GAAG,CAAC,EAC1B,qBAAqB,GAAG,CAAC,GAC1B,GAAG,KAAK,CAAC;IAEV,IAAI,CAAC,KAAK,EAAE,CAAC;QACX,OAAO;YACL,KAAK,EAAE,CAAC;YACR,MAAM,EAAE,CAAC;YACT,KAAK,EAAE,CAAC;YACR,QAAQ,EAAE,KAAK;SAChB,CAAC;IACJ,CAAC;IAED,MAAM,EAAE,OAAO,EAAE,GAAG,KAAK,CAAC;IAE1B,sBAAsB;IACtB,MAAM,gBAAgB,GAAG,CACvB,OAAO,CAAC,oBAAoB,CAAC,eAAe,CAAC;UAC3C,OAAO,CAAC,qBAAqB,CAAC,gBAAgB,CAAC,CAClD,CAAC;IAEF,6FAA6F;IAC7F,MAAM,eAAe,GAAG,CACtB,CAAC,OAAO,CAAC,0BAA0B,EAAE,CAAC,qBAAqB,CAAC;WACvD,OAAO,CAAC,oBAAoB,CAAC,qBAAqB,CAAC,CAAC;UACvD,CAAC,OAAO,CAAC,2BAA2B,EAAE,CAAC,sBAAsB,CAAC;eAC3D,OAAO,CAAC,qBAAqB,CAAC,sBAAsB,CAAC,CAAC,CAC5D,CAAC;IAEF,+DAA+D;IAC/D,MAAM,UAAU,GAAG,CACjB,OAAO,CAAC,qBAAqB,CAAC,gBAAgB,GAAG,qBAAqB,CAAC;UACrE,OAAO,CAAC,sBAAsB,CAAC,iBAAiB,CAAC,CACpD,CAAC;IAEF,MAAM,cAAc,GAAG,gBAAgB,GAAG,eAAe,CAAC;IAC1D,MAAM,SAAS,GAAG,cAAc,GAAG,UAAU,CAAC;IAE9C,OAAO;QACL,KAAK,EAAE,MAAM,CAAC,cAAc,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC;QACxC,MAAM,EAAE,MAAM,CAAC,UAAU,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC;QACrC,KAAK,EAAE,MAAM,CAAC,SAAS,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC;QACnC,QAAQ,EAAE,KAAK,CAAC,OAAO,CAAC,QAAQ;KACjC,CAAC;AACJ,CAAC,CAAC;AAtDW,QAAA,cAAc,kBAsDzB"}

package/dist/utilities/functional.utils.d.ts

@@ -0,0 +1 @@
+export declare const pick: <T, K extends keyof T>(obj: T, keys: K[]) => Pick<T, K>;

package/dist/utilities/functional.utils.js

@@ -0,0 +1,9 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.pick = void 0;
+const pick = (obj, keys) => (keys.reduce((acc, key) => {
+    Object.assign(acc, { [key]: obj[key] });
+    return acc;
+}, {}));
+exports.pick = pick;
+//# sourceMappingURL=functional.utils.js.map

package/dist/utilities/functional.utils.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"functional.utils.js","sourceRoot":"","sources":["../../src/utilities/functional.utils.ts"],"names":[],"mappings":";;;AAAO,MAAM,IAAI,GAAG,CAAuB,GAAM,EAAE,IAAS,EAAc,EAAE,CAAC,CAC3E,IAAI,CAAC,MAAM,CAAC,CAAC,GAAG,EAAE,GAAG,EAAE,EAAE;IACvB,MAAM,CAAC,MAAM,CAAC,GAAG,EAAE,EAAE,CAAC,GAAG,CAAC,EAAE,GAAG,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;IAExC,OAAO,GAAG,CAAC;AACb,CAAC,EAAE,EAAgB,CAAC,CACrB,CAAC;AANW,QAAA,IAAI,QAMf"}

package/dist/utilities/index.d.ts

@@ -0,0 +1,9 @@
+export * from './functional.utils';
+export * from './llmTracing';
+export * from './promptBuilder';
+export * from './calculateCosts';
+export * from './logger';
+export * from './reporter';
+export * from './schema';
+export * from './serializeError';
+export * from './tools';

package/dist/utilities/index.js

@@ -0,0 +1,26 @@
+"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("./functional.utils"), exports);
+__exportStar(require("./llmTracing"), exports);
+__exportStar(require("./promptBuilder"), exports);
+__exportStar(require("./calculateCosts"), exports);
+__exportStar(require("./logger"), exports);
+__exportStar(require("./reporter"), exports);
+__exportStar(require("./schema"), exports);
+__exportStar(require("./serializeError"), exports);
+__exportStar(require("./tools"), exports);
+//# sourceMappingURL=index.js.map

package/dist/utilities/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/utilities/index.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;AAAA,qDAAmC;AACnC,+CAA6B;AAC7B,kDAAgC;AAChC,mDAAiC;AACjC,2CAAyB;AACzB,6CAA2B;AAC3B,2CAAyB;AACzB,mDAAiC;AACjC,0CAAwB"}

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

@@ -0,0 +1,3 @@
+export * from './llmTracing.typedefs';
+export * from './llmTracing.constants';
+export * from './noopLLMTracing';

package/dist/utilities/llmTracing/index.js

@@ -0,0 +1,20 @@
+"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("./llmTracing.typedefs"), exports);
+__exportStar(require("./llmTracing.constants"), exports);
+__exportStar(require("./noopLLMTracing"), exports);
+//# sourceMappingURL=index.js.map

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

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

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

@@ -0,0 +1,7 @@
+/**
+ * CloudWatch namespace + metric name for the prompt-fallback-serving alarm.
+ * The alarm is provisioned against these exact string values, so they are a
+ * published contract — renaming a value requires re-pointing the alarm first.
+ */
+export declare const LLM_GATEWAY_METRIC_NAMESPACE = "LLMGateway";
+export declare const PROMPT_FALLBACK_SERVED_METRIC = "LangfuseFallbackServed";

package/dist/utilities/llmTracing/llmTracing.constants.js

@@ -0,0 +1,11 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PROMPT_FALLBACK_SERVED_METRIC = exports.LLM_GATEWAY_METRIC_NAMESPACE = void 0;
+/**
+ * CloudWatch namespace + metric name for the prompt-fallback-serving alarm.
+ * The alarm is provisioned against these exact string values, so they are a
+ * published contract — renaming a value requires re-pointing the alarm first.
+ */
+exports.LLM_GATEWAY_METRIC_NAMESPACE = 'LLMGateway';
+exports.PROMPT_FALLBACK_SERVED_METRIC = 'LangfuseFallbackServed';
+//# sourceMappingURL=llmTracing.constants.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"llmTracing.constants.js","sourceRoot":"","sources":["../../../src/utilities/llmTracing/llmTracing.constants.ts"],"names":[],"mappings":";;;AAAA;;;;GAIG;AACU,QAAA,4BAA4B,GAAG,YAAY,CAAC;AAE5C,QAAA,6BAA6B,GAAG,wBAAwB,CAAC"}

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

@@ -0,0 +1,126 @@
+/**
+ * Trace/observation metadata. Values are coerced to strings before they reach
+ * the SDK, so callers may pass scalars.
+ */
+export type LLMTraceMetadata = Record<string, string | number | boolean>;
+export interface LLMTraceContext {
+    /** Overrides the trace name (defaults to the wrapping operation name). */
+    name?: string;
+    userId?: string;
+    sessionId?: string;
+    tags?: string[];
+    metadata?: LLMTraceMetadata;
+}
+/**
+ * Structural reference to the managed prompt a generation was produced from.
+ * SDK-free by design: the gateway only carries `name`/`version`/`isFallback`,
+ * and the tracer implementation turns it into a prompt link (a fallback
+ * prompt intentionally produces no link).
+ */
+export interface LLMTracedPrompt {
+    name: string;
+    version: number;
+    isFallback?: boolean;
+}
+/**
+ * Escape-hatch update applied to the active trace of a single tracer. `name`,
+ * `input` and `output` replace the previous values; `metadata` merges. Outside
+ * an active scope the call is a safe no-op.
+ *
+ * `output` is the only way a trace gets one: the root never harvests the
+ * wrapped operation's return value, so a feature that wants a meaningful trace
+ * output states it here, in whatever trimmed shape is worth reading.
+ */
+export interface LLMActiveTraceUpdate {
+    name?: string;
+    input?: unknown;
+    output?: unknown;
+    metadata?: LLMTraceMetadata;
+}
+/**
+ * Per-call generation capture passed from a provider service to the base
+ * service's success/error metric points. The observation name defaults to the
+ * service method when no prompt name is threaded through.
+ */
+export interface LLMGenerationTrace {
+    name: string;
+    input?: unknown;
+    output?: unknown;
+    modelParameters?: Record<string, unknown>;
+    metadata?: LLMTraceMetadata;
+    /**
+     * The managed prompt this generation used. Threaded through so the tracer can
+     * link the observation to its prompt version.
+     */
+    prompt?: LLMTracedPrompt;
+    /**
+     * The user this call was made for. A typed trace attribute, never a metadata
+     * key: the tracer promotes it to the trace's own user field, which is what
+     * Langfuse filters and groups on.
+     */
+    userId?: string;
+    /**
+     * Groups every trace of one conversation, review, or agent run under a single
+     * Langfuse session. Typed trace attribute, never a metadata key.
+     */
+    sessionId?: string;
+    /** Langfuse trace tags. Typed trace attribute, never a metadata key. */
+    tags?: string[];
+    /** Epoch milliseconds captured immediately before the provider call. */
+    startedAt: number;
+}
+/**
+ * Full per-call generation record passed to `recordGeneration`. Extracted from
+ * `LLMGenerationTrace` so the gateway and `@mate-academy/llm-tracer` share the
+ * exact same recorded shape.
+ */
+export interface LLMGenerationTraceRecord extends LLMGenerationTrace {
+    /** Epoch milliseconds stamped when the generation is handed to the tracer. */
+    endedAt: number;
+    model: string | null;
+    usageDetails?: Record<string, number>;
+    costDetails?: Record<string, number>;
+    isError?: boolean;
+}
+/**
+ * The tracing surface the gateway depends on. Any implementation (the no-op,
+ * or a real tracer from `@mate-academy/llm-tracer`) satisfies it, so
+ * consumers hold a single type regardless of whether tracing is configured.
+ */
+export interface LLMGatewayTracer {
+    readonly isEnabled: boolean;
+    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
+     * never touch another project's trace.
+     */
+    updateActiveTrace(update: LLMActiveTraceUpdate): void;
+    /**
+     * The context the active scope was opened with, or `undefined` outside a
+     * scope. It is what lets a consumer resolve what the surrounding operation
+     * declared (its user, session, tags) without the application threading that
+     * context through every call.
+     */
+    getActiveTraceContext(): LLMTraceContext | undefined;
+    flush(): Promise<void>;
+    /**
+     * Tears down the tracer's provider/exporter. Optional so a 7.8 minor does not
+     * break external structural implementations that predate the method.
+     */
+    shutdown?(): Promise<void>;
+}
+export interface LLMFallbackMetricDimensions {
+    feature?: string;
+    promptName?: string;
+    reason?: string;
+}
+/**
+ * Emits a single fallback-served data point. Consumers inject a real CloudWatch
+ * implementation when they build the gateway; the default is a no-op so the
+ * gateway carries no AWS dependency and tracing stays fire-and-forget.
+ */
+export type LLMFallbackMetricEmitter = (dimensions: LLMFallbackMetricDimensions) => void;

package/dist/utilities/llmTracing/llmTracing.typedefs.js

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

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

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

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

@@ -0,0 +1,3 @@
+import { type LLMFallbackMetricEmitter, type LLMGatewayTracer } from '../../utilities/llmTracing/llmTracing.typedefs';
+export declare const noopLLMGatewayTracer: LLMGatewayTracer;
+export declare const noopFallbackMetricEmitter: LLMFallbackMetricEmitter;

package/dist/utilities/llmTracing/noopLLMTracing.js

@@ -0,0 +1,36 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.noopFallbackMetricEmitter = exports.noopLLMGatewayTracer = void 0;
+class NoopLLMGatewayTracer {
+    isEnabled = false;
+    async withTrace(_name, _context, fn) {
+        return fn();
+    }
+    recordGeneration() {
+        // no-op when disabled
+    }
+    async withToolObservation(_name, _input, fn) {
+        return fn();
+    }
+    async withAgentObservation(_name, _input, fn) {
+        return fn();
+    }
+    updateActiveTrace() {
+        // no-op when disabled
+    }
+    getActiveTraceContext() {
+        return undefined;
+    }
+    async flush() {
+        // no-op when disabled
+    }
+    async shutdown() {
+        // no-op when disabled
+    }
+}
+exports.noopLLMGatewayTracer = new NoopLLMGatewayTracer();
+const noopFallbackMetricEmitter = () => {
+    // no-op when no emitter is injected
+};
+exports.noopFallbackMetricEmitter = noopFallbackMetricEmitter;
+//# sourceMappingURL=noopLLMTracing.js.map

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

@@ -0,0 +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,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/dist/utilities/logger/LLMLoggerInterface.d.ts

@@ -0,0 +1,36 @@
+/**
+ * Internal logger interface for the LLM Gateway package.
+ * Compatible with common logging libraries.
+ */
+export interface LLMLoggerInterface {
+    /**
+     * Log informational messages
+     * @param message - The message to log
+     * @param meta - Optional metadata to include with the log
+     */
+    info(message: string, meta?: Record<string, any>): void;
+    /**
+     * Log error messages
+     * @param message - The error message to log
+     * @param meta - Optional metadata to include with the log
+     */
+    error(message: string, meta?: Record<string, any>): void;
+    /**
+     * Log warning messages
+     * @param message - The warning message to log
+     * @param meta - Optional metadata to include with the log
+     */
+    warn(message: string, meta?: Record<string, any>): void;
+    /**
+     * Log debug messages (optional)
+     * @param message - The debug message to log
+     * @param meta - Optional metadata to include with the log
+     */
+    debug?(message: string, meta?: Record<string, any>): void;
+    /**
+     * Create a child logger with additional context
+     * @param context - The context to add to the child logger
+     * @returns A new logger instance with the additional context
+     */
+    child(context: string): LLMLoggerInterface;
+}

package/dist/utilities/logger/LLMLoggerInterface.js

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

package/dist/utilities/logger/LLMLoggerInterface.js.map

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

package/dist/utilities/logger/index.d.ts

@@ -0,0 +1 @@
+export * from './LLMLoggerInterface';

package/dist/utilities/logger/index.js

@@ -0,0 +1,18 @@
+"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("./LLMLoggerInterface"), exports);
+//# sourceMappingURL=index.js.map

package/dist/utilities/logger/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/utilities/logger/index.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;AAAA,uDAAqC"}

package/dist/utilities/promptBuilder.d.ts

@@ -0,0 +1,58 @@
+/**
+ * Utility types and functions for handling prompts with dynamic replacements and conditional sections.
+ * This allows for type-safe string templates with placeholders that can be replaced with actual values.
+ * The `createPromptTemplate` function helps create typed prompts with automatic extraction of replacement keys.
+ *
+ * @module promptBuilder
+ * @example
+ * // Example usage:
+ * const PROMPTS = {
+ *   welcomeMessage: createPromptTemplate(`
+ *     Generate a welcome message for a user who has just started their auto tech check attempt on {{topicTitle}}.
+ *     {{#hasBonus}}
+ *       This topic includes bonus content: {{bonusContent}}
+ *     {{/hasBonus}}
+ *
+ *     {{#valueAsCondition}}
+ *       This is a conditional section that will only appear if the value is truthy.
+ *       Value can be used inside the section: {{valueAsCondition}}
+ *     {{/valueAsCondition}}
+ *
+ *     {{#!skipSection}}
+ *       This negative conditional section will only appear if skipSection is falsy.
+ *     {{/skipSection}}
+ *  `),
+ * };
+ *
+ * const instruction = PROMPTS.welcomeMessage({
+ *   topicTitle: 'JavaScript Basics',
+ *   hasBonus: true,
+ *   bonusContent: 'Advanced debugging techniques',
+ * });
+ *
+ * // This will generate a prompt:
+ * // "Generate a welcome message for a user who has just started their auto tech check attempt on JavaScript Basics.
+ * //  This topic includes bonus content: Advanced debugging techniques"
+ */
+type RegularValue = string | number;
+type ConditionalValue = RegularValue | boolean | undefined | null;
+type ExtractAllVariables<T extends string> = T extends `${string}{{${infer Key}}}${infer Rest}` ? Key extends `${infer CleanKey}` ? CleanKey | ExtractAllVariables<Rest> : never : never;
+type ExtractSectionVariables<T extends string> = T extends `${string}{{#!${infer Key}}}${infer Rest}` ? Key | ExtractSectionVariables<Rest> : T extends `${string}{{#${infer Key}}}${infer Rest}` ? Key | ExtractSectionVariables<Rest> : never;
+type ExtractClosingTagVariables<T extends string> = T extends `${string}{{/${infer Key}}}${infer Rest}` ? Key | ExtractClosingTagVariables<Rest> : never;
+type AllSectionVariables<T extends string> = ExtractSectionVariables<T> | ExtractClosingTagVariables<T>;
+type ExtractRegularVariables<T extends string> = ExtractAllVariables<T> extends infer All ? All extends string ? All extends `#!${string}` | `#${string}` | `/${string}` ? never : All : never : never;
+type CreateVariableRecord<T extends string> = ExtractRegularVariables<T> extends never ? AllSectionVariables<T> extends never ? Record<string, never> : Record<AllSectionVariables<T>, ConditionalValue> : AllSectionVariables<T> extends never ? Record<ExtractRegularVariables<T>, RegularValue> : Omit<Record<ExtractRegularVariables<T>, RegularValue>, AllSectionVariables<T>> & Record<AllSectionVariables<T>, ConditionalValue>;
+type HasVariables<T extends string> = ExtractAllVariables<T> extends never ? false : true;
+/**
+ * Creates a prompt template function that can be used to generate prompts
+ * with dynamic replacements and conditional sections.
+ * @template T The type of the template string. Inferred from the provided template.
+ * @param {T} template The template string with placeholders:
+ * - for dynamic values (e.g., `{{topicTitle}}`)
+ * - for conditional sections (e.g., `{{#section}}...{{/section}}`)
+ * - for negative conditional sections (e.g., `{{#!section}}...{{/section}}`)
+ * - for sections that use conditional variables as values (e.g., `{{#bonus}}...{{bonus}}...{{/bonus}}`)
+ * @returns A function that takes the dynamic values and returns the generated prompt.
+ */
+export declare function createPromptTemplate<T extends string>(template: T): (...args: HasVariables<T> extends false ? [] : [variables: CreateVariableRecord<T>]) => string;
+export {};