@mate-academy/llm-gateway 8.8.2 → 8.8.3

package/dist/providers/OpenAICompatible/OpenAICompatibleSpeechToText.service.js

@@ -0,0 +1,98 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.OpenAICompatibleSpeechToTextService = void 0;
+const fs_1 = require("fs");
+const openai_1 = require("openai");
+const utilities_1 = require("../../utilities");
+const services_1 = require("../../services");
+const OpenAI_entity_1 = require("../../providers/OpenAI/OpenAI.entity");
+const mime_types_1 = __importDefault(require("mime-types"));
+class OpenAICompatibleSpeechToTextService extends services_1.LLMSpeechToTextService {
+    constructor(provider, logger, reporter, options) {
+        super(provider, logger, reporter, options);
+    }
+    get instance() {
+        return this.getOrCreateInstance(() => new openai_1.OpenAI(this.options));
+    }
+    get transcribeLimits() {
+        return OpenAI_entity_1.OpenAIEntity.transcribeLimits;
+    }
+    buildTranscriptionParams(options, audioFileStream) {
+        return {
+            model: options.model.name,
+            file: audioFileStream,
+            response_format: 'json',
+            prompt: options.instructions,
+        };
+    }
+    async transcribe(options) {
+        const { model, pathToAudio, mimeType, instructions, abortSignal, reporterContext, traceContext, } = options;
+        const writeMetrics = this.reporter?.initWriter(reporterContext);
+        const method = this.getMethodName(this.transcribe);
+        const generationStartedAt = Date.now();
+        try {
+            abortSignal?.throwIfAborted();
+            const { maxFileSize, supportedMimeTypes, } = this.transcribeLimits;
+            const fileSize = (0, fs_1.statSync)(pathToAudio).size;
+            if (fileSize > maxFileSize) {
+                throw new Error(`File size exceeds the limit of ${maxFileSize} bytes`);
+            }
+            const resolvedMimeType = mimeType ?? mime_types_1.default.lookup(pathToAudio);
+            if (!resolvedMimeType || !supportedMimeTypes.includes(resolvedMimeType)) {
+                throw new Error(`Unsupported audio file type: ${resolvedMimeType}. Supported types are: ${supportedMimeTypes.join(', ')}`);
+            }
+            const audioFileStream = (0, fs_1.createReadStream)(pathToAudio, { signal: abortSignal });
+            abortSignal?.throwIfAborted();
+            const params = this.buildTranscriptionParams(options, audioFileStream);
+            const response = await this.instance.audio.transcriptions.create(params, {
+                signal: abortSignal,
+            });
+            abortSignal?.throwIfAborted();
+            const usage = this.extractUsage(response, fileSize);
+            await this.writeSuccessMetrics({
+                method,
+                model,
+                usage,
+                writeMetrics,
+                generationTrace: this.buildGenerationTrace({
+                    method,
+                    traceContext,
+                    input: { pathToAudio, instructions },
+                    output: response.text,
+                    modelParameters: model.config,
+                    startedAt: generationStartedAt,
+                }),
+            });
+            return { text: response.text, usage, cost: (0, utilities_1.calculateCosts)(model, usage) };
+        }
+        catch (error) {
+            await this.writeErrorMetrics({
+                method,
+                model,
+                isAborted: abortSignal?.aborted,
+                writeMetrics,
+                error,
+                generationTrace: this.buildGenerationTrace({
+                    method,
+                    traceContext,
+                    input: { pathToAudio, instructions },
+                    modelParameters: model.config,
+                    startedAt: generationStartedAt,
+                }),
+            });
+            this.logRequestFailure({
+                method,
+                message: 'Error transcribing audio',
+                error,
+                isAborted: abortSignal?.aborted,
+                meta: { options },
+            });
+            return { error };
+        }
+    }
+}
+exports.OpenAICompatibleSpeechToTextService = OpenAICompatibleSpeechToTextService;
+//# sourceMappingURL=OpenAICompatibleSpeechToText.service.js.map

