@earendil-works/pi-ai — 统一多 Provider LLM API

统一多 Provider LLM API，是 Pi monorepo 的最底层包。只包含支持工具调用（function calling）的模型。

安装

npm install @earendil-works/pi-ai

TypeBox 类型导出（Type、Static、TSchema）从本包重导出，无需单独依赖。

核心概念

Models 集合

Models 是 Provider 集合的入口，通过注册 Provider 工厂来管理模型。最快速方式是注册所有内置 Provider：

import { builtinModels } from '@earendil-works/pi-ai/providers/all';
const models = builtinModels();
const model = models.getModel('openai', 'gpt-4o-mini')!;

生产场景建议按需注册 Provider 以减少 bundle 体积。

Context

Context 是可序列化的对话状态，可以在不同模型之间传递（Cross-Provider Handoffs）：

const context: Context = {
  systemPrompt: 'You are a helpful assistant.',
  messages: [...],
  tools: [...]
};

流式 API

const s = models.stream(model, context);
for await (const event of s) {
  switch (event.type) {
    case 'text_delta':   process.stdout.write(event.delta); break;
    case 'tool_call':    /* 处理工具调用 */; break;
    case 'thinking_delta': /* reasoning 内容 */; break;
  }
}

工具定义

用 TypeBox schema 定义工具参数，兼顾类型安全和运行时验证：

const tools: Tool[] = [{
  name: 'get_weather',
  description: 'Get weather for a location',
  parameters: Type.Object({
    location: Type.String({ description: 'City name' }),
    unit: Type.Optional(Type.Union([Type.Literal('celsius'), Type.Literal('fahrenheit')]))
  })
}];

Auth 解析

Provider 按以下优先级解析认证：

构造 Provider 时传入的显式凭证
对应环境变量（如 ANTHROPIC_API_KEY、OPENAI_API_KEY）
Credential Store（OAuth 登录后保存）

特性列表

Thinking/Reasoning 统一接口（支持 streaming thinking content）
Cross-Provider Handoffs（同一 Context 跨模型传递）
Context 序列化/反序列化
Browser 环境支持（可 tree-shaking）
Bedrock Provider（独立 .js 文件，避免 AWS SDK 体积影响）
Faux Provider（用于测试，无需真实 API 调用）
Stop reason 统一枚举
AbortSignal 支持及中断后继续

相关页面：providers | pi-agent-core

Wiki AI

目录