@mate-academy/llm-gateway 8.8.2 → 8.8.4

package/dist/LLMError.d.ts

@@ -0,0 +1,12 @@
+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

@@ -0,0 +1,36 @@
+"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

@@ -0,0 +1 @@
+{"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

@@ -0,0 +1,30 @@
+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

@@ -0,0 +1,56 @@
+"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

@@ -0,0 +1 @@
+{"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

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

package/dist/LLMGateway.typedefs.js

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

package/dist/LLMGateway.typedefs.js.map

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