@clinebot/llms 0.0.0

package/src/providers/handlers/gemini-base.ts

@@ -0,0 +1,302 @@
+/**
+ * Gemini Base Handler
+ *
+ * Handler for Google's Gemini API using the official SDK.
+ * Supports Vertex AI, thinking/reasoning, and native tool calling.
+ */
+
+import {
+	FunctionCallingConfigMode,
+	type GenerateContentConfig,
+	GoogleGenAI,
+	ThinkingLevel,
+} from "@google/genai";
+import {
+	convertToGeminiMessages,
+	convertToolsToGemini,
+} from "../transform/gemini-format";
+import {
+	type ApiStream,
+	type HandlerModelInfo,
+	type ModelInfo,
+	type ProviderConfig,
+	supportsModelThinking,
+} from "../types";
+import type { Message, ToolDefinition } from "../types/messages";
+import { RetriableError, retryStream } from "../utils/retry";
+import { BaseHandler } from "./base";
+
+const DEFAULT_THINKING_BUDGET_TOKENS = 1024;
+
+/**
+ * Handler for Google's Gemini API
+ */
+export class GeminiHandler extends BaseHandler {
+	private client: GoogleGenAI | undefined;
+
+	private ensureClient(): GoogleGenAI {
+		if (!this.client) {
+			// Check for Vertex AI configuration
+			if (this.config.gcp?.projectId) {
+				this.client = new GoogleGenAI({
+					vertexai: true,
+					project: this.config.gcp.projectId,
+					location: this.config.region ?? "us-central1",
+					httpOptions: {
+						headers: this.getRequestHeaders(),
+					},
+				});
+			} else {
+				// Standard API key auth
+				if (!this.config.apiKey) {
+					throw new Error(
+						"Gemini API key is required when not using Vertex AI",
+					);
+				}
+
+				this.client = new GoogleGenAI({
+					apiKey: this.config.apiKey,
+					httpOptions: {
+						headers: this.getRequestHeaders(),
+					},
+				});
+			}
+		}
+		return this.client;
+	}
+
+	getModel(): HandlerModelInfo {
+		const modelId = this.config.modelId;
+		const knownModels = this.config.knownModels ?? {};
+		const fallbackModel = knownModels[modelId] ?? {};
+		const modelInfo = this.config.modelInfo ?? fallbackModel;
+
+		return { id: modelId, info: { ...modelInfo, id: modelId } };
+	}
+
+	getMessages(_systemPrompt: string, messages: Message[]) {
+		return convertToGeminiMessages(messages);
+	}
+
+	async *createMessage(
+		systemPrompt: string,
+		messages: Message[],
+		tools?: ToolDefinition[],
+	): ApiStream {
+		yield* retryStream(
+			() => this.createMessageInternal(systemPrompt, messages, tools),
+			{ maxRetries: 4, baseDelay: 2000, maxDelay: 15000 },
+		);
+	}
+
+	private async *createMessageInternal(
+		systemPrompt: string,
+		messages: Message[],
+		tools?: ToolDefinition[],
+	): ApiStream {
+		const client = this.ensureClient();
+		const { id: modelId, info } = this.getModel();
+		const abortSignal = this.getAbortSignal();
+		const responseId = this.createResponseId();
+
+		// Convert messages
+		const contents = this.getMessages(systemPrompt, messages);
+
+		const thinkingSupported = supportsModelThinking(info);
+		const thinkingRequested =
+			this.config.thinking === true ||
+			typeof this.config.thinkingBudgetTokens === "number" ||
+			typeof this.config.reasoningEffort === "string";
+		let thinkingBudget = 0;
+		let thinkingLevel: ThinkingLevel | undefined;
+
+		if (thinkingSupported && thinkingRequested) {
+			const requestedBudget =
+				this.config.thinkingBudgetTokens ??
+				(this.config.thinking ? DEFAULT_THINKING_BUDGET_TOKENS : 0);
+			thinkingBudget = Math.min(
+				Math.max(0, requestedBudget),
+				info.thinkingConfig?.maxBudget ?? 24576,
+			);
+
+			// If thinkingConfig has a thinkingLevel, it supports thinking level control
+			if (info.thinkingConfig?.thinkingLevel) {
+				const level = this.config.reasoningEffort;
+				if (level === "high") {
+					thinkingLevel = ThinkingLevel.HIGH;
+				} else if (level === "low" || level === "medium") {
+					thinkingLevel = ThinkingLevel.LOW;
+				}
+			}
+		}
+
+		// Build request config with abort signal
+		const requestConfig: GenerateContentConfig = {
+			httpOptions: this.config.baseUrl
+				? { baseUrl: this.config.baseUrl, headers: this.getRequestHeaders() }
+				: undefined,
+			abortSignal,
+			systemInstruction: systemPrompt,
+			temperature: info.temperature ?? 1,
+		};
+
+		// Add thinking config only when explicitly requested and supported.
+		if (
+			info.thinkingConfig &&
+			thinkingSupported &&
+			thinkingRequested &&
+			(thinkingBudget > 0 || !!thinkingLevel)
+		) {
+			requestConfig.thinkingConfig = {
+				thinkingBudget: thinkingLevel ? undefined : thinkingBudget,
+				thinkingLevel,
+				includeThoughts: true,
+			};
+		}
+
+		// Add tools if provided
+		if (tools && tools.length > 0) {
+			const functionDeclarations = convertToolsToGemini(tools);
+			requestConfig.tools = [{ functionDeclarations }];
+			requestConfig.toolConfig = {
+				functionCallingConfig: {
+					mode: FunctionCallingConfigMode.AUTO,
+				},
+			};
+		}
+
+		try {
+			const result = await client.models.generateContentStream({
+				model: modelId,
+				contents,
+				config: requestConfig,
+			});
+
+			let promptTokens = 0;
+			let outputTokens = 0;
+			let cacheReadTokens = 0;
+			let thoughtsTokenCount = 0;
+
+			for await (const chunk of result) {
+				// Handle content parts
+				const parts = chunk?.candidates?.[0]?.content?.parts ?? [];
+
+				for (const part of parts) {
+					if ((part as any).thought && part.text) {
+						// Thinking content
+						yield {
+							type: "reasoning",
+							reasoning: part.text || "",
+							signature: (part as any).thoughtSignature,
+							id: responseId,
+						};
+					} else if (part.text) {
+						// Regular text
+						yield {
+							type: "text",
+							text: part.text,
+							id: responseId,
+							signature: (part as any).thoughtSignature,
+						};
+					}
+
+					if (part.functionCall) {
+						// Tool call
+						const functionCall = part.functionCall;
+						const args = Object.entries(functionCall.args ?? {}).filter(
+							([, val]) => !!val,
+						);
+
+						if (args.length > 0) {
+							yield {
+								type: "tool_calls",
+								tool_call: {
+									function: {
+										id: responseId,
+										name: functionCall.name,
+										arguments: functionCall.args as Record<string, unknown>,
+									},
+								},
+								id: responseId,
+								signature: (part as any).thoughtSignature,
+							};
+						}
+					}
+				}
+
+				// Track usage
+				if (chunk.usageMetadata) {
+					promptTokens = chunk.usageMetadata.promptTokenCount ?? promptTokens;
+					outputTokens =
+						chunk.usageMetadata.candidatesTokenCount ?? outputTokens;
+					thoughtsTokenCount =
+						(chunk.usageMetadata as any).thoughtsTokenCount ??
+						thoughtsTokenCount;
+					cacheReadTokens =
+						(chunk.usageMetadata as any).cachedContentTokenCount ??
+						cacheReadTokens;
+				}
+			}
+
+			// Yield final usage
+			const totalCost = this.calculateGeminiCost(
+				info,
+				promptTokens,
+				outputTokens,
+				thoughtsTokenCount,
+				cacheReadTokens,
+			);
+
+			yield {
+				type: "usage",
+				inputTokens: promptTokens - cacheReadTokens,
+				outputTokens,
+				thoughtsTokenCount,
+				cacheReadTokens,
+				cacheWriteTokens: 0,
+				totalCost,
+				id: responseId,
+			};
+
+			// Yield done chunk to indicate streaming completed successfully
+			yield { type: "done", success: true, id: responseId };
+		} catch (error) {
+			// Handle rate limit errors with retry info
+			if (error instanceof Error && error.message.includes("429")) {
+				throw new RetriableError(error.message, undefined, { cause: error });
+			}
+			throw error;
+		}
+	}
+
+	private calculateGeminiCost(
+		info: ModelInfo,
+		inputTokens: number,
+		outputTokens: number,
+		thoughtsTokenCount: number,
+		cacheReadTokens: number,
+	): number | undefined {
+		const pricing = info.pricing;
+		if (!pricing?.input || !pricing?.output) {
+			return undefined;
+		}
+
+		const uncachedInputTokens = inputTokens - cacheReadTokens;
+		const inputCost = pricing.input * (uncachedInputTokens / 1_000_000);
+		const outputCost =
+			pricing.output * ((outputTokens + thoughtsTokenCount) / 1_000_000);
+		const cacheReadCost =
+			cacheReadTokens > 0
+				? (pricing.cacheRead ?? 0) * (cacheReadTokens / 1_000_000)
+				: 0;
+
+		return inputCost + outputCost + cacheReadCost;
+	}
+}
+
+/**
+ * Create a Gemini handler
+ */
+export function createGeminiHandler(config: ProviderConfig): GeminiHandler {
+	return new GeminiHandler(config);
+}

