provider-kit 0.1.0

package/README.md

@@ -0,0 +1,126 @@
+# @openchat/provider-kit
+
+**One API for 42 LLM providers.** OpenAI, Anthropic, Ollama, OpenRouter, Google Gemini, Azure, AWS Bedrock, Cohere — same interface, built-in retry and timeout.
+
+```js
+import { createProvider } from '@openchat/provider-kit'
+
+const provider = await createProvider('openai', { apiKey: 'sk-...' })
+const reply = await provider.chat('gpt-4', [
+  { role: 'user', content: 'Hello' }
+])
+// { content: '...', model: 'gpt-4', usage: { prompt_tokens: 10, completion_tokens: 20 } }
+```
+
+## Install
+
+```bash
+npm install @openchat/provider-kit
+```
+
+## Usage
+
+### Basic chat
+
+```js
+import { createProvider } from '@openchat/provider-kit'
+
+const provider = await createProvider('openai', { apiKey: process.env.OPENAI_API_KEY })
+const reply = await provider.chat('gpt-4o-mini', [
+  { role: 'system', content: 'You are a poet' },
+  { role: 'user', content: 'Write a haiku' },
+])
+console.log(reply.content)
+```
+
+### With retry and timeout
+
+```js
+import { safeProviderCall } from '@openchat/provider-kit'
+
+const reply = await safeProviderCall(
+  () => provider.chat('gpt-4', messages),
+  { provider: 'openai', retries: 3, timeout: 30000 }
+)
+```
+
+### Available providers
+
+| Provider | `type` | Requires |
+|----------|--------|----------|
+| OpenAI | `openai` | `OPENAI_API_KEY` |
+| Anthropic | `anthropic` | `ANTHROPIC_API_KEY` |
+| Ollama | `ollama` | local server at `http://localhost:11434` |
+| Azure OpenAI | `azure` | Azure credentials |
+| AWS Bedrock | `bedrock` | AWS credentials |
+| Cohere | `cohere` | `COHERE_API_KEY` |
+| Google Gemini | `gemini` | `GEMINI_API_KEY` |
+| OpenAI-compatible | `openai` with custom `baseUrl` | Any OpenAI-compatible API |
+
+### Streaming
+
+```js
+const stream = await provider.chatStream('gpt-4', messages)
+for await (const chunk of stream) {
+  if (chunk.type === 'content') process.stdout.write(chunk.content)
+}
+```
+
+### Error handling
+
+`createProvider`, `.chat()`, `.chatStream()` — all throw `ProviderError` with consistent fields:
+
+```js
+import { ProviderError } from '@openchat/provider-kit'
+
+try { /* ... */ } catch (e) {
+  if (e instanceof ProviderError) {
+    console.log(e.provider, e.statusCode, e.retryable, e.type)
+    // e.g. 'openai', 429, true, 'rate_limit'
+  }
+}
+```
+
+### Function Calling
+
+```js
+const reply = await provider.chat('gpt-4', messages, {
+  tools: [{
+    type: 'function',
+    function: {
+      name: 'get_weather',
+      description: 'Get weather for a city',
+      parameters: { type: 'object', properties: { city: { type: 'string' } } }
+    }
+  }]
+})
+if (reply.toolCalls) {
+  // [{ id, name, arguments: { city: 'Tokyo' } }]
+}
+```
+
+## ProviderRegistry
+
+Manage multiple providers with a registry:
+
+```js
+import { providerRegistry, createProvider } from '@openchat/provider-kit'
+
+await providerRegistry.configure('openai', { apiKey: 'sk-...' })
+await providerRegistry.configure('ollama', { baseUrl: 'http://localhost:11434' })
+
+const provider = providerRegistry.get('openai')
+const reply = await provider.chat('gpt-4', messages)
+```
+
+## Known Limitations (v0.1.0)
+
+- **No config persistence by default.** API keys must be passed on every `createProvider()` call. Use `createStore()` for persistent config.
+- **10 adapters implemented out of 42 presets.** The remaining 32 use OpenAI-compatible fallback. Contributions welcome.
+- **No TypeScript types.** Planned for v0.2.0.
+- **Not for production.** API keys are stored in memory. No OS keychain integration.
+- **`.provider-kit.json` should be added to `.gitignore`** if you choose to use file persistence via `createStore()`.
+
+## Related
+
+- `@openchat/fairy-guardian` — self-healing process cluster for AI model servers

