universal-llm-client 4.3.0 → 4.5.0

package/src/tests/auditor.test.ts

@@ -0,0 +1,224 @@
+/**
+ * Tests for auditor.ts — Observability implementations
+ */
+import { describe, it, expect } from 'bun:test';
+import { NoopAuditor, ConsoleAuditor, BufferedAuditor, type AuditEvent } from '../auditor.js';
+
+describe('NoopAuditor', () => {
+    it('accepts events without error', () => {
+        const auditor = new NoopAuditor();
+        expect(() => {
+            auditor.record({
+                timestamp: Date.now(),
+                type: 'request',
+                provider: 'test',
+            });
+        }).not.toThrow();
+    });
+
+    it('accepts structured output events without error', () => {
+        const auditor = new NoopAuditor();
+        expect(() => {
+            auditor.record({
+                timestamp: Date.now(),
+                type: 'structured_request',
+                provider: 'test',
+                schemaName: 'User',
+            });
+        }).not.toThrow();
+    });
+});
+
+describe('ConsoleAuditor', () => {
+    it('creates with default prefix', () => {
+        const auditor = new ConsoleAuditor();
+        expect(auditor).toBeDefined();
+    });
+
+    it('creates with custom prefix', () => {
+        const auditor = new ConsoleAuditor('[TEST]');
+        expect(auditor).toBeDefined();
+    });
+
+    it('records all event types without error', () => {
+        const auditor = new ConsoleAuditor('[TEST]');
+        const types: AuditEvent['type'][] = [
+            'request', 'response', 'stream_start', 'stream_end',
+            'tool_call', 'tool_result', 'error', 'retry', 'failover',
+            'structured_request', 'structured_response', 'structured_validation_error',
+        ];
+
+        for (const type of types) {
+            expect(() => {
+                auditor.record({
+                    timestamp: Date.now(),
+                    type,
+                    provider: 'test',
+                    model: 'test-model',
+                    duration: 100,
+                    usage: { inputTokens: 10, outputTokens: 20, totalTokens: 30 },
+                    error: type === 'error' || type === 'structured_validation_error' ? 'test error' : undefined,
+                    metadata: type === 'failover' ? { nextProvider: 'backup' } : undefined,
+                    schemaName: type.startsWith('structured') ? 'User' : undefined,
+                    rawOutput: type === 'structured_validation_error' ? '{"name": "invalid"}' : undefined,
+                });
+            }).not.toThrow();
+        }
+    });
+
+    it('logs structured_request with schema name', () => {
+        const auditor = new ConsoleAuditor('[TEST]');
+        // Should not throw when logging structured request
+        expect(() => {
+            auditor.record({
+                timestamp: Date.now(),
+                type: 'structured_request',
+                provider: 'ollama',
+                schemaName: 'User',
+            });
+        }).not.toThrow();
+    });
+
+    it('logs structured_response with duration and schema name', () => {
+        const auditor = new ConsoleAuditor('[TEST]');
+        expect(() => {
+            auditor.record({
+                timestamp: Date.now(),
+                type: 'structured_response',
+                provider: 'google',
+                model: 'gemini-2.0-flash',
+                duration: 150,
+                schemaName: 'User',
+                usage: { inputTokens: 100, outputTokens: 50, totalTokens: 150 },
+            });
+        }).not.toThrow();
+    });
+
+    it('logs structured_validation_error with schema name and error', () => {
+        const auditor = new ConsoleAuditor('[TEST]');
+        expect(() => {
+            auditor.record({
+                timestamp: Date.now(),
+                type: 'structured_validation_error',
+                provider: 'openai',
+                schemaName: 'User',
+                error: 'Validation failed: name is required',
+                rawOutput: '{"age": 30}',
+            });
+        }).not.toThrow();
+    });
+});
+
+describe('BufferedAuditor', () => {
+    it('buffers events', () => {
+        const auditor = new BufferedAuditor();
+        const event: AuditEvent = {
+            timestamp: Date.now(),
+            type: 'request',
+            provider: 'test',
+        };
+
+        auditor.record(event);
+        auditor.record(event);
+        auditor.record(event);
+
+        expect(auditor.getEvents()).toHaveLength(3);
+    });
+
+    it('buffers structured output events', () => {
+        const auditor = new BufferedAuditor();
+        
+        auditor.record({
+            timestamp: Date.now(),
+            type: 'structured_request',
+            provider: 'ollama',
+            schemaName: 'User',
+        });
+        auditor.record({
+            timestamp: Date.now(),
+            type: 'structured_response',
+            provider: 'ollama',
+            schemaName: 'User',
+            duration: 100,
+        });
+
+        const events = auditor.getEvents();
+        expect(events).toHaveLength(2);
+        expect(events[0]?.type).toBe('structured_request');
+        expect(events[0]?.schemaName).toBe('User');
+        expect(events[1]?.type).toBe('structured_response');
+    });
+
+    it('buffers structured_validation_error events', () => {
+        const auditor = new BufferedAuditor();
+        
+        auditor.record({
+            timestamp: Date.now(),
+            type: 'structured_validation_error',
+            provider: 'openai',
+            schemaName: 'User',
+            error: 'Validation failed',
+            rawOutput: '{"invalid": true}',
+        });
+
+        const events = auditor.getEvents();
+        expect(events).toHaveLength(1);
+        expect(events[0]?.type).toBe('structured_validation_error');
+        expect(events[0]?.schemaName).toBe('User');
+        expect(events[0]?.error).toBe('Validation failed');
+        expect(events[0]?.rawOutput).toBe('{"invalid": true}');
+    });
+
+    it('flushes events to callback', async () => {
+        const flushed: AuditEvent[][] = [];
+        const auditor = new BufferedAuditor({
+            onFlush: async (events) => {
+                flushed.push([...events]);
+            },
+        });
+
+        auditor.record({ timestamp: 1, type: 'request' });
+        auditor.record({ timestamp: 2, type: 'response' });
+
+        await auditor.flush();
+
+        expect(flushed).toHaveLength(1);
+        expect(flushed[0]).toHaveLength(2);
+        expect(auditor.getEvents()).toHaveLength(0);
+    });
+
+    it('auto-flushes when buffer is full', async () => {
+        let flushCount = 0;
+        const auditor = new BufferedAuditor({
+            maxBufferSize: 3,
+            onFlush: async () => { flushCount++; },
+        });
+
+        auditor.record({ timestamp: 1, type: 'request' });
+        auditor.record({ timestamp: 2, type: 'request' });
+        auditor.record({ timestamp: 3, type: 'request' }); // triggers auto-flush
+
+        // Give auto-flush time to complete
+        await new Promise(r => setTimeout(r, 50));
+        expect(flushCount).toBe(1);
+    });
+
+    it('clears without flushing', () => {
+        const auditor = new BufferedAuditor();
+        auditor.record({ timestamp: 1, type: 'request' });
+        auditor.record({ timestamp: 2, type: 'response' });
+
+        auditor.clear();
+        expect(auditor.getEvents()).toHaveLength(0);
+    });
+
+    it('flush with no events is a no-op', async () => {
+        let flushed = false;
+        const auditor = new BufferedAuditor({
+            onFlush: async () => { flushed = true; },
+        });
+
+        await auditor.flush();
+        expect(flushed).toBe(false);
+    });
+});

