@dexto/core 1.4.0 → 1.5.0

package/dist/llm/providers/local/types.d.ts

@@ -0,0 +1,219 @@
+/**
+ * Types for native local model support via node-llama-cpp and Ollama.
+ */
+/**
+ * GPU acceleration backends supported by node-llama-cpp.
+ * - metal: Apple Silicon (M1/M2/M3) via Metal API
+ * - cuda: NVIDIA GPUs via CUDA
+ * - vulkan: Cross-platform GPU acceleration
+ * - cpu: CPU-only execution (fallback)
+ */
+export type GPUBackend = 'metal' | 'cuda' | 'vulkan' | 'cpu';
+/**
+ * Common GGUF quantization types.
+ * Lower quantization = smaller file size, slightly lower quality.
+ * Q4_K_M is a good balance for most use cases.
+ */
+export type QuantizationType = 'Q2_K' | 'Q3_K_S' | 'Q3_K_M' | 'Q3_K_L' | 'Q4_0' | 'Q4_K_S' | 'Q4_K_M' | 'Q5_0' | 'Q5_K_S' | 'Q5_K_M' | 'Q6_K' | 'Q8_0' | 'F16' | 'F32';
+/**
+ * Categories for organizing local models in the UI.
+ */
+export type LocalModelCategory = 'general' | 'coding' | 'reasoning' | 'small' | 'vision';
+/**
+ * Model source - where the model can be downloaded from.
+ */
+export type ModelSource = 'huggingface' | 'ollama';
+/**
+ * Curated local model entry from the registry.
+ * These are pre-vetted models with known configurations.
+ */
+export interface LocalModelInfo {
+    /** Unique identifier (e.g., 'llama-3.3-8b-q4') */
+    id: string;
+    /** Human-readable display name */
+    name: string;
+    /** Short description of the model's capabilities */
+    description: string;
+    /** HuggingFace repository ID (e.g., 'bartowski/Llama-3.3-8B-Instruct-GGUF') */
+    huggingfaceId: string;
+    /** Filename of the GGUF file to download */
+    filename: string;
+    /** Quantization level */
+    quantization: QuantizationType;
+    /** Expected file size in bytes (for progress estimation) */
+    sizeBytes: number;
+    /** Maximum context window size in tokens */
+    contextLength: number;
+    /** Model categories for filtering */
+    categories: LocalModelCategory[];
+    /** Minimum VRAM required in GB (for GPU inference) */
+    minVRAM?: number;
+    /** Minimum RAM required in GB (for CPU inference) */
+    minRAM?: number;
+    /** Whether this model is recommended (featured in UI) */
+    recommended?: boolean;
+    /** Model author/organization */
+    author?: string;
+    /** License type (e.g., 'llama3.3', 'apache-2.0', 'mit') */
+    license?: string;
+    /** Whether model supports vision/images */
+    supportsVision?: boolean;
+    /** Whether model supports tool/function calling */
+    supportsTools?: boolean;
+}
+/**
+ * State of a model download.
+ */
+export type ModelDownloadStatus = 'pending' | 'downloading' | 'verifying' | 'complete' | 'error';
+/**
+ * Progress information for a model download.
+ * Emitted via events during download.
+ */
+export interface ModelDownloadProgress {
+    /** Model ID being downloaded */
+    modelId: string;
+    /** Current download status */
+    status: ModelDownloadStatus;
+    /** Bytes downloaded so far */
+    bytesDownloaded: number;
+    /** Total file size in bytes */
+    totalBytes: number;
+    /** Download progress as percentage (0-100) */
+    percentage: number;
+    /** Download speed in bytes per second */
+    speed?: number;
+    /** Estimated time remaining in seconds */
+    eta?: number;
+    /** Error message if status is 'error' */
+    error?: string;
+}
+/**
+ * GPU detection result.
+ */
+export interface GPUInfo {
+    /** Detected GPU backend */
+    backend: GPUBackend;
+    /** Whether GPU acceleration is available */
+    available: boolean;
+    /** GPU device name (e.g., 'Apple M2 Pro', 'NVIDIA RTX 4090') */
+    deviceName?: string;
+    /** Available VRAM in megabytes */
+    vramMB?: number;
+    /** GPU driver version */
+    driverVersion?: string;
+}
+/**
+ * Extended LLM configuration for local models.
+ * Extends the base config with local-specific options.
+ */
+export interface LocalLLMConfig {
+    /** Provider type */
+    provider: 'local' | 'ollama';
+    /** Model ID from local registry or custom GGUF path */
+    model: string;
+    /** Number of layers to offload to GPU (-1 = auto, 0 = CPU only) */
+    gpuLayers?: number;
+    /** Override context size (tokens) */
+    contextSize?: number;
+    /** Number of CPU threads to use */
+    threads?: number;
+    /** Inference batch size */
+    batchSize?: number;
+    /** Path to model file (resolved from model ID) */
+    modelPath?: string;
+}
+/**
+ * Installed model metadata (persisted to state file).
+ */
+export interface InstalledModel {
+    /** Model ID from registry */
+    id: string;
+    /** Absolute path to the .gguf file */
+    filePath: string;
+    /** File size in bytes */
+    sizeBytes: number;
+    /** When the model was downloaded (ISO timestamp) */
+    downloadedAt: string;
+    /** When the model was last used (ISO timestamp) */
+    lastUsedAt?: string;
+    /** SHA-256 hash of the file for integrity verification */
+    sha256?: string;
+    /** Source of the download */
+    source: ModelSource;
+}
+/**
+ * Model state manager state (persisted to ~/.dexto/models/state.json).
+ */
+export interface ModelState {
+    /** Schema version for migrations */
+    version: string;
+    /** Map of model ID to installed model info */
+    installed: Record<string, InstalledModel>;
+    /** Currently active/selected model ID */
+    activeModelId?: string;
+    /** Queue of model IDs pending download */
+    downloadQueue: string[];
+}
+/**
+ * Options for downloading a model.
+ */
+export interface ModelDownloadOptions {
+    /** Model ID to download */
+    modelId: string;
+    /** Directory to save the model (default: ~/.dexto/models/) */
+    outputDir?: string;
+    /** Whether to show CLI progress (default: true) */
+    showProgress?: boolean;
+    /** Callback for progress updates */
+    onProgress?: (progress: ModelDownloadProgress) => void;
+    /** HuggingFace token for gated models */
+    hfToken?: string;
+}
+/**
+ * Result of a model download operation.
+ */
+export interface ModelDownloadResult {
+    /** Whether download was successful */
+    success: boolean;
+    /** Path to the downloaded model file */
+    filePath?: string;
+    /** SHA-256 hash of the downloaded file */
+    sha256?: string;
+    /** Error message if download failed */
+    error?: string;
+}
+/**
+ * Ollama model info (from Ollama API /api/tags).
+ */
+export interface OllamaModelInfo {
+    /** Model name (e.g., 'llama3.3:8b') */
+    name: string;
+    /** Model size in bytes */
+    size: number;
+    /** Model digest/hash */
+    digest: string;
+    /** When the model was last modified */
+    modifiedAt: string;
+    /** Model details (parameters, family, etc.) */
+    details?: {
+        family?: string;
+        parameterSize?: string;
+        quantizationLevel?: string;
+    };
+}
+/**
+ * Ollama server status.
+ */
+export interface OllamaStatus {
+    /** Whether Ollama server is running */
+    running: boolean;
+    /** Ollama server URL */
+    url: string;
+    /** Ollama version */
+    version?: string;
+    /** Available models on the server */
+    models?: OllamaModelInfo[];
+    /** Error message if not running */
+    error?: string;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/llm/providers/local/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../../src/llm/providers/local/types.ts"],"names":[],"mappings":"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"}

package/dist/llm/providers/openrouter-model-registry.cjs

@@ -0,0 +1,350 @@
+"use strict";
+var __create = Object.create;
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(
+  // If the importer is in node compatibility mode or this is not an ESM
+  // file that has been converted to a CommonJS file using a Babel-
+  // compatible transform (i.e. "__esModule" has not been set), then set
+  // "default" to the CommonJS "module.exports" for node compatibility.
+  isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target,
+  mod
+));
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+var openrouter_model_registry_exports = {};
+__export(openrouter_model_registry_exports, {
+  __TEST_ONLY__: () => __TEST_ONLY__,
+  getCachedOpenRouterModels: () => getCachedOpenRouterModels,
+  getOpenRouterModelCacheInfo: () => getOpenRouterModelCacheInfo,
+  getOpenRouterModelContextLength: () => getOpenRouterModelContextLength,
+  getOpenRouterModelInfo: () => getOpenRouterModelInfo,
+  lookupOpenRouterModel: () => lookupOpenRouterModel,
+  openRouterModelRegistry: () => openRouterModelRegistry,
+  refreshOpenRouterModelCache: () => refreshOpenRouterModelCache,
+  scheduleOpenRouterModelRefresh: () => scheduleOpenRouterModelRefresh
+});
+module.exports = __toCommonJS(openrouter_model_registry_exports);
+var import_node_fs = require("node:fs");
+var import_node_fs2 = require("node:fs");
+var import_node_path = __toESM(require("node:path"), 1);
+var import_path = require("../../utils/path.js");
+var import_logger = require("../../logger/logger.js");
+const OPENROUTER_MODELS_ENDPOINT = "https://openrouter.ai/api/v1/models";
+const CACHE_FILENAME = "openrouter-models.json";
+const CACHE_SUBDIR = "cache";
+const CACHE_TTL_MS = 1e3 * 60 * 60 * 24;
+const MIN_REFRESH_INTERVAL_MS = 1e3 * 60 * 5;
+const DEFAULT_CONTEXT_LENGTH = 128e3;
+class OpenRouterModelRegistry {
+  constructor(cachePath2) {
+    this.cachePath = cachePath2;
+    this.loadCacheFromDisk();
+  }
+  /** Map from normalized model ID to model info */
+  models = null;
+  lastFetchedAt = null;
+  refreshPromise = null;
+  lastRefreshAttemptAt = null;
+  lastUsedApiKey;
+  /**
+   * Look up a model ID against the OpenRouter catalog.
+   * @returns 'valid' if model exists, 'invalid' if not found, 'unknown' if cache is stale/empty
+   */
+  lookup(modelId) {
+    const normalized = this.normalizeModelId(modelId);
+    if (!normalized) {
+      return "unknown";
+    }
+    if (!this.models || this.models.size === 0) {
+      this.scheduleRefresh({ force: true });
+      return "unknown";
+    }
+    if (!this.isCacheFresh()) {
+      this.scheduleRefresh();
+      return "unknown";
+    }
+    return this.models.has(normalized) ? "valid" : "invalid";
+  }
+  /**
+   * Get context length for a model ID.
+   * @returns context length if model is in cache, null if not found or cache is stale
+   */
+  getContextLength(modelId) {
+    const normalized = this.normalizeModelId(modelId);
+    if (!normalized) {
+      return null;
+    }
+    if (!this.models || this.models.size === 0 || !this.isCacheFresh()) {
+      return null;
+    }
+    const info = this.models.get(normalized);
+    return info?.contextLength ?? null;
+  }
+  /**
+   * Get model info for a model ID.
+   * @returns model info if found in cache, null otherwise
+   */
+  getModelInfo(modelId) {
+    const normalized = this.normalizeModelId(modelId);
+    if (!normalized) {
+      return null;
+    }
+    if (!this.models || this.models.size === 0 || !this.isCacheFresh()) {
+      return null;
+    }
+    return this.models.get(normalized) ?? null;
+  }
+  /**
+   * Schedule a non-blocking background refresh of the model cache.
+   */
+  scheduleRefresh(options) {
+    const apiKey = options?.apiKey ?? this.lastUsedApiKey;
+    if (apiKey) {
+      this.lastUsedApiKey = apiKey;
+    }
+    if (this.refreshPromise) {
+      return;
+    }
+    const now = Date.now();
+    if (!options?.force && this.lastRefreshAttemptAt && now - this.lastRefreshAttemptAt < MIN_REFRESH_INTERVAL_MS) {
+      return;
+    }
+    this.lastRefreshAttemptAt = now;
+    this.refreshPromise = this.refreshInternal(apiKey).catch((error) => {
+      import_logger.logger.warn(
+        `Failed to refresh OpenRouter model registry: ${error instanceof Error ? error.message : String(error)}`
+      );
+    }).finally(() => {
+      this.refreshPromise = null;
+    });
+  }
+  /**
+   * Blocking refresh of the model cache.
+   */
+  async refresh(options) {
+    const apiKey = options?.apiKey ?? this.lastUsedApiKey;
+    if (apiKey) {
+      this.lastUsedApiKey = apiKey;
+    }
+    if (!options?.force && this.refreshPromise) {
+      await this.refreshPromise;
+      return;
+    }
+    if (!options?.force) {
+      const now = Date.now();
+      if (this.lastRefreshAttemptAt && now - this.lastRefreshAttemptAt < MIN_REFRESH_INTERVAL_MS) {
+        if (this.refreshPromise) {
+          await this.refreshPromise;
+        }
+        return;
+      }
+      this.lastRefreshAttemptAt = now;
+    } else {
+      this.lastRefreshAttemptAt = Date.now();
+    }
+    const promise = this.refreshInternal(apiKey).finally(() => {
+      this.refreshPromise = null;
+    });
+    this.refreshPromise = promise;
+    await promise;
+  }
+  /**
+   * Get all cached model IDs (or null if cache is empty).
+   */
+  getCachedModels() {
+    if (!this.models || this.models.size === 0) {
+      return null;
+    }
+    return Array.from(this.models.keys());
+  }
+  /**
+   * Get all cached model info (or null if cache is empty).
+   */
+  getCachedModelsWithInfo() {
+    if (!this.models || this.models.size === 0) {
+      return null;
+    }
+    return Array.from(this.models.values());
+  }
+  /**
+   * Get cache metadata for debugging/monitoring.
+   */
+  getCacheMetadata() {
+    return {
+      lastFetchedAt: this.lastFetchedAt ? new Date(this.lastFetchedAt) : null,
+      modelCount: this.models ? this.models.size : 0,
+      isFresh: this.isCacheFresh()
+    };
+  }
+  async refreshInternal(apiKey) {
+    try {
+      const headers = {
+        Accept: "application/json"
+      };
+      if (apiKey) {
+        headers.Authorization = `Bearer ${apiKey}`;
+      }
+      import_logger.logger.debug("Refreshing OpenRouter model registry from remote source");
+      const response = await fetch(OPENROUTER_MODELS_ENDPOINT, { headers });
+      if (!response.ok) {
+        const body = await response.text();
+        throw new Error(`HTTP ${response.status}: ${body}`);
+      }
+      const payload = await response.json();
+      const models = this.extractModels(payload);
+      if (models.length === 0) {
+        throw new Error("No model identifiers returned by OpenRouter");
+      }
+      await this.writeCache(models);
+      import_logger.logger.info(`OpenRouter model registry refreshed with ${models.length} models`);
+    } catch (error) {
+      throw error instanceof Error ? error : new Error(String(error));
+    }
+  }
+  loadCacheFromDisk() {
+    if (!(0, import_node_fs2.existsSync)(this.cachePath)) {
+      return;
+    }
+    try {
+      const raw = (0, import_node_fs2.readFileSync)(this.cachePath, "utf-8");
+      const parsed = JSON.parse(raw);
+      if (!Array.isArray(parsed.models) || typeof parsed.fetchedAt !== "string") {
+        import_logger.logger.warn(`Invalid OpenRouter model cache structure at ${this.cachePath}`);
+        return;
+      }
+      this.models = /* @__PURE__ */ new Map();
+      for (const model of parsed.models) {
+        if (typeof model === "object" && model.id && typeof model.contextLength === "number") {
+          this.models.set(model.id.toLowerCase(), model);
+        }
+      }
+      const timestamp = Date.parse(parsed.fetchedAt);
+      this.lastFetchedAt = Number.isNaN(timestamp) ? null : timestamp;
+      import_logger.logger.debug(
+        `Loaded ${this.models.size} OpenRouter models from cache (fetched at ${parsed.fetchedAt})`
+      );
+    } catch (error) {
+      import_logger.logger.warn(
+        `Failed to load OpenRouter model cache: ${error instanceof Error ? error.message : String(error)}`
+      );
+    }
+  }
+  normalizeModelId(modelId) {
+    if (!modelId) {
+      return null;
+    }
+    return modelId.trim().toLowerCase();
+  }
+  isCacheFresh() {
+    if (!this.lastFetchedAt) {
+      return false;
+    }
+    return Date.now() - this.lastFetchedAt < CACHE_TTL_MS;
+  }
+  async writeCache(models) {
+    const modelMap = /* @__PURE__ */ new Map();
+    for (const model of models) {
+      if (model.id.trim()) {
+        modelMap.set(model.id.toLowerCase(), model);
+      }
+    }
+    const uniqueModels = Array.from(modelMap.values()).sort((a, b) => a.id.localeCompare(b.id));
+    await import_node_fs.promises.mkdir(import_node_path.default.dirname(this.cachePath), { recursive: true });
+    const now = /* @__PURE__ */ new Date();
+    const cachePayload = {
+      fetchedAt: now.toISOString(),
+      models: uniqueModels
+    };
+    await import_node_fs.promises.writeFile(this.cachePath, JSON.stringify(cachePayload, null, 2), "utf-8");
+    this.models = new Map(uniqueModels.map((m) => [m.id.toLowerCase(), m]));
+    this.lastFetchedAt = now.getTime();
+  }
+  extractModels(payload) {
+    if (!payload) {
+      return [];
+    }
+    const raw = payload.data ?? payload.models ?? payload;
+    if (!Array.isArray(raw)) {
+      return [];
+    }
+    const models = [];
+    for (const item of raw) {
+      if (item && typeof item === "object") {
+        const record = item;
+        const id = this.firstString([record.id, record.model, record.name]);
+        if (id) {
+          let contextLength = DEFAULT_CONTEXT_LENGTH;
+          if (typeof record.context_length === "number") {
+            contextLength = record.context_length;
+          } else if (record.top_provider && typeof record.top_provider === "object" && typeof record.top_provider.context_length === "number") {
+            contextLength = record.top_provider.context_length;
+          }
+          models.push({ id, contextLength });
+        }
+      }
+    }
+    return models;
+  }
+  firstString(values) {
+    for (const value of values) {
+      if (typeof value === "string" && value.trim().length > 0) {
+        return value;
+      }
+    }
+    return null;
+  }
+}
+const cachePath = (0, import_path.getDextoGlobalPath)(CACHE_SUBDIR, CACHE_FILENAME);
+const openRouterModelRegistry = new OpenRouterModelRegistry(cachePath);
+function lookupOpenRouterModel(modelId) {
+  return openRouterModelRegistry.lookup(modelId);
+}
+function scheduleOpenRouterModelRefresh(options) {
+  openRouterModelRegistry.scheduleRefresh(options);
+}
+async function refreshOpenRouterModelCache(options) {
+  await openRouterModelRegistry.refresh(options);
+}
+function getCachedOpenRouterModels() {
+  return openRouterModelRegistry.getCachedModels();
+}
+function getOpenRouterModelContextLength(modelId) {
+  return openRouterModelRegistry.getContextLength(modelId);
+}
+function getOpenRouterModelInfo(modelId) {
+  return openRouterModelRegistry.getModelInfo(modelId);
+}
+function getOpenRouterModelCacheInfo() {
+  return openRouterModelRegistry.getCacheMetadata();
+}
+const __TEST_ONLY__ = {
+  cachePath,
+  CACHE_TTL_MS
+};
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  __TEST_ONLY__,
+  getCachedOpenRouterModels,
+  getOpenRouterModelCacheInfo,
+  getOpenRouterModelContextLength,
+  getOpenRouterModelInfo,
+  lookupOpenRouterModel,
+  openRouterModelRegistry,
+  refreshOpenRouterModelCache,
+  scheduleOpenRouterModelRefresh
+});

