@compilr-dev/sdk 0.1.0

package/dist/models/model-registry.js

@@ -0,0 +1,621 @@
+/**
+ * Model Registry
+ *
+ * Defines supported models with metadata for each provider.
+ * Used for:
+ * - Model selection UI (list instead of free text)
+ * - Session restore strategy (based on thinking format)
+ * - Status indicators and warnings
+ * - Context window resolution
+ */
+// =============================================================================
+// Model Registry
+// =============================================================================
+/**
+ * Registry of known models with their metadata.
+ * Models are grouped by provider for easier maintenance.
+ */
+export const MODEL_REGISTRY = [
+    // ---------------------------------------------------------------------------
+    // Claude Models (Anthropic)
+    // ---------------------------------------------------------------------------
+    {
+        id: 'claude-haiku-4-5-20251001',
+        displayName: 'Haiku 4.5',
+        description: 'Fast, low cost',
+        provider: 'claude',
+        defaultTier: 'fast',
+        thinkingFormat: 'claude',
+        status: 'supported',
+        contextWindow: 200000,
+    },
+    {
+        id: 'claude-sonnet-4-5-20250929',
+        displayName: 'Sonnet 4.5',
+        description: 'Balanced (recommended)',
+        provider: 'claude',
+        defaultTier: 'balanced',
+        thinkingFormat: 'claude',
+        status: 'supported',
+        contextWindow: 200000,
+    },
+    {
+        id: 'claude-opus-4-5-20251101',
+        displayName: 'Opus 4.5',
+        description: 'Most capable',
+        provider: 'claude',
+        defaultTier: 'powerful',
+        thinkingFormat: 'claude',
+        status: 'supported',
+        contextWindow: 200000,
+    },
+    // Older Claude models (still supported)
+    {
+        id: 'claude-3-5-sonnet-20241022',
+        displayName: 'Sonnet 3.5',
+        description: 'Previous generation',
+        provider: 'claude',
+        thinkingFormat: 'claude',
+        status: 'supported',
+        contextWindow: 200000,
+        notes: 'Previous generation',
+    },
+    {
+        id: 'claude-3-5-haiku-20241022',
+        displayName: 'Haiku 3.5',
+        description: 'Previous generation',
+        provider: 'claude',
+        thinkingFormat: 'claude',
+        status: 'supported',
+        contextWindow: 200000,
+        notes: 'Previous generation',
+    },
+    // ---------------------------------------------------------------------------
+    // Gemini Models (Google)
+    // ---------------------------------------------------------------------------
+    // Gemini 2.x - Supported
+    {
+        id: 'gemini-2.0-flash',
+        displayName: 'Gemini 2.0 Flash',
+        description: 'Fast, no thinking',
+        provider: 'gemini',
+        thinkingFormat: 'none',
+        status: 'supported',
+        contextWindow: 1000000,
+        notes: 'Fast, no thinking blocks',
+    },
+    {
+        id: 'gemini-2.5-flash-lite',
+        displayName: 'Gemini 2.5 Flash Lite',
+        description: 'Fast, low cost',
+        provider: 'gemini',
+        defaultTier: 'fast',
+        thinkingFormat: 'gemini-v2',
+        status: 'supported',
+        contextWindow: 1000000,
+    },
+    {
+        id: 'gemini-2.5-flash',
+        displayName: 'Gemini 2.5 Flash',
+        description: 'Balanced (recommended)',
+        provider: 'gemini',
+        defaultTier: 'balanced',
+        thinkingFormat: 'gemini-v2',
+        status: 'supported',
+        contextWindow: 1000000,
+    },
+    {
+        id: 'gemini-2.5-pro',
+        displayName: 'Gemini 2.5 Pro',
+        description: 'Most capable',
+        provider: 'gemini',
+        defaultTier: 'powerful',
+        thinkingFormat: 'gemini-v2',
+        status: 'supported',
+        contextWindow: 1000000,
+    },
+    // Gemini 3.x - Preview, has stability issues with function calling
+    {
+        id: 'gemini-3-flash-preview',
+        displayName: 'Gemini 3 Flash (Preview)',
+        description: 'Preview - may have stability issues',
+        provider: 'gemini',
+        thinkingFormat: 'gemini-v3',
+        status: 'supported',
+        contextWindow: 1000000,
+        notes: 'Preview: 500 errors during function calling, high token usage',
+    },
+    {
+        id: 'gemini-3-pro-preview',
+        displayName: 'Gemini 3 Pro (Preview)',
+        description: 'Preview - may have stability issues',
+        provider: 'gemini',
+        thinkingFormat: 'gemini-v3',
+        status: 'supported',
+        contextWindow: 1000000,
+        notes: 'Preview: Works but very high token usage during function calling',
+    },
+    // ---------------------------------------------------------------------------
+    // OpenAI Models
+    // ---------------------------------------------------------------------------
+    {
+        id: 'gpt-4o',
+        displayName: 'GPT-4o',
+        description: 'Balanced (recommended)',
+        provider: 'openai',
+        defaultTier: 'balanced',
+        thinkingFormat: 'none',
+        status: 'supported',
+        contextWindow: 128000,
+    },
+    {
+        id: 'gpt-4o-mini',
+        displayName: 'GPT-4o Mini',
+        description: 'Fast, low cost',
+        provider: 'openai',
+        defaultTier: 'fast',
+        thinkingFormat: 'none',
+        status: 'supported',
+        contextWindow: 128000,
+    },
+    {
+        id: 'gpt-4-turbo',
+        displayName: 'GPT-4 Turbo',
+        description: 'Most capable',
+        provider: 'openai',
+        defaultTier: 'powerful',
+        thinkingFormat: 'none',
+        status: 'supported',
+        contextWindow: 128000,
+    },
+    // GPT-5 models (if available)
+    {
+        id: 'gpt-5-nano-2025-08-07',
+        displayName: 'GPT-5 Nano',
+        description: 'Fast, experimental',
+        provider: 'openai',
+        thinkingFormat: 'none',
+        status: 'experimental',
+        contextWindow: 128000,
+        notes: 'Latest generation',
+    },
+    {
+        id: 'gpt-5-mini-2025-08-07',
+        displayName: 'GPT-5 Mini',
+        description: 'Balanced, experimental',
+        provider: 'openai',
+        thinkingFormat: 'none',
+        status: 'experimental',
+        contextWindow: 128000,
+        notes: 'Latest generation',
+    },
+    {
+        id: 'gpt-5.2-2025-12-11',
+        displayName: 'GPT-5.2',
+        description: 'Most capable, experimental',
+        provider: 'openai',
+        thinkingFormat: 'none',
+        status: 'experimental',
+        contextWindow: 128000,
+        notes: 'Latest generation',
+    },
+    // ---------------------------------------------------------------------------
+    // Ollama Models (Local)
+    // ---------------------------------------------------------------------------
+    {
+        id: 'llama3.2:8b',
+        displayName: 'Llama 3.2 8B',
+        description: 'Fast, small',
+        provider: 'ollama',
+        defaultTier: 'fast',
+        thinkingFormat: 'none',
+        status: 'supported',
+        notes: 'Requires: ollama pull llama3.2:8b',
+    },
+    {
+        id: 'llama3.2:70b',
+        displayName: 'Llama 3.2 70B',
+        description: 'Most capable',
+        provider: 'ollama',
+        defaultTier: 'powerful',
+        thinkingFormat: 'none',
+        status: 'supported',
+        notes: 'Requires: ollama pull llama3.2:70b',
+    },
+    {
+        id: 'deepseek-r1:14b',
+        displayName: 'DeepSeek R1 14B',
+        description: 'Balanced, reasoning',
+        provider: 'ollama',
+        defaultTier: 'balanced',
+        thinkingFormat: 'none',
+        status: 'supported',
+        notes: 'Requires: ollama pull deepseek-r1:14b',
+    },
+    {
+        id: 'deepseek-r1:32b',
+        displayName: 'DeepSeek R1 32B',
+        description: 'Strong reasoning',
+        provider: 'ollama',
+        thinkingFormat: 'none',
+        status: 'supported',
+        notes: 'Requires: ollama pull deepseek-r1:32b',
+    },
+    {
+        id: 'qwen2.5:7b',
+        displayName: 'Qwen 2.5 7B',
+        description: 'Fast, multilingual',
+        provider: 'ollama',
+        thinkingFormat: 'none',
+        status: 'supported',
+        notes: 'Requires: ollama pull qwen2.5:7b',
+    },
+    {
+        id: 'qwen2.5:32b',
+        displayName: 'Qwen 2.5 32B',
+        description: 'Strong multilingual',
+        provider: 'ollama',
+        thinkingFormat: 'none',
+        status: 'supported',
+        notes: 'Requires: ollama pull qwen2.5:32b',
+    },
+    {
+        id: 'mistral:7b',
+        displayName: 'Mistral 7B',
+        description: 'Fast, efficient',
+        provider: 'ollama',
+        thinkingFormat: 'none',
+        status: 'supported',
+        notes: 'Requires: ollama pull mistral:7b',
+    },
+    {
+        id: 'codellama:13b',
+        displayName: 'Code Llama 13B',
+        description: 'Code-focused',
+        provider: 'ollama',
+        thinkingFormat: 'none',
+        status: 'supported',
+        notes: 'Optimized for code. Requires: ollama pull codellama:13b',
+    },
+    // ---------------------------------------------------------------------------
+    // Together AI Models (OpenAI-compatible)
+    // ---------------------------------------------------------------------------
+    {
+        id: 'meta-llama/Llama-3.2-8B-Instruct-Turbo',
+        displayName: 'Llama 3.2 8B Instruct',
+        description: 'Fast, low cost',
+        provider: 'together',
+        defaultTier: 'fast',
+        thinkingFormat: 'none',
+        status: 'supported',
+    },
+    {
+        id: 'meta-llama/Llama-3.2-70B-Instruct-Turbo',
+        displayName: 'Llama 3.2 70B Instruct',
+        description: 'Balanced',
+        provider: 'together',
+        defaultTier: 'balanced',
+        thinkingFormat: 'none',
+        status: 'supported',
+    },
+    {
+        id: 'deepseek-ai/DeepSeek-R1-Distill-Llama-70B',
+        displayName: 'DeepSeek R1 70B',
+        description: 'Most capable',
+        provider: 'together',
+        defaultTier: 'powerful',
+        thinkingFormat: 'none',
+        status: 'supported',
+    },
+    // ---------------------------------------------------------------------------
+    // Groq Models (OpenAI-compatible, fast inference)
+    // ---------------------------------------------------------------------------
+    {
+        id: 'llama-3.2-8b-instant',
+        displayName: 'Llama 3.2 8B',
+        description: 'Fast, low cost',
+        provider: 'groq',
+        defaultTier: 'fast',
+        thinkingFormat: 'none',
+        status: 'supported',
+    },
+    {
+        id: 'llama-3.2-70b-versatile',
+        displayName: 'Llama 3.2 70B',
+        description: 'Balanced',
+        provider: 'groq',
+        defaultTier: 'balanced',
+        thinkingFormat: 'none',
+        status: 'supported',
+    },
+    {
+        id: 'deepseek-r1-distill-llama-70b',
+        displayName: 'DeepSeek R1 70B',
+        description: 'Most capable',
+        provider: 'groq',
+        defaultTier: 'powerful',
+        thinkingFormat: 'none',
+        status: 'supported',
+    },
+    // ---------------------------------------------------------------------------
+    // Fireworks AI Models (OpenAI-compatible)
+    // ---------------------------------------------------------------------------
+    {
+        id: 'accounts/fireworks/models/llama-v3p2-8b-instruct',
+        displayName: 'Llama 3.2 8B',
+        description: 'Fast, low cost',
+        provider: 'fireworks',
+        defaultTier: 'fast',
+        thinkingFormat: 'none',
+        status: 'supported',
+    },
+    {
+        id: 'accounts/fireworks/models/llama-v3p2-70b-instruct',
+        displayName: 'Llama 3.2 70B',
+        description: 'Balanced',
+        provider: 'fireworks',
+        defaultTier: 'balanced',
+        thinkingFormat: 'none',
+        status: 'supported',
+    },
+    {
+        id: 'accounts/fireworks/models/deepseek-r1',
+        displayName: 'DeepSeek R1',
+        description: 'Most capable',
+        provider: 'fireworks',
+        defaultTier: 'powerful',
+        thinkingFormat: 'none',
+        status: 'supported',
+    },
+    // ---------------------------------------------------------------------------
+    // Perplexity Models (Search-augmented AI)
+    // ---------------------------------------------------------------------------
+    {
+        id: 'llama-3.1-sonar-small-128k-online',
+        displayName: 'Sonar Small',
+        description: 'Fast, low cost',
+        provider: 'perplexity',
+        defaultTier: 'fast',
+        thinkingFormat: 'none',
+        status: 'supported',
+        notes: 'Includes real-time web search',
+    },
+    {
+        id: 'llama-3.1-sonar-large-128k-online',
+        displayName: 'Sonar Large',
+        description: 'Balanced',
+        provider: 'perplexity',
+        defaultTier: 'balanced',
+        thinkingFormat: 'none',
+        status: 'supported',
+        notes: 'Includes real-time web search',
+    },
+    {
+        id: 'llama-3.1-sonar-huge-128k-online',
+        displayName: 'Sonar Huge',
+        description: 'Most capable',
+        provider: 'perplexity',
+        defaultTier: 'powerful',
+        thinkingFormat: 'none',
+        status: 'supported',
+        notes: 'Includes real-time web search',
+    },
+    // ---------------------------------------------------------------------------
+    // OpenRouter Models (Aggregator - access many providers)
+    // ---------------------------------------------------------------------------
+    {
+        id: 'meta-llama/llama-3.2-8b-instruct',
+        displayName: 'Llama 3.2 8B',
+        description: 'Fast, low cost',
+        provider: 'openrouter',
+        defaultTier: 'fast',
+        thinkingFormat: 'none',
+        status: 'supported',
+    },
+    {
+        id: 'anthropic/claude-3-5-sonnet',
+        displayName: 'Claude 3.5 Sonnet',
+        description: 'Balanced (via OpenRouter)',
+        provider: 'openrouter',
+        defaultTier: 'balanced',
+        thinkingFormat: 'none',
+        status: 'supported',
+    },
+    {
+        id: 'anthropic/claude-3-opus',
+        displayName: 'Claude 3 Opus',
+        description: 'Most capable (via OpenRouter)',
+        provider: 'openrouter',
+        defaultTier: 'powerful',
+        thinkingFormat: 'none',
+        status: 'supported',
+    },
+];
+// =============================================================================
+// Helper Functions
+// =============================================================================
+/**
+ * Get all models for a specific provider.
+ */
+export function getModelsForProvider(provider) {
+    return MODEL_REGISTRY.filter((m) => m.provider === provider);
+}
+/**
+ * Get models for a provider, sorted for display.
+ * Order: supported first, then by defaultTier (fast->balanced->powerful), then alphabetical.
+ */
+export function getModelsSortedForDisplay(provider) {
+    const models = getModelsForProvider(provider);
+    return models.sort((a, b) => {
+        // Status priority: supported > experimental > unsupported
+        const statusOrder = {
+            supported: 0,
+            experimental: 1,
+            unsupported: 2,
+        };
+        const statusDiff = statusOrder[a.status] - statusOrder[b.status];
+        if (statusDiff !== 0)
+            return statusDiff;
+        // Default tier models first (they're the recommended ones)
+        const aHasDefault = a.defaultTier !== undefined ? 0 : 1;
+        const bHasDefault = b.defaultTier !== undefined ? 0 : 1;
+        if (aHasDefault !== bHasDefault)
+            return aHasDefault - bHasDefault;
+        // Alphabetical by display name
+        return a.displayName.localeCompare(b.displayName);
+    });
+}
+/**
+ * Get model info by ID.
+ * Returns undefined for unknown models.
+ */
+export function getModelInfo(modelId) {
+    return MODEL_REGISTRY.find((m) => m.id === modelId);
+}
+/**
+ * Check if a model is in the registry.
+ */
+export function isKnownModel(modelId) {
+    return MODEL_REGISTRY.some((m) => m.id === modelId);
+}
+/**
+ * Check if a model is supported.
+ * Returns false for unknown models (conservative default).
+ */
+export function isModelSupported(modelId) {
+    const model = getModelInfo(modelId);
+    return model?.status === 'supported';
+}
+/**
+ * Get the thinking format for a model.
+ * Returns 'none' for unknown models (safe default).
+ */
+export function getThinkingFormat(modelId) {
+    const model = getModelInfo(modelId);
+    return model?.thinkingFormat ?? 'none';
+}
+/**
+ * Get status indicator for UI display.
+ */
+export function getStatusIndicator(status) {
+    switch (status) {
+        case 'supported':
+            return '✓';
+        case 'experimental':
+            return '~';
+        case 'unsupported':
+            return '⚠';
+    }
+}
+/**
+ * Get status label for UI display.
+ */
+export function getStatusLabel(status) {
+    switch (status) {
+        case 'supported':
+            return 'Supported';
+        case 'experimental':
+            return 'Experimental';
+        case 'unsupported':
+            return 'Unsupported';
+    }
+}
+/**
+ * Get the default model for a tier from the registry.
+ * Returns the first model with that defaultTier, or undefined if none.
+ */
+export function getDefaultModelForTier(provider, tier) {
+    return MODEL_REGISTRY.find((m) => m.provider === provider && m.defaultTier === tier && m.status === 'supported');
+}
+/**
+ * Check if two models have compatible thinking formats for session restore.
+ * Compatible means we can restore without clearing history.
+ */
+export function areThinkingFormatsCompatible(fromModelId, toModelId) {
+    if (!fromModelId)
+        return true; // No previous model = compatible
+    const fromFormat = getThinkingFormat(fromModelId);
+    const toFormat = getThinkingFormat(toModelId);
+    // Same format is always compatible
+    if (fromFormat === toFormat)
+        return true;
+    // 'none' is compatible with anything (no thinking blocks to worry about)
+    if (fromFormat === 'none' || toFormat === 'none')
+        return true;
+    // gemini-v3 is incompatible with everything else
+    if (fromFormat === 'gemini-v3' || toFormat === 'gemini-v3')
+        return false;
+    // claude and gemini-v2 are NOT directly compatible (different formats)
+    // but we can strip thinking blocks
+    return false;
+}
+/**
+ * Determine if session history should be cleared when switching models.
+ * Returns true if history must be cleared (incompatible), false if we can keep/strip.
+ *
+ * Note: Gemini v3 no longer requires clearing history since Session 119.
+ * The native @google/genai SDK handles thought signatures automatically.
+ */
+export function shouldClearHistoryOnModelChange(_fromModelId, _toModelId) {
+    // With native SDK support for all providers, no model switch requires clearing history.
+    // Thinking blocks from different providers can be stripped during restore.
+    return false;
+}
+// =============================================================================
+// Context Window Resolution
+// =============================================================================
+/**
+ * Provider fallback context limits.
+ * Used when a model is not in the registry or has no contextWindow set.
+ */
+function getProviderContextLimitFallback(provider) {
+    switch (provider) {
+        case 'gemini':
+            return 1000000;
+        case 'claude':
+            return 200000;
+        case 'openai':
+            return 128000;
+        case 'ollama':
+            return 32000;
+        case 'together':
+            return 131072;
+        case 'groq':
+            return 131072;
+        case 'fireworks':
+            return 131072;
+        case 'perplexity':
+            return 131072;
+        case 'openrouter':
+            return 128000;
+        default:
+            return 200000;
+    }
+}
+/**
+ * Get context window size for a model ID.
+ * Falls back to provider default if model not found or contextWindow not set.
+ */
+export function getModelContextWindow(modelId, provider) {
+    const info = getModelInfo(modelId);
+    if (info?.contextWindow) {
+        return info.contextWindow;
+    }
+    return getProviderContextLimitFallback(provider);
+}
+/**
+ * Get model display name by ID.
+ * Returns the model ID if not found in registry.
+ */
+export function getModelDisplayName(modelId) {
+    const model = getModelInfo(modelId);
+    return model?.displayName ?? modelId;
+}
+/**
+ * Get model description by ID.
+ * Returns empty string if not found.
+ */
+export function getModelDescription(modelId) {
+    const model = getModelInfo(modelId);
+    return model?.description ?? '';
+}

