@compilr-dev/sdk 0.1.0

package/dist/models/model-tiers.js

@@ -0,0 +1,105 @@
+/**
+ * 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 { TIER_INFO } from './types.js';
+import { getDefaultModelForTier as getDefaultFromRegistry } from './model-registry.js';
+/**
+ * Get the default model ID for a tier from the registry.
+ */
+function getDefaultModelId(provider, tier) {
+    const modelInfo = getDefaultFromRegistry(provider, tier);
+    if (modelInfo) {
+        return modelInfo.id;
+    }
+    throw new Error(`No default model found for ${provider}/${tier} in MODEL_REGISTRY`);
+}
+/**
+ * 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 function getModelForTier(provider, tier, overrides) {
+    const override = overrides?.[provider]?.[tier];
+    if (override) {
+        return override;
+    }
+    return getDefaultModelId(provider, tier);
+}
+/**
+ * Get all tier mappings for a provider (with optional overrides applied).
+ */
+export function getTierMappings(provider, overrides) {
+    return {
+        fast: getModelForTier(provider, 'fast', overrides),
+        balanced: getModelForTier(provider, 'balanced', overrides),
+        powerful: getModelForTier(provider, 'powerful', overrides),
+    };
+}
+/**
+ * Get the display name for a model tier.
+ */
+export function getTierDisplayName(tier) {
+    return TIER_INFO[tier].label;
+}
+/**
+ * Get short model name from full model ID (for display).
+ * e.g., "claude-sonnet-4-5-20250929" -> "Sonnet 4.5"
+ */
+export function getShortModelName(modelId) {
+    // Claude models
+    if (modelId.includes('claude-haiku'))
+        return 'Haiku 4.5';
+    if (modelId.includes('claude-sonnet'))
+        return 'Sonnet 4.5';
+    if (modelId.includes('claude-opus'))
+        return 'Opus 4.5';
+    // OpenAI models
+    if (modelId.includes('gpt-5-nano'))
+        return 'GPT-5 Nano';
+    if (modelId.includes('gpt-5-mini'))
+        return 'GPT-5 Mini';
+    if (modelId.includes('gpt-5.2'))
+        return 'GPT-5.2';
+    if (modelId.includes('gpt-4o-mini'))
+        return 'GPT-4o Mini';
+    if (modelId.includes('gpt-4o'))
+        return 'GPT-4o';
+    if (modelId.includes('gpt-4-turbo'))
+        return 'GPT-4 Turbo';
+    // Gemini models
+    if (modelId.includes('gemini-2.5-flash-lite'))
+        return 'Flash Lite 2.5';
+    if (modelId.includes('gemini-2.5-flash'))
+        return 'Flash 2.5';
+    if (modelId.includes('gemini-2.5-pro'))
+        return 'Pro 2.5';
+    if (modelId.includes('gemini-3-flash'))
+        return 'Flash 3';
+    if (modelId.includes('gemini-3-pro'))
+        return 'Pro 3';
+    // Ollama - just return the model ID
+    return modelId;
+}
+/**
+ * Get the default tier mappings (without user overrides).
+ * Derived from MODEL_REGISTRY — single source of truth.
+ */
+export function getDefaultTierMappings() {
+    const providers = ['claude', 'openai', 'gemini', 'ollama'];
+    const tiers = ['fast', 'balanced', 'powerful'];
+    const result = {};
+    for (const provider of providers) {
+        result[provider] = {};
+        for (const tier of tiers) {
+            result[provider][tier] = getDefaultModelId(provider, tier);
+        }
+    }
+    return result;
+}

package/dist/models/providers.d.ts