package/src/providers/handlers/index.ts

@@ -0,0 +1,67 @@
+/**
+ * Handlers Index
+ *
+ * Re-exports all handler classes and factory functions.
+ */
+
+export { AnthropicHandler, createAnthropicHandler } from "./anthropic-base";
+export { AskSageHandler, createAskSageHandler } from "./asksage";
+export {
+	getMissingApiKeyError,
+	getProviderEnvKeys,
+	normalizeProviderId,
+	resolveApiKeyForProvider,
+} from "./auth";
+// Base classes
+export { BaseHandler } from "./base";
+export { BedrockHandler, createBedrockHandler } from "./bedrock-base";
+export {
+	ClaudeCodeHandler,
+	CodexHandler,
+	createClaudeCodeHandler,
+	createCodexHandler,
+	createDifyHandler,
+	createMistralHandler,
+	createOpenCodeHandler,
+	createSapAiCoreHandler,
+	DifyHandler,
+	MistralHandler,
+	OpenCodeHandler,
+	SapAiCoreHandler,
+} from "./community-sdk";
+export { FetchBaseHandler } from "./fetch-base";
+export { createGeminiHandler, GeminiHandler } from "./gemini-base";
+// OpenAI Chat Completions API handler
+export { createOpenAIHandler, OpenAIBaseHandler } from "./openai-base";
+// OpenAI Responses API handler
+export {
+	createOpenAIResponsesHandler,
+	OpenAIResponsesHandler,
+} from "./openai-responses";
+// Provider configurations
+export {
+	clearLiveModelsCatalogCache,
+	clearPrivateModelsCatalogCache,
+	DEFAULT_MODELS_CATALOG_URL,
+	getLiveModelsCatalog,
+	getProviderConfig,
+	isOpenAICompatibleProvider,
+	OPENAI_COMPATIBLE_PROVIDERS,
+	type ProviderDefaults,
+	resolveProviderConfig,
+} from "./providers";
+// R1-based handlers (DeepSeek Reasoner, etc.)
+export { createR1Handler, R1BaseHandler } from "./r1-base";
+// Custom handler registry
+export {
+	clearRegistry,
+	getRegisteredHandler,
+	getRegisteredHandlerAsync,
+	getRegisteredProviderIds,
+	hasRegisteredHandler,
+	isRegisteredHandlerAsync,
+	registerAsyncHandler,
+	registerHandler,
+	unregisterHandler,
+} from "./registry";
+export { createVertexHandler, VertexHandler } from "./vertex";

