confused-ai-core 0.1.0

package/src/llm/openai-provider.ts

@@ -0,0 +1,313 @@
+/**
+ * OpenAI LLM provider.
+ * Requires: npm install openai
+ */
+
+import type {
+    LLMProvider,
+    Message,
+    GenerateResult,
+    GenerateOptions,
+    LLMToolDefinition,
+    ToolCall,
+    StreamOptions,
+} from './types.js';
+import { DebugLogger, createDebugLogger } from '../debug-logger.js';
+
+// Minimal types so we don't require openai at compile time (peer dependency at runtime)
+interface OpenAIClient {
+    chat: {
+        completions: {
+            create(params: OpenAICreateParams): Promise<OpenAIResponse | AsyncIterable<OpenAIStreamChunk>>;
+        };
+    };
+}
+interface OpenAICreateParams {
+    model: string;
+    messages: OpenAIMessageParam[];
+    temperature?: number;
+    max_tokens?: number;
+    stop?: string[];
+    tools?: OpenAITool[];
+    tool_choice?: 'auto' | 'none';
+    stream?: boolean;
+}
+// Content: string or multimodal parts (text, image_url, etc.) per OpenAI API
+type OpenAIContent = string | Array<{ type: string; text?: string; image_url?: { url: string; detail?: string }; file?: { url: string }; audio?: { url: string }; video?: { url: string } }> | null;
+type OpenAIMessageParam =
+    | { role: 'system' | 'user'; content: OpenAIContent }
+    | { role: 'assistant'; content: OpenAIContent; tool_calls?: { id: string; type: 'function'; function: { name: string; arguments: string } }[] }
+    | { role: 'tool'; content: string; tool_call_id: string };
+interface OpenAITool {
+    type: 'function';
+    function: { name: string; description: string; parameters: Record<string, unknown> };
+}
+interface OpenAIResponse {
+    choices?: { message?: { content?: string | null; tool_calls?: { id: string; function?: { name?: string; arguments?: string } }[] }; finish_reason?: string }[];
+    usage?: { prompt_tokens?: number; completion_tokens?: number; total_tokens?: number };
+}
+interface OpenAIStreamChunk {
+    choices?: {
+        delta?: {
+            content?: string | null;
+            tool_calls?: { index: number; id?: string; function?: { name?: string; arguments?: string } }[]
+        };
+        finish_reason?: string | null;
+    }[];
+    usage?: { prompt_tokens?: number; completion_tokens?: number; total_tokens?: number };
+}
+
+export interface OpenAIProviderConfig {
+    /** OpenAI client instance, or options to create one */
+    client?: OpenAIClient;
+    /** Model name (default: gpt-4o). Use e.g. llama3.2, bern2-8b for open models. */
+    model?: string;
+    /** API key (used only if client is not provided). Optional when baseURL points to a local server (e.g. Ollama). */
+    apiKey?: string;
+    /** Base URL for the API (e.g. https://api.openai.com/v1, or http://localhost:11434/v1 for Ollama). */
+    baseURL?: string;
+    /** Enable debug logging */
+    debug?: boolean;
+}
+
+/**
+ * Map framework Message[] to OpenAI format
+ */
+function toOpenAIMessages(messages: Message[]): OpenAIMessageParam[] {
+    return messages.map((m) => {
+        if (m.role === 'assistant' && 'toolCalls' in m && (m as { toolCalls?: ToolCall[] }).toolCalls?.length) {
+            const content = m.content;
+            const normalized = Array.isArray(content) ? content : (content ?? null);
+            return {
+                role: 'assistant',
+                content: normalized as OpenAIContent,
+                tool_calls: (m as { toolCalls: ToolCall[] }).toolCalls.map((tc) => ({
+                    id: tc.id,
+                    type: 'function' as const,
+                    function: { name: tc.name, arguments: JSON.stringify(tc.arguments) },
+                })),
+            };
+        }
+        if (m.role === 'tool') {
+            const toolMsg = m as Message & { toolCallId?: string };
+            const content = typeof m.content === 'string' ? m.content : (Array.isArray(m.content) ? (m.content.find((p: { type: string; text?: string }) => p.type === 'text') as { text?: string } | undefined)?.text ?? '' : '');
+            return {
+                role: 'tool',
+                content,
+                tool_call_id: toolMsg.toolCallId ?? '',
+            };
+        }
+        const content = m.content;
+        const normalized = Array.isArray(content) ? content : (content ?? null);
+        return { role: m.role as 'system' | 'user' | 'assistant', content: normalized as OpenAIContent };
+    });
+}
+
+/**
+ * Map framework LLMToolDefinition to OpenAI format
+ */
+function toOpenAITools(tools?: LLMToolDefinition[]): OpenAITool[] | undefined {
+    if (!tools?.length) return undefined;
+    return tools.map((t) => ({
+        type: 'function' as const,
+        function: {
+            name: t.name,
+            description: t.description,
+            parameters: t.parameters as Record<string, unknown>,
+        },
+    }));
+}
+
+/**
+ * OpenAI implementation of LLMProvider.
+ * Install the openai package: npm install openai
+ */
+export class OpenAIProvider implements LLMProvider {
+    private client: OpenAIClient;
+    private model: string;
+    private logger: DebugLogger;
+
+    constructor(config: OpenAIProviderConfig = {}) {
+        this.logger = createDebugLogger('OpenAIProvider', config.debug ?? false);
+
+        if (config.client) {
+            this.client = config.client;
+        } else {
+            const apiKey = config.apiKey ?? process.env.OPENAI_API_KEY;
+            const baseURL = config.baseURL ?? process.env.OPENAI_BASE_URL;
+            if (!baseURL && !apiKey) {
+                throw new Error('OpenAIProvider requires apiKey (or OPENAI_API_KEY) or baseURL (or OPENAI_BASE_URL)');
+            }
+            const { OpenAI } = require('openai') as {
+                OpenAI: new (opts: { apiKey?: string; baseURL?: string }) => OpenAIClient;
+            };
+            this.client = new OpenAI({
+                apiKey: apiKey ?? 'not-needed',
+                ...(baseURL && { baseURL }),
+            });
+        }
+        this.model = config.model ?? 'gpt-4o';
+        this.logger.debug('OpenAIProvider initialized', undefined, { model: this.model });
+    }
+
+    async generateText(messages: Message[], options?: GenerateOptions): Promise<GenerateResult> {
+        const startTime = Date.now();
+        this.logger.logStart('LLM generateText', {
+            messageCount: messages.length,
+            model: this.model,
+        });
+
+        const body: Record<string, unknown> = {
+            model: this.model,
+            messages: toOpenAIMessages(messages),
+            temperature: options?.temperature ?? 0.7,
+            max_tokens: options?.maxTokens,
+            stop: options?.stop,
+        };
+
+        const tools = toOpenAITools(options?.tools);
+        if (tools?.length) {
+            body.tools = tools;
+            body.tool_choice = options?.toolChoice === 'none' ? 'none' : 'auto';
+            this.logger.debug('Including tools in request', undefined, { toolCount: tools.length });
+        }
+
+        const response = await this.client.chat.completions.create(body as unknown as OpenAICreateParams) as OpenAIResponse;
+
+        const choice = response.choices?.[0];
+        if (!choice?.message) {
+            this.logger.warn('Empty response from LLM');
+            return { text: '', finishReason: choice?.finish_reason ?? 'unknown' };
+        }
+
+        const msg = choice.message;
+        let text = typeof msg.content === 'string' ? msg.content : '';
+
+        const toolCalls: ToolCall[] | undefined = msg.tool_calls?.map((tc: { id: string; function?: { name?: string; arguments?: string } }) => ({
+            id: tc.id,
+            name: tc.function?.name ?? '',
+            arguments: (() => {
+                try {
+                    return JSON.parse(tc.function?.arguments ?? '{}') as Record<string, unknown>;
+                } catch {
+                    return {};
+                }
+            })(),
+        }));
+
+        const duration = Date.now() - startTime;
+        this.logger.logComplete('LLM generateText', duration, {
+            textLength: text.length,
+            toolCallsCount: toolCalls?.length ?? 0,
+            tokens: response.usage?.total_tokens,
+        });
+
+        return {
+            text,
+            toolCalls: toolCalls?.length ? toolCalls : undefined,
+            finishReason: choice.finish_reason ?? undefined,
+            usage: response.usage
+                ? {
+                    promptTokens: response.usage.prompt_tokens,
+                    completionTokens: response.usage.completion_tokens,
+                    totalTokens: response.usage.total_tokens,
+                }
+                : undefined,
+        };
+    }
+
+    async streamText(messages: Message[], options?: StreamOptions): Promise<GenerateResult> {
+        const body: Record<string, unknown> = {
+            model: this.model,
+            messages: toOpenAIMessages(messages),
+            temperature: options?.temperature ?? 0.7,
+            max_tokens: options?.maxTokens,
+            stop: options?.stop,
+            stream: true,
+        };
+
+        const tools = toOpenAITools(options?.tools);
+        if (tools?.length) {
+            body.tools = tools;
+            body.tool_choice = options?.toolChoice === 'none' ? 'none' : 'auto';
+        }
+
+        const stream = await this.client.chat.completions.create(body as unknown as OpenAICreateParams) as AsyncIterable<OpenAIStreamChunk>;
+
+        let fullText = '';
+        const toolCallsMap = new Map<number, { id: string; name: string; args: string }>();
+        let finishReason: string | undefined;
+        let usage: GenerateResult['usage'];
+
+        for await (const chunk of stream) {
+            const delta = chunk.choices?.[0]?.delta;
+            if (!delta) continue;
+
+            // Handle text content
+            if (delta.content) {
+                const textDelta = delta.content;
+                fullText += textDelta;
+                options?.onChunk?.({ type: 'text', text: textDelta });
+            }
+
+            // Handle tool calls
+            if (delta.tool_calls) {
+                for (const tc of delta.tool_calls) {
+                    if (tc.id) {
+                        toolCallsMap.set(tc.index, {
+                            id: tc.id,
+                            name: tc.function?.name ?? '',
+                            args: tc.function?.arguments ?? ''
+                        });
+                    } else if (tc.function?.arguments) {
+                        const existing = toolCallsMap.get(tc.index);
+                        if (existing) {
+                            existing.args += tc.function.arguments;
+                        }
+                    }
+
+                    if (tc.function?.arguments) {
+                        options?.onChunk?.({
+                            type: 'tool_call',
+                            id: tc.id ?? toolCallsMap.get(tc.index)?.id ?? '',
+                            name: tc.function.name ?? toolCallsMap.get(tc.index)?.name ?? '',
+                            argsDelta: tc.function.arguments
+                        });
+                    }
+                }
+            }
+
+            if (chunk.choices?.[0]?.finish_reason) {
+                finishReason = chunk.choices[0].finish_reason ?? undefined;
+            }
+
+            if (chunk.usage) {
+                usage = {
+                    promptTokens: chunk.usage.prompt_tokens,
+                    completionTokens: chunk.usage.completion_tokens,
+                    totalTokens: chunk.usage.total_tokens,
+                };
+            }
+        }
+
+        // Parse tool calls
+        const toolCalls: ToolCall[] = Array.from(toolCallsMap.values()).map(tc => ({
+            id: tc.id,
+            name: tc.name,
+            arguments: (() => {
+                try {
+                    return JSON.parse(tc.args) as Record<string, unknown>;
+                } catch {
+                    return {};
+                }
+            })(),
+        }));
+
+        return {
+            text: fullText,
+            toolCalls: toolCalls.length ? toolCalls : undefined,
+            finishReason,
+            usage,
+        };
+    }
+}