@@ -0,0 +1,90 @@
+/**
+ * Provider Metadata
+ *
+ * Contains metadata for all providers, including "Others" providers
+ * that use OpenAI-compatible APIs.
+ *
+ * Note: CLI-specific fields like `credentialKey` are NOT included here.
+ * The CLI extends this metadata with its own credential mapping.
+ */
+import type { ProviderType } from '../config.js';
+/**
+ * Provider metadata for UI and configuration.
+ * Domain-agnostic — no credential storage concerns.
+ */
+export interface ProviderMetadata {
+    /** Provider type */
+    type: ProviderType;
+    /** Display name for UI */
+    displayName: string;
+    /** Short description */
+    description: string;
+    /** API endpoint URL */
+    endpoint: string;
+    /** Environment variable name for API key */
+    envVar: string;
+    /** URL to get API key */
+    keyUrl: string;
+    /** Whether this provider requires an API key */
+    requiresKey: boolean;
+    /** Provider category for grouping in UI */
+    category: 'primary' | 'local' | 'others';
+    /** Notes or warnings for the UI */
+    notes?: string;
+}
+/**
+ * Model metadata for "Others" providers.
+ * Curated list of recommended models per tier.
+ */
+export interface OthersProviderModel {
+    /** Model ID as used in API calls */
+    id: string;
+    /** Display name for UI */
+    displayName: string;
+    /** Short description */
+    description: string;
+    /** Provider type */
+    provider: ProviderType;
+    /** Tier (fast/balanced/powerful) */
+    tier: 'fast' | 'balanced' | 'powerful';
+}
+/**
+ * Metadata for all providers.
+ */
+export declare const PROVIDER_METADATA: Record<ProviderType, ProviderMetadata>;
+/**
+ * Curated models for Together AI.
+ */
+export declare const TOGETHER_MODELS: OthersProviderModel[];
+/**
+ * Curated models for Groq.
+ */
+export declare const GROQ_MODELS: OthersProviderModel[];
+/**
+ * Curated models for Fireworks AI.
+ */
+export declare const FIREWORKS_MODELS: OthersProviderModel[];
+/**
+ * Curated models for Perplexity.
+ */
+export declare const PERPLEXITY_MODELS: OthersProviderModel[];
+/**
+ * Curated models for OpenRouter.
+ */
+export declare const OPENROUTER_MODELS: OthersProviderModel[];
+/**
+ * Get curated models for a specific "Others" provider.
+ */
+export declare function getModelsForOthersProvider(provider: ProviderType): OthersProviderModel[];
+/**
+ * Get all "Others" providers (for UI listing).
+ */
+export declare function getOthersProviders(): ProviderMetadata[];
+/**
+ * Get provider metadata by type.
+ */
+export declare function getProviderMetadata(provider: ProviderType): ProviderMetadata;
+/**
+ * Check if a provider is an "Others" provider.
+ */
+export declare function isOthersProvider(provider: ProviderType): boolean;

package/dist/models/providers.js

