@build-astron-co/nimbus 0.4.1 → 0.4.3

package/src/llm/circuit-breaker.ts

@@ -1,140 +0,0 @@
-/**
- * Provider Circuit Breaker
- *
- * Prevents cascading failures by tracking consecutive errors per provider.
- * When a provider fails too many times in a row, its circuit "opens" and
- * requests are skipped until a cooldown period elapses. After cooldown the
- * circuit enters HALF_OPEN, allowing a single probe request to determine
- * whether the provider has recovered.
- *
- * States:
- *   CLOSED    → normal operation (all requests pass through)
- *   OPEN      → provider is failing; skip until cooldown expires
- *   HALF_OPEN → cooldown elapsed; allow one probe request
- */
-
-export type CircuitState = 'CLOSED' | 'OPEN' | 'HALF_OPEN';
-
-interface ProviderCircuit {
-  state: CircuitState;
-  failures: number;
-  lastFailure: number;
-}
-
-const DEFAULT_FAILURE_THRESHOLD = 5;
-const DEFAULT_COOLDOWN_MS = 60_000; // 60 seconds
-
-export class ProviderCircuitBreaker {
-  private circuits: Map<string, ProviderCircuit> = new Map();
-  private failureThreshold: number;
-  private cooldownMs: number;
-
-  constructor(opts?: { failureThreshold?: number; cooldownMs?: number }) {
-    this.failureThreshold = opts?.failureThreshold ?? DEFAULT_FAILURE_THRESHOLD;
-    this.cooldownMs = opts?.cooldownMs ?? DEFAULT_COOLDOWN_MS;
-  }
-
-  /**
-   * Check whether a provider is available for requests.
-   * Returns false only when the circuit is OPEN and cooldown hasn't elapsed.
-   */
-  isAvailable(provider: string): boolean {
-    const circuit = this.circuits.get(provider);
-    if (!circuit) {
-      return true;
-    }
-
-    if (circuit.state === 'CLOSED') {
-      return true;
-    }
-
-    if (circuit.state === 'OPEN') {
-      const elapsed = Date.now() - circuit.lastFailure;
-      if (elapsed >= this.cooldownMs) {
-        // Transition to HALF_OPEN: allow a single probe
-        circuit.state = 'HALF_OPEN';
-        return true;
-      }
-      return false;
-    }
-
-    // HALF_OPEN: allow probe
-    return true;
-  }
-
-  /**
-   * Record a successful request. Resets the circuit to CLOSED.
-   */
-  recordSuccess(provider: string): void {
-    const circuit = this.circuits.get(provider);
-    if (circuit) {
-      circuit.state = 'CLOSED';
-      circuit.failures = 0;
-    }
-  }
-
-  /**
-   * Record a failed request. Increments the failure counter and may
-   * open the circuit if the threshold is exceeded.
-   */
-  recordFailure(provider: string): void {
-    let circuit = this.circuits.get(provider);
-    if (!circuit) {
-      circuit = { state: 'CLOSED', failures: 0, lastFailure: 0 };
-      this.circuits.set(provider, circuit);
-    }
-
-    circuit.failures++;
-    circuit.lastFailure = Date.now();
-
-    if (circuit.failures >= this.failureThreshold && circuit.state !== 'OPEN') {
-      circuit.state = 'OPEN';
-      // Emit a visible warning when a provider circuit opens
-      if (process.stderr.isTTY) {
-        process.stderr.write(
-          `\x1b[33m  Warning: Provider '${provider}' disabled after ${this.failureThreshold} consecutive failures. Will retry in ${Math.round(this.cooldownMs / 1000)}s.\x1b[0m\n`
-        );
-      }
-    } else if (circuit.failures >= this.failureThreshold) {
-      circuit.state = 'OPEN';
-    }
-  }
-
-  /**
-   * Get the current state of a provider's circuit.
-   */
-  getState(provider: string): CircuitState {
-    return this.circuits.get(provider)?.state ?? 'CLOSED';
-  }
-
-  /**
-   * Reset a specific provider's circuit (e.g., after manual recovery).
-   */
-  reset(provider: string): void {
-    this.circuits.delete(provider);
-  }
-
-  /**
-   * Reset all circuits.
-   */
-  resetAll(): void {
-    this.circuits.clear();
-  }
-
-  /**
-   * Get the names of all providers whose circuits are currently OPEN.
-   * Useful for surfacing circuit breaker state in the TUI.
-   */
-  getOpenCircuits(): string[] {
-    const open: string[] = [];
-    for (const [name, circuit] of this.circuits) {
-      if (circuit.state === 'OPEN') {
-        const elapsed = Date.now() - circuit.lastFailure;
-        if (elapsed < this.cooldownMs) {
-          open.push(name);
-        }
-      }
-    }
-    return open;
-  }
-}

