@clinebot/llms 0.0.0

package/dist/providers/types/config.d.ts

@@ -0,0 +1,261 @@
+/**
+ * Provider Configuration Types
+ *
+ * Unified configuration interface for all providers.
+ * This replaces the per-provider config chaos with a single structure.
+ */
+import type { ModelInfo } from "./model-info";
+import { BUILT_IN_PROVIDER, BUILT_IN_PROVIDER_IDS, type BuiltInProviderId, isBuiltInProviderId, normalizeProviderId } from "./provider-ids";
+export { BUILT_IN_PROVIDER, BUILT_IN_PROVIDER_IDS, type BuiltInProviderId, isBuiltInProviderId, normalizeProviderId, };
+/**
+ * All supported provider IDs (built-in + custom)
+ *
+ * Custom provider IDs can be registered via `registerHandler()` or `registerAsyncHandler()`.
+ * Any string is accepted to allow for custom handlers that extend BaseHandler.
+ */
+export type ProviderId = BuiltInProviderId | (string & {});
+/**
+ * Provider categories based on underlying SDK/protocol
+ */
+export type ProviderCategory = "anthropic" | "openai" | "openai-compat" | "openai-responses" | "gemini" | "bedrock" | "custom";
+/**
+ * Capabilities that a provider/model may support
+ */
+export type ProviderCapability = "reasoning" | "prompt-cache" | "streaming" | "tools" | "vision" | "computer-use" | "oauth";
+/**
+ * Authentication configuration
+ */
+export interface AuthConfig {
+    /** API key (most common) */
+    apiKey?: string;
+    /** OAuth access token */
+    accessToken?: string;
+    /** Refresh token for OAuth */
+    refreshToken?: string;
+    /** Account ID (for account-based auth) */
+    accountId?: string;
+    /** OAuth callback path (e.g., for Qwen Code) */
+    oauthPath?: string;
+}
+/**
+ * Endpoint configuration
+ */
+export interface EndpointConfig {
+    /** Base URL for the API */
+    baseUrl?: string;
+    /** Custom headers to include */
+    headers?: Record<string, string>;
+    /** Request timeout in milliseconds */
+    timeoutMs?: number;
+}
+/**
+ * Model configuration
+ */
+export interface ModelConfig {
+    /** Model identifier */
+    modelId: string;
+    /** Pre-fetched model info (optional - will use defaults if not provided) */
+    modelInfo?: ModelInfo;
+    /** Known models for this provider with their info */
+    knownModels?: Record<string, ModelInfo>;
+}
+/**
+ * Token limits configuration
+ */
+export interface TokenConfig {
+    /** Maximum context window tokens (overrides model default) */
+    maxContextTokens?: number;
+    /** Maximum output tokens (overrides model default) */
+    maxOutputTokens?: number;
+}
+/**
+ * Reasoning/thinking model configuration
+ */
+export interface ReasoningConfig {
+    /** Reasoning effort level */
+    reasoningEffort?: "low" | "medium" | "high";
+    /** Extended thinking budget in tokens */
+    thinkingBudgetTokens?: number;
+    /** Enable thinking with provider/model defaults when supported */
+    thinking?: boolean;
+}
+/**
+ * Region configuration (shared across cloud providers)
+ */
+export interface RegionConfig {
+    /** Cloud region (AWS, GCP, Azure, or provider-specific like Qwen's china/international) */
+    region?: string;
+    /** API line for region-specific routing (e.g., "china" | "international" for Qwen) */
+    apiLine?: "china" | "international";
+    /** Use cross-region inference (Bedrock) */
+    useCrossRegionInference?: boolean;
+    /** Use global inference (Bedrock) */
+    useGlobalInference?: boolean;
+}
+/**
+ * AWS-specific configuration (for Bedrock)
+ */
+export interface AwsConfig {
+    accessKey?: string;
+    secretKey?: string;
+    sessionToken?: string;
+    authentication?: "iam" | "api-key" | "profile";
+    profile?: string;
+    usePromptCache?: boolean;
+    endpoint?: string;
+    customModelBaseId?: string;
+}
+/**
+ * Google Cloud configuration (for Vertex AI)
+ */
+export interface GcpConfig {
+    projectId?: string;
+    region?: string;
+}
+/**
+ * Azure configuration (for Azure OpenAI)
+ */
+export interface AzureConfig {
+    apiVersion?: string;
+    useIdentity?: boolean;
+}
+/**
+ * SAP AI Core configuration
+ */
+export interface SapConfig {
+    clientId?: string;
+    clientSecret?: string;
+    tokenUrl?: string;
+    resourceGroup?: string;
+    deploymentId?: string;
+    useOrchestrationMode?: boolean;
+    api?: "orchestration" | "foundation-models";
+    defaultSettings?: Record<string, unknown>;
+}
+/**
+ * OCA (Oracle Cloud AI) configuration
+ */
+export interface OcaConfig {
+    mode?: "internal" | "external";
+    usePromptCache?: boolean;
+}
+/**
+ * Codex CLI provider options
+ */
+export interface CodexConfig {
+    defaultSettings?: Record<string, unknown>;
+    modelSettings?: Record<string, unknown>;
+}
+/**
+ * Claude Code provider options
+ */
+export interface ClaudeCodeConfig {
+    [key: string]: unknown;
+}
+/**
+ * OpenCode provider options
+ */
+export interface OpenCodeConfig {
+    hostname?: string;
+    port?: number;
+    autoStartServer?: boolean;
+    serverTimeout?: number;
+    defaultSettings?: Record<string, unknown>;
+    modelSettings?: Record<string, unknown>;
+}
+/**
+ * Cloud provider configurations (grouped)
+ */
+export interface CloudConfig {
+    /** AWS/Bedrock options */
+    aws?: AwsConfig;
+    /** Google Cloud/Vertex options */
+    gcp?: GcpConfig;
+    /** Azure options */
+    azure?: AzureConfig;
+    /** SAP AI Core options */
+    sap?: SapConfig;
+    /** OCA options */
+    oca?: OcaConfig;
+}
+/**
+ * Provider-specific options that don't fit other categories
+ */
+export interface ProviderOptions {
+    /** OpenRouter provider sorting preference */
+    openRouterProviderSorting?: string;
+    /** Runtime model catalog refresh configuration */
+    modelCatalog?: ModelCatalogConfig;
+}
+/**
+ * Runtime model catalog refresh options
+ */
+export interface ModelCatalogConfig {
+    /** Fetch latest catalog at handler initialization */
+    loadLatestOnInit?: boolean;
+    /** Fetch provider-private models when auth is available */
+    loadPrivateOnAuth?: boolean;
+    /** Catalog endpoint URL */
+    url?: string;
+    /** Cache TTL for live catalog in milliseconds */
+    cacheTtlMs?: number;
+    /** Throw when live catalog refresh fails */
+    failOnError?: boolean;
+}
+/**
+ * Unified provider configuration interface
+ *
+ * This is the single configuration interface that clients provide.
+ * All provider-specific options are grouped into logical sub-interfaces.
+ */
+export interface ProviderConfig extends AuthConfig, EndpointConfig, ModelConfig, TokenConfig, ReasoningConfig, RegionConfig, CloudConfig, ProviderOptions {
+    /** Provider ID - determines which handler to use */
+    providerId: ProviderId;
+    /** Capabilities this provider/model supports */
+    capabilities?: ProviderCapability[];
+    /** Task/session ID for telemetry */
+    taskId?: string;
+    /** Retry callback */
+    onRetryAttempt?: (attempt: number, maxRetries: number, delay: number, error: unknown) => void;
+    /** AbortSignal for cancelling requests */
+    abortSignal?: AbortSignal;
+    /** Codex CLI-specific options */
+    codex?: CodexConfig;
+    /** Claude Code-specific options */
+    claudeCode?: ClaudeCodeConfig;
+    /** OpenCode-specific options */
+    opencode?: OpenCodeConfig;
+}
+/**
+ * Simplified configuration for common use cases
+ */
+export interface SimpleProviderConfig {
+    providerId: ProviderId;
+    apiKey: string;
+    modelId: string;
+    baseUrl?: string;
+}
+/**
+ * Create a full ProviderConfig from a simple config
+ */
+export declare function createConfig(simple: SimpleProviderConfig): ProviderConfig;
+/**
+ * Check if a provider config has a specific capability
+ */
+export declare function hasCapability(config: ProviderConfig, capability: ProviderCapability): boolean;
+/**
+ * Check if provider supports reasoning/thinking
+ */
+export declare function supportsReasoning(config: ProviderConfig): boolean;
+/**
+ * Check if provider supports prompt caching
+ */
+export declare function supportsPromptCache(config: ProviderConfig): boolean;
+/**
+ * @deprecated Use ProviderConfig directly - all fields are now unified
+ */
+export type ProviderSpecificConfig = Pick<ProviderConfig, "aws" | "gcp" | "azure" | "sap" | "oca" | "maxContextTokens" | "apiLine" | "oauthPath" | "openRouterProviderSorting">;
+/**
+ * @deprecated Use ProviderConfig directly
+ */
+export type ProviderDefaultsConfig = Pick<ProviderConfig, "baseUrl" | "modelId" | "knownModels" | "headers" | "capabilities">;

