@prysm-ai/llm 0.3.0

package/src/provider/openai.ts

@@ -0,0 +1,280 @@
+import OpenAI from 'openai';
+import type { ChatMessage, LLMResponse, LLMRequestOptions, ModelInfo } from '../types';
+import type { MessageContent, MessagePart } from '../content';
+import { BaseLLMProvider } from '../base';
+
+/**
+ * 流式输出选项
+ * 继承 LLMRequestOptions 的所有选项，额外提供流式回调
+ */
+export interface StreamingOptions extends Omit<LLMRequestOptions, 'stream'> {
+  /** 标记为流式请求 */
+  stream: true;
+  /** 流式块回调，每次收到内容片段时触发 */
+  onChunk?: (chunk: string) => void;
+  /** 流式完成回调，传入完整内容 */
+  onComplete?: (fullContent: string) => void;
+  /** 错误回调 */
+  onError?: (error: Error) => void;
+}
+
+/**
+ * OpenAI Provider 配置
+ */
+export interface OpenAIProviderConfig {
+  /** API 密钥 */
+  apiKey: string;
+  /** 可选的 API 基础地址，用于代理 */
+  baseUrl?: string;
+  /** 可选的 API 路径 */
+  apiPath?: string;
+  /** 可选的超时时间（毫秒） */
+  timeoutMs?: number;
+}
+
+/**
+ * OpenAI LLM Provider 实现类
+ * 支持 OpenAI GPT 系列模型的对话和流式输出
+ */
+export class OpenAIProvider extends BaseLLMProvider {
+  /** 提供商类型标识 */
+  readonly provider: 'openai' = 'openai';
+
+  /** 默认使用的模型 */
+  override readonly defaultModel = 'gpt-4o';
+
+  /** OpenAI SDK 客户端实例 */
+  private client: OpenAI;
+
+  /**
+   * 创建 OpenAI Provider 实例
+   * @param config - 提供者配置，包含 apiKey 和可选的 baseUrl
+   */
+  constructor(config: OpenAIProviderConfig) {
+    super(config.apiKey, config.baseUrl);
+    this.client = new OpenAI({
+      apiKey: config.apiKey,
+      baseURL: config.baseUrl,
+    });
+  }
+
+  /**
+   * 发送对话请求（非流式）
+   * @param messages - 对话消息列表
+   * @param options - 请求选项，包含模型、温度等参数
+   * @returns LLM 响应结果
+   */
+  async chat(messages: ChatMessage[], options: LLMRequestOptions = { model: this.defaultModel }): Promise<LLMResponse> {
+    const openaiMessages = messages.map(msg => this.normalizeMessage(msg));
+
+    const createOptions: OpenAI.Chat.ChatCompletionCreateParamsNonStreaming = {
+      model: options.model,
+      messages: openaiMessages as OpenAI.Chat.ChatCompletionMessageParam[],
+    };
+
+    if (options.temperature !== undefined) {
+      createOptions.temperature = options.temperature;
+    }
+    if (options.maxTokens !== undefined) {
+      createOptions.max_tokens = options.maxTokens;
+    }
+    if (options.topP !== undefined) {
+      createOptions.top_p = options.topP;
+    }
+    if (options.tools !== undefined) {
+      createOptions.tools = options.tools as OpenAI.Chat.ChatCompletionTool[];
+    }
+    if (options.toolChoice !== undefined) {
+      createOptions.tool_choice = options.toolChoice as OpenAI.Chat.ChatCompletionToolChoiceOption;
+    }
+    if (options.stop !== undefined) {
+      createOptions.stop = options.stop;
+    }
+    if (options.responseFormat !== undefined) {
+      (createOptions as unknown as Record<string, unknown>).response_format = options.responseFormat;
+    }
+
+    try {
+      const response = await this.client.chat.completions.create(createOptions);
+
+      const choice = response.choices[0]!;
+      const message = choice.message;
+
+      const result: LLMResponse = {
+        id: response.id,
+        model: response.model,
+        role: 'assistant',
+        content: message.content ?? '',
+        finishReason: mapFinishReason(choice.finish_reason),
+        usage: {
+          promptTokens: response.usage?.prompt_tokens ?? 0,
+          completionTokens: response.usage?.completion_tokens ?? 0,
+          totalTokens: response.usage?.total_tokens ?? 0,
+        },
+      };
+
+      if (message.tool_calls) {
+        result.toolCalls = message.tool_calls.map(tc => ({
+          id: tc.id!,
+          type: 'function' as const,
+          function: {
+            name: tc.function!.name,
+            arguments: tc.function!.arguments,
+          },
+        }));
+      }
+
+      return result;
+    } catch (error) {
+      if (error instanceof Error) {
+        throw new Error(`OpenAI API error: ${error.message}`);
+      }
+      throw new Error(`OpenAI API error: ${String(error)}`);
+    }
+  }
+
+  /**
+   * 发送流式对话请求
+   * @param messages - 对话消息列表
+   * @param options - 流式选项，包含 onChunk、onComplete、onError 回调
+   */
+  async chatStream(messages: ChatMessage[], options: StreamingOptions): Promise<void> {
+    const openaiMessages = messages.map(msg => this.normalizeMessage(msg));
+
+    const createOptions: OpenAI.Chat.ChatCompletionCreateParamsStreaming = {
+      model: options.model,
+      messages: openaiMessages as OpenAI.Chat.ChatCompletionMessageParam[],
+      stream: true,
+    };
+
+    if (options.temperature !== undefined) {
+      createOptions.temperature = options.temperature;
+    }
+    if (options.maxTokens !== undefined) {
+      createOptions.max_tokens = options.maxTokens;
+    }
+    if (options.topP !== undefined) {
+      createOptions.top_p = options.topP;
+    }
+    if (options.stop !== undefined) {
+      createOptions.stop = options.stop;
+    }
+    if (options.tools !== undefined) {
+      createOptions.tools = options.tools as OpenAI.Chat.ChatCompletionTool[];
+    }
+
+    try {
+      const response = await this.client.chat.completions.create(createOptions as any);
+      let fullContent = '';
+
+      // 处理异步迭代器和同步迭代器两种响应类型
+      const stream = response as any;
+      if (typeof stream[Symbol.asyncIterator] === 'function') {
+        for await (const chunk of stream) {
+          const content = chunk.choices?.[0]?.delta?.content;
+          if (content) {
+            fullContent += content;
+            options.onChunk?.(content);
+          }
+        }
+      } else if (typeof stream[Symbol.iterator] === 'function') {
+        for (const chunk of stream) {
+          const content = chunk.choices?.[0]?.delta?.content;
+          if (content) {
+            fullContent += content;
+            options.onChunk?.(content);
+          }
+        }
+      }
+
+      options.onComplete?.(fullContent);
+    } catch (error) {
+      options.onError?.(error instanceof Error ? error : new Error(String(error)));
+      throw error;
+    }
+  }
+
+  /**
+   * 规范化消息格式
+   * 将通用 ChatMessage 转换为 OpenAI 格式
+   * @param msg - 原始消息
+   * @returns OpenAI 格式的消息
+   */
+  private normalizeMessage(msg: ChatMessage): { role: string; content: string | OpenAI.Chat.ChatCompletionContentPart[]; name?: string; tool_calls?: unknown; tool_call_id?: string } {
+    const result: { role: string; content: string | OpenAI.Chat.ChatCompletionContentPart[]; name?: string; tool_calls?: unknown; tool_call_id?: string } = {
+      role: msg.role,
+      content: this.normalizeContent(msg.content),
+    };
+    if (msg.name !== undefined) result.name = msg.name;
+    if (msg.toolCalls !== undefined) result.tool_calls = msg.toolCalls;
+    if (msg.toolCallId !== undefined) result.tool_call_id = msg.toolCallId;
+    return result;
+  }
+
+  /**
+   * 规范化消息内容
+   * 将字符串或消息片段数组转换为 OpenAI 格式
+   * @param content - 原始内容
+   * @returns OpenAI 格式的内容
+   */
+  private normalizeContent(content: MessageContent): string | OpenAI.Chat.ChatCompletionContentPart[] {
+    if (typeof content === 'string') {
+      return content;
+    }
+    return content.map((part: MessagePart) => {
+      if (part.type === 'text') {
+        return { type: 'text', text: part.text } as OpenAI.Chat.ChatCompletionContentPart;
+      }
+      if (part.type === 'image_url') {
+        return { type: 'image_url', image_url: part.image_url } as OpenAI.Chat.ChatCompletionContentPart;
+      }
+      return { type: 'text', text: '' } as OpenAI.Chat.ChatCompletionContentPart;
+    });
+  }
+
+  /**
+   * 获取可用模型列表
+   * @returns 模型信息列表
+   */
+  async listModels(): Promise<ModelInfo[]> {
+    const models = await this.client.models.list();
+    return models.data.map(m => ({
+      provider: 'openai' as const,
+      model: m.id,
+      displayName: m.id,
+      contextWindow: 128000,
+      supportsTools: true,
+      supportsVision: m.id.includes('vision'),
+    }));
+  }
+
+  /**
+   * 验证 API 密钥是否有效
+   * @returns 密钥是否有效
+   */
+  async validateKey(): Promise<boolean> {
+    try {
+      await this.client.models.list();
+      return true;
+    } catch {
+      return false;
+    }
+  }
+}
+
+/**
+ * 映射 finish reason
+ * 将 OpenAI 的 finish_reason 转换为通用格式
+ * @param reason - OpenAI 返回的 finish_reason
+ * @returns 通用 finish reason
+ */
+function mapFinishReason(reason: string | null): LLMResponse['finishReason'] {
+  switch (reason) {
+    case 'stop': return 'stop';
+    case 'length': return 'length';
+    case 'content_filter': return 'content_filter';
+    case 'tool_calls': return 'tool_calls';
+    case 'function_call': return 'function_call';
+    default: return 'stop';
+  }
+}

