universal-llm-client 4.0.0 → 4.2.0

package/src/tests/router.test.ts

@@ -0,0 +1,254 @@
+/**
+ * Tests for router.ts — Failover Engine
+ */
+import { describe, it, expect, mock, beforeEach } from 'bun:test';
+import { Router, type ProviderEntry } from '../router.js';
+import { BaseLLMClient } from '../client.js';
+import { BufferedAuditor } from '../auditor.js';
+import type {
+    LLMChatMessage,
+    LLMChatResponse,
+    ChatOptions,
+    DecodedEvent,
+} from '../interfaces.js';
+
+// ============================================================================
+// Mock Client
+// ============================================================================
+
+class MockClient extends BaseLLMClient {
+    public chatFn: (messages: LLMChatMessage[]) => Promise<LLMChatResponse>;
+    public embedFn: (text: string) => Promise<number[]>;
+    public modelsFn: () => Promise<string[]>;
+
+    constructor(id: string, opts?: {
+        chatFn?: (messages: LLMChatMessage[]) => Promise<LLMChatResponse>;
+        embedFn?: (text: string) => Promise<number[]>;
+    }) {
+        super({
+            model: `mock-${id}`,
+            url: `http://mock-${id}`,
+            apiType: 'openai' as never,
+        });
+        this.chatFn = opts?.chatFn ?? (async () => ({
+            message: { role: 'assistant' as const, content: `Response from ${id}` },
+            provider: id,
+        }));
+        this.embedFn = opts?.embedFn ?? (async () => [1, 2, 3]);
+        this.modelsFn = async () => [`mock-${id}`];
+    }
+
+    async chat(messages: LLMChatMessage[]): Promise<LLMChatResponse> {
+        return this.chatFn(messages);
+    }
+
+    async *chatStream(): AsyncGenerator<DecodedEvent, LLMChatResponse | void, unknown> {
+        yield { type: 'text', content: 'streamed' };
+        return { message: { role: 'assistant', content: 'streamed' }, provider: 'mock' };
+    }
+
+    async getModels(): Promise<string[]> {
+        return this.modelsFn();
+    }
+
+    async embed(text: string): Promise<number[]> {
+        return this.embedFn(text);
+    }
+}
+
+// ============================================================================
+// Tests
+// ============================================================================
+
+describe('Router', () => {
+    let router: Router;
+    let auditor: BufferedAuditor;
+
+    beforeEach(() => {
+        auditor = new BufferedAuditor();
+        router = new Router({ auditor, retriesPerProvider: 1, maxFailures: 2, cooldownMs: 100 });
+    });
+
+    describe('provider management', () => {
+        it('adds providers and sorts by priority', () => {
+            const clientA = new MockClient('a');
+            const clientB = new MockClient('b');
+
+            router.addProvider({ id: 'a', client: clientA, priority: 2 });
+            router.addProvider({ id: 'b', client: clientB, priority: 1 });
+
+            const status = router.getStatus();
+            expect(status).toHaveLength(2);
+            // b has lower priority number = tried first
+            expect(status[0]!.id).toBe('b');
+            expect(status[1]!.id).toBe('a');
+        });
+
+        it('removes providers', () => {
+            router.addProvider({ id: 'a', client: new MockClient('a'), priority: 0 });
+            router.addProvider({ id: 'b', client: new MockClient('b'), priority: 1 });
+            router.removeProvider('a');
+
+            expect(router.getStatus()).toHaveLength(1);
+            expect(router.getStatus()[0]!.id).toBe('b');
+        });
+    });
+
+    describe('execution with failover', () => {
+        it('uses the highest-priority provider', async () => {
+            const clientA = new MockClient('a');
+            const clientB = new MockClient('b');
+
+            router.addProvider({ id: 'a', client: clientA, priority: 0 });
+            router.addProvider({ id: 'b', client: clientB, priority: 1 });
+
+            const result = await router.chat([{ role: 'user', content: 'test' }]);
+            expect(result.provider).toBe('a');
+        });
+
+        it('fails over to next provider on error', async () => {
+            const clientA = new MockClient('a', {
+                chatFn: async () => { throw new Error('A failed'); },
+            });
+            const clientB = new MockClient('b');
+
+            router.addProvider({ id: 'a', client: clientA, priority: 0 });
+            router.addProvider({ id: 'b', client: clientB, priority: 1 });
+
+            const result = await router.chat([{ role: 'user', content: 'test' }]);
+            expect(result.provider).toBe('b');
+
+            // Check audit events
+            const events = auditor.getEvents();
+            const failoverEvents = events.filter(e => e.type === 'failover');
+            expect(failoverEvents.length).toBeGreaterThan(0);
+        });
+
+        it('retries within a provider before failover', async () => {
+            let attempts = 0;
+            const clientA = new MockClient('a', {
+                chatFn: async () => {
+                    attempts++;
+                    if (attempts === 1) throw new Error('Transient failure');
+                    return {
+                        message: { role: 'assistant' as const, content: 'recovered' },
+                        provider: 'a',
+                    };
+                },
+            });
+
+            router.addProvider({ id: 'a', client: clientA, priority: 0 });
+            const result = await router.chat([{ role: 'user', content: 'test' }]);
+
+            expect(result.provider).toBe('a');
+            expect(attempts).toBe(2); // first attempt + 1 retry
+        });
+
+        it('throws when all providers fail', async () => {
+            const clientA = new MockClient('a', {
+                chatFn: async () => { throw new Error('A failed'); },
+            });
+            const clientB = new MockClient('b', {
+                chatFn: async () => { throw new Error('B failed'); },
+            });
+
+            router.addProvider({ id: 'a', client: clientA, priority: 0 });
+            router.addProvider({ id: 'b', client: clientB, priority: 1 });
+
+            expect(router.chat([{ role: 'user', content: 'test' }])).rejects.toThrow();
+        });
+
+        it('throws when no providers configured', async () => {
+            expect(router.chat([{ role: 'user', content: 'test' }])).rejects.toThrow(
+                'No available LLM providers'
+            );
+        });
+    });
+
+    describe('health tracking', () => {
+        it('marks unhealthy after max failures', async () => {
+            const failing = new MockClient('fail', {
+                chatFn: async () => { throw new Error('always fails'); },
+            });
+            const backup = new MockClient('backup');
+
+            router.addProvider({ id: 'fail', client: failing, priority: 0 });
+            router.addProvider({ id: 'backup', client: backup, priority: 1 });
+
+            // Each chat call records 1 failure for 'fail', maxFailures is 2
+            await router.chat([{ role: 'user', content: 'test 1' }]);
+            await router.chat([{ role: 'user', content: 'test 2' }]);
+
+            const status = router.getStatus();
+            const failStatus = status.find(s => s.id === 'fail');
+            expect(failStatus!.healthy).toBe(false);
+        });
+
+        it('recovers after cooldown expires', async () => {
+            let callCount = 0;
+            const failing = new MockClient('fail', {
+                chatFn: async () => {
+                    callCount++;
+                    if (callCount <= 4) throw new Error('failing');
+                    return {
+                        message: { role: 'assistant' as const, content: 'recovered' },
+                        provider: 'fail',
+                    };
+                },
+            });
+            const backup = new MockClient('backup');
+
+            router.addProvider({ id: 'fail', client: failing, priority: 0 });
+            router.addProvider({ id: 'backup', client: backup, priority: 1 });
+
+            // First call: fail → backup
+            await router.chat([{ role: 'user', content: '1' }]);
+
+            // Wait for cooldown (100ms in test config)
+            await new Promise(r => setTimeout(r, 150));
+
+            // After cooldown, fail should be tried again
+            const status = router.getStatus();
+            const failStatus = status.find(s => s.id === 'fail');
+            expect(failStatus!.healthy).toBe(true);
+        });
+    });
+
+    describe('tool registration', () => {
+        it('broadcasts tool registration to all providers', () => {
+            const clientA = new MockClient('a');
+            const clientB = new MockClient('b');
+
+            router.addProvider({ id: 'a', client: clientA, priority: 0 });
+            router.addProvider({ id: 'b', client: clientB, priority: 1 });
+
+            router.registerTool(
+                'test_tool',
+                'A test tool',
+                { type: 'object', properties: {} },
+                async () => 'result',
+            );
+
+            // Both clients should have the tool registered
+            const defsA = clientA.getToolDefinitions();
+            const defsB = clientB.getToolDefinitions();
+            expect(defsA).toHaveLength(1);
+            expect(defsB).toHaveLength(1);
+            expect(defsA[0]!.function.name).toBe('test_tool');
+        });
+    });
+
+    describe('model aggregation', () => {
+        it('aggregates models from all providers', async () => {
+            const clientA = new MockClient('a');
+            const clientB = new MockClient('b');
+
+            router.addProvider({ id: 'a', client: clientA, priority: 0 });
+            router.addProvider({ id: 'b', client: clientB, priority: 1 });
+
+            const models = await router.getModels();
+            expect(models).toContain('mock-a');
+            expect(models).toContain('mock-b');
+        });
+    });
+});

