@sschepis/robodev 1.0.0

package/src/core/ai-provider.mjs

@@ -0,0 +1,579 @@
+// AI Provider abstraction layer
+// Handles provider detection, endpoint configuration, and request/response translation
+// Supports: OpenAI, Google Gemini (via @google/genai SDK), and local (LMStudio, Ollama, etc.)
+
+import { config } from '../config.mjs';
+
+/**
+ * Supported AI providers
+ */
+export const AI_PROVIDERS = {
+    LOCAL: 'local',
+    OPENAI: 'openai',
+    GEMINI: 'gemini',
+};
+
+/**
+ * Default endpoints for each provider
+ */
+const PROVIDER_ENDPOINTS = {
+    [AI_PROVIDERS.LOCAL]: 'http://localhost:1234/v1/chat/completions',
+    [AI_PROVIDERS.OPENAI]: 'https://api.openai.com/v1/chat/completions',
+    // Gemini uses SDK, not REST endpoint — this is only a fallback
+    [AI_PROVIDERS.GEMINI]: null,
+};
+
+// Lazy-loaded Gemini SDK instance
+let _geminiAI = null;
+
+/**
+ * Get or create the Gemini SDK client
+ * @returns {Object} GoogleGenAI instance
+ */
+async function getGeminiClient() {
+    if (_geminiAI) return _geminiAI;
+
+    const { GoogleGenAI } = await import('@google/genai');
+    _geminiAI = new GoogleGenAI({ apiKey: config.keys.google });
+    return _geminiAI;
+}
+
+/**
+ * Detect the AI provider from the model name
+ * @param {string} model - The model identifier
+ * @returns {string} The detected provider key
+ */
+export function detectProvider(model) {
+    // Explicit provider override takes priority
+    const explicitProvider = config.ai.provider;
+    if (explicitProvider && Object.values(AI_PROVIDERS).includes(explicitProvider)) {
+        return explicitProvider;
+    }
+
+    if (!model) return AI_PROVIDERS.LOCAL;
+
+    const m = model.toLowerCase();
+
+    // Google Gemini models
+    if (m.startsWith('gemini-') || m.startsWith('models/gemini-')) {
+        return AI_PROVIDERS.GEMINI;
+    }
+
+    // OpenAI models
+    if (m.startsWith('gpt-') || m.startsWith('o1') || m.startsWith('o3') || m.startsWith('o4')) {
+        return AI_PROVIDERS.OPENAI;
+    }
+
+    // Default: local server (LMStudio, Ollama, etc.)
+    return AI_PROVIDERS.LOCAL;
+}
+
+/**
+ * Get the appropriate endpoint URL for a provider
+ * @param {string} provider - The provider key
+ * @returns {string|null} The endpoint URL (null for SDK-based providers)
+ */
+export function getEndpoint(provider) {
+    // If user has explicitly set an endpoint, always use it
+    const configuredEndpoint = config.ai.endpoint;
+    if (configuredEndpoint && configuredEndpoint !== 'http://localhost:1234/v1/chat/completions') {
+        return configuredEndpoint;
+    }
+
+    return PROVIDER_ENDPOINTS[provider] || PROVIDER_ENDPOINTS[AI_PROVIDERS.LOCAL];
+}
+
+/**
+ * Get the appropriate authorization headers for a provider (REST-based only)
+ * @param {string} provider - The provider key
+ * @returns {Object} Headers object
+ */
+export function getAuthHeaders(provider) {
+    switch (provider) {
+        case AI_PROVIDERS.OPENAI:
+            if (config.keys.openai) {
+                return { 'Authorization': `Bearer ${config.keys.openai}` };
+            }
+            return {};
+
+        case AI_PROVIDERS.LOCAL:
+        default:
+            // Local servers may still use an API key for compatibility
+            if (config.keys.openai) {
+                return { 'Authorization': `Bearer ${config.keys.openai}` };
+            }
+            return {};
+    }
+}
+
+// ─── OpenAI ↔ Gemini Format Translation ──────────────────────────────────
+
+/**
+ * Convert OpenAI-format tools to Gemini functionDeclarations
+ * OpenAI: [{type: "function", function: {name, description, parameters}}]
+ * Gemini: [{functionDeclarations: [{name, description, parameters}]}]
+ */
+function openaiToolsToGemini(tools) {
+    if (!tools || tools.length === 0) return undefined;
+
+    const declarations = tools
+        .filter(t => t.type === 'function' && t.function)
+        .map(t => {
+            const decl = {
+                name: t.function.name,
+                description: t.function.description || '',
+                parameters: sanitizeSchemaForGemini(t.function.parameters),
+            };
+            return decl;
+        });
+
+    return [{ functionDeclarations: declarations }];
+}
+
+/**
+ * Sanitize a JSON Schema to be compatible with Gemini's expectations.
+ * Gemini does not support some JSON Schema constructs that OpenAI does.
+ */
+function sanitizeSchemaForGemini(schema) {
+    if (!schema) return undefined;
+
+    const clean = { ...schema };
+
+    // Remove unsupported keywords
+    delete clean.default;
+    delete clean.minimum;
+    delete clean.maximum;
+    delete clean.$schema;
+
+    // Gemini expects `required` only as an array of property names at the object level.
+    // Remove boolean `required` values on individual properties (OpenAI allows this).
+    // Also remove empty required arrays — Gemini may reject these.
+    if (typeof clean.required === 'boolean') {
+        delete clean.required;
+    } else if (Array.isArray(clean.required) && clean.required.length === 0) {
+        delete clean.required;
+    }
+
+    // Gemini doesn't support "any" type — convert to "string"
+    if (clean.type === 'any') {
+        clean.type = 'string';
+    }
+
+    // Recursively clean nested properties
+    if (clean.properties) {
+        const cleanProps = {};
+        for (const [key, value] of Object.entries(clean.properties)) {
+            cleanProps[key] = sanitizeSchemaForGemini(value);
+        }
+        clean.properties = cleanProps;
+    }
+
+    // Clean array items
+    if (clean.items) {
+        clean.items = sanitizeSchemaForGemini(clean.items);
+    }
+
+    return clean;
+}
+
+/**
+ * Convert OpenAI-format messages to Gemini contents + systemInstruction
+ * OpenAI: [{role: "system"|"user"|"assistant"|"tool", content, tool_calls, tool_call_id, name}]
+ * Gemini: {systemInstruction, contents: [{role: "user"|"model", parts: [...]}]}
+ */
+function openaiMessagesToGemini(messages) {
+    let systemInstruction = undefined;
+    const contents = [];
+
+    for (const msg of messages) {
+        if (msg.role === 'system') {
+            // Extract system instruction (use the last one if multiple)
+            systemInstruction = msg.content;
+            continue;
+        }
+
+        if (msg.role === 'user') {
+            contents.push({
+                role: 'user',
+                parts: [{ text: msg.content }],
+            });
+            continue;
+        }
+
+        if (msg.role === 'assistant') {
+            // If we have preserved Gemini parts (from a previous round-trip),
+            // use them directly to preserve thought/thoughtSignature fields
+            if (msg._geminiParts && Array.isArray(msg._geminiParts)) {
+                contents.push({ role: 'model', parts: msg._geminiParts });
+                continue;
+            }
+
+            const parts = [];
+
+            // Text content
+            if (msg.content) {
+                parts.push({ text: msg.content });
+            }
+
+            // Tool calls → functionCall parts (with optional thoughtSignature)
+            if (msg.tool_calls && msg.tool_calls.length > 0) {
+                for (const tc of msg.tool_calls) {
+                    let args;
+                    try {
+                        args = typeof tc.function.arguments === 'string'
+                            ? JSON.parse(tc.function.arguments)
+                            : tc.function.arguments;
+                    } catch {
+                        args = {};
+                    }
+                    const fcPart = {
+                        functionCall: {
+                            name: tc.function.name,
+                            args: args,
+                        },
+                    };
+                    // Preserve thoughtSignature if stored from prior Gemini response
+                    if (tc._thoughtSignature) {
+                        fcPart.thoughtSignature = tc._thoughtSignature;
+                    }
+                    parts.push(fcPart);
+                }
+            }
+
+            if (parts.length > 0) {
+                contents.push({ role: 'model', parts });
+            }
+            continue;
+        }
+
+        if (msg.role === 'tool') {
+            // Tool result → functionResponse part
+            let responseObj;
+            try {
+                responseObj = typeof msg.content === 'string'
+                    ? { result: msg.content }
+                    : msg.content;
+            } catch {
+                responseObj = { result: String(msg.content) };
+            }
+
+            contents.push({
+                role: 'user',
+                parts: [{
+                    functionResponse: {
+                        name: msg.name || 'unknown_tool',
+                        response: responseObj,
+                    },
+                }],
+            });
+            continue;
+        }
+    }
+
+    return { systemInstruction, contents };
+}
+
+/**
+ * Convert a Gemini generateContent response to OpenAI-compatible format
+ * so the rest of the app can process it uniformly.
+ *
+ * IMPORTANT: For thinking models (gemini-3-*), the response may include
+ * `thought` and `thoughtSignature` fields in parts. These MUST be preserved
+ * and sent back in subsequent turns for function calling to work.
+ * We store them as `_geminiParts` on the message object.
+ */
+function geminiResponseToOpenai(geminiResponse) {
+    const candidate = geminiResponse.candidates?.[0];
+    if (!candidate) {
+        return { choices: [] };
+    }
+
+    const parts = candidate.content?.parts || [];
+    const message = { role: 'assistant' };
+
+    // Collect text parts (exclude thought parts from visible content)
+    const textParts = parts.filter(p => p.text && !p.thought).map(p => p.text);
+    if (textParts.length > 0) {
+        message.content = textParts.join('');
+    } else {
+        message.content = null;
+    }
+
+    // Collect function calls — preserve thoughtSignature for thinking models
+    const functionCalls = parts.filter(p => p.functionCall);
+    if (functionCalls.length > 0) {
+        message.tool_calls = functionCalls.map((p, i) => ({
+            id: `call_gemini_${Date.now()}_${i}`,
+            type: 'function',
+            function: {
+                name: p.functionCall.name,
+                arguments: JSON.stringify(p.functionCall.args || {}),
+            },
+            // Preserve Gemini-specific fields for round-tripping
+            _thoughtSignature: p.thoughtSignature || undefined,
+        }));
+    }
+
+    // Preserve the FULL original parts array for faithful reconstruction
+    // This ensures thought parts and thoughtSignatures survive the round-trip
+    message._geminiParts = parts;
+
+    return {
+        choices: [{
+            index: 0,
+            message,
+            finish_reason: candidate.finishReason || 'stop',
+        }],
+        usage: geminiResponse.usageMetadata ? {
+            prompt_tokens: geminiResponse.usageMetadata.promptTokenCount || 0,
+            completion_tokens: geminiResponse.usageMetadata.candidatesTokenCount || 0,
+            total_tokens: geminiResponse.usageMetadata.totalTokenCount || 0,
+        } : undefined,
+    };
+}
+
+// ─── Provider Context ────────────────────────────────────────────────────
+
+/**
+ * Transform request body for provider-specific quirks (REST providers only)
+ * @param {string} provider - The provider key
+ * @param {Object} body - The OpenAI-compatible request body
+ * @returns {Object} The transformed request body
+ */
+export function transformRequestBody(provider, body) {
+    const transformed = { ...body };
+
+    switch (provider) {
+        case AI_PROVIDERS.OPENAI:
+            // OpenAI doesn't support reasoning_effort for most models
+            // Keep it for models that might support it (o1, etc.)
+            break;
+
+        case AI_PROVIDERS.LOCAL:
+        default:
+            // Local servers (LMStudio) typically support all OpenAI params
+            break;
+    }
+
+    return transformed;
+}
+
+/**
+ * Create a fully configured provider context for making API calls
+ * @param {string} [model] - Optional model override; defaults to config.ai.model
+ * @returns {{ provider: string, endpoint: string|null, headers: Object, model: string }}
+ */
+export function createProviderContext(model) {
+    const activeModel = model || config.ai.model;
+    const provider = detectProvider(activeModel);
+    const endpoint = getEndpoint(provider);
+    const authHeaders = provider !== AI_PROVIDERS.GEMINI ? getAuthHeaders(provider) : {};
+
+    return {
+        provider,
+        endpoint,
+        headers: {
+            'Content-Type': 'application/json',
+            ...authHeaders,
+        },
+        model: activeModel,
+    };
+}
+
+// ─── Unified API Call Functions ──────────────────────────────────────────
+
+/**
+ * Make an API call using the provider abstraction.
+ * For Gemini: uses @google/genai SDK with format translation
+ * For OpenAI/Local: uses REST fetch with OpenAI-compatible format
+ *
+ * @param {Object} requestBody - OpenAI-compatible request body (model, messages, tools, etc.)
+ * @param {Object} [options] - Optional overrides
+ * @param {string} [options.model] - Model override
+ * @returns {Promise<Object>} OpenAI-compatible parsed JSON response
+ */
+export async function callProvider(requestBody, options = {}) {
+    const ctx = createProviderContext(options.model || requestBody.model);
+
+    // ── Gemini: use native SDK ──
+    if (ctx.provider === AI_PROVIDERS.GEMINI) {
+        return await callGeminiSDK(ctx, requestBody);
+    }
+
+    // ── OpenAI / Local: use REST fetch ──
+    return await callOpenAIREST(ctx, requestBody);
+}
+
+/**
+ * Make a streaming API call using the provider abstraction.
+ * For Gemini: falls back to non-streaming (SDK stream support can be added later)
+ * For OpenAI/Local: uses REST SSE streaming
+ *
+ * @param {Object} requestBody - OpenAI-compatible request body
+ * @param {Object} [options] - Optional overrides
+ * @returns {Promise<Response>} Raw fetch Response for streaming (or synthetic for Gemini)
+ */
+export async function callProviderStream(requestBody, options = {}) {
+    const ctx = createProviderContext(options.model || requestBody.model);
+
+    // ── Gemini: use SDK (non-streaming, wrapped as synthetic stream) ──
+    if (ctx.provider === AI_PROVIDERS.GEMINI) {
+        return await callGeminiSDKStream(ctx, requestBody);
+    }
+
+    // ── OpenAI / Local: use REST SSE ──
+    const body = transformRequestBody(ctx.provider, { ...requestBody, stream: true });
+
+    const response = await fetch(ctx.endpoint, {
+        method: 'POST',
+        headers: ctx.headers,
+        body: JSON.stringify(body),
+    });
+
+    if (!response.ok) {
+        const providerLabel = ctx.provider === AI_PROVIDERS.LOCAL
+            ? 'Local AI server (is LMStudio running?)'
+            : `${ctx.provider} API`;
+        throw new Error(`${providerLabel} Error: ${response.status} - ${response.statusText}`);
+    }
+
+    return response;
+}
+
+// ─── Gemini SDK Calls ────────────────────────────────────────────────────
+
+/**
+ * Call Gemini using the @google/genai SDK
+ */
+async function callGeminiSDK(ctx, requestBody) {
+    const ai = await getGeminiClient();
+    const { systemInstruction, contents } = openaiMessagesToGemini(requestBody.messages);
+    const geminiTools = openaiToolsToGemini(requestBody.tools);
+
+    const generateConfig = {};
+    if (requestBody.temperature !== undefined) {
+        generateConfig.temperature = requestBody.temperature;
+    }
+    if (requestBody.max_tokens) {
+        generateConfig.maxOutputTokens = requestBody.max_tokens;
+    }
+
+    // Build tool config for auto tool choice
+    if (geminiTools) {
+        generateConfig.tools = geminiTools;
+    }
+
+    if (systemInstruction) {
+        generateConfig.systemInstruction = systemInstruction;
+    }
+
+    const geminiResponse = await ai.models.generateContent({
+        model: ctx.model,
+        contents: contents,
+        config: generateConfig,
+    });
+
+    // Translate response to OpenAI format
+    return geminiResponseToOpenai(geminiResponse);
+}
+
+/**
+ * Call Gemini streaming using the @google/genai SDK.
+ * Returns a synthetic Response object that mimics SSE streaming.
+ */
+async function callGeminiSDKStream(ctx, requestBody) {
+    const ai = await getGeminiClient();
+    const { systemInstruction, contents } = openaiMessagesToGemini(requestBody.messages);
+    const geminiTools = openaiToolsToGemini(requestBody.tools);
+
+    const generateConfig = {};
+    if (requestBody.temperature !== undefined) {
+        generateConfig.temperature = requestBody.temperature;
+    }
+    if (geminiTools) {
+        generateConfig.tools = geminiTools;
+    }
+    if (systemInstruction) {
+        generateConfig.systemInstruction = systemInstruction;
+    }
+
+    // Use generateContentStream for real streaming
+    const streamResult = await ai.models.generateContentStream({
+        model: ctx.model,
+        contents: contents,
+        config: generateConfig,
+    });
+
+    // Create a ReadableStream that wraps the Gemini async iterator
+    const stream = new ReadableStream({
+        async start(controller) {
+            const encoder = new TextEncoder();
+            try {
+                for await (const chunk of streamResult) {
+                    const text = chunk.text || '';
+                    if (text) {
+                        // Emit SSE-formatted data matching OpenAI streaming format
+                        const sseData = JSON.stringify({
+                            choices: [{
+                                delta: { content: text },
+                                index: 0,
+                            }],
+                        });
+                        controller.enqueue(encoder.encode(`data: ${sseData}\n\n`));
+                    }
+                }
+                controller.enqueue(encoder.encode('data: [DONE]\n\n'));
+                controller.close();
+            } catch (err) {
+                controller.error(err);
+            }
+        },
+    });
+
+    // Return a synthetic Response object
+    return new Response(stream, {
+        status: 200,
+        headers: { 'Content-Type': 'text/event-stream' },
+    });
+}
+
+// ─── OpenAI/Local REST Calls ─────────────────────────────────────────────
+
+/**
+ * Call OpenAI or local server using REST
+ */
+async function callOpenAIREST(ctx, requestBody) {
+    const body = transformRequestBody(ctx.provider, requestBody);
+
+    const response = await fetch(ctx.endpoint, {
+        method: 'POST',
+        headers: ctx.headers,
+        body: JSON.stringify(body),
+    });
+
+    if (!response.ok) {
+        const providerLabel = ctx.provider === AI_PROVIDERS.LOCAL
+            ? 'Local AI server (is LMStudio running?)'
+            : `${ctx.provider} API`;
+        throw new Error(`${providerLabel} Error: ${response.status} - ${response.statusText}`);
+    }
+
+    return response.json();
+}
+
+// ─── Utility Functions ───────────────────────────────────────────────────
+
+/**
+ * Get a human-readable label for the current provider setup
+ * @param {string} [model] - Optional model override
+ * @returns {string} Description like "Gemini (gemini-2.0-flash)"
+ */
+export function getProviderLabel(model) {
+    const ctx = createProviderContext(model);
+    const labels = {
+        [AI_PROVIDERS.LOCAL]: 'Local',
+        [AI_PROVIDERS.OPENAI]: 'OpenAI',
+        [AI_PROVIDERS.GEMINI]: 'Gemini',
+    };
+    return `${labels[ctx.provider] || ctx.provider} (${ctx.model})`;
+}