package/src/provider/proxy.ts

@@ -0,0 +1,171 @@
+import type { ChatMessage, LLMResponse, LLMRequestOptions, ModelInfo } from '../types';
+import { StreamingOptions } from './openai';
+import { AnthropicStreamingOptions } from './anthropic';
+import { BaseLLMProvider } from '../base';
+import { LLMProviderType } from '../constants';
+import { AnthropicProvider } from './anthropic';
+import { OpenAIProvider } from './openai';
+
+// 配置接口
+export interface ProxyProviderConfig {
+  provider?: LLMProviderType;
+  apiKey?: string;
+  baseUrl?: string;
+  apiPath?: string;
+  timeoutMs?: number;
+  defaultModel?: string;
+}
+
+// 运行时配置
+export interface RuntimeConfig {
+  apiKey?: string;
+  baseUrl?: string;
+  model?: string;
+}
+
+// 内部实现类
+class ProxyProviderImpl extends BaseLLMProvider {
+  readonly provider: LLMProviderType;
+  override readonly defaultModel: string;
+
+  private actualProvider: BaseLLMProvider | null = null;
+  private currentConfig: ProxyProviderConfig;
+
+  constructor(config?: ProxyProviderConfig) {
+    super(config?.apiKey, config?.baseUrl);
+    this.provider = config?.provider ?? LLMProviderType.Anthropic;
+    this.defaultModel = config?.defaultModel ?? this.getDefaultModel(this.provider);
+    this.currentConfig = config ?? {};
+
+    if (config?.apiKey && config?.provider) {
+      this.actualProvider = this.createProvider(config);
+    }
+  }
+
+  private getDefaultModel(provider: LLMProviderType | string): string {
+    const providerType = provider as LLMProviderType;
+    return providerType === LLMProviderType.OpenAI ? 'gpt-4o' : 'claude-3-5-sonnet-20241022';
+  }
+
+  private createProvider(config: ProxyProviderConfig): BaseLLMProvider {
+    if (!config.provider || !config.apiKey) {
+      throw new Error('provider and apiKey are required');
+    }
+
+    const providerType = config.provider as LLMProviderType;
+
+    if (providerType === LLMProviderType.OpenAI) {
+      return new OpenAIProvider({
+        apiKey: config.apiKey,
+        ...(config.baseUrl ? { baseUrl: config.baseUrl } : {}),
+        ...(config.apiPath ? { apiPath: config.apiPath } : {}),
+        ...(config.timeoutMs ? { timeoutMs: config.timeoutMs } : {}),
+      });
+    } else {
+      return new AnthropicProvider({
+        apiKey: config.apiKey,
+        ...(config.baseUrl ? { baseUrl: config.baseUrl } : {}),
+        ...(config.apiPath ? { apiPath: config.apiPath } : {}),
+        ...(config.timeoutMs ? { timeoutMs: config.timeoutMs } : {}),
+      });
+    }
+  }
+
+  setProvider(config: ProxyProviderConfig): void {
+    if (!config.provider || !config.apiKey) {
+      throw new Error('provider and apiKey are required');
+    }
+    this.currentConfig = config;
+    this.actualProvider = this.createProvider(config);
+  }
+
+  updateConfig(config: RuntimeConfig): void {
+    if (config.apiKey || config.baseUrl) {
+      const newConfig: ProxyProviderConfig = {
+        ...this.currentConfig,
+        ...(config.apiKey ? { apiKey: config.apiKey } : {}),
+        ...(config.baseUrl ? { baseUrl: config.baseUrl } : {}),
+      };
+      this.currentConfig = newConfig;
+      this.actualProvider = this.createProvider(newConfig);
+    }
+  }
+
+  setModel(model: string): void {
+    this.currentConfig.defaultModel = model;
+  }
+
+  private ensureProvider(): BaseLLMProvider {
+    if (!this.actualProvider) {
+      throw new Error('Provider not initialized. Call setProvider() first.');
+    }
+    return this.actualProvider;
+  }
+
+  async chat(messages: ChatMessage[], options?: LLMRequestOptions): Promise<LLMResponse> {
+    const provider = this.ensureProvider();
+    const finalOptions: LLMRequestOptions = {
+      ...options,
+      model: options?.model ?? this.defaultModel,
+    };
+    return provider.chat(messages, finalOptions);
+  }
+
+  async chatStream(messages: ChatMessage[], options: StreamingOptions): Promise<void> {
+    const provider = this.ensureProvider();
+    const finalOptions = {
+      ...options,
+      model: options.model ?? this.currentConfig.defaultModel,
+    };
+
+    if (this.provider === LLMProviderType.Anthropic) {
+      return (provider as AnthropicProvider).chatStream(messages, finalOptions as AnthropicStreamingOptions);
+    }
+    return (provider as OpenAIProvider).chatStream(messages, finalOptions);
+  }
+
+  async listModels(): Promise<ModelInfo[]> {
+    return this.ensureProvider().listModels();
+  }
+
+  async validateKey(): Promise<boolean> {
+    return this.ensureProvider().validateKey();
+  }
+}
+
+// Class 模式导出
+export { ProxyProviderImpl as ProxyProvider };
+
+// 函数模式配置（必须传参）
+export interface ProxyConfig {
+  provider: LLMProviderType;
+  apiKey: string;
+  baseUrl?: string;
+  apiPath?: string;
+  timeoutMs?: number;
+  defaultModel?: string;
+}
+
+// 函数模式返回值
+export interface ProxyFunctions {
+  chat: (messages: ChatMessage[], options?: LLMRequestOptions) => Promise<LLMResponse>;
+  chatStream: (messages: ChatMessage[], options: StreamingOptions) => Promise<void>;
+  listModels: () => Promise<ModelInfo[]>;
+  validateKey: () => Promise<boolean>;
+  setModel: (model: string) => void;
+  updateConfig: (config: RuntimeConfig) => void;
+}
+
+// 函数模式
+export function proxyProvider(config: ProxyConfig): ProxyFunctions {
+  const provider = new ProxyProviderImpl(config);
+
+  return {
+    chat: (messages, options) => provider.chat(messages, options),
+    chatStream: (messages, options) => provider.chatStream(messages, options),
+    listModels: () => provider.listModels(),
+    validateKey: () => provider.validateKey(),
+    setModel: (model) => provider.setModel(model),
+    updateConfig: (config) => provider.updateConfig(config),
+  };
+}