package/dist/providers/OpenAICompatible/OpenAICompatibleSpeechToText.service.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"OpenAICompatibleSpeechToText.service.js","sourceRoot":"","sources":["../../../src/providers/OpenAICompatible/OpenAICompatibleSpeechToText.service.ts"],"names":[],"mappings":"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"}

package/dist/providers/OpenAICompatible/OpenAICompatibleTextToSpeech.service.d.ts

@@ -0,0 +1,22 @@
+import { OpenAI } from 'openai';
+import { type LLMProviders, type LLMCreateSpeechOptions, type LLMCreateSpeechResult, type LLMInstanceOptions, type LLMModel } from '../../LLMService.typedefs';
+import { type LLMLoggerInterface } from '../../utilities/logger';
+import { type LLMReporterInterface } from '../../utilities/reporter';
+import { LLMTextToSpeechService } from '../../services';
+type OpenAICompatibleTTSProvider = LLMProviders.OpenAI | LLMProviders.LLMAPI;
+interface SpeechUsage {
+    inputTextTokens: number;
+    outputAudioTokens: number;
+}
+export declare abstract class OpenAICompatibleTextToSpeechService<Provider extends OpenAICompatibleTTSProvider, Reporter extends LLMReporterInterface<any> | undefined> extends LLMTextToSpeechService<Provider, Reporter> {
+    constructor(provider: Provider, logger: LLMLoggerInterface | undefined, reporter: Reporter, options?: LLMInstanceOptions[Provider]);
+    get instance(): OpenAI;
+    protected getDefaultVoice(_modelName: string): string;
+    protected getRequestOptions(abortSignal?: AbortSignal): {
+        signal?: AbortSignal;
+        headers?: Record<string, string>;
+    };
+    protected abstract extractUsage(audioBuffer: Buffer, text: string, model: LLMModel<Provider>): Promise<SpeechUsage> | SpeechUsage;
+    createSpeech(options: LLMCreateSpeechOptions<typeof this.provider, Reporter>): Promise<LLMCreateSpeechResult>;
+}
+export {};

package/dist/providers/OpenAICompatible/OpenAICompatibleTextToSpeech.service.js

@@ -0,0 +1,67 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.OpenAICompatibleTextToSpeechService = void 0;
+const openai_1 = require("openai");
+const services_1 = require("../../services");
+class OpenAICompatibleTextToSpeechService extends services_1.LLMTextToSpeechService {
+    constructor(provider, logger, reporter, options) {
+        super(provider, logger, reporter, options);
+    }
+    get instance() {
+        return this.getOrCreateInstance(() => new openai_1.OpenAI(this.options));
+    }
+    getDefaultVoice(_modelName) {
+        return 'alloy';
+    }
+    getRequestOptions(abortSignal) {
+        return { signal: abortSignal };
+    }
+    async createSpeech(options) {
+        const { text, model, instructions, speechOptions, abortSignal, reporterContext, } = options;
+        const writeMetrics = this.reporter?.initWriter(reporterContext);
+        try {
+            abortSignal?.throwIfAborted();
+            const audioResponse = await this.instance.audio.speech.create({
+                model: model.name,
+                input: text,
+                instructions,
+                voice: speechOptions?.voice ?? this.getDefaultVoice(model.name),
+                response_format: speechOptions?.response_format,
+                speed: speechOptions?.speed,
+            }, this.getRequestOptions(abortSignal));
+            abortSignal?.throwIfAborted();
+            const audioArrayBuffer = await audioResponse.arrayBuffer();
+            const audioBuffer = Buffer.from(audioArrayBuffer);
+            abortSignal?.throwIfAborted();
+            const usage = await this.extractUsage(audioBuffer, text, model);
+            await this.writeSuccessMetrics({
+                method: this.getMethodName(this.createSpeech),
+                model,
+                usage,
+                writeMetrics,
+            });
+            return {
+                audio: audioBuffer,
+                mimeType: audioResponse.headers.get('Content-Type'),
+            };
+        }
+        catch (error) {
+            await this.writeErrorMetrics({
+                method: this.getMethodName(this.createSpeech),
+                model,
+                isAborted: abortSignal?.aborted,
+                writeMetrics,
+            });
+            this.logRequestFailure({
+                method: this.getMethodName(this.createSpeech),
+                message: 'Error creating speech',
+                error,
+                isAborted: abortSignal?.aborted,
+                meta: { options },
+            });
+            return { error };
+        }
+    }
+}
+exports.OpenAICompatibleTextToSpeechService = OpenAICompatibleTextToSpeechService;
+//# sourceMappingURL=OpenAICompatibleTextToSpeech.service.js.map

