@dangao/bun-server 1.12.1 → 2.0.0

package/src/ai/providers/openai-provider.ts

@@ -0,0 +1,242 @@
+import type { LlmProvider, AiRequest, AiResponse, AiMessage } from '../types';
+import { AiProviderError, AiRateLimitError, AiContextLengthError, AiTimeoutError } from '../errors';
+
+export interface OpenAIProviderConfig {
+  apiKey: string;
+  /** Default: https://api.openai.com/v1 */
+  baseUrl?: string;
+  /** Default: gpt-4o */
+  defaultModel?: string;
+  /** Pricing per 1M tokens (input/output) for cost estimation */
+  pricing?: Record<string, { input: number; output: number }>;
+}
+
+const DEFAULT_PRICING: Record<string, { input: number; output: number }> = {
+  'gpt-4o': { input: 2.5, output: 10 },
+  'gpt-4o-mini': { input: 0.15, output: 0.6 },
+  'gpt-4-turbo': { input: 10, output: 30 },
+  'gpt-3.5-turbo': { input: 0.5, output: 1.5 },
+};
+
+interface OpenAiToolCallFunction {
+  name?: string;
+  arguments?: string;
+}
+
+interface OpenAiToolCall {
+  id?: string;
+  function?: OpenAiToolCallFunction;
+}
+
+interface OpenAiMessage {
+  content?: string | null;
+  tool_calls?: OpenAiToolCall[];
+}
+
+interface OpenAiChoice {
+  message?: OpenAiMessage;
+  finish_reason?: string | null;
+}
+
+interface OpenAiUsage {
+  prompt_tokens?: number;
+  completion_tokens?: number;
+  total_tokens?: number;
+}
+
+interface OpenAiChatCompletionResponse {
+  choices?: OpenAiChoice[];
+  usage?: OpenAiUsage;
+}
+
+export class OpenAIProvider implements LlmProvider {
+  public readonly name = 'openai';
+  private readonly apiKey: string;
+  private readonly baseUrl: string;
+  private readonly defaultModel: string;
+  private readonly pricing: Record<string, { input: number; output: number }>;
+
+  public constructor(config: OpenAIProviderConfig) {
+    this.apiKey = config.apiKey;
+    this.baseUrl = (config.baseUrl ?? 'https://api.openai.com/v1').replace(/\/$/, '');
+    this.defaultModel = config.defaultModel ?? 'gpt-4o';
+    this.pricing = { ...DEFAULT_PRICING, ...(config.pricing ?? {}) };
+  }
+
+  public async complete(request: AiRequest): Promise<AiResponse> {
+    const model = request.model ?? this.defaultModel;
+    const body: Record<string, unknown> = {
+      model,
+      messages: request.messages,
+      temperature: request.temperature,
+      max_tokens: request.maxTokens,
+    };
+
+    if (request.tools && request.tools.length > 0) {
+      body['tools'] = request.tools.map((t) => ({
+        type: 'function',
+        function: { name: t.name, description: t.description, parameters: t.parameters },
+      }));
+    }
+
+    const response = await this.post('/chat/completions', body);
+    const choice = response.choices?.[0];
+    const usage = response.usage ?? { prompt_tokens: 0, completion_tokens: 0, total_tokens: 0 };
+    const message = choice?.message;
+
+    return {
+      content: message?.content ?? '',
+      toolCalls: message?.tool_calls?.map((tc) => ({
+        id: tc.id ?? '',
+        name: tc.function?.name ?? '',
+        arguments: this.safeParseToolArguments(tc.function?.arguments),
+      })),
+      model,
+      provider: this.name,
+      usage: {
+        promptTokens: usage.prompt_tokens ?? 0,
+        completionTokens: usage.completion_tokens ?? 0,
+        totalTokens: usage.total_tokens ?? 0,
+        estimatedCostUsd: this.estimateCost(
+          model,
+          usage.prompt_tokens ?? 0,
+          usage.completion_tokens ?? 0,
+        ),
+      },
+      finishReason: choice?.finish_reason === 'tool_calls' ? 'tool_calls' : 'stop',
+    };
+  }
+
+  public stream(request: AiRequest): ReadableStream<Uint8Array> {
+    const model = request.model ?? this.defaultModel;
+    const body: Record<string, unknown> = {
+      model,
+      messages: request.messages,
+      temperature: request.temperature,
+      max_tokens: request.maxTokens,
+      stream: true,
+    };
+
+    if (request.tools && request.tools.length > 0) {
+      body['tools'] = request.tools.map((t) => ({
+        type: 'function',
+        function: { name: t.name, description: t.description, parameters: t.parameters },
+      }));
+    }
+
+    const encoder = new TextEncoder();
+    const apiKey = this.apiKey;
+    const baseUrl = this.baseUrl;
+
+    return new ReadableStream<Uint8Array>({
+      async start(controller) {
+        try {
+          const res = await fetch(`${baseUrl}/chat/completions`, {
+            method: 'POST',
+            headers: {
+              'Content-Type': 'application/json',
+              'Authorization': `Bearer ${apiKey}`,
+            },
+            body: JSON.stringify(body),
+          });
+
+          if (!res.ok || !res.body) {
+            const err = await res.text();
+            controller.enqueue(encoder.encode(`data: ${JSON.stringify({ error: err, done: true })}\n\n`));
+            controller.close();
+            return;
+          }
+
+          const reader = res.body.getReader();
+          const dec = new TextDecoder();
+          let buf = '';
+
+          while (true) {
+            const { done, value } = await reader.read();
+            if (done) break;
+            buf += dec.decode(value, { stream: true });
+
+            const lines = buf.split('\n');
+            buf = lines.pop() ?? '';
+
+            for (const line of lines) {
+              if (line.startsWith('data: ')) {
+                const data = line.slice(6).trim();
+                if (data === '[DONE]') {
+                  controller.enqueue(encoder.encode(`data: ${JSON.stringify({ done: true })}\n\n`));
+                  continue;
+                }
+                try {
+                  const parsed = JSON.parse(data);
+                  const delta = parsed.choices?.[0]?.delta;
+                  const chunk = { content: delta?.content ?? '', done: false };
+                  controller.enqueue(encoder.encode(`data: ${JSON.stringify(chunk)}\n\n`));
+                } catch {
+                  // skip malformed lines
+                }
+              }
+            }
+          }
+        } catch (err) {
+          controller.enqueue(encoder.encode(`data: ${JSON.stringify({ error: String(err), done: true })}\n\n`));
+        } finally {
+          controller.close();
+        }
+      },
+    });
+  }
+
+  public countTokens(messages: AiMessage[]): number {
+    // Rough approximation: 1 token ≈ 4 chars
+    return Math.ceil(messages.reduce((sum, m) => sum + m.content.length, 0) / 4);
+  }
+
+  private async post(path: string, body: Record<string, unknown>): Promise<OpenAiChatCompletionResponse> {
+    const res = await fetch(`${this.baseUrl}${path}`, {
+      method: 'POST',
+      headers: {
+        'Content-Type': 'application/json',
+        'Authorization': `Bearer ${this.apiKey}`,
+      },
+      body: JSON.stringify(body),
+    });
+
+    if (res.status === 429) {
+      const retryAfter = res.headers.get('retry-after');
+      throw new AiRateLimitError(this.name, retryAfter ? Number(retryAfter) * 1000 : undefined);
+    }
+    if (res.status === 413) {
+      throw new AiContextLengthError(this.name);
+    }
+    if (res.status === 408 || res.status === 504) {
+      throw new AiTimeoutError(this.name, 30000);
+    }
+    if (!res.ok) {
+      const text = await res.text();
+      throw new AiProviderError(text, this.name, res.status);
+    }
+
+    return await res.json() as OpenAiChatCompletionResponse;
+  }
+
+  private safeParseToolArguments(argumentsJson?: string): Record<string, unknown> {
+    if (!argumentsJson) {
+      return {};
+    }
+    try {
+      const parsed = JSON.parse(argumentsJson);
+      if (typeof parsed === 'object' && parsed !== null) {
+        return parsed as Record<string, unknown>;
+      }
+      return {};
+    } catch {
+      return {};
+    }
+  }
+
+  private estimateCost(model: string, promptTokens: number, completionTokens: number): number {
+    const pricing = this.pricing[model];
+    if (!pricing) return 0;
+    return (promptTokens * pricing.input + completionTokens * pricing.output) / 1_000_000;
+  }
+}

