@aryee337/aery-ai 0.1.148 → 0.2.10

package/README.md

@@ -16,9 +16,6 @@ Unified LLM API with automatic model discovery, provider configuration, token an
   - [Validating Tool Arguments](#validating-tool-arguments)
   - [Complete Event Reference](#complete-event-reference)
 - [Image Input](#image-input)
-- [Image Generation](#image-generation)
-  - [Basic Image Generation](#basic-image-generation)
-  - [Notes and Limitations](#notes-and-limitations)
 - [Thinking/Reasoning](#thinkingreasoning)
   - [Unified Interface](#unified-interface-streamsimplecompletesimple)
   - [Provider-Specific Options](#provider-specific-options-streamcomplete)
@@ -36,11 +33,10 @@ Unified LLM API with automatic model discovery, provider configuration, token an
 - [Cross-Provider Handoffs](#cross-provider-handoffs)
 - [Context Serialization](#context-serialization)
 - [Browser Usage](#browser-usage)
-  - [Browser Compatibility Notes](#browser-compatibility-notes)
   - [Environment Variables](#environment-variables-nodejs-only)
   - [Checking Environment Variables](#checking-environment-variables)
 - [OAuth Providers](#oauth-providers)
-  - [Vertex AI](#vertex-ai)
+  - [Vertex AI (ADC)](#vertex-ai-adc)
   - [CLI Login](#cli-login)
   - [Programmatic OAuth](#programmatic-oauth)
   - [Login Flow Example](#login-flow-example)
@@ -51,30 +47,40 @@ Unified LLM API with automatic model discovery, provider configuration, token an
 ## Supported Providers
 
 - **OpenAI**
-- **Azure OpenAI (Responses)**
 - **OpenAI Codex** (ChatGPT Plus/Pro subscription, requires OAuth, see below)
-- **DeepSeek**
 - **Anthropic**
 - **Google**
 - **Vertex AI** (Gemini via Vertex AI)
 - **Mistral**
 - **Groq**
 - **Cerebras**
-- **Cloudflare AI Gateway**
-- **Cloudflare Workers AI**
+- **Together**
+- **Moonshot** (requires `MOONSHOT_API_KEY`)
+- **Qianfan** (requires `QIANFAN_API_KEY`)
+- **NVIDIA** (requires `NVIDIA_API_KEY`)
+- **NanoGPT** (requires `NANO_GPT_API_KEY`)
+- **Hugging Face Inference**
 - **xAI**
+- **Venice** (requires `VENICE_API_KEY`)
+- **Wafer Pass** (requires `WAFER_PASS_API_KEY`; flat-rate subscription, includes GLM-5.1 and Qwen3.5-397B-A17B)
+- **Wafer Serverless** (requires `WAFER_SERVERLESS_API_KEY`; pay-as-you-go)
 - **OpenRouter**
-- **Vercel AI Gateway**
-- **MiniMax**
-- **Together AI**
+- **Kilo Gateway** (supports OAuth `/login kilo` or `KILO_API_KEY`)
+- **LiteLLM** (requires `LITELLM_API_KEY`)
+- **zAI** (requires `ZAI_API_KEY`)
+- **MiniMax Coding Plan** (requires `MINIMAX_CODE_API_KEY` or `MINIMAX_CODE_CN_API_KEY`)
+- **Xiaomi MiMo** (requires `XIAOMI_API_KEY`)
+- **ZenMux** (requires `ZENMUX_API_KEY`)
+- **Qwen Portal** (supports `QWEN_OAUTH_TOKEN` or `QWEN_PORTAL_API_KEY`)
+- **Cloudflare AI Gateway** (requires `CLOUDFLARE_AI_GATEWAY_API_KEY` and provider-specific gateway base URL)
+- **Ollama** (local OpenAI-compatible runtime; optional `OLLAMA_API_KEY`)
+- **Ollama Cloud** (hosted native Ollama API; requires `OLLAMA_CLOUD_API_KEY`)
+- **llama.cpp** (local OpenAI and Anthropic compatible inference server)
+- **vLLM** (OpenAI-compatible server; `VLLM_API_KEY` for secured deployments)
 - **GitHub Copilot** (requires OAuth, see below)
-- **Amazon Bedrock**
-- **OpenCode Zen**
-- **OpenCode Go**
-- **Fireworks** (uses Anthropic-compatible API)
-- **Kimi For Coding** (Moonshot AI, uses Anthropic-compatible API)
-- **Xiaomi MiMo** (uses Anthropic-compatible API; defaults to API billing endpoint, with separate Token Plan providers for `cn`/`ams`/`sgp` regions)
-- **Any OpenAI-compatible API**: Ollama, vLLM, LM Studio, etc.
+- **Google Gemini CLI** (requires OAuth, see below)
+- **Antigravity** (requires OAuth, see below)
+- **Any OpenAI-compatible API**: LM Studio, custom proxies, etc.
 
 ## Installation
 
@@ -82,79 +88,82 @@ Unified LLM API with automatic model discovery, provider configuration, token an
 npm install @aryee337/aery-ai
 ```
 
-TypeBox exports are re-exported from `@aryee337/aery-ai`: `Type`, `Static`, and `TSchema`.
-
 ## Quick Start
 
 ```typescript
-import { Type, getModel, stream, complete, Context, Tool, StringEnum } from '@aryee337/aery-ai';
+import { z, getModel, stream, complete, Context, Tool } from "@aryee337/aery-ai";
 
 // Fully typed with auto-complete support for both providers and models
-const model = getModel('openai', 'gpt-4o-mini');
-
-// Define tools with TypeBox schemas for type safety and validation
-const tools: Tool[] = [{
-  name: 'get_time',
-  description: 'Get the current time',
-  parameters: Type.Object({
-    timezone: Type.Optional(Type.String({ description: 'Optional timezone (e.g., America/New_York)' }))
-  })
-}];
+const model = getModel("openai", "gpt-4o-mini");
+
+// Define tools with Zod schemas for type safety and validation
+const tools: Tool[] = [
+	{
+		name: "get_time",
+		description: "Get the current time",
+		parameters: z.object({
+			timezone: z
+				.string()
+				.optional()
+				.describe("Optional timezone (e.g., America/New_York)"),
+		}),
+	},
+];
 
 // Build a conversation context (easily serializable and transferable between models)
 const context: Context = {
-  systemPrompt: 'You are a helpful assistant.',
-  messages: [{ role: 'user', content: 'What time is it?' }],
-  tools
+	systemPrompt: ["You are a helpful assistant."],
+	messages: [{ role: "user", content: "What time is it?" }],
+	tools,
 };
 
 // Option 1: Streaming with all event types
 const s = stream(model, context);
 
 for await (const event of s) {
-  switch (event.type) {
-    case 'start':
-      console.log(`Starting with ${event.partial.model}`);
-      break;
-    case 'text_start':
-      console.log('\n[Text started]');
-      break;
-    case 'text_delta':
-      process.stdout.write(event.delta);
-      break;
-    case 'text_end':
-      console.log('\n[Text ended]');
-      break;
-    case 'thinking_start':
-      console.log('[Model is thinking...]');
-      break;
-    case 'thinking_delta':
-      process.stdout.write(event.delta);
-      break;
-    case 'thinking_end':
-      console.log('[Thinking complete]');
-      break;
-    case 'toolcall_start':
-      console.log(`\n[Tool call started: index ${event.contentIndex}]`);
-      break;
-    case 'toolcall_delta':
-      // Partial tool arguments are being streamed
-      const partialCall = event.partial.content[event.contentIndex];
-      if (partialCall.type === 'toolCall') {
-        console.log(`[Streaming args for ${partialCall.name}]`);
-      }
-      break;
-    case 'toolcall_end':
-      console.log(`\nTool called: ${event.toolCall.name}`);
-      console.log(`Arguments: ${JSON.stringify(event.toolCall.arguments)}`);
-      break;
-    case 'done':
-      console.log(`\nFinished: ${event.reason}`);
-      break;
-    case 'error':
-      console.error(`Error: ${event.error}`);
-      break;
-  }
+	switch (event.type) {
+		case "start":
+			console.log(`Starting with ${event.partial.model}`);
+			break;
+		case "text_start":
+			console.log("\n[Text started]");
+			break;
+		case "text_delta":
+			process.stdout.write(event.delta);
+			break;
+		case "text_end":
+			console.log("\n[Text ended]");
+			break;
+		case "thinking_start":
+			console.log("[Model is thinking...]");
+			break;
+		case "thinking_delta":
+			process.stdout.write(event.delta);
+			break;
+		case "thinking_end":
+			console.log("[Thinking complete]");
+			break;
+		case "toolcall_start":
+			console.log(`\n[Tool call started: index ${event.contentIndex}]`);
+			break;
+		case "toolcall_delta":
+			// Partial tool arguments are being streamed
+			const partialCall = event.partial.content[event.contentIndex];
+			if (partialCall.type === "toolCall") {
+				console.log(`[Streaming args for ${partialCall.name}]`);
+			}
+			break;
+		case "toolcall_end":
+			console.log(`\nTool called: ${event.toolCall.name}`);
+			console.log(`Arguments: ${JSON.stringify(event.toolCall.arguments)}`);
+			break;
+		case "done":
+			console.log(`\nFinished: ${event.reason}`);
+			break;
+		case "error":
+			console.error(`Error: ${event.error}`);
+			break;
+	}
 }
 
 // Get the final message after streaming, add it to the context
@@ -162,33 +171,34 @@ const finalMessage = await s.result();
 context.messages.push(finalMessage);
 
 // Handle tool calls if any
-const toolCalls = finalMessage.content.filter(b => b.type === 'toolCall');
+const toolCalls = finalMessage.content.filter((b) => b.type === "toolCall");
 for (const call of toolCalls) {
-  // Execute the tool
-  const result = call.name === 'get_time'
-    ? new Date().toLocaleString('en-US', {
-        timeZone: call.arguments.timezone || 'UTC',
-        dateStyle: 'full',
-        timeStyle: 'long'
-      })
-    : 'Unknown tool';
-
-  // Add tool result to context (supports text and images)
-  context.messages.push({
-    role: 'toolResult',
-    toolCallId: call.id,
-    toolName: call.name,
-    content: [{ type: 'text', text: result }],
-    isError: false,
-    timestamp: Date.now()
-  });
+	// Execute the tool
+	const result =
+		call.name === "get_time"
+			? new Date().toLocaleString("en-US", {
+					timeZone: call.arguments.timezone || "UTC",
+					dateStyle: "full",
+					timeStyle: "long",
+				})
+			: "Unknown tool";
+
+	// Add tool result to context (supports text and images)
+	context.messages.push({
+		role: "toolResult",
+		toolCallId: call.id,
+		toolName: call.name,
+		content: [{ type: "text", text: result }],
+		isError: false,
+		timestamp: Date.now(),
+	});
 }
 
 // Continue if there were tool calls
 if (toolCalls.length > 0) {
-  const continuation = await complete(model, context);
-  context.messages.push(continuation);
-  console.log('After tool execution:', continuation.content);
+	const continuation = await complete(model, context);
+	context.messages.push(continuation);
+	console.log("After tool execution:", continuation.content);
 }
 
 console.log(`Total tokens: ${finalMessage.usage.input} in, ${finalMessage.usage.output} out`);
@@ -198,45 +208,42 @@ console.log(`Cost: $${finalMessage.usage.cost.total.toFixed(4)}`);
 const response = await complete(model, context);
 
 for (const block of response.content) {
-  if (block.type === 'text') {
-    console.log(block.text);
-  } else if (block.type === 'toolCall') {
-    console.log(`Tool: ${block.name}(${JSON.stringify(block.arguments)})`);
-  }
+	if (block.type === "text") {
+		console.log(block.text);
+	} else if (block.type === "toolCall") {
+		console.log(`Tool: ${block.name}(${JSON.stringify(block.arguments)})`);
+	}
 }
 ```
 
 ## Tools
 
-Tools enable LLMs to interact with external systems. This library uses TypeBox schemas for type-safe tool definitions with automatic validation using TypeBox's built-in validator and value conversion utilities. TypeBox schemas can be serialized and deserialized as plain JSON, making them ideal for distributed systems.
+Tools enable LLMs to interact with external systems. This library uses **Zod** schemas for type-safe tool definitions with automatic validation. Schemas are converted to JSON Schema for providers as needed.
 
 ### Defining Tools
 
 ```typescript
-import { Type, Tool, StringEnum } from '@aryee337/aery-ai';
+import { z, Tool } from "@aryee337/aery-ai";
 
-// Define tool parameters with TypeBox
+// Define tool parameters with Zod
 const weatherTool: Tool = {
-  name: 'get_weather',
-  description: 'Get current weather for a location',
-  parameters: Type.Object({
-    location: Type.String({ description: 'City name or coordinates' }),
-    units: StringEnum(['celsius', 'fahrenheit'], { default: 'celsius' })
-  })
+	name: "get_weather",
+	description: "Get current weather for a location",
+	parameters: z.object({
+		location: z.string().describe("City name or coordinates"),
+		units: z.enum(["celsius", "fahrenheit"]).default("celsius"),
+	}),
 };
 
-// Note: For Google API compatibility, use StringEnum helper instead of Type.Enum
-// Type.Enum generates anyOf/const patterns that Google doesn't support
-
 const bookMeetingTool: Tool = {
-  name: 'book_meeting',
-  description: 'Schedule a meeting',
-  parameters: Type.Object({
-    title: Type.String({ minLength: 1 }),
-    startTime: Type.String({ format: 'date-time' }),
-    endTime: Type.String({ format: 'date-time' }),
-    attendees: Type.Array(Type.String({ format: 'email' }), { minItems: 1 })
-  })
+	name: "book_meeting",
+	description: "Schedule a meeting",
+	parameters: z.object({
+		title: z.string().min(1),
+		startTime: z.string().describe("ISO 8601 date-time"),
+		endTime: z.string().describe("ISO 8601 date-time"),
+		attendees: z.array(z.email()).min(1),
+	}),
 };
 ```
 
@@ -245,46 +252,46 @@ const bookMeetingTool: Tool = {
 Tool results use content blocks and can include both text and images:
 
 ```typescript
-import { readFileSync } from 'fs';
+import * as fs from "node:fs";
 
 const context: Context = {
-  messages: [{ role: 'user', content: 'What is the weather in London?' }],
-  tools: [weatherTool]
+	messages: [{ role: "user", content: "What is the weather in London?" }],
+	tools: [weatherTool],
 };
 
 const response = await complete(model, context);
 
 // Check for tool calls in the response
 for (const block of response.content) {
-  if (block.type === 'toolCall') {
-    // Execute your tool with the arguments
-    // See "Validating Tool Arguments" section for validation
-    const result = await executeWeatherApi(block.arguments);
-
-    // Add tool result with text content
-    context.messages.push({
-      role: 'toolResult',
-      toolCallId: block.id,
-      toolName: block.name,
-      content: [{ type: 'text', text: JSON.stringify(result) }],
-      isError: false,
-      timestamp: Date.now()
-    });
-  }
+	if (block.type === "toolCall") {
+		// Execute your tool with the arguments
+		// See "Validating Tool Arguments" section for validation
+		const result = await executeWeatherApi(block.arguments);
+
+		// Add tool result with text content
+		context.messages.push({
+			role: "toolResult",
+			toolCallId: block.id,
+			toolName: block.name,
+			content: [{ type: "text", text: JSON.stringify(result) }],
+			isError: false,
+			timestamp: Date.now(),
+		});
+	}
 }
 
 // Tool results can also include images (for vision-capable models)
-const imageBuffer = readFileSync('chart.png');
+const imageBuffer = fs.readFileSync("chart.png");
 context.messages.push({
-  role: 'toolResult',
-  toolCallId: 'tool_xyz',
-  toolName: 'generate_chart',
-  content: [
-    { type: 'text', text: 'Generated chart showing temperature trends' },
-    { type: 'image', data: imageBuffer.toString('base64'), mimeType: 'image/png' }
-  ],
-  isError: false,
-  timestamp: Date.now()
+	role: "toolResult",
+	toolCallId: "tool_xyz",
+	toolName: "generate_chart",
+	content: [
+		{ type: "text", text: "Generated chart showing temperature trends" },
+		{ type: "image", data: imageBuffer.toBase64(), mimeType: "image/png" },
+	],
+	isError: false,
+	timestamp: Date.now(),
 });
 ```
 
@@ -296,34 +303,35 @@ During streaming, tool call arguments are progressively parsed as they arrive. T
 const s = stream(model, context);
 
 for await (const event of s) {
-  if (event.type === 'toolcall_delta') {
-    const toolCall = event.partial.content[event.contentIndex];
-
-    // toolCall.arguments contains partially parsed JSON during streaming
-    // This allows for progressive UI updates
-    if (toolCall.type === 'toolCall' && toolCall.arguments) {
-      // BE DEFENSIVE: arguments may be incomplete
-      // Example: Show file path being written even before content is complete
-      if (toolCall.name === 'write_file' && toolCall.arguments.path) {
-        console.log(`Writing to: ${toolCall.arguments.path}`);
-
-        // Content might be partial or missing
-        if (toolCall.arguments.content) {
-          console.log(`Content preview: ${toolCall.arguments.content.substring(0, 100)}...`);
-        }
-      }
-    }
-  }
-
-  if (event.type === 'toolcall_end') {
-    // Here toolCall.arguments is complete (but not yet validated)
-    const toolCall = event.toolCall;
-    console.log(`Tool completed: ${toolCall.name}`, toolCall.arguments);
-  }
+	if (event.type === "toolcall_delta") {
+		const toolCall = event.partial.content[event.contentIndex];
+
+		// toolCall.arguments contains partially parsed JSON during streaming
+		// This allows for progressive UI updates
+		if (toolCall.type === "toolCall" && toolCall.arguments) {
+			// BE DEFENSIVE: arguments may be incomplete
+			// Example: Show file path being written even before content is complete
+			if (toolCall.name === "write_file" && toolCall.arguments.path) {
+				console.log(`Writing to: ${toolCall.arguments.path}`);
+
+				// Content might be partial or missing
+				if (toolCall.arguments.content) {
+					console.log(`Content preview: ${toolCall.arguments.content.substring(0, 100)}...`);
+				}
+			}
+		}
+	}
+
+	if (event.type === "toolcall_end") {
+		// Here toolCall.arguments is complete (but not yet validated)
+		const toolCall = event.toolCall;
+		console.log(`Tool completed: ${toolCall.name}`, toolCall.arguments);
+	}
 }
 ```
 
 **Important notes about partial tool arguments:**
+
 - During `toolcall_delta` events, `arguments` contains the best-effort parse of partial JSON
 - Fields may be missing or incomplete - always check for existence before use
 - String values may be truncated mid-word
@@ -334,37 +342,37 @@ for await (const event of s) {
 
 ### Validating Tool Arguments
 
-When using `agentLoop`, tool arguments are automatically validated against your TypeBox schemas before execution. If validation fails, the error is returned to the model as a tool result, allowing it to retry.
+When using `agentLoop`, tool arguments are automatically validated against your Zod parameter schemas before execution. If validation fails, the error is returned to the model as a tool result, allowing it to retry.
 
 When implementing your own tool execution loop with `stream()` or `complete()`, use `validateToolCall` to validate arguments before passing them to your tools:
 
 ```typescript
-import { stream, validateToolCall, Tool } from '@aryee337/aery-ai';
+import { stream, validateToolCall, Tool } from "@aryee337/aery-ai";
 
 const tools: Tool[] = [weatherTool, calculatorTool];
 const s = stream(model, { messages, tools });
 
 for await (const event of s) {
-  if (event.type === 'toolcall_end') {
-    const toolCall = event.toolCall;
-
-    try {
-      // Validate arguments against the tool's schema (throws on invalid args)
-      const validatedArgs = validateToolCall(tools, toolCall);
-      const result = await executeMyTool(toolCall.name, validatedArgs);
-      // ... add tool result to context
-    } catch (error) {
-      // Validation failed - return error as tool result so model can retry
-      context.messages.push({
-        role: 'toolResult',
-        toolCallId: toolCall.id,
-        toolName: toolCall.name,
-        content: [{ type: 'text', text: error.message }],
-        isError: true,
-        timestamp: Date.now()
-      });
-    }
-  }
+	if (event.type === "toolcall_end") {
+		const toolCall = event.toolCall;
+
+		try {
+			// Validate arguments against the tool's schema (throws on invalid args)
+			const validatedArgs = validateToolCall(tools, toolCall);
+			const result = await executeMyTool(toolCall.name, validatedArgs);
+			// ... add tool result to context
+		} catch (error) {
+			// Validation failed - return error as tool result so model can retry
+			context.messages.push({
+				role: "toolResult",
+				toolCallId: toolCall.id,
+				toolName: toolCall.name,
+				content: [{ type: "text", text: error.message }],
+				isError: true,
+				timestamp: Date.now(),
+			});
+		}
+	}
 }
 ```
 
@@ -372,123 +380,59 @@ for await (const event of s) {
 
 All streaming events emitted during assistant message generation:
 
-| Event Type | Description | Key Properties |
-|------------|-------------|----------------|
-| `start` | Stream begins | `partial`: Initial assistant message structure |
-| `text_start` | Text block starts | `contentIndex`: Position in content array |
-| `text_delta` | Text chunk received | `delta`: New text, `contentIndex`: Position |
-| `text_end` | Text block complete | `content`: Full text, `contentIndex`: Position |
-| `thinking_start` | Thinking block starts | `contentIndex`: Position in content array |
-| `thinking_delta` | Thinking chunk received | `delta`: New text, `contentIndex`: Position |
-| `thinking_end` | Thinking block complete | `content`: Full thinking, `contentIndex`: Position |
-| `toolcall_start` | Tool call begins | `contentIndex`: Position in content array |
-| `toolcall_delta` | Tool arguments streaming | `delta`: JSON chunk, `partial.content[contentIndex].arguments`: Partial parsed args |
-| `toolcall_end` | Tool call complete | `toolCall`: Complete validated tool call with `id`, `name`, `arguments` |
-| `done` | Stream complete | `reason`: Stop reason ("stop", "length", "toolUse"), `message`: Final assistant message |
-| `error` | Error occurred | `reason`: Error type ("error" or "aborted"), `error`: AssistantMessage with partial content |
-
-Streaming events for different content blocks are not guaranteed to be contiguous. Providers may emit deltas for text, thinking, and tool calls in the same upstream chunk, and pi may surface corresponding events interleaved, for example `text_start`, `text_delta`, `toolcall_start`, `text_delta`, `toolcall_delta`. Consumers must use `contentIndex` to associate each delta/end event with its block and must not assume that a block's `*_start`/`*_delta`/`*_end` sequence is uninterrupted by events for other blocks.
+| Event Type       | Description              | Key Properties                                                                              |
+| ---------------- | ------------------------ | ------------------------------------------------------------------------------------------- |
+| `start`          | Stream begins            | `partial`: Initial assistant message structure                                              |
+| `text_start`     | Text block starts        | `contentIndex`: Position in content array                                                   |
+| `text_delta`     | Text chunk received      | `delta`: New text, `contentIndex`: Position                                                 |
+| `text_end`       | Text block complete      | `content`: Full text, `contentIndex`: Position                                              |
+| `thinking_start` | Thinking block starts    | `contentIndex`: Position in content array                                                   |
+| `thinking_delta` | Thinking chunk received  | `delta`: New text, `contentIndex`: Position                                                 |
+| `thinking_end`   | Thinking block complete  | `content`: Full thinking, `contentIndex`: Position                                          |
+| `toolcall_start` | Tool call begins         | `contentIndex`: Position in content array                                                   |
+| `toolcall_delta` | Tool arguments streaming | `delta`: JSON chunk, `partial.content[contentIndex].arguments`: Partial parsed args         |
+| `toolcall_end`   | Tool call complete       | `toolCall`: Complete validated tool call with `id`, `name`, `arguments`                     |
+| `done`           | Stream complete          | `reason`: Stop reason ("stop", "length", "toolUse"), `message`: Final assistant message     |
+| `error`          | Error occurred           | `reason`: Error type ("error" or "aborted"), `error`: AssistantMessage with partial content |
 
 ## Image Input
 
 Models with vision capabilities can process images. You can check if a model supports images via the `input` property. If you pass images to a non-vision model, they are silently ignored.
 
 ```typescript
-import { readFileSync } from 'fs';
-import { getModel, complete } from '@aryee337/aery-ai';
+import * as fs from "node:fs";
+import { getModel, complete } from "@aryee337/aery-ai";
 
-const model = getModel('openai', 'gpt-4o-mini');
+const model = getModel("openai", "gpt-4o-mini");
 
 // Check if model supports images
-if (model.input.includes('image')) {
-  console.log('Model supports vision');
+if (model.input.includes("image")) {
+	console.log("Model supports vision");
 }
 
-const imageBuffer = readFileSync('image.png');
-const base64Image = imageBuffer.toString('base64');
+const imageBuffer = fs.readFileSync("image.png");
+const base64Image = imageBuffer.toBase64();
 
 const response = await complete(model, {
-  messages: [{
-    role: 'user',
-    content: [
-      { type: 'text', text: 'What is in this image?' },
-      { type: 'image', data: base64Image, mimeType: 'image/png' }
-    ]
-  }]
+	messages: [
+		{
+			role: "user",
+			content: [
+				{ type: "text", text: "What is in this image?" },
+				{ type: "image", data: base64Image, mimeType: "image/png" },
+			],
+		},
+	],
 });
 
 // Access the response
 for (const block of response.content) {
-  if (block.type === 'text') {
-    console.log(block.text);
-  }
-}
-```
-
-## Image Generation
-
-Image generation uses a separate API surface from text/chat generation. Use `getImageModel()` / `getImageModels()` / `getImageProviders()` to discover image-generation models, and `generateImages()` to get the final result.
-
-Do not use `stream()` or `complete()` for image generation. Image generation is a one-shot API: `generateImages()` waits for the provider response and returns the final `AssistantImages` result.
-
-### Basic Image Generation
-
-```typescript
-import { getImageModel, generateImages } from '@aryee337/aery-ai';
-
-const model = getImageModel('openrouter', 'google/gemini-2.5-flash-image');
-
-const result = await generateImages(model, {
-  input: [{ type: 'text', text: 'Generate a red circle on a plain white background.' }]
-}, {
-  apiKey: process.env.OPENROUTER_API_KEY
-});
-
-for (const block of result.output) {
-  if (block.type === 'text') {
-    console.log(block.text);
-  } else if (block.type === 'image') {
-    console.log(block.mimeType);
-    console.log(block.data.substring(0, 32));
-  }
+	if (block.type === "text") {
+		console.log(block.text);
+	}
 }
 ```
 
-Some models also support image input:
-
-```typescript
-import { readFileSync } from 'fs';
-
-const imageBuffer = readFileSync('input.png');
-const result = await generateImages(model, {
-  input: [
-    { type: 'text', text: 'Create a variation of this image with a blue background.' },
-    { type: 'image', data: imageBuffer.toString('base64'), mimeType: 'image/png' }
-  ]
-}, {
-  apiKey: process.env.OPENROUTER_API_KEY
-});
-```
-
-Check capabilities on the model metadata:
-
-```typescript
-console.log(model.input);   // ['text', 'image']
-console.log(model.output);  // ['image'] or ['image', 'text']
-```
-
-### Notes and Limitations
-
-- Use `getImageModel(...)`, not `getModel(...)`.
-- Use `generateImages()`, not `stream()` / `complete()`.
-- Image-generation models do not participate in tool calling.
-- Outputs are returned in `AssistantImages.output` and can include both base64-encoded `ImageContent` blocks and `TextContent` blocks.
-- Some models return only images, others return images plus text. Check `model.output`.
-- Some models accept image input, others are text-to-image only. Check `model.input`.
-- Like the streaming APIs, image generation supports options such as `apiKey`, `signal`, `headers`, `onPayload`, and `onResponse`, and results may include `stopReason`, `responseId`, and `usage`.
-- If you want a model to analyze images in a conversation or call tools, use the regular `stream()` / `complete()` APIs with a model that supports image input.
-- At the moment, image generation is available through only one provider, OpenRouter.
-
 ## Thinking/Reasoning
 
 Many models support thinking/reasoning capabilities where they can show their internal thought process. You can check if a model supports reasoning via the `reasoning` property. If you pass reasoning options to a non-reasoning model, they are silently ignored.
@@ -496,10 +440,10 @@ Many models support thinking/reasoning capabilities where they can show their in
 ### Unified Interface (streamSimple/completeSimple)
 
 ```typescript
-import { getModel, streamSimple, completeSimple } from '@aryee337/aery-ai';
+import { getModel, streamSimple, completeSimple } from "@aryee337/aery-ai";
 
 // Many models across providers support thinking/reasoning
-const model = getModel('anthropic', 'claude-sonnet-4-20250514');
+const model = getModel("anthropic", "claude-sonnet-4-20250514");
 // or getModel('openai', 'gpt-5-mini');
 // or getModel('google', 'gemini-2.5-flash');
 // or getModel('xai', 'grok-code-fast-1');
@@ -509,23 +453,27 @@ const model = getModel('anthropic', 'claude-sonnet-4-20250514');
 
 // Check if model supports reasoning
 if (model.reasoning) {
-  console.log('Model supports reasoning/thinking');
+	console.log("Model supports reasoning/thinking");
 }
 
 // Use the simplified reasoning option
-const response = await completeSimple(model, {
-  messages: [{ role: 'user', content: 'Solve: 2x + 5 = 13' }]
-}, {
-  reasoning: 'medium'  // 'minimal' | 'low' | 'medium' | 'high' | 'xhigh'
-});
+const response = await completeSimple(
+	model,
+	{
+		messages: [{ role: "user", content: "Solve: 2x + 5 = 13" }],
+	},
+	{
+		reasoning: "medium", // 'minimal' | 'low' | 'medium' | 'high' | 'xhigh' (xhigh maps to high on non-OpenAI providers)
+	}
+);
 
 // Access thinking and text blocks
 for (const block of response.content) {
-  if (block.type === 'thinking') {
-    console.log('Thinking:', block.thinking);
-  } else if (block.type === 'text') {
-    console.log('Response:', block.text);
-  }
+	if (block.type === "thinking") {
+		console.log("Thinking:", block.thinking);
+	} else if (block.type === "text") {
+		console.log("Response:", block.text);
+	}
 }
 ```
 
@@ -534,29 +482,29 @@ for (const block of response.content) {
 For fine-grained control, use the provider-specific options:
 
 ```typescript
-import { getModel, complete } from '@aryee337/aery-ai';
+import { getModel, complete } from "@aryee337/aery-ai";
 
 // OpenAI Reasoning (o1, o3, gpt-5)
-const openaiModel = getModel('openai', 'gpt-5-mini');
+const openaiModel = getModel("openai", "gpt-5-mini");
 await complete(openaiModel, context, {
-  reasoningEffort: 'medium',
-  reasoningSummary: 'detailed'  // OpenAI Responses API only
+	reasoningEffort: "medium",
+	reasoningSummary: "detailed", // OpenAI Responses API only
 });
 
 // Anthropic Thinking (Claude Sonnet 4)
-const anthropicModel = getModel('anthropic', 'claude-sonnet-4-20250514');
+const anthropicModel = getModel("anthropic", "claude-sonnet-4-20250514");
 await complete(anthropicModel, context, {
-  thinkingEnabled: true,
-  thinkingBudgetTokens: 8192  // Optional token limit
+	thinkingEnabled: true,
+	thinkingBudgetTokens: 8192, // Optional token limit
 });
 
 // Google Gemini Thinking
-const googleModel = getModel('google', 'gemini-2.5-flash');
+const googleModel = getModel("google", "gemini-2.5-flash");
 await complete(googleModel, context, {
-  thinking: {
-    enabled: true,
-    budgetTokens: 8192  // -1 for dynamic, 0 to disable
-  }
+	thinking: {
+		enabled: true,
+		budgetTokens: 8192, // -1 for dynamic, 0 to disable
+	},
 });
 ```
 
@@ -565,20 +513,20 @@ await complete(googleModel, context, {
 When streaming, thinking content is delivered through specific events:
 
 ```typescript
-const s = streamSimple(model, context, { reasoning: 'high' });
+const s = streamSimple(model, context, { reasoning: "high" });
 
 for await (const event of s) {
-  switch (event.type) {
-    case 'thinking_start':
-      console.log('[Model started thinking]');
-      break;
-    case 'thinking_delta':
-      process.stdout.write(event.delta);  // Stream thinking content
-      break;
-    case 'thinking_end':
-      console.log('\n[Thinking complete]');
-      break;
-  }
+	switch (event.type) {
+		case "thinking_start":
+			console.log("[Model started thinking]");
+			break;
+		case "thinking_delta":
+			process.stdout.write(event.delta); // Stream thinking content
+			break;
+		case "thinking_end":
+			console.log("\n[Thinking complete]");
+			break;
+	}
 }
 ```
 
@@ -592,8 +540,6 @@ Every `AssistantMessage` includes a `stopReason` field that indicates how the ge
 - `"error"` - An error occurred during generation
 - `"aborted"` - Request was cancelled via abort signal
 
-`AssistantMessage` may also include `responseId`, a provider-specific upstream response or message identifier when the underlying API exposes one. Do not assume it is always present across providers.
-
 ## Error Handling
 
 When a request ends with an error (including aborts and tool call validation errors), the streaming API emits an error event:
@@ -601,20 +547,20 @@ When a request ends with an error (including aborts and tool call validation err
 ```typescript
 // In streaming
 for await (const event of stream) {
-  if (event.type === 'error') {
-    // event.reason is either "error" or "aborted"
-    // event.error is the AssistantMessage with partial content
-    console.error(`Error (${event.reason}):`, event.error.errorMessage);
-    console.log('Partial content:', event.error.content);
-  }
+	if (event.type === "error") {
+		// event.reason is either "error" or "aborted"
+		// event.error is the AssistantMessage with partial content
+		console.error(`Error (${event.reason}):`, event.error.errorMessage);
+		console.log("Partial content:", event.error.content);
+	}
 }
 
 // The final message will have the error details
 const message = await stream.result();
-if (message.stopReason === 'error' || message.stopReason === 'aborted') {
-  console.error('Request failed:', message.errorMessage);
-  // message.content contains any partial content received before the error
-  // message.usage contains partial token counts and costs
+if (message.stopReason === "error" || message.stopReason === "aborted") {
+	console.error("Request failed:", message.errorMessage);
+	// message.content contains any partial content received before the error
+	// message.usage contains partial token counts and costs
 }
 ```
 
@@ -623,35 +569,38 @@ if (message.stopReason === 'error' || message.stopReason === 'aborted') {
 The abort signal allows you to cancel in-progress requests. Aborted requests have `stopReason === 'aborted'`:
 
 ```typescript
-import { getModel, stream } from '@aryee337/aery-ai';
+import { getModel, stream } from "@aryee337/aery-ai";
 
-const model = getModel('openai', 'gpt-4o-mini');
-const controller = new AbortController();
+const model = getModel("openai", "gpt-4o-mini");
 
 // Abort after 2 seconds
-setTimeout(() => controller.abort(), 2000);
-
-const s = stream(model, {
-  messages: [{ role: 'user', content: 'Write a long story' }]
-}, {
-  signal: controller.signal
-});
+const signal = AbortSignal.timeout(2000);
+
+const s = stream(
+	model,
+	{
+		messages: [{ role: "user", content: "Write a long story" }],
+	},
+	{
+		signal,
+	}
+);
 
 for await (const event of s) {
-  if (event.type === 'text_delta') {
-    process.stdout.write(event.delta);
-  } else if (event.type === 'error') {
-    // event.reason tells you if it was "error" or "aborted"
-    console.log(`${event.reason === 'aborted' ? 'Aborted' : 'Error'}:`, event.error.errorMessage);
-  }
+	if (event.type === "text_delta") {
+		process.stdout.write(event.delta);
+	} else if (event.type === "error") {
+		// event.reason tells you if it was "error" or "aborted"
+		console.log(`${event.reason === "aborted" ? "Aborted" : "Error"}:`, event.error.errorMessage);
+	}
 }
 
 // Get results (may be partial if aborted)
 const response = await s.result();
-if (response.stopReason === 'aborted') {
-  console.log('Request was aborted:', response.errorMessage);
-  console.log('Partial content received:', response.content);
-  console.log('Tokens used:', response.usage);
+if (response.stopReason === "aborted") {
+	console.log("Request was aborted:", response.errorMessage);
+	console.log("Partial content received:", response.content);
+	console.log("Tokens used:", response.usage);
 }
 ```
 
@@ -661,9 +610,7 @@ Aborted messages can be added to the conversation context and continued in subse
 
 ```typescript
 const context = {
-  messages: [
-    { role: 'user', content: 'Explain quantum computing in detail' }
-  ]
+	messages: [{ role: "user", content: "Explain quantum computing in detail" }],
 };
 
 // First request gets aborted after 2 seconds
@@ -674,278 +621,168 @@ const partial = await complete(model, context, { signal: controller1.signal });
 
 // Add the partial response to context
 context.messages.push(partial);
-context.messages.push({ role: 'user', content: 'Please continue' });
+context.messages.push({ role: "user", content: "Please continue" });
 
 // Continue the conversation
 const continuation = await complete(model, context);
 ```
 
-### Debugging Provider Payloads
+### Common Stream Options
+
+All providers accept the base `StreamOptions` (in addition to provider-specific options):
 
-Use the `onPayload` callback to inspect the request payload sent to the provider. This is useful for debugging request formatting issues or provider validation errors.
+- `apiKey`: Override the provider API key
+- `headers`: Extra request headers merged on top of model-defined headers
+- `sessionId`: Provider-specific session identifier (prompt caching/routing)
+- `signal`: Abort in-flight requests
+- `onPayload`: Callback invoked with the provider request payload just before sending
+
+Example:
 
 ```typescript
 const response = await complete(model, context, {
-  onPayload: (payload) => {
-    console.log('Provider payload:', JSON.stringify(payload, null, 2));
-  }
+	apiKey: "sk-live",
+	headers: { "X-Debug-Trace": "true" },
+	onPayload: (payload) => {
+		console.log("request payload", payload);
+	},
 });
 ```
 
-The callback is supported by `stream`, `complete`, `streamSimple`, and `completeSimple`.
-
 ## APIs, Models, and Providers
 
-The library uses a registry of API implementations. Built-in APIs include:
-
-- **`anthropic-messages`**: Anthropic Messages API (`streamAnthropic`, `AnthropicOptions`)
-- **`google-generative-ai`**: Google Generative AI API (`streamGoogle`, `GoogleOptions`)
-- **`google-vertex`**: Google Vertex AI API (`streamGoogleVertex`, `GoogleVertexOptions`)
-- **`mistral-conversations`**: Mistral Conversations API (`streamMistral`, `MistralOptions`)
-- **`openai-completions`**: OpenAI Chat Completions API (`streamOpenAICompletions`, `OpenAICompletionsOptions`)
-- **`openai-responses`**: OpenAI Responses API (`streamOpenAIResponses`, `OpenAIResponsesOptions`)
-- **`openai-codex-responses`**: OpenAI Codex Responses API (`streamOpenAICodexResponses`, `OpenAICodexResponsesOptions`)
-- **`azure-openai-responses`**: Azure OpenAI Responses API (`streamAzureOpenAIResponses`, `AzureOpenAIResponsesOptions`)
-- **`bedrock-converse-stream`**: Amazon Bedrock Converse API (`streamBedrock`, `BedrockOptions`)
-
-### Faux provider for tests
-
-`registerFauxProvider()` registers a temporary in-memory provider for tests and demos. It is opt-in and not part of the built-in provider set.
-
-```typescript
-import {
-  complete,
-  fauxAssistantMessage,
-  fauxText,
-  fauxThinking,
-  fauxToolCall,
-  registerFauxProvider,
-  stream,
-} from '@aryee337/aery-ai';
-
-const registration = registerFauxProvider({
-  tokensPerSecond: 50 // optional
-});
-
-const model = registration.getModel();
-const context = {
-  messages: [{ role: 'user', content: 'Summarize package.json and then call echo', timestamp: Date.now() }]
-};
-
-registration.setResponses([
-  fauxAssistantMessage([
-    fauxThinking('Need to inspect package metadata first.'),
-    fauxToolCall('echo', { text: 'package.json' })
-  ], { stopReason: 'toolUse' })
-]);
+The library implements 4 API interfaces, each with its own streaming function and options:
 
-const first = await complete(model, context, {
-  sessionId: 'session-1',
-  cacheRetention: 'short'
-});
-context.messages.push(first);
-
-context.messages.push({
-  role: 'toolResult',
-  toolCallId: first.content.find((block) => block.type === 'toolCall')!.id,
-  toolName: 'echo',
-  content: [{ type: 'text', text: 'package.json contents here' }],
-  isError: false,
-  timestamp: Date.now()
-});
-
-registration.setResponses([
-  fauxAssistantMessage([
-    fauxThinking('Now I can summarize the tool output.'),
-    fauxText('Here is the summary.')
-  ])
-]);
-
-const s = stream(model, context);
-for await (const event of s) {
-  console.log(event.type);
-}
-
-// Optional: register multiple faux models for model-switching tests
-const multiModel = registerFauxProvider({
-  models: [
-    { id: 'faux-fast', reasoning: false },
-    { id: 'faux-thinker', reasoning: true }
-  ]
-});
-const thinker = multiModel.getModel('faux-thinker');
-
-console.log(thinker?.reasoning);
-console.log(registration.getPendingResponseCount());
-console.log(registration.state.callCount);
-registration.unregister();
-multiModel.unregister();
-```
-
-Notes:
-- Responses are consumed from a queue in request start order.
-- If the queue is empty, the faux provider returns an assistant error message with `errorMessage: "No more faux responses queued"`.
-- Use `registration.setResponses([...])` to replace the remaining queue and `registration.appendResponses([...])` to add more responses.
-- `registration.models` exposes all registered faux models. `registration.getModel()` returns the first one, and `registration.getModel(id)` returns a specific one.
-- Use `fauxAssistantMessage(...)` for scripted assistant replies. Use `fauxText(...)`, `fauxThinking(...)`, and `fauxToolCall(...)` to build content blocks without filling in low-level fields manually.
-- `registration.unregister()` removes the temporary provider from the global API registry.
-- Usage is estimated at roughly 1 token per 4 characters. When `sessionId` is present and `cacheRetention` is not `"none"`, prompt cache reads and writes are simulated automatically.
-- Tool call arguments stream incrementally via `toolcall_delta` chunks.
-- By default, each streamed chunk is emitted on its own microtask. Set `tokensPerSecond` to pace chunk delivery in real time.
-- The intended use is one deterministic scripted flow per registration. If you need independent concurrent flows, register separate faux providers.
+- **`anthropic-messages`**: Anthropic's Messages API (`streamAnthropic`, `AnthropicOptions`)
+- **`google-generative-ai`**: Google's Generative AI API (`streamGoogle`, `GoogleOptions`)
+- **`openai-completions`**: OpenAI's Chat Completions API (`streamOpenAICompletions`, `OpenAICompletionsOptions`)
+- **`openai-responses`**: OpenAI's Responses API (`streamOpenAIResponses`, `OpenAIResponsesOptions`)
 
 ### Providers and Models
 
 A **provider** offers models through a specific API. For example:
+
 - **Anthropic** models use the `anthropic-messages` API
 - **Google** models use the `google-generative-ai` API
 - **OpenAI** models use the `openai-responses` API
-- **Mistral** models use the `mistral-conversations` API
-- **xAI, Cerebras, Groq, Together AI, etc.** models use the `openai-completions` API (OpenAI-compatible)
+- **Mistral, xAI, Cerebras, Groq, etc.** models use the `openai-completions` API (OpenAI-compatible)
 
 ### Querying Providers and Models
 
 ```typescript
-import { getProviders, getModels, getModel } from '@aryee337/aery-ai';
+import { getProviders, getModels, getModel } from "@aryee337/aery-ai";
 
 // Get all available providers
 const providers = getProviders();
 console.log(providers); // ['openai', 'anthropic', 'google', 'xai', 'groq', ...]
 
 // Get all models from a provider (fully typed)
-const anthropicModels = getModels('anthropic');
+const anthropicModels = getModels("anthropic");
 for (const model of anthropicModels) {
-  console.log(`${model.id}: ${model.name}`);
-  console.log(`  API: ${model.api}`); // 'anthropic-messages'
-  console.log(`  Context: ${model.contextWindow} tokens`);
-  console.log(`  Vision: ${model.input.includes('image')}`);
-  console.log(`  Reasoning: ${model.reasoning}`);
+	console.log(`${model.id}: ${model.name}`);
+	console.log(`  API: ${model.api}`); // 'anthropic-messages'
+	console.log(`  Context: ${model.contextWindow} tokens`);
+	console.log(`  Vision: ${model.input.includes("image")}`);
+	console.log(`  Reasoning: ${model.reasoning}`);
 }
 
 // Get a specific model (both provider and model ID are auto-completed in IDEs)
-const model = getModel('openai', 'gpt-4o-mini');
+const model = getModel("openai", "gpt-4o-mini");
 console.log(`Using ${model.name} via ${model.api} API`);
 ```
 
 ### Custom Models
 
-You can create custom models for local inference servers or custom endpoints:
+You can create custom models for local inference servers or custom endpoints.
+
+For local Ollama, `OLLAMA_API_KEY` is optional and mainly needed for authenticated/self-hosted gateways. `ollama` remains the local OpenAI-compatible runtime integration.
 
 ```typescript
-import { Model, stream } from '@aryee337/aery-ai';
-
-// Example: Ollama using OpenAI-compatible API
-const ollamaModel: Model<'openai-completions'> = {
-  id: 'llama-3.1-8b',
-  name: 'Llama 3.1 8B (Ollama)',
-  api: 'openai-completions',
-  provider: 'ollama',
-  baseUrl: 'http://localhost:11434/v1',
-  reasoning: false,
-  input: ['text'],
-  cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
-  contextWindow: 128000,
-  maxTokens: 32000
+import { Model, stream } from "@aryee337/aery-ai";
+
+// Example: local Ollama using the OpenAI-compatible API
+const ollamaModel: Model<"openai-completions"> = {
+	id: "llama-3.1-8b",
+	name: "Llama 3.1 8B (Ollama)",
+	api: "openai-completions",
+	provider: "ollama",
+	baseUrl: "http://localhost:11434/v1",
+	reasoning: false,
+	input: ["text"],
+	cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
+	contextWindow: 128000,
+	maxTokens: 32000,
 };
 
-// Example: LiteLLM proxy with explicit compat settings
-const litellmModel: Model<'openai-completions'> = {
-  id: 'gpt-4o',
-  name: 'GPT-4o (via LiteLLM)',
-  api: 'openai-completions',
-  provider: 'litellm',
-  baseUrl: 'http://localhost:4000/v1',
-  reasoning: false,
-  input: ['text', 'image'],
-  cost: { input: 2.5, output: 10, cacheRead: 0, cacheWrite: 0 },
-  contextWindow: 128000,
-  maxTokens: 16384,
-  compat: {
-    supportsStore: false,  // LiteLLM doesn't support the store field
-  }
-};
+const localResponse = await stream(ollamaModel, context, {
+	apiKey: process.env.OLLAMA_API_KEY, // Optional; local Ollama usually runs without auth
+});
 
-// Example: Custom endpoint with headers (bypassing Cloudflare bot detection)
-const proxyModel: Model<'anthropic-messages'> = {
-  id: 'claude-sonnet-4',
-  name: 'Claude Sonnet 4 (Proxied)',
-  api: 'anthropic-messages',
-  provider: 'custom-proxy',
-  baseUrl: 'https://proxy.example.com/v1',
-  reasoning: true,
-  input: ['text', 'image'],
-  cost: { input: 3, output: 15, cacheRead: 0.3, cacheWrite: 3.75 },
-  contextWindow: 200000,
-  maxTokens: 8192,
-  headers: {
-    'User-Agent': 'Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36',
-    'X-Custom-Auth': 'bearer-token-here'
-  }
+// Example: Ollama Cloud using the native /api/chat transport
+const ollamaCloudModel: Model<"ollama-chat"> = {
+	id: "gpt-oss:120b",
+	name: "GPT OSS 120B (Ollama Cloud)",
+	api: "ollama-chat",
+	provider: "ollama-cloud",
+	baseUrl: "https://ollama.com",
+	reasoning: true,
+	input: ["text", "image"],
+	cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
+	contextWindow: 262144,
+	maxTokens: 8192,
 };
 
-// Use the custom model
-const response = await stream(ollamaModel, context, {
-  apiKey: 'dummy' // Ollama doesn't need a real key
+const cloudResponse = await stream(ollamaCloudModel, context, {
+	apiKey: process.env.OLLAMA_CLOUD_API_KEY,
 });
-```
 
-Some OpenAI-compatible servers do not understand the `developer` role used for reasoning-capable models. For those providers, set `compat.supportsDeveloperRole` to `false` so the system prompt is sent as a `system` message instead. If the server also does not support `reasoning_effort`, set `compat.supportsReasoningEffort` to `false` too.
-
-Use model-level `thinkingLevelMap` to describe model-specific thinking controls. Keys are thinking levels (`off`, `minimal`, `low`, `medium`, `high`, `xhigh`). Missing keys use provider defaults, string values are sent to the provider, and `null` marks a level unsupported.
-
-This commonly applies to Ollama, vLLM, SGLang, and similar OpenAI-compatible servers. You can set `compat` at the provider level or per model.
+// Example: LiteLLM proxy with explicit compat settings
+const litellmModel: Model<"openai-completions"> = {
+	id: "gpt-4o",
+	name: "GPT-4o (via LiteLLM)",
+	api: "openai-completions",
+	provider: "litellm",
+	baseUrl: "http://localhost:4000/v1",
+	reasoning: false,
+	input: ["text", "image"],
+	cost: { input: 2.5, output: 10, cacheRead: 0, cacheWrite: 0 },
+	contextWindow: 128000,
+	maxTokens: 16384,
+	compat: {
+		supportsStore: false, // LiteLLM doesn't support the store field
+	},
+};
 
-```typescript
-const ollamaReasoningModel: Model<'openai-completions'> = {
-  id: 'gpt-oss:20b',
-  name: 'GPT-OSS 20B (Ollama)',
-  api: 'openai-completions',
-  provider: 'ollama',
-  baseUrl: 'http://localhost:11434/v1',
-  reasoning: true,
-  input: ['text'],
-  cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
-  contextWindow: 131072,
-  maxTokens: 32000,
-  thinkingLevelMap: {
-    minimal: null,
-    low: null,
-    medium: null,
-    high: 'high',
-    xhigh: null,
-  },
-  compat: {
-    supportsDeveloperRole: false,
-    supportsReasoningEffort: false,
-  }
+// Example: Custom endpoint with headers (bypassing Cloudflare bot detection)
+const proxyModel: Model<"anthropic-messages"> = {
+	id: "claude-sonnet-4",
+	name: "Claude Sonnet 4 (Proxied)",
+	api: "anthropic-messages",
+	provider: "custom-proxy",
+	baseUrl: "https://proxy.example.com/v1",
+	reasoning: true,
+	input: ["text", "image"],
+	cost: { input: 3, output: 15, cacheRead: 0.3, cacheWrite: 3.75 },
+	contextWindow: 200000,
+	maxTokens: 8192,
+	headers: {
+		"User-Agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36",
+		"X-Custom-Auth": "bearer-token-here",
+	},
 };
 ```
 
 ### OpenAI Compatibility Settings
 
-The `openai-completions` API is implemented by many providers with minor differences. By default, the library auto-detects compatibility settings based on `baseUrl` for a small set of known OpenAI-compatible providers (Cerebras, xAI, Chutes, DeepSeek, Together AI, zAi, OpenCode, Cloudflare Workers AI, etc.). For custom proxies or unknown endpoints, you can override these settings via the `compat` field. For `openai-responses` models, the compat field only supports Responses-specific flags.
+The `openai-completions` API is implemented by many providers with minor differences. By default, the library auto-detects compatibility settings based on `baseUrl` for known providers (Cerebras, xAI, Mistral, Chutes, etc.). For custom proxies or unknown endpoints, you can override these settings via the `compat` field:
 
 ```typescript
-interface OpenAICompletionsCompat {
-  supportsStore?: boolean;           // Whether provider supports the `store` field (default: true)
-  supportsDeveloperRole?: boolean;   // Whether provider supports `developer` role vs `system` (default: true)
-  supportsReasoningEffort?: boolean; // Whether provider supports `reasoning_effort` (default: true)
-  supportsUsageInStreaming?: boolean; // Whether provider supports `stream_options: { include_usage: true }` (default: true)
-  supportsStrictMode?: boolean;      // Whether provider supports `strict` in tool definitions (default: true)
-  sendSessionAffinityHeaders?: boolean; // Whether to send `session_id`, `x-client-request-id`, and `x-session-affinity` from `sessionId` when caching is enabled (default: false)
-  maxTokensField?: 'max_completion_tokens' | 'max_tokens';  // Which field name to use (default: max_completion_tokens)
-  requiresToolResultName?: boolean;  // Whether tool results require the `name` field (default: false)
-  requiresAssistantAfterToolResult?: boolean; // Whether tool results must be followed by an assistant message (default: false)
-  requiresThinkingAsText?: boolean;  // Whether thinking blocks must be converted to text (default: false)
-  requiresReasoningContentOnAssistantMessages?: boolean; // Whether all replayed assistant messages must include empty reasoning_content when reasoning is enabled (default: auto-detected for DeepSeek)
-  thinkingFormat?: 'openai' | 'openrouter' | 'deepseek' | 'together' | 'zai' | 'qwen' | 'qwen-chat-template'; // Format for reasoning param: 'openai' uses reasoning_effort, 'openrouter' uses reasoning: { effort }, 'deepseek' uses thinking: { type } plus reasoning_effort, 'together' uses reasoning: { enabled } plus reasoning_effort when supported, 'zai' uses enable_thinking, 'qwen' uses enable_thinking, 'qwen-chat-template' uses chat_template_kwargs.enable_thinking (default: openai)
-  cacheControlFormat?: 'anthropic';  // Anthropic-style cache_control on system prompt, last tool, and last user/assistant text content
-  openRouterRouting?: OpenRouterRouting; // OpenRouter routing preferences (default: {})
-  vercelGatewayRouting?: VercelGatewayRouting; // Vercel AI Gateway routing preferences (default: {})
-}
-
-interface OpenAIResponsesCompat {
-  // Reserved for future use
+interface OpenAICompat {
+	supportsStore?: boolean; // Whether provider supports the `store` field (default: true)
+	supportsDeveloperRole?: boolean; // Whether provider supports `developer` role vs `system` (default: true)
+	supportsReasoningEffort?: boolean; // Whether provider supports `reasoning_effort` (default: true)
+	maxTokensField?: "max_completion_tokens" | "max_tokens"; // Which field name to use (default: max_completion_tokens)
+	extraBody?: Record<string, unknown>; // Extra request-body fields for custom proxy routing or provider-specific options
 }
 ```
 
@@ -957,20 +794,18 @@ If `compat` is not set, the library falls back to URL-based detection. If `compa
 
 ### Type Safety
 
-Models are typed by their API, which keeps the model metadata accurate. Provider-specific option types are enforced when you call the provider functions directly. The generic `stream` and `complete` functions accept `StreamOptions` with additional provider fields.
+Models are typed by their API, ensuring type-safe options:
 
 ```typescript
-import { streamAnthropic, type AnthropicOptions } from '@aryee337/aery-ai';
-
 // TypeScript knows this is an Anthropic model
-const claude = getModel('anthropic', 'claude-sonnet-4-20250514');
-
-const options: AnthropicOptions = {
-  thinkingEnabled: true,
-  thinkingBudgetTokens: 2048
-};
+const claude = getModel("anthropic", "claude-sonnet-4-20250514");
 
-await streamAnthropic(claude, context, options);
+// So these options are type-checked for AnthropicOptions
+await stream(claude, context, {
+	thinkingEnabled: true, // ✓ Valid for anthropic-messages
+	thinkingBudgetTokens: 2048, // ✓ Valid for anthropic-messages
+	// reasoningEffort: 'high'  // ✗ TypeScript error: not valid for anthropic-messages
+});
 ```
 
 ## Cross-Provider Handoffs
@@ -989,41 +824,43 @@ When messages from one provider are sent to a different provider, the library au
 ### Example: Multi-Provider Conversation
 
 ```typescript
-import { getModel, complete, Context } from '@aryee337/aery-ai';
+import { getModel, complete, Context } from "@aryee337/aery-ai";
 
 // Start with Claude
-const claude = getModel('anthropic', 'claude-sonnet-4-20250514');
+const claude = getModel("anthropic", "claude-sonnet-4-20250514");
 const context: Context = {
-  messages: []
+	messages: [],
 };
 
-context.messages.push({ role: 'user', content: 'What is 25 * 18?' });
+context.messages.push({ role: "user", content: "What is 25 * 18?" });
 const claudeResponse = await complete(claude, context, {
-  thinkingEnabled: true
+	thinkingEnabled: true,
 });
 context.messages.push(claudeResponse);
 
 // Switch to GPT-5 - it will see Claude's thinking as <thinking> tagged text
-const gpt5 = getModel('openai', 'gpt-5-mini');
-context.messages.push({ role: 'user', content: 'Is that calculation correct?' });
+const gpt5 = getModel("openai", "gpt-5-mini");
+context.messages.push({ role: "user", content: "Is that calculation correct?" });
 const gptResponse = await complete(gpt5, context);
 context.messages.push(gptResponse);
 
 // Switch to Gemini
-const gemini = getModel('google', 'gemini-2.5-flash');
-context.messages.push({ role: 'user', content: 'What was the original question?' });
+const gemini = getModel("google", "gemini-2.5-flash");
+context.messages.push({ role: "user", content: "What was the original question?" });
 const geminiResponse = await complete(gemini, context);
 ```
 
 ### Provider Compatibility
 
 All providers can handle messages from other providers, including:
+
 - Text content
 - Tool calls and tool results (including images in tool results)
 - Thinking/reasoning blocks (transformed to tagged text for cross-provider compatibility)
 - Aborted messages with partial content
 
 This enables flexible workflows where you can:
+
 - Start with a fast model for initial responses
 - Switch to a more capable model for complex reasoning
 - Use specialized models for specific tasks
@@ -1034,33 +871,31 @@ This enables flexible workflows where you can:
 The `Context` object can be easily serialized and deserialized using standard JSON methods, making it simple to persist conversations, implement chat history, or transfer contexts between services:
 
 ```typescript
-import { Context, getModel, complete } from '@aryee337/aery-ai';
+import { Context, getModel, complete } from "@aryee337/aery-ai";
 
 // Create and use a context
 const context: Context = {
-  systemPrompt: 'You are a helpful assistant.',
-  messages: [
-    { role: 'user', content: 'What is TypeScript?' }
-  ]
+	systemPrompt: ["You are a helpful assistant."],
+	messages: [{ role: "user", content: "What is TypeScript?" }],
 };
 
-const model = getModel('openai', 'gpt-4o-mini');
+const model = getModel("openai", "gpt-4o-mini");
 const response = await complete(model, context);
 context.messages.push(response);
 
 // Serialize the entire context
 const serialized = JSON.stringify(context);
-console.log('Serialized context size:', serialized.length, 'bytes');
+console.log("Serialized context size:", serialized.length, "bytes");
 
 // Save to database, localStorage, file, etc.
-localStorage.setItem('conversation', serialized);
+localStorage.setItem("conversation", serialized);
 
 // Later: deserialize and continue the conversation
-const restored: Context = JSON.parse(localStorage.getItem('conversation')!);
-restored.messages.push({ role: 'user', content: 'Tell me more about its type system' });
+const restored: Context = JSON.parse(localStorage.getItem("conversation")!);
+restored.messages.push({ role: "user", content: "Tell me more about its type system" });
 
 // Continue with any model
-const newModel = getModel('anthropic', 'claude-3-5-haiku-20241022');
+const newModel = getModel("anthropic", "claude-haiku-4-5-20251001");
 const continuation = await complete(newModel, restored);
 ```
 
@@ -1071,100 +906,127 @@ const continuation = await complete(newModel, restored);
 The library supports browser environments. You must pass the API key explicitly since environment variables are not available in browsers:
 
 ```typescript
-import { getModel, complete } from '@aryee337/aery-ai';
+import { getModel, complete } from "@aryee337/aery-ai";
 
 // API key must be passed explicitly in browser
-const model = getModel('anthropic', 'claude-3-5-haiku-20241022');
-
-const response = await complete(model, {
-  messages: [{ role: 'user', content: 'Hello!' }]
-}, {
-  apiKey: 'your-api-key'
-});
+const model = getModel("anthropic", "claude-haiku-4-5-20251001");
+
+const response = await complete(
+	model,
+	{
+		messages: [{ role: "user", content: "Hello!" }],
+	},
+	{
+		apiKey: "your-api-key",
+	}
+);
 ```
 
 > **Security Warning**: Exposing API keys in frontend code is dangerous. Anyone can extract and abuse your keys. Only use this approach for internal tools or demos. For production applications, use a backend proxy that keeps your API keys secure.
 
-### Browser Compatibility Notes
-
-- Amazon Bedrock (`bedrock-converse-stream`) is not supported in browser environments.
-- OAuth login flows are not supported in browser environments. Use the `@aryee337/aery-ai/oauth` entry point in Node.js.
-- In browser builds, Bedrock can still appear in model lists. Calls to Bedrock models fail at runtime.
-- Use a server-side proxy or backend service if you need Bedrock or OAuth-based auth from a web app.
-
 ### Environment Variables (Node.js only)
 
 In Node.js environments, you can set environment variables to avoid passing API keys:
 
-| Provider | Environment Variable(s) |
-|----------|------------------------|
-| OpenAI | `OPENAI_API_KEY` |
-| Azure OpenAI | `AZURE_OPENAI_API_KEY` + `AZURE_OPENAI_BASE_URL` (e.g. `https://{resource}.openai.azure.com`) or `AZURE_OPENAI_RESOURCE_NAME`. Supports `*.openai.azure.com` and `*.cognitiveservices.azure.com`; root endpoints auto-normalize to `/openai/v1`. Optional: `AZURE_OPENAI_AAERY_VERSION` (default `v1`), `AZURE_OPENAI_DEPLOYMENT_NAME_MAP`. |
-| Anthropic | `ANTHROPIC_API_KEY` or `ANTHROPIC_OAUTH_TOKEN` |
-| DeepSeek | `DEEPSEEK_API_KEY` |
-| Google | `GEMINI_API_KEY` |
-| Vertex AI | `GOOGLE_CLOUD_API_KEY` or `GOOGLE_CLOUD_PROJECT` (or `GCLOUD_PROJECT`) + `GOOGLE_CLOUD_LOCATION` + ADC |
-| Mistral | `MISTRAL_API_KEY` |
-| Groq | `GROQ_API_KEY` |
-| Cerebras | `CEREBRAS_API_KEY` |
-| Cloudflare AI Gateway | `CLOUDFLARE_API_KEY` + `CLOUDFLARE_ACCOUNT_ID` + `CLOUDFLARE_GATEWAY_ID` |
-| Cloudflare Workers AI | `CLOUDFLARE_API_KEY` + `CLOUDFLARE_ACCOUNT_ID` |
-| xAI | `XAI_API_KEY` |
-| Fireworks | `FIREWORKS_API_KEY` |
-| Together AI | `TOGETHER_API_KEY` |
-| OpenRouter | `OPENROUTER_API_KEY` |
-| Vercel AI Gateway | `AI_GATEWAY_API_KEY` |
-| zAI | `ZAI_API_KEY` |
-| MiniMax | `MINIMAX_API_KEY` |
-| OpenCode Zen / OpenCode Go | `OPENCODE_API_KEY` |
-| Kimi For Coding | `KIMI_API_KEY` |
-| Xiaomi MiMo (API billing) | `XIAOMI_API_KEY` |
-| Xiaomi MiMo Token Plan (China) | `XIAOMI_TOKEN_PLAN_CN_API_KEY` |
-| Xiaomi MiMo Token Plan (Amsterdam) | `XIAOMI_TOKEN_PLAN_AMS_API_KEY` |
-| Xiaomi MiMo Token Plan (Singapore) | `XIAOMI_TOKEN_PLAN_SGP_API_KEY` |
-| GitHub Copilot | `COPILOT_GITHUB_TOKEN` |
-
+| Provider       | Environment Variable(s)                                                      |
+| -------------- | ---------------------------------------------------------------------------- |
+| OpenAI         | `OPENAI_API_KEY`                                                             |
+| Anthropic      | `ANTHROPIC_API_KEY` or `ANTHROPIC_OAUTH_TOKEN` (or `ANTHROPIC_FOUNDRY_API_KEY` when `CLAUDE_CODE_USE_FOUNDRY=true`) |
+| Google         | `GEMINI_API_KEY`                                                             |
+| Vertex AI      | `GOOGLE_CLOUD_PROJECT` (or `GCLOUD_PROJECT`) + `GOOGLE_CLOUD_LOCATION` + ADC |
+| Mistral        | `MISTRAL_API_KEY`                                                            |
+| Groq           | `GROQ_API_KEY`                                                               |
+| Cerebras       | `CEREBRAS_API_KEY`                                                           |
+| Together       | `TOGETHER_API_KEY`                                                           |
+| Qianfan        | `QIANFAN_API_KEY`                                                            |
+| Hugging Face   | `HUGGINGFACE_HUB_TOKEN` or `HF_TOKEN`                                        |
+| Synthetic      | `SYNTHETIC_API_KEY`                                                          |
+| NVIDIA         | `NVIDIA_API_KEY`                                                             |
+| NanoGPT        | `NANO_GPT_API_KEY`                                                          |
+| Venice         | `VENICE_API_KEY`                                                             |
+| Moonshot       | `MOONSHOT_API_KEY`                                                           |
+| xAI            | `XAI_API_KEY`                                                                |
+| OpenRouter     | `OPENROUTER_API_KEY`                                                         |
+| LiteLLM        | `LITELLM_API_KEY`                                                            |
+| Ollama         | `OLLAMA_API_KEY` (optional for local deployments)                            |
+| Ollama Cloud   | `OLLAMA_CLOUD_API_KEY`                                                     |
+| Qwen Portal    | `QWEN_OAUTH_TOKEN` or `QWEN_PORTAL_API_KEY`                                  |
+| zAI            | `ZAI_API_KEY`                                                                |
+| MiniMax Code   | `MINIMAX_CODE_API_KEY` (international) or `MINIMAX_CODE_CN_API_KEY` (China) |
+| Xiaomi MiMo    | `XIAOMI_API_KEY`                                                             |
+| ZenMux         | `ZENMUX_API_KEY`                                                             |
+| vLLM           | `VLLM_API_KEY`                                                               |
+| Cloudflare AI Gateway | `CLOUDFLARE_AI_GATEWAY_API_KEY`                                      |
+| GitHub Copilot | `COPILOT_GITHUB_TOKEN` or `GH_TOKEN` or `GITHUB_TOKEN`                      |
+
+For Cloudflare AI Gateway models, use provider base URL format
+`https://gateway.ai.cloudflare.com/v1/<account>/<gateway>/anthropic`.
+
+For Anthropic Foundry routing, set `CLAUDE_CODE_USE_FOUNDRY=true` plus:
+`FOUNDRY_BASE_URL`, `ANTHROPIC_FOUNDRY_API_KEY`, optional `ANTHROPIC_CUSTOM_HEADERS`,
+and optional mTLS material (`CLAUDE_CODE_CLIENT_CERT`, `CLAUDE_CODE_CLIENT_KEY`, `NODE_EXTRA_CA_CERTS`).
+
+Provider endpoint defaults for the current OpenAI-compatible integrations:
+
+- Together: `https://api.together.xyz/v1`
+- Moonshot: `https://api.moonshot.ai/v1`
+- Qianfan: `https://qianfan.baidubce.com/v2`
+- NVIDIA: `https://integrate.api.nvidia.com/v1`
+- NanoGPT: `https://nano-gpt.com/api/v1`
+- Hugging Face Inference: `https://router.huggingface.co/v1`
+- Venice: `https://api.venice.ai/api/v1`
+- Xiaomi MiMo: `https://api.xiaomimimo.com/anthropic`
+- ZenMux (OpenAI): `https://zenmux.ai/api/v1`
+- ZenMux (Anthropic models): `https://zenmux.ai/api/anthropic`
+- vLLM: `http://127.0.0.1:8000/v1`
+- Ollama: local OpenAI-compatible runtime (`http://127.0.0.1:11434/v1`)
+- Ollama Cloud: native Ollama API host (`https://ollama.com/api`, configured here as base URL `https://ollama.com`)
+- LiteLLM: `http://localhost:4000/v1`
+- Cloudflare AI Gateway: `https://gateway.ai.cloudflare.com/v1/<account>/<gateway>/anthropic`
+- Qwen Portal: `https://portal.qwen.ai/v1`
 When set, the library automatically uses these keys:
 
 ```typescript
 // Uses OPENAI_API_KEY from environment
-const model = getModel('openai', 'gpt-4o-mini');
+const model = getModel("openai", "gpt-4o-mini");
 const response = await complete(model, context);
 
 // Or override with explicit key
 const response = await complete(model, context, {
-  apiKey: 'sk-different-key'
+	apiKey: "sk-different-key",
 });
 ```
 
 ### Checking Environment Variables
 
 ```typescript
-import { getEnvApiKey } from '@aryee337/aery-ai';
+import { getEnvApiKey } from "@aryee337/aery-ai";
 
 // Check if an API key is set in environment variables
-const key = getEnvApiKey('openai');  // checks OPENAI_API_KEY
+const key = getEnvApiKey("openai"); // checks OPENAI_API_KEY
 ```
 
 ## OAuth Providers
 
-Several providers require OAuth authentication instead of static API keys:
+Several providers support OAuth authentication (some also support static API keys):
 
 - **Anthropic** (Claude Pro/Max subscription)
 - **OpenAI Codex** (ChatGPT Plus/Pro subscription, access to GPT-5.x Codex models)
 - **GitHub Copilot** (Copilot subscription)
+- **Google Gemini CLI** (Gemini 2.0/2.5 via Google Cloud Code Assist; free tier or paid subscription)
+- **Antigravity** (Free Gemini 3, Claude, GPT-OSS via Google Cloud)
+- **Qwen Portal** (Qwen OAuth token or API key)
 
 For paid Cloud Code Assist subscriptions, set `GOOGLE_CLOUD_PROJECT` or `GOOGLE_CLOUD_PROJECT_ID` to your project ID.
 
-### Vertex AI
+### Vertex AI (ADC)
 
-Vertex AI models support either a Google Cloud API key or Application Default Credentials (ADC):
+Vertex AI models use Application Default Credentials (ADC):
 
-- **API key**: Set `GOOGLE_CLOUD_API_KEY` or pass `apiKey` in the call options.
-- **Local development (ADC)**: Run `gcloud auth application-default login`
-- **CI/Production (ADC)**: Set `GOOGLE_APPLICATION_CREDENTIALS` to point to a service account JSON key file
+- **Local development**: Run `gcloud auth application-default login`
+- **CI/Production**: Set `GOOGLE_APPLICATION_CREDENTIALS` to point to a service account JSON key file
 
-When using ADC, also set `GOOGLE_CLOUD_PROJECT` (or `GCLOUD_PROJECT`) and `GOOGLE_CLOUD_LOCATION`. You can also pass `project`/`location` in the call options. When using `GOOGLE_CLOUD_API_KEY`, `project` and `location` are not required.
+Also set `GOOGLE_CLOUD_PROJECT` (or `GCLOUD_PROJECT`) and `GOOGLE_CLOUD_LOCATION`. You can also pass `project`/`location` in the call options.
 
 Example:
 
@@ -1179,19 +1041,17 @@ export GOOGLE_APPLICATION_CREDENTIALS="/path/to/service-account.json"
 ```
 
 ```typescript
-import { getModel, complete } from '@aryee337/aery-ai';
+import { getModel, complete } from "@aryee337/aery-ai";
 
 (async () => {
-  const model = getModel('google-vertex', 'gemini-2.5-flash');
-  const response = await complete(model, {
-    messages: [{ role: 'user', content: 'Hello from Vertex AI' }]
-  }, {
-    apiKey: process.env.GOOGLE_CLOUD_API_KEY,
-  });
-
-  for (const block of response.content) {
-    if (block.type === 'text') console.log(block.text);
-  }
+	const model = getModel("google-vertex", "gemini-2.5-flash");
+	const response = await complete(model, {
+		messages: [{ role: "user", content: "Hello from Vertex AI" }],
+	});
+
+	for (const block of response.content) {
+		if (block.type === "text") console.log(block.text);
+	}
 })().catch(console.error);
 ```
 
@@ -1199,58 +1059,86 @@ Official docs: [Application Default Credentials](https://cloud.google.com/docs/a
 
 ### CLI Login
 
-The quickest way to authenticate:
+Authenticate via the [`aery`](https://aery.dev) coding-agent CLI, which drives this library's OAuth/API-key flows in-process and persists into `agent.db`:
 
 ```bash
-npx @aryee337/aery-ai login              # interactive provider selection
-npx @aryee337/aery-ai login anthropic    # login to specific provider
-npx @aryee337/aery-ai list               # list available providers
+aery auth-broker login              # interactive provider selection
+aery auth-broker login anthropic    # login to a specific provider
+aery auth-broker login vllm         # store vLLM API key (or placeholder for local no-auth)
+aery auth-broker list               # list supported providers
+aery auth-broker logout             # interactive — pick a stored credential to remove
 ```
 
-Credentials are saved to `auth.json` in the current directory.
+Credentials are saved to `agent.db` in the agent directory. `/login qianfan` opens the Qianfan console and stores the pasted API key.
+
+`login` supports OAuth providers (Anthropic, OpenAI Codex, GitHub Copilot, Gemini CLI, Antigravity) and API-key onboarding flows.
+
+For the current API-key onboarding flows, the library covers Together, Moonshot, Qianfan, NVIDIA, NanoGPT, Hugging Face, Venice, Xiaomi, vLLM, LiteLLM, Cloudflare AI Gateway, Qwen Portal, and Ollama Cloud. Ollama remains the local runtime integration; set `OLLAMA_API_KEY` only when your local or self-hosted deployment enforces bearer auth.
 
 ### Programmatic OAuth
 
-The library provides login and token refresh functions via the `@aryee337/aery-ai/oauth` entry point. Credential storage is the caller's responsibility.
+The library provides login and token refresh functions. Credential storage is the caller's responsibility.
 
 ```typescript
 import {
-  // Login functions (return credentials, do not store)
-  loginAnthropic,
-  loginOpenAICodex,
-  loginGitHubCopilot,
-  loginGeminiCli,
-
-  // Token management
-  refreshOAuthToken,   // (provider, credentials) => new credentials
-  getOAuthApiKey,      // (provider, credentialsMap) => { newCredentials, apiKey } | null
-
-  // Types
-  type OAuthProvider,
-  type OAuthCredentials,
-} from '@aryee337/aery-ai/oauth';
+	// Login functions (return credentials, do not store)
+	loginAnthropic,
+	loginOpenAICodex,
+	loginGitHubCopilot,
+	loginGeminiCli,
+	loginAntigravity,
+	loginCloudflareAiGateway,
+	loginHuggingface,
+	loginLiteLLM,
+	loginMoonshot,
+	loginNvidia,
+	loginNanoGPT,
+	loginQianfan,
+	loginQwenPortal,
+	loginTogether,
+	loginVenice,
+	loginVllm,
+	loginXiaomi,
+
+	// Token management
+	refreshOAuthToken, // (provider, credentials) => new credentials
+	getOAuthApiKey, // (provider, credentialsMap) => { newCredentials, apiKey } | null
+
+	// Types
+	type OAuthProvider, // includes 'anthropic', 'openai-codex', 'github-copilot', 'google-gemini-cli', 'google-antigravity', 'together', 'moonshot', 'qianfan', 'nvidia', 'nanogpt', 'huggingface', 'venice', 'xiaomi', 'vllm', 'litellm', 'cloudflare-ai-gateway', 'qwen-portal', ...
+	type OAuthCredentials,
+} from "@aryee337/aery-ai";
+```
+
+`loginOpenAICodex` accepts an optional `originator` value used in the OAuth flow:
+
+```typescript
+await loginOpenAICodex({
+	onAuth: ({ url }) => console.log(url),
+	originator: "my-cli",
+});
 ```
 
 ### Login Flow Example
 
 ```typescript
-import { loginGitHubCopilot } from '@aryee337/aery-ai/oauth';
-import { writeFileSync } from 'fs';
+import { loginGitHubCopilot } from "@aryee337/aery-ai";
+import * as fs from "node:fs";
 
 const credentials = await loginGitHubCopilot({
-  onAuth: (url, instructions) => {
-    console.log(`Open: ${url}`);
-    if (instructions) console.log(instructions);
-  },
-  onPrompt: async (prompt) => {
-    return await getUserInput(prompt.message);
-  },
-  onProgress: (message) => console.log(message)
+	onAuth: (url, instructions) => {
+		console.log(`Open: ${url}`);
+		if (instructions) console.log(instructions);
+	},
+	onPrompt: async (prompt) => {
+		return await getUserInput(prompt.message);
+	},
+	onProgress: (message) => console.log(message),
 });
 
 // Store credentials yourself
-const auth = { 'github-copilot': { type: 'oauth', ...credentials } };
-writeFileSync('auth.json', JSON.stringify(auth, null, 2));
+const auth = { "github-copilot": { type: "oauth", ...credentials } };
+fs.writeFileSync("credentials.json", JSON.stringify(auth, null, 2));
 ```
 
 ### Using OAuth Tokens
@@ -1258,125 +1146,38 @@ writeFileSync('auth.json', JSON.stringify(auth, null, 2));
 Use `getOAuthApiKey()` to get an API key, automatically refreshing if expired:
 
 ```typescript
-import { getModel, complete } from '@aryee337/aery-ai';
-import { getOAuthApiKey } from '@aryee337/aery-ai/oauth';
-import { readFileSync, writeFileSync } from 'fs';
+import { getModel, complete, getOAuthApiKey } from "@aryee337/aery-ai";
+import * as fs from "node:fs";
 
 // Load your stored credentials
-const auth = JSON.parse(readFileSync('auth.json', 'utf-8'));
+const auth = JSON.parse(fs.readFileSync("credentials.json", "utf-8"));
 
 // Get API key (refreshes if expired)
-const result = await getOAuthApiKey('github-copilot', auth);
-if (!result) throw new Error('Not logged in');
+const result = await getOAuthApiKey("github-copilot", auth);
+if (!result) throw new Error("Not logged in");
 
 // Save refreshed credentials
-auth['github-copilot'] = { type: 'oauth', ...result.newCredentials };
-writeFileSync('auth.json', JSON.stringify(auth, null, 2));
+auth["github-copilot"] = { type: "oauth", ...result.newCredentials };
+fs.writeFileSync("credentials.json", JSON.stringify(auth, null, 2));
 
 // Use the API key
-const model = getModel('github-copilot', 'gpt-4o');
-const response = await complete(model, {
-  messages: [{ role: 'user', content: 'Hello!' }]
-}, { apiKey: result.apiKey });
+const model = getModel("github-copilot", "gpt-4o");
+const response = await complete(
+	model,
+	{
+		messages: [{ role: "user", content: "Hello!" }],
+	},
+	{ apiKey: result.apiKey }
+);
 ```
 
 ### Provider Notes
 
-**OpenAI Codex**: Requires a ChatGPT Plus or Pro subscription. Provides access to GPT-5.x Codex models with extended context windows and reasoning capabilities. The library automatically handles session-based prompt caching when `sessionId` is provided in stream options. You can set `transport` in stream options to `"sse"`, `"websocket"`, or `"auto"` for Codex Responses transport selection. When using WebSocket with a `sessionId`, connections are reused per session and expire after 5 minutes of inactivity.
-
-**Azure OpenAI (Responses)**: Uses the Responses API only. Set `AZURE_OPENAI_API_KEY` and either `AZURE_OPENAI_BASE_URL` or `AZURE_OPENAI_RESOURCE_NAME`. `AZURE_OPENAI_BASE_URL` supports both `https://<resource>.openai.azure.com` and `https://<resource>.cognitiveservices.azure.com`; root endpoints are normalized to `.../openai/v1` automatically. Use `AZURE_OPENAI_AAERY_VERSION` (defaults to `v1`) to override the API version if needed. Deployment names are treated as model IDs by default, override with `azureDeploymentName` or `AZURE_OPENAI_DEPLOYMENT_NAME_MAP` using comma-separated `model-id=deployment` pairs (for example `gpt-4o-mini=my-deployment,gpt-4o=prod`). Legacy deployment-based URLs are intentionally unsupported.
+**OpenAI Codex**: Requires a ChatGPT Plus or Pro subscription. Provides access to GPT-5.x Codex models with extended context windows and reasoning capabilities. The library automatically handles session-based prompt caching when `sessionId` is provided in stream options.
 
 **GitHub Copilot**: If you get "The requested model is not supported" error, enable the model manually in VS Code: open Copilot Chat, click the model selector, select the model (warning icon), and click "Enable".
 
-## Development
-
-### Adding a New Provider
-
-Adding a new LLM provider requires changes across multiple files. This checklist covers all necessary steps:
-
-#### 1. Core Types (`src/types.ts`)
-
-- Add the API identifier to `KnownApi` (for example `"bedrock-converse-stream"`)
-- Create an options interface extending `StreamOptions` (for example `BedrockOptions`)
-- Add the provider name to `KnownProvider` (for example `"amazon-bedrock"`)
-
-#### 2. Provider Implementation (`src/providers/`)
-
-Create a new provider file (for example `amazon-bedrock.ts`) that exports:
-
-- `stream<Provider>()` function returning `AssistantMessageEventStream`
-- `streamSimple<Provider>()` for `SimpleStreamOptions` mapping
-- Provider-specific options interface
-- Message conversion functions to transform `Context` to provider format
-- Tool conversion if the provider supports tools
-- Response parsing to emit standardized events (`text`, `tool_call`, `thinking`, `usage`, `stop`)
-
-#### 3. API Registry Integration (`src/providers/register-builtins.ts`)
-
-- Register the API with `registerApiProvider()`
-- Add a package subpath export in `package.json` for the provider module (`./dist/providers/<provider>.js`)
-- Add lazy loader wrappers in `src/providers/register-builtins.ts`, do not statically import provider implementation modules there
-- Add any root-level `export type` re-exports in `src/index.ts` that should remain available from `@aryee337/aery-ai`
-- Add credential detection in `env-api-keys.ts` for the new provider
-- Ensure `streamSimple` handles auth lookup via `getEnvApiKey()` or provider-specific auth
-
-#### 4. Model Generation (`scripts/generate-models.ts`, `scripts/generate-image-models.ts`)
-
-- Add logic to fetch and parse models from the provider's source (e.g., models.dev API)
-- Map chat/tool-capable provider model data to the standardized `Model` interface via `scripts/generate-models.ts`
-- Map image-generation provider model data to the standardized `ImagesModel` interface via `scripts/generate-image-models.ts`
-- Handle provider-specific quirks (pricing format, capability flags, model ID transformations)
-
-#### 5. Tests (`test/`)
-
-Create or update test files to cover the new provider:
-
-- `stream.test.ts` - Basic streaming and tool use
-- `tokens.test.ts` - Token usage reporting
-- `abort.test.ts` - Request cancellation
-- `empty.test.ts` - Empty message handling
-- `context-overflow.test.ts` - Context limit errors
-- `image-limits.test.ts` - Image support (if applicable)
-- `unicode-surrogate.test.ts` - Unicode handling
-- `tool-call-without-result.test.ts` - Orphaned tool calls
-- `image-tool-result.test.ts` - Images in tool results
-- `total-tokens.test.ts` - Token counting accuracy
-- `cross-provider-handoff.test.ts` - Cross-provider context replay
-
-For `cross-provider-handoff.test.ts`, add at least one provider/model pair. If the provider exposes multiple model families (for example GPT and Claude), add at least one pair per family.
-
-For providers with non-standard auth (AWS, Google Vertex), create a utility like `bedrock-utils.ts` with credential detection helpers.
-
-#### 6. Coding Agent Integration (`../coding-agent/`)
-
-Update `src/core/model-resolver.ts`:
-
-- Add a default model ID for the provider in `DEFAULT_MODELS`
-
-Update `src/cli/args.ts`:
-
-- Add environment variable documentation in the help text
-
-Update `README.md`:
-
-- Add the provider to the providers section with setup instructions
-
-#### 7. Documentation
-
-Update `packages/ai/README.md`:
-
-- Add to the Supported Providers table
-- Document any provider-specific options or authentication requirements
-- Add environment variable to the Environment Variables section
-
-#### 8. Changelog
-
-Add an entry to `packages/ai/CHANGELOG.md` under `## [Unreleased]`:
-
-```markdown
-### Added
-- Added support for [Provider Name] provider ([#PR](link) by [@author](link))
-```
+**Google Gemini CLI / Antigravity**: These use Google Cloud OAuth. The `apiKey` returned by `getOAuthApiKey()` is a JSON string containing both the token and project ID, which the library handles automatically.
 
 ## License