package/src/providers/handlers/openai-base.ts

@@ -0,0 +1,277 @@
+/**
+ * OpenAI Base Handler
+ *
+ * Base class for all handlers using the OpenAI SDK.
+ * This handles the common streaming logic and can be extended for:
+ * - Standard OpenAI API
+ * - OpenAI-compatible providers (DeepSeek, xAI, Together, etc.)
+ * - OpenRouter
+ * - Azure OpenAI
+ */
+
+import OpenAI from "openai";
+import type { ChatCompletionChunk } from "openai/resources/chat/completions";
+import {
+	convertToOpenAIMessages,
+	getOpenAIToolParams,
+} from "../transform/openai-format";
+import type {
+	ApiStream,
+	HandlerModelInfo,
+	ModelCapability,
+	ModelInfo,
+	ProviderConfig,
+} from "../types";
+import type { Message, ToolDefinition } from "../types/messages";
+import { retryStream } from "../utils/retry";
+import { ToolCallProcessor } from "../utils/tool-processor";
+import { getMissingApiKeyError, resolveApiKeyForProvider } from "./auth";
+import { BaseHandler } from "./base";
+
+const DEFAULT_REASONING_EFFORT = "medium" as const;
+
+/**
+ * Base handler for OpenAI SDK-based providers
+ *
+ * Uses ProviderConfig fields:
+ * - baseUrl: Base URL for the API
+ * - modelId: Model ID
+ * - knownModels: Known models with their info
+ * - headers: Custom headers
+ * - capabilities: Array of supported capabilities (reasoning, prompt-cache, etc.)
+ */
+export class OpenAIBaseHandler extends BaseHandler {
+	protected client: OpenAI | undefined;
+
+	/**
+	 * Ensure the OpenAI client is initialized
+	 * Can be overridden for custom client creation (e.g., Azure)
+	 */
+	protected ensureClient(): OpenAI {
+		if (!this.client) {
+			const baseURL = this.config.baseUrl;
+
+			if (!baseURL) {
+				throw new Error("Base URL is required. Set baseUrl in config.");
+			}
+			const apiKey = resolveApiKeyForProvider(
+				this.config.providerId,
+				this.config.apiKey,
+			);
+			if (!apiKey) {
+				throw new Error(getMissingApiKeyError(this.config.providerId));
+			}
+			const requestHeaders = this.getRequestHeaders();
+			// const hasAuthorizationHeader = Object.keys(requestHeaders).some((key) => key.toLowerCase() === "authorization")
+
+			this.client = new OpenAI({
+				apiKey,
+				baseURL,
+				defaultHeaders: requestHeaders,
+			});
+		}
+		return this.client;
+	}
+
+	/**
+	 * Get model info, falling back to provider defaults
+	 */
+	getModel(): HandlerModelInfo {
+		const modelId = this.config.modelId;
+		if (!modelId) {
+			throw new Error("Model ID is required. Set modelId in config.");
+		}
+
+		const modelInfo =
+			this.config.modelInfo ??
+			this.config.knownModels?.[modelId] ??
+			this.getDefaultModelInfo();
+
+		return { id: modelId, info: { ...modelInfo, id: modelId } };
+	}
+
+	protected getDefaultModelInfo(): ModelInfo {
+		const capabilities: ModelCapability[] = this.config.capabilities?.includes(
+			"prompt-cache",
+		)
+			? ["prompt-cache"]
+			: [];
+		return {
+			id: this.config.modelId,
+			capabilities,
+		};
+	}
+
+	getMessages(
+		systemPrompt: string,
+		messages: Message[],
+	): OpenAI.Chat.ChatCompletionMessageParam[] {
+		return [
+			{ role: "system", content: systemPrompt },
+			...convertToOpenAIMessages(messages),
+		];
+	}
+
+	/**
+	 * Create a streaming message
+	 */
+	async *createMessage(
+		systemPrompt: string,
+		messages: Message[],
+		tools?: ToolDefinition[],
+	): ApiStream {
+		yield* retryStream(() =>
+			this.createMessageInternal(systemPrompt, messages, tools),
+		);
+	}
+
+	private async *createMessageInternal(
+		systemPrompt: string,
+		messages: Message[],
+		tools?: ToolDefinition[],
+	): ApiStream {
+		const client = this.ensureClient();
+		const { id: modelId, info: modelInfo } = this.getModel();
+		const responseId = this.createResponseId();
+
+		// Convert messages to OpenAI format
+		const openAiMessages = this.getMessages(systemPrompt, messages);
+
+		// Build request options
+		const requestOptions: OpenAI.ChatCompletionCreateParamsStreaming = {
+			model: modelId,
+			messages: openAiMessages,
+			stream: true,
+			stream_options: { include_usage: true },
+			...getOpenAIToolParams(tools, {
+				// OpenRouter can reject strict function schemas on some routed models.
+				strict: this.config.providerId !== "openrouter",
+			}),
+		};
+
+		// Add max tokens if configured
+		if (modelInfo.maxTokens) {
+			requestOptions.max_completion_tokens = modelInfo.maxTokens;
+		}
+
+		// Add temperature if not a reasoning model
+		const modelSupportsReasoning =
+			modelInfo.capabilities?.includes("reasoning") ?? false;
+		if (!modelSupportsReasoning) {
+			requestOptions.temperature = modelInfo.temperature ?? 0;
+		}
+
+		// Add reasoning effort for supported models
+		const supportsReasoningEffort =
+			modelInfo.capabilities?.includes("reasoning-effort") ||
+			modelInfo.capabilities?.includes("reasoning") ||
+			false;
+		const effectiveReasoningEffort =
+			this.config.reasoningEffort ??
+			(this.config.thinking ? DEFAULT_REASONING_EFFORT : undefined);
+		if (supportsReasoningEffort && effectiveReasoningEffort) {
+			(requestOptions as any).reasoning_effort = effectiveReasoningEffort;
+		}
+
+		const requestHeaders = this.getRequestHeaders();
+		const hasAuthorizationHeader = Object.keys(requestHeaders).some(
+			(key) => key.toLowerCase() === "authorization",
+		);
+		const apiKey = resolveApiKeyForProvider(
+			this.config.providerId,
+			this.config.apiKey,
+		);
+		if (!hasAuthorizationHeader && apiKey) {
+			requestHeaders.Authorization = `Bearer ${apiKey}`;
+		}
+		const abortSignal = this.getAbortSignal();
+		const stream = await client.chat.completions.create(requestOptions, {
+			signal: abortSignal,
+			headers: requestHeaders,
+		});
+		const toolCallProcessor = new ToolCallProcessor();
+
+		for await (const chunk of stream) {
+			yield* this.withResponseIdForAll(
+				this.processChunk(chunk, toolCallProcessor, modelInfo, responseId),
+				responseId,
+			);
+		}
+
+		// Yield done chunk to indicate streaming completed successfully
+		yield { type: "done", success: true, id: responseId };
+	}
+
+	/**
+	 * Process a single chunk from the stream
+	 * Can be overridden for provider-specific handling
+	 */
+	protected *processChunk(
+		chunk: ChatCompletionChunk,
+		toolCallProcessor: ToolCallProcessor,
+		_modelInfo: ModelInfo,
+		responseId: string,
+	): Generator<import("../types").ApiStreamChunk> {
+		const delta = chunk.choices?.[0]?.delta && {
+			...chunk.choices[0].delta,
+			reasoning_content: (chunk.choices[0].delta as any).reasoning_content,
+		};
+
+		// Handle text content
+		if (delta?.content) {
+			yield { type: "text", text: delta.content, id: responseId };
+		}
+
+		// Handle reasoning content (DeepSeek, xAI, etc.)
+		if (delta?.reasoning_content) {
+			yield {
+				type: "reasoning",
+				reasoning: (delta as any).reasoning_content,
+				id: responseId,
+			};
+		}
+
+		// Handle tool calls
+		if (delta?.tool_calls) {
+			yield* toolCallProcessor.processToolCallDeltas(
+				delta.tool_calls.map((tc) => ({
+					index: tc.index,
+					id: tc.id,
+					function: tc.function,
+				})),
+				responseId,
+			);
+		}
+
+		// Handle usage information
+		if (chunk.usage) {
+			const inputTokens = chunk.usage.prompt_tokens ?? 0;
+			const outputTokens = chunk.usage.completion_tokens ?? 0;
+			const cacheReadTokens =
+				(chunk.usage as any).prompt_tokens_details?.cached_tokens ?? 0;
+			const cacheWriteTokens =
+				(chunk.usage as any).prompt_cache_miss_tokens ?? 0;
+
+			yield {
+				type: "usage",
+				inputTokens,
+				outputTokens,
+				cacheReadTokens,
+				cacheWriteTokens,
+				totalCost: this.calculateCost(
+					inputTokens,
+					outputTokens,
+					cacheReadTokens,
+				),
+				id: responseId,
+			};
+		}
+	}
+}
+
+/**
+ * Create an OpenAI-compatible handler
+ */
+export function createOpenAIHandler(config: ProviderConfig): OpenAIBaseHandler {
+	return new OpenAIBaseHandler(config);
+}