@usejarvis/brain 0.1.0

package/src/llm/gemini.ts

@@ -0,0 +1,371 @@
+import type {
+  LLMProvider,
+  LLMMessage,
+  LLMOptions,
+  LLMResponse,
+  LLMStreamEvent,
+  LLMTool,
+  LLMToolCall,
+} from './provider.ts';
+
+type GeminiPart =
+  | { text: string }
+  | { functionCall: { name: string; args: Record<string, unknown> } }
+  | { functionResponse: { name: string; response: Record<string, unknown> } };
+
+type GeminiContent = {
+  role: 'user' | 'model';
+  parts: GeminiPart[];
+};
+
+type GeminiFunctionDeclaration = {
+  name: string;
+  description: string;
+  parameters: Record<string, unknown>;
+};
+
+type GeminiResponse = {
+  candidates: Array<{
+    content: { parts: GeminiPart[]; role: 'model' };
+    finishReason: 'STOP' | 'MAX_TOKENS' | 'SAFETY' | 'RECITATION' | 'OTHER' | null;
+  }>;
+  usageMetadata?: {
+    promptTokenCount: number;
+    candidatesTokenCount: number;
+    totalTokenCount: number;
+  };
+  modelVersion?: string;
+};
+
+type GeminiStreamChunk = {
+  candidates?: Array<{
+    content?: { parts?: GeminiPart[]; role?: 'model' };
+    finishReason?: string | null;
+  }>;
+  usageMetadata?: {
+    promptTokenCount: number;
+    candidatesTokenCount: number;
+    totalTokenCount: number;
+  };
+};
+
+const MAX_RETRIES = 3;
+const RETRY_BASE_DELAY_MS = 5000;
+
+export class GeminiProvider implements LLMProvider {
+  name = 'gemini';
+  private apiKey: string;
+  private defaultModel: string;
+  private baseUrl = 'https://generativelanguage.googleapis.com/v1beta';
+
+  constructor(apiKey: string, defaultModel = 'gemini-3-flash-preview') {
+    this.apiKey = apiKey;
+    this.defaultModel = defaultModel;
+  }
+
+  private async fetchWithRetry(url: string, body: string): Promise<Response> {
+    for (let attempt = 0; attempt <= MAX_RETRIES; attempt++) {
+      const response = await fetch(url, {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json' },
+        body,
+      });
+
+      if (response.ok) return response;
+
+      if ((response.status === 429 || response.status >= 500) && attempt < MAX_RETRIES) {
+        const delay = RETRY_BASE_DELAY_MS * Math.pow(2, attempt);
+        console.log(`[Gemini] ${response.status} — retrying in ${delay / 1000}s (attempt ${attempt + 1}/${MAX_RETRIES})`);
+        await Bun.sleep(delay);
+        continue;
+      }
+
+      const errorText = await response.text();
+      throw new Error(`Gemini API error (${response.status}): ${errorText}`);
+    }
+
+    throw new Error('Gemini API: max retries exceeded');
+  }
+
+  async chat(messages: LLMMessage[], options: LLMOptions = {}): Promise<LLMResponse> {
+    const { model = this.defaultModel, temperature, max_tokens, tools } = options;
+    const url = `${this.baseUrl}/models/${model}:generateContent?key=${this.apiKey}`;
+
+    const { systemInstruction, contents } = this.convertMessages(messages);
+    const body: Record<string, unknown> = { contents };
+
+    if (systemInstruction) body.systemInstruction = systemInstruction;
+
+    const generationConfig: Record<string, unknown> = {};
+    if (temperature !== undefined) generationConfig.temperature = temperature;
+    if (max_tokens !== undefined) generationConfig.maxOutputTokens = max_tokens;
+    if (Object.keys(generationConfig).length > 0) body.generationConfig = generationConfig;
+
+    if (tools && tools.length > 0) {
+      body.tools = [{ functionDeclarations: this.convertTools(tools) }];
+    }
+
+    const response = await this.fetchWithRetry(url, JSON.stringify(body));
+    const data = await response.json() as GeminiResponse;
+    return this.convertResponse(data, model);
+  }
+
+  async *stream(messages: LLMMessage[], options: LLMOptions = {}): AsyncIterable<LLMStreamEvent> {
+    const { model = this.defaultModel, temperature, max_tokens, tools } = options;
+    const url = `${this.baseUrl}/models/${model}:streamGenerateContent?alt=sse&key=${this.apiKey}`;
+
+    const { systemInstruction, contents } = this.convertMessages(messages);
+    const body: Record<string, unknown> = { contents };
+
+    if (systemInstruction) body.systemInstruction = systemInstruction;
+
+    const generationConfig: Record<string, unknown> = {};
+    if (temperature !== undefined) generationConfig.temperature = temperature;
+    if (max_tokens !== undefined) generationConfig.maxOutputTokens = max_tokens;
+    if (Object.keys(generationConfig).length > 0) body.generationConfig = generationConfig;
+
+    if (tools && tools.length > 0) {
+      body.tools = [{ functionDeclarations: this.convertTools(tools) }];
+    }
+
+    let response: Response;
+    try {
+      response = await this.fetchWithRetry(url, JSON.stringify(body));
+    } catch (err) {
+      yield { type: 'error', error: err instanceof Error ? err.message : String(err) };
+      return;
+    }
+
+    if (!response.body) {
+      yield { type: 'error', error: 'No response body' };
+      return;
+    }
+
+    let accumulatedText = '';
+    const toolCalls: LLMToolCall[] = [];
+    let finishReason: string | null = null;
+    let usage = { input_tokens: 0, output_tokens: 0 };
+
+    try {
+      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.trim() || !line.startsWith('data: ')) continue;
+
+          const data = line.slice(6);
+          if (data === '[DONE]') continue;
+
+          try {
+            const chunk = JSON.parse(data) as GeminiStreamChunk;
+
+            if (chunk.usageMetadata) {
+              usage.input_tokens = chunk.usageMetadata.promptTokenCount ?? 0;
+              usage.output_tokens = chunk.usageMetadata.candidatesTokenCount ?? 0;
+            }
+
+            if (chunk.candidates && chunk.candidates.length > 0) {
+              const candidate = chunk.candidates[0]!;
+
+              if (candidate.finishReason) {
+                finishReason = candidate.finishReason;
+              }
+
+              if (candidate.content?.parts) {
+                for (const part of candidate.content.parts) {
+                  if ('text' in part) {
+                    accumulatedText += part.text;
+                    yield { type: 'text', text: part.text };
+                  } else if ('functionCall' in part) {
+                    const toolCall: LLMToolCall = {
+                      id: `call_${Date.now()}_${Math.random().toString(36).slice(2, 8)}`,
+                      name: part.functionCall.name,
+                      arguments: part.functionCall.args,
+                    };
+                    toolCalls.push(toolCall);
+                    yield { type: 'tool_call', tool_call: toolCall };
+                  }
+                }
+              }
+            }
+          } catch {
+            // Skip invalid JSON lines
+          }
+        }
+      }
+
+      yield {
+        type: 'done',
+        response: {
+          content: accumulatedText,
+          tool_calls: toolCalls,
+          usage,
+          model,
+          finish_reason: this.mapFinishReason(finishReason),
+        },
+      };
+    } catch (err) {
+      yield { type: 'error', error: `Stream error: ${err}` };
+    }
+  }
+
+  async listModels(): Promise<string[]> {
+    try {
+      const response = await fetch(
+        `${this.baseUrl}/models?key=${this.apiKey}`,
+      );
+
+      if (!response.ok) throw new Error(`Failed to list models: ${response.status}`);
+
+      const data = await response.json() as { models: Array<{ name: string }> };
+      return data.models
+        .map(m => m.name.replace('models/', ''))
+        .filter(id => id.startsWith('gemini'))
+        .sort();
+    } catch {
+      return [
+        'gemini-3.1-pro-preview',
+        'gemini-3-deep-think',
+        'gemini-3-flash-preview',
+        'gemini-3-1-flash-lite-preview',
+        'gemini-2.5-pro',
+        'gemini-2.5-flash',
+      ];
+    }
+  }
+
+  private convertMessages(messages: LLMMessage[]): {
+    systemInstruction?: { parts: Array<{ text: string }> };
+    contents: GeminiContent[];
+  } {
+    const systemMessages = messages.filter(m => m.role === 'system');
+    const systemText = systemMessages
+      .map(m => typeof m.content === 'string' ? m.content : m.content.filter(b => b.type === 'text').map(b => (b as { text: string }).text).join('\n'))
+      .join('\n\n');
+
+    const systemInstruction = systemText
+      ? { parts: [{ text: systemText }] }
+      : undefined;
+
+    const contents: GeminiContent[] = [];
+    const nonSystem = messages.filter(m => m.role !== 'system');
+
+    for (const msg of nonSystem) {
+      if (msg.role === 'assistant') {
+        const parts: GeminiPart[] = [];
+
+        if (msg.content) {
+          const text = typeof msg.content === 'string'
+            ? msg.content
+            : msg.content.filter(b => b.type === 'text').map(b => (b as { text: string }).text).join('\n');
+          if (text) parts.push({ text });
+        }
+
+        if (msg.tool_calls) {
+          for (const tc of msg.tool_calls) {
+            parts.push({
+              functionCall: { name: tc.name, args: tc.arguments },
+            });
+          }
+        }
+
+        if (parts.length > 0) {
+          contents.push({ role: 'model', parts });
+        }
+      } else if (msg.role === 'tool') {
+        // Tool results go as user role with functionResponse
+        const responseContent = typeof msg.content === 'string'
+          ? (() => { try { return JSON.parse(msg.content); } catch { return { result: msg.content }; } })()
+          : { result: msg.content };
+
+        contents.push({
+          role: 'user',
+          parts: [{
+            functionResponse: {
+              name: msg.tool_call_id ?? 'unknown',
+              response: responseContent,
+            },
+          }],
+        });
+      } else {
+        // User message
+        const text = typeof msg.content === 'string'
+          ? msg.content
+          : msg.content.filter(b => b.type === 'text').map(b => (b as { text: string }).text).join('\n');
+
+        contents.push({ role: 'user', parts: [{ text }] });
+      }
+    }
+
+    return { systemInstruction, contents };
+  }
+
+  private convertTools(tools: LLMTool[]): GeminiFunctionDeclaration[] {
+    return tools.map(tool => ({
+      name: tool.name,
+      description: tool.description,
+      parameters: tool.parameters,
+    }));
+  }
+
+  private convertResponse(response: GeminiResponse, model: string): LLMResponse {
+    const candidate = response.candidates?.[0];
+    let content = '';
+    const tool_calls: LLMToolCall[] = [];
+
+    if (candidate?.content?.parts) {
+      for (const part of candidate.content.parts) {
+        if ('text' in part) {
+          content += part.text;
+        } else if ('functionCall' in part) {
+          tool_calls.push({
+            id: `call_${Date.now()}_${Math.random().toString(36).slice(2, 8)}`,
+            name: part.functionCall.name,
+            arguments: part.functionCall.args,
+          });
+        }
+      }
+    }
+
+    return {
+      content,
+      tool_calls,
+      usage: {
+        input_tokens: response.usageMetadata?.promptTokenCount ?? 0,
+        output_tokens: response.usageMetadata?.candidatesTokenCount ?? 0,
+      },
+      model: response.modelVersion ?? model,
+      finish_reason: this.mapFinishReason(candidate?.finishReason ?? null),
+    };
+  }
+
+  private mapFinishReason(reason: string | null): 'stop' | 'tool_use' | 'length' | 'error' {
+    switch (reason) {
+      case 'STOP':
+        return 'stop';
+      case 'MAX_TOKENS':
+        return 'length';
+      case 'SAFETY':
+      case 'RECITATION':
+        return 'error';
+      default:
+        return tool_calls_present(reason) ? 'tool_use' : 'stop';
+    }
+  }
+}
+
+// Gemini doesn't have a distinct "tool_use" finish reason — we detect it
+// from the response content instead. This helper is only for the fallback
+// in mapFinishReason; the actual tool_call detection happens in convertResponse.
+function tool_calls_present(_reason: string | null): boolean {
+  return false;
+}