package/dist/providers/OpenAICompatible/OpenAICompatibleTextToSpeech.service.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"OpenAICompatibleTextToSpeech.service.js","sourceRoot":"","sources":["../../../src/providers/OpenAICompatible/OpenAICompatibleTextToSpeech.service.ts"],"names":[],"mappings":";;;AAAA,mCAAgC;AAUhC,yCAAoD;AASpD,MAAsB,mCAGpB,SAAQ,iCAA0C;IAClD,YACE,QAAkB,EAClB,MAAsC,EACtC,QAAkB,EAClB,OAAsC;QAEtC,KAAK,CAAC,QAAQ,EAAE,MAAM,EAAE,QAAQ,EAAE,OAAO,CAAC,CAAC;IAC7C,CAAC;IAED,IAAI,QAAQ;QACV,OAAO,IAAI,CAAC,mBAAmB,CAC7B,GAAG,EAAE,CAAC,IAAI,eAAM,CAAC,IAAI,CAAC,OAAO,CAAsB,CACpD,CAAC;IACJ,CAAC;IAES,eAAe,CAAC,UAAkB;QAC1C,OAAO,OAAO,CAAC;IACjB,CAAC;IAES,iBAAiB,CAAC,WAAyB;QACnD,OAAO,EAAE,MAAM,EAAE,WAAW,EAAE,CAAC;IACjC,CAAC;IAQD,KAAK,CAAC,YAAY,CAChB,OAA+D;QAE/D,MAAM,EACJ,IAAI,EACJ,KAAK,EACL,YAAY,EACZ,aAAa,EACb,WAAW,EACX,eAAe,GAChB,GAAG,OAAO,CAAC;QAEZ,MAAM,YAAY,GAAG,IAAI,CAAC,QAAQ,EAAE,UAAU,CAAC,eAAe,CAAC,CAAC;QAEhE,IAAI,CAAC;YACH,WAAW,EAAE,cAAc,EAAE,CAAC;YAE9B,MAAM,aAAa,GAAG,MAAM,IAAI,CAAC,QAAQ,CAAC,KAAK,CAAC,MAAM,CAAC,MAAM,CAAC;gBAC5D,KAAK,EAAE,KAAK,CAAC,IAAI;gBACjB,KAAK,EAAE,IAAI;gBACX,YAAY;gBACZ,KAAK,EAAE,aAAa,EAAE,KAAK,IAAI,IAAI,CAAC,eAAe,CAAC,KAAK,CAAC,IAAI,CAAC;gBAC/D,eAAe,EAAE,aAAa,EAAE,eAAsB;gBACtD,KAAK,EAAE,aAAa,EAAE,KAAK;aAC5B,EAAE,IAAI,CAAC,iBAAiB,CAAC,WAAW,CAAC,CAAC,CAAC;YAExC,WAAW,EAAE,cAAc,EAAE,CAAC;YAE9B,MAAM,gBAAgB,GAAG,MAAM,aAAa,CAAC,WAAW,EAAE,CAAC;YAC3D,MAAM,WAAW,GAAG,MAAM,CAAC,IAAI,CAAC,gBAAgB,CAAC,CAAC;YAElD,WAAW,EAAE,cAAc,EAAE,CAAC;YAE9B,MAAM,KAAK,GAAG,MAAM,IAAI,CAAC,YAAY,CAAC,WAAW,EAAE,IAAI,EAAE,KAAK,CAAC,CAAC;YAEhE,MAAM,IAAI,CAAC,mBAAmB,CAAC;gBAC7B,MAAM,EAAE,IAAI,CAAC,aAAa,CAAC,IAAI,CAAC,YAAY,CAAC;gBAC7C,KAAK;gBACL,KAAK;gBACL,YAAY;aACb,CAAC,CAAC;YAEH,OAAO;gBACL,KAAK,EAAE,WAAW;gBAClB,QAAQ,EAAE,aAAa,CAAC,OAAO,CAAC,GAAG,CAAC,cAAc,CAAC;aACpD,CAAC;QACJ,CAAC;QAAC,OAAO,KAAU,EAAE,CAAC;YACpB,MAAM,IAAI,CAAC,iBAAiB,CAAC;gBAC3B,MAAM,EAAE,IAAI,CAAC,aAAa,CAAC,IAAI,CAAC,YAAY,CAAC;gBAC7C,KAAK;gBACL,SAAS,EAAE,WAAW,EAAE,OAAO;gBAC/B,YAAY;aACb,CAAC,CAAC;YAEH,IAAI,CAAC,iBAAiB,CAAC;gBACrB,MAAM,EAAE,IAAI,CAAC,aAAa,CAAC,IAAI,CAAC,YAAY,CAAC;gBAC7C,OAAO,EAAE,uBAAuB;gBAChC,KAAK;gBACL,SAAS,EAAE,WAAW,EAAE,OAAO;gBAC/B,IAAI,EAAE,EAAE,OAAO,EAAE;aAClB,CAAC,CAAC;YAEH,OAAO,EAAE,KAAK,EAAE,CAAC;QACnB,CAAC;IACH,CAAC;CACF;AAlGD,kFAkGC"}