@@ -0,0 +1,295 @@
+/**
+ * Provider Metadata
+ *
+ * Contains metadata for all providers, including "Others" providers
+ * that use OpenAI-compatible APIs.
+ *
+ * Note: CLI-specific fields like `credentialKey` are NOT included here.
+ * The CLI extends this metadata with its own credential mapping.
+ */
+// =============================================================================
+// Provider Metadata Registry
+// =============================================================================
+/**
+ * Metadata for all providers.
+ */
+export const PROVIDER_METADATA = {
+    // Primary providers
+    claude: {
+        type: 'claude',
+        displayName: 'Anthropic (Claude)',
+        description: 'Claude models from Anthropic',
+        endpoint: 'https://api.anthropic.com/v1',
+        envVar: 'ANTHROPIC_API_KEY',
+        keyUrl: 'https://console.anthropic.com/settings/keys',
+        requiresKey: true,
+        category: 'primary',
+    },
+    openai: {
+        type: 'openai',
+        displayName: 'OpenAI',
+        description: 'GPT models from OpenAI',
+        endpoint: 'https://api.openai.com/v1',
+        envVar: 'OPENAI_API_KEY',
+        keyUrl: 'https://platform.openai.com/api-keys',
+        requiresKey: true,
+        category: 'primary',
+    },
+    gemini: {
+        type: 'gemini',
+        displayName: 'Google AI (Gemini)',
+        description: 'Gemini models from Google',
+        endpoint: 'https://generativelanguage.googleapis.com/v1beta',
+        envVar: 'GOOGLE_API_KEY',
+        keyUrl: 'https://aistudio.google.com/apikey',
+        requiresKey: true,
+        category: 'primary',
+    },
+    // Local provider
+    ollama: {
+        type: 'ollama',
+        displayName: 'Ollama (local)',
+        description: 'Local models via Ollama',
+        endpoint: 'http://localhost:11434',
+        envVar: '',
+        keyUrl: 'https://ollama.ai',
+        requiresKey: false,
+        category: 'local',
+    },
+    // "Others" providers (OpenAI-compatible APIs)
+    together: {
+        type: 'together',
+        displayName: 'Together AI',
+        description: 'Fast inference, many open models',
+        endpoint: 'https://api.together.xyz/v1',
+        envVar: 'TOGETHER_API_KEY',
+        keyUrl: 'https://api.together.xyz/settings/api-keys',
+        requiresKey: true,
+        category: 'others',
+    },
+    groq: {
+        type: 'groq',
+        displayName: 'Groq',
+        description: 'Ultra-fast inference',
+        endpoint: 'https://api.groq.com/openai/v1',
+        envVar: 'GROQ_API_KEY',
+        keyUrl: 'https://console.groq.com/keys',
+        requiresKey: true,
+        category: 'others',
+    },
+    fireworks: {
+        type: 'fireworks',
+        displayName: 'Fireworks AI',
+        description: 'Fast inference, fine-tuned models',
+        endpoint: 'https://api.fireworks.ai/inference/v1',
+        envVar: 'FIREWORKS_API_KEY',
+        keyUrl: 'https://fireworks.ai/account/api-keys',
+        requiresKey: true,
+        category: 'others',
+    },
+    perplexity: {
+        type: 'perplexity',
+        displayName: 'Perplexity',
+        description: 'Search-augmented AI',
+        endpoint: 'https://api.perplexity.ai',
+        envVar: 'PERPLEXITY_API_KEY',
+        keyUrl: 'https://www.perplexity.ai/settings/api',
+        requiresKey: true,
+        category: 'others',
+    },
+    openrouter: {
+        type: 'openrouter',
+        displayName: 'OpenRouter',
+        description: 'Model aggregator (100+ models)',
+        endpoint: 'https://openrouter.ai/api/v1',
+        envVar: 'OPENROUTER_API_KEY',
+        keyUrl: 'https://openrouter.ai/keys',
+        requiresKey: true,
+        category: 'others',
+        notes: 'Access multiple providers with one API key',
+    },
+    custom: {
+        type: 'custom',
+        displayName: 'Custom Endpoint',
+        description: 'User-defined OpenAI-compatible endpoint',
+        endpoint: '', // User-provided
+        envVar: 'OPENAI_API_KEY', // Default to OpenAI format
+        keyUrl: '',
+        requiresKey: true,
+        category: 'others',
+        notes: 'Advanced: configure your own endpoint',
+    },
+};
+// =============================================================================
+// Curated Model Lists for "Others" Providers
+// =============================================================================
+/**
+ * Curated models for Together AI.
+ */
+export const TOGETHER_MODELS = [
+    {
+        id: 'meta-llama/Llama-3.2-8B-Instruct-Turbo',
+        displayName: 'Llama 3.2 8B Instruct',
+        description: 'Fast, low cost',
+        provider: 'together',
+        tier: 'fast',
+    },
+    {
+        id: 'meta-llama/Llama-3.2-70B-Instruct-Turbo',
+        displayName: 'Llama 3.2 70B Instruct',
+        description: 'Balanced',
+        provider: 'together',
+        tier: 'balanced',
+    },
+    {
+        id: 'deepseek-ai/DeepSeek-R1-Distill-Llama-70B',
+        displayName: 'DeepSeek R1 70B',
+        description: 'Most capable',
+        provider: 'together',
+        tier: 'powerful',
+    },
+];
+/**
+ * Curated models for Groq.
+ */
+export const GROQ_MODELS = [
+    {
+        id: 'llama-3.2-8b-instant',
+        displayName: 'Llama 3.2 8B',
+        description: 'Fast, low cost',
+        provider: 'groq',
+        tier: 'fast',
+    },
+    {
+        id: 'llama-3.2-70b-versatile',
+        displayName: 'Llama 3.2 70B',
+        description: 'Balanced',
+        provider: 'groq',
+        tier: 'balanced',
+    },
+    {
+        id: 'deepseek-r1-distill-llama-70b',
+        displayName: 'DeepSeek R1 70B',
+        description: 'Most capable',
+        provider: 'groq',
+        tier: 'powerful',
+    },
+];
+/**
+ * Curated models for Fireworks AI.
+ */
+export const FIREWORKS_MODELS = [
+    {
+        id: 'accounts/fireworks/models/llama-v3p2-8b-instruct',
+        displayName: 'Llama 3.2 8B',
+        description: 'Fast, low cost',
+        provider: 'fireworks',
+        tier: 'fast',
+    },
+    {
+        id: 'accounts/fireworks/models/llama-v3p2-70b-instruct',
+        displayName: 'Llama 3.2 70B',
+        description: 'Balanced',
+        provider: 'fireworks',
+        tier: 'balanced',
+    },
+    {
+        id: 'accounts/fireworks/models/deepseek-r1',
+        displayName: 'DeepSeek R1',
+        description: 'Most capable',
+        provider: 'fireworks',
+        tier: 'powerful',
+    },
+];
+/**
+ * Curated models for Perplexity.
+ */
+export const PERPLEXITY_MODELS = [
+    {
+        id: 'llama-3.1-sonar-small-128k-online',
+        displayName: 'Sonar Small',
+        description: 'Fast, low cost',
+        provider: 'perplexity',
+        tier: 'fast',
+    },
+    {
+        id: 'llama-3.1-sonar-large-128k-online',
+        displayName: 'Sonar Large',
+        description: 'Balanced',
+        provider: 'perplexity',
+        tier: 'balanced',
+    },
+    {
+        id: 'llama-3.1-sonar-huge-128k-online',
+        displayName: 'Sonar Huge',
+        description: 'Most capable',
+        provider: 'perplexity',
+        tier: 'powerful',
+    },
+];
+/**
+ * Curated models for OpenRouter.
+ */
+export const OPENROUTER_MODELS = [
+    {
+        id: 'meta-llama/llama-3.2-8b-instruct',
+        displayName: 'Llama 3.2 8B',
+        description: 'Fast, low cost',
+        provider: 'openrouter',
+        tier: 'fast',
+    },
+    {
+        id: 'anthropic/claude-3-5-sonnet',
+        displayName: 'Claude 3.5 Sonnet',
+        description: 'Balanced (via OpenRouter)',
+        provider: 'openrouter',
+        tier: 'balanced',
+    },
+    {
+        id: 'anthropic/claude-3-opus',
+        displayName: 'Claude 3 Opus',
+        description: 'Most capable (via OpenRouter)',
+        provider: 'openrouter',
+        tier: 'powerful',
+    },
+];
+// =============================================================================
+// Helper Functions
+// =============================================================================
+/**
+ * Get curated models for a specific "Others" provider.
+ */
+export function getModelsForOthersProvider(provider) {
+    switch (provider) {
+        case 'together':
+            return TOGETHER_MODELS;
+        case 'groq':
+            return GROQ_MODELS;
+        case 'fireworks':
+            return FIREWORKS_MODELS;
+        case 'perplexity':
+            return PERPLEXITY_MODELS;
+        case 'openrouter':
+            return OPENROUTER_MODELS;
+        default:
+            return [];
+    }
+}
+/**
+ * Get all "Others" providers (for UI listing).
+ */
+export function getOthersProviders() {
+    return Object.values(PROVIDER_METADATA).filter((p) => p.category === 'others' && p.type !== 'custom');
+}
+/**
+ * Get provider metadata by type.
+ */
+export function getProviderMetadata(provider) {
+    return PROVIDER_METADATA[provider];
+}
+/**
+ * Check if a provider is an "Others" provider.
+ */
+export function isOthersProvider(provider) {
+    return PROVIDER_METADATA[provider].category === 'others';
+}