package/src/ai/service.ts

@@ -0,0 +1,155 @@
+import { Injectable } from '../di/decorators';
+import type {
+  LlmProvider,
+  AiRequest,
+  AiResponse,
+  AiModuleOptions,
+  AiMessage,
+} from './types';
+import { AI_MODULE_OPTIONS_TOKEN } from './types';
+import { Inject } from '../di/decorators';
+import { AiNoProviderError, AiAllProvidersFailed, AiTimeoutError } from './errors';
+import type { ToolRegistry } from './tools/tool-registry';
+import { ToolExecutor } from './tools/tool-executor';
+
+/**
+ * Core AI service — manages multiple LLM providers, fallback, streaming,
+ * Tool Calling loop, and cost tracking.
+ */
+@Injectable()
+export class AiService {
+  private readonly providers = new Map<string, LlmProvider>();
+  private defaultProviderName: string | undefined;
+  private readonly options: AiModuleOptions;
+  private toolExecutor: ToolExecutor | null = null;
+
+  public constructor(
+    @Inject(AI_MODULE_OPTIONS_TOKEN) options: AiModuleOptions,
+  ) {
+    this.options = options;
+    for (const entry of options.providers) {
+      const provider = new entry.provider(entry.config);
+      this.providers.set(entry.name, provider);
+      if (entry.default || !this.defaultProviderName) {
+        this.defaultProviderName = entry.name;
+      }
+    }
+  }
+
+  /**
+   * Attach a ToolRegistry so the service can run Tool Calling loops
+   */
+  public setToolRegistry(registry: ToolRegistry): void {
+    this.toolExecutor = new ToolExecutor(registry);
+  }
+
+  /**
+   * Non-streaming completion with optional Tool Calling loop
+   */
+  public async complete(request: AiRequest): Promise<AiResponse> {
+    const maxIterations = this.options.tools?.maxIterations ?? 10;
+    let messages: AiMessage[] = [...request.messages];
+    let iteration = 0;
+
+    while (iteration < maxIterations) {
+      const response = await this.completeSingle({ ...request, messages });
+
+      // No tool calls — return final response
+      if (!response.toolCalls || response.toolCalls.length === 0 || !this.toolExecutor) {
+        return response;
+      }
+
+      // Append assistant message with tool calls
+      messages = [
+        ...messages,
+        { role: 'assistant', content: response.content, toolCalls: response.toolCalls },
+      ];
+
+      // Execute tools and append results
+      const toolResults = await this.toolExecutor.executeAll(response.toolCalls);
+      messages = [...messages, ...toolResults];
+
+      iteration++;
+    }
+
+    // Reached max iterations — do final pass without tools
+    return this.completeSingle({ ...request, messages, tools: [] });
+  }
+
+  /**
+   * Streaming completion — returns SSE ReadableStream
+   */
+  public stream(request: AiRequest): ReadableStream<Uint8Array> {
+    const provider = this.getProvider(request.provider);
+    return provider.stream(request);
+  }
+
+  /**
+   * Estimate token count for messages using the default provider
+   */
+  public countTokens(messages: AiMessage[]): number {
+    const provider = this.getProvider();
+    return provider.countTokens(messages);
+  }
+
+  /**
+   * Get a provider by name (or default)
+   */
+  public getProvider(name?: string): LlmProvider {
+    const providerName = name ?? this.defaultProviderName;
+    if (!providerName) throw new AiNoProviderError();
+
+    const provider = this.providers.get(providerName);
+    if (!provider) throw new AiNoProviderError();
+
+    return provider;
+  }
+
+  /**
+   * List all registered provider names
+   */
+  public getProviderNames(): string[] {
+    return Array.from(this.providers.keys());
+  }
+
+  private async completeSingle(request: AiRequest): Promise<AiResponse> {
+    const targetName = request.provider ?? this.defaultProviderName;
+    if (!targetName) throw new AiNoProviderError();
+
+    const fallback = this.options.fallback ?? false;
+    const timeout = this.options.timeout ?? 30000;
+
+    if (!fallback) {
+      return this.withTimeout(this.getProvider(targetName).complete(request), timeout, targetName);
+    }
+
+    // Fallback chain: try target first, then others in order
+    const names = [
+      targetName,
+      ...Array.from(this.providers.keys()).filter((n) => n !== targetName),
+    ];
+
+    const errors: string[] = [];
+    for (const name of names) {
+      try {
+        const provider = this.providers.get(name);
+        if (!provider) continue;
+        return await this.withTimeout(provider.complete({ ...request, provider: name }), timeout, name);
+      } catch (err) {
+        errors.push(`${name}: ${err instanceof Error ? err.message : String(err)}`);
+      }
+    }
+
+    throw new AiAllProvidersFailed(errors);
+  }
+
+  private withTimeout<T>(promise: Promise<T>, ms: number, providerName: string): Promise<T> {
+    return new Promise<T>((resolve, reject) => {
+      const timer = setTimeout(() => reject(new AiTimeoutError(providerName, ms)), ms);
+      promise.then(
+        (val) => { clearTimeout(timer); resolve(val); },
+        (err) => { clearTimeout(timer); reject(err); },
+      );
+    });
+  }
+}

