@clinebot/llms 0.0.0

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

@@ -0,0 +1,280 @@
+/**
+ * R1 Base Handler
+ *
+ * Handler for R1-based reasoning models (DeepSeek Reasoner, etc.)
+ * These models have special requirements:
+ * 1. Consecutive messages with the same role must be merged
+ * 2. reasoning_content field for tool calling continuations
+ * 3. No temperature parameter
+ * 4. Response includes reasoning_content in the delta
+ */
+
+import OpenAI from "openai";
+import type { ChatCompletionChunk } from "openai/resources/chat/completions";
+import { getOpenAIToolParams } from "../transform/openai-format";
+import { convertToR1Messages } from "../transform/r1-format";
+import type {
+	ApiStream,
+	ApiStreamChunk,
+	HandlerModelInfo,
+	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";
+
+/**
+ * Extended usage type for DeepSeek with cache tokens
+ */
+interface R1Usage extends OpenAI.CompletionUsage {
+	prompt_cache_hit_tokens?: number;
+	prompt_cache_miss_tokens?: number;
+}
+
+/**
+ * Base handler for R1-based reasoning models
+ *
+ * Uses ProviderConfig fields:
+ * - baseUrl: Base URL for the API
+ * - modelId: Model ID
+ * - knownModels: Known models with their info
+ * - headers: Custom headers
+ */
+export class R1BaseHandler extends BaseHandler {
+	protected client: OpenAI | undefined;
+
+	/**
+	 * Ensure the OpenAI client is initialized
+	 */
+	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: hasAuthorizationHeader
+					? requestHeaders
+					: { ...requestHeaders, Authorization: `Bearer ${apiKey}` },
+			});
+		}
+		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 {
+		return {
+			id: this.config.modelId,
+			capabilities: ["prompt-cache", "reasoning"],
+		};
+	}
+
+	/**
+	 * Check if this model is a reasoner model (no temperature allowed)
+	 */
+	protected isReasonerModel(modelId: string): boolean {
+		return modelId.includes("reasoner") || modelId.includes("r1");
+	}
+
+	getMessages(
+		systemPrompt: string,
+		messages: Message[],
+	): OpenAI.Chat.ChatCompletionMessageParam[] {
+		return [
+			{ role: "system", content: systemPrompt },
+			...convertToR1Messages(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 R1 format (handles merging and reasoning_content)
+		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),
+		};
+
+		// Add max tokens if configured
+		if (modelInfo.maxTokens) {
+			requestOptions.max_completion_tokens = modelInfo.maxTokens;
+		}
+
+		// Only set temperature for non-reasoner models
+		if (!this.isReasonerModel(modelId)) {
+			requestOptions.temperature = modelInfo.temperature ?? 0;
+		}
+
+		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
+	 */
+	protected *processChunk(
+		chunk: ChatCompletionChunk,
+		toolCallProcessor: ToolCallProcessor,
+		modelInfo: ModelInfo,
+		responseId: string,
+	): Generator<ApiStreamChunk> {
+		const delta = chunk.choices?.[0]?.delta;
+
+		// Handle text content
+		if (delta?.content) {
+			yield { type: "text", text: delta.content, id: responseId };
+		}
+
+		// Handle reasoning content (R1 specific)
+		if ((delta as any)?.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 with R1-specific cache tokens
+		if (chunk.usage) {
+			yield* this.processUsage(chunk.usage, modelInfo, responseId);
+		}
+	}
+
+	/**
+	 * Process usage information with R1-specific cache handling
+	 *
+	 * DeepSeek reports total input AND cache reads/writes,
+	 * where the input tokens is the sum of the cache hits/misses.
+	 */
+	protected *processUsage(
+		usage: OpenAI.CompletionUsage,
+		_modelInfo: ModelInfo,
+		responseId: string,
+	): Generator<ApiStreamChunk> {
+		const r1Usage = usage as R1Usage;
+
+		const inputTokens = r1Usage.prompt_tokens ?? 0; // sum of cache hits and misses
+		const outputTokens = r1Usage.completion_tokens ?? 0;
+		const cacheReadTokens = r1Usage.prompt_cache_hit_tokens ?? 0;
+		const cacheWriteTokens = r1Usage.prompt_cache_miss_tokens ?? 0;
+
+		// Calculate non-cached input tokens (will always be 0 for DeepSeek since input = read + write)
+		const nonCachedInputTokens = Math.max(
+			0,
+			inputTokens - cacheReadTokens - cacheWriteTokens,
+		);
+
+		yield {
+			type: "usage",
+			inputTokens: nonCachedInputTokens,
+			outputTokens,
+			cacheReadTokens,
+			cacheWriteTokens,
+			totalCost: this.calculateCost(inputTokens, outputTokens, cacheReadTokens),
+			id: responseId,
+		};
+	}
+}
+
+/**
+ * Create an R1-compatible handler
+ */
+export function createR1Handler(config: ProviderConfig): R1BaseHandler {
+	return new R1BaseHandler(config);
+}

package/src/providers/handlers/registry.ts

@@ -0,0 +1,185 @@
+/**
+ * Custom Handler Registry
+ *
+ * Allows users to register their own custom handlers that extend BaseHandler.
+ * This is useful for providers that require dependencies not included in this package
+ * (e.g., VSCode LM handler that requires the vscode package).
+ *
+ * @example
+ * ```typescript
+ * import { registerHandler, BaseHandler, type ProviderConfig, type ApiStream, type Message } from "@clinebot/providers"
+ * import * as vscode from "vscode"
+ *
+ * class VSCodeLmHandler extends BaseHandler {
+ *   async *createMessage(systemPrompt: string, messages: Message[]): ApiStream {
+ *     // Implementation using vscode.lm API
+ *   }
+ * }
+ *
+ * // Register the handler
+ * registerHandler("vscode-lm", (config) => new VSCodeLmHandler(config))
+ *
+ * // Now createHandler will use your custom handler for "vscode-lm"
+ * const handler = createHandler({ providerId: "vscode-lm", modelId: "copilot" })
+ * ```
+ */
+
+import type {
+	ApiHandler,
+	HandlerFactory,
+	LazyHandlerFactory,
+	ProviderConfig,
+} from "../types";
+
+/**
+ * Registry entry that can be either sync or async factory
+ */
+type RegistryEntry = {
+	factory: HandlerFactory<ProviderConfig> | LazyHandlerFactory<ProviderConfig>;
+	isAsync: boolean;
+};
+
+/**
+ * Internal registry of custom handlers
+ */
+const customHandlerRegistry = new Map<string, RegistryEntry>();
+
+/**
+ * Register a custom handler factory for a provider ID
+ *
+ * Use this to add handlers for providers that require external dependencies
+ * not bundled with this package, or to override built-in handlers.
+ *
+ * @param providerId - The provider ID to register (can be existing or new)
+ * @param factory - Factory function that creates the handler
+ *
+ * @example
+ * ```typescript
+ * // Simple registration
+ * registerHandler("my-provider", (config) => new MyHandler(config))
+ *
+ * // Override built-in handler
+ * registerHandler("anthropic", (config) => new MyCustomAnthropicHandler(config))
+ * ```
+ */
+export function registerHandler(
+	providerId: string,
+	factory: HandlerFactory<ProviderConfig>,
+): void {
+	customHandlerRegistry.set(providerId, { factory, isAsync: false });
+}
+
+/**
+ * Register an async handler factory for lazy loading
+ *
+ * Use this when your handler has heavy dependencies that should be
+ * loaded only when needed.
+ *
+ * @param providerId - The provider ID to register
+ * @param factory - Async factory function that creates the handler
+ *
+ * @example
+ * ```typescript
+ * registerAsyncHandler("heavy-provider", async (config) => {
+ *   const { HeavyHandler } = await import("./heavy-handler")
+ *   return new HeavyHandler(config)
+ * })
+ * ```
+ */
+export function registerAsyncHandler(
+	providerId: string,
+	factory: LazyHandlerFactory<ProviderConfig>,
+): void {
+	customHandlerRegistry.set(providerId, { factory, isAsync: true });
+}
+
+/**
+ * Unregister a custom handler
+ *
+ * @param providerId - The provider ID to unregister
+ * @returns true if a handler was removed, false if none existed
+ */
+export function unregisterHandler(providerId: string): boolean {
+	return customHandlerRegistry.delete(providerId);
+}
+
+/**
+ * Check if a custom handler is registered for a provider ID
+ *
+ * @param providerId - The provider ID to check
+ */
+export function hasRegisteredHandler(providerId: string): boolean {
+	return customHandlerRegistry.has(providerId);
+}
+
+/**
+ * Get a registered handler (internal use)
+ *
+ * @param providerId - The provider ID to get
+ * @param config - The config to pass to the factory
+ * @returns The handler instance, or undefined if not registered
+ */
+export function getRegisteredHandler(
+	providerId: string,
+	config: ProviderConfig,
+): ApiHandler | undefined {
+	const entry = customHandlerRegistry.get(providerId);
+	if (!entry) {
+		return undefined;
+	}
+
+	if (entry.isAsync) {
+		throw new Error(
+			`Handler for "${providerId}" is registered as async. Use getRegisteredHandlerAsync() or createHandlerAsync() instead.`,
+		);
+	}
+
+	return (entry.factory as HandlerFactory<ProviderConfig>)(config);
+}
+
+/**
+ * Get a registered handler asynchronously (internal use)
+ *
+ * @param providerId - The provider ID to get
+ * @param config - The config to pass to the factory
+ * @returns The handler instance, or undefined if not registered
+ */
+export async function getRegisteredHandlerAsync(
+	providerId: string,
+	config: ProviderConfig,
+): Promise<ApiHandler | undefined> {
+	const entry = customHandlerRegistry.get(providerId);
+	if (!entry) {
+		return undefined;
+	}
+
+	if (entry.isAsync) {
+		return (entry.factory as LazyHandlerFactory<ProviderConfig>)(config);
+	}
+
+	return (entry.factory as HandlerFactory<ProviderConfig>)(config);
+}
+
+/**
+ * Check if a registered handler is async
+ *
+ * @param providerId - The provider ID to check
+ */
+export function isRegisteredHandlerAsync(providerId: string): boolean {
+	const entry = customHandlerRegistry.get(providerId);
+	return entry?.isAsync ?? false;
+}
+
+/**
+ * Get all registered provider IDs
+ */
+export function getRegisteredProviderIds(): string[] {
+	return Array.from(customHandlerRegistry.keys());
+}
+
+/**
+ * Clear all registered handlers (mainly for testing)
+ */
+export function clearRegistry(): void {
+	customHandlerRegistry.clear();
+}

package/src/providers/handlers/vertex.test.ts

@@ -0,0 +1,124 @@
+import { beforeEach, describe, expect, it, vi } from "vitest";
+import type { Message } from "../types/messages";
+
+const geminiConstructorSpy = vi.fn();
+const geminiGetMessagesSpy = vi.fn();
+const geminiCreateMessageSpy = vi.fn();
+
+vi.mock("./gemini-base", () => {
+	return {
+		GeminiHandler: class {
+			constructor(config: unknown) {
+				geminiConstructorSpy(config);
+			}
+
+			getMessages(systemPrompt: string, messages: Message[]) {
+				return geminiGetMessagesSpy(systemPrompt, messages);
+			}
+
+			createMessage(
+				systemPrompt: string,
+				messages: Message[],
+				tools?: unknown[],
+			) {
+				return geminiCreateMessageSpy(systemPrompt, messages, tools);
+			}
+
+			getModel() {
+				return {
+					id: "gemini-2.5-pro",
+					info: {
+						id: "gemini-2.5-pro",
+						name: "Gemini 2.5 Pro",
+						contextWindow: 1,
+						maxTokens: 1,
+					},
+				};
+			}
+		},
+	};
+});
+
+import { VertexHandler } from "./vertex";
+
+describe("VertexHandler", () => {
+	beforeEach(() => {
+		vi.clearAllMocks();
+	});
+
+	it("routes Gemini models through GeminiHandler with Vertex config defaults", () => {
+		geminiGetMessagesSpy.mockReturnValue([
+			{ role: "user", parts: [{ text: "ok" }] },
+		]);
+
+		const handler = new VertexHandler({
+			providerId: "vertex",
+			modelId: "gemini-2.5-pro",
+			gcp: { projectId: "my-project" },
+		});
+
+		const messages: Message[] = [{ role: "user", content: "Hello" }];
+		const converted = handler.getMessages("You are helpful.", messages);
+
+		expect(geminiConstructorSpy).toHaveBeenCalledTimes(1);
+		expect(geminiConstructorSpy).toHaveBeenCalledWith(
+			expect.objectContaining({
+				region: "us-central1",
+				gcp: expect.objectContaining({
+					projectId: "my-project",
+					region: "us-central1",
+				}),
+			}),
+		);
+		expect(geminiGetMessagesSpy).toHaveBeenCalledWith(
+			"You are helpful.",
+			messages,
+		);
+		expect(converted).toEqual([{ role: "user", parts: [{ text: "ok" }] }]);
+	});
+
+	it("uses Anthropic-style message conversion for Claude models", () => {
+		const handler = new VertexHandler({
+			providerId: "vertex",
+			modelId: "claude-sonnet-4-5",
+			gcp: { projectId: "my-project", region: "us-east5" },
+		});
+
+		const converted = handler.getMessages("System", [
+			{ role: "user", content: "Hello Claude" },
+		]);
+
+		expect(geminiGetMessagesSpy).not.toHaveBeenCalled();
+		expect(converted).toEqual([
+			{
+				role: "user",
+				content: [{ type: "text", text: "Hello Claude" }],
+			},
+		]);
+	});
+
+	it("requires gcp.projectId for Vertex provider", async () => {
+		const handler = new VertexHandler({
+			providerId: "vertex",
+			modelId: "gemini-2.5-pro",
+		});
+
+		const stream = handler.createMessage("System", [
+			{ role: "user", content: "Hello" },
+		]);
+		await expect(stream.next()).rejects.toThrow("gcp.projectId");
+	});
+
+	it("requires region for Claude models on Vertex", async () => {
+		const handler = new VertexHandler({
+			providerId: "vertex",
+			modelId: "claude-sonnet-4-5",
+			gcp: { projectId: "my-project" },
+		});
+
+		const stream = handler.createMessage("System", [
+			{ role: "user", content: "Hello" },
+		]);
+		await expect(stream.next()).rejects.toThrow("gcp.region");
+	});
+});