package/dist/providers/index.d.ts

@@ -0,0 +1,3 @@
+export * from './OpenAI';
+export * from './GoogleGenerativeAI';
+export * from './LLMAPI';

package/dist/providers/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("./OpenAI"), exports);
+__exportStar(require("./GoogleGenerativeAI"), exports);
+__exportStar(require("./LLMAPI"), exports);
+//# sourceMappingURL=index.js.map

package/dist/providers/index.js.map

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

package/dist/services/LLMAssistanceService.abstract.d.ts

@@ -0,0 +1,39 @@
+import { type LLMAssistInNewChatOptions, type LLMAssistanceOptions, type LLMAssistanceResult, type LLMAssistanceMessage, type LLMToolDefinition, type LLMCreateChatOptions, type LLMCreateChatResult, type LLMCreateFileStorageOptions, type LLMCreateFileStorageResult, type LLMInstanceOptions, type LLMModel, type LLMProviders, LLMPurposes, type LLMUploadFileOptions, type LLMUploadFileResult, type LLMStructuredResult, type LLMUploadedFile, type LLMTerminalToolOutcome, LLMToolLoopStopReasons } from '../LLMService.typedefs';
+import { type LLMLoggerInterface } from '../utilities/logger';
+import { type LLMReporterInterface } from '../utilities/reporter';
+import { LLMBaseService } from '../services';
+import { type LLMSchemaInterface, type InferSchema } from '../utilities/schema';
+export declare abstract class LLMAssistanceService<Provider extends LLMProviders, Reporter extends LLMReporterInterface<any> | undefined> extends LLMBaseService<LLMPurposes.Assistance, Provider, Reporter> {
+    constructor(provider: Provider, logger: LLMLoggerInterface | undefined, reporter: Reporter, options?: LLMInstanceOptions[Provider]);
+    /**
+     * Classifies why a tool loop stopped. A terminal tool outranks exhaustion:
+     * the loop broke on purpose before the iteration budget mattered.
+     */
+    protected resolveToolLoopStopReason(params: {
+        terminalTool: LLMTerminalToolOutcome | undefined;
+        toolIterationsExhausted: boolean;
+    }): LLMToolLoopStopReasons;
+    protected validateToolDefinitions(tools: LLMToolDefinition[]): void;
+    abstract uploadFile(options: LLMUploadFileOptions<Reporter>): Promise<LLMUploadFileResult>;
+    abstract getFile(path: string): Promise<LLMUploadedFile | null>;
+    abstract deleteFile(fileId: string): Promise<void>;
+    abstract createFileStorage(options: LLMCreateFileStorageOptions<Provider, Reporter>): Promise<LLMCreateFileStorageResult>;
+    abstract deleteFileStorage(fileStorageId: string): Promise<void>;
+    abstract createChat(options: LLMCreateChatOptions<Provider, Reporter>): Promise<LLMCreateChatResult>;
+    abstract deleteChat(chatId: string): Promise<void>;
+    assistInChat<Schema extends LLMSchemaInterface>(options: LLMAssistanceOptions<Provider, Reporter> & {
+        schema: Schema;
+    }): Promise<LLMStructuredResult<InferSchema<Schema>>>;
+    assistInChat(options: LLMAssistanceOptions<Provider, Reporter>): Promise<LLMAssistanceResult>;
+    private runAgentObservation;
+    private getAssistanceFailure;
+    protected abstract assistInChatText(options: LLMAssistanceOptions<Provider, Reporter>): Promise<LLMAssistanceResult>;
+    protected abstract assistInChatStructured(options: LLMAssistanceOptions<Provider, Reporter> & {
+        schema: LLMSchemaInterface;
+    }): Promise<LLMStructuredResult>;
+    assistInNewChat<Schema extends LLMSchemaInterface>(options: LLMAssistInNewChatOptions<Provider, Reporter> & {
+        schema: Schema;
+    }): Promise<LLMStructuredResult<InferSchema<Schema>>>;
+    assistInNewChat(options: LLMAssistInNewChatOptions<Provider, Reporter>): Promise<LLMAssistanceResult>;
+    abstract countTokens(messages: LLMAssistanceMessage[], model: LLMModel<Provider>): Promise<number>;
+}