package/src/ai/tools/tool-executor.ts

@@ -0,0 +1,38 @@
+import type { AiMessage, AiToolCall } from '../types';
+import type { ToolRegistry } from './tool-registry';
+
+/**
+ * Executes tool calls from LLM responses and formats results as AiMessages
+ */
+export class ToolExecutor {
+  public constructor(private readonly registry: ToolRegistry) {}
+
+  /**
+   * Execute all tool calls in parallel and return result messages
+   */
+  public async executeAll(toolCalls: AiToolCall[]): Promise<AiMessage[]> {
+    const results = await Promise.all(
+      toolCalls.map((call) => this.executeOne(call)),
+    );
+    return results;
+  }
+
+  private async executeOne(call: AiToolCall): Promise<AiMessage> {
+    let content: string;
+    try {
+      const result = await this.registry.execute(call.name, call.arguments);
+      content =
+        typeof result === 'string'
+          ? result
+          : JSON.stringify(result, null, 2);
+    } catch (err) {
+      content = `Error executing tool "${call.name}": ${err instanceof Error ? err.message : String(err)}`;
+    }
+
+    return {
+      role: 'tool',
+      content,
+      toolCallId: call.id,
+    };
+  }
+}

package/src/ai/tools/tool-registry.ts

@@ -0,0 +1,91 @@
+import type { AiToolDefinition } from '../types';
+import { AI_TOOL_METADATA_KEY } from '../types';
+
+/**
+ * Registered tool entry
+ */
+export interface RegisteredTool extends AiToolDefinition {
+  /** Bound execute function */
+  execute(args: Record<string, unknown>): Promise<unknown>;
+}
+
+/**
+ * Registry for all @AiTool()-decorated methods
+ */
+export class ToolRegistry {
+  private readonly tools = new Map<string, RegisteredTool>();
+
+  /**
+   * Register a tool manually
+   */
+  public register(tool: RegisteredTool): void {
+    this.tools.set(tool.name, tool);
+  }
+
+  /**
+   * Scan an object instance for @AiTool() decorated methods and register them
+   */
+  public scanAndRegister(instance: object): void {
+    const proto = Object.getPrototypeOf(instance);
+    const methodNames = Object.getOwnPropertyNames(proto).filter(
+      (key) => key !== 'constructor',
+    );
+
+    for (const methodName of methodNames) {
+      const metadata: AiToolDefinition | undefined = Reflect.getMetadata(
+        AI_TOOL_METADATA_KEY,
+        proto,
+        methodName,
+      );
+      if (metadata) {
+        const method = (instance as Record<string, unknown>)[methodName];
+        if (typeof method === 'function') {
+          this.tools.set(metadata.name, {
+            ...metadata,
+            execute: (args: Record<string, unknown>) =>
+              (method as (args: Record<string, unknown>) => Promise<unknown>).call(
+                instance,
+                args,
+              ),
+          });
+        }
+      }
+    }
+  }
+
+  /**
+   * Get all registered tools as definitions (for LLM request)
+   */
+  public getDefinitions(): AiToolDefinition[] {
+    return Array.from(this.tools.values()).map(({ name, description, parameters }) => ({
+      name,
+      description,
+      parameters,
+    }));
+  }
+
+  /**
+   * Execute a tool by name
+   */
+  public async execute(name: string, args: Record<string, unknown>): Promise<unknown> {
+    const tool = this.tools.get(name);
+    if (!tool) {
+      throw new Error(`Tool "${name}" not found in registry`);
+    }
+    return tool.execute(args);
+  }
+
+  /**
+   * Check whether a tool exists
+   */
+  public has(name: string): boolean {
+    return this.tools.has(name);
+  }
+
+  /**
+   * Number of registered tools
+   */
+  public get size(): number {
+    return this.tools.size;
+  }
+}