package/package.json

@@ -0,0 +1,19 @@
+{
+  "name": "provider-kit",
+  "version": "0.1.0",
+  "description": "42 LLM provider unified API — one interface for OpenAI, Anthropic, Ollama, OpenRouter, and 38 more. Built-in retry, timeout, and error handling.",
+  "type": "module",
+  "main": "./src/index.js",
+  "exports": { ".": "./src/index.js" },
+  "files": ["src/", "README.md"],
+  "scripts": {
+    "test": "node --test test/*.test.js",
+    "prepublishOnly": "npm test",
+    "version": "git add -A src/ CHANGELOG.md",
+    "postversion": "git push && git push --tags"
+  },
+  "keywords": ["llm", "openai", "anthropic", "ollama", "provider", "api"],
+  "license": "MIT",
+  "engines": { "node": ">=18" },
+  "repository": { "type": "git", "url": "https://github.com/openchat-ai/openchat" }
+}

package/src/core/persistent-config.js

@@ -0,0 +1,107 @@
+/**
+ * Persistent config for @openchat/provider-kit
+ *
+ * Lookup order:
+ *   1. PROVIDER_KIT_CONFIG_PATH 环境变量
+ *   2. cwd/.provider-kit.json
+ *   3. 内存（不写文件）
+ *
+ * 绝不写 ~/ 目录。这是公共 npm 包，不是 OpenChat 专属.
+ */
+
+import { resolve } from 'path';
+import { existsSync, readFileSync, writeFileSync, mkdirSync } from 'fs';
+
+function resolveConfigPath() {
+  const envPath = process.env.PROVIDER_KIT_CONFIG_PATH;
+  if (envPath) return resolve(envPath);
+  const cwdPath = resolve(process.cwd(), '.provider-kit.json');
+  if (existsSync(cwdPath)) return cwdPath;
+  return null;
+}
+
+const CONFIG_PATH = resolveConfigPath();
+
+class PersistentConfig {
+  constructor() {
+    this._store = {};
+    this._apiKeys = {};
+    this._readOnly = !CONFIG_PATH;
+    this._load();
+  }
+
+  _load() {
+    if (!CONFIG_PATH) return; // memory only
+    try {
+      const data = JSON.parse(readFileSync(CONFIG_PATH, 'utf8'));
+      this._store = data.store || {};
+      this._apiKeys = data.apiKeys || {};
+    } catch {
+      this._store = {};
+      this._apiKeys = {};
+    }
+  }
+
+  _save() {
+    if (this._readOnly) return;
+    try {
+      mkdirSync(resolve(CONFIG_PATH, '..'), { recursive: true });
+      writeFileSync(CONFIG_PATH, JSON.stringify({ store: this._store, apiKeys: this._apiKeys }, null, 2), 'utf8');
+    } catch {
+      // silent: 只读容器 / 权限不足
+    }
+  }
+
+  getApiKey(provider) {
+    return this._apiKeys[provider] || process.env[`${provider.toUpperCase()}_API_KEY`] || '';
+  }
+
+  setApiKey(provider, key) {
+    this._apiKeys[provider] = key;
+    this._save();
+  }
+
+  removeApiKey(provider) {
+    delete this._apiKeys[provider];
+    this._save();
+  }
+
+  listKeys() {
+    return Object.keys(this._apiKeys);
+  }
+
+  getPreference(key) {
+    return this._store[key];
+  }
+
+  setPreference(key, val) {
+    this._store[key] = val;
+    this._save();
+  }
+
+  getBridgeConfig() {
+    return this._store;
+  }
+}
+
+export const persistentConfig = new PersistentConfig();
+
+/**
+ * createStore — DI 模式：自定义存储实现
+ * 用于框架集成者（Next.js、Remix、Bridge 等）传入自己的持久化方案
+ *
+ * 示例:
+ *   const store = createStore({ load: () => db.get('config'), save: (d) => db.set('config', d) });
+ *   store.setApiKey('openai', 'sk-xxx');
+ */
+export function createStore(impl = {}) {
+  const store = new PersistentConfig();
+  if (impl.apiKeys) store._apiKeys = impl.apiKeys;
+  if (impl.store) store._store = impl.store;
+  if (impl.load) { try { const d = impl.load(); if (d) { store._apiKeys = d.apiKeys || {}; store._store = d.store || {}; } } catch {} }
+  if (impl.save) { const origSave = store._save.bind(store); store._save = () => { origSave(); impl.save({ apiKeys: store._apiKeys, store: store._store }); }; }
+  if (impl.onSave) store._save = impl.onSave;
+  return store;
+}
+
+export default persistentConfig;