package/dist/providers/types/handler.d.ts

@@ -0,0 +1,71 @@
+/**
+ * Handler Interface Types
+ *
+ * Core interfaces that all provider handlers must implement.
+ */
+import type { Message, ToolDefinition } from "./messages";
+import type { ModelInfo } from "./model-info";
+import type { ApiStream, ApiStreamUsageChunk } from "./stream";
+/**
+ * Model information returned by handlers
+ */
+export interface HandlerModelInfo {
+    /** Model identifier */
+    id: string;
+    /** Model capabilities and pricing info */
+    info: ModelInfo;
+}
+/**
+ * Core API Handler interface
+ *
+ * All providers must implement this interface.
+ */
+export interface ApiHandler {
+    /**
+     * Convert Cline messages into provider-specific message format
+     *
+     * @param systemPrompt - The system prompt to use
+     * @param messages - Conversation history
+     * @returns Provider-specific messages payload
+     */
+    getMessages(systemPrompt: string, messages: Message[]): unknown;
+    /**
+     * Create a streaming message completion
+     *
+     * @param systemPrompt - The system prompt to use
+     * @param messages - Conversation history
+     * @param tools - Optional tool definitions for native tool calling
+     * @returns An async generator yielding stream chunks
+     */
+    createMessage(systemPrompt: string, messages: Message[], tools?: ToolDefinition[]): ApiStream;
+    /**
+     * Get the current model configuration
+     */
+    getModel(): HandlerModelInfo;
+    /**
+     * Get usage information for the last API call (optional)
+     * Some providers can fetch this from a separate endpoint
+     */
+    getApiStreamUsage?(): Promise<ApiStreamUsageChunk | undefined>;
+    /**
+     * Abort the current request (optional)
+     */
+    abort?(): void;
+}
+/**
+ * Handler for simple single-turn completions
+ */
+export interface SingleCompletionHandler {
+    /**
+     * Complete a single prompt without streaming
+     */
+    completePrompt(prompt: string): Promise<string>;
+}
+/**
+ * Factory function type for creating handlers
+ */
+export type HandlerFactory<TConfig = unknown> = (config: TConfig) => ApiHandler;
+/**
+ * Async factory for lazy-loaded handlers
+ */
+export type LazyHandlerFactory<TConfig = unknown> = (config: TConfig) => Promise<ApiHandler>;