package/src/ai/types.ts

@@ -0,0 +1,145 @@
+/**
+ * AI message role
+ */
+export type AiMessageRole = 'system' | 'user' | 'assistant' | 'tool';
+
+/**
+ * Single AI message
+ */
+export interface AiMessage {
+  role: AiMessageRole;
+  content: string;
+  /** Tool call ID (only for role='tool') */
+  toolCallId?: string;
+  /** Tool calls returned by assistant */
+  toolCalls?: AiToolCall[];
+}
+
+/**
+ * AI tool call from LLM response
+ */
+export interface AiToolCall {
+  id: string;
+  name: string;
+  arguments: Record<string, unknown>;
+}
+
+/**
+ * AI tool definition (for function calling)
+ */
+export interface AiToolDefinition {
+  name: string;
+  description: string;
+  /** JSON Schema for parameters */
+  parameters: Record<string, unknown>;
+}
+
+/**
+ * AI request to LLM
+ */
+export interface AiRequest {
+  messages: AiMessage[];
+  model?: string;
+  temperature?: number;
+  maxTokens?: number;
+  tools?: AiToolDefinition[];
+  /** Provider name override */
+  provider?: string;
+}
+
+/**
+ * Non-streaming AI response
+ */
+export interface AiResponse {
+  content: string;
+  toolCalls?: AiToolCall[];
+  model: string;
+  provider: string;
+  usage: AiUsage;
+  finishReason: 'stop' | 'tool_calls' | 'length' | 'error';
+}
+
+/**
+ * Streaming AI chunk
+ */
+export interface AiChunk {
+  content?: string;
+  toolCallDelta?: {
+    index: number;
+    id?: string;
+    name?: string;
+    argumentsDelta?: string;
+  };
+  done: boolean;
+  model?: string;
+  usage?: AiUsage;
+}
+
+/**
+ * Token usage statistics
+ */
+export interface AiUsage {
+  promptTokens: number;
+  completionTokens: number;
+  totalTokens: number;
+  /** Estimated cost in USD */
+  estimatedCostUsd?: number;
+}
+
+/**
+ * LLM provider abstraction interface
+ */
+export interface LlmProvider {
+  /**
+   * Non-streaming completion
+   */
+  complete(request: AiRequest): Promise<AiResponse>;
+  /**
+   * Streaming completion — returns SSE-encoded ReadableStream
+   */
+  stream(request: AiRequest): ReadableStream<Uint8Array>;
+  /**
+   * Approximate token count for messages
+   */
+  countTokens(messages: AiMessage[]): number;
+  /** Provider name */
+  readonly name: string;
+}
+
+/**
+ * Provider configuration entry
+ */
+export interface AiProviderConfig<T = unknown> {
+  name: string;
+  provider: new (config: T) => LlmProvider;
+  config: T;
+  /** Use this provider by default */
+  default?: boolean;
+}
+
+/**
+ * AiModule configuration
+ */
+export interface AiModuleOptions {
+  providers: AiProviderConfig[];
+  /** Enable provider fallback chain on error */
+  fallback?: boolean;
+  /** Request timeout in ms */
+  timeout?: number;
+  /** Tool calling configuration */
+  tools?: {
+    /** Auto-discover @AiTool() decorated methods */
+    autoDiscover?: boolean;
+    /** Max tool call iterations per request */
+    maxIterations?: number;
+  };
+}
+
+export const AI_SERVICE_TOKEN = Symbol('@dangao/bun-server:ai:service');
+export const AI_MODULE_OPTIONS_TOKEN = Symbol('@dangao/bun-server:ai:options');
+export const AI_TOOL_REGISTRY_TOKEN = Symbol('@dangao/bun-server:ai:tool-registry');
+
+/**
+ * Metadata key for @AiTool decorator
+ */
+export const AI_TOOL_METADATA_KEY = '@dangao/bun-server:ai:tool';