package/dist/models/types.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Model Types — Shared types for the models module
+ */
+/**
+ * Model tier levels for role-based selection
+ */
+export type ModelTier = 'fast' | 'balanced' | 'powerful';
+/**
+ * All available tiers in order.
+ */
+export declare const MODEL_TIERS: ModelTier[];
+/**
+ * Check if a tier is valid.
+ */
+export declare function isValidTier(tier: string): tier is ModelTier;
+/**
+ * Provider-specific model mappings (tier -> model ID)
+ */
+export type ProviderModelMap = Record<ModelTier, string>;
+/**
+ * Tier info metadata
+ */
+export interface TierInfo {
+    label: string;
+    description: string;
+    shortDescription: string;
+}
+export declare const TIER_INFO: Record<ModelTier, TierInfo>;

package/dist/models/types.js

@@ -0,0 +1,30 @@
+/**
+ * Model Types — Shared types for the models module
+ */
+/**
+ * All available tiers in order.
+ */
+export const MODEL_TIERS = ['fast', 'balanced', 'powerful'];
+/**
+ * Check if a tier is valid.
+ */
+export function isValidTier(tier) {
+    return tier === 'fast' || tier === 'balanced' || tier === 'powerful';
+}
+export const TIER_INFO = {
+    fast: {
+        label: 'Fast',
+        description: 'Quick responses, lower cost - best for simple tasks',
+        shortDescription: 'Quick, low cost',
+    },
+    balanced: {
+        label: 'Balanced',
+        description: 'Good balance of speed and capability - recommended default',
+        shortDescription: 'Recommended',
+    },
+    powerful: {
+        label: 'Powerful',
+        description: 'Best reasoning and capability - for complex tasks',
+        shortDescription: 'Best reasoning',
+    },
+};

