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

package/dist/OpenAIAdapter.d.ts

@@ -0,0 +1,245 @@
+import type { FlinkToolSchema, LLMAdapter, LLMMessage, LLMStreamChunk } from "@flink-app/flink/ai";
+export interface OpenAIAdapterOptions {
+    /**
+     * OpenAI API key
+     */
+    apiKey: string;
+    /**
+     * Model to use (e.g., "gpt-4.1", "gpt-5", "o4-mini")
+     */
+    model: string;
+    /**
+     * Optional: Enable structured outputs with JSON schema validation
+     * Ensures the model output matches the provided schema with 100% reliability
+     *
+     * In Responses API, this is configured via text.format instead of response_format
+     * @see https://platform.openai.com/docs/guides/structured-outputs
+     */
+    structuredOutput?: {
+        type: "json_schema";
+        name: string;
+        description?: string;
+        schema: Record<string, unknown>;
+        strict?: boolean;
+    };
+    /**
+     * Optional: Enable debug logging for development and troubleshooting
+     *
+     * When enabled, logs:
+     * - Full request parameters sent to OpenAI
+     * - Tool call decisions made by the LLM
+     * - Token usage and performance metrics
+     *
+     * @default false
+     */
+    debug?: boolean;
+}
+/**
+ * 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
+ *   }
+ * });
+ * ```
+ */
+export declare class OpenAIAdapter implements LLMAdapter<FlinkToolSchema> {
+    private client;
+    private model;
+    private structuredOutput?;
+    debug: boolean;
+    private log;
+    constructor(options: OpenAIAdapterOptions);
+    constructor(apiKey: string, model: string);
+    stream(params: {
+        instructions: string;
+        messages: LLMMessage[];
+        tools: FlinkToolSchema[];
+        maxTokens: number;
+        temperature: number;
+        providerMetadata?: Record<string, any>;
+    }): AsyncGenerator<LLMStreamChunk>;
+    /**
+     * 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.
+     */
+    private buildOpenAIUserContent;
+    private convertMessagesToResponsesInput;
+    /**
+     * 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: {...} } }
+     */
+    private convertToolsToResponsesFormat;
+    /**
+     * 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
+     */
+    private sanitizeSchemaForStrictMode;
+    /**
+     * 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)
+     */
+    private isReasoningModel;
+    /**
+     * 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.
+     */
+    private normalizeStopReason;
+}
+//# sourceMappingURL=OpenAIAdapter.d.ts.map

package/dist/OpenAIAdapter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"OpenAIAdapter.d.ts","sourceRoot":"","sources":["../src/OpenAIAdapter.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,eAAe,EAAE,UAAU,EAAmB,UAAU,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAC;AAcpH,MAAM,WAAW,oBAAoB;IACjC;;OAEG;IACH,MAAM,EAAE,MAAM,CAAC;IAEf;;OAEG;IACH,KAAK,EAAE,MAAM,CAAC;IAEd;;;;;;OAMG;IACH,gBAAgB,CAAC,EAAE;QACf,IAAI,EAAE,aAAa,CAAC;QACpB,IAAI,EAAE,MAAM,CAAC;QACb,WAAW,CAAC,EAAE,MAAM,CAAC;QACrB,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;QAChC,MAAM,CAAC,EAAE,OAAO,CAAC;KACpB,CAAC;IAEF;;;;;;;;;OASG;IACH,KAAK,CAAC,EAAE,OAAO,CAAC;CACnB;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmGG;AACH,qBAAa,aAAc,YAAW,UAAU,CAAC,eAAe,CAAC;IAC7D,OAAO,CAAC,MAAM,CAAS;IACvB,OAAO,CAAC,KAAK,CAAS;IACtB,OAAO,CAAC,gBAAgB,CAAC,CAA2C;IAC7D,KAAK,EAAE,OAAO,CAAC;IACtB,OAAO,CAAC,GAAG,CAAmD;gBAElD,OAAO,EAAE,oBAAoB;gBAC7B,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM;IAsBlC,MAAM,CAAC,MAAM,EAAE;QAClB,YAAY,EAAE,MAAM,CAAC;QACrB,QAAQ,EAAE,UAAU,EAAE,CAAC;QACvB,KAAK,EAAE,eAAe,EAAE,CAAC;QACzB,SAAS,EAAE,MAAM,CAAC;QAClB,WAAW,EAAE,MAAM,CAAC;QACpB,gBAAgB,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC;KAC1C,GAAG,cAAc,CAAC,cAAc,CAAC;IAyKlC;;;;;;;;;;;;;;;;;;;;OAoBG;IAEH;;;;;OAKG;IACH,OAAO,CAAC,sBAAsB;IAqB9B,OAAO,CAAC,+BAA+B;IAqGvC;;;;;;;;OAQG;IACH,OAAO,CAAC,6BAA6B;IAUrC;;;;;;;;;;;;;;;;;;;;;;;OAuBG;IACH,OAAO,CAAC,2BAA2B;IA8JnC;;;;;;;OAOG;IACH,OAAO,CAAC,gBAAgB;IAKxB;;;;;;;;;;;;;;;;OAgBG;IACH,OAAO,CAAC,mBAAmB;CAkB9B"}