@shykaruu/jarvis-brain 0.4.0

package/src/llm/provider.test.ts

@@ -0,0 +1,487 @@
+import { test, expect, describe, beforeEach, afterEach, mock } from 'bun:test';
+import { AnthropicProvider } from './anthropic.ts';
+import { OpenAIProvider, isOfficialOpenAI, resolveOpenAIBaseUrl } from './openai.ts';
+import { GroqProvider } from './groq.ts';
+import { OllamaProvider } from './ollama.ts';
+import { OpenRouterProvider } from './openrouter.ts';
+import { LLMManager } from './manager.ts';
+import { guardImageSize, type LLMMessage, type ContentBlock } from './provider.ts';
+import { isToolResult, type ToolResult } from '../actions/tools/registry.ts';
+
+describe('LLM Provider Types', () => {
+  test('AnthropicProvider can be instantiated', () => {
+    const provider = new AnthropicProvider('test-key', 'test-model');
+    expect(provider.name).toBe('anthropic');
+  });
+
+  test('OpenAIProvider can be instantiated', () => {
+    const provider = new OpenAIProvider('test-key', 'test-model');
+    expect(provider.name).toBe('openai');
+  });
+
+  test('GroqProvider can be instantiated', () => {
+    const provider = new GroqProvider('test-key', 'test-model');
+    expect(provider.name).toBe('groq');
+  });
+
+  test('OllamaProvider can be instantiated', () => {
+    const provider = new OllamaProvider('http://localhost:11434', 'llama3');
+    expect(provider.name).toBe('ollama');
+  });
+
+  test('OpenRouterProvider can be instantiated', () => {
+    const provider = new OpenRouterProvider('test-key', 'anthropic/claude-sonnet-4');
+    expect(provider.name).toBe('openrouter');
+  });
+});
+
+describe('LLMManager', () => {
+  test('can register providers', () => {
+    const manager = new LLMManager();
+    const anthropic = new AnthropicProvider('test-key');
+
+    manager.registerProvider(anthropic);
+    expect(manager.getProvider('anthropic')).toBe(anthropic);
+  });
+
+  test('sets first registered provider as primary', () => {
+    const manager = new LLMManager();
+    const anthropic = new AnthropicProvider('test-key');
+
+    manager.registerProvider(anthropic);
+    // Primary is set automatically
+    expect(manager.getProvider('anthropic')).toBeDefined();
+  });
+
+  test('can change primary provider', () => {
+    const manager = new LLMManager();
+    const anthropic = new AnthropicProvider('test-key-1');
+    const openai = new OpenAIProvider('test-key-2');
+
+    manager.registerProvider(anthropic);
+    manager.registerProvider(openai);
+    manager.setPrimary('openai');
+
+    // Should not throw
+    expect(manager.getProvider('openai')).toBeDefined();
+  });
+
+  test('throws when setting non-existent provider as primary', () => {
+    const manager = new LLMManager();
+    expect(() => manager.setPrimary('nonexistent')).toThrow();
+  });
+
+  test('can set fallback chain', () => {
+    const manager = new LLMManager();
+    const anthropic = new AnthropicProvider('test-key-1');
+    const openai = new OpenAIProvider('test-key-2');
+
+    manager.registerProvider(anthropic);
+    manager.registerProvider(openai);
+    manager.setPrimary('anthropic');
+    manager.setFallbackChain(['openai']);
+
+    // Should not throw
+    expect(manager.getProvider('anthropic')).toBeDefined();
+    expect(manager.getProvider('openai')).toBeDefined();
+  });
+
+  test('throws when setting non-existent fallback provider', () => {
+    const manager = new LLMManager();
+    const anthropic = new AnthropicProvider('test-key');
+
+    manager.registerProvider(anthropic);
+    expect(() => manager.setFallbackChain(['nonexistent'])).toThrow();
+  });
+});
+
+describe('Message Types', () => {
+  test('LLMMessage has correct structure', () => {
+    const message: LLMMessage = {
+      role: 'user',
+      content: 'Hello',
+    };
+
+    expect(message.role).toBe('user');
+    expect(message.content).toBe('Hello');
+  });
+
+  test('supports all message roles', () => {
+    const messages: LLMMessage[] = [
+      { role: 'system', content: 'You are helpful' },
+      { role: 'user', content: 'Hello' },
+      { role: 'assistant', content: 'Hi there' },
+    ];
+
+    expect(messages).toHaveLength(3);
+    expect(messages[0]!.role).toBe('system');
+    expect(messages[1]!.role).toBe('user');
+    expect(messages[2]!.role).toBe('assistant');
+  });
+});
+
+describe('Provider URLs', () => {
+  test('AnthropicProvider uses correct API URL', () => {
+    const provider = new AnthropicProvider('test-key') as any;
+    expect(provider.apiUrl).toBe('https://api.anthropic.com/v1/messages');
+  });
+
+  test('OpenAIProvider uses correct API URL', () => {
+    const provider = new OpenAIProvider('test-key') as any;
+    expect(provider.apiUrl).toBe('https://api.openai.com/v1/chat/completions');
+  });
+
+  test('OpenAIProvider uses custom compatible base URL as the request base', () => {
+    const provider = new OpenAIProvider('test-key', 'test-model', 'https://gateway.example.com/v1/') as any;
+    expect(provider.baseUrl).toBe('https://gateway.example.com/v1/');
+    expect(provider.apiUrl).toBe('https://gateway.example.com/v1/chat/completions');
+  });
+
+  test('OpenAIProvider preserves custom path prefixes in compatible base URLs', () => {
+    const provider = new OpenAIProvider('test-key', 'test-model', 'https://gateway.example.com/openai/') as any;
+    expect(provider.baseUrl).toBe('https://gateway.example.com/openai/');
+    expect(provider.apiUrl).toBe('https://gateway.example.com/openai/chat/completions');
+  });
+
+  test('OpenRouterProvider uses correct API URL', () => {
+    const provider = new OpenRouterProvider('test-key') as any;
+    expect(provider.apiUrl).toBe('https://openrouter.ai/api/v1/chat/completions');
+  });
+
+  test('GroqProvider uses correct API URL', () => {
+    const provider = new GroqProvider('test-key') as any;
+    expect(provider.apiUrl).toBe('https://api.groq.com/openai/v1/chat/completions');
+  });
+
+  test('OllamaProvider uses correct base URL', () => {
+    const provider = new OllamaProvider() as any;
+    expect(provider.baseUrl).toBe('http://localhost:11434');
+  });
+
+  test('OllamaProvider removes trailing slash from base URL', () => {
+    const provider = new OllamaProvider('http://localhost:11434/') as any;
+    expect(provider.baseUrl).toBe('http://localhost:11434');
+  });
+});
+
+describe('OpenAI base URL resolution', () => {
+  test('uses official OpenAI API when omitted', () => {
+    expect(resolveOpenAIBaseUrl().toString()).toBe('https://api.openai.com/v1/');
+  });
+
+  test('adds a trailing slash so relative endpoints resolve consistently', () => {
+    expect(resolveOpenAIBaseUrl('https://gateway.example.com/v1').toString()).toBe('https://gateway.example.com/v1/');
+  });
+
+  test('preserves the provided base path', () => {
+    expect(resolveOpenAIBaseUrl('https://gateway.example.com/openai').toString()).toBe('https://gateway.example.com/openai/');
+  });
+
+  test('rejects invalid URLs', () => {
+    expect(() => resolveOpenAIBaseUrl('not-a-url')).toThrow();
+  });
+
+  test('treats the default endpoint as official OpenAI', () => {
+    expect(isOfficialOpenAI()).toBe(true);
+    expect(isOfficialOpenAI('https://api.openai.com/v1')).toBe(true);
+  });
+
+  test('treats custom compatible gateways as non-official OpenAI', () => {
+    expect(isOfficialOpenAI('https://gateway.example.com/openai')).toBe(false);
+  });
+});
+
+describe('Default Models', () => {
+  test('AnthropicProvider has correct default model', () => {
+    const provider = new AnthropicProvider('test-key') as any;
+    expect(provider.defaultModel).toBe('claude-sonnet-4-5-20250929');
+  });
+
+  test('OpenAIProvider has correct default model', () => {
+    const provider = new OpenAIProvider('test-key') as any;
+    expect(provider.defaultModel).toBe('gpt-4o');
+  });
+
+  test('OllamaProvider has correct default model', () => {
+    const provider = new OllamaProvider() as any;
+    expect(provider.defaultModel).toBe('llama3');
+  });
+
+  test('GroqProvider has correct default model', () => {
+    const provider = new GroqProvider('test-key') as any;
+    expect(provider.defaultModel).toBe('llama-3.3-70b-versatile');
+  });
+
+  test('OpenRouterProvider has correct default model', () => {
+    const provider = new OpenRouterProvider('test-key') as any;
+    expect(provider.defaultModel).toBe('anthropic/claude-sonnet-4');
+  });
+
+  test('can override default models', () => {
+    const anthropic = new AnthropicProvider('key', 'custom-model') as any;
+    const openai = new OpenAIProvider('key', 'custom-model') as any;
+    const groq = new GroqProvider('key', 'custom-model') as any;
+    const ollama = new OllamaProvider('http://localhost:11434', 'custom-model') as any;
+    const openrouter = new OpenRouterProvider('key', 'custom-model') as any;
+
+    expect(anthropic.defaultModel).toBe('custom-model');
+    expect(openai.defaultModel).toBe('custom-model');
+    expect(groq.defaultModel).toBe('custom-model');
+    expect(ollama.defaultModel).toBe('custom-model');
+    expect(openrouter.defaultModel).toBe('custom-model');
+  });
+});
+
+describe('Vision Support', () => {
+  describe('guardImageSize', () => {
+    test('passes text blocks through unchanged', () => {
+      const block: ContentBlock = { type: 'text', text: 'hello' };
+      expect(guardImageSize(block)).toBe(block);
+    });
+
+    test('passes small images through unchanged', () => {
+      const block: ContentBlock = {
+        type: 'image',
+        source: { type: 'base64', media_type: 'image/png', data: 'abc123' },
+      };
+      expect(guardImageSize(block)).toBe(block);
+    });
+
+    test('replaces oversized images with text warning', () => {
+      const bigData = 'x'.repeat(6 * 1024 * 1024); // 6 MB
+      const block: ContentBlock = {
+        type: 'image',
+        source: { type: 'base64', media_type: 'image/png', data: bigData },
+      };
+      const result = guardImageSize(block);
+      expect(result.type).toBe('text');
+      expect((result as { type: 'text'; text: string }).text).toContain('too large');
+    });
+  });
+
+  describe('isToolResult', () => {
+    test('returns true for valid ToolResult', () => {
+      const tr: ToolResult = {
+        content: [{ type: 'text', text: 'hello' }],
+      };
+      expect(isToolResult(tr)).toBe(true);
+    });
+
+    test('returns false for plain string', () => {
+      expect(isToolResult('hello')).toBe(false);
+    });
+
+    test('returns false for null', () => {
+      expect(isToolResult(null)).toBe(false);
+    });
+
+    test('returns false for object without content array', () => {
+      expect(isToolResult({ content: 'not an array' })).toBe(false);
+    });
+
+    test('returns false for object with no content field', () => {
+      expect(isToolResult({ data: 'something' })).toBe(false);
+    });
+  });
+
+  describe('ContentBlock in LLMMessage', () => {
+    test('LLMMessage accepts string content', () => {
+      const msg: LLMMessage = { role: 'user', content: 'Hello' };
+      expect(typeof msg.content).toBe('string');
+    });
+
+    test('LLMMessage accepts ContentBlock[] content', () => {
+      const msg: LLMMessage = {
+        role: 'tool',
+        content: [
+          { type: 'text', text: 'Screenshot captured' },
+          { type: 'image', source: { type: 'base64', media_type: 'image/png', data: 'abc' } },
+        ],
+        tool_call_id: 'test-id',
+      };
+      expect(Array.isArray(msg.content)).toBe(true);
+      expect((msg.content as ContentBlock[]).length).toBe(2);
+    });
+  });
+});
+
+describe('Tool Call Conversion', () => {
+  const toolUseConversation: LLMMessage[] = [
+    { role: 'system', content: 'You are helpful' },
+    { role: 'user', content: 'What time is it?' },
+    {
+      role: 'assistant',
+      content: '',
+      tool_calls: [
+        { id: 'call_1', name: 'get_time', arguments: { timezone: 'UTC' } },
+      ],
+    },
+    {
+      role: 'tool',
+      content: '2026-03-30T12:00:00Z',
+      tool_call_id: 'call_1',
+    },
+  ];
+
+  test('OpenAIProvider preserves tool_calls on assistant messages', () => {
+    const provider = new OpenAIProvider('test-key') as any;
+    const converted = provider.convertMessages(toolUseConversation);
+
+    const assistant = converted[2];
+    expect(assistant.role).toBe('assistant');
+    expect(assistant.tool_calls).toBeDefined();
+    expect(assistant.tool_calls).toHaveLength(1);
+    expect(assistant.tool_calls[0].id).toBe('call_1');
+    expect(assistant.tool_calls[0].type).toBe('function');
+    expect(assistant.tool_calls[0].function.name).toBe('get_time');
+    expect(assistant.tool_calls[0].function.arguments).toBe('{"timezone":"UTC"}');
+  });
+
+  test('OpenAIProvider preserves tool_call_id on tool messages', () => {
+    const provider = new OpenAIProvider('test-key') as any;
+    const converted = provider.convertMessages(toolUseConversation);
+
+    const tool = converted[3];
+    expect(tool.role).toBe('tool');
+    expect(tool.tool_call_id).toBe('call_1');
+    expect(tool.content).toBe('2026-03-30T12:00:00Z');
+  });
+
+  test('GroqProvider preserves tool_calls on assistant messages', () => {
+    const provider = new GroqProvider('test-key') as any;
+    const converted = provider.convertMessages(toolUseConversation);
+
+    const assistant = converted[2];
+    expect(assistant.role).toBe('assistant');
+    expect(assistant.tool_calls).toBeDefined();
+    expect(assistant.tool_calls).toHaveLength(1);
+    expect(assistant.tool_calls[0].id).toBe('call_1');
+    expect(assistant.tool_calls[0].type).toBe('function');
+    expect(assistant.tool_calls[0].function.name).toBe('get_time');
+    expect(assistant.tool_calls[0].function.arguments).toBe('{"timezone":"UTC"}');
+    expect(assistant.content).toBeNull();
+  });
+
+  test('GroqProvider preserves tool_call_id on tool messages', () => {
+    const provider = new GroqProvider('test-key') as any;
+    const converted = provider.convertMessages(toolUseConversation);
+
+    const tool = converted[3];
+    expect(tool.role).toBe('tool');
+    expect(tool.tool_call_id).toBe('call_1');
+    expect(tool.content).toBe('2026-03-30T12:00:00Z');
+  });
+
+  test('Messages without tool_calls omit the field', () => {
+    const provider = new OpenAIProvider('test-key') as any;
+    const converted = provider.convertMessages([
+      { role: 'user', content: 'Hello' },
+      { role: 'assistant', content: 'Hi there' },
+    ]);
+    expect(converted[0].tool_calls).toBeUndefined();
+    expect(converted[1].tool_calls).toBeUndefined();
+    expect(converted[0].tool_call_id).toBeUndefined();
+  });
+});
+
+describe('Groq request shaping', () => {
+  const originalFetch = globalThis.fetch;
+
+  beforeEach(() => {
+    globalThis.fetch = mock(async (_url: string, init?: RequestInit) => {
+      return new Response(JSON.stringify({
+        id: 'cmpl_test',
+        object: 'chat.completion',
+        created: Date.now(),
+        model: 'llama-test',
+        choices: [
+          {
+            index: 0,
+            message: { role: 'assistant', content: 'ok' },
+            finish_reason: 'stop',
+          },
+        ],
+        usage: {
+          prompt_tokens: 10,
+          completion_tokens: 5,
+          total_tokens: 15,
+        },
+      }), {
+        status: 200,
+        headers: {
+          'Content-Type': 'application/json',
+          'x-test-body': typeof init?.body === 'string' ? init.body : '',
+        },
+      });
+    }) as unknown as typeof fetch;
+  });
+
+  afterEach(() => {
+    globalThis.fetch = originalFetch;
+  });
+
+  test('GroqProvider uses Groq-compatible tool fields', async () => {
+    const provider = new GroqProvider('test-key') as any;
+    const messages: LLMMessage[] = [
+      { role: 'system', content: 'You are helpful.' },
+      { role: 'user', content: 'Use the weather tool.' },
+    ];
+
+    await provider.chat(messages, {
+      max_tokens: 321,
+      tools: [
+        {
+          name: 'weather_lookup',
+          description: 'Look up weather',
+          parameters: {
+            type: 'object',
+            properties: {
+              city: { type: 'string' },
+            },
+            required: ['city'],
+          },
+        },
+      ],
+    });
+
+    const fetchMock = globalThis.fetch as unknown as ReturnType<typeof mock>;
+    expect(fetchMock).toHaveBeenCalledTimes(1);
+    const init = fetchMock.mock.calls[0]?.[1] as RequestInit;
+    const body = JSON.parse(String(init.body));
+
+    expect(body.max_completion_tokens).toBe(321);
+    expect(body.max_tokens).toBeUndefined();
+    expect(body.tool_choice).toBe('auto');
+    expect(body.parallel_tool_calls).toBe(true);
+    expect(body.tools).toHaveLength(1);
+  });
+
+  test('GroqProvider trims oversized history but keeps system and latest turn', async () => {
+    const provider = new GroqProvider('test-key') as any;
+    const long = 'x'.repeat(12_000);
+    const messages: LLMMessage[] = [
+      { role: 'system', content: 'System prompt' },
+      { role: 'user', content: long },
+      { role: 'assistant', content: long },
+      { role: 'user', content: 'latest question' },
+    ];
+
+    await provider.chat(messages, {
+      tools: [
+        {
+          name: 'delegate_task',
+          description: 'Delegate focused work',
+          parameters: { type: 'object', properties: {}, required: [] },
+        },
+      ],
+    });
+
+    const fetchMock = globalThis.fetch as unknown as ReturnType<typeof mock>;
+    const init = fetchMock.mock.calls[0]?.[1] as RequestInit;
+    const body = JSON.parse(String(init.body));
+
+    expect(body.messages[0].role).toBe('system');
+    expect(body.messages.at(-1).content).toBe('latest question');
+    expect(body.messages.length).toBeLessThan(messages.length);
+  });
+});

