@mate-academy/llm-gateway 8.8.2 → 8.8.3

package/dist/providers/OpenAI/services/OpenAIAssistance.service.js

@@ -0,0 +1,712 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.OpenAIAssistanceService = void 0;
+const fs_1 = require("fs");
+const openai_1 = require("openai");
+const LLMService_typedefs_1 = require("../../../LLMService.typedefs");
+const LLMService_constants_1 = require("../../../LLMService.constants");
+const serializeError_1 = require("../../../utilities/serializeError");
+const services_1 = require("../../../services");
+const buildFunctionCallOutput_1 = require("./buildFunctionCallOutput");
+const OpenAI_typedefs_1 = require("../../../providers/OpenAI/OpenAI.typedefs");
+const OpenAI_entity_1 = require("../../../providers/OpenAI/OpenAI.entity");
+const uuid_1 = require("uuid");
+class OpenAIAssistanceService extends services_1.LLMAssistanceService {
+    uploadedFiles = new Map();
+    responseHistory = new Map();
+    chatInstructions = new Map();
+    constructor(logger, reporter, options) {
+        super(LLMService_typedefs_1.LLMProviders.OpenAI, logger, reporter, options);
+    }
+    get instance() {
+        return this.getOrCreateInstance(() => new openai_1.OpenAI(this.options));
+    }
+    async uploadFile(fileOptions) {
+        const { path, name, mimeType, abortSignal, reporterContext, } = fileOptions;
+        const writeMetrics = this.reporter?.initWriter(reporterContext);
+        try {
+            abortSignal?.throwIfAborted();
+            const existingFile = await this.getFile(path);
+            if (existingFile) {
+                this.writeSuccessMetrics({
+                    method: this.getMethodName(this.uploadFile),
+                    model: null,
+                    usage: {},
+                    writeMetrics,
+                });
+                return existingFile;
+            }
+            const readableStream = (0, fs_1.createReadStream)(path, { signal: abortSignal });
+            abortSignal?.throwIfAborted();
+            const uploadedFile = await this.instance.files.create({
+                purpose: 'assistants',
+                file: readableStream,
+            }, {
+                signal: abortSignal,
+            });
+            abortSignal?.throwIfAborted();
+            await this.instance.files.waitForProcessing(uploadedFile.id);
+            abortSignal?.throwIfAborted();
+            const uploadedFileInfo = {
+                name,
+                path,
+                mimeType,
+                fileId: uploadedFile.id,
+            };
+            this.uploadedFiles.set(path, uploadedFileInfo);
+            await this.writeSuccessMetrics({
+                method: this.getMethodName(this.uploadFile),
+                model: null,
+                usage: {},
+                writeMetrics,
+            });
+            return uploadedFileInfo;
+        }
+        catch (error) {
+            await this.writeErrorMetrics({
+                method: this.getMethodName(this.uploadFile),
+                model: null,
+                isAborted: abortSignal?.aborted,
+                writeMetrics,
+            });
+            this.logRequestFailure({
+                method: this.getMethodName(this.uploadFile),
+                message: 'Error uploading file',
+                error,
+                isAborted: abortSignal?.aborted,
+                meta: { file: fileOptions },
+            });
+            return { error };
+        }
+    }
+    async getFile(path) {
+        return this.uploadedFiles.get(path) || null;
+    }
+    async deleteFile(fileId) {
+        await this.instance.files.delete(fileId);
+        this.uploadedFiles.delete(fileId);
+    }
+    async createFileStorage(options) {
+        const { uploadedFiles, abortSignal, reporterContext, } = options;
+        const writeMetrics = this.reporter?.initWriter(reporterContext);
+        try {
+            const vectorStore = await this.instance.vectorStores.create({
+                expires_after: {
+                    anchor: 'last_active_at',
+                    days: 1,
+                },
+            }, {
+                signal: abortSignal,
+            });
+            abortSignal?.throwIfAborted();
+            if (uploadedFiles.length > 0) {
+                await this.instance.vectorStores.fileBatches
+                    .createAndPoll(vectorStore.id, { file_ids: uploadedFiles.map(({ fileId }) => fileId) }, { signal: abortSignal });
+                abortSignal?.throwIfAborted();
+            }
+            await this.writeSuccessMetrics({
+                method: this.getMethodName(this.createFileStorage),
+                model: null,
+                usage: {},
+                writeMetrics,
+            });
+            return {
+                storageId: vectorStore.id,
+            };
+        }
+        catch (error) {
+            await this.writeErrorMetrics({
+                method: this.getMethodName(this.createFileStorage),
+                model: null,
+                isAborted: abortSignal?.aborted,
+                writeMetrics,
+            });
+            this.logRequestFailure({
+                method: this.getMethodName(this.createFileStorage),
+                message: 'Error creating file storage',
+                error,
+                isAborted: abortSignal?.aborted,
+                meta: { uploadedFiles },
+            });
+            return { error };
+        }
+    }
+    async deleteFileStorage(fileStorageId) {
+        await this.instance.vectorStores.delete(fileStorageId);
+    }
+    async createChat(options) {
+        const { storageId, model, instructions, history = [], abortSignal, reporterContext, } = options;
+        const writeMetrics = this.reporter?.initWriter(reporterContext);
+        try {
+            abortSignal?.throwIfAborted();
+            const chatId = (0, uuid_1.v4)();
+            if (instructions) {
+                this.chatInstructions.set(chatId, instructions);
+            }
+            let inputTextTokens;
+            let inputCachedTextTokens;
+            let outputTextTokens;
+            if (history.length > 0) {
+                const initialInput = history
+                    .map((msg) => this.convertLLMMessageToResponsesInput(msg))
+                    .flat();
+                const tools = [];
+                if (storageId) {
+                    tools.push({
+                        type: 'file_search',
+                        vector_store_ids: [storageId],
+                    });
+                }
+                const response = await this.instance.responses.create({
+                    model: model.name,
+                    input: initialInput,
+                    tools: tools.length > 0
+                        ? tools
+                        : undefined,
+                    instructions,
+                }, {
+                    signal: abortSignal,
+                });
+                this.responseHistory.set(chatId, response.id);
+                const totalInputTokens = response.usage?.input_tokens ?? 0;
+                const cachedInputTokens = response.usage?.input_tokens_details?.cached_tokens ?? 0;
+                const totalOutputTokens = response.usage?.output_tokens ?? 0;
+                const reasoningOutputTokens = response.usage?.output_tokens_details?.reasoning_tokens ?? 0;
+                inputTextTokens = totalInputTokens - cachedInputTokens;
+                inputCachedTextTokens = cachedInputTokens;
+                outputTextTokens = totalOutputTokens + reasoningOutputTokens;
+            }
+            await this.writeSuccessMetrics({
+                method: this.getMethodName(this.createChat),
+                model,
+                usage: {
+                    inputTextTokens,
+                    inputCachedTextTokens,
+                    outputTextTokens,
+                },
+                writeMetrics,
+            });
+            return { chatId };
+        }
+        catch (error) {
+            await this.writeErrorMetrics({
+                method: this.getMethodName(this.createChat),
+                model,
+                isAborted: abortSignal?.aborted,
+                writeMetrics,
+            });
+            this.logRequestFailure({
+                method: this.getMethodName(this.createChat),
+                message: 'Error creating chat',
+                error,
+                isAborted: abortSignal?.aborted,
+                meta: { options },
+            });
+            return { error };
+        }
+    }
+    async deleteChat(chatId) {
+        this.responseHistory.delete(chatId);
+        this.chatInstructions.delete(chatId);
+    }
+    prepareAssistTools(options) {
+        const { message, storageId } = options;
+        const customTools = options.tools ?? [];
+        const messageInput = this.convertLLMMessageToResponsesInput(message);
+        let tools = [];
+        if (customTools.length > 0) {
+            this.validateToolDefinitions(customTools);
+            tools = this.convertCustomToolsToResponsesAPI(customTools);
+        }
+        if (storageId) {
+            tools.push({
+                type: 'file_search',
+                vector_store_ids: [storageId],
+            });
+        }
+        return { messageInput, tools };
+    }
+    extractUsageFromResponse(response) {
+        return {
+            inputTokens: response.usage?.input_tokens ?? 0,
+            cachedInputTokens: response.usage
+                ?.input_tokens_details
+                ?.cached_tokens ?? 0,
+            outputTokens: response.usage?.output_tokens ?? 0,
+            reasoningTokens: response.usage
+                ?.output_tokens_details
+                ?.reasoning_tokens ?? 0,
+        };
+    }
+    buildUsageMetrics(usage) {
+        return {
+            inputTextTokens: usage.inputTokens - usage.cachedInputTokens,
+            inputCachedTextTokens: usage.cachedInputTokens,
+            outputTextTokens: usage.outputTokens + usage.reasoningTokens,
+        };
+    }
+    buildRoundOutcome = (response) => ({
+        output: response.output,
+        usage: this.buildUsageMetrics(this.extractUsageFromResponse(response)),
+    });
+    /**
+     * The transcript a traced round of this turn shows. The Responses API keeps
+     * earlier turns of the chat server-side and refers to them by
+     * `previous_response_id`, so what a round can honestly show is what this call
+     * put on the wire: the chat's instructions, this turn's input items, and
+     * everything the tool loop appends to them afterwards.
+     */
+    startTracedConversation(params) {
+        const instructions = this.chatInstructions.get(params.chatId);
+        return [
+            ...(instructions
+                ? [{
+                        role: OpenAI_typedefs_1.OpenAIRoles.Developer,
+                        content: instructions,
+                    }]
+                : []),
+            ...params.messageInput,
+        ];
+    }
+    async assistInChatText(options) {
+        const { model, chatId, abortSignal, reporterContext, traceContext, } = options;
+        const writeMetrics = this.reporter?.initWriter(reporterContext);
+        const method = this.getMethodName(this.assistInChatText);
+        const generationStartedAt = Date.now();
+        const rounds = this.openAgentRounds({
+            method,
+            model,
+            traceContext,
+            modelParameters: model.config,
+        });
+        try {
+            abortSignal?.throwIfAborted();
+            const lastResponseId = this.responseHistory.get(chatId);
+            const { messageInput, tools } = this.prepareAssistTools(options);
+            const customTools = options.tools ?? [];
+            const conversation = this.startTracedConversation({
+                chatId,
+                messageInput,
+            });
+            const initialResponse = await rounds.run({
+                input: [...conversation],
+                call: () => this.instance.responses.create({
+                    model: model.name,
+                    input: messageInput,
+                    previous_response_id: lastResponseId,
+                    tools: tools.length > 0
+                        ? tools
+                        : undefined,
+                    instructions: this.chatInstructions.get(chatId),
+                }, { signal: abortSignal }),
+                describeOutcome: this.buildRoundOutcome,
+            });
+            this.responseHistory.set(chatId, initialResponse.id);
+            const maxIterations = options.maxToolIterations
+                ?? LLMService_constants_1.DEFAULT_MAX_TOOL_ITERATIONS;
+            const toolLoopResult = await this.executeToolLoop({
+                response: initialResponse,
+                tools: customTools,
+                model,
+                chatId,
+                maxIterations,
+                abortSignal,
+                allTools: tools,
+                rounds,
+                conversation,
+                onAssistantNarration: options.onAssistantNarration,
+            });
+            const { response: finalResponse, totalUsage } = toolLoopResult;
+            const text = finalResponse.output_text || '';
+            await this.writeSuccessMetrics({
+                method,
+                model,
+                usage: this.buildUsageMetrics(totalUsage),
+                writeMetrics,
+            });
+            return {
+                text,
+                toolIterationsUsed: toolLoopResult.toolIterationsUsed,
+                ...(toolLoopResult.toolIterationsExhausted && {
+                    toolIterationsExhausted: true,
+                }),
+                stopReason: toolLoopResult.stopReason,
+                ...(toolLoopResult.terminalTool && {
+                    terminalTool: toolLoopResult.terminalTool,
+                }),
+            };
+        }
+        catch (error) {
+            await this.writeErrorMetrics({
+                method,
+                model,
+                isAborted: abortSignal?.aborted,
+                writeMetrics,
+                error,
+                generationTrace: this.buildUnstartedRunTrace({
+                    rounds,
+                    method,
+                    traceContext,
+                    input: options.message,
+                    modelParameters: model.config,
+                    startedAt: generationStartedAt,
+                }),
+            });
+            this.logRequestFailure({
+                method,
+                message: 'Error assisting in chat with Responses API',
+                error,
+                isAborted: abortSignal?.aborted,
+                meta: { options },
+            });
+            return {
+                error: error instanceof Error
+                    ? error
+                    : new Error(String(error)),
+            };
+        }
+    }
+    async assistInChatStructured(options) {
+        const { model, chatId, abortSignal, schema, reporterContext, traceContext, } = options;
+        const writeMetrics = this.reporter?.initWriter(reporterContext);
+        const method = this.getMethodName(this.assistInChatStructured);
+        const generationStartedAt = Date.now();
+        const rounds = this.openAgentRounds({
+            method,
+            model,
+            traceContext,
+            modelParameters: model.config,
+        });
+        try {
+            abortSignal?.throwIfAborted();
+            const lastResponseId = this.responseHistory.get(chatId);
+            const { messageInput, tools } = this.prepareAssistTools(options);
+            const customTools = options.tools ?? [];
+            const jsonSchema = schema._toProviderSchema(LLMService_typedefs_1.LLMProviders.OpenAI);
+            const textFormat = {
+                format: {
+                    type: 'json_schema',
+                    name: 'structured_response',
+                    strict: true,
+                    schema: jsonSchema,
+                },
+            };
+            const conversation = this.startTracedConversation({
+                chatId,
+                messageInput,
+            });
+            const initialResponse = await rounds.run({
+                input: [...conversation],
+                call: () => this.instance.responses.create({
+                    model: model.name,
+                    input: messageInput,
+                    previous_response_id: lastResponseId,
+                    tools: tools.length > 0
+                        ? tools
+                        : undefined,
+                    instructions: this.chatInstructions.get(chatId),
+                    text: textFormat,
+                }, { signal: abortSignal }),
+                describeOutcome: this.buildRoundOutcome,
+            });
+            this.responseHistory.set(chatId, initialResponse.id);
+            const maxIterations = options.maxToolIterations
+                ?? LLMService_constants_1.DEFAULT_MAX_TOOL_ITERATIONS;
+            const toolLoopResult = await this.executeToolLoop({
+                response: initialResponse,
+                tools: customTools,
+                model,
+                chatId,
+                maxIterations,
+                abortSignal,
+                allTools: tools,
+                rounds,
+                conversation,
+                textFormat,
+                onAssistantNarration: options.onAssistantNarration,
+            });
+            const { response: finalResponse, totalUsage, } = toolLoopResult;
+            const content = finalResponse.output_text || '';
+            if (toolLoopResult.terminalTool) {
+                await this.writeSuccessMetrics({
+                    method: this.getMethodName(this.assistInChatStructured),
+                    model,
+                    usage: this.buildUsageMetrics(totalUsage),
+                    writeMetrics,
+                });
+                return {
+                    text: content,
+                    toolIterationsUsed: toolLoopResult.toolIterationsUsed,
+                    stopReason: toolLoopResult.stopReason,
+                    terminalTool: toolLoopResult.terminalTool,
+                };
+            }
+            if (!content) {
+                throw new Error('Empty response from OpenAI Responses API');
+            }
+            try {
+                const parsed = JSON.parse(content);
+                const validation = schema._parse(parsed);
+                await this.writeSuccessMetrics({
+                    method,
+                    model,
+                    usage: this.buildUsageMetrics(totalUsage),
+                    writeMetrics,
+                });
+                return {
+                    text: content,
+                    data: validation.data,
+                    parseError: validation.error,
+                    toolIterationsUsed: toolLoopResult.toolIterationsUsed,
+                    ...(toolLoopResult.toolIterationsExhausted && {
+                        toolIterationsExhausted: true,
+                    }),
+                    stopReason: toolLoopResult.stopReason,
+                };
+            }
+            catch (parseError) {
+                const parseErrorMessage = parseError instanceof Error
+                    ? parseError.message
+                    : String(parseError);
+                this.logger
+                    ?.child(this.getMethodName(this.assistInChatStructured))
+                    .warn('Failed to parse JSON response', {
+                    content,
+                    parseError: parseErrorMessage,
+                });
+                throw parseError;
+            }
+        }
+        catch (error) {
+            await this.writeErrorMetrics({
+                method,
+                model,
+                isAborted: abortSignal?.aborted,
+                writeMetrics,
+                error,
+                generationTrace: this.buildUnstartedRunTrace({
+                    rounds,
+                    method,
+                    traceContext,
+                    input: options.message,
+                    modelParameters: model.config,
+                    startedAt: generationStartedAt,
+                }),
+            });
+            this.logRequestFailure({
+                method,
+                message: 'Error assisting in chat with structured'
+                    + ' output using Responses API',
+                error,
+                isAborted: abortSignal?.aborted,
+                meta: { options },
+            });
+            return {
+                text: '',
+                error: error instanceof Error
+                    ? error
+                    : new Error(String(error)),
+                parseError: 'Failed to get structured response'
+                    + ' from OpenAI Responses API',
+            };
+        }
+    }
+    convertCustomToolsToResponsesAPI(tools) {
+        return tools.map((tool) => ({
+            type: 'function',
+            name: tool.name,
+            description: tool.description,
+            parameters: tool.parameters._toProviderSchema(LLMService_typedefs_1.LLMProviders.OpenAI),
+            strict: true,
+        }));
+    }
+    async executeFunctionCall(call, toolDefinitions) {
+        const matchingTool = toolDefinitions.find((tool) => tool.name === call.name);
+        if (!matchingTool) {
+            const unknownToolMessage = `Unknown tool: '${call.name}'`;
+            return {
+                outputItem: {
+                    type: 'function_call_output',
+                    call_id: call.call_id,
+                    output: unknownToolMessage,
+                },
+                toolName: call.name,
+                output: unknownToolMessage,
+                isTerminal: false,
+            };
+        }
+        const isTerminal = matchingTool.terminal === true;
+        try {
+            const parsedArguments = JSON.parse(call.arguments);
+            const result = await this.getTracer().withToolObservation(`${this.serviceName}/tool:${call.name}`, parsedArguments, () => Promise.resolve(matchingTool.execute(parsedArguments)));
+            return {
+                outputItem: {
+                    type: 'function_call_output',
+                    call_id: call.call_id,
+                    output: (0, buildFunctionCallOutput_1.buildFunctionCallOutput)(result),
+                },
+                toolName: call.name,
+                output: result,
+                isTerminal,
+            };
+        }
+        catch (error) {
+            const errorMessage = error instanceof Error
+                ? error.message
+                : String(error);
+            this.logger
+                ?.child(this.getMethodName(this.executeFunctionCall))
+                .error('Tool execution failed', {
+                toolName: call.name,
+                error: (0, serializeError_1.serializeError)(error),
+            });
+            const failureMessage = `Error executing tool '${call.name}':`
+                + ` ${errorMessage}`;
+            return {
+                outputItem: {
+                    type: 'function_call_output',
+                    call_id: call.call_id,
+                    output: failureMessage,
+                },
+                toolName: call.name,
+                output: failureMessage,
+                isTerminal,
+            };
+        }
+    }
+    async executeToolLoop(parameters) {
+        const { tools, model, chatId, maxIterations, abortSignal, allTools, rounds, conversation, textFormat, onAssistantNarration, } = parameters;
+        const tracedConversation = [...conversation];
+        let currentResponse = parameters.response;
+        const totalUsage = this.extractUsageFromResponse(currentResponse);
+        let toolIterationsUsed = 1;
+        let terminalTool;
+        for (let iteration = 0; iteration < maxIterations; iteration++) {
+            abortSignal?.throwIfAborted();
+            const functionCalls = this.getFunctionCallsFromResponse(currentResponse);
+            if (functionCalls.length === 0) {
+                break;
+            }
+            if (onAssistantNarration) {
+                onAssistantNarration(currentResponse.output_text || '');
+            }
+            const executedCalls = await Promise.all(functionCalls.map((call) => this.executeFunctionCall(call, tools)));
+            const terminalCall = executedCalls.find((executed) => executed.isTerminal);
+            if (terminalCall) {
+                abortSignal?.throwIfAborted();
+                terminalTool = {
+                    name: terminalCall.toolName,
+                    output: terminalCall.output,
+                };
+                break;
+            }
+            const outputItems = executedCalls.map((executed) => executed.outputItem);
+            abortSignal?.throwIfAborted();
+            tracedConversation.push(...currentResponse.output, ...outputItems);
+            const nextResponse = await rounds.run({
+                input: [...tracedConversation],
+                call: () => this.instance.responses.create({
+                    model: model.name,
+                    input: outputItems,
+                    previous_response_id: currentResponse.id,
+                    tools: allTools,
+                    instructions: this.chatInstructions.get(chatId),
+                    ...(textFormat && { text: textFormat }),
+                }, { signal: abortSignal }),
+                describeOutcome: this.buildRoundOutcome,
+            });
+            this.responseHistory.set(chatId, nextResponse.id);
+            toolIterationsUsed += 1;
+            const iterationUsage = this.extractUsageFromResponse(nextResponse);
+            totalUsage.inputTokens +=
+                iterationUsage.inputTokens;
+            totalUsage.cachedInputTokens +=
+                iterationUsage.cachedInputTokens;
+            totalUsage.outputTokens +=
+                iterationUsage.outputTokens;
+            totalUsage.reasoningTokens +=
+                iterationUsage.reasoningTokens;
+            currentResponse = nextResponse;
+        }
+        const toolIterationsExhausted = !terminalTool
+            && this.getFunctionCallsFromResponse(currentResponse).length > 0;
+        if (toolIterationsExhausted) {
+            this.logger
+                ?.child(this.getMethodName(this.executeToolLoop))
+                .warn('Tool loop reached maxToolIterations', {
+                maxToolIterations: maxIterations,
+                toolIterationsUsed,
+            });
+        }
+        return {
+            response: currentResponse,
+            totalUsage,
+            toolIterationsUsed,
+            toolIterationsExhausted,
+            stopReason: this.resolveToolLoopStopReason({
+                terminalTool,
+                toolIterationsExhausted,
+            }),
+            terminalTool,
+        };
+    }
+    getFunctionCallsFromResponse(response) {
+        return response.output.filter((item) => item.type === 'function_call');
+    }
+    convertLLMMessageToResponsesInput(message) {
+        const { content, role } = message;
+        if (role === LLMService_typedefs_1.LLMRoles.Assistant) {
+            const outputContent = content
+                .filter((item) => item.type === LLMService_typedefs_1.LLMMessageContentType.TEXT)
+                .map((item) => ({
+                type: 'output_text',
+                text: item.text,
+                annotations: [],
+            }));
+            return [{
+                    id: `msg_${Date.now()}_${Math.random().toString(36).substring(2, 9)}`,
+                    role: OpenAI_typedefs_1.OpenAIRoles.Assistant,
+                    content: outputContent,
+                    status: 'completed',
+                    type: 'message',
+                }];
+        }
+        const messageContent = [];
+        content.forEach((item) => {
+            switch (item.type) {
+                case LLMService_typedefs_1.LLMMessageContentType.TEXT:
+                    messageContent.push({
+                        type: 'input_text',
+                        text: item.text,
+                    });
+                    break;
+                case LLMService_typedefs_1.LLMMessageContentType.IMAGE_URL:
+                    messageContent.push({
+                        type: 'input_image',
+                        image_url: item.image_url.url,
+                        detail: 'auto',
+                    });
+                    break;
+                default:
+                    this.logger
+                        ?.child('convertLLMMessageToResponsesInput')
+                        .warn('Unsupported message content type', { item });
+                    break;
+            }
+        });
+        return [{
+                role: role === LLMService_typedefs_1.LLMRoles.User
+                    ? OpenAI_typedefs_1.OpenAIRoles.User
+                    : OpenAI_typedefs_1.OpenAIRoles.Developer,
+                content: messageContent,
+            }];
+    }
+    async countTokens(messages) {
+        const countTokensFn = OpenAI_entity_1.OpenAIEntity
+            .getCountTokensFn();
+        const messageContents = messages.flatMap((message) => message.content);
+        return countTokensFn(messageContents);
+    }
+}
+exports.OpenAIAssistanceService = OpenAIAssistanceService;
+//# sourceMappingURL=OpenAIAssistance.service.js.map