package/src/llm/openrouter-provider.ts

@@ -0,0 +1,29 @@
+/**
+ * OpenRouter LLM provider.
+ * OpenRouter (https://openrouter.ai) routes to many models (OpenAI, Anthropic, Google, Meta, etc.) via one API.
+ * Uses the OpenAI-compatible endpoint; this is a thin wrapper around OpenAIProvider.
+ */
+
+import type { LLMProvider } from './types.js';
+import { OpenAIProvider } from './openai-provider.js';
+
+const OPENROUTER_BASE_URL = 'https://openrouter.ai/api/v1';
+
+export interface OpenRouterProviderConfig {
+    /** OpenRouter API key (or set OPENROUTER_API_KEY). */
+    apiKey: string;
+    /** Model id, e.g. openai/gpt-4o, anthropic/claude-3-sonnet, google/gemini-pro. Default: openai/gpt-4o */
+    model?: string;
+}
+
+/**
+ * Create an LLM provider that uses OpenRouter.
+ * Gives access to many best-in-class models (OpenAI, Anthropic, Google, etc.) through one API.
+ */
+export function createOpenRouterProvider(config: OpenRouterProviderConfig): LLMProvider {
+    return new OpenAIProvider({
+        apiKey: config.apiKey,
+        baseURL: OPENROUTER_BASE_URL,
+        model: config.model ?? 'openai/gpt-4o',
+    });
+}

