universal-llm-client 4.0.0 → 4.2.0

package/src/http.ts

@@ -0,0 +1,247 @@
+/**
+ * Universal LLM Client v3 — HTTP Utilities
+ *
+ * Zero-dependency HTTP layer using native fetch.
+ * Works on Node 22+, Bun, Deno, and browsers.
+ */
+
+import type { LLMClientOptions } from './interfaces.js';
+
+// ============================================================================
+// Types
+// ============================================================================
+
+export interface HttpRequestOptions {
+    method?: 'GET' | 'POST';
+    headers?: Record<string, string>;
+    body?: unknown;
+    timeout?: number;
+    signal?: AbortSignal;
+}
+
+export interface HttpResponse<T = unknown> {
+    ok: boolean;
+    status: number;
+    data: T;
+    /** Response headers (when available) */
+    headers?: Headers;
+}
+
+// ============================================================================
+// HTTP Request
+// ============================================================================
+
+/**
+ * Make an HTTP request with timeout and error handling.
+ * Uses native fetch (available in all target runtimes).
+ */
+export async function httpRequest<T = unknown>(
+    url: string,
+    options: HttpRequestOptions = {},
+): Promise<HttpResponse<T>> {
+    const { method = 'GET', headers = {}, body, timeout = 30000, signal } = options;
+
+    const controller = new AbortController();
+    const timeoutId = setTimeout(() => controller.abort(), timeout);
+
+    // Combine external signal with timeout
+    const combinedSignal = signal
+        ? AbortSignal.any([signal, controller.signal])
+        : controller.signal;
+
+    try {
+        const response = await fetch(url, {
+            method,
+            headers: {
+                'Content-Type': 'application/json',
+                ...headers,
+            },
+            body: body ? JSON.stringify(body) : undefined,
+            signal: combinedSignal,
+        });
+
+        clearTimeout(timeoutId);
+
+        if (!response.ok) {
+            const errorText = await response.text().catch(() => 'Unknown error');
+            throw new Error(`HTTP ${response.status}: ${errorText}`);
+        }
+
+        const data = (await response.json()) as T;
+
+        return {
+            ok: response.ok,
+            status: response.status,
+            data,
+            headers: response.headers,
+        };
+    } catch (error) {
+        clearTimeout(timeoutId);
+
+        if (error instanceof Error && error.name === 'AbortError') {
+            throw new Error(`Request timeout after ${timeout}ms: ${url}`);
+        }
+        throw error;
+    }
+}
+
+// ============================================================================
+// Streaming HTTP
+// ============================================================================
+
+/**
+ * Make a streaming HTTP request.
+ * Yields raw string chunks as they arrive.
+ */
+export async function* httpStream(
+    url: string,
+    options: HttpRequestOptions = {},
+): AsyncGenerator<string, void, unknown> {
+    const { method = 'POST', headers = {}, body, timeout = 120000, signal } = options;
+
+    const controller = new AbortController();
+    const timeoutId = setTimeout(() => controller.abort(), timeout);
+
+    const combinedSignal = signal
+        ? AbortSignal.any([signal, controller.signal])
+        : controller.signal;
+
+    try {
+        const response = await fetch(url, {
+            method,
+            headers: {
+                'Content-Type': 'application/json',
+                ...headers,
+            },
+            body: body ? JSON.stringify(body) : undefined,
+            signal: combinedSignal,
+        });
+
+        clearTimeout(timeoutId);
+
+        if (!response.ok) {
+            const errorText = await response.text().catch(() => 'Unknown error');
+            throw new Error(`HTTP ${response.status}: ${errorText}`);
+        }
+
+        if (!response.body) {
+            throw new Error('No response body for streaming');
+        }
+
+        const reader = response.body.getReader();
+        const decoder = new TextDecoder();
+
+        try {
+            while (true) {
+                const { done, value } = await reader.read();
+                if (done) break;
+                yield decoder.decode(value, { stream: true });
+            }
+        } finally {
+            reader.releaseLock();
+        }
+    } catch (error) {
+        clearTimeout(timeoutId);
+
+        if (error instanceof Error && error.name === 'AbortError') {
+            throw new Error(`Stream timeout after ${timeout}ms: ${url}`);
+        }
+        throw error;
+    }
+}
+
+// ============================================================================
+// Protocol Parsers
+// ============================================================================
+
+/**
+ * Parse NDJSON (newline-delimited JSON) stream.
+ * Used by Ollama's streaming API.
+ */
+export async function* parseNDJSON<T = unknown>(
+    stream: AsyncGenerator<string>,
+): AsyncGenerator<T, void, unknown> {
+    let buffer = '';
+
+    for await (const chunk of stream) {
+        buffer += chunk;
+        const lines = buffer.split('\n');
+        buffer = lines.pop() ?? '';
+
+        for (const line of lines) {
+            const trimmed = line.trim();
+            if (!trimmed) continue;
+
+            try {
+                yield JSON.parse(trimmed) as T;
+            } catch {
+                // Skip invalid JSON lines
+            }
+        }
+    }
+
+    // Handle remaining buffer
+    if (buffer.trim()) {
+        try {
+            yield JSON.parse(buffer) as T;
+        } catch {
+            // Skip invalid JSON
+        }
+    }
+}
+
+/**
+ * Parse Server-Sent Events stream.
+ * Used by OpenAI-compatible APIs and LlamaCpp/vLLM.
+ */
+export async function* parseSSE(
+    stream: AsyncGenerator<string>,
+): AsyncGenerator<{ event?: string; data: string }, void, unknown> {
+    let buffer = '';
+
+    for await (const chunk of stream) {
+        buffer += chunk;
+
+        // Split by double newlines (SSE event delimiter)
+        const events = buffer.split('\n\n');
+        buffer = events.pop() ?? '';
+
+        for (const event of events) {
+            const lines = event.split('\n');
+            let eventType: string | undefined;
+            const dataLines: string[] = [];
+
+            for (const line of lines) {
+                if (line.startsWith('event:')) {
+                    eventType = line.slice(6).trim();
+                } else if (line.startsWith('data:')) {
+                    dataLines.push(line.slice(5).trim());
+                }
+            }
+
+            const data = dataLines.join('\n');
+            if (data && data !== '[DONE]') {
+                yield { event: eventType, data };
+            }
+        }
+    }
+}
+
+// ============================================================================
+// Header Utilities
+// ============================================================================
+
+/**
+ * Build standard headers for LLM API requests.
+ */
+export function buildHeaders(options: LLMClientOptions): Record<string, string> {
+    const headers: Record<string, string> = {
+        'Content-Type': 'application/json',
+    };
+
+    if (options.apiKey) {
+        headers['Authorization'] = `Bearer ${options.apiKey}`;
+    }
+
+    return headers;
+}