package/src/llm/provider.ts

@@ -0,0 +1,61 @@
+export type ContentBlock =
+  | { type: 'text'; text: string }
+  | { type: 'image'; source: { type: 'base64'; media_type: string; data: string } };
+
+export type LLMMessage = {
+  role: 'system' | 'user' | 'assistant' | 'tool';
+  content: string | ContentBlock[];
+  tool_calls?: LLMToolCall[];   // present on assistant messages with tool use
+  tool_call_id?: string;        // present on tool result messages
+};
+
+export type LLMTool = {
+  name: string;
+  description: string;
+  parameters: Record<string, unknown>;  // JSON Schema
+};
+
+export type LLMToolCall = {
+  id: string;
+  name: string;
+  arguments: Record<string, unknown>;
+};
+
+export type LLMResponse = {
+  content: string;
+  tool_calls: LLMToolCall[];
+  usage: { input_tokens: number; output_tokens: number };
+  model: string;
+  finish_reason: 'stop' | 'tool_use' | 'length' | 'error';
+};
+
+export type LLMStreamEvent =
+  | { type: 'text'; text: string }
+  | { type: 'tool_call'; tool_call: LLMToolCall }
+  | { type: 'done'; response: LLMResponse }
+  | { type: 'error'; error: string };
+
+export type LLMOptions = {
+  model?: string;
+  temperature?: number;
+  max_tokens?: number;
+  tools?: LLMTool[];
+  stream?: boolean;
+  tool_choice?: 'auto' | 'none' | 'required';  // 'auto' enables tool calling when available
+};
+
+export interface LLMProvider {
+  name: string;
+  chat(messages: LLMMessage[], options?: LLMOptions): Promise<LLMResponse>;
+  stream(messages: LLMMessage[], options?: LLMOptions): AsyncIterable<LLMStreamEvent>;
+  listModels(): Promise<string[]>;
+}
+
+const MAX_IMAGE_BYTES = 5 * 1024 * 1024; // 5 MB base64 limit
+
+export function guardImageSize(block: ContentBlock): ContentBlock {
+  if (block.type === 'image' && block.source.data.length > MAX_IMAGE_BYTES) {
+    return { type: 'text', text: '[Image too large to send — saved to disk instead]' };
+  }
+  return block;
+}