package/src/llm/types.ts

@@ -0,0 +1,131 @@
+/**
+ * LLM provider abstraction for production-grade agent frameworks.
+ * Implement this interface to plug in OpenAI, Anthropic, Google, or custom backends.
+ */
+
+/**
+ * Role of a message in a conversation
+ */
+export type MessageRole = 'system' | 'user' | 'assistant' | 'tool';
+
+/**
+ * Multimodal content part: text, image_url, etc. (OpenAI-style)
+ */
+export type ContentPart =
+    | { readonly type: 'text'; readonly text: string }
+    | { readonly type: 'image_url'; readonly image_url: { readonly url: string; readonly detail?: 'low' | 'high' | 'auto' } }
+    | { readonly type: 'file'; readonly file: { readonly url: string; readonly filename?: string } }
+    | { readonly type: 'audio'; readonly audio: { readonly url: string } }
+    | { readonly type: 'video'; readonly video: { readonly url: string } };
+
+/**
+ * A single message in a conversation.
+ * content can be string (text-only) or ContentPart[] for multimodal (text, images, audio, video, files).
+ */
+export interface Message {
+    readonly role: MessageRole;
+    readonly content: string | ContentPart[];
+}
+
+/**
+ * Message with optional toolCallId (for role 'tool')
+ */
+export interface MessageWithToolId extends Message {
+    readonly toolCallId?: string;
+}
+
+/**
+ * Tool call requested by the model (name + arguments)
+ */
+export interface ToolCall {
+    readonly id: string;
+    readonly name: string;
+    readonly arguments: Record<string, unknown>;
+}
+
+/**
+ * Tool result to send back to the model
+ */
+export interface ToolResultMessage {
+    readonly toolCallId: string;
+    readonly content: string;
+}
+
+/**
+ * Assistant message that may include tool calls
+ */
+export interface AssistantMessage extends Message {
+    role: 'assistant';
+    content: string;
+    toolCalls?: ToolCall[];
+}
+
+/**
+ * Tool definition for the LLM (name, description, parameters schema as JSON Schema)
+ */
+export interface LLMToolDefinition {
+    readonly name: string;
+    readonly description: string;
+    readonly parameters: Record<string, unknown>; // JSON Schema
+}
+
+/**
+ * Result of a single generation (no streaming)
+ */
+export interface GenerateResult {
+    readonly text: string;
+    readonly toolCalls?: ToolCall[];
+    readonly finishReason?: string;
+    readonly usage?: { promptTokens?: number; completionTokens?: number; totalTokens?: number };
+}
+
+/**
+ * Options for generateText
+ */
+export interface GenerateOptions {
+    readonly temperature?: number;
+    readonly maxTokens?: number;
+    readonly tools?: LLMToolDefinition[];
+    readonly toolChoice?: 'auto' | 'none' | { type: 'tool'; name: string };
+    readonly stop?: string[];
+}
+
+/**
+ * Chunk from streaming (text delta or tool call delta)
+ */
+export interface StreamChunk {
+    readonly type: 'text';
+    readonly text: string;
+}
+
+export interface StreamToolCallChunk {
+    readonly type: 'tool_call';
+    readonly id: string;
+    readonly name: string;
+    readonly argsDelta: string;
+}
+
+export type StreamDelta = StreamChunk | StreamToolCallChunk;
+
+/**
+ * Options for streamText
+ */
+export interface StreamOptions extends GenerateOptions {
+    readonly onChunk?: (delta: StreamDelta) => void;
+}
+
+/**
+ * LLM provider interface.
+ * Implement for OpenAI, Anthropic, Google, local models, etc.
+ */
+export interface LLMProvider {
+    /**
+     * Generate a single response (and optional tool calls) from messages.
+     */
+    generateText(messages: Message[], options?: GenerateOptions): Promise<GenerateResult>;
+
+    /**
+     * Stream response tokens and optional tool calls. Call onChunk for each delta.
+     */
+    streamText?(messages: Message[], options?: StreamOptions): Promise<GenerateResult>;
+}