package/dist/providers/types/index.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Types Index
+ *
+ * Re-exports all types from the types module.
+ */
+export { type AuthConfig, type AwsConfig, type AzureConfig, BUILT_IN_PROVIDER, BUILT_IN_PROVIDER_IDS, type BuiltInProviderId, type ClaudeCodeConfig, type CloudConfig, type CodexConfig, createConfig, type EndpointConfig, type GcpConfig, hasCapability, isBuiltInProviderId, type ModelCatalogConfig, type ModelConfig, normalizeProviderId, type OcaConfig, type OpenCodeConfig, type ProviderCapability, type ProviderCategory, type ProviderConfig, type ProviderDefaultsConfig, type ProviderId, type ProviderOptions, type ProviderSpecificConfig, type ReasoningConfig, type RegionConfig, type SapConfig, type SimpleProviderConfig, supportsPromptCache, supportsReasoning, type TokenConfig, } from "./config";
+export type { ApiHandler, HandlerFactory, HandlerModelInfo, LazyHandlerFactory, SingleCompletionHandler, } from "./handler";
+export type { ContentBlock, FileContent, ImageContent, Message, MessageRole, MessageWithMetadata, RedactedThinkingContent, TextContent, ThinkingContent, ToolDefinition, ToolResultContent, ToolUseContent, } from "./messages";
+export { ApiFormat, getModelPricing, hasModelCapability, type ModelCapability, type ModelInfo, type ModelPricing, type ModelWithId, type OpenAICompatibleModelInfo, supportsModelThinking, type ThinkingConfig, } from "./model-info";
+export { type AuthSettings, AuthSettingsSchema, type AwsSettings, AwsSettingsSchema, type AzureSettings, AzureSettingsSchema, createProviderConfig, type GcpSettings, GcpSettingsSchema, type ModelCatalogSettings, ModelCatalogSettingsSchema, type OcaSettings, OcaSettingsSchema, ProviderIdSchema, type ProviderSettings, ProviderSettingsSchema, parseSettings, type ReasoningSettings, ReasoningSettingsSchema, type SapSettings, SapSettingsSchema, safeCreateProviderConfig, safeParseSettings, toProviderConfig, } from "./settings";
+export type { ApiStream, ApiStreamChunk, ApiStreamDoneChunk, ApiStreamReasoningChunk, ApiStreamTextChunk, ApiStreamToolCall, ApiStreamToolCallsChunk, ApiStreamUsageChunk, } from "./stream";