package/src/tests/gemma-diffusion.test.ts

@@ -0,0 +1,115 @@
+/**
+ * Tests for the DiffusionGemma native-protocol adapter.
+ * Wire-format samples are taken verbatim from live vLLM responses
+ * (skip_special_tokens: false) captured June 2026.
+ */
+
+import { describe, expect, it } from 'bun:test';
+import {
+    gemmaArgsToJson,
+    isGemmaDiffusionModel,
+    parseGemmaDiffusionOutput,
+} from '../gemma-diffusion.js';
+
+describe('isGemmaDiffusionModel', () => {
+    it('detects the served model id', () => {
+        expect(isGemmaDiffusionModel('RedHatAI/diffusiongemma-26B-A4B-it-NVFP4')).toBe(true);
+        expect(isGemmaDiffusionModel('nvidia/DiffusionGemma-26B')).toBe(true);
+        expect(isGemmaDiffusionModel('diffusion_gemma-mini')).toBe(true);
+    });
+
+    it('ignores other models', () => {
+        expect(isGemmaDiffusionModel('gemma-4-27b-it')).toBe(false);
+        expect(isGemmaDiffusionModel('gpt-4o')).toBe(false);
+        expect(isGemmaDiffusionModel('stable-diffusion-xl')).toBe(false);
+    });
+});
+
+describe('gemmaArgsToJson', () => {
+    it('converts quoted strings and bare keys', () => {
+        const json = gemmaArgsToJson('city:<|"|>Paris<|"|>,unit:<|"|>celsius<|"|>');
+        expect(JSON.parse(json)).toEqual({ city: 'Paris', unit: 'celsius' });
+    });
+
+    it('handles numbers, booleans and null', () => {
+        const json = gemmaArgsToJson('count:3,ratio:-2.5e2,on:true,off:false,nothing:null');
+        expect(JSON.parse(json)).toEqual({ count: 3, ratio: -250, on: true, off: false, nothing: null });
+    });
+
+    it('preserves JSON-hostile characters inside quoted strings', () => {
+        const json = gemmaArgsToJson('q:<|"|>a, b: {c} [d] "e"<|"|>');
+        expect(JSON.parse(json)).toEqual({ q: 'a, b: {c} [d] "e"' });
+    });
+
+    it('handles nested objects and arrays', () => {
+        const json = gemmaArgsToJson('filter:{city:<|"|>Rio<|"|>,limit:2},tags:[<|"|>a<|"|>,<|"|>b<|"|>,1]');
+        expect(JSON.parse(json)).toEqual({ filter: { city: 'Rio', limit: 2 }, tags: ['a', 'b', 1] });
+    });
+
+    it('treats unquoted bare words as strings (model deviation)', () => {
+        const json = gemmaArgsToJson('unit:celsius,city:Paris');
+        expect(JSON.parse(json)).toEqual({ unit: 'celsius', city: 'Paris' });
+    });
+
+    it('handles empty arguments', () => {
+        expect(JSON.parse(gemmaArgsToJson(''))).toEqual({});
+    });
+});
+
+describe('parseGemmaDiffusionOutput', () => {
+    it('parses the live tool-call wire format', () => {
+        const raw =
+            '<|channel>thought\nThe user is asking for the weather. I should use the `get_weather` tool.<channel|>' +
+            '<|tool_call>call:get_weather{city:<|"|>Paris<|"|>,unit:<|"|>celsius<|"|>}<tool_call|>';
+        const parsed = parseGemmaDiffusionOutput(raw);
+        expect(parsed.reasoning).toContain('get_weather');
+        expect(parsed.content).toBe('');
+        expect(parsed.toolCalls).toHaveLength(1);
+        expect(parsed.toolCalls[0]!.name).toBe('get_weather');
+        expect(JSON.parse(parsed.toolCalls[0]!.argumentsJson)).toEqual({ city: 'Paris', unit: 'celsius' });
+    });
+
+    it('separates reasoning from answer (the live 42 sample)', () => {
+        const raw =
+            '<|channel>thought\n*   Question: What is 17 + 25?\n    *   30 + 12 = 42\n\n    *   The answer is 42.<channel|>42';
+        const parsed = parseGemmaDiffusionOutput(raw);
+        expect(parsed.content).toBe('42');
+        expect(parsed.reasoning).toContain('30 + 12 = 42');
+        expect(parsed.toolCalls).toHaveLength(0);
+    });
+
+    it('handles answer text after a tool result turn (no thought)', () => {
+        const parsed = parseGemmaDiffusionOutput('The current weather in Paris is 18°C and partly cloudy.');
+        expect(parsed.content).toBe('The current weather in Paris is 18°C and partly cloudy.');
+        expect(parsed.reasoning).toBe('');
+        expect(parsed.toolCalls).toHaveLength(0);
+    });
+
+    it('captures a dangling unterminated thought channel (max_tokens cutoff)', () => {
+        const parsed = parseGemmaDiffusionOutput('<|channel>thought\nStill reasoning about');
+        expect(parsed.content).toBe('');
+        expect(parsed.reasoning).toBe('Still reasoning about');
+    });
+
+    it('parses multiple tool calls in one turn', () => {
+        const raw =
+            '<|tool_call>call:get_weather{city:<|"|>Paris<|"|>}<tool_call|>' +
+            '<|tool_call>call:get_weather{city:<|"|>London<|"|>}<tool_call|>';
+        const parsed = parseGemmaDiffusionOutput(raw);
+        expect(parsed.toolCalls.map(t => JSON.parse(t.argumentsJson)['city'])).toEqual(['Paris', 'London']);
+    });
+
+    it('strips residual control tokens from text', () => {
+        const parsed = parseGemmaDiffusionOutput('Hello there.<turn|>');
+        expect(parsed.content).toBe('Hello there.');
+    });
+
+    it('strips stray unbalanced channel markers (live run 1 sample)', () => {
+        const raw =
+            '<|channel>thought\nThe current weather is 18C.<channel|>' +
+            '<channel|>The weather in Paris is currently 18°C and partly cloudy.';
+        const parsed = parseGemmaDiffusionOutput(raw);
+        expect(parsed.content).toBe('The weather in Paris is currently 18°C and partly cloudy.');
+        expect(parsed.reasoning).toBe('The current weather is 18C.');
+    });
+});