package/src/llm/config-loader.ts

@@ -1,201 +0,0 @@
-/**
- * LLM Config Loader
- *
- * Reads ~/.nimbus/config.yaml and maps LLM-related settings
- * to RouterConfig for the LLM Router.
- */
-
-import * as fs from 'fs';
-import * as path from 'path';
-import * as os from 'os';
-import { logger } from '../utils';
-import type { RouterConfig } from './router';
-
-/**
- * Load LLM configuration from ~/.nimbus/config.yaml
- * Returns a Partial<RouterConfig> that can be passed to LLMRouter constructor
- */
-export function loadLLMConfig(): Partial<RouterConfig> {
-  const configPath =
-    process.env.NIMBUS_CONFIG_PATH || path.join(os.homedir(), '.nimbus', 'config.yaml');
-
-  if (!fs.existsSync(configPath)) {
-    logger.info(`No config file found at ${configPath}, using defaults`);
-    return {};
-  }
-
-  try {
-    const content = fs.readFileSync(configPath, 'utf-8');
-    const parsed = parseSimpleYaml(content);
-    const llmSection = parsed.llm || {};
-
-    const config: Partial<RouterConfig> = {};
-
-    // Map default provider
-    if (llmSection.default_provider) {
-      config.defaultProvider = llmSection.default_provider;
-    }
-
-    // Map default model
-    if (llmSection.defaultModel) {
-      config.defaultModel = llmSection.defaultModel;
-    }
-
-    // Map cost optimization settings
-    const costOpt = llmSection.cost_optimization;
-    if (costOpt) {
-      config.costOptimization = {
-        enabled: costOpt.enabled ?? false,
-        cheapModel: costOpt.cheap_model || '',
-        expensiveModel: costOpt.expensive_model || '',
-        cheapModelFor: costOpt.use_cheap_model_for || [],
-        expensiveModelFor: costOpt.use_expensive_model_for || [],
-      };
-    }
-
-    // Map fallback settings
-    const fallback = llmSection.fallback;
-    if (fallback) {
-      config.fallback = {
-        enabled: fallback.enabled ?? true,
-        providers: fallback.providers || [],
-      };
-    }
-
-    // Map token budget
-    if (llmSection.maxTokens) {
-      config.tokenBudget = {
-        maxTokensPerRequest: llmSection.maxTokens,
-      };
-    }
-
-    logger.info(`Loaded LLM config from ${configPath}`);
-    return config;
-  } catch (error: any) {
-    logger.warn(`Failed to load LLM config from ${configPath}: ${error.message}`);
-    return {};
-  }
-}
-
-/**
- * Minimal YAML parser for flat/nested key-value configs.
- * Handles the subset of YAML used by Nimbus config files.
- */
-function parseSimpleYaml(content: string): Record<string, any> {
-  const result: Record<string, any> = {};
-  const lines = content.split('\n');
-  // Stack tracks: indent level, the parent object, and the last key set on that object
-  const stack: { indent: number; obj: Record<string, any>; lastKey?: string }[] = [
-    { indent: -1, obj: result },
-  ];
-
-  for (const rawLine of lines) {
-    // Skip comments and empty lines
-    const commentIdx = rawLine.indexOf('#');
-    const line = commentIdx >= 0 ? rawLine.slice(0, commentIdx) : rawLine;
-    if (line.trim() === '') {
-      continue;
-    }
-
-    const indent = line.length - line.trimStart().length;
-    const trimmed = line.trim();
-
-    // Handle list items (- value)
-    if (trimmed.startsWith('- ')) {
-      const listValue = trimmed.slice(2).trim();
-      // Pop stack to find the owner of the list key.
-      // If we're inside an empty object created by "key:" with no value,
-      // pop past it to find the frame that owns the key.
-      while (stack.length > 1 && stack[stack.length - 1].indent >= indent) {
-        stack.pop();
-      }
-      // If the current frame has no lastKey, it's a placeholder empty object --
-      // pop one more to reach the frame that holds the actual key reference.
-      let frame = stack[stack.length - 1];
-      if (!frame.lastKey && stack.length > 1) {
-        stack.pop();
-        frame = stack[stack.length - 1];
-      }
-      const parentObj = frame.obj;
-      const lastKey = frame.lastKey;
-      if (lastKey) {
-        if (!Array.isArray(parentObj[lastKey])) {
-          parentObj[lastKey] = [];
-        }
-        parentObj[lastKey].push(parseYamlValue(listValue));
-      }
-      continue;
-    }
-
-    // Handle key: value pairs
-    const colonIdx = trimmed.indexOf(':');
-    if (colonIdx === -1) {
-      continue;
-    }
-
-    const key = trimmed.slice(0, colonIdx).trim();
-    const rawValue = trimmed.slice(colonIdx + 1).trim();
-
-    // Pop stack to find parent at correct indent level
-    while (stack.length > 1 && stack[stack.length - 1].indent >= indent) {
-      stack.pop();
-    }
-
-    const frame = stack[stack.length - 1];
-    const current = frame.obj;
-
-    if (rawValue === '' || rawValue === undefined) {
-      // Nested object (or potentially a list -- will be converted if list items follow)
-      current[key] = {};
-      frame.lastKey = key;
-      stack.push({ indent, obj: current[key] });
-    } else {
-      current[key] = parseYamlValue(rawValue);
-      frame.lastKey = key;
-    }
-  }
-
-  return result;
-}
-
-/**
- * Parse a YAML scalar value
- */
-function parseYamlValue(value: string): any {
-  // Remove surrounding quotes
-  if (
-    (value.startsWith('"') && value.endsWith('"')) ||
-    (value.startsWith("'") && value.endsWith("'"))
-  ) {
-    return value.slice(1, -1);
-  }
-
-  // Boolean
-  if (value === 'true') {
-    return true;
-  }
-  if (value === 'false') {
-    return false;
-  }
-
-  // Null
-  if (value === 'null' || value === '~') {
-    return null;
-  }
-
-  // Number
-  const num = Number(value);
-  if (!isNaN(num) && value !== '') {
-    return num;
-  }
-
-  // Inline list [a, b, c]
-  if (value.startsWith('[') && value.endsWith(']')) {
-    return value
-      .slice(1, -1)
-      .split(',')
-      .map(v => parseYamlValue(v.trim()));
-  }
-
-  return value;
-}