package/src/llm/test.ts

@@ -0,0 +1,88 @@
+/**
+ * Manual test file for LLM providers
+ *
+ * Run with: bun run src/llm/test.ts
+ */
+
+import { LLMManager, AnthropicProvider, OpenAIProvider, OllamaProvider } from './index.ts';
+import { loadConfig } from '../config/index.ts';
+
+async function testProviders() {
+  console.log('Loading config...');
+  const config = await loadConfig();
+
+  const manager = new LLMManager();
+
+  // Register providers based on config
+  if (config.llm.anthropic?.api_key) {
+    const anthropic = new AnthropicProvider(
+      config.llm.anthropic.api_key,
+      config.llm.anthropic.model
+    );
+    manager.registerProvider(anthropic);
+    console.log('Registered Anthropic provider');
+  }
+
+  if (config.llm.openai?.api_key) {
+    const openai = new OpenAIProvider(
+      config.llm.openai.api_key,
+      config.llm.openai.model,
+      config.llm.openai.base_url,
+    );
+    manager.registerProvider(openai);
+    console.log('Registered OpenAI provider');
+  }
+
+  if (config.llm.ollama) {
+    const ollama = new OllamaProvider(
+      config.llm.ollama.base_url,
+      config.llm.ollama.model
+    );
+    manager.registerProvider(ollama);
+    console.log('Registered Ollama provider');
+  }
+
+  // Set primary and fallbacks
+  manager.setPrimary(config.llm.primary);
+  manager.setFallbackChain(config.llm.fallback);
+
+  console.log(`\nPrimary provider: ${config.llm.primary}`);
+  console.log(`Fallback chain: ${config.llm.fallback.join(', ')}\n`);
+
+  // Test basic chat
+  console.log('Testing chat...');
+  const messages = [
+    { role: 'system' as const, content: 'You are a helpful assistant.' },
+    { role: 'user' as const, content: 'Say hello in exactly 5 words.' },
+  ];
+
+  try {
+    const response = await manager.chat(messages);
+    console.log('Response:', response.content);
+    console.log('Model:', response.model);
+    console.log('Usage:', response.usage);
+    console.log('Finish reason:', response.finish_reason);
+  } catch (err) {
+    console.error('Chat failed:', err);
+  }
+
+  // Test streaming
+  console.log('\n\nTesting streaming...');
+  try {
+    for await (const event of manager.stream(messages)) {
+      if (event.type === 'text') {
+        process.stdout.write(event.text);
+      } else if (event.type === 'done') {
+        console.log('\n\nStream completed!');
+        console.log('Model:', event.response.model);
+        console.log('Usage:', event.response.usage);
+      } else if (event.type === 'error') {
+        console.error('Stream error:', event.error);
+      }
+    }
+  } catch (err) {
+    console.error('Stream failed:', err);
+  }
+}
+
+testProviders().catch(console.error);