package/src/tests/http.test.ts

@@ -0,0 +1,200 @@
+/**
+ * Tests for http.ts — Universal HTTP utilities
+ */
+import { describe, it, expect, mock, beforeEach, afterEach } from 'bun:test';
+import { httpRequest, parseNDJSON, parseSSE, buildHeaders } from '../http.js';
+import { AIModelApiType } from '../interfaces.js';
+
+describe('httpRequest', () => {
+    const originalFetch = globalThis.fetch;
+
+    afterEach(() => {
+        globalThis.fetch = originalFetch;
+    });
+
+    it('makes a GET request and parses JSON', async () => {
+        globalThis.fetch = mock(async () =>
+            new Response(JSON.stringify({ ok: true }), {
+                status: 200,
+                headers: { 'Content-Type': 'application/json' },
+            })
+        ) as typeof fetch;
+
+        const result = await httpRequest<{ ok: boolean }>('http://test.com/api');
+        expect(result.ok).toBe(true);
+        expect(result.status).toBe(200);
+        expect(result.data.ok).toBe(true);
+    });
+
+    it('makes a POST request with body', async () => {
+        let capturedBody: string | undefined;
+        globalThis.fetch = mock(async (_url: string | URL | Request, init?: RequestInit) => {
+            capturedBody = init?.body as string;
+            return new Response(JSON.stringify({ received: true }), {
+                status: 200,
+                headers: { 'Content-Type': 'application/json' },
+            });
+        }) as typeof fetch;
+
+        await httpRequest('http://test.com/api', {
+            method: 'POST',
+            body: { message: 'hello' },
+        });
+
+        expect(capturedBody).toBe(JSON.stringify({ message: 'hello' }));
+    });
+
+    it('throws on non-OK response', async () => {
+        globalThis.fetch = mock(async () =>
+            new Response('Unauthorized', { status: 401 })
+        ) as typeof fetch;
+
+        expect(httpRequest('http://test.com/api')).rejects.toThrow('HTTP 401');
+    });
+
+    it('includes custom headers', async () => {
+        let capturedHeaders: HeadersInit | undefined;
+        globalThis.fetch = mock(async (_url: string | URL | Request, init?: RequestInit) => {
+            capturedHeaders = init?.headers;
+            return new Response(JSON.stringify({}), { status: 200 });
+        }) as typeof fetch;
+
+        await httpRequest('http://test.com/api', {
+            headers: { 'X-Custom': 'value' },
+        });
+
+        expect(capturedHeaders).toHaveProperty('X-Custom', 'value');
+    });
+});
+
+describe('parseNDJSON', () => {
+    it('parses newline-delimited JSON', async () => {
+        async function* source(): AsyncGenerator<string> {
+            yield '{"a":1}\n{"b":2}\n';
+        }
+
+        const results: Record<string, number>[] = [];
+        for await (const item of parseNDJSON<Record<string, number>>(source())) {
+            results.push(item);
+        }
+
+        expect(results).toHaveLength(2);
+        expect(results[0]).toEqual({ a: 1 });
+        expect(results[1]).toEqual({ b: 2 });
+    });
+
+    it('handles chunks split across JSON boundaries', async () => {
+        async function* source(): AsyncGenerator<string> {
+            yield '{"a":';
+            yield '1}\n{"b":2';
+            yield '}\n';
+        }
+
+        const results: unknown[] = [];
+        for await (const item of parseNDJSON(source())) {
+            results.push(item);
+        }
+
+        expect(results).toHaveLength(2);
+    });
+
+    it('skips empty lines', async () => {
+        async function* source(): AsyncGenerator<string> {
+            yield '{"a":1}\n\n\n{"b":2}\n';
+        }
+
+        const results: unknown[] = [];
+        for await (const item of parseNDJSON(source())) {
+            results.push(item);
+        }
+
+        expect(results).toHaveLength(2);
+    });
+
+    it('handles remaining buffer content', async () => {
+        async function* source(): AsyncGenerator<string> {
+            yield '{"a":1}';
+        }
+
+        const results: unknown[] = [];
+        for await (const item of parseNDJSON(source())) {
+            results.push(item);
+        }
+
+        expect(results).toHaveLength(1);
+    });
+});
+
+describe('parseSSE', () => {
+    it('parses server-sent events', async () => {
+        async function* source(): AsyncGenerator<string> {
+            yield 'data: {"content":"hello"}\n\ndata: {"content":"world"}\n\n';
+        }
+
+        const results: { event?: string; data: string }[] = [];
+        for await (const event of parseSSE(source())) {
+            results.push(event);
+        }
+
+        expect(results).toHaveLength(2);
+        expect(results[0]!.data).toBe('{"content":"hello"}');
+        expect(results[1]!.data).toBe('{"content":"world"}');
+    });
+
+    it('skips [DONE] events', async () => {
+        async function* source(): AsyncGenerator<string> {
+            yield 'data: {"content":"hello"}\n\ndata: [DONE]\n\n';
+        }
+
+        const results: unknown[] = [];
+        for await (const event of parseSSE(source())) {
+            results.push(event);
+        }
+
+        expect(results).toHaveLength(1);
+    });
+
+    it('extracts event type', async () => {
+        async function* source(): AsyncGenerator<string> {
+            yield 'event: custom\ndata: {"test":true}\n\n';
+        }
+
+        const results: { event?: string; data: string }[] = [];
+        for await (const event of parseSSE(source())) {
+            results.push(event);
+        }
+
+        expect(results).toHaveLength(1);
+        expect(results[0]!.event).toBe('custom');
+    });
+});
+
+describe('buildHeaders', () => {
+    it('returns Content-Type header', () => {
+        const headers = buildHeaders({
+            model: 'test',
+            url: 'http://test.com',
+            apiType: AIModelApiType.Ollama,
+        });
+        expect(headers['Content-Type']).toBe('application/json');
+    });
+
+    it('adds Authorization header when apiKey is set', () => {
+        const headers = buildHeaders({
+            model: 'test',
+            url: 'http://test.com',
+            apiType: AIModelApiType.OpenAI,
+            apiKey: 'sk-test',
+        });
+        expect(headers['Authorization']).toBe('Bearer sk-test');
+    });
+
+    it('omits Authorization when no apiKey', () => {
+        const headers = buildHeaders({
+            model: 'test',
+            url: 'http://test.com',
+            apiType: AIModelApiType.Ollama,
+        });
+        expect(headers['Authorization']).toBeUndefined();
+    });
+});