package/dist/models/model-tiers.d.ts

@@ -0,0 +1,36 @@
+/**
+ * Model Tiers — Role-Based Model Selection (Pure/Settings-Free)
+ *
+ * Pure functions for tier-based model selection. The SDK version accepts
+ * optional override maps as parameters instead of reading from settings.
+ * CLI wraps these with its settings layer.
+ */
+import type { ProviderType } from '../config.js';
+import type { ModelTier, ProviderModelMap } from './types.js';
+/**
+ * Get the model ID for a given tier and provider.
+ * Checks overrides first, then falls back to registry defaults.
+ *
+ * @param provider - The provider type
+ * @param tier - The model tier
+ * @param overrides - Optional tier overrides (e.g., from user settings)
+ */
+export declare function getModelForTier(provider: ProviderType, tier: ModelTier, overrides?: Partial<Record<ProviderType, Partial<ProviderModelMap>>>): string;
+/**
+ * Get all tier mappings for a provider (with optional overrides applied).
+ */
+export declare function getTierMappings(provider: ProviderType, overrides?: Partial<Record<ProviderType, Partial<ProviderModelMap>>>): ProviderModelMap;
+/**
+ * Get the display name for a model tier.
+ */
+export declare function getTierDisplayName(tier: ModelTier): string;
+/**
+ * Get short model name from full model ID (for display).
+ * e.g., "claude-sonnet-4-5-20250929" -> "Sonnet 4.5"
+ */
+export declare function getShortModelName(modelId: string): string;
+/**
+ * Get the default tier mappings (without user overrides).
+ * Derived from MODEL_REGISTRY — single source of truth.
+ */
+export declare function getDefaultTierMappings(): Record<ProviderType, ProviderModelMap>;