Required dependencies

npm install @providerprotocol/ai

No native modules, no pod install, no Android linking. The package has zero runtime dependencies; it uses the platform's native fetch. Node.js 18+ is required for native fetch and ReadableStream support.

Project setup

1. Copy source: Place the source/ directory into your project, e.g. src/vendor/provider-protocol-ai/.

2. tsconfig paths (if importing locally instead of via npm):

{
  "compilerOptions": {
    "paths": {
      "@providerprotocol/ai": ["./src/vendor/provider-protocol-ai/index.ts"],
      "@providerprotocol/ai/*": ["./src/vendor/provider-protocol-ai/*/index.ts"]
    },
    "moduleResolution": "bundler",
    "target": "ES2022",
    "module": "ESNext"
  }
}

3. Environment variables - Set API keys before running. The SDK reads these automatically:

ANTHROPIC_API_KEY=sk-ant-...
OPENAI_API_KEY=sk-...
GROQ_API_KEY=gsk_...
CEREBRAS_API_KEY=...
MOONSHOT_API_KEY=...
GOOGLE_API_KEY=...
XAI_API_KEY=...
OPENROUTER_API_KEY=...

4. Module resolution: If using .ts file extensions in imports (import ... from './core/llm.ts'), ensure your bundler or runtime (Bun, ts-node with --esm, Vite) supports TypeScript extension imports. With tsc + Node.js, set "moduleResolution": "bundler" or "nodenext".

5. Runtime: Bun or Node.js 18+. Deno is also supported with native fetch.

Public API

llm

import { llm } from '@providerprotocol/ai';
import { anthropic } from '@providerprotocol/ai/anthropic';

const model = llm({
  model: anthropic('claude-sonnet-4-20250514'),
  system?: string,
  params?: { max_tokens?: number },
  tools?: Tool[],
  structure?: object,
});

// Returns an object with:
model.generate(input?: string | Message[], overrides?: object): Promise<Turn>
model.stream(input?: string | Message[], overrides?: object): AsyncIterable<StreamEvent> & PromiseLike<Turn>

Use llm to create a reusable, model-bound inference object. Pass a provider-specific model descriptor (e.g. anthropic(...), openai(...)) and optional defaults. Call .generate() for a single response or .stream() for streaming.

embedding

import { embedding } from '@providerprotocol/ai';
import { openai } from '@providerprotocol/ai/openai';

const embedder = embedding({ model: openai('text-embedding-3-small') });
const result = await embedder.embed('Hello world');
// result.embeddings: number[][]

Creates a model-bound embedding function. Supported by OpenAI, Google, Ollama, and OpenRouter. Pass text or an array of strings.

image

import { image } from '@providerprotocol/ai';
import { openai } from '@providerprotocol/ai/openai';

const generator = image({ model: openai('dall-e-3') });
const result = await generator.generate({ prompt: 'A mountain at sunrise' });
// result.images: string[]  (base64 or URLs depending on provider)

Creates a model-bound image generation function. Supported by OpenAI, Google Imagen, xAI, and OpenRouter. The return shape includes provider-specific metadata.

anthropic (provider factory)

import { anthropic, betas } from '@providerprotocol/ai/anthropic';

const model = anthropic('claude-sonnet-4-20250514', {
  betas?: BetaKey[],
  apiKey?: string,
});

Returns a model descriptor consumed by llm(). Optionally enable Anthropic beta features (e.g. betas.structuredOutputs). API key defaults to ANTHROPIC_API_KEY.

Working examples

Scenario - Basic single-turn generation with Anthropic

Create a Claude-backed assistant and generate a single response. The turn.response.text field contains the final text.

import { llm } from '@providerprotocol/ai';
import { anthropic } from '@providerprotocol/ai/anthropic';

const claude = llm({
  model: anthropic('claude-sonnet-4-20250514'),
  params: { max_tokens: 512 },
  system: 'You are a concise assistant.',
});

const turn = await claude.generate('Explain transformers in one paragraph.');
console.log(turn.response.text);

Scenario - Streaming with abort control

Stream tokens as they arrive and abort after a timeout. The stream is both an async iterable and a PromiseLike<Turn>.

import { llm } from '@providerprotocol/ai';
import { openai } from '@providerprotocol/ai/openai';

const gpt = llm({ model: openai('gpt-4o') });

const stream = gpt.stream('Write a short story about a robot.');

setTimeout(() => stream.abort(), 8000);

for await (const event of stream) {
  if (event.type === 'text_delta') {
    process.stdout.write(event.delta.text);
  }
}

const turn = await stream.turn;
console.log('\nTotal tokens:', turn.response.usage?.total_tokens);

Scenario - Multi-turn conversation with tool use

Maintain conversation history across turns and supply a tool the model can call.

import { llm } from '@providerprotocol/ai';
import { anthropic } from '@providerprotocol/ai/anthropic';
import type { Message } from '@providerprotocol/ai';

const claude = llm({
  model: anthropic('claude-sonnet-4-20250514'),
  tools: [{
    name: 'getWeather',
    description: 'Get current weather for a city',
    parameters: {
      type: 'object',
      properties: { city: { type: 'string' } },
      required: ['city'],
    },
    run: async ({ city }: { city: string }) => ({ temp: 22, conditions: 'clear' }),
  }],
});