package/dist/services/LLMAssistanceService.abstract.js

@@ -0,0 +1,101 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.LLMAssistanceService = void 0;
+const LLMService_typedefs_1 = require("../LLMService.typedefs");
+const services_1 = require("../services");
+class LLMAssistanceFailureError extends Error {
+    assistanceResult;
+    constructor(message, assistanceResult) {
+        super(message);
+        this.assistanceResult = assistanceResult;
+        this.name = LLMAssistanceFailureError.name;
+    }
+}
+class LLMAssistanceService extends services_1.LLMBaseService {
+    constructor(provider, logger, reporter, options) {
+        super(provider, 'AssistanceService', LLMService_typedefs_1.LLMPurposes.Assistance, logger, reporter, options);
+    }
+    /**
+     * Classifies why a tool loop stopped. A terminal tool outranks exhaustion:
+     * the loop broke on purpose before the iteration budget mattered.
+     */
+    resolveToolLoopStopReason(params) {
+        if (params.terminalTool) {
+            return LLMService_typedefs_1.LLMToolLoopStopReasons.TerminalTool;
+        }
+        if (params.toolIterationsExhausted) {
+            return LLMService_typedefs_1.LLMToolLoopStopReasons.MaxIterations;
+        }
+        return LLMService_typedefs_1.LLMToolLoopStopReasons.Completed;
+    }
+    validateToolDefinitions(tools) {
+        const namePattern = /^[a-zA-Z0-9_-]+$/;
+        const names = new Set();
+        for (const tool of tools) {
+            if (!namePattern.test(tool.name)) {
+                throw new Error(`Invalid tool name "${tool.name}":`
+                    + ' must match [a-zA-Z0-9_-]+');
+            }
+            if (names.has(tool.name)) {
+                throw new Error(`Duplicate tool name "${tool.name}"`);
+            }
+            names.add(tool.name);
+        }
+    }
+    assistInChat(options) {
+        if (options.schema) {
+            return this.runAgentObservation(options, () => this.assistInChatStructured(options));
+        }
+        return this.runAgentObservation(options, () => this.assistInChatText(options));
+    }
+    async runAgentObservation(options, operation) {
+        if (!options.agentName) {
+            return operation();
+        }
+        try {
+            return await this.getTracer().withAgentObservation(options.agentName, options.message, async () => {
+                const assistanceResult = await operation();
+                const failureMessage = this.getAssistanceFailure(assistanceResult);
+                if (failureMessage !== undefined) {
+                    throw new LLMAssistanceFailureError(failureMessage, assistanceResult);
+                }
+                return assistanceResult;
+            });
+        }
+        catch (error) {
+            if (error instanceof LLMAssistanceFailureError) {
+                return error.assistanceResult;
+            }
+            throw error;
+        }
+    }
+    getAssistanceFailure(assistanceResult) {
+        if ('error' in assistanceResult) {
+            return assistanceResult.error.message;
+        }
+        return 'parseError' in assistanceResult
+            ? assistanceResult.parseError || undefined
+            : undefined;
+    }
+    async assistInNewChat(options) {
+        const chatResult = await this.createChat(options);
+        if ('error' in chatResult) {
+            return chatResult;
+        }
+        const message = {
+            role: LLMService_typedefs_1.LLMRoles.User,
+            content: [{
+                    type: LLMService_typedefs_1.LLMMessageContentType.TEXT,
+                    text: options.prompt,
+                }],
+        };
+        // @ts-expect-error conditional Reporter type prevents direct assignment
+        return this.assistInChat({
+            ...options,
+            chatId: chatResult.chatId,
+            message,
+        });
+    }
+}
+exports.LLMAssistanceService = LLMAssistanceService;
+//# sourceMappingURL=LLMAssistanceService.abstract.js.map

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

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

