@webneat/ai-sdk-pi

Use models configured in Pi with Vercel AI SDK 5. The provider uses Pi's model transports directly. It does not start the Pi or Codex CLI and does not execute model-requested tools itself.

Install

pnpm add @webneat/ai-sdk-pi ai

Node.js 22.19 or newer is required. Configure credentials with Pi before making requests:

pi auth login

Use any Pi provider

import { generateText } from 'ai'
import { createPi } from '@webneat/ai-sdk-pi'

const pi = createPi()
const model = pi('anthropic', 'claude-sonnet-4-5')

await pi.ready()

const result = await generateText({
  model,
  prompt: 'Explain typed errors in one paragraph.',
})

console.log(result.text)

ready() checks models already requested from that factory and verifies their provider credentials. Requests also initialize the runtime lazily, so calling ready() is optional.

Codex models use the same generic API:

const model = pi('openai-codex', 'gpt-5.6-luna', { reasoning: 'high' })

The package also exports a shared pi factory instance.

Use with @webneat/ai

Pass a Pi model to the models registry in system(). Text agents use generateText, including tool execution and follow-up requests. Data agents use generateObject for object, array, and enum schemas.

The adapter leaves tool execution and output-schema validation to the AI SDK. Pi handles model lookup, credentials, and transport. Requests use Pi's complete response directly.

Factory options

const pi = createPi({
  authPath: '/path/to/auth.json',
  modelsPath: '/path/to/models.json',
  defaults: {
    transport: 'sse',
    cacheRetention: 'none',
  },
})

Tests and applications may inject a Models runtime through the runtime option.

Per-request options

Use the pi provider-options key with the generic provider:

await generateText({
  model,
  prompt: 'Hello',
  providerOptions: {
    pi: {
      reasoning: 'medium',
      cacheRetention: 'short',
      sessionId: 'conversation-1',
    },
  },
})

Supported settings are:

• reasoning: off, minimal, low, medium, high, xhigh, or max
• transport: sse, websocket, or auto
• cacheRetention: none, short, or long
• sessionId: a caller-managed stable session ID
• textVerbosity: low, medium, or high for Codex Responses models

Unknown per-request Pi options produce warnings. Unknown factory defaults and model settings throw InvalidArgumentError. Settings must be plain objects, including null-prototype objects. Dates, maps, and class instances are rejected.

The adapter forwards AI SDK temperature, maximum output tokens, headers, and abort signals when Pi supports them. It reports warnings for ignored standard settings.

Provider capabilities

| Pi API | Required tool choice | Named tool choice | Reasoning | | --------------------------------------- | ------------------------------------- | --------------------------- | ---------------------- | | OpenAI Completions | required | OpenAI function selector | supported | | OpenAI Responses and Azure Responses | required | Responses function selector | supported | | OpenAI Codex Responses | required, with named tools filtered | supported | supported | | Anthropic Messages and Bedrock Converse | any | provider tool selector | supported | | Google Generative AI and Vertex | any, with named tools filtered | supported | supported | | Mistral Conversations | required | OpenAI function selector | supported values only | | Pi Messages | required | OpenAI function selector | supported | | Custom API strings | auto and none only | rejected | ignored with a warning |

The offline suite covers request mapping through the public provider without credentials. Credential-backed integration tests remain opt-in through PI_INTEGRATION=1.

Supported content

• Text and reasoning
• Client-executed function tools
• Structured JSON output through an internal tool
• Base64 and Uint8Array image input for image-capable models
• Text and image tool results
• Usage, cost, cache, response, and reasoning-signature metadata

The adapter rejects file URLs passed directly to doGenerate. The AI SDK can download remote images before calling the adapter. Non-image files are rejected, and provider-defined tools are reported as unsupported.

Structured output uses one internal tool and returns its value as JSON text. Combining JSON response format with application tools in the same request is not supported.

Generation and cancellation

Use generateText or generateObject. Streaming and raw event chunks are not supported. The required doStream method rejects with UnsupportedFunctionalityError without making a Pi request, so streamText and streamObject cannot be used with this provider.

A supplied abortSignal cancels generation. Pi may still use streaming internally to produce its complete response; the transport setting controls that underlying connection.

Development

The offline integration suite uses the built @webneat/ai workspace package. From the repository root:

pnpm --filter @webneat/ai build
pnpm --filter @webneat/ai-sdk-pi typecheck
pnpm --filter @webneat/ai-sdk-pi test
pnpm --filter @webneat/ai-sdk-pi build

Tests exercise the public provider and AI SDK calls, including @webneat/ai text and data agents, multi-step tools, conversation replay, request mapping, and explicit rejection of streaming. The injected runtime returns complete assistant messages and records requests; it does not simulate transport events. Live provider tests require PI_INTEGRATION=1 and configured credentials.

Security

The adapter never executes tool calls, starts a shell, or loads Pi extensions and skills. Pi's model runtime handles model lookup and credentials. Do not put authorization or cookie values in custom diagnostic output.