package/src/llm/cost-calculator.ts

@@ -1,171 +0,0 @@
-/**
- * Per-request cost calculation for LLM providers
- *
- * Pricing data is based on published rates from each provider.
- * Prices are per 1K tokens (input / output).
- * Ollama models are local and free.
- * Unknown models return 0 cost with a warning log.
- */
-
-import { logger } from '../utils';
-
-export interface CostBreakdown {
-  /** Input token cost in USD */
-  input: number;
-  /** Output token cost in USD */
-  output: number;
-}
-
-export interface CostResult {
-  /** Total cost in USD */
-  costUSD: number;
-  /** Per-component breakdown */
-  breakdown: CostBreakdown;
-}
-
-/**
- * Pricing entry: [inputPricePer1K, outputPricePer1K] in USD
- */
-type PricingEntry = [input: number, output: number];
-
-/**
- * Pricing data by provider and model.
- * Prices are in USD per 1,000 tokens.
- */
-const PRICING: Record<string, Record<string, PricingEntry>> = {
-  anthropic: {
-    // Claude 4 family
-    'claude-4-opus': [0.015, 0.075],
-    'claude-opus-4-20250514': [0.015, 0.075],
-    'claude-4-sonnet': [0.003, 0.015],
-    'claude-sonnet-4-20250514': [0.003, 0.015],
-    'claude-4-haiku': [0.0008, 0.004],
-    'claude-haiku-4-20250514': [0.0008, 0.004],
-    // Claude 3.5 family
-    'claude-3.5-sonnet': [0.003, 0.015],
-    'claude-3-5-sonnet-20241022': [0.003, 0.015],
-    'claude-3.5-haiku': [0.0008, 0.004],
-    'claude-3-5-haiku-20241022': [0.0008, 0.004],
-    // Claude 3 family
-    'claude-3-opus': [0.015, 0.075],
-    'claude-3-opus-20240229': [0.015, 0.075],
-    'claude-3-haiku': [0.00025, 0.00125],
-    'claude-3-haiku-20240307': [0.00025, 0.00125],
-  },
-  openai: {
-    'gpt-4': [0.03, 0.06],
-    'gpt-4-turbo': [0.01, 0.03],
-    'gpt-4-turbo-2024-04-09': [0.01, 0.03],
-    'gpt-4o': [0.005, 0.015],
-    'gpt-4o-2024-11-20': [0.005, 0.015],
-    'gpt-4o-mini': [0.00015, 0.0006],
-    'gpt-4o-mini-2024-07-18': [0.00015, 0.0006],
-    'gpt-3.5-turbo': [0.0005, 0.0015],
-  },
-  google: {
-    'gemini-pro': [0.00025, 0.0005],
-    'gemini-1.5-pro': [0.00125, 0.005],
-    'gemini-1.5-flash': [0.000075, 0.0003],
-    'gemini-2.0-flash-exp': [0.000075, 0.0003],
-  },
-  ollama: {
-    // All local models are free
-  },
-  groq: {
-    'llama-3.1-70b-versatile': [0.00059, 0.00079],
-    'llama-3.1-8b-instant': [0.00005, 0.00008],
-    'llama-3.3-70b-versatile': [0.00059, 0.00079],
-    'mixtral-8x7b-32768': [0.00024, 0.00024],
-    'gemma2-9b-it': [0.0002, 0.0002],
-  },
-  together: {
-    'meta-llama/Llama-3.1-70B-Instruct-Turbo': [0.00088, 0.00088],
-    'meta-llama/Llama-3.1-8B-Instruct-Turbo': [0.00018, 0.00018],
-    'meta-llama/Llama-3.3-70B-Instruct-Turbo': [0.00088, 0.00088],
-    'mistralai/Mixtral-8x22B-Instruct-v0.1': [0.0012, 0.0012],
-    'Qwen/Qwen2.5-72B-Instruct-Turbo': [0.0012, 0.0012],
-  },
-  deepseek: {
-    'deepseek-chat': [0.00014, 0.00028],
-    'deepseek-coder': [0.00014, 0.00028],
-    'deepseek-reasoner': [0.00055, 0.00219],
-  },
-  fireworks: {
-    'accounts/fireworks/models/llama-v3p1-70b-instruct': [0.0009, 0.0009],
-    'accounts/fireworks/models/llama-v3p1-8b-instruct': [0.0002, 0.0002],
-    'accounts/fireworks/models/mixtral-8x22b-instruct': [0.0009, 0.0009],
-    'accounts/fireworks/models/qwen2p5-72b-instruct': [0.0009, 0.0009],
-  },
-  perplexity: {
-    'llama-3.1-sonar-large-128k-online': [0.001, 0.001],
-    'llama-3.1-sonar-small-128k-online': [0.0002, 0.0002],
-    'llama-3.1-sonar-huge-128k-online': [0.005, 0.005],
-  },
-  openrouter: {
-    // OpenRouter models use provider/model format; prices approximate the underlying provider
-    'anthropic/claude-sonnet-4-20250514': [0.003, 0.015],
-    'anthropic/claude-haiku-4-20250514': [0.0008, 0.004],
-    'anthropic/claude-opus-4-20250514': [0.015, 0.075],
-    'anthropic/claude-3.5-sonnet': [0.003, 0.015],
-    'openai/gpt-4o': [0.005, 0.015],
-    'openai/gpt-4o-mini': [0.00015, 0.0006],
-    'google/gemini-2.0-flash-exp': [0.000075, 0.0003],
-    'meta-llama/llama-3.1-405b-instruct': [0.003, 0.003],
-    'meta-llama/llama-3.1-70b-instruct': [0.0008, 0.0008],
-    'mistralai/mixtral-8x22b-instruct': [0.0009, 0.0009],
-  },
-};
-
-/**
- * Calculate the cost for a single LLM request.
- *
- * @param provider  - Provider name (e.g. "anthropic", "openai", "google", "ollama", "openrouter")
- * @param model     - Model identifier (e.g. "claude-sonnet-4-20250514", "gpt-4o")
- * @param inputTokens  - Number of input/prompt tokens
- * @param outputTokens - Number of output/completion tokens
- * @returns Cost result with total USD cost and per-component breakdown
- */
-export function calculateCost(
-  provider: string,
-  model: string,
-  inputTokens: number,
-  outputTokens: number
-): CostResult {
-  // Ollama is always free
-  if (provider === 'ollama') {
-    return { costUSD: 0, breakdown: { input: 0, output: 0 } };
-  }
-
-  const providerPricing = PRICING[provider];
-  if (!providerPricing) {
-    logger.debug(`No pricing data for provider "${provider}", returning zero cost`);
-    return { costUSD: 0, breakdown: { input: 0, output: 0 } };
-  }
-
-  const entry = providerPricing[model];
-  if (!entry) {
-    logger.debug(
-      `No pricing data for model "${model}" on provider "${provider}", returning zero cost`
-    );
-    return { costUSD: 0, breakdown: { input: 0, output: 0 } };
-  }
-
-  const [inputPricePer1K, outputPricePer1K] = entry;
-  const inputCost = (inputTokens / 1000) * inputPricePer1K;
-  const outputCost = (outputTokens / 1000) * outputPricePer1K;
-
-  return {
-    costUSD: inputCost + outputCost,
-    breakdown: {
-      input: inputCost,
-      output: outputCost,
-    },
-  };
-}
-
-/**
- * Get available pricing data (useful for debugging / admin endpoints).
- */
-export function getPricingData(): Record<string, Record<string, PricingEntry>> {
-  return PRICING;
-}