package/dist/services/LLMBaseService.abstract.d.ts

@@ -0,0 +1,161 @@
+import { type LLMCallTraceContext, type LLMInstanceOptions, type LLMInstances, type LLMProviders, type LLMPurposes, type LLMProviderModelsByPurpose } from '../LLMService.typedefs';
+import { type LLMLoggerInterface } from '../utilities/logger';
+import { type LLMReporterInterface, type LLMMetricsWriter } from '../utilities/reporter';
+import { type LLMModel } from '../LLMService.typedefs';
+import { type LLMGatewayTracer, type LLMGenerationTrace, type LLMModelUsage } from '../utilities';
+import { LLMAgentRounds } from './agentRounds';
+export declare abstract class LLMBaseService<Purpose extends LLMPurposes, Provider extends LLMProviders, Reporter extends LLMReporterInterface<any> | undefined> {
+    readonly provider: Provider;
+    readonly serviceName: string;
+    readonly purpose: Purpose;
+    logger: LLMLoggerInterface | undefined;
+    reporter: Reporter;
+    options?: LLMInstanceOptions[Provider] | undefined;
+    private static readonly sharedInstanceCache;
+    private tracer;
+    constructor(provider: Provider, serviceName: string, purpose: Purpose, logger: LLMLoggerInterface | undefined, reporter: Reporter, options?: LLMInstanceOptions[Provider] | undefined);
+    /**
+     * Wires the tracer the service reports generations and tool calls to. Called
+     * by `LLMGateway` right after construction; services built through
+     * `LLMServiceFactory` keep the no-op tracer.
+     */
+    initTracer(tracer: LLMGatewayTracer): void;
+    protected getTracer(): LLMGatewayTracer;
+    /**
+     * The LLM instance for the current provider.
+     */
+    abstract get instance(): LLMInstances[Provider];
+    /**
+     * Available models for the current provider and purpose.
+     */
+    get models(): LLMProviderModelsByPurpose<Purpose, Provider>[Purpose];
+    /**
+     * Initialize the logger by creating a child logger with the provider and service name.
+     */
+    protected initLogger(): void;
+    /**
+     * Inject method names into class methods for better logging and reporting.
+     */
+    private injectMethodNames;
+    /**
+     * Get the method name from a function.
+     * If the method name is not available, return 'unknown'.
+     */
+    protected getMethodName(func: Function & {
+        methodName?: string;
+    }): string;
+    /**
+     * Generate a cache key from credentials/options.
+     * Includes provider to ensure cache isolation between different providers.
+     * Note: Different purposes (Completion, Assistance, etc.) for the same provider
+     * share the same underlying client instance.
+     */
+    protected getCredentialsCacheKey(options: LLMInstanceOptions[Provider] | undefined): string;
+    /**
+     * Get or create cached instance for current credentials.
+     * This method implements LRU caching to bound memory usage across all service types.
+     * @throws {Error} If options are not provided (required for instance creation)
+     */
+    protected getOrCreateInstance(factory: () => LLMInstances[Provider]): LLMInstances[Provider];
+    /**
+     * Evict least recently used instance from the shared cache.
+     */
+    private evictLeastRecentlyUsed;
+    /**
+     * Set new options for the LLM service instance.
+     * The instance will be lazily recreated with new credentials on next access.
+     */
+    setOptions(options: LLMInstanceOptions[Provider]): void;
+    /**
+     * Get the current options for the LLM service instance.
+     */
+    getOptions(): LLMInstanceOptions[Provider] | undefined;
+    /**
+     * Clear all cached instances from the shared cache.
+     * Useful for testing and manual resource cleanup.
+     */
+    clearInstanceCache(): void;
+    protected getDefaultTraceName(method: string): string;
+    /**
+     * Builds the per-call generation trace from the standard method options.
+     * Returns `undefined` when tracing is disabled, so providers skip the work.
+     */
+    protected buildGenerationTrace(params: {
+        method: string;
+        traceContext?: LLMCallTraceContext;
+        input: unknown;
+        output?: unknown;
+        modelParameters?: Record<string, unknown>;
+        startedAt: number;
+    }): LLMGenerationTrace | undefined;
+    /**
+     * 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.
+     */
+    protected openAgentRounds(params: {
+        method: string;
+        model: LLMModel<Provider> | null;
+        traceContext?: LLMCallTraceContext;
+        modelParameters?: Record<string, unknown>;
+    }): LLMAgentRounds;
+    /**
+     * 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.
+     */
+    protected buildUnstartedRunTrace(params: {
+        rounds: LLMAgentRounds;
+        method: string;
+        traceContext?: LLMCallTraceContext;
+        input: unknown;
+        modelParameters?: Record<string, unknown>;
+        startedAt: number;
+    }): LLMGenerationTrace | undefined;
+    /**
+     * Write success metrics for a specific method, and emit the matching
+     * generation observation when per-call trace context is provided.
+     */
+    protected writeSuccessMetrics<TModel extends LLMModel<Provider>>(params: {
+        method: string;
+        model: TModel | null;
+        usage: LLMModelUsage;
+        writeMetrics: LLMMetricsWriter | undefined;
+        generationTrace?: LLMGenerationTrace;
+    }): Promise<void>;
+    /**
+     * Token totals and costs of one accounted call, in the shape both the metrics
+     * writer and a generation observation take.
+     */
+    private buildGenerationAccounting;
+    /**
+     * Write error metrics for a specific method, and emit the matching generation
+     * observation (level ERROR) when per-call trace context is given.
+     */
+    protected writeErrorMetrics<TModel extends LLMModel<Provider>>(params: {
+        method: string;
+        model: TModel | null;
+        isAborted?: boolean;
+        writeMetrics: LLMMetricsWriter | undefined;
+        generationTrace?: LLMGenerationTrace;
+        error?: unknown;
+    }): Promise<void>;
+    /**
+     * Log a request failure at a severity matching whether it was an
+     * intentional cancellation (isAborted) or a genuine provider/network error.
+     * An aborted request is expected behaviour, not an operational failure, so
+     * it is logged as a warning rather than an error.
+     */
+    protected logRequestFailure(params: {
+        method: string;
+        message: string;
+        error: unknown;
+        isAborted?: boolean;
+        meta?: Record<string, unknown>;
+    }): void;
+    private recordGenerationTrace;
+    private describeError;
+}