package/src/llm/index.ts

@@ -0,0 +1,19 @@
+// Provider types and interfaces
+export type {
+  LLMMessage,
+  LLMTool,
+  LLMToolCall,
+  LLMResponse,
+  LLMStreamEvent,
+  LLMOptions,
+  LLMProvider,
+} from './provider.ts';
+
+// Provider implementations
+export { AnthropicProvider } from './anthropic.ts';
+export { OpenAIProvider } from './openai.ts';
+export { GeminiProvider } from './gemini.ts';
+export { OllamaProvider } from './ollama.ts';
+
+// Manager
+export { LLMManager } from './manager.ts';

package/src/llm/manager.ts

@@ -0,0 +1,153 @@
+import type {
+  LLMProvider,
+  LLMMessage,
+  LLMOptions,
+  LLMResponse,
+  LLMStreamEvent,
+} from './provider.ts';
+
+export class LLMManager {
+  private providers: Map<string, LLMProvider> = new Map();
+  private primaryProvider = '';
+  private fallbackChain: string[] = [];
+
+  constructor() {}
+
+  registerProvider(provider: LLMProvider): void {
+    this.providers.set(provider.name, provider);
+
+    // Set as primary if it's the first provider
+    if (!this.primaryProvider) {
+      this.primaryProvider = provider.name;
+    }
+  }
+
+  setPrimary(name: string): void {
+    if (!this.providers.has(name)) {
+      throw new Error(`Provider '${name}' not registered`);
+    }
+    this.primaryProvider = name;
+  }
+
+  setFallbackChain(names: string[]): void {
+    for (const name of names) {
+      if (!this.providers.has(name)) {
+        throw new Error(`Provider '${name}' not registered`);
+      }
+    }
+    this.fallbackChain = names;
+  }
+
+  getProvider(name: string): LLMProvider | undefined {
+    return this.providers.get(name);
+  }
+
+  getPrimary(): string {
+    return this.primaryProvider;
+  }
+
+  getFallbackChain(): string[] {
+    return [...this.fallbackChain];
+  }
+
+  getProviderNames(): string[] {
+    return [...this.providers.keys()];
+  }
+
+  /**
+   * Atomically replace all providers. Safe for in-flight requests because
+   * JS is single-threaded and the map assignment is atomic.
+   */
+  replaceProviders(providers: LLMProvider[], primary: string, fallback: string[]): void {
+    const newMap = new Map<string, LLMProvider>();
+    for (const p of providers) {
+      newMap.set(p.name, p);
+    }
+    this.providers = newMap;
+    this.primaryProvider = newMap.has(primary) ? primary : (providers[0]?.name ?? '');
+    this.fallbackChain = fallback.filter(n => newMap.has(n));
+  }
+
+  async chat(messages: LLMMessage[], options?: LLMOptions): Promise<LLMResponse> {
+    const providerNames = [this.primaryProvider, ...this.fallbackChain];
+    const errors: Array<{ provider: string; error: string }> = [];
+
+    for (const providerName of providerNames) {
+      const provider = this.providers.get(providerName);
+      if (!provider) continue;
+
+      try {
+        return await provider.chat(messages, options);
+      } catch (err) {
+        const errorMsg = err instanceof Error ? err.message : String(err);
+        errors.push({ provider: providerName, error: errorMsg });
+        console.error(`Provider ${providerName} failed:`, errorMsg);
+      }
+    }
+
+    throw new Error(
+      `All providers failed:\n${errors.map(e => `  ${e.provider}: ${e.error}`).join('\n')}`
+    );
+  }
+
+  async *stream(messages: LLMMessage[], options?: LLMOptions): AsyncIterable<LLMStreamEvent> {
+    const providerNames = [this.primaryProvider, ...this.fallbackChain];
+    const errors: Array<{ provider: string; error: string }> = [];
+    const MAX_RETRIES_PER_PROVIDER = 3;
+    const RETRY_BASE_MS = 5000;
+
+    for (const providerName of providerNames) {
+      const provider = this.providers.get(providerName);
+      if (!provider) continue;
+
+      for (let attempt = 0; attempt <= MAX_RETRIES_PER_PROVIDER; attempt++) {
+        try {
+          let hasError = false;
+          let isRetryable = false;
+          for await (const event of provider.stream(messages, options)) {
+            if (event.type === 'error') {
+              hasError = true;
+              // Retry on transient errors (overloaded, rate limit, server errors)
+              isRetryable = /overloaded|rate.limit|529|5\d\d|timeout/i.test(event.error);
+              if (isRetryable && attempt < MAX_RETRIES_PER_PROVIDER) {
+                const delay = RETRY_BASE_MS * Math.pow(2, attempt);
+                console.log(`[LLMManager] ${providerName} stream error (${event.error}) — retrying in ${delay / 1000}s (attempt ${attempt + 1}/${MAX_RETRIES_PER_PROVIDER})`);
+                await Bun.sleep(delay);
+              } else {
+                errors.push({ provider: providerName, error: event.error });
+                console.error(`Provider ${providerName} stream error:`, event.error);
+              }
+              break;
+            }
+            yield event;
+          }
+
+          if (!hasError) {
+            return; // Successful stream completion
+          }
+          if (isRetryable && attempt < MAX_RETRIES_PER_PROVIDER) {
+            continue; // Retry same provider
+          }
+          break; // Non-retryable error, try next provider
+        } catch (err) {
+          const errorMsg = err instanceof Error ? err.message : String(err);
+          const isRetryable = /overloaded|rate.limit|529|5\d\d|timeout|ECONNRESET/i.test(errorMsg);
+          if (isRetryable && attempt < MAX_RETRIES_PER_PROVIDER) {
+            const delay = RETRY_BASE_MS * Math.pow(2, attempt);
+            console.log(`[LLMManager] ${providerName} stream failed (${errorMsg}) — retrying in ${delay / 1000}s (attempt ${attempt + 1}/${MAX_RETRIES_PER_PROVIDER})`);
+            await Bun.sleep(delay);
+            continue;
+          }
+          errors.push({ provider: providerName, error: errorMsg });
+          console.error(`Provider ${providerName} stream failed:`, errorMsg);
+          break; // Try next provider
+        }
+      }
+    }
+
+    yield {
+      type: 'error',
+      error: `All providers failed:\n${errors.map(e => `  ${e.provider}: ${e.error}`).join('\n')}`,
+    };
+  }
+}