package/src/tests/stream-decoder.test.ts

@@ -0,0 +1,179 @@
+/**
+ * Tests for stream-decoder.ts — Pluggable reasoning strategies
+ */
+import { describe, it, expect } from 'bun:test';
+import {
+    PassthroughDecoder,
+    StandardChatDecoder,
+    InterleavedReasoningDecoder,
+    createDecoder,
+    type DecodedEvent,
+} from '../stream-decoder.js';
+
+describe('PassthroughDecoder', () => {
+    it('emits all tokens as text events', () => {
+        const events: DecodedEvent[] = [];
+        const decoder = new PassthroughDecoder(e => events.push(e));
+
+        decoder.push('Hello');
+        decoder.push(' world');
+        decoder.flush();
+
+        expect(events).toHaveLength(2);
+        expect(events[0]).toEqual({ type: 'text', content: 'Hello' });
+        expect(events[1]).toEqual({ type: 'text', content: ' world' });
+    });
+
+    it('returns clean content', () => {
+        const decoder = new PassthroughDecoder(() => {});
+        decoder.push('Hello ');
+        decoder.push('world');
+        decoder.flush();
+        expect(decoder.getCleanContent()).toBe('Hello world');
+    });
+
+    it('returns no reasoning', () => {
+        const decoder = new PassthroughDecoder(() => {});
+        decoder.push('test');
+        expect(decoder.getReasoning()).toBeUndefined();
+    });
+});
+
+describe('StandardChatDecoder', () => {
+    it('emits text events', () => {
+        const events: DecodedEvent[] = [];
+        const decoder = new StandardChatDecoder(e => events.push(e));
+
+        decoder.push('Hello');
+        expect(events).toHaveLength(1);
+        expect(events[0]).toEqual({ type: 'text', content: 'Hello' });
+    });
+
+    it('emits reasoning events', () => {
+        const events: DecodedEvent[] = [];
+        const decoder = new StandardChatDecoder(e => events.push(e));
+
+        decoder.pushReasoning('Thinking...');
+        expect(events).toHaveLength(1);
+        expect(events[0]).toEqual({ type: 'thinking', content: 'Thinking...' });
+    });
+
+    it('emits tool call events', () => {
+        const events: DecodedEvent[] = [];
+        const decoder = new StandardChatDecoder(e => events.push(e));
+
+        const calls = [{
+            id: 'call_1',
+            type: 'function' as const,
+            function: { name: 'get_time', arguments: '{}' },
+        }];
+        decoder.pushToolCalls(calls);
+
+        expect(events).toHaveLength(1);
+        expect(events[0]!.type).toBe('tool_call');
+    });
+
+    it('tracks both content and reasoning', () => {
+        const decoder = new StandardChatDecoder(() => {});
+        decoder.push('Text');
+        decoder.pushReasoning('Reason');
+        decoder.flush();
+
+        expect(decoder.getCleanContent()).toBe('Text');
+        expect(decoder.getReasoning()).toBe('Reason');
+    });
+});
+
+describe('InterleavedReasoningDecoder', () => {
+    it('extracts think tags from text', () => {
+        const events: DecodedEvent[] = [];
+        const decoder = new InterleavedReasoningDecoder(e => events.push(e));
+
+        decoder.push('<think>I should analyze this</think>The answer is 42');
+        decoder.flush();
+
+        const thinkEvents = events.filter(e => e.type === 'thinking');
+        const textEvents = events.filter(e => e.type === 'text');
+
+        expect(thinkEvents.length).toBeGreaterThan(0);
+        expect(textEvents.length).toBeGreaterThan(0);
+        expect(decoder.getReasoning()).toBe('I should analyze this');
+        expect(decoder.getCleanContent()).toBe('The answer is 42');
+    });
+
+    it('handles think tags split across chunks', () => {
+        const events: DecodedEvent[] = [];
+        const decoder = new InterleavedReasoningDecoder(e => events.push(e));
+
+        decoder.push('<thi');
+        decoder.push('nk>Split reasoning</th');
+        decoder.push('ink>Done');
+        decoder.flush();
+
+        expect(decoder.getReasoning()).toBe('Split reasoning');
+        expect(decoder.getCleanContent()).toBe('Done');
+    });
+
+    it('handles progress tags', () => {
+        const events: DecodedEvent[] = [];
+        const decoder = new InterleavedReasoningDecoder(e => events.push(e));
+
+        decoder.push('<progress>Loading data</progress>Complete');
+        decoder.flush();
+
+        const progressEvents = events.filter(e => e.type === 'progress');
+        expect(progressEvents.length).toBeGreaterThan(0);
+        expect(decoder.getCleanContent()).toBe('Complete');
+    });
+
+    it('handles plain text with no tags', () => {
+        const events: DecodedEvent[] = [];
+        const decoder = new InterleavedReasoningDecoder(e => events.push(e));
+
+        decoder.push('Just plain text');
+        decoder.flush();
+
+        expect(decoder.getCleanContent()).toBe('Just plain text');
+        expect(decoder.getReasoning()).toBeUndefined();
+    });
+
+    it('handles empty reasoning', () => {
+        const decoder = new InterleavedReasoningDecoder(() => {});
+        decoder.push('<think></think>Content');
+        decoder.flush();
+
+        expect(decoder.getCleanContent()).toBe('Content');
+        expect(decoder.getReasoning()).toBeUndefined();
+    });
+
+    it('handles multiple think blocks', () => {
+        const decoder = new InterleavedReasoningDecoder(() => {});
+
+        decoder.push('<think>First thought</think>Text<think>Second thought</think>More text');
+        decoder.flush();
+
+        expect(decoder.getReasoning()).toBe('First thoughtSecond thought');
+        expect(decoder.getCleanContent()).toBe('TextMore text');
+    });
+});
+
+describe('createDecoder', () => {
+    it('creates passthrough decoder', () => {
+        const decoder = createDecoder('passthrough', () => {});
+        expect(decoder).toBeInstanceOf(PassthroughDecoder);
+    });
+
+    it('creates standard-chat decoder', () => {
+        const decoder = createDecoder('standard-chat', () => {});
+        expect(decoder).toBeInstanceOf(StandardChatDecoder);
+    });
+
+    it('creates interleaved-reasoning decoder', () => {
+        const decoder = createDecoder('interleaved-reasoning', () => {});
+        expect(decoder).toBeInstanceOf(InterleavedReasoningDecoder);
+    });
+
+    it('throws for unknown type', () => {
+        expect(() => createDecoder('unknown' as never, () => {})).toThrow('Unknown decoder type');
+    });
+});