package/dist/providers/types/messages.d.ts

@@ -0,0 +1,139 @@
+/**
+ * Message Types
+ *
+ * Standardized message format for input to providers.
+ * This is a simplified, provider-agnostic format that can be
+ * converted to any provider's native format.
+ */
+/**
+ * Message roles
+ */
+export type MessageRole = "user" | "assistant";
+/**
+ * Text content block
+ */
+export interface TextContent {
+    type: "text";
+    text: string;
+    /** Thought signature for this text part (Gemini) */
+    signature?: string;
+}
+/**
+ * File content block for Cline
+ */
+export interface FileContent {
+    type: "file";
+    content: string;
+    /** Absolute Path */
+    path: string;
+    source?: string;
+}
+/**
+ * Image content block
+ */
+export interface ImageContent {
+    type: "image";
+    /** Base64 encoded image data */
+    data: string;
+    /** MIME type (e.g., "image/png", "image/jpeg") */
+    mediaType: string;
+}
+/**
+ * Tool use content block (assistant's tool call)
+ */
+export interface ToolUseContent {
+    type: "tool_use";
+    /** Unique ID for this tool call */
+    id: string;
+    /** Name of the tool being called */
+    name: string;
+    /** Arguments for the tool call */
+    input: Record<string, unknown>;
+    /** Thought signature for this function call part (Gemini) */
+    signature?: string;
+}
+/**
+ * Tool result content block (user's response to tool call)
+ */
+export interface ToolResultContent {
+    type: "tool_result";
+    /** ID of the tool call this is responding to */
+    tool_use_id: string;
+    /** Result content (can be text or error) */
+    content: string | Array<TextContent | ImageContent | FileContent>;
+    /** Whether this result represents an error */
+    is_error?: boolean;
+}
+/**
+ * Thinking/reasoning content block
+ */
+export interface ThinkingContent {
+    type: "thinking";
+    /** The thinking/reasoning text */
+    thinking: string;
+    /** Signature for the thinking block (provider-specific) */
+    signature?: string;
+}
+/**
+ * Redacted thinking content block
+ */
+export interface RedactedThinkingContent {
+    type: "redacted_thinking";
+    /** Encrypted/redacted data */
+    data: string;
+}
+/**
+ * Union of all content block types
+ */
+export type ContentBlock = TextContent | ImageContent | ToolUseContent | ToolResultContent | ThinkingContent | FileContent | RedactedThinkingContent;
+/**
+ * A single message in the conversation
+ */
+export interface Message {
+    /** Message role */
+    role: MessageRole;
+    /** Message content - can be a simple string or array of content blocks */
+    content: string | ContentBlock[];
+}
+/**
+ * Extended message with metadata (used for storage/history)
+ */
+export interface MessageWithMetadata extends Message {
+    /** Unique message ID */
+    id?: string;
+    /** Provider ID used to generate this message */
+    providerId?: string;
+    /** Model ID used to generate this message */
+    modelId?: string;
+    /** Model info at the time of generation */
+    modelInfo?: {
+        id: string;
+        provider: string;
+    };
+    /** Token usage metrics */
+    metrics?: {
+        inputTokens?: number;
+        outputTokens?: number;
+        cacheReadTokens?: number;
+        cacheWriteTokens?: number;
+        cost?: number;
+    };
+    /** Timestamp of when the message was created */
+    ts?: number;
+}
+/**
+ * Tool definition for native tool calling
+ */
+export interface ToolDefinition {
+    /** Tool name */
+    name: string;
+    /** Tool description */
+    description: string;
+    /** JSON Schema for the tool's input parameters */
+    inputSchema: {
+        type: "object";
+        properties: Record<string, unknown>;
+        required?: string[];
+        additionalProperties?: boolean;
+    };
+}

