genaicode 2.0.0 → 2.3.0

package/dist/providers/openai-converter.d.ts

@@ -1,5 +1,5 @@
 import type OpenAI from 'openai';
-import type { GenerationRequest, GenerationResult, PromptItem, ToolChoice, ToolDefinition } from '../core/types.js';
+import type { GenerationRequest, GenerationResult, PromptItem, StreamEvent, ToolChoice, ToolDefinition } from '../core/types.js';
 type OpenAIMessage = OpenAI.Chat.Completions.ChatCompletionMessageParam;
 export declare function toOpenAIMessages(prompt: PromptItem[]): OpenAIMessage[];
 export declare function toOpenAITools(tools: ToolDefinition[] | undefined): OpenAI.Chat.Completions.ChatCompletionTool[] | undefined;
@@ -12,5 +12,24 @@ export declare function toOpenAIRequest(request: GenerationRequest, defaultModel
     max_completion_tokens: number | undefined;
     tools: OpenAI.Chat.Completions.ChatCompletionTool[] | undefined;
     tool_choice: OpenAI.Chat.Completions.ChatCompletionToolChoiceOption | undefined;
+    response_format: import("openai/resources/shared.mjs").ResponseFormatText | import("openai/resources/shared.mjs").ResponseFormatJSONSchema | import("openai/resources/shared.mjs").ResponseFormatJSONObject | undefined;
 };
+export declare function toOpenAIStreamRequest(request: GenerationRequest, defaultModel: string): {
+    stream: true;
+    stream_options: {
+        include_usage: true;
+    };
+    model: string;
+    messages: OpenAI.Chat.Completions.ChatCompletionMessageParam[];
+    temperature: number | undefined;
+    max_completion_tokens: number | undefined;
+    tools: OpenAI.Chat.Completions.ChatCompletionTool[] | undefined;
+    tool_choice: OpenAI.Chat.Completions.ChatCompletionToolChoiceOption | undefined;
+    response_format: import("openai/resources/shared.mjs").ResponseFormatText | import("openai/resources/shared.mjs").ResponseFormatJSONSchema | import("openai/resources/shared.mjs").ResponseFormatJSONObject | undefined;
+};
+/**
+ * Accumulate OpenAI chat completion chunks into StreamEvents.
+ * Tool-call argument fragments are emitted as `tool-call-delta` and finalized on `done`.
+ */
+export declare function fromOpenAIStream(chunks: AsyncIterable<OpenAI.Chat.Completions.ChatCompletionChunk>): AsyncGenerator<StreamEvent>;
 export {};

package/dist/providers/openai-converter.js

@@ -97,6 +97,21 @@ export function fromOpenAICompletion(completion) {
         raw: completion,
     };
 }