const history: Message[] = [];

const t1 = await claude.generate(history, 'My name is Sam.');
history.push(...t1.messages);

const t2 = await claude.generate(history, 'What is the weather in Tokyo?');
history.push(...t2.messages);

console.log(t2.response.text);

Scenario - Embeddings with OpenAI

Generate vector embeddings for a list of strings.

import { embedding } from '@providerprotocol/ai';
import { openai } from '@providerprotocol/ai/openai';

const embedder = embedding({ model: openai('text-embedding-3-small') });

const result = await embedder.embed([
  'The quick brown fox',
  'Jumps over the lazy dog',
]);

console.log('Dimensions:', result.embeddings[0].length);
console.log('Vectors:', result.embeddings.length);

File walkthrough

• index.ts - Barrel export; re-exports llm, embedding, image, createProvider, and media wrappers (Image, Document, Audio, Video).
• anthropic/index.ts - Public Anthropic surface: anthropic() factory, tools, betas constants, and all Anthropic-specific types.
• cerebras/index.ts - Public Cerebras surface: cerebras() factory and full Cerebras request/response types.
• google/index.ts - Public Google Gemini surface: google(), tools, cache, and Gemini-specific parameter types including GoogleImagenParams and GoogleEmbedParams.
• core/llm.ts - llm() factory; orchestrates provider selection, tool execution loop, and turn assembly.
• core/embedding.ts - embedding() factory; delegates to provider-specific embedding handlers.
• core/image.ts - image() factory for image generation.
• core/provider.ts - createProvider() for registering custom/self-hosted providers.
• core/provider-handlers.ts - Internal dispatch table mapping provider keys to handler implementations.
• core/media/Image.ts - Image class for wrapping base64, URL, or file-based image content.
• core/media/document.ts - Document class for PDF and plain-text document inputs.
• core/media/Audio.ts - Audio class for audio content passed to multimodal models.
• core/media/Video.ts - Video class for video content (Google Gemini).
• http/ - Internal HTTP layer: fetch wrapper, SSE parser, retry logic, key resolution, error types.
• middleware/ - Composable middleware: logging, persistence, pub/sub (Express/Fastify/H3/WebAPI adapters), pipeline runner, and parsed-object extraction.
• providers/ - Per-provider request/response transform implementations; not intended for direct import.
• stream/ - Normalized streaming event types and async iterable utilities.
• types/ - Shared Message, Turn, Tool, and other cross-provider TypeScript types.
• utils/ - Internal helpers (JSON parsing, schema conversion, etc.).

Common pitfalls and fixes

• Missing API key at runtime: The SDK reads env vars at call time, not import time. Ensure the key is set in the process environment before calling .generate() or .stream(). Use dotenv in development.
• Node.js < 18 lacks native fetch: Upgrade to Node 18+ or polyfill with npm install node-fetch and global.fetch = require('node-fetch') before any imports.
• .ts extension imports fail with tsc: Set "moduleResolution": "bundler" or "nodenext" in tsconfig.json; plain "node" resolution does not support explicit .ts extensions.
• Streaming turn not awaited: Calling for await on the stream consumes it; afterward, await stream.turn may resolve immediately or be unavailable depending on drain state. Capture stream.turn before the loop or await stream directly to auto-drain.
• Tool run function not called: Tools must be passed to llm() at construction time or as an override in the first argument of generate()/stream(). Passing them only in the second argument (the prompt slot) has no effect.
• Cerebras reasoning metadata: Cerebras reasoning output is not in turn.response.text; access it via turn.response.metadata.cerebras.reasoning after the turn resolves.

Vibe-coding prompt template

I have dropped the source of `@providerprotocol/ai@0.0.44` into `src/vendor/provider-protocol-ai/`.
I also have `USAGE.md` open which documents all real exports and working examples.

Please help me integrate this SDK into my existing TypeScript project step by step:

1. Read `USAGE.md` and `src/vendor/provider-protocol-ai/index.ts` to understand the available exports.
2. Update my `tsconfig.json` paths so that `@providerprotocol/ai` and `@providerprotocol/ai/*` resolve to the vendor source.
3. Add the required environment variables to my `.env` file for the providers I plan to use.
4. Create a `src/ai/client.ts` that instantiates an `llm` instance using the provider of my choice.
5. Wire up a simple Express route (or equivalent) that calls `model.generate()` and returns the response as JSON.
6. Add a streaming endpoint that uses `model.stream()` and pipes `text_delta` events to the client as Server-Sent Events.
7. Show me how to add a tool with a Zod schema to the `llm` instance.

Use only the exports documented in `USAGE.md`. Do not invent method names or import paths.

License and credit

See source/LICENSE if present in the vendored directory. The upstream package is @providerprotocol/ai (version 0.0.44). Refer to the upstream repository for the authoritative license terms.

This product’s unique contribution is clean room implementation of valuable code block into AVCP compatible standard.

The full install guide and integration prompts unlock after purchase.

Vercel AI SDK Multi-Provider TypeScript Toolkit

SaaS, AI & Subscription Products

Free