package/src/llm/index.ts

@@ -1,8 +0,0 @@
-export { LLMRouter } from './router';
-export type { RouterConfig, ProviderInfo, StreamFallbackMeta } from './router';
-export * from './types';
-export { calculateCost } from './cost-calculator';
-export { loadLLMConfig } from './config-loader';
-export { resolveModelAlias, stripProviderPrefix } from './model-aliases';
-export { detectProvider } from './provider-registry';
-export * from './auth-bridge';

package/src/llm/model-aliases.ts

@@ -1,115 +0,0 @@
-/**
- * Model alias resolution
- * Maps short names to full model identifiers
- */
-
-const MODEL_ALIASES: Record<string, string> = {
-  // Anthropic shortcuts
-  sonnet: 'claude-sonnet-4-20250514',
-  haiku: 'claude-haiku-4-20250514',
-  opus: 'claude-opus-4-20250514',
-  claude: 'claude-sonnet-4-20250514',
-
-  // OpenAI shortcuts
-  gpt4: 'gpt-4o',
-  gpt4o: 'gpt-4o',
-  gpt4mini: 'gpt-4o-mini',
-  '4o': 'gpt-4o',
-  '4o-mini': 'gpt-4o-mini',
-
-  // Google shortcuts
-  gemini: 'gemini-2.0-flash-exp',
-  'gemini-flash': 'gemini-2.0-flash-exp',
-  'gemini-pro': 'gemini-1.5-pro',
-
-  // Groq shortcuts
-  groq: 'llama-3.1-70b-versatile',
-  'groq-fast': 'llama-3.1-8b-instant',
-
-  // Together shortcuts
-  together: 'meta-llama/Llama-3.1-70B-Instruct-Turbo',
-  'together-llama': 'meta-llama/Llama-3.1-70B-Instruct-Turbo',
-
-  // DeepSeek shortcuts
-  deepseek: 'deepseek-chat',
-  'deepseek-coder': 'deepseek-coder',
-  'deepseek-r1': 'deepseek-reasoner',
-
-  // Fireworks shortcuts
-  fireworks: 'accounts/fireworks/models/llama-v3p1-70b-instruct',
-
-  // Perplexity shortcuts
-  perplexity: 'llama-3.1-sonar-large-128k-online',
-  pplx: 'llama-3.1-sonar-large-128k-online',
-  sonar: 'llama-3.1-sonar-large-128k-online',
-
-  // Local shortcuts
-  llama: 'llama3.2',
-  mistral: 'mistral',
-  codellama: 'codellama',
-};
-
-/**
- * Resolve a model alias to its full model identifier.
- * Returns the original string if no alias match is found.
- *
- * @param modelOrAlias - Short alias or full model identifier
- * @returns Resolved full model identifier
- */
-export function resolveModelAlias(modelOrAlias: string): string {
-  return MODEL_ALIASES[modelOrAlias.toLowerCase()] || modelOrAlias;
-}
-
-/**
- * Strip a "provider/" prefix from a model string.
- *
- * Model strings can be specified as "provider/model" (e.g., "anthropic/claude-sonnet-4-20250514").
- * The provider prefix is used for routing but must be stripped before sending to the
- * provider's API, which expects just the model ID (e.g., "claude-sonnet-4-20250514").
- *
- * Preserves multi-segment model IDs used by OpenRouter (e.g., "meta-llama/llama-3.1-405b")
- * and Fireworks (e.g., "accounts/fireworks/models/llama-v3p3-70b-instruct") by only
- * stripping prefixes that match known provider names.
- *
- * @param model - Model string, optionally with provider prefix
- * @returns Model string with provider prefix removed
- */
-export function stripProviderPrefix(model: string): string {
-  if (!model.includes('/')) {
-    return model;
-  }
-
-  const slashIndex = model.indexOf('/');
-  const prefix = model.slice(0, slashIndex).toLowerCase();
-
-  // Only strip if the prefix is a known provider name.
-  // This preserves OpenRouter-style "meta-llama/llama-3.1-405b" and
-  // Fireworks-style "accounts/fireworks/models/..." paths.
-  const KNOWN_PROVIDERS = new Set([
-    'anthropic',
-    'openai',
-    'google',
-    'ollama',
-    'groq',
-    'together',
-    'deepseek',
-    'fireworks',
-    'perplexity',
-    'bedrock',
-  ]);
-
-  if (KNOWN_PROVIDERS.has(prefix)) {
-    return model.slice(slashIndex + 1);
-  }
-
-  return model;
-}
-
-/**
- * Get a copy of all registered model aliases.
- *
- * @returns Record mapping alias names to full model identifiers
- */
-export function getAliases(): Record<string, string> {
-  return { ...MODEL_ALIASES };
-}