package/src/router.ts

@@ -0,0 +1,113 @@
+import type { ChatMessage, LLMResponse, LLMRequestOptions } from './types';
+import { BaseLLMProvider } from './base';
+
+class LLMError extends Error {
+  constructor(message: string, public context?: Record<string, unknown>) {
+    super(message);
+    this.name = 'LLMError';
+  }
+}
+
+export interface RouterConfig {
+  primaryProvider: BaseLLMProvider;
+  fallbackProviders?: BaseLLMProvider[];
+  defaultModel?: string;
+}
+
+interface ProviderHealth {
+  provider: BaseLLMProvider;
+  healthy: boolean;
+  lastCheck: number;
+}
+
+export class LLMRouter {
+  private primaryProvider: BaseLLMProvider;
+  private fallbackProviders: BaseLLMProvider[] = [];
+  private providerHealth: Map<string, ProviderHealth> = new Map();
+  private healthCheckIntervalMs = 30000;
+
+  constructor(config: RouterConfig) {
+    this.primaryProvider = config.primaryProvider;
+    this.fallbackProviders = config.fallbackProviders ?? [];
+  }
+
+  async chat(messages: ChatMessage[], options?: LLMRequestOptions): Promise<LLMResponse> {
+    const attemptOrder = this.getHealthyProviders();
+
+    for (const provider of attemptOrder) {
+      try {
+        return await provider.chat(messages, options);
+      } catch (error) {
+        this.markProviderUnhealthy(provider);
+        console.error(`Provider ${provider.provider} failed:`, error);
+
+        if (provider === attemptOrder[attemptOrder.length - 1]) {
+          throw new LLMError(`All LLM providers failed`, { originalError: error });
+        }
+      }
+    }
+
+    throw new LLMError('No available LLM providers');
+  }
+
+  private getHealthyProviders(): BaseLLMProvider[] {
+    const now = Date.now();
+    const healthy: BaseLLMProvider[] = [];
+
+    const primaryHealth = this.providerHealth.get(this.primaryProvider.provider);
+    if (!primaryHealth || (now - primaryHealth.lastCheck > this.healthCheckIntervalMs)) {
+      healthy.push(this.primaryProvider);
+    } else if (primaryHealth.healthy) {
+      healthy.push(this.primaryProvider);
+    }
+
+    for (const provider of this.fallbackProviders) {
+      const health = this.providerHealth.get(provider.provider);
+      if (!health || health.healthy) {
+        healthy.push(provider);
+      }
+    }
+
+    return healthy.length > 0 ? healthy : [this.primaryProvider];
+  }
+
+  private markProviderUnhealthy(provider: BaseLLMProvider): void {
+    this.providerHealth.set(provider.provider, {
+      provider,
+      healthy: false,
+      lastCheck: Date.now(),
+    });
+  }
+
+  async validateAllProviders(): Promise<Map<string, boolean>> {
+    const results = new Map<string, boolean>();
+
+    const primary = await this.primaryProvider.validateKey();
+    results.set(this.primaryProvider.provider, primary);
+    this.providerHealth.set(this.primaryProvider.provider, {
+      provider: this.primaryProvider,
+      healthy: primary,
+      lastCheck: Date.now(),
+    });
+
+    for (const provider of this.fallbackProviders) {
+      const healthy = await provider.validateKey();
+      results.set(provider.provider, healthy);
+      this.providerHealth.set(provider.provider, {
+        provider,
+        healthy,
+        lastCheck: Date.now(),
+      });
+    }
+
+    return results;
+  }
+
+  getPrimaryProvider(): BaseLLMProvider {
+    return this.primaryProvider;
+  }
+
+  addFallback(provider: BaseLLMProvider): void {
+    this.fallbackProviders.push(provider);
+  }
+}