package/src/index.ts

@@ -0,0 +1,161 @@
+/**
+ * Universal LLM Client v3
+ *
+ * A universal LLM client with transparent provider failover,
+ * streaming tool execution, pluggable reasoning, and native observability.
+ *
+ * @module universal-llm-client
+ */
+
+// ============================================================================
+// Public API — The Universal Client
+// ============================================================================
+
+export { AIModel } from './ai-model.js';
+
+// ============================================================================
+// Types & Interfaces
+// ============================================================================
+
+export {
+    // Enums
+    AIModelApiType,
+    AIModelType,
+    // Config
+    type AIModelConfig,
+    type ProviderConfig,
+    type LLMClientOptions,
+    // Messages
+    type LLMChatMessage,
+    type LLMMessageContent,
+    type LLMContentPart,
+    type LLMTextContent,
+    type LLMImageContent,
+    type LLMAudioContent,
+    // Responses
+    type LLMChatResponse,
+    type TokenUsageInfo,
+    // Tools
+    type LLMToolCall,
+    type LLMToolDefinition,
+    type LLMFunction,
+    type ToolHandler,
+    type ToolExecutionResult,
+    type ToolRegistry,
+    type ToolRegistryEntry,
+    // Options
+    type ChatOptions,
+    type ResponseFormat,
+    type OutputOptions,
+    // Model info
+    type ModelMetadata,
+    // Helpers
+    textContent,
+    imageContent,
+    multimodalMessage,
+    extractTextContent,
+    hasImages,
+    audioContent,
+    hasAudio,
+} from './interfaces.js';
+
+// ============================================================================
+// Observability
+// ============================================================================
+
+export {
+    type Auditor,
+    type AuditEvent,
+    type AuditEventType,
+    NoopAuditor,
+    ConsoleAuditor,
+    BufferedAuditor,
+} from './auditor.js';
+
+// ============================================================================
+// Stream Decoding
+// ============================================================================
+
+export {
+    type StreamDecoder,
+    type DecodedEvent,
+    type DecoderCallback,
+    type DecoderType,
+    type DecoderOptions,
+    type DecoderFactory,
+    createDecoder,
+    registerDecoder,
+    getRegisteredDecoders,
+    PassthroughDecoder,
+    StandardChatDecoder,
+    InterleavedReasoningDecoder,
+} from './stream-decoder.js';
+
+// ============================================================================
+// Tool Utilities
+// ============================================================================
+
+export {
+    ToolBuilder,
+    ToolExecutor,
+    createTimeTool,
+    createRandomNumberTool,
+} from './tools.js';
+
+// ============================================================================
+// HTTP Utilities (for advanced use cases)
+// ============================================================================
+
+export {
+    httpRequest,
+    httpStream,
+    parseNDJSON,
+    parseSSE,
+    buildHeaders,
+    type HttpRequestOptions,
+    type HttpResponse,
+} from './http.js';
+
+// ============================================================================
+// MCP Integration
+// ============================================================================
+
+export {
+    MCPToolBridge,
+    type MCPBridgeConfig,
+    type MCPServerConfig,
+    type MCPTool,
+} from './mcp.js';
+
+// ============================================================================
+// Structured Output
+// ============================================================================
+
+export {
+    StructuredOutputError,
+    type StructuredOutputErrorOptions,
+    type StructuredOutputOptions,
+    type StructuredOutputResult,
+    type StructuredOutputSuccess,
+    type StructuredOutputFailure,
+    type JSONSchema,
+    type SchemaProvider,
+    type ProviderSchema,
+    type SchemaConfig,
+    isStructuredOutputSuccess,
+    isStructuredOutputFailure,
+    // Schema conversion utilities
+    normalizeJsonSchema,
+    convertToProviderSchema,
+    stripUnsupportedFeatures,
+    getJsonSchema,
+    getJsonSchemaFromConfig,
+    // Validation functions
+    parseStructured,
+    tryParseStructured,
+    validateStructuredOutput,
+    stripJsonFences,
+    // Streaming parser
+    StreamingJsonParser,
+    type StreamingStructuredResult,
+} from './structured-output.js';