package/src/llm/provider-registry.ts

@@ -1,63 +0,0 @@
-/**
- * Provider Registry
- * Auto-detects the provider from a model string
- */
-
-/**
- * Map of known provider prefixes used in "provider/model" format
- */
-const PROVIDER_MAP: Record<string, string> = {
-  anthropic: 'anthropic',
-  openai: 'openai',
-  google: 'google',
-  'meta-llama': 'openrouter',
-  mistralai: 'openrouter',
-  groq: 'groq',
-  together: 'together',
-  deepseek: 'deepseek',
-  fireworks: 'fireworks',
-  perplexity: 'perplexity',
-};
-
-/**
- * Detect the provider for a given model string.
- *
- * Detection strategy:
- * 1. Explicit provider prefix (e.g., "groq/llama-3.1-70b") -- split on "/" and look up prefix
- * 2. Model name pattern matching (e.g., "claude-*" -> anthropic, "gpt-*" -> openai)
- * 3. Default to "anthropic" if no pattern matches
- *
- * @param model - Model identifier, optionally prefixed with "provider/"
- * @returns Detected provider name
- */
-export function detectProvider(model: string): string {
-  // Explicit provider prefix (e.g., "groq/llama-3.1-70b")
-  if (model.includes('/')) {
-    const prefix = model.split('/')[0].toLowerCase();
-    return PROVIDER_MAP[prefix] || 'openrouter';
-  }
-
-  // Model name pattern matching
-  if (model.startsWith('claude')) {
-    return 'anthropic';
-  }
-  if (model.startsWith('gpt')) {
-    return 'openai';
-  }
-  if (model.startsWith('gemini')) {
-    return 'google';
-  }
-  if (
-    model.startsWith('llama') ||
-    model.startsWith('mistral') ||
-    model.startsWith('codellama') ||
-    model.startsWith('phi')
-  ) {
-    return 'ollama';
-  }
-  if (model.startsWith('deepseek')) {
-    return 'deepseek';
-  }
-
-  return 'anthropic'; // default
-}