@flink-app/openai-adapter 2.0.0-alpha.100

package/dist/OpenAIAdapter.js

@@ -0,0 +1,667 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.OpenAIAdapter = void 0;
+const flink_1 = require("@flink-app/flink");
+const openai_1 = __importDefault(require("openai"));
+/**
+ * OpenAI adapter for Flink AI framework using the Responses API
+ *
+ * Built on OpenAI's Responses API (evolution of Chat Completions) which provides:
+ * - Step-aware reasoning: Model can return multiple tool calls in a single response
+ * - Explicit tool invocation: Tool calls and results are first-class typed items
+ * - Better performance: 3% improvement on SWE-bench, 5% on TAUBench
+ *
+ * ## Architecture
+ *
+ * IMPORTANT: The Responses API does NOT run your agent loop.
+ *
+ * What it provides:
+ * - Multiple tool calls in one response (but you execute them)
+ * - Structured step types (message, function_call, function_call_output)
+ * - Streaming event taxonomy
+ *
+ * What you still handle:
+ * - Tool execution (Flink's AgentRunner does this)
+ * - Multi-turn loops (call API → execute tools → call API again)
+ * - Deciding when to stop
+ * - Managing conversation state
+ *
+ * This is intentional - it gives you full control over the agent loop.
+ *
+ * ## Streaming-Only Design
+ *
+ * This adapter uses streaming as the primary method because:
+ * - Better user experience (time-to-first-token <500ms)
+ * - Prevents HTTP timeouts for long responses
+ * - FlinkAgent's lazy generator pattern supports both streaming and non-streaming UX
+ *
+ * For non-streaming consumption, simply await the final result:
+ * ```typescript
+ * const response = agent.execute({ message: "Hello" });
+ * const result = await response.result; // Consumes stream but returns final result
+ * ```
+ *
+ * ## System Instructions - Two Approaches
+ *
+ * You can provide system instructions in two ways:
+ *
+ * 1. **Top-level instructions** (via Flink's instructions parameter):
+ *    - Automatically prepended as system message to conversation
+ *    - Simpler approach, recommended for most cases
+ *    - Following Vercel AI SDK pattern
+ *
+ * 2. **System role messages** (via messages array):
+ *    - Add `{ role: "system", content: "..." }` to messages
+ *    - Gives more control over message structure and placement
+ *    - Useful when you need system context at specific points in conversation
+ *
+ * Both approaches can be used together - system messages in input array + top-level instructions.
+ *
+ * ## Features
+ * - ✅ Step-based tool calling with multiple calls per response
+ * - ✅ Streaming support with event-based updates
+ * - ✅ Structured outputs with JSON schema (100% reliability)
+ * - ✅ Support for all OpenAI models (GPT-4.1, GPT-5, o-series)
+ * - ✅ Flexible system instructions (top-level or in messages)
+ *
+ * ## Basic Usage
+ * ```typescript
+ * import { OpenAIAdapter } from "@flink-app/openai-adapter";
+ * import { FlinkApp } from "@flink-app/flink";
+ *
+ * const app = new FlinkApp({
+ *   ai: {
+ *     llms: {
+ *       default: new OpenAIAdapter({
+ *         apiKey: process.env.OPENAI_API_KEY!,
+ *         model: "gpt-5"
+ *       }),
+ *     },
+ *   },
+ * });
+ * ```
+ *
+ * ## Structured Outputs
+ * ```typescript
+ * const adapter = new OpenAIAdapter({
+ *   apiKey: process.env.OPENAI_API_KEY!,
+ *   model: "gpt-5",
+ *   structuredOutput: {
+ *     type: "json_schema",
+ *     name: "user_profile",
+ *     schema: {
+ *       type: "object",
+ *       properties: {
+ *         name: { type: "string" },
+ *         age: { type: "number" }
+ *       },
+ *       required: ["name", "age"],
+ *       additionalProperties: false
+ *     },
+ *     strict: true
+ *   }
+ * });
+ * ```
+ */
+class OpenAIAdapter {
+    constructor(optionsOrApiKey, model) {
+        this.log = flink_1.FlinkLogFactory.createLogger("flink.ai.openai");
+        if (typeof optionsOrApiKey === "string") {
+            // Legacy constructor: new OpenAIAdapter(apiKey, model)
+            this.client = new openai_1.default({ apiKey: optionsOrApiKey });
+            this.model = model;
+            this.debug = false; // Default: no debug logging
+        }
+        else {
+            // New constructor: new OpenAIAdapter({ apiKey, model, structuredOutput, debug })
+            this.client = new openai_1.default({ apiKey: optionsOrApiKey.apiKey });
+            this.model = optionsOrApiKey.model;
+            this.structuredOutput = optionsOrApiKey.structuredOutput;
+            this.debug = optionsOrApiKey.debug ?? false; // Default: no debug logging
+        }
+        // Enable debug logging for this component if debug flag is set
+        if (this.debug) {
+            this.log.setLevel("debug");
+            this.log.info("OpenAI adapter initialized with debug logging enabled");
+        }
+    }
+    async *stream(params) {
+        try {
+            // Convert instructions to system message + Flink messages to OpenAI Responses API format
+            // Following Vercel AI SDK pattern: instructions are prepended as a system message
+            const input = this.convertMessagesToResponsesInput(params.instructions, params.messages);
+            // Convert tools to Responses API format
+            const tools = params.tools.length > 0 ? this.convertToolsToResponsesFormat(params.tools) : undefined;
+            this.log.trace(JSON.stringify(tools));
+            // Build text format config for structured outputs
+            const textFormat = this.structuredOutput
+                ? {
+                    format: {
+                        type: "json_schema",
+                        name: this.structuredOutput.name,
+                        description: this.structuredOutput.description,
+                        schema: this.structuredOutput.schema,
+                        strict: this.structuredOutput.strict ?? true,
+                    },
+                }
+                : undefined;
+            // Call Responses API with streaming
+            // Note: Each stream is one turn; Flink's AgentRunner handles the multi-turn loop
+            // IMPORTANT: Do NOT include top-level instructions field - we prepend as system message in input array
+            const streamParams = {
+                model: this.model,
+                input: input,
+                tools: tools,
+                max_output_tokens: params.maxTokens,
+                text: textFormat,
+                stream: true,
+                // Only include temperature for models that support it
+                // Reasoning models (o1, o3, gpt-5) don't support temperature
+                ...(this.isReasoningModel() ? {} : { temperature: params.temperature }),
+            };
+            this.log.debug("Starting OpenAI stream request", {
+                model: this.model,
+                messageCount: input.length,
+                toolCount: tools?.length || 0,
+                maxTokens: params.maxTokens,
+                hasStructuredOutput: !!this.structuredOutput,
+            });
+            if (this.debug) {
+                this.log.debug("Full request params:", streamParams);
+            }
+            const stream = await this.client.responses.stream(streamParams);
+            this.log.debug("Stream connection established");
+            let totalInputTokens = 0;
+            let totalOutputTokens = 0;
+            let cachedInputTokens = 0;
+            let finalStatus = "completed";
+            // Track function calls in progress (streaming may send partial data)
+            const functionCallsInProgress = new Map();
+            for await (const event of stream) {
+                // Handle different event types from Responses streaming
+                if (event.type === "response.output_item.added") {
+                    const addedEvent = event;
+                    const item = addedEvent.item;
+                    if (item?.type === "function_call") {
+                        functionCallsInProgress.set(item.call_id, {
+                            name: item.name || "",
+                            arguments: "",
+                        });
+                    }
+                }
+                else if (event.type === "response.output_text.delta") {
+                    const textEvent = event;
+                    yield { type: "text", delta: textEvent.delta || "" };
+                }
+                else if (event.type === "response.function_call_arguments.delta") {
+                    const argsEvent = event;
+                    const callId = argsEvent.item_id;
+                    const existing = functionCallsInProgress.get(callId);
+                    if (existing) {
+                        existing.arguments += argsEvent.delta || "";
+                    }
+                }
+                else if (event.type === "response.output_item.done") {
+                    const doneEvent = event;
+                    const item = doneEvent.item;
+                    if (item?.type === "function_call") {
+                        // Read arguments from the done event item, not from accumulated deltas
+                        // The item.arguments property contains the complete arguments string
+                        const funcItem = item;
+                        // Log the tool call decision from LLM
+                        this.log.debug("LLM decided to call tool", {
+                            name: funcItem.name,
+                            call_id: funcItem.call_id,
+                            arguments: funcItem.arguments,
+                        });
+                        // Handle empty string arguments (LLM sometimes sends "" instead of "{}")
+                        const argsStr = funcItem.arguments?.trim() || "{}";
+                        yield {
+                            type: "tool_call",
+                            toolCall: {
+                                id: funcItem.call_id,
+                                name: funcItem.name,
+                                input: JSON.parse(argsStr),
+                            },
+                        };
+                    }
+                }
+                else if (event.type === "response.completed") {
+                    const completedEvent = event;
+                    const response = completedEvent.response;
+                    if (response?.usage) {
+                        totalInputTokens = response.usage.input_tokens || 0;
+                        totalOutputTokens = response.usage.output_tokens || 0;
+                        // Capture cached tokens from prompt_tokens_details
+                        // @ts-ignore - OpenAI SDK types may not include this yet
+                        cachedInputTokens = response.usage.input_tokens_details?.cached_tokens || 0;
+                    }
+                    finalStatus = response?.status || "completed";
+                }
+            }
+            // Log token usage
+            this.log.info("OpenAI request completed", {
+                inputTokens: totalInputTokens,
+                outputTokens: totalOutputTokens,
+                cachedInputTokens: cachedInputTokens,
+                totalTokens: totalInputTokens + totalOutputTokens,
+                status: finalStatus,
+                model: this.model,
+            });
+            // Yield usage
+            yield {
+                type: "usage",
+                usage: {
+                    inputTokens: totalInputTokens,
+                    outputTokens: totalOutputTokens,
+                    ...(cachedInputTokens > 0 && { cachedInputTokens }),
+                },
+            };
+            // Yield done
+            yield {
+                type: "done",
+                stopReason: this.normalizeStopReason(finalStatus),
+            };
+        }
+        catch (error) {
+            // Log the error
+            this.log.error("OpenAI API request failed", {
+                status: error.status,
+                message: error.message,
+                model: this.model,
+                error: error,
+            });
+            // Enhanced error handling for OpenAI API errors
+            if (error.status === 400) {
+                throw new Error(`OpenAI API error (400 Bad Request): ${error.message || "Invalid request"}. ` +
+                    `Common causes: invalid model name, malformed messages, or invalid tool schemas. ` +
+                    `Model: ${this.model}`);
+            }
+            throw error;
+        }
+    }
+    /**
+     * Convert Flink messages to OpenAI Responses API input format
+     *
+     * Always sends full conversation history for reliability.
+     *
+     * The Responses API accepts:
+     * 1. System messages: { role: "system", content: "..." }
+     * 2. User messages: { role: "user", content: "..." }
+     * 3. Assistant messages: { role: "assistant", content: "..." }
+     * 4. Function calls: { type: "function_call", ... } ← From previous responses
+     * 5. Function call outputs: { type: "function_call_output", ... } ← Tool results
+     *
+     * Multi-turn pattern:
+     * - User: "What's the weather?"
+     * - Assistant: "Let me check" + function_call
+     * - function_call_output: "22°C"
+     * - Assistant: "It's 22°C and sunny"
+     * - User: "What about tomorrow?"
+     *
+     * All message types are preserved for full conversation context.
+     */
+    /**
+     * Build the OpenAI user content from text/image content blocks.
+     * Returns a plain string when there are no images (most common case),
+     * or an array of input_text / input_image items for multimodal messages.
+     * Returns null if there are no user-facing blocks.
+     */
+    buildOpenAIUserContent(blocks) {
+        const textBlocks = blocks.filter((b) => b.type === "text");
+        const imageBlocks = blocks.filter((b) => b.type === "image");
+        if (imageBlocks.length === 0) {
+            // Text-only: keep as plain string for backwards compat
+            const firstText = textBlocks[0];
+            return firstText && firstText.type === "text" ? firstText.text : null;
+        }
+        // Multimodal: build content array
+        const content = [];
+        for (const block of textBlocks) {
+            if (block.type === "text")
+                content.push({ type: "input_text", text: block.text });
+        }
+        for (const block of imageBlocks) {
+            if (block.type === "image")
+                content.push({ type: "input_image", image_url: block.url });
+        }
+        return content.length > 0 ? content : null;
+    }
+    convertMessagesToResponsesInput(instructions, messages) {
+        const result = [];
+        // 1. Prepend instructions as system message (Vercel AI SDK pattern)
+        if (instructions) {
+            result.push({
+                role: "system",
+                content: instructions,
+            });
+        }
+        // Convert all messages to full conversation history
+        for (const msg of messages) {
+            // 2. Handle additional system messages (for dynamic context)
+            if (msg.role === "system") {
+                result.push({
+                    role: "system",
+                    content: msg.content,
+                });
+                continue;
+            }
+            // 3. Handle user messages
+            if (msg.role === "user") {
+                if (typeof msg.content === "string") {
+                    // Simple text message
+                    result.push({
+                        role: "user",
+                        content: msg.content,
+                    });
+                }
+                else {
+                    // Handle content blocks (tool results + text + images)
+                    const content = msg.content;
+                    const toolResultBlocks = content.filter((block) => block.type === "tool_result");
+                    const userBlocks = content.filter((block) => block.type !== "tool_result");
+                    // Add function call outputs (tool results) — these are top-level items
+                    for (const block of toolResultBlocks) {
+                        if (block.type === "tool_result") {
+                            result.push({
+                                type: "function_call_output",
+                                call_id: block.tool_use_id,
+                                output: block.content,
+                            });
+                        }
+                    }
+                    // Add user content (text + images) if present
+                    const userContent = this.buildOpenAIUserContent(userBlocks);
+                    if (userContent) {
+                        result.push({ role: "user", content: userContent });
+                    }
+                }
+                continue;
+            }
+            // 4. Handle assistant messages
+            if (msg.role === "assistant") {
+                if (typeof msg.content === "string") {
+                    // Pass through text-only assistant messages
+                    result.push({
+                        role: "assistant",
+                        content: msg.content,
+                    });
+                    continue;
+                }
+                // Handle assistant messages with content blocks (tool calls)
+                const content = msg.content;
+                const textBlocks = content.filter((block) => block.type === "text");
+                const toolUseBlocks = content.filter((block) => block.type === "tool_use");
+                // Add assistant message if there's text content
+                if (textBlocks.length > 0) {
+                    const firstTextBlock = textBlocks[0];
+                    if (firstTextBlock.type === "text") {
+                        result.push({
+                            role: "assistant",
+                            content: firstTextBlock.text,
+                        });
+                    }
+                }
+                // Add function calls (these MUST be included for context)
+                for (const block of toolUseBlocks) {
+                    if (block.type === "tool_use") {
+                        result.push({
+                            type: "function_call",
+                            call_id: block.id,
+                            name: block.name,
+                            arguments: JSON.stringify(block.input),
+                        });
+                    }
+                }
+                continue;
+            }
+        }
+        return result;
+    }
+    /**
+     * Convert Flink tools to Responses API format
+     *
+     * Responses API uses internally-tagged format:
+     * { type: "function", name: "...", description: "...", parameters: {...} }
+     *
+     * vs Chat Completions externally-tagged format:
+     * { type: "function", function: { name: "...", description: "...", parameters: {...} } }
+     */
+    convertToolsToResponsesFormat(tools) {
+        return tools.map((tool) => ({
+            type: "function",
+            name: tool.name,
+            description: tool.description,
+            parameters: this.sanitizeSchemaForStrictMode(tool.inputSchema),
+            strict: true,
+        }));
+    }
+    /**
+     * Sanitize JSON Schema for OpenAI's strict mode
+     *
+     * OpenAI's strict mode only supports a subset of JSON Schema.
+     * This function removes unsupported keywords that would cause the model
+     * to silently fail and return empty {} arguments.
+     *
+     * Unsupported keywords (stripped):
+     * - $schema (meta-schema reference)
+     * - minLength, maxLength, pattern (string constraints)
+     * - minimum, maximum, exclusiveMinimum, exclusiveMaximum, multipleOf (number constraints)
+     * - minItems, maxItems, uniqueItems (array constraints)
+     * - minProperties, maxProperties (object constraints)
+     * - format (string format hints like "email", "uri")
+     *
+     * Enforced requirements:
+     * - additionalProperties: false on all objects (required by strict mode)
+     * - required array must include all properties without default values
+     *
+     * Note: Removed constraints should be documented in the description field
+     * where the model can read them as natural language instructions.
+     *
+     * Reference: https://platform.openai.com/docs/guides/structured-outputs
+     */
+    sanitizeSchemaForStrictMode(schema) {
+        // Deep clone to avoid mutating the original schema
+        const sanitized = JSON.parse(JSON.stringify(schema));
+        // OpenAI requires the root schema to be of type "object"
+        if (sanitized.type !== "object") {
+            throw new Error(`OpenAI tool input schema must have root type "object", got "${sanitized.type ?? "unknown"}". ` + `Wrap your input type in an object interface.`);
+        }
+        const unsupportedKeywords = [
+            "$schema",
+            "minLength",
+            "maxLength",
+            "pattern",
+            "minimum",
+            "maximum",
+            "exclusiveMinimum",
+            "exclusiveMaximum",
+            "multipleOf",
+            "minItems",
+            "maxItems",
+            "uniqueItems",
+            "minProperties",
+            "maxProperties",
+            "format",
+        ];
+        const sanitizeNode = (node) => {
+            if (!node || typeof node !== "object")
+                return;
+            // OpenAI does not allow any sibling keywords alongside $ref — strip them all
+            if (node.$ref) {
+                const ref = node.$ref;
+                for (const key of Object.keys(node)) {
+                    if (key !== "$ref")
+                        delete node[key];
+                }
+                node.$ref = ref;
+                return; // nothing else to process on a $ref node
+            }
+            // Remove unsupported keywords from this node
+            for (const keyword of unsupportedKeywords) {
+                delete node[keyword];
+            }
+            // Convert const to enum (OpenAI strict mode prefers enum; const alone may lack type)
+            // e.g. { "const": "normal" } → { "type": "string", "enum": ["normal"] }
+            if (node.hasOwnProperty("const")) {
+                const val = node.const;
+                if (!node.type) {
+                    if (val === null)
+                        node.type = "null";
+                    else if (typeof val === "string")
+                        node.type = "string";
+                    else if (typeof val === "number")
+                        node.type = "number";
+                    else if (typeof val === "boolean")
+                        node.type = "boolean";
+                }
+                node.enum = [val];
+                delete node.const;
+            }
+            // Enforce additionalProperties: false on objects (required by strict mode)
+            // Also ensure properties exists (OpenAI requires it even for empty objects)
+            if (node.type === "object" && !node.properties) {
+                node.properties = {};
+            }
+            if (node.type === "object" && node.properties) {
+                node.additionalProperties = false;
+                // Fix the required array to only include properties without defaults
+                // OpenAI requires all properties to either be in 'required' or have a 'default'
+                if (node.required && Array.isArray(node.required)) {
+                    const propertyKeys = Object.keys(node.properties);
+                    const requiredFields = propertyKeys.filter((key) => {
+                        const prop = node.properties[key];
+                        return !prop.hasOwnProperty("default");
+                    });
+                    node.required = requiredFields;
+                }
+                else if (node.properties) {
+                    // If no required array exists, create one with all properties without defaults
+                    const propertyKeys = Object.keys(node.properties);
+                    const requiredFields = propertyKeys.filter((key) => {
+                        const prop = node.properties[key];
+                        return !prop.hasOwnProperty("default");
+                    });
+                    if (requiredFields.length > 0) {
+                        node.required = requiredFields;
+                    }
+                }
+            }
+            // Recursively sanitize nested structures
+            if (node.properties) {
+                for (const key in node.properties) {
+                    sanitizeNode(node.properties[key]);
+                }
+            }
+            if (node.items) {
+                if (Array.isArray(node.items)) {
+                    node.items.forEach(sanitizeNode);
+                }
+                else {
+                    sanitizeNode(node.items);
+                }
+            }
+            if (node.allOf)
+                node.allOf.forEach(sanitizeNode);
+            if (node.anyOf) {
+                node.anyOf.forEach(sanitizeNode);
+                // Collapse anyOf of simple typed enums into a cleaner form.
+                // e.g. anyOf[{type:"string",enum:["a"]},{type:"string",enum:["b"]},{type:"number",enum:[1]}]
+                //   → anyOf[{type:"string",enum:["a","b"]},{type:"number",enum:[1]}]
+                // And if only one type remains, unwrap the anyOf entirely:
+                //   → {type:"string",enum:["a","b"]}
+                const isSimpleEnum = (e) => e &&
+                    typeof e === "object" &&
+                    typeof e.type === "string" &&
+                    Array.isArray(e.enum) &&
+                    !e.$ref &&
+                    !e.anyOf &&
+                    !e.allOf &&
+                    !e.oneOf &&
+                    !e.properties &&
+                    !e.items;
+                if (node.anyOf.every(isSimpleEnum)) {
+                    const byType = {};
+                    for (const entry of node.anyOf) {
+                        if (!byType[entry.type])
+                            byType[entry.type] = [];
+                        byType[entry.type].push(...entry.enum);
+                    }
+                    const types = Object.keys(byType);
+                    if (types.length === 1) {
+                        node.type = types[0];
+                        node.enum = byType[types[0]];
+                        delete node.anyOf;
+                    }
+                    else {
+                        node.anyOf = types.map((t) => ({ type: t, enum: byType[t] }));
+                    }
+                }
+            }
+            if (node.oneOf)
+                node.oneOf.forEach(sanitizeNode);
+            if (node.not)
+                sanitizeNode(node.not);
+            // Sanitize schemas in $defs (added by ToolExecutor to make schemas self-contained)
+            if (node.$defs && typeof node.$defs === "object") {
+                for (const def of Object.values(node.$defs)) {
+                    sanitizeNode(def);
+                }
+            }
+        };
+        sanitizeNode(sanitized);
+        return sanitized;
+    }
+    /**
+     * Check if the model is a reasoning model that doesn't support temperature
+     *
+     * Reasoning models use a different internal process and don't allow temperature control:
+     * - o1, o1-mini, o1-preview
+     * - o3, o3-mini
+     * - gpt-5 (uses reasoning approach)
+     */
+    isReasoningModel() {
+        const modelLower = this.model.toLowerCase();
+        return modelLower.startsWith("o1") || modelLower.startsWith("o3") || modelLower.startsWith("gpt-5");
+    }
+    /**
+     * Normalize stop reason from Responses API to Flink format
+     *
+     * LIMITATION: This mapping is lossy. Responses API provides richer status:
+     * - "completed" → "end_turn"
+     * - "incomplete" → "max_tokens"
+     * - "failed" → "max_tokens" (loses error signal)
+     * - "cancelled" → "end_turn" (loses cancellation signal)
+     *
+     * Future improvement: Add LLMResponse.metadata field to preserve:
+     * - Raw status from provider
+     * - Safety stop reasons
+     * - Tool execution errors
+     * - Model-specific error codes
+     *
+     * For now, we map to Flink's limited set and lose granularity.
+     */
+    normalizeStopReason(status) {
+        // Map Responses API status to Flink's stopReason enum
+        switch (status) {
+            case "incomplete":
+                return "max_tokens"; // Hit token limit
+            case "failed":
+                // TODO: This loses important signal (safety, tool_error, model_error)
+                // Consider logging or adding metadata field
+                return "max_tokens"; // Best approximation for now
+            case "cancelled":
+                return "end_turn"; // User/system cancelled
+            case "completed":
+            default:
+                // For Responses API, tool calls are part of the response items
+                // so we typically get "completed" even when tools were called
+                return "end_turn";
+        }
+    }
+}
+exports.OpenAIAdapter = OpenAIAdapter;
+//# sourceMappingURL=OpenAIAdapter.js.map