package/dist/llm/providers/openrouter-model-registry.d.ts

@@ -0,0 +1,120 @@
+/**
+ * OpenRouter Model Registry
+ *
+ * Provides dynamic model validation against OpenRouter's catalog of 100+ models.
+ * Fetches and caches the model list from OpenRouter's API with a 24-hour TTL.
+ *
+ * Features:
+ * - Lazy loading: Cache is populated on first lookup
+ * - Background refresh: Non-blocking cache updates
+ * - Graceful degradation: Returns 'unknown' when cache is stale, allowing config
+ * - Throttled requests: Max 1 refresh per 5 minutes to avoid rate limits
+ */
+export type LookupStatus = 'valid' | 'invalid' | 'unknown';
+/** Model info stored in cache */
+export interface OpenRouterModelInfo {
+    id: string;
+    contextLength: number;
+}
+interface RefreshOptions {
+    apiKey?: string;
+    force?: boolean;
+}
+declare class OpenRouterModelRegistry {
+    private readonly cachePath;
+    /** Map from normalized model ID to model info */
+    private models;
+    private lastFetchedAt;
+    private refreshPromise;
+    private lastRefreshAttemptAt;
+    private lastUsedApiKey?;
+    constructor(cachePath: string);
+    /**
+     * Look up a model ID against the OpenRouter catalog.
+     * @returns 'valid' if model exists, 'invalid' if not found, 'unknown' if cache is stale/empty
+     */
+    lookup(modelId: string): LookupStatus;
+    /**
+     * Get context length for a model ID.
+     * @returns context length if model is in cache, null if not found or cache is stale
+     */
+    getContextLength(modelId: string): number | null;
+    /**
+     * Get model info for a model ID.
+     * @returns model info if found in cache, null otherwise
+     */
+    getModelInfo(modelId: string): OpenRouterModelInfo | null;
+    /**
+     * Schedule a non-blocking background refresh of the model cache.
+     */
+    scheduleRefresh(options?: RefreshOptions): void;
+    /**
+     * Blocking refresh of the model cache.
+     */
+    refresh(options?: RefreshOptions): Promise<void>;
+    /**
+     * Get all cached model IDs (or null if cache is empty).
+     */
+    getCachedModels(): string[] | null;
+    /**
+     * Get all cached model info (or null if cache is empty).
+     */
+    getCachedModelsWithInfo(): OpenRouterModelInfo[] | null;
+    /**
+     * Get cache metadata for debugging/monitoring.
+     */
+    getCacheMetadata(): {
+        lastFetchedAt: Date | null;
+        modelCount: number;
+        isFresh: boolean;
+    };
+    private refreshInternal;
+    private loadCacheFromDisk;
+    private normalizeModelId;
+    private isCacheFresh;
+    private writeCache;
+    private extractModels;
+    private firstString;
+}
+export declare const openRouterModelRegistry: OpenRouterModelRegistry;
+/**
+ * Look up a model ID against the OpenRouter catalog.
+ * @returns 'valid' if model exists, 'invalid' if not found, 'unknown' if cache is stale/empty
+ */
+export declare function lookupOpenRouterModel(modelId: string): LookupStatus;
+/**
+ * Schedule a non-blocking background refresh of the OpenRouter model cache.
+ */
+export declare function scheduleOpenRouterModelRefresh(options?: RefreshOptions): void;
+/**
+ * Perform a blocking refresh of the OpenRouter model cache.
+ */
+export declare function refreshOpenRouterModelCache(options?: RefreshOptions): Promise<void>;
+/**
+ * Get all cached OpenRouter model IDs (or null if cache is empty).
+ */
+export declare function getCachedOpenRouterModels(): string[] | null;
+/**
+ * Get context length for an OpenRouter model.
+ * @returns context length if model is in cache, null if not found or cache is stale
+ */
+export declare function getOpenRouterModelContextLength(modelId: string): number | null;
+/**
+ * Get model info for an OpenRouter model.
+ * @returns model info if found in cache, null otherwise
+ */
+export declare function getOpenRouterModelInfo(modelId: string): OpenRouterModelInfo | null;
+/**
+ * Get cache metadata for debugging/monitoring.
+ */
+export declare function getOpenRouterModelCacheInfo(): {
+    lastFetchedAt: Date | null;
+    modelCount: number;
+    isFresh: boolean;
+};
+export declare const __TEST_ONLY__: {
+    cachePath: string;
+    CACHE_TTL_MS: number;
+};
+export {};
+//# sourceMappingURL=openrouter-model-registry.d.ts.map