package/src/tests/interfaces.test.ts

@@ -0,0 +1,117 @@
+/**
+ * Tests for interfaces.ts — Helper functions and type utilities
+ */
+import { describe, it, expect } from 'bun:test';
+import {
+    textContent,
+    imageContent,
+    multimodalMessage,
+    extractTextContent,
+    hasImages,
+    AIModelApiType,
+    AIModelType,
+} from '../interfaces.js';
+
+describe('Helper Functions', () => {
+    describe('textContent', () => {
+        it('creates a text content part', () => {
+            const result = textContent('Hello');
+            expect(result).toEqual({ type: 'text', text: 'Hello' });
+        });
+    });
+
+    describe('imageContent', () => {
+        it('creates an image content part from base64', () => {
+            const result = imageContent('abc123');
+            expect(result.type).toBe('image_url');
+            expect(result.image_url.url).toBe('data:image/jpeg;base64,abc123');
+        });
+
+        it('creates an image content part from URL', () => {
+            const result = imageContent('https://example.com/image.jpg');
+            expect(result.image_url.url).toBe('https://example.com/image.jpg');
+        });
+
+        it('creates an image content part from data URI', () => {
+            const result = imageContent('data:image/png;base64,abc');
+            expect(result.image_url.url).toBe('data:image/png;base64,abc');
+        });
+
+        it('respects custom mimeType', () => {
+            const result = imageContent('abc123', 'image/png');
+            expect(result.image_url.url).toBe('data:image/png;base64,abc123');
+        });
+
+        it('includes detail parameter', () => {
+            const result = imageContent('https://example.com/img.jpg', 'image/jpeg', 'low');
+            expect(result.image_url.detail).toBe('low');
+        });
+    });
+
+    describe('multimodalMessage', () => {
+        it('creates a user message with text and images', () => {
+            const msg = multimodalMessage('Describe this', ['base64img']);
+            expect(msg.role).toBe('user');
+            expect(Array.isArray(msg.content)).toBe(true);
+            const parts = msg.content as Array<{ type: string }>;
+            expect(parts).toHaveLength(2);
+            expect(parts[0]!.type).toBe('text');
+            expect(parts[1]!.type).toBe('image_url');
+        });
+
+        it('handles multiple images', () => {
+            const msg = multimodalMessage('Compare', ['img1', 'img2', 'img3']);
+            const parts = msg.content as Array<{ type: string }>;
+            expect(parts).toHaveLength(4); // 1 text + 3 images
+        });
+    });
+
+    describe('extractTextContent', () => {
+        it('extracts text from string content', () => {
+            expect(extractTextContent('Hello')).toBe('Hello');
+        });
+
+        it('extracts text from content parts array', () => {
+            const content = [
+                textContent('Hello'),
+                imageContent('img'),
+                textContent(' World'),
+            ];
+            expect(extractTextContent(content)).toBe('Hello World');
+        });
+
+        it('returns empty string from image-only content', () => {
+            const content = [imageContent('img')];
+            expect(extractTextContent(content)).toBe('');
+        });
+    });
+
+    describe('hasImages', () => {
+        it('returns false for string content', () => {
+            expect(hasImages('Hello')).toBe(false);
+        });
+
+        it('returns false for text-only content parts', () => {
+            expect(hasImages([textContent('Hello')])).toBe(false);
+        });
+
+        it('returns true for content with images', () => {
+            expect(hasImages([textContent('Hello'), imageContent('img')])).toBe(true);
+        });
+    });
+});
+
+describe('Enums', () => {
+    it('AIModelApiType has expected values', () => {
+        expect(AIModelApiType.Ollama).toBe('ollama');
+        expect(AIModelApiType.OpenAI).toBe('openai');
+        expect(AIModelApiType.Google).toBe('google');
+        expect(AIModelApiType.Vertex).toBe('vertex');
+        expect(AIModelApiType.LlamaCpp).toBe('llamacpp');
+    });
+
+    it('AIModelType has expected values', () => {
+        expect(AIModelType.Chat).toBe('chat');
+        expect(AIModelType.Embedding).toBe('embedding');
+    });
+});