package/dist/providers/types/model-info.d.ts

@@ -0,0 +1,32 @@
+/**
+ * Model Information Types
+ *
+ * Re-exports model types from @clinebot/models (the single source of truth)
+ * and provides provider-specific helpers and aliases.
+ */
+import type { ModelCapability, ModelInfo, ModelPricing, ThinkingConfig } from "../../models/schemas/model";
+import { ApiFormat } from "../../models/schemas/model";
+export type { ModelCapability, ModelInfo, ModelPricing, ThinkingConfig };
+export { ApiFormat };
+export type { ApiFormat as ApiFormatType } from "../../models/schemas/model";
+/**
+ * Check if a model has a specific capability
+ */
+export declare function hasModelCapability(info: ModelInfo, capability: ModelCapability): boolean;
+/**
+ * Check if a model supports explicit thinking/reasoning controls.
+ */
+export declare function supportsModelThinking(info: ModelInfo): boolean;
+/**
+ * Get pricing for a model
+ */
+export declare function getModelPricing(info: ModelInfo): ModelPricing;
+/**
+ * Model with its identifier
+ */
+export interface ModelWithId {
+    id: string;
+    info: ModelInfo;
+}
+/** Alias for ModelInfo - all model types use the same interface */
+export type OpenAICompatibleModelInfo = ModelInfo;

package/dist/providers/types/provider-ids.d.ts

@@ -0,0 +1,63 @@
+/**
+ * Built-in provider IDs
+ *
+ * Single source of truth for all built-in provider identifiers.
+ * Use BUILT_IN_PROVIDER_IDS for runtime operations (validation, iteration)
+ * Use BuiltInProviderId type for compile-time type safety
+ */
+export declare enum BUILT_IN_PROVIDER {
+    ANTHROPIC = "anthropic",
+    CLAUDE_CODE = "claude-code",
+    CLINE = "cline",
+    OPENAI = "openai",// OpenAi Completions
+    OPENAI_NATIVE = "openai-native",
+    OPENAI_CODEX = "openai-codex",
+    OPENCODE = "opencode",
+    BEDROCK = "bedrock",
+    VERTEX = "vertex",
+    GEMINI = "gemini",
+    OLLAMA = "ollama",
+    LMSTUDIO = "lmstudio",
+    DEEPSEEK = "deepseek",
+    XAI = "xai",
+    TOGETHER = "together",
+    FIREWORKS = "fireworks",
+    GROQ = "groq",
+    CEREBRAS = "cerebras",
+    SAMBANOVA = "sambanova",
+    NEBIUS = "nebius",
+    BASETEN = "baseten",
+    REQUESTY = "requesty",
+    LITELLM = "litellm",
+    HUGGINGFACE = "huggingface",
+    VERCEL_AI_GATEWAY = "vercel-ai-gateway",
+    AIHUBMIX = "aihubmix",
+    HICAP = "hicap",
+    NOUS_RESEARCH = "nousResearch",
+    HUAWEI_CLOUD_MAAS = "huawei-cloud-maas",
+    QWEN = "qwen",
+    QWEN_CODE = "qwen-code",
+    DOUBAO = "doubao",
+    MISTRAL = "mistral",
+    MOONSHOT = "moonshot",
+    ASKSAGE = "asksage",
+    ZAI = "zai",
+    MINIMAX = "minimax",
+    DIFY = "dify",
+    OCA = "oca",
+    SAPAICORE = "sapaicore",
+    OPENROUTER = "openrouter"
+}
+/**
+ * Provider ID aliases normalized to canonical built-in IDs.
+ *
+ * Keep this map as the single source of truth for alias handling.
+ */
+export declare const PROVIDER_ID_ALIASES: Record<string, BUILT_IN_PROVIDER>;
+export declare const BUILT_IN_PROVIDER_IDS: [BUILT_IN_PROVIDER, ...BUILT_IN_PROVIDER[]];
+/** Type derived from the array - use for type annotations */
+export type BuiltInProviderId = (typeof BUILT_IN_PROVIDER_IDS)[number];
+/** Check if a string is a valid built-in provider ID */
+export declare function isBuiltInProviderId(id: string): id is BuiltInProviderId;
+/** Normalize provider aliases to canonical IDs */
+export declare function normalizeProviderId(providerId: string): string;