package/dist/models.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Model defaults and context window sizes
+ *
+ * This file maintains backward compatibility with the original SDK API.
+ * Internally, it delegates to the full model registry in ./models/.
+ */
+import type { ProviderType } from './config.js';
+/**
+ * Default model for each provider.
+ * Derived from MODEL_REGISTRY — uses the 'balanced' tier default for each provider.
+ */
+export declare const DEFAULT_MODELS: Record<ProviderType, string>;
+/**
+ * Default context window when model is unknown
+ */
+export declare const DEFAULT_CONTEXT_WINDOW = 128000;
+/**
+ * Get the context window size for a model.
+ * Delegates to the full registry with prefix-matching fallback.
+ */
+export declare function getContextWindow(model?: string): number;

package/dist/models.js

@@ -0,0 +1,73 @@
+/**
+ * Model defaults and context window sizes
+ *
+ * This file maintains backward compatibility with the original SDK API.
+ * Internally, it delegates to the full model registry in ./models/.
+ */
+import { getDefaultModelForTier, getModelContextWindow, MODEL_REGISTRY } from './models/index.js';
+/**
+ * Default model for each provider.
+ * Derived from MODEL_REGISTRY — uses the 'balanced' tier default for each provider.
+ */
+export const DEFAULT_MODELS = (() => {
+    const providers = [
+        'claude',
+        'openai',
+        'gemini',
+        'ollama',
+        'together',
+        'groq',
+        'fireworks',
+        'perplexity',
+        'openrouter',
+        'custom',
+    ];
+    const result = {};
+    for (const provider of providers) {
+        const balanced = getDefaultModelForTier(provider, 'balanced');
+        if (balanced) {
+            result[provider] = balanced.id;
+        }
+        else {
+            // Fallback: first supported model for this provider, or a sensible default
+            const firstModel = MODEL_REGISTRY.find((m) => m.provider === provider && m.status === 'supported');
+            result[provider] = firstModel?.id ?? 'gpt-4o';
+        }
+    }
+    return result;
+})();
+/**
+ * Default context window when model is unknown
+ */
+export const DEFAULT_CONTEXT_WINDOW = 128000;
+/**
+ * Get the context window size for a model.
+ * Delegates to the full registry with prefix-matching fallback.
+ */
+export function getContextWindow(model) {
+    if (!model) {
+        return DEFAULT_CONTEXT_WINDOW;
+    }
+    // Use the registry-backed implementation
+    const result = getModelContextWindow(model);
+    // getModelContextWindow returns the provider fallback (200000) for unknown models,
+    // but the original getContextWindow returned DEFAULT_CONTEXT_WINDOW (128000).
+    // Check if the model was actually found in the registry.
+    const inRegistry = MODEL_REGISTRY.some((m) => m.id === model);
+    if (inRegistry) {
+        return result;
+    }
+    // Prefix match against registry entries (e.g., new dated variant of known model)
+    for (const entry of MODEL_REGISTRY) {
+        if (!entry.contextWindow)
+            continue;
+        const parts = entry.id.split('-');
+        if (parts.length < 2)
+            continue;
+        const prefix = parts.slice(0, -1).join('-');
+        if (prefix && model.startsWith(prefix)) {
+            return entry.contextWindow;
+        }
+    }
+    return DEFAULT_CONTEXT_WINDOW;
+}

package/dist/presets/coding.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Coding preset — batteries-included for software development
+ */
+import type { Preset, AnyTool } from './types.js';
+/**
+ * All file operation tools
+ */
+export declare const fileTools: AnyTool[];
+/**
+ * All shell tools
+ */
+export declare const shellTools: AnyTool[];
+/**
+ * Web tools
+ */
+export declare const webTools: AnyTool[];
+/**
+ * Coding preset — full development environment
+ */
+export declare const codingPreset: Preset;
+export { webTools as codingWebTools };