package/src/types.ts

@@ -0,0 +1,77 @@
+import { z } from 'zod';
+import type { MessageContent } from './content';
+
+export const ChatMessageRoleSchema = z.enum(['system', 'user', 'assistant', 'tool']);
+export type ChatMessageRole = z.infer<typeof ChatMessageRoleSchema>;
+
+export interface ChatMessage {
+  id: string;
+  role: ChatMessageRole;
+  content: MessageContent;
+  name?: string;
+  toolCallId?: string;
+  toolCalls?: ToolCall[];
+  metadata?: Record<string, unknown>;
+}
+
+export interface ToolCall {
+  id: string;
+  type: 'function';
+  function: {
+    name: string;
+    arguments: string;
+  };
+}
+
+export interface LLMResponse {
+  id: string;
+  model: string;
+  role: 'assistant';
+  content: string;
+  toolCalls?: ToolCall[];
+  finishReason: 'stop' | 'length' | 'content_filter' | 'tool_calls' | 'function_call';
+  usage: {
+    promptTokens: number;
+    completionTokens: number;
+    totalTokens: number;
+  };
+  metadata?: Record<string, unknown>;
+}
+
+export interface EmbedResponse {
+  embeddings: number[][];
+  model: string;
+  usage?: {
+    promptTokens: number;
+    totalTokens: number;
+  };
+}
+
+export interface LLMRequestOptions {
+  model: string;
+  temperature?: number;
+  maxTokens?: number;
+  topP?: number;
+  tools?: unknown[];
+  toolChoice?: unknown;
+  responseFormat?: { type: 'text' | 'json_object' };
+  stop?: string[];
+  stream?: boolean;
+}
+
+export interface EmbedRequest {
+  model: string;
+  input: string | string[];
+}
+
+export type LLMProvider = 'openai' | 'anthropic' | 'local';
+
+export interface ModelInfo {
+  provider: LLMProvider;
+  model: string;
+  displayName: string;
+  contextWindow: number;
+  supportsTools: boolean;
+  supportsVision: boolean;
+  maxOutputTokens?: number;
+}

package/tsconfig.json

@@ -0,0 +1,9 @@
+{
+  "extends": "../../tsconfig.json",
+  "compilerOptions": {
+    "outDir": "./dist",
+    "rootDir": "./src"
+  },
+  "include": ["src/**/*"],
+  "exclude": ["node_modules", "dist", "tests"]
+}

package/vitest.config.ts

@@ -0,0 +1,14 @@
+import { defineConfig } from 'vitest/config';
+import { fileURLToPath } from 'url';
+import { dirname, resolve } from 'path';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+
+export default defineConfig({
+  test: {
+    globals: true,
+    environment: 'node',
+    setupFiles: [resolve(__dirname, './tests/setup/globals.ts')],
+  },
+});