@providerprotocol/ai 0.0.34 → 0.0.36

package/README.md

@@ -26,9 +26,12 @@ console.log(turn.response.text);
 | Google | `@providerprotocol/ai/google` | ✓ | ✓ | ✓ |
 | xAI | `@providerprotocol/ai/xai` | ✓ | | ✓ |
 | Ollama | `@providerprotocol/ai/ollama` | ✓ | ✓ | |
-| OpenRouter | `@providerprotocol/ai/openrouter` | ✓ | ✓ | |
+| OpenRouter | `@providerprotocol/ai/openrouter` | ✓ | ✓ | ✓ |
+| Groq | `@providerprotocol/ai/groq` | ✓ | | |
+| Cerebras | `@providerprotocol/ai/cerebras` | ✓ | | |
+| OpenResponses | `@providerprotocol/ai/responses` | ✓ | | |
 
-API keys are loaded automatically from environment variables (`ANTHROPIC_API_KEY`, `OPENAI_API_KEY`, etc.).
+API keys are loaded automatically from environment variables (`ANTHROPIC_API_KEY`, `OPENAI_API_KEY`, `GROQ_API_KEY`, `CEREBRAS_API_KEY`, etc.).
 
 ## LLM
 
@@ -44,6 +47,12 @@ for await (const event of stream) {
 const turn = await stream.turn;
 ```
 
+Stream results are PromiseLike, so you can also await the stream directly to auto-drain:
+
+```typescript
+const turn = await claude.stream('Count to 5');
+```
+
 **Stream Control:**
 
 ```typescript
@@ -63,6 +72,7 @@ for await (const event of stream) {
 |-------|-------------|
 | `text_delta` | Incremental text output |
 | `reasoning_delta` | Incremental reasoning/thinking output |
+| `object_delta` | Incremental structured output JSON |
 | `tool_call_delta` | Tool call arguments being streamed |
 | `tool_execution_start` | Tool execution has started |
 | `tool_execution_end` | Tool execution has completed |
@@ -123,12 +133,36 @@ console.log(turn.data); // { name: 'John', age: 30 }
 ### Multimodal Input
 
 ```typescript
-import { Image } from '@providerprotocol/ai';
+import { Image, Document, Audio, Video } from '@providerprotocol/ai';
 
+// Images
 const img = await Image.fromPath('./photo.png');
 const turn = await claude.generate([img, 'What is in this image?']);
+
+// Documents (PDF, text)
+const doc = await Document.fromPath('./report.pdf', 'Annual Report');
+const docTurn = await claude.generate([doc.toBlock(), 'Summarize this document']);
+
+// Audio (Google, OpenRouter)
+const audio = await Audio.fromPath('./recording.mp3');
+const audioTurn = await gemini.generate([audio.toBlock(), 'Transcribe this audio']);
+
+// Video (Google, OpenRouter)
+const video = await Video.fromPath('./clip.mp4');
+const videoTurn = await gemini.generate([video.toBlock(), 'Describe this video']);
 ```
 
+**Multimodal Support by Provider:**
+
+| Provider | Image | Document | Audio | Video |
+|----------|:-----:|:--------:|:-----:|:-----:|
+| Anthropic | ✓ | PDF, Text | | |
+| OpenAI | ✓ | PDF, Text | | |
+| Google | ✓ | PDF, Text | ✓ | ✓ |
+| OpenRouter | ✓ | PDF, Text | ✓ | ✓ |
+| xAI | ✓ | | | |
+| Groq | ✓ | | | |
+
 ## Anthropic Beta Features
 
 Anthropic provides beta features through the `betas` export. Enable them at the model level:
@@ -168,21 +202,164 @@ const thinker = llm({
 | `interleavedThinking` | Claude can think between tool calls |
 | `devFullThinking` | Developer mode for full thinking visibility |
 | `effort` | Control response thoroughness vs efficiency (Opus 4.5) |
+| `computerUseLegacy` | Computer use for Claude 3.x models |
 | `computerUse` | Mouse, keyboard, screenshot control (Claude 4) |
+| `computerUseOpus` | Computer use with extra commands (Opus 4.5) |
 | `codeExecution` | Python/Bash sandbox execution |
 | `tokenEfficientTools` | Up to 70% token reduction for tool calls |
 | `fineGrainedToolStreaming` | Stream tool args without buffering |
+| `maxTokens35Sonnet` | 8,192 output tokens for Claude 3.5 Sonnet |
 | `output128k` | 128K token output length |
 | `context1m` | 1 million token context window (Sonnet 4) |
 | `promptCaching` | Reduced latency and costs via caching |
 | `extendedCacheTtl` | 1-hour cache TTL (vs 5-minute default) |
+| `contextManagement` | Automatic tool call clearing for context |
+| `modelContextWindowExceeded` | Handle exceeded context windows |
 | `advancedToolUse` | Tool Search, Programmatic Tool Calling |
 | `mcpClient` | Connect to remote MCP servers |
+| `mcpClientLatest` | Updated MCP client |
 | `filesApi` | Upload and manage files |
 | `pdfs` | PDF document support |
+| `tokenCounting` | Token counting endpoint |
 | `messageBatches` | Async batch processing at 50% cost |
 | `skills` | Agent Skills (PowerPoint, Excel, Word, PDF) |
 
+## Anthropic Built-in Tools
+
+Use Anthropic's built-in tools directly with the `tools` export:
+
+```typescript
+import { anthropic, betas, tools } from '@providerprotocol/ai/anthropic';
+import { llm } from '@providerprotocol/ai';
+
+// Web search with optional user location
+const model = llm({
+  model: anthropic('claude-sonnet-4-20250514'),
+  params: {
+    tools: [tools.webSearch({ max_results: 5 })],
+  },
+});
+
+// Computer use (requires beta)
+const computerModel = llm({
+  model: anthropic('claude-sonnet-4-20250514', {
+    betas: [betas.computerUse],
+  }),
+  params: {
+    tools: [tools.computer({ display_width: 1920, display_height: 1080, display_number: 1 })],
+  },
+});
+
+// Code execution (requires beta)
+const codeModel = llm({
+  model: anthropic('claude-sonnet-4-20250514', {
+    betas: [betas.codeExecution],
+  }),
+  params: {
+    tools: [tools.codeExecution()],
+  },
+});
+```
+
+**Available Built-in Tools:**
+
+| Tool | Description |
+|------|-------------|
+| `tools.webSearch()` | Search the web with optional max results and location |
+| `tools.computer()` | Mouse, keyboard, and screenshot control |
+| `tools.textEditor()` | Edit text files programmatically |
+| `tools.bash()` | Execute bash commands |
+| `tools.codeExecution()` | Run code in a sandboxed environment |
+| `tools.toolSearch()` | Search through available tools |
+
+## Reasoning / Extended Thinking
+
+Access model reasoning and extended thinking across providers with a unified API.
+
+### Anthropic
+
+```typescript
+import { llm } from '@providerprotocol/ai';
+import { anthropic } from '@providerprotocol/ai/anthropic';
+
+const claude = llm({
+  model: anthropic('claude-sonnet-4-20250514'),
+  params: {
+    max_tokens: 16000,
+    thinking: {
+      type: 'enabled',
+      budget_tokens: 5000,
+    },
+  },
+});
+
+const turn = await claude.generate('Solve this complex problem...');
+console.log(turn.response.reasoning); // Reasoning blocks
+```
+
+### OpenAI
+
+```typescript
+import { llm } from '@providerprotocol/ai';
+import { openai } from '@providerprotocol/ai/openai';
+
+const gpt = llm({
+  model: openai('o3-mini'),
+  params: {
+    max_output_tokens: 4000,
+    reasoning: {
+      effort: 'medium',
+      summary: 'detailed',
+    },
+  },
+});
+```
+
+### Google Gemini
+
+```typescript
+import { llm } from '@providerprotocol/ai';
+import { google } from '@providerprotocol/ai/google';
+
+const gemini = llm({
+  model: google('gemini-2.5-flash'),
+  params: {
+    maxOutputTokens: 4000,
+    thinkingConfig: {
+      thinkingBudget: -1, // Dynamic
+      includeThoughts: true,
+    },
+  },
+});
+```
+
+### Cerebras
+
+```typescript
+import { llm } from '@providerprotocol/ai';
+import { cerebras } from '@providerprotocol/ai/cerebras';
+
+const model = llm({
+  model: cerebras('gpt-oss-120b'),
+  params: {
+    reasoning_effort: 'high',
+    reasoning_format: 'parsed',
+  },
+});
+```
+
+### Streaming Reasoning
+
+All providers emit `ReasoningDelta` events during streaming:
+
+```typescript
+for await (const event of stream) {
+  if (event.type === 'reasoning_delta') {
+    process.stdout.write(event.delta.text);
+  }
+}
+```
+
 ## Embeddings
 
 ```typescript
@@ -414,6 +591,161 @@ localStorage.setItem('conversation', JSON.stringify(json));
 const restored = Thread.fromJSON(JSON.parse(localStorage.getItem('conversation')));
 ```
 
+## Middleware
+
+Compose request/response/stream transformations with the middleware system. Middleware is imported from dedicated entry points.
+
+### Parsed Object Middleware
+
+Automatically parse streaming JSON from structured output and tool call events:
+
+```typescript
+import { llm } from '@providerprotocol/ai';
+import { anthropic } from '@providerprotocol/ai/anthropic';
+import { parsedObjectMiddleware } from '@providerprotocol/ai/middleware/parsed-object';
+
+const model = llm({
+  model: anthropic('claude-sonnet-4-20250514'),
+  structure: {
+    type: 'object',
+    properties: {
+      city: { type: 'string' },
+      country: { type: 'string' },
+      population: { type: 'number' },
+    },
+    required: ['city', 'country', 'population'],
+  },
+  middleware: [parsedObjectMiddleware()],
+});
+
+for await (const event of model.stream('What is the capital of France?')) {
+  if (event.type === 'object_delta') {
+    // Access incrementally parsed structured data
+    console.log(event.delta.parsed);
+    // { city: "Par" } -> { city: "Paris" } -> { city: "Paris", country: "Fr" } -> ...
+  }
+}
+```
+
+### Logging Middleware
+
+Add visibility into request lifecycle:
+
+```typescript
+import { llm } from '@providerprotocol/ai';
+import { anthropic } from '@providerprotocol/ai/anthropic';
+import { loggingMiddleware } from '@providerprotocol/ai/middleware/logging';
+
+const model = llm({
+  model: anthropic('claude-sonnet-4-20250514'),
+  middleware: [loggingMiddleware({ level: 'debug' })],
+});
+
+// Logs: [PP] [anthropic] Starting llm request (streaming)
+// Logs: [PP] [anthropic] Completed in 1234ms
+const result = await model.generate('Hello');
+```
+
+### Pub-Sub Middleware (Stream Resumption)
+
+Enable reconnecting clients to catch up on missed events during active generation. The middleware buffers events, publishes them to subscribers, and removes streams on completion/abort/error.
+If a stream never reaches those hooks (for example, a process crash), the adapter may retain the entry. Custom adapters should invoke `onComplete` when `remove()` runs so subscriber streams can terminate.
+Streams are created lazily on first `append()` or `subscribe()` call.
+
+```typescript
+import { llm } from '@providerprotocol/ai';
+import { anthropic } from '@providerprotocol/ai/anthropic';
+import { pubsubMiddleware, memoryAdapter } from '@providerprotocol/ai/middleware/pubsub';
+import { webapi } from '@providerprotocol/ai/middleware/pubsub/server';
+
+// Create a shared adapter instance
+const adapter = memoryAdapter({ maxStreams: 1000 });
+
+// Server route handling both new requests and reconnections
+Bun.serve({
+  port: 3000,
+  async fetch(req) {
+    const { messages, streamId } = await req.json();
+    const exists = await adapter.exists(streamId);
+
+    if (!exists) {
+      // Start background generation (fire and forget)
+      // Stream is created lazily on first append()
+      const model = llm({
+        model: anthropic('claude-sonnet-4-20250514'),
+        middleware: [pubsubMiddleware({ adapter, streamId })],
+      });
+      model.stream(messages).then(turn => { /* save to DB */ });
+    }
+
+    // Both new and reconnect: subscribe to events
+    return new Response(webapi.createSubscriberStream(streamId, adapter), {
+      headers: { 'Content-Type': 'text/event-stream' },
+    });
+  },
+});
+```
+
+**Framework Adapters:**
+
+```typescript
+// Express
+import { express } from '@providerprotocol/ai/middleware/pubsub/server';
+app.post('/api/ai/reconnect', (req, res) => {
+  const { streamId } = req.body;
+  express.streamSubscriber(streamId, adapter, res);
+});
+
+// Fastify
+import { fastify } from '@providerprotocol/ai/middleware/pubsub/server';
+app.post('/api/ai/reconnect', (request, reply) => {
+  const { streamId } = request.body;
+  return fastify.streamSubscriber(streamId, adapter, reply);
+});
+
+// H3/Nuxt
+import { h3 } from '@providerprotocol/ai/middleware/pubsub/server';
+export default defineEventHandler(async (event) => {
+  const { streamId } = await readBody(event);
+  return h3.streamSubscriber(streamId, adapter, event);
+});
+```
+
+**Custom Adapters:**
+
+Implement `PubSubAdapter` for custom backends (Redis, etc.):
+
+```typescript
+import type { PubSubAdapter } from '@providerprotocol/ai/middleware/pubsub';
+
+const redisAdapter: PubSubAdapter = {
+  async exists(streamId) { /* check if stream exists */ },
+  async append(streamId, event) { /* append event, create lazily */ },
+  async getEvents(streamId) { /* return events or [] */ },
+  subscribe(streamId, onEvent, onComplete) { /* subscribe to live events */ },
+  publish(streamId, event) { /* broadcast to subscribers */ },
+  async remove(streamId) { /* notify onComplete then delete */ },
+};
+```
+
+### Combining Middleware
+
+```typescript
+import { llm } from '@providerprotocol/ai';
+import { anthropic } from '@providerprotocol/ai/anthropic';
+import { loggingMiddleware } from '@providerprotocol/ai/middleware/logging';
+import { parsedObjectMiddleware } from '@providerprotocol/ai/middleware/parsed-object';
+
+const model = llm({
+  model: anthropic('claude-sonnet-4-20250514'),
+  structure: mySchema,
+  middleware: [
+    loggingMiddleware({ level: 'info' }),
+    parsedObjectMiddleware(),
+  ],
+});
+```
+
 ## Error Handling
 
 All errors are normalized to `UPPError` with consistent error codes:
@@ -561,6 +893,74 @@ export default defineEventHandler(async (event) => {
 - Request/response logging, content filtering
 - Double-layer retry: client retries to proxy, server retries to AI provider
 
+## OpenAI API Modes
+
+OpenAI supports two API endpoints. The Responses API is the default and recommended approach:
+
+```typescript
+import { openai } from '@providerprotocol/ai/openai';
+
+// Responses API (default, recommended)
+openai('gpt-4o')
+
+// Chat Completions API (legacy)
+openai('gpt-4o', { api: 'completions' })
+```
+
+The Responses API supports built-in tools and stateful conversations. Use completions for backward compatibility.
+
+## OpenAI Built-in Tools
+
+With the Responses API, use OpenAI's built-in tools directly:
+
+```typescript
+import { llm } from '@providerprotocol/ai';
+import { openai, tools } from '@providerprotocol/ai/openai';
+
+// Web search
+const model = llm({
+  model: openai('gpt-4o'),
+  params: {
+    tools: [tools.webSearch()],
+  },
+});
+
+// File search with vector stores
+const researchModel = llm({
+  model: openai('gpt-4o'),
+  params: {
+    tools: [tools.fileSearch({ vector_store_ids: ['vs_abc123'] })],
+  },
+});
+
+// Code interpreter
+const codeModel = llm({
+  model: openai('gpt-4o'),
+  params: {
+    tools: [tools.codeInterpreter()],
+  },
+});
+
+// Image generation
+const creativeModel = llm({
+  model: openai('gpt-4o'),
+  params: {
+    tools: [tools.imageGeneration()],
+  },
+});
+```
+
+**Available Built-in Tools:**
+
+| Tool | Description |
+|------|-------------|
+| `tools.webSearch()` | Search the web with optional user location |
+| `tools.fileSearch()` | Search uploaded files in vector stores |
+| `tools.codeInterpreter()` | Execute code in a sandboxed environment |
+| `tools.computer()` | Computer use with display configuration |
+| `tools.imageGeneration()` | Generate images via DALL-E |
+| `tools.mcp()` | Connect to MCP servers |
+
 ## xAI API Modes
 
 xAI supports multiple API compatibility modes:
@@ -578,6 +978,119 @@ xai('grok-3-fast', { api: 'responses' })
 xai('grok-3-fast', { api: 'messages' })
 ```
 
+## Groq
+
+Fast inference with Llama, Gemma, and Mixtral models:
+
+```typescript
+import { llm } from '@providerprotocol/ai';
+import { groq } from '@providerprotocol/ai/groq';
+
+const model = llm({
+  model: groq('llama-3.3-70b-versatile'),
+  params: { max_tokens: 1000 },
+});
+
+const turn = await model.generate('Hello!');
+```
+
+**With web search:**
+
+```typescript
+const searchModel = llm({
+  model: groq('llama-3.3-70b-versatile'),
+  params: {
+    search_settings: { mode: 'auto' },
+  },
+});
+```
+
+**With RAG documents:**
+
+```typescript
+const ragModel = llm({
+  model: groq('llama-3.3-70b-versatile'),
+  params: {
+    documents: [
+      { title: 'Doc 1', content: 'Document content here...' },
+      { title: 'Doc 2', content: 'More content...' },
+    ],
+    citation_options: { include: true },
+  },
+});
+```
+
+**Capabilities:** Streaming, tool calling, structured output, image input (Llama 4 preview), web search, RAG with citations.
+
+**Environment:** `GROQ_API_KEY`
+
+## Cerebras
+
+Ultra-fast inference with Llama, Qwen, and GPT-OSS models:
+
+```typescript
+import { llm } from '@providerprotocol/ai';
+import { cerebras } from '@providerprotocol/ai/cerebras';
+
+const model = llm({
+  model: cerebras('llama-3.3-70b'),
+  params: { max_completion_tokens: 1000 },
+});
+
+const turn = await model.generate('Hello!');
+```
+
+**With reasoning (GPT-OSS):**
+
+```typescript
+const model = llm({
+  model: cerebras('gpt-oss-120b'),
+  params: {
+    reasoning_effort: 'high',
+    reasoning_format: 'parsed',
+  },
+});
+```
+
+**Capabilities:** Streaming, tool calling, structured output, reasoning parameters.
+
+**Environment:** `CEREBRAS_API_KEY`
+
+## OpenResponses Provider
+
+Connect to any server implementing the [OpenResponses specification](https://www.openresponses.org):
+
+```typescript
+import { llm } from '@providerprotocol/ai';
+import { responses } from '@providerprotocol/ai/responses';
+
+// Using with OpenAI
+const model = llm({
+  model: responses('gpt-5.2', {
+    host: 'https://api.openai.com/v1',
+    apiKeyEnv: 'OPENAI_API_KEY',
+  }),
+  params: { max_output_tokens: 1000 },
+});
+
+// Using with OpenRouter
+const routerModel = llm({
+  model: responses('openai/gpt-4o', {
+    host: 'https://openrouter.ai/api/v1',
+    apiKeyEnv: 'OPENROUTER_API_KEY',
+  }),
+});
+
+// Using with self-hosted server
+const localModel = llm({
+  model: responses('llama-3.3-70b', {
+    host: 'http://localhost:8080/v1',
+  }),
+});
+```
+
+**Capabilities:** Full multimodal support, streaming, tool calling, structured output, reasoning summaries.
+
 ## Alternative Import Style
 
 Use the `ai` namespace for a grouped import style:
@@ -607,6 +1120,14 @@ import type {
   StreamEvent,
   StreamResult,
 
+  // Content blocks
+  TextBlock,
+  ImageBlock,
+  ReasoningBlock,
+  DocumentBlock,
+  AudioBlock,
+  VideoBlock,
+
   // Modality results
   EmbeddingResult,
   ImageResult,
@@ -620,9 +1141,31 @@ import type {
   KeyStrategy,
   RetryStrategy,
   LLMCapabilities,
+
+  // Middleware
+  Middleware,
+  MiddlewareContext,
+  StreamContext,
 } from '@providerprotocol/ai';
 ```
 
+**Type-Safe Enums:**
+
+```typescript
+import {
+  StreamEventType,
+  ErrorCode,
+  ContentBlockType,
+  MessageRole,
+  ModalityType,
+} from '@providerprotocol/ai';
+
+// Use instead of magic strings
+if (event.type === StreamEventType.TextDelta) { ... }
+if (error.code === ErrorCode.RateLimited) { ... }
+if (block.type === ContentBlockType.Text) { ... }
+```
+
 ### Custom Providers
 
 Build custom providers with `createProvider`:

package/dist/anthropic/index.d.ts

@@ -1,4 +1,5 @@
-import { P as Provider } from '../llm-BQJZj3cD.js';
+import { d as Provider } from '../llm-ByUFPcFH.js';
+import '../stream-S7nwQRqM.js';
 
 /**
  * @fileoverview Anthropic API type definitions.