package/src/index.js

@@ -0,0 +1,16 @@
+/**
+ * @openchat/provider-kit
+ *
+ * 42 LLM provider unified API — one interface for OpenAI, Anthropic,
+ * Ollama, OpenRouter, and 38 more.
+ *
+ * Quick start:
+ *   import { providerRegistry, createProvider } from '@openchat/provider-kit';
+ *   const provider = createProvider('openai', { apiKey: 'sk-...' });
+ *   const reply = await provider.chat('gpt-4', [{ role: 'user', content: 'Hi' }]);
+ */
+
+export { ProviderError, AbortError, withRetry, withTimeout, safeProviderCall, classifyError, createCancelSignal } from './providers/provider-error-adapter.js';
+export { ProviderManager, providerManager } from './providers/provider-manager.js';
+export { providerRegistry, createProvider, listPresetProviders, PRESET_PROVIDERS } from './providers/provider-registry.js';
+export { persistentConfig, createStore } from './core/persistent-config.js';

package/src/providers/anthropic-adapter.js

@@ -0,0 +1,368 @@
+import { ProviderError } from './provider-error-adapter.js';
+import fs from 'fs';
+import path from 'path';
+import { fileURLToPath } from 'url';
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+
+/**
+ * Anthropic Claude API 适配器
+ *
+ * Anthropic 使用独特的 Messages API 格式，与 OpenAI 不同：
+ * - Endpoint: /v1/messages (不是 /chat/completions)
+ * - Header: x-api-key (不是 Authorization: Bearer)
+ * - 请求格式: { model, messages, max_tokens, ... }
+ * - 响应格式: { id, content: [{ type: 'text', text: '...' }], ... }
+ *
+ * 参考文档: https://docs.anthropic.com/claude/reference/messages_post
+ */
+
+// 加载用户配置
+function loadModelConfig() {
+  try {
+    const configPath = path.join(__dirname, '../config/model-selection.json');
+    if (fs.existsSync(configPath)) {
+      const data = fs.readFileSync(configPath, 'utf8');
+      const config = JSON.parse(data);
+      return config.modelSelection?.anthropic || {};
+    }
+  } catch (e) {
+    console.warn('[AnthropicAdapter] Failed to load model config:', e.message);
+  }
+  return {};
+}
+
+const modelConfig = loadModelConfig();
+
+export class AnthropicAdapter {
+  constructor(config) {
+    this.id = config.id || 'anthropic';
+    this.name = config.name || 'Claude';
+    this.nameCn = config.nameCn || 'Anthropic Claude';
+    this.baseUrl = config.baseUrl || 'https://api.anthropic.com';
+    this.apiKey = config.apiKey || null;
+
+    // 完全从配置读取模型，配置有什么就用什么
+    this.defaultModel = config.defaultModel || modelConfig.defaultModel || null;
+
+    // 可用模型列表完全来自配置
+    this.models = config.models || modelConfig.availableModels || [];
+    this.connected = false;
+    this.description = config.description || 'Anthropic Claude 系列模型';
+
+    // Anthropic 特定配置
+    this.anthropicVersion = config.anthropicVersion || '2023-06-01';
+    this.timeout = config.timeout || 60000;
+    this.headers = config.headers || {};
+  }
+
+  /**
+   * 连接/验证 API Key
+   */
+  async connect(apiKey) {
+    if (apiKey) this.apiKey = apiKey;
+
+    if (!this.apiKey) {
+      throw new ProviderError('API Key required for Anthropic Claude');
+    }
+
+    // Anthropic 没有 /models 端点，直接测试连接
+    try {
+      // 发送一个简单的测试请求
+      await this.chat(this.defaultModel, [
+        { role: 'user', content: 'Hi' }
+      ], { max_tokens: 10 });
+
+      this.connected = true;
+      return true;
+    } catch (e) {
+      // 如果有 API Key，假定连接成功
+      if (this.apiKey) {
+        this.connected = true;
+        return true;
+      }
+      throw e;
+    }
+  }
+
+  /**
+   * 断开连接
+   */
+  disconnect() {
+    this.connected = false;
+  }
+
+  /**
+   * 转换消息格式: OpenAI -> Anthropic
+   *
+   * OpenAI:  [{ role: 'system', content: '...' }, { role: 'user', content: '...' }]
+   * Anthropic: system: '...', messages: [{ role: 'user', content: '...' }]
+   */
+  convertMessages(messages) {
+    const systemMessages = [];
+    const anthropicMessages = [];
+
+    for (const msg of messages) {
+      if (msg.role === 'system') {
+        systemMessages.push(msg.content);
+      } else if (msg.role === 'user' || msg.role === 'assistant') {
+        anthropicMessages.push({
+          role: msg.role,
+          content: typeof msg.content === 'string'
+            ? msg.content
+            : JSON.stringify(msg.content)
+        });
+      }
+    }
+
+    return {
+      system: systemMessages.join('\n\n'),
+      messages: anthropicMessages
+    };
+  }
+
+  /**
+   * 转换响应格式: Anthropic -> OpenAI
+   */
+  convertResponse(anthropicResponse) {
+    const content = anthropicResponse.content
+      .filter(c => c.type === 'text')
+      .map(c => c.text)
+      .join('');
+
+    return {
+      content,
+      model: anthropicResponse.model,
+      usage: {
+        prompt_tokens: anthropicResponse.usage?.input_tokens || 0,
+        completion_tokens: anthropicResponse.usage?.output_tokens || 0,
+        total_tokens: (anthropicResponse.usage?.input_tokens || 0) +
+                     (anthropicResponse.usage?.output_tokens || 0)
+      },
+      raw: anthropicResponse
+    };
+  }
+
+  /**
+   * 发送聊天消息
+   */
+  async chat(model, messages, options = {}) {
+    if (!this.connected) {
+      throw new ProviderError('Anthropic provider not connected');
+    }
+
+    const url = `${this.baseUrl}/v1/messages`;
+
+    const { system, messages: anthropicMessages } = this.convertMessages(messages);
+
+    const body = {
+      model: model || this.defaultModel,
+      messages: anthropicMessages,
+      max_tokens: options.max_tokens || options.maxTokens || 4096,
+      stream: options.stream || false
+    };
+
+    // 添加 system 消息
+    if (system) {
+      body.system = system;
+    }
+
+    // 可选参数
+    if (options.temperature !== undefined) {
+      body.temperature = options.temperature;
+    }
+    if (options.top_p !== undefined) {
+      body.top_p = options.top_p;
+    }
+    if (options.top_k !== undefined) {
+      body.top_k = options.top_k;
+    }
+
+    // Tool Use (Function Calling)
+    if (options.tools && options.tools.length > 0) {
+      body.tools = this.convertTools(options.tools);
+    }
+
+    const headers = {
+      'Content-Type': 'application/json',
+      'x-api-key': this.apiKey,
+      'anthropic-version': this.anthropicVersion,
+      ...this.headers
+    };
+
+    const response = await fetch(url, {
+      method: 'POST',
+      headers,
+      body: JSON.stringify(body),
+      signal: this.timeout ? AbortSignal.timeout(this.timeout) : undefined
+    });
+
+    if (!response.ok) {
+      const error = await response.json().catch(() => ({}));
+      throw new ProviderError(
+        error.error?.message ||
+        `Anthropic API error: ${response.status} ${response.statusText}`
+      );
+    }
+
+    const data = await response.json();
+    return this.convertResponse(data);
+  }
+
+  /**
+   * 流式聊天
+   */
+  async *chatStream(model, messages, options = {}) {
+    if (!this.connected) {
+      throw new ProviderError('Anthropic provider not connected');
+    }
+
+    const url = `${this.baseUrl}/v1/messages`;
+
+    const { system, messages: anthropicMessages } = this.convertMessages(messages);
+
+    const body = {
+      model: model || this.defaultModel,
+      messages: anthropicMessages,
+      max_tokens: options.max_tokens || options.maxTokens || 4096,
+      stream: true
+    };
+
+    if (system) {
+      body.system = system;
+    }
+
+    if (options.temperature !== undefined) {
+      body.temperature = options.temperature;
+    }
+    if (options.top_p !== undefined) {
+      body.top_p = options.top_p;
+    }
+
+    if (options.tools && options.tools.length > 0) {
+      body.tools = this.convertTools(options.tools);
+    }
+
+    const headers = {
+      'Content-Type': 'application/json',
+      'x-api-key': this.apiKey,
+      'anthropic-version': this.anthropicVersion,
+      ...this.headers
+    };
+
+    const response = await fetch(url, {
+      method: 'POST',
+      headers,
+      body: JSON.stringify(body),
+      signal: this.timeout ? AbortSignal.timeout(this.timeout) : undefined
+    });
+
+    if (!response.ok) {
+      const error = await response.json().catch(() => ({}));
+      throw new ProviderError(
+        error.error?.message ||
+        `Anthropic API error: ${response.status} ${response.statusText}`
+      );
+    }
+
+    const reader = response.body.getReader();
+    const decoder = new TextDecoder();
+    let buffer = '';
+
+    while (true) {
+      const { done, value } = await reader.read();
+      if (done) break;
+
+      buffer += decoder.decode(value, { stream: true });
+      const lines = buffer.split('\n');
+      buffer = lines.pop() || '';
+
+      for (const line of lines) {
+        if (line.startsWith('data: ')) {
+          const data = line.slice(6);
+
+          try {
+            const json = JSON.parse(data);
+
+            // 处理不同的事件类型
+            if (json.type === 'content_block_delta') {
+              const delta = json.delta;
+              if (delta?.type === 'text_delta' && delta.text) {
+                yield { type: 'content', content: delta.text, done: false };
+              }
+            } else if (json.type === 'message_stop') {
+              yield { done: true };
+              return;
+            }
+          } catch (e) {
+            // 忽略解析错误
+          }
+        }
+      }
+    }
+
+    yield { done: true };
+  }
+
+  /**
+   * 转换工具格式: OpenAI tools -> Anthropic tools
+   */
+  convertTools(openaiTools) {
+    return openaiTools.map(tool => ({
+      name: tool.function.name,
+      description: tool.function.description || '',
+      input_schema: tool.function.parameters || {
+        type: 'object',
+        properties: {}
+      }
+    }));
+  }
+
+  /**
+   * 获取模型列表
+   */
+  async fetchModels() {
+    // Anthropic 没有 /models 端点，返回硬编码列表
+    return this.models;
+  }
+
+  /**
+   * 获取模型列表（本地）
+   */
+  getModels() {
+    return this.models;
+  }
+
+  /**
+   * 获取状态
+   */
+  getStatus() {
+    return {
+      id: this.id,
+      name: this.name,
+      nameCn: this.nameCn,
+      baseUrl: this.baseUrl,
+      connected: this.connected,
+      modelCount: this.models.length,
+      defaultModel: this.defaultModel,
+      hasApiKey: !!this.apiKey,
+      transport: 'anthropic_messages'
+    };
+  }
+}
+
+/**
+ * 创建 Anthropic Provider
+ */
+export function createAnthropicProvider(apiKey = null, overrides = {}) {
+  return new AnthropicAdapter({
+    id: 'anthropic',
+    name: 'Claude',
+    nameCn: 'Anthropic Claude',
+    baseUrl: 'https://api.anthropic.com',
+    apiKey,
+    ...overrides
+  });
+}
+
+export default AnthropicAdapter;