+function toOpenAIResponseFormat(format) {
+    if (!format || format.type === 'text')
+        return undefined;
+    if (format.type === 'json') {
+        return { type: 'json_object' };
+    }
+    return {
+        type: 'json_schema',
+        json_schema: {
+            name: format.name,
+            schema: format.schema,
+            strict: format.strict,
+        },
+    };
+}
 export function toOpenAIRequest(request, defaultModel) {
     return {
         model: request.model ?? defaultModel,
@@ -105,6 +120,89 @@ export function toOpenAIRequest(request, defaultModel) {
         max_completion_tokens: request.maxOutputTokens,
         tools: toOpenAITools(request.tools),
         tool_choice: toOpenAIToolChoice(request.toolChoice),
+        response_format: toOpenAIResponseFormat(request.responseFormat),
+    };
+}
+export function toOpenAIStreamRequest(request, defaultModel) {
+    return {
+        ...toOpenAIRequest(request, defaultModel),
+        stream: true,
+        stream_options: { include_usage: true },
+    };
+}
+/**
+ * Accumulate OpenAI chat completion chunks into StreamEvents.
+ * Tool-call argument fragments are emitted as `tool-call-delta` and finalized on `done`.
+ */
+export async function* fromOpenAIStream(chunks) {
+    let text = '';
+    const toolCalls = new Map();
+    let model;
+    let finishReason;
+    let usage;
+    let raw;
+    for await (const chunk of chunks) {
+        raw = chunk;
+        model = chunk.model ?? model;
+        if (chunk.usage) {
+            usage = {
+                inputTokens: chunk.usage.prompt_tokens,
+                outputTokens: chunk.usage.completion_tokens,
+                totalTokens: chunk.usage.total_tokens,
+                cachedInputTokens: chunk.usage.prompt_tokens_details?.cached_tokens,
+            };
+            yield { type: 'usage', usage };
+        }
+        const choice = chunk.choices[0];
+        if (!choice)
+            continue;
+        finishReason = choice.finish_reason ?? finishReason;
+        const delta = choice.delta;
+        if (delta.content) {
+            text += delta.content;
+            yield { type: 'text-delta', text: delta.content };
+        }
+        for (const call of delta.tool_calls ?? []) {
+            const current = toolCalls.get(call.index) ?? { arguments: '' };
+            if (call.id)
+                current.id = call.id;
+            if (call.function?.name)
+                current.name = call.function.name;
+            if (call.function?.arguments) {
+                current.arguments += call.function.arguments;
+                yield {
+                    type: 'tool-call-delta',
+                    id: current.id,
+                    name: current.name,
+                    argumentsDelta: call.function.arguments,
+                };
+            }
+            toolCalls.set(call.index, current);
+        }
+    }
+    const parts = [];
+    if (text)
+        parts.push({ type: 'text', text });
+    for (const call of toolCalls.values()) {
+        if (!call.name)
+            continue;
+        const toolCall = {
+            id: call.id,
+            name: call.name,
+            arguments: parseArguments(call.arguments),
+        };
+        parts.push({ type: 'toolCall', toolCall });
+        yield { type: 'tool-call', toolCall };
+    }
+    yield {
+        type: 'done',
+        result: {
+            parts,
+            model,
+            finishReason: finishReason ?? undefined,
+            usage,
+            raw,
+        },
     };
 }
 //# sourceMappingURL=openai-converter.js.map

package/dist/providers/openai-converter.js.map

@@ -1 +1 @@
-{"version":3,"file":"openai-converter.js","sourceRoot":"","sources":["../../src/providers/openai-converter.ts"],"names":[],"mappings":"AAYA,SAAS,cAAc,CAAC,KAAa;IACnC,IAAI,CAAC;QACH,MAAM,MAAM,GAAG,IAAI,CAAC,KAAK,CAAC,KAAK,CAAY,CAAC;QAC5C,OAAO,OAAO,MAAM,KAAK,QAAQ,IAAI,MAAM,KAAK,IAAI,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,MAAM,CAAC;YAC5E,CAAC,CAAE,MAAkC;YACrC,CAAC,CAAC,EAAE,KAAK,EAAE,MAAM,EAAE,CAAC;IACxB,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,EAAE,IAAI,EAAE,KAAK,EAAE,CAAC;IACzB,CAAC;AACH,CAAC;AAED,SAAS,SAAS,CAChB,KAAgD;IAEhD,MAAM,GAAG,GAAG,KAAK,CAAC,GAAG,IAAI,QAAQ,KAAK,CAAC,SAAS,WAAW,KAAK,CAAC,IAAI,IAAI,EAAE,EAAE,CAAC;IAC9E,OAAO,EAAE,IAAI,EAAE,WAAW,EAAE,SAAS,EAAE,EAAE,GAAG,EAAE,EAAE,CAAC;AACnD,CAAC;AAED,MAAM,UAAU,gBAAgB,CAAC,MAAoB;IACnD,OAAO,MAAM,CAAC,OAAO,CAAC,CAAC,IAAI,EAAmB,EAAE;QAC9C,IAAI,IAAI,CAAC,IAAI,KAAK,cAAc,EAAE,CAAC;YACjC,OAAO,CAAC,EAAE,IAAI,EAAE,QAAQ,EAAE,OAAO,EAAE,IAAI,CAAC,YAAY,IAAI,IAAI,CAAC,IAAI,IAAI,EAAE,EAAE,CAAC,CAAC;QAC7E,CAAC;QACD,IAAI,IAAI,CAAC,IAAI,KAAK,WAAW,EAAE,CAAC;YAC9B,OAAO;gBACL;oBACE,IAAI,EAAE,WAAW;oBACjB,OAAO,EAAE,IAAI,CAAC,IAAI,IAAI,IAAI;oBAC1B,GAAG,CAAC,IAAI,CAAC,SAAS,EAAE,MAAM;wBACxB,CAAC,CAAC;4BACE,UAAU,EAAE,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,CAAC;gCACxC,IAAI,EAAE,UAAmB;gCACzB,EAAE,EAAE,IAAI,CAAC,EAAE,IAAI,IAAI,CAAC,IAAI;gCACxB,QAAQ,EAAE,EAAE,IAAI,EAAE,IAAI,CAAC,IAAI,EAAE,SAAS,EAAE,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,SAAS,CAAC,EAAE;6BACzE,CAAC,CAAC;yBACJ;wBACH,CAAC,CAAC,EAAE,CAAC;iBACR;aACF,CAAC;QACJ,CAAC;QAED,MAAM,QAAQ,GAAoB,CAAC,IAAI,CAAC,WAAW,IAAI,EAAE,CAAC,CAAC,GAAG,CAAC,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC;YAC1E,IAAI,EAAE,MAAM;YACZ,YAAY,EAAE,MAAM,CAAC,MAAM,IAAI,MAAM,CAAC,IAAI;YAC1C,OAAO,EAAE,MAAM,CAAC,OAAO;SACxB,CAAC,CAAC,CAAC;QACJ,IAAI,IAAI,CAAC,IAAI,IAAI,IAAI,CAAC,MAAM,EAAE,MAAM,IAAI,QAAQ,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;YAC9D,MAAM,OAAO,GAAG,IAAI,CAAC,MAAM,EAAE,MAAM;gBACjC,CAAC,CAAC,CAAC,GAAG,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,EAAE,IAAI,EAAE,MAAe,EAAE,IAAI,EAAE,IAAI,CAAC,IAAI,EAAE,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,GAAG,IAAI,CAAC,MAAM,CAAC,GAAG,CAAC,SAAS,CAAC,CAAC;gBACrG,CAAC,CAAC,CAAC,IAAI,CAAC,IAAI,IAAI,EAAE,CAAC,CAAC;YACtB,QAAQ,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,CAAC,CAAC;QAC3C,CAAC;QACD,OAAO,QAAQ,CAAC;IAClB,CAAC,CAAC,CAAC;AACL,CAAC;AAED,MAAM,UAAU,aAAa,CAC3B,KAAmC;IAEnC,OAAO,KAAK,EAAE,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,CAAC;QAC3B,IAAI,EAAE,UAAU;QAChB,QAAQ,EAAE;YACR,IAAI,EAAE,IAAI,CAAC,IAAI;YACf,WAAW,EAAE,IAAI,CAAC,WAAW;YAC7B,UAAU,EAAE,IAAI,CAAC,UAAU;SAC5B;KACF,CAAC,CAAC,CAAC;AACN,CAAC;AAED,MAAM,UAAU,kBAAkB,CAChC,MAA8B;IAE9B,IAAI,CAAC,MAAM,IAAI,OAAO,MAAM,KAAK,QAAQ;QAAE,OAAO,MAAM,CAAC;IACzD,OAAO,EAAE,IAAI,EAAE,UAAU,EAAE,QAAQ,EAAE,EAAE,IAAI,EAAE,MAAM,CAAC,IAAI,EAAE,EAAE,CAAC;AAC/D,CAAC;AAED,MAAM,UAAU,oBAAoB,CAAC,UAAkD;IACrF,MAAM,MAAM,GAAG,UAAU,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC;IACrC,MAAM,KAAK,GAAiB,EAAE,CAAC;IAC/B,IAAI,MAAM,EAAE,OAAO,CAAC,OAAO,EAAE,CAAC;QAC5B,KAAK,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,CAAC,OAAO,CAAC,OAAO,EAAE,CAAC,CAAC;IAC7D,CAAC;IACD,KAAK,MAAM,IAAI,IAAI,MAAM,EAAE,OAAO,CAAC,UAAU,IAAI,EAAE,EAAE,CAAC;QACpD,IAAI,IAAI,CAAC,IAAI,KAAK,UAAU;YAAE,SAAS;QACvC,KAAK,CAAC,IAAI,CAAC;YACT,IAAI,EAAE,UAAU;YAChB,QAAQ,EAAE;gBACR,EAAE,EAAE,IAAI,CAAC,EAAE;gBACX,IAAI,EAAE,IAAI,CAAC,QAAQ,CAAC,IAAI;gBACxB,SAAS,EAAE,cAAc,CAAC,IAAI,CAAC,QAAQ,CAAC,SAAS,CAAC;aACnD;SACF,CAAC,CAAC;IACL,CAAC;IACD,OAAO;QACL,KAAK;QACL,KAAK,EAAE,UAAU,CAAC,KAAK;QACvB,YAAY,EAAE,MAAM,EAAE,aAAa,IAAI,SAAS;QAChD,KAAK,EAAE,UAAU,CAAC,KAAK;YACrB,CAAC,CAAC;gBACE,WAAW,EAAE,UAAU,CAAC,KAAK,CAAC,aAAa;gBAC3C,YAAY,EAAE,UAAU,CAAC,KAAK,CAAC,iBAAiB;gBAChD,WAAW,EAAE,UAAU,CAAC,KAAK,CAAC,YAAY;gBAC1C,iBAAiB,EAAE,UAAU,CAAC,KAAK,CAAC,qBAAqB,EAAE,aAAa;aACzE;YACH,CAAC,CAAC,SAAS;QACb,GAAG,EAAE,UAAU;KAChB,CAAC;AACJ,CAAC;AAED,MAAM,UAAU,eAAe,CAAC,OAA0B,EAAE,YAAoB;IAC9E,OAAO;QACL,KAAK,EAAE,OAAO,CAAC,KAAK,IAAI,YAAY;QACpC,QAAQ,EAAE,gBAAgB,CAAC,OAAO,CAAC,MAAM,CAAC;QAC1C,WAAW,EAAE,OAAO,CAAC,WAAW;QAChC,qBAAqB,EAAE,OAAO,CAAC,eAAe;QAC9C,KAAK,EAAE,aAAa,CAAC,OAAO,CAAC,KAAK,CAAC;QACnC,WAAW,EAAE,kBAAkB,CAAC,OAAO,CAAC,UAAU,CAAC;KACqB,CAAC;AAC7E,CAAC"}
+{"version":3,"file":"openai-converter.js","sourceRoot":"","sources":["../../src/providers/openai-converter.ts"],"names":[],"mappings":"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"}

package/dist/providers/openai.js

@@ -1,5 +1,5 @@
 import OpenAI from 'openai';
-import { fromOpenAICompletion, toOpenAIRequest } from './openai-converter.js';
+import { fromOpenAICompletion, fromOpenAIStream, toOpenAIRequest, toOpenAIStreamRequest } from './openai-converter.js';
 export function openai(options = {}) {
     const client = new OpenAI({
         apiKey: options.apiKey ?? process.env.OPENAI_API_KEY,
@@ -10,6 +10,13 @@ export function openai(options = {}) {
     const defaultModel = options.model ?? process.env.OPENAI_MODEL;
     return {
         name: 'openai',
+        capabilities: {
+            streaming: true,
+            tools: true,
+            images: 'input',
+            systemPrompt: true,
+            jsonResponse: true,
+        },
         async generate(request) {
             const model = request.model ?? defaultModel;
             if (!model) {
@@ -20,6 +27,16 @@ export function openai(options = {}) {
             });
             return fromOpenAICompletion(completion);
         },
+        async *stream(request) {
+            const model = request.model ?? defaultModel;
+            if (!model) {
+                throw new Error('No OpenAI model configured. Pass `model` to openai() or the request builder.');
+            }
+            const chunks = await client.chat.completions.create(toOpenAIStreamRequest(request, model), {
+                signal: request.signal,
+            });
+            yield* fromOpenAIStream(chunks);
+        },
     };
 }
 export function openaiCompatible(options) {

package/dist/providers/openai.js.map

@@ -1 +1 @@
-{"version":3,"file":"openai.js","sourceRoot":"","sources":["../../src/providers/openai.ts"],"names":[],"mappings":"AAAA,OAAO,MAAM,MAAM,QAAQ,CAAC;AAE5B,OAAO,EAAE,oBAAoB,EAAE,eAAe,EAAE,MAAM,uBAAuB,CAAC;AAU9E,MAAM,UAAU,MAAM,CAAC,UAAiC,EAAE;IACxD,MAAM,MAAM,GAAG,IAAI,MAAM,CAAC;QACxB,MAAM,EAAE,OAAO,CAAC,MAAM,IAAI,OAAO,CAAC,GAAG,CAAC,cAAc;QACpD,OAAO,EAAE,OAAO,CAAC,OAAO;QACxB,YAAY,EAAE,OAAO,CAAC,YAAY;QAClC,OAAO,EAAE,OAAO,CAAC,OAAO;KACzB,CAAC,CAAC;IACH,MAAM,YAAY,GAAG,OAAO,CAAC,KAAK,IAAI,OAAO,CAAC,GAAG,CAAC,YAAY,CAAC;IAE/D,OAAO;QACL,IAAI,EAAE,QAAQ;QACd,KAAK,CAAC,QAAQ,CAAC,OAAO;YACpB,MAAM,KAAK,GAAG,OAAO,CAAC,KAAK,IAAI,YAAY,CAAC;YAC5C,IAAI,CAAC,KAAK,EAAE,CAAC;gBACX,MAAM,IAAI,KAAK,CAAC,8EAA8E,CAAC,CAAC;YAClG,CAAC;YACD,MAAM,UAAU,GAAG,MAAM,MAAM,CAAC,IAAI,CAAC,WAAW,CAAC,MAAM,CAAC,eAAe,CAAC,OAAO,EAAE,KAAK,CAAC,EAAE;gBACvF,MAAM,EAAE,OAAO,CAAC,MAAM;aACvB,CAAC,CAAC;YACH,OAAO,oBAAoB,CAAC,UAAU,CAAC,CAAC;QAC1C,CAAC;KACF,CAAC;AACJ,CAAC;AAMD,MAAM,UAAU,gBAAgB,CAAC,OAAwC;IACvE,MAAM,QAAQ,GAAG,MAAM,CAAC,OAAO,CAAC,CAAC;IACjC,OAAO,EAAE,GAAG,QAAQ,EAAE,IAAI,EAAE,OAAO,CAAC,IAAI,IAAI,mBAAmB,EAAE,CAAC;AACpE,CAAC"}
+{"version":3,"file":"openai.js","sourceRoot":"","sources":["../../src/providers/openai.ts"],"names":[],"mappings":"AAAA,OAAO,MAAM,MAAM,QAAQ,CAAC;AAE5B,OAAO,EAAE,oBAAoB,EAAE,gBAAgB,EAAE,eAAe,EAAE,qBAAqB,EAAE,MAAM,uBAAuB,CAAC;AAUvH,MAAM,UAAU,MAAM,CAAC,UAAiC,EAAE;IACxD,MAAM,MAAM,GAAG,IAAI,MAAM,CAAC;QACxB,MAAM,EAAE,OAAO,CAAC,MAAM,IAAI,OAAO,CAAC,GAAG,CAAC,cAAc;QACpD,OAAO,EAAE,OAAO,CAAC,OAAO;QACxB,YAAY,EAAE,OAAO,CAAC,YAAY;QAClC,OAAO,EAAE,OAAO,CAAC,OAAO;KACzB,CAAC,CAAC;IACH,MAAM,YAAY,GAAG,OAAO,CAAC,KAAK,IAAI,OAAO,CAAC,GAAG,CAAC,YAAY,CAAC;IAE/D,OAAO;QACL,IAAI,EAAE,QAAQ;QACd,YAAY,EAAE;YACZ,SAAS,EAAE,IAAI;YACf,KAAK,EAAE,IAAI;YACX,MAAM,EAAE,OAAO;YACf,YAAY,EAAE,IAAI;YAClB,YAAY,EAAE,IAAI;SACnB;QACD,KAAK,CAAC,QAAQ,CAAC,OAAO;YACpB,MAAM,KAAK,GAAG,OAAO,CAAC,KAAK,IAAI,YAAY,CAAC;YAC5C,IAAI,CAAC,KAAK,EAAE,CAAC;gBACX,MAAM,IAAI,KAAK,CAAC,8EAA8E,CAAC,CAAC;YAClG,CAAC;YACD,MAAM,UAAU,GAAG,MAAM,MAAM,CAAC,IAAI,CAAC,WAAW,CAAC,MAAM,CAAC,eAAe,CAAC,OAAO,EAAE,KAAK,CAAC,EAAE;gBACvF,MAAM,EAAE,OAAO,CAAC,MAAM;aACvB,CAAC,CAAC;YACH,OAAO,oBAAoB,CAAC,UAAU,CAAC,CAAC;QAC1C,CAAC;QACD,KAAK,CAAC,CAAC,MAAM,CAAC,OAAO;YACnB,MAAM,KAAK,GAAG,OAAO,CAAC,KAAK,IAAI,YAAY,CAAC;YAC5C,IAAI,CAAC,KAAK,EAAE,CAAC;gBACX,MAAM,IAAI,KAAK,CAAC,8EAA8E,CAAC,CAAC;YAClG,CAAC;YACD,MAAM,MAAM,GAAG,MAAM,MAAM,CAAC,IAAI,CAAC,WAAW,CAAC,MAAM,CAAC,qBAAqB,CAAC,OAAO,EAAE,KAAK,CAAC,EAAE;gBACzF,MAAM,EAAE,OAAO,CAAC,MAAM;aACvB,CAAC,CAAC;YACH,KAAK,CAAC,CAAC,gBAAgB,CAAC,MAAM,CAAC,CAAC;QAClC,CAAC;KACF,CAAC;AACJ,CAAC;AAMD,MAAM,UAAU,gBAAgB,CAAC,OAAwC;IACvE,MAAM,QAAQ,GAAG,MAAM,CAAC,OAAO,CAAC,CAAC;IACjC,OAAO,EAAE,GAAG,QAAQ,EAAE,IAAI,EAAE,OAAO,CAAC,IAAI,IAAI,mBAAmB,EAAE,CAAC;AACpE,CAAC"}

package/dist/providers.d.ts

@@ -8,4 +8,4 @@ export { fromGoogleResponse, toGoogleContents, toGoogleRequest, toGoogleSystemIn
 export type { GoogleRequestDefaults } from './providers/google-converter.js';
 export { openai, openaiCompatible } from './providers/openai.js';
 export type { OpenAICompatibleProviderOptions, OpenAIProviderOptions } from './providers/openai.js';
-export { fromOpenAICompletion, toOpenAIMessages, toOpenAIRequest, toOpenAIToolChoice, toOpenAITools, } from './providers/openai-converter.js';
+export { fromOpenAICompletion, fromOpenAIStream, toOpenAIMessages, toOpenAIRequest, toOpenAIStreamRequest, toOpenAIToolChoice, toOpenAITools, } from './providers/openai-converter.js';

package/dist/providers.js

@@ -3,5 +3,5 @@ export { fromAnthropicMessage, toAnthropicMessages, toAnthropicRequest, toAnthro
 export { gemini, vertexAI } from './providers/google.js';
 export { fromGoogleResponse, toGoogleContents, toGoogleRequest, toGoogleSystemInstruction, } from './providers/google-converter.js';
 export { openai, openaiCompatible } from './providers/openai.js';
-export { fromOpenAICompletion, toOpenAIMessages, toOpenAIRequest, toOpenAIToolChoice, toOpenAITools, } from './providers/openai-converter.js';
+export { fromOpenAICompletion, fromOpenAIStream, toOpenAIMessages, toOpenAIRequest, toOpenAIStreamRequest, toOpenAIToolChoice, toOpenAITools, } from './providers/openai-converter.js';
 //# sourceMappingURL=providers.js.map

package/dist/providers.js.map

@@ -1 +1 @@
-{"version":3,"file":"providers.js","sourceRoot":"","sources":["../src/providers.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,MAAM,0BAA0B,CAAC;AAErD,OAAO,EACL,oBAAoB,EACpB,mBAAmB,EACnB,kBAAkB,EAClB,iBAAiB,EACjB,qBAAqB,GACtB,MAAM,oCAAoC,CAAC;AAE5C,OAAO,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,uBAAuB,CAAC;AAEzD,OAAO,EACL,kBAAkB,EAClB,gBAAgB,EAChB,eAAe,EACf,yBAAyB,GAC1B,MAAM,iCAAiC,CAAC;AAEzC,OAAO,EAAE,MAAM,EAAE,gBAAgB,EAAE,MAAM,uBAAuB,CAAC;AAEjE,OAAO,EACL,oBAAoB,EACpB,gBAAgB,EAChB,eAAe,EACf,kBAAkB,EAClB,aAAa,GACd,MAAM,iCAAiC,CAAC"}
+{"version":3,"file":"providers.js","sourceRoot":"","sources":["../src/providers.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,MAAM,0BAA0B,CAAC;AAErD,OAAO,EACL,oBAAoB,EACpB,mBAAmB,EACnB,kBAAkB,EAClB,iBAAiB,EACjB,qBAAqB,GACtB,MAAM,oCAAoC,CAAC;AAE5C,OAAO,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,uBAAuB,CAAC;AAEzD,OAAO,EACL,kBAAkB,EAClB,gBAAgB,EAChB,eAAe,EACf,yBAAyB,GAC1B,MAAM,iCAAiC,CAAC;AAEzC,OAAO,EAAE,MAAM,EAAE,gBAAgB,EAAE,MAAM,uBAAuB,CAAC;AAEjE,OAAO,EACL,oBAAoB,EACpB,gBAAgB,EAChB,gBAAgB,EAChB,eAAe,EACf,qBAAqB,EACrB,kBAAkB,EAClB,aAAa,GACd,MAAM,iCAAiC,CAAC"}

package/docs/pivot.md

@@ -71,20 +71,39 @@ and in the 1.x npm line.
 - Add converter contract tests with multimodal and tool-call fixtures.
 - Keep provider SDKs isolated behind the `genaicode/providers` export.
 
-### Phase 3: backend ergonomics
-
-- Streaming with a provider-neutral event IR.
-- Middleware for observability, rate limiting, caching, and fallback.
-- First-class schema adapters without requiring a specific validation library.
-- Small framework examples for HTTP handlers, queues, and cron jobs.
-- Re-evaluate separate provider packages if dependency size becomes material.
-
-### Phase 4: hardening
-
-- Provider capability metadata.
-- Retry classification and idempotency guidance.
-- Compatibility fixtures for multimodal and tool-call round trips.
-- Stable extension contracts and a written semver policy.
+### Phase 3: backend ergonomics — implemented
+
+- Streaming with a provider-neutral event IR — implemented (`StreamEvent`,
+  `RequestBuilder.stream` / `streamText`, native provider streams with generate
+  fallback).
+- Middleware for observability, rate limiting, caching, and fallback —
+  implemented (`timingPlugin`, `rateLimitPlugin`, `cachePlugin`, `fallbackPlugin`,
+  `fallbackProvider`).
+- First-class schema adapters without requiring a specific validation library — implemented.
+- Small framework examples for HTTP handlers, queues, and cron jobs — implemented
+  under `examples/`.
+- Re-evaluate separate provider packages if dependency size becomes material —
+  evaluated; keep bundled for 2.x (see [provider-packages.md](./provider-packages.md)).
+
+### Phase 4: hardening — implemented
+
+- Provider capability metadata — implemented (`ProviderCapabilities` on
+  `ModelProvider`).
+- Retry classification and idempotency guidance — implemented
+  (`classifyError` / `withRetry` + [retry.md](./retry.md)).
+- Compatibility fixtures for multimodal and tool-call round trips — implemented
+  under `src/providers/fixtures/`.
+- Stable extension contracts and a written semver policy — implemented
+  ([semver.md](./semver.md)).
+
+### Release status
+
+- `2.0.0` on npm shipped the Phase 1–2 kernel and provider adapters.
+- `2.1.0` publishes Phases 3–4 (streaming, middleware, capabilities, retry
+  helpers, fixtures, examples, and related docs).
+- `2.2.0` adds portable `responseFormat` and `thinking` request fields (so apps
+  need fewer provider-specific `generationConfig` casts). See
+  [CHANGELOG.md](../CHANGELOG.md).
 
 ## Success measures
 

package/docs/provider-packages.md

@@ -0,0 +1,60 @@
+# Provider package split evaluation
+
+Phase 3 asked whether OpenAI, Anthropic, and Google adapters should move into
+separate packages to shrink the default install.
+
+## Current shape
+
+| Package surface        | Role                                      |
+| ---------------------- | ----------------------------------------- |
+| `genaicode`            | Core client, IR, plugins, middleware      |
+| `genaicode/providers`  | Adapters + public converters              |
+
+Hard dependencies today (approximate installed sizes in this repo's lockfile):
+
+- `openai` ~12MB
+- `@anthropic-ai/sdk` ~5MB
+- `@google/genai` (+ tree) ~14MB
+
+Together the provider SDKs dominate runtime dependency weight versus the small
+core TypeScript sources.
+
+## Options considered
+
+1. **Keep bundled (status quo)**  
+   One install, one version matrix, simplest DX. Cost: every consumer downloads
+   all three SDKs even if they only use one.
+
+2. **Separate packages** (`genaicode-openai`, `genaicode-anthropic`, …)  
+   Smallest installs. Cost: version skew between core and adapters, more release
+   surface, harder getting-started docs.
+
+3. **Peer dependencies + optional installs**  
+   Core stays free of SDKs; `genaicode/providers` re-exports adapters that import
+   peers. Cost: peer warnings and slightly worse first-run DX.
+
+## Decision for 2.0
+
+**Keep provider adapters bundled behind `genaicode/providers` for 2.x.**
+
+Reasons:
+
+- The product pitch is a tiny portable layer with batteries-included adapters.
+- Converter functions are part of the public compatibility story and are tested
+  together against shared fixtures.
+- Absolute weight (~30MB of SDKs) is material but still far smaller than GenAIcode
+  1.x; success measures emphasize “substantially smaller than 1.x,” not absolute
+  minimalism.
+- Splitting before streaming, middleware, and capability metadata settled would
+  freeze the wrong package boundaries.
+
+## Revisit triggers
+
+Split (or move to optional peers) when any of these become true:
+
+- Published install size or cold `npm install` time becomes a documented user pain.
+- A provider SDK forces frequent breaking upgrades independent of core.
+- Tree-shaking cannot eliminate unused SDKs for bundlers targeting edge runtimes.
+
+Until then, application authors who need a zero-SDK core can implement
+`ModelProvider` directly and ignore `genaicode/providers`.

package/docs/retry.md

@@ -0,0 +1,62 @@
+# Retry classification and idempotency
+
+GenAIcode does **not** retry provider calls automatically. Retries, backoff, and
+failure budgets belong to application code so side effects stay explicit.
+
+## Classify, then decide
+
+```ts
+import { classifyError, isRetryable, withRetry } from 'genaicode';
+
+const classified = classifyError(error);
+if (classified.retryable) {
+  // transient: 408/425/429/5xx, network resets, overload heuristics
+}
+
+await withRetry(() => ai('summarize this').text(), {
+  attempts: 3,
+  delayMs: 250,
+  shouldRetry: (error) => isRetryable(error),
+});
+```
+
+`classifyError` returns `{ class, retryable, reason, status?, code?, cause }`:
+
+| Class       | Typical causes                         | Retry? |
+| ----------- | -------------------------------------- | ------ |
+| `transient` | 429, 5xx, timeouts, connection resets  | yes    |
+| `permanent` | 4xx (except above), auth, abort        | no     |
+| `unknown`   | Unrecognized shapes                    | no*    |
+
+\*Treat unknown as non-retryable by default; override with `shouldRetry` when you
+know more about your gateway.
+
+## Idempotency guidance
+
+Safe to retry without extra coordination:
+
+- Pure generation (`text`, `json`, `toolCalls` that only *propose* tool calls)
+- Read-only prompts against immutable inputs
+
+Not safe to retry blindly:
+
+- Application code that executes tool calls with side effects (writes, charges, emails)
+- Chains where a partial turn already mutated external state
+
+Patterns that keep retries safe:
+
+1. **Propose, then commit.** Let the model return a plan; apply side effects once
+   after validation.
+2. **Idempotency keys.** If a tool must run inside a retry loop, key the effect
+   (e.g. `Idempotency-Key` on a payment API) so duplicates collapse.
+3. **Outbox / queue.** Persist the intended effect before calling the provider, or
+   after a successful model response but before side effects, depending on your
+   failure mode.
+4. **Do not put retries inside plugins by default.** A retry plugin hides policy
+   from callers; prefer `withRetry` at the call site or a named, intentional plugin.
+
+## Streaming
+
+If a stream fails mid-flight, do not assume the partial text was committed anywhere.
+Re-run the full request (or resume with your own checkpointing). Conversation
+chains only append history after a successful completed turn.

package/docs/semver.md

@@ -0,0 +1,56 @@
+# Semver and extension contracts
+
+GenAIcode 2.x follows semantic versioning for the published TypeScript API.
+
+## Public contracts (semver-stable)
+
+These are covered by minor/patch compatibility within 2.x:
+
+- `genaicode()` client, immutable request builders, and conversation chains
+- `PromptItem`, `GenerationRequest`, `GenerationResult`, `StreamEvent`
+- `ResponseFormat`, `ThinkingConfig`, and related capability flags
+- `ModelProvider` and `GenAIPlugin` interfaces
+- Prompt helpers (`prompt`, `system`, `user`, `assistant`, `asPrompt`, …)
+- Result helpers (`resultText`, `parseJsonResult`, …)
+- Built-in middleware factories (`timingPlugin`, `rateLimitPlugin`, `cachePlugin`,
+  `fallbackPlugin`, `fallbackProvider`)
+- Error helpers (`classifyError`, `isRetryable`, `withRetry`)
+- Provider factories and converter functions exported from `genaicode/providers`
+
+## Additive changes (minor)
+
+Safe in a minor release:
+
+- New optional fields on request/result/stream types
+- New optional methods on `ModelProvider` / `GenAIPlugin` (callers must feature-detect)
+- New exports and middleware helpers
+- New provider adapters behind `genaicode/providers`
+- New capability flags on `ProviderCapabilities`
+
+## Breaking changes (major)
+
+Require a new major version:
+
+- Removing or renaming exports
+- Changing the meaning of existing `PromptItem` fields
+- Making previously optional callback/plugin behavior mandatory
+- Changing default retry/side-effect policy (there is none today; introducing
+  hidden retries would be a major behavioral break)
+- Moving provider SDKs in a way that removes the current `genaicode/providers`
+  entry without a compatibility window
+
+## Non-guarantees
+
+- Exact shapes of `raw` provider payloads
+- Timing of stream events beyond the `StreamEvent` discriminant
+- Dependency versions of underlying provider SDKs within a major (may bump in
+  minors when needed for security or API drift)
+- Example apps under `examples/` (illustrative only)
+
+## Plugin and provider authors
+
+- Depend on TypeScript types from `genaicode`, not on private `dist/` paths.
+- Prefer ordinary package exports over runtime loaders.
+- Feature-detect `provider.stream` and `provider.capabilities`.
+- Treat `metadata` on `GenerationRequest` as an open bag for your middleware;
+  do not require core to understand your keys.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "genaicode",
-  "version": "2.0.0",
+  "version": "2.3.0",
   "description": "A small, provider-neutral TypeScript toolkit for calling LLMs from backend code.",
   "author": "Grzegorz Tańczyk",
   "repository": {
@@ -27,6 +27,7 @@
   "files": [
     "dist",
     "docs",
+    "CHANGELOG.md",
     "README.md",
     "LICENSE"
   ],
@@ -45,10 +46,12 @@
     "build": "npm run clean && tsc -p tsconfig.build.json",
     "lint": "eslint . --ext js,ts --report-unused-disable-directives --max-warnings 0",
     "test": "vitest --config vitest.unit.config.ts --run",
+    "test:e2e": "vitest --config vitest.e2e.config.ts --run",
     "test:watch": "vitest --config vitest.unit.config.ts",
     "type-check": "tsc --noEmit",
     "check": "npm run type-check && npm run lint && npm test && npm run build",
-    "prepublishOnly": "npm run check"
+    "prepublishOnly": "npm run check",
+    "prepare": "npm run build"
   },
   "dependencies": {
     "@anthropic-ai/sdk": "^0.74.0",