@gmickel/gno 0.3.0

package/src/llm/cache.ts

@@ -0,0 +1,467 @@
+/**
+ * Model cache resolver.
+ * Handles hf: URI parsing and model cache management.
+ *
+ * @module src/llm/cache
+ */
+
+import { mkdir, readFile, rm, stat, writeFile } from 'node:fs/promises';
+// node:path: join for path construction, isAbsolute for cross-platform path detection
+import { isAbsolute, join } from 'node:path';
+// node:url: fileURLToPath for proper file:// URL handling
+import { fileURLToPath } from 'node:url';
+import { getModelsCachePath } from '../app/constants';
+import {
+  downloadFailedError,
+  invalidUriError,
+  modelNotCachedError,
+  modelNotFoundError,
+} from './errors';
+import type {
+  DownloadProgress,
+  LlmResult,
+  ModelCacheEntry,
+  ModelType,
+  ProgressCallback,
+} from './types';
+
+// ─────────────────────────────────────────────────────────────────────────────
+// URI Parsing
+// ─────────────────────────────────────────────────────────────────────────────
+
+// Regex patterns for URI parsing (top-level for performance)
+const HF_QUANT_PATTERN = /^([^/]+)\/([^/:]+):(\w+)$/;
+const HF_PATH_PATTERN = /^([^/]+)\/([^/]+)\/(.+\.gguf)$/;
+
+export type ParsedModelUri =
+  | {
+      scheme: 'hf';
+      org: string;
+      repo: string;
+      file: string;
+      quantization?: string;
+    }
+  | {
+      scheme: 'file';
+      file: string;
+    };
+
+/**
+ * Parse a model URI into components.
+ *
+ * Supported formats:
+ * - hf:org/repo/file.gguf (explicit file)
+ * - hf:org/repo:Q4_K_M (quantization shorthand - infers filename)
+ * - file:///path/to/model.gguf (standard file URL)
+ * - file:///C:/path/to/model.gguf (Windows file URL)
+ * - file:/path/to/model.gguf (simplified file URI)
+ * - /path/to/model.gguf (Unix absolute path)
+ * - C:\path\to\model.gguf (Windows absolute path)
+ * - \\server\share\model.gguf (UNC path)
+ */
+export function parseModelUri(
+  uri: string
+): { ok: true; value: ParsedModelUri } | { ok: false; error: string } {
+  // Handle hf: scheme
+  if (uri.startsWith('hf:')) {
+    const rest = uri.slice(3);
+
+    // Check for quantization shorthand: hf:org/repo:Q4_K_M
+    const colonMatch = rest.match(HF_QUANT_PATTERN);
+    if (colonMatch) {
+      const [, org, repo, quant] = colonMatch;
+      // Regex guarantees these are defined when match succeeds
+      if (org && repo && quant) {
+        return {
+          ok: true,
+          value: {
+            scheme: 'hf',
+            org,
+            repo,
+            file: '', // Will be resolved by node-llama-cpp
+            quantization: quant,
+          },
+        };
+      }
+    }
+
+    // Full path: hf:org/repo/file.gguf
+    const pathMatch = rest.match(HF_PATH_PATTERN);
+    if (pathMatch) {
+      const [, org, repo, file] = pathMatch;
+      // Regex guarantees these are defined when match succeeds
+      if (org && repo && file) {
+        return {
+          ok: true,
+          value: {
+            scheme: 'hf',
+            org,
+            repo,
+            file,
+          },
+        };
+      }
+    }
+
+    return { ok: false, error: `Invalid hf: URI format: ${uri}` };
+  }
+
+  // Handle file:// URLs (proper file URLs like file:///C:/path or file:///path)
+  if (uri.startsWith('file://')) {
+    try {
+      const filePath = fileURLToPath(new URL(uri));
+      return {
+        ok: true,
+        value: { scheme: 'file', file: filePath },
+      };
+    } catch {
+      return { ok: false, error: `Invalid file URL: ${uri}` };
+    }
+  }
+
+  // Handle simplified file: scheme (file:/path or file:C:\path)
+  if (uri.startsWith('file:')) {
+    const path = uri.slice(5);
+    if (!path) {
+      return { ok: false, error: 'Empty file path' };
+    }
+    return {
+      ok: true,
+      value: { scheme: 'file', file: path },
+    };
+  }
+
+  // Treat as local file path if absolute (works on both Unix and Windows)
+  if (isAbsolute(uri)) {
+    return {
+      ok: true,
+      value: { scheme: 'file', file: uri },
+    };
+  }
+
+  return { ok: false, error: `Unknown URI scheme: ${uri}` };
+}
+
+/**
+ * Convert parsed URI back to node-llama-cpp format.
+ */
+export function toNodeLlamaCppUri(parsed: ParsedModelUri): string {
+  if (parsed.scheme === 'file') {
+    return parsed.file;
+  }
+
+  // hf: format for node-llama-cpp
+  if (parsed.quantization) {
+    return `hf:${parsed.org}/${parsed.repo}:${parsed.quantization}`;
+  }
+  return `hf:${parsed.org}/${parsed.repo}/${parsed.file}`;
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Manifest
+// ─────────────────────────────────────────────────────────────────────────────
+
+interface Manifest {
+  version: '1.0';
+  models: ModelCacheEntry[];
+}
+
+const MANIFEST_VERSION = '1.0' as const;
+
+// ─────────────────────────────────────────────────────────────────────────────
+// ModelCache
+// ─────────────────────────────────────────────────────────────────────────────
+
+export class ModelCache {
+  readonly dir: string;
+  private readonly manifestPath: string;
+  private manifest: Manifest | null = null;
+
+  constructor(cacheDir?: string) {
+    this.dir = cacheDir ?? getModelsCachePath();
+    this.manifestPath = join(this.dir, 'manifest.json');
+  }
+
+  /**
+   * Resolve a model URI to a local file path.
+   * Returns error if not cached.
+   */
+  async resolve(uri: string, type: ModelType): Promise<LlmResult<string>> {
+    const parsed = parseModelUri(uri);
+    if (!parsed.ok) {
+      return { ok: false, error: invalidUriError(uri, parsed.error) };
+    }
+
+    // Local files: verify existence
+    if (parsed.value.scheme === 'file') {
+      const exists = await this.fileExists(parsed.value.file);
+      if (!exists) {
+        return {
+          ok: false,
+          error: modelNotFoundError(
+            uri,
+            `File not found: ${parsed.value.file}`
+          ),
+        };
+      }
+      return { ok: true, value: parsed.value.file };
+    }
+
+    // HF models: check cache
+    const cached = await this.getCachedPath(uri);
+    if (cached) {
+      return { ok: true, value: cached };
+    }
+
+    return { ok: false, error: modelNotCachedError(uri, type) };
+  }
+
+  /**
+   * Download a model to the cache.
+   * Uses node-llama-cpp's resolveModelFile for HF models.
+   */
+  async download(
+    uri: string,
+    type: ModelType,
+    onProgress?: ProgressCallback,
+    force?: boolean
+  ): Promise<LlmResult<string>> {
+    const parsed = parseModelUri(uri);
+    if (!parsed.ok) {
+      return { ok: false, error: invalidUriError(uri, parsed.error) };
+    }
+
+    // Local files: just verify
+    if (parsed.value.scheme === 'file') {
+      const exists = await this.fileExists(parsed.value.file);
+      if (!exists) {
+        return {
+          ok: false,
+          error: modelNotFoundError(
+            uri,
+            `File not found: ${parsed.value.file}`
+          ),
+        };
+      }
+      return { ok: true, value: parsed.value.file };
+    }
+
+    // Ensure cache dir exists
+    await mkdir(this.dir, { recursive: true });
+
+    // Force: delete existing file to trigger re-download
+    if (force) {
+      const existingPath = await this.getCachedPath(uri);
+      if (existingPath) {
+        await rm(existingPath).catch(() => {
+          // Ignore: file may not exist or already deleted
+        });
+      }
+    }
+
+    try {
+      const { resolveModelFile } = await import('node-llama-cpp');
+
+      // Convert to node-llama-cpp format (handles quantization shorthand)
+      // node-llama-cpp needs hf: prefix to identify HuggingFace models
+      const hfUri = toNodeLlamaCppUri(parsed.value);
+
+      const resolvedPath = await resolveModelFile(hfUri, {
+        directory: this.dir,
+        onProgress: onProgress
+          ? (status: unknown) => {
+              // Type-safe check for download progress status
+              if (
+                status &&
+                typeof status === 'object' &&
+                'type' in status &&
+                status.type === 'download' &&
+                'downloadedSize' in status &&
+                'totalSize' in status
+              ) {
+                const s = status as {
+                  downloadedSize: number;
+                  totalSize: number;
+                };
+                const progress: DownloadProgress = {
+                  downloadedBytes: s.downloadedSize,
+                  totalBytes: s.totalSize,
+                  percent:
+                    s.totalSize > 0
+                      ? (s.downloadedSize / s.totalSize) * 100
+                      : 0,
+                };
+                onProgress(progress);
+              }
+            }
+          : undefined,
+      });
+
+      // Update manifest
+      await this.addToManifest(uri, type, resolvedPath);
+
+      return { ok: true, value: resolvedPath };
+    } catch (e) {
+      return { ok: false, error: downloadFailedError(uri, e) };
+    }
+  }
+
+  /**
+   * Check if a model is cached/available.
+   * For file: URIs, checks if file exists on disk.
+   * For hf: URIs, checks the manifest.
+   */
+  async isCached(uri: string): Promise<boolean> {
+    const cached = await this.getCachedPath(uri);
+    return cached !== null;
+  }
+
+  /**
+   * Get cached/available path for a URI.
+   * For file: URIs, returns path if file exists.
+   * For hf: URIs, checks the manifest.
+   */
+  async getCachedPath(uri: string): Promise<string | null> {
+    // Handle file: URIs directly (check filesystem, not manifest)
+    const parsed = parseModelUri(uri);
+    if (parsed.ok && parsed.value.scheme === 'file') {
+      const exists = await this.fileExists(parsed.value.file);
+      return exists ? parsed.value.file : null;
+    }
+
+    // HF URIs: check manifest
+    const manifest = await this.loadManifest();
+    const entry = manifest.models.find((m) => m.uri === uri);
+    if (!entry) {
+      return null;
+    }
+
+    // Verify file still exists
+    const exists = await this.fileExists(entry.path);
+    if (!exists) {
+      // Remove stale entry
+      await this.removeFromManifest(uri);
+      return null;
+    }
+
+    return entry.path;
+  }
+
+  /**
+   * List all cached models.
+   */
+  async list(): Promise<ModelCacheEntry[]> {
+    const manifest = await this.loadManifest();
+    return manifest.models;
+  }
+
+  /**
+   * Get total size of all cached models.
+   */
+  async totalSize(): Promise<number> {
+    const manifest = await this.loadManifest();
+    return manifest.models.reduce((sum, m) => sum + (m.size || 0), 0);
+  }
+
+  /**
+   * Clear cached models.
+   * If types provided, only clears models of those types.
+   */
+  async clear(types?: ModelType[]): Promise<void> {
+    const manifest = await this.loadManifest();
+
+    const toRemove = types
+      ? manifest.models.filter((m) => types.includes(m.type))
+      : manifest.models;
+
+    for (const entry of toRemove) {
+      try {
+        await rm(entry.path, { force: true });
+      } catch {
+        // Ignore deletion errors
+      }
+    }
+
+    // Update manifest
+    if (types) {
+      manifest.models = manifest.models.filter((m) => !types.includes(m.type));
+    } else {
+      manifest.models = [];
+    }
+
+    await this.saveManifest(manifest);
+  }
+
+  // ───────────────────────────────────────────────────────────────────────────
+  // Private
+  // ───────────────────────────────────────────────────────────────────────────
+
+  private async fileExists(path: string): Promise<boolean> {
+    try {
+      await stat(path);
+      return true;
+    } catch {
+      return false;
+    }
+  }
+
+  private async loadManifest(): Promise<Manifest> {
+    if (this.manifest) {
+      return this.manifest;
+    }
+
+    try {
+      const content = await readFile(this.manifestPath, 'utf-8');
+      this.manifest = JSON.parse(content) as Manifest;
+      return this.manifest;
+    } catch {
+      // No manifest or invalid - create empty
+      this.manifest = { version: MANIFEST_VERSION, models: [] };
+      return this.manifest;
+    }
+  }
+
+  private async saveManifest(manifest: Manifest): Promise<void> {
+    await mkdir(this.dir, { recursive: true });
+    await writeFile(this.manifestPath, JSON.stringify(manifest, null, 2));
+    this.manifest = manifest;
+  }
+
+  private async addToManifest(
+    uri: string,
+    type: ModelType,
+    path: string
+  ): Promise<void> {
+    const manifest = await this.loadManifest();
+
+    // Get file size and compute checksum
+    let size = 0;
+    try {
+      const stats = await stat(path);
+      size = stats.size;
+    } catch {
+      // Ignore
+    }
+
+    // Remove existing entry if present
+    manifest.models = manifest.models.filter((m) => m.uri !== uri);
+
+    // Add new entry
+    manifest.models.push({
+      uri,
+      type,
+      path,
+      size,
+      checksum: '', // TODO: compute SHA-256 for large files
+      cachedAt: new Date().toISOString(),
+    });
+
+    await this.saveManifest(manifest);
+  }
+
+  private async removeFromManifest(uri: string): Promise<void> {
+    const manifest = await this.loadManifest();
+    manifest.models = manifest.models.filter((m) => m.uri !== uri);
+    await this.saveManifest(manifest);
+  }
+}

package/src/llm/errors.ts

@@ -0,0 +1,191 @@
+/**
+ * LLM error types and helpers.
+ * Follows the pattern from converters/errors.ts
+ *
+ * @module src/llm/errors
+ */
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Error Types
+// ─────────────────────────────────────────────────────────────────────────────
+
+export type LlmErrorCode =
+  | 'MODEL_NOT_FOUND'
+  | 'MODEL_NOT_CACHED'
+  | 'MODEL_DOWNLOAD_FAILED'
+  | 'MODEL_LOAD_FAILED'
+  | 'MODEL_CORRUPTED'
+  | 'INFERENCE_FAILED'
+  | 'TIMEOUT'
+  | 'OUT_OF_MEMORY'
+  | 'INVALID_URI';
+
+export interface LlmError {
+  code: LlmErrorCode;
+  message: string;
+  modelUri?: string;
+  retryable: boolean;
+  cause?: unknown;
+  suggestion?: string;
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Constants
+// ─────────────────────────────────────────────────────────────────────────────
+
+const MAX_CAUSE_LENGTH = 1000;
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Helpers
+// ─────────────────────────────────────────────────────────────────────────────
+
+/**
+ * Normalize a cause to safe, serializable format.
+ */
+function normalizeCause(
+  cause: unknown
+): { name: string; message: string } | string | undefined {
+  if (cause === undefined || cause === null) {
+    return;
+  }
+
+  if (cause instanceof Error) {
+    const message =
+      cause.message.length > MAX_CAUSE_LENGTH
+        ? `${cause.message.slice(0, MAX_CAUSE_LENGTH)}...`
+        : cause.message;
+    return { name: cause.name, message };
+  }
+
+  if (typeof cause === 'string') {
+    return cause.length > MAX_CAUSE_LENGTH
+      ? `${cause.slice(0, MAX_CAUSE_LENGTH)}...`
+      : cause;
+  }
+
+  try {
+    const str = String(cause);
+    return str.length > MAX_CAUSE_LENGTH
+      ? `${str.slice(0, MAX_CAUSE_LENGTH)}...`
+      : str;
+  } catch {
+    return '[unserializable cause]';
+  }
+}
+
+/**
+ * Create an LlmError with normalized cause.
+ */
+export function llmError(
+  code: LlmErrorCode,
+  opts: Omit<LlmError, 'code'>
+): LlmError {
+  return {
+    code,
+    ...opts,
+    cause: normalizeCause(opts.cause),
+  };
+}
+
+/**
+ * Check if error is retryable.
+ */
+export function isRetryable(code: LlmErrorCode): boolean {
+  return ['MODEL_DOWNLOAD_FAILED', 'TIMEOUT', 'INFERENCE_FAILED'].includes(
+    code
+  );
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Error Factories
+// ─────────────────────────────────────────────────────────────────────────────
+
+export function modelNotFoundError(uri: string, details?: string): LlmError {
+  return llmError('MODEL_NOT_FOUND', {
+    message: details
+      ? `Model not found: ${details}`
+      : `Model not found: ${uri}`,
+    modelUri: uri,
+    retryable: false,
+  });
+}
+
+export function modelNotCachedError(
+  uri: string,
+  modelType: 'embed' | 'rerank' | 'gen'
+): LlmError {
+  return llmError('MODEL_NOT_CACHED', {
+    message: `${modelType} model not cached`,
+    modelUri: uri,
+    retryable: false,
+    suggestion: `Run: gno models pull --${modelType}`,
+  });
+}
+
+export function downloadFailedError(uri: string, cause?: unknown): LlmError {
+  return llmError('MODEL_DOWNLOAD_FAILED', {
+    message: `Failed to download model: ${uri}`,
+    modelUri: uri,
+    retryable: true,
+    cause,
+  });
+}
+
+export function loadFailedError(uri: string, cause?: unknown): LlmError {
+  return llmError('MODEL_LOAD_FAILED', {
+    message: `Failed to load model: ${uri}`,
+    modelUri: uri,
+    retryable: false,
+    cause,
+    suggestion: 'Run: gno doctor',
+  });
+}
+
+export function corruptedError(uri: string, cause?: unknown): LlmError {
+  return llmError('MODEL_CORRUPTED', {
+    message: `Model file corrupted: ${uri}`,
+    modelUri: uri,
+    retryable: false,
+    cause,
+    suggestion: 'Run: gno models clear && gno models pull',
+  });
+}
+
+export function inferenceFailedError(uri: string, cause?: unknown): LlmError {
+  return llmError('INFERENCE_FAILED', {
+    message: `Inference failed for model: ${uri}`,
+    modelUri: uri,
+    retryable: true,
+    cause,
+  });
+}
+
+export function timeoutError(
+  uri: string,
+  operation: 'load' | 'inference',
+  timeoutMs: number
+): LlmError {
+  return llmError('TIMEOUT', {
+    message: `${operation} timed out after ${timeoutMs}ms`,
+    modelUri: uri,
+    retryable: true,
+  });
+}
+
+export function outOfMemoryError(uri: string, cause?: unknown): LlmError {
+  return llmError('OUT_OF_MEMORY', {
+    message: `Out of memory loading model: ${uri}`,
+    modelUri: uri,
+    retryable: false,
+    cause,
+    suggestion: 'Try a smaller quantization (Q4_K_M) or close other apps',
+  });
+}
+
+export function invalidUriError(uri: string, details: string): LlmError {
+  return llmError('INVALID_URI', {
+    message: `Invalid model URI: ${details}`,
+    modelUri: uri,
+    retryable: false,
+  });
+}

package/src/llm/index.ts

@@ -0,0 +1,58 @@
+/**
+ * LLM subsystem public API.
+ *
+ * @module src/llm
+ */
+
+// Re-export config types (source of truth in config/types.ts)
+export type { ModelConfig, ModelPreset } from '../config/types';
+export type { ParsedModelUri } from './cache';
+// Cache
+export { ModelCache, parseModelUri, toNodeLlamaCppUri } from './cache';
+// Errors
+export type { LlmError, LlmErrorCode } from './errors';
+export {
+  corruptedError,
+  downloadFailedError,
+  inferenceFailedError,
+  invalidUriError,
+  isRetryable,
+  llmError,
+  loadFailedError,
+  modelNotCachedError,
+  modelNotFoundError,
+  outOfMemoryError,
+  timeoutError,
+} from './errors';
+// Adapter
+export { createLlmAdapter, LlmAdapter } from './nodeLlamaCpp/adapter';
+// Lifecycle
+export {
+  getModelManager,
+  ModelManager,
+  resetModelManager,
+} from './nodeLlamaCpp/lifecycle';
+// Registry
+export {
+  getActivePreset,
+  getModelConfig,
+  getPreset,
+  listPresets,
+  resolveModelUri,
+} from './registry';
+// Types
+export type {
+  DownloadProgress,
+  EmbeddingPort,
+  GenerationPort,
+  GenParams,
+  LlmResult,
+  LoadedModel,
+  ModelCacheEntry,
+  ModelStatus,
+  ModelType,
+  ModelUri,
+  ProgressCallback,
+  RerankPort,
+  RerankScore,
+} from './types';