kiku-agent 1.2.0 → 1.3.0

package/server/agent/modelConfig.js

@@ -0,0 +1,487 @@
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { findRegistryEntry } from '../../src/lib/vram/modelRegistry.js';
+
+const GGUF_MAGIC = 0x46554747; 
+const MAX_HEADER_BYTES = 256 * 1024 * 1024; 
+
+const GGUF_VALUE_TYPES = Object.freeze({
+  UINT8: 0, INT8: 1, UINT16: 2, INT16: 3, UINT32: 4, INT32: 5,
+  FLOAT32: 6, BOOL: 7, STRING: 8, ARRAY: 9, UINT64: 10, INT64: 11, FLOAT64: 12,
+});
+
+const GGUF_FILE_TYPES = Object.freeze({
+  0: 'fp32', 1: 'fp16', 2: 'q4_0', 3: 'q4_1', 7: 'q8_0', 8: 'q5_0', 9: 'q5_1',
+  10: 'q2_k', 11: 'q3_k_s', 12: 'q3_k_m', 13: 'q3_k_l', 14: 'q4_k_s', 15: 'q4_k_m',
+  16: 'q5_k_s', 17: 'q5_k_m', 18: 'q6_k', 19: 'iq2_xxs', 22: 'iq3_xs', 24: 'iq1_s',
+  25: 'iq4_nl', 26: 'iq3_s', 28: 'iq2_s', 30: 'iq4_xs', 32: 'bf16', 38: 'mxfp4',
+});
+
+const GGUF_SCALAR_READERS = Object.freeze({
+  [GGUF_VALUE_TYPES.UINT8]: 'readUInt8',
+  [GGUF_VALUE_TYPES.INT8]: 'readInt8',
+  [GGUF_VALUE_TYPES.UINT16]: 'readUInt16',
+  [GGUF_VALUE_TYPES.INT16]: 'readInt16',
+  [GGUF_VALUE_TYPES.UINT32]: 'readUInt32',
+  [GGUF_VALUE_TYPES.INT32]: 'readInt32',
+  [GGUF_VALUE_TYPES.FLOAT32]: 'readFloat32',
+  [GGUF_VALUE_TYPES.BOOL]: 'readBool',
+  [GGUF_VALUE_TYPES.UINT64]: 'readUInt64',
+  [GGUF_VALUE_TYPES.INT64]: 'readInt64',
+  [GGUF_VALUE_TYPES.FLOAT64]: 'readFloat64',
+});
+
+class GgufReader {
+  constructor(fd) {
+    this.fd = fd;
+    this.buffer = Buffer.alloc(0);
+    this.cursor = 0;
+    this.totalRead = 0;
+  }
+
+  ensure(byteCount) {
+    if (this.buffer.length - this.cursor >= byteCount) return;
+    while (this.buffer.length - this.cursor < byteCount) {
+      if (this.totalRead > MAX_HEADER_BYTES) {
+        throw new Error(`GGUF header exceeded ${MAX_HEADER_BYTES / (1024 * 1024)} MB read budget`);
+      }
+      const chunk = Buffer.alloc(1024 * 1024);
+      const bytesRead = fs.readSync(this.fd, chunk, 0, chunk.length, this.totalRead);
+      if (bytesRead <= 0) throw new Error('Unexpected end of GGUF file while parsing header');
+      this.totalRead += bytesRead;
+      this.buffer = this.cursor > 0
+        ? Buffer.concat([this.buffer.subarray(this.cursor), chunk.subarray(0, bytesRead)])
+        : Buffer.concat([this.buffer, chunk.subarray(0, bytesRead)]);
+      this.cursor = 0;
+    }
+  }
+
+  u8() { this.ensure(1); return this.buffer.readUInt8(this.cursor++); }
+  u32() { this.ensure(4); const v = this.buffer.readUInt32LE(this.cursor); this.cursor += 4; return v; }
+  u64() {
+    this.ensure(8);
+    const v = this.buffer.readBigUInt64LE(this.cursor);
+    this.cursor += 8;
+    return Number(v);
+  }
+  string() {
+    const len = this.u64();
+    this.ensure(len);
+    const v = this.buffer.toString('utf8', this.cursor, this.cursor + len);
+    this.cursor += len;
+    return v;
+  }
+  value(type) {
+    if (type === GGUF_VALUE_TYPES.STRING) return this.string();
+    if (type === GGUF_VALUE_TYPES.ARRAY) {
+      const elemType = this.u32();
+      const count = this.u64();
+      if (count > 5_000_000) throw new Error('GGUF metadata array unreasonably large');
+      const out = new Array(count);
+      const scalarReader = GGUF_SCALAR_READERS[elemType];
+      for (let i = 0; i < count; i++) {
+        out[i] = scalarReader ? this[scalarReader]() : this.value(elemType);
+      }
+      return out;
+    }
+    const scalarReader = GGUF_SCALAR_READERS[type];
+    if (!scalarReader) throw new Error(`Unknown GGUF value type ${type}`);
+    return this[scalarReader]();
+  }
+  readBool() { return this.u8() !== 0; }
+  readInt8() { this.ensure(1); const v = this.buffer.readInt8(this.cursor); this.cursor += 1; return v; }
+  readUInt8() { return this.u8(); }
+  readUInt16() { this.ensure(2); const v = this.buffer.readUInt16LE(this.cursor); this.cursor += 2; return v; }
+  readInt16() { this.ensure(2); const v = this.buffer.readInt16LE(this.cursor); this.cursor += 2; return v; }
+  readInt32() { this.ensure(4); const v = this.buffer.readInt32LE(this.cursor); this.cursor += 4; return v; }
+  readUInt32() { return this.u32(); }
+  readFloat32() { this.ensure(4); const v = this.buffer.readFloatLE(this.cursor); this.cursor += 4; return v; }
+  readFloat64() { this.ensure(8); const v = this.buffer.readDoubleLE(this.cursor); this.cursor += 8; return v; }
+  readInt64() { this.ensure(8); const v = this.buffer.readBigInt64LE(this.cursor); this.cursor += 8; return Number(v); }
+  readUInt64() { return this.u64(); }
+}
+
+
+const PARSED_GGUF_CACHE_LIMIT = 100;
+const parsedGgufCache = new Map();
+
+export function parseGgufMetadata(filePath) {
+  let cacheKey = null;
+  try {
+    const stat = fs.statSync(filePath);
+    cacheKey = `${filePath}:${stat.mtimeMs}:${stat.size}`;
+    if (parsedGgufCache.has(cacheKey)) {
+      const cached = parsedGgufCache.get(cacheKey);
+      return cached ? { ...cached } : cached;
+    }
+  } catch {}
+  const parsed = parseGgufMetadataUncached(filePath);
+  if (cacheKey && parsed) {
+    if (parsedGgufCache.size >= PARSED_GGUF_CACHE_LIMIT) {
+      parsedGgufCache.delete(parsedGgufCache.keys().next().value);
+    }
+    parsedGgufCache.set(cacheKey, parsed);
+    return { ...parsed };
+  }
+  return parsed;
+}
+
+function parseGgufMetadataUncached(filePath) {
+  let fd = null;
+  try {
+    fd = fs.openSync(filePath, 'r');
+    const reader = new GgufReader(fd);
+    reader.ensure(4);
+    const magic = reader.buffer.readUInt32LE(reader.cursor);
+    reader.cursor += 4;
+    if (magic !== GGUF_MAGIC) return null;
+    reader.u32();
+
+    const tensorCount = reader.u64();
+    const kvCount = reader.u64();
+
+    const kv = {};
+    for (let i = 0; i < kvCount; i++) {
+      const key = reader.string();
+      const type = reader.u32();
+      kv[key] = reader.value(type);
+    }
+
+    
+    let paramCount = 0;
+    for (let i = 0; i < tensorCount; i++) {
+      reader.string(); 
+      const nDims = reader.u32();
+      let elements = 1;
+      for (let d = 0; d < nDims; d++) elements *= reader.u64();
+      reader.u32(); 
+      reader.u64(); 
+      paramCount += elements;
+    }
+
+    const arch = typeof kv['general.architecture'] === 'string' ? kv['general.architecture'] : null;
+    const prefix = arch ? `${arch}.` : '';
+    const pick = (key) => {
+      const v = prefix ? kv[`${prefix}${key}`] : undefined;
+      return v === undefined ? null : v;
+    };
+
+    const name = typeof kv['general.name'] === 'string' ? kv['general.name'] : path.basename(filePath);
+    const queryHeads = pick('attention.head_count');
+    const hiddenSize = pick('embedding_length');
+    const headDim = pick('attention.key_length') ?? pick('attention.value_length')
+      ?? (hiddenSize && queryHeads ? Math.round(hiddenSize / queryHeads) : null);
+    const swaWindow = pick('attention.swa_size') ?? pick('attention.sliding_window')
+      ?? pick('attention.window_size');
+    let fileSizeBytes = null;
+    try {
+      fileSizeBytes = fs.statSync(filePath).size;
+    } catch {
+
+    }
+    const fileType = kv['general.file_type'];
+
+    return {
+      filePath,
+      fileName: path.basename(filePath),
+      fileSizeBytes,
+      arch,
+      name,
+      quant: GGUF_FILE_TYPES[fileType] ?? extractQuantFromName(path.basename(filePath)),
+      layers: pick('block_count'),
+      queryHeads,
+      kvHeads: pick('attention.head_count_kv') ?? queryHeads,
+      headDim,
+      hiddenSize,
+      contextLength: pick('context_length'),
+      expertCount: pick('expert_count'),
+      swa: Number.isFinite(Number(swaWindow)) && Number(swaWindow) > 0
+        ? { windowTokens: Number(swaWindow) }
+        : null,
+      paramCount: paramCount > 0 ? paramCount : null,
+    };
+  } catch (err) {
+    return { error: err.message, filePath };
+  } finally {
+    if (fd !== null) {
+      try { fs.closeSync(fd); } catch { /* already closed */ }
+    }
+  }
+}
+
+
+export function extractQuantFromName(text) {
+  if (!text) return null;
+  const matches = String(text).match(/\b(iq[1-4]_[a-z0-9]+|q[2-8]_[a-z0-9_]+|q[2-8]_0|bf16|fp16|f16|fp32|f32|q8)\b/gi);
+  return matches ? matches[matches.length - 1].toLowerCase() : null;
+}
+
+
+export function describeVisionConfig(visionConfig) {
+  if (!visionConfig || typeof visionConfig !== 'object') return null;
+  const hidden = Number(visionConfig.hidden_size) || 1024;
+  const layers = Number(visionConfig.num_hidden_layers) || 24;
+  const patchSize = Number(visionConfig.patch_size) || 14;
+  const imageSize = Number(visionConfig.image_size) || 336;
+  
+  const params = layers * 12 * hidden * hidden + hidden * patchSize * patchSize * 3;
+  let tokensPerImage = Math.floor(imageSize / patchSize) ** 2 + 1;
+  tokensPerImage = Math.min(2048, Math.max(576, tokensPerImage));
+  return { encoderParamsB: Number((params / 1e9).toFixed(3)), tokensPerImage };
+}
+
+
+export function parseHfConfigJson(configJson, modelId = null) {
+  if (!configJson || typeof configJson !== 'object') return null;
+  const cfg = configJson.text_config && typeof configJson.text_config === 'object' ? configJson.text_config : configJson;
+  const queryHeads = cfg.num_attention_heads ?? null;
+  const hiddenSize = cfg.hidden_size ?? null;
+  const headDim = cfg.head_dim ?? (hiddenSize && queryHeads ? Math.round(hiddenSize / queryHeads) : null);
+  const isVlm = Boolean(configJson.vision_config || cfg.vision_config) ||
+    /llava|vl|vision|paligemma|multimodal/i.test(String(configJson.model_type || cfg.model_type || '') + String((configJson.architectures || cfg.architectures || []).join(' ')));
+  return {
+    modelId,
+    arch: cfg.model_type || configJson.model_type || (configJson.architectures ? configJson.architectures[0] : null),
+    name: modelId || configJson._name_or_path || cfg._name_or_path || null,
+    quant: null,
+    layers: cfg.num_hidden_layers ?? null,
+    queryHeads,
+    kvHeads: cfg.num_key_value_heads ?? queryHeads,
+    headDim,
+    hiddenSize,
+    contextLength: cfg.max_position_embeddings ?? null,
+    expertCount: cfg.num_local_experts ?? cfg.num_experts ?? null,
+    swa: Number.isFinite(Number(cfg.sliding_window)) && Number(cfg.sliding_window) > 0
+      ? { windowTokens: Number(cfg.sliding_window) }
+      : null,
+    paramCount: null,
+    vision: isVlm ? (describeVisionConfig(configJson.vision_config || cfg.vision_config) || { encoderParamsB: null, tokensPerImage: 576 }) : null,
+  };
+}
+
+export function candidateGgufDirectories() {
+  const home = os.homedir();
+  const dirs = [];
+  if (process.env.LMSTUDIO_MODELS_DIR) dirs.push(process.env.LMSTUDIO_MODELS_DIR);
+  dirs.push(path.join(home, '.lmstudio', 'models'));
+  if (process.platform === 'win32' && process.env.LOCALAPPDATA) {
+    dirs.push(path.join(process.env.LOCALAPPDATA, 'LM Studio', 'models'));
+  }
+  if (process.platform === 'linux') {
+    dirs.push(path.join(home, '.cache', 'lm-studio', 'models'));
+  }
+  return [...new Set(dirs)];
+}
+
+export function listGgufFiles(dir, depth = 0, limit = 200, acc = []) {
+  if (depth > 4 || acc.length >= limit) return acc;
+  let entries = [];
+  try {
+    entries = fs.readdirSync(dir, { withFileTypes: true });
+  } catch {
+    return acc;
+  }
+  for (const entry of entries) {
+    if (acc.length >= limit) break;
+    const full = path.join(dir, entry.name);
+    if (entry.isDirectory()) {
+      listGgufFiles(full, depth + 1, limit, acc);
+    } else if (entry.isFile() && entry.name.toLowerCase().endsWith('.gguf')) {
+      acc.push(full);
+    }
+  }
+  return acc;
+}
+
+let cachedGgufs = null;
+let lastGgufScanTime = 0;
+const GGUF_SCAN_TTL_MS = 30_000;
+
+export function listInstalledGgufs(force = false) {
+  const now = Date.now();
+  if (!force && cachedGgufs && (now - lastGgufScanTime < GGUF_SCAN_TTL_MS)) {
+    return [...cachedGgufs];
+  }
+  const dirs = candidateGgufDirectories();
+  const models = [];
+  const seenPaths = new Set();
+  for (const dir of dirs) {
+    const files = listGgufFiles(dir);
+    for (const f of files) {
+      if (seenPaths.has(f)) continue;
+      seenPaths.add(f);
+      try {
+        const stat = fs.statSync(f);
+        const fileName = path.basename(f);
+        const isMmproj = fileName.toLowerCase().startsWith('mmproj-');
+        const quant = extractQuantFromName(fileName);
+        const relDir = path.basename(path.dirname(f));
+        const label = relDir && relDir !== 'models' ? `${relDir} (${fileName})` : fileName;
+        models.push({
+          path: f,
+          fileName,
+          label,
+          fileSizeBytes: stat.size,
+          sizeGb: Number((stat.size / (1024 ** 3)).toFixed(2)),
+          quant,
+          isMmproj,
+        });
+      } catch {}
+    }
+  }
+  cachedGgufs = models;
+  lastGgufScanTime = now;
+  return [...models];
+}
+
+function stripProviderPrefix(modelName) {
+  return String(modelName || '').toLowerCase().split('/').pop().replace(/[^a-z0-9.-]/g, '');
+}
+
+async function fetchJson(url, timeoutMs = 4000) {
+  const res = await fetch(url, { signal: AbortSignal.timeout(timeoutMs), headers: { 'User-Agent': 'kiku-agent-vram' } });
+  if (!res.ok) throw new Error(`HTTP ${res.status}`);
+  return res.json();
+}
+
+/**
+ * Resolve the architecture configuration for a target model.
+ *
+ * @param {object} options
+ * @param {string}  [options.modelPath]  Path to a .gguf checkpoint (parsed directly).
+ * @param {string}  [options.modelName]  Model id (registry / LM Studio dir / HF lookup).
+ * @param {object}  [options.overrides]  Explicit geometry, e.g. { layers, kvHeads, headDim,
+ *                                       hiddenSize, queryHeads, paramsB, contextLength, quant }.
+ * @param {boolean} [options.allowNetwork=true]  Permit HuggingFace config.json lookups.
+ * @returns {Promise<{source: string, config: object|null, approx: boolean, error?: string}>}
+ */
+export async function resolveModelConfig({ modelPath = null, modelName = null, overrides = {}, allowNetwork = true } = {}) {
+  const overrideConfig = buildOverrideConfig(overrides);
+  const completeOverride = overrideConfig?.layers && overrideConfig.kvHeads &&
+    (overrideConfig.headDim || (overrideConfig.hiddenSize && overrideConfig.queryHeads)) &&
+    (overrideConfig.paramCount || overrideConfig.paramsB);
+  if (completeOverride) {
+    return { source: 'overrides', config: overrideConfig, approx: false };
+  }
+
+  if (modelPath) {
+    try {
+      if (fs.existsSync(modelPath) && fs.statSync(modelPath).isFile() && modelPath.toLowerCase().endsWith('.gguf')) {
+        const parsed = parseGgufMetadata(modelPath);
+        if (parsed && !parsed.error) {
+          return { source: 'gguf', config: parsed, approx: false };
+        }
+        return { source: 'gguf', config: null, approx: false, error: parsed?.error || 'Unreadable GGUF header' };
+      }
+    } catch (err) {
+      return { source: 'gguf', config: null, approx: false, error: err.message };
+    }
+  }
+
+  const quantFromName = extractQuantFromName(modelName || modelPath || '');
+
+  if (modelName) {
+    const needle = stripProviderPrefix(modelName);
+    const requestedQuant = overrides.quant ? (extractQuantFromName(overrides.quant) || String(overrides.quant).toLowerCase()) : null;
+    const quantNeedle = extractQuantFromName(needle) || requestedQuant;
+    for (const dir of candidateGgufDirectories()) {
+      const files = listGgufFiles(dir);
+      const matches = files.filter(f => stripProviderPrefix(f).includes(needle));
+      if (matches.length === 0) continue;
+      const preferred = (quantNeedle && matches.find(f => {
+        const fileQuant = extractQuantFromName(f);
+        return fileQuant === quantNeedle || f.toLowerCase().includes(String(quantNeedle).toLowerCase());
+      })) || matches[0];
+      const parsed = parseGgufMetadata(preferred);
+      if (parsed && !parsed.error) {
+        return { source: 'gguf', config: parsed, approx: false };
+      }
+    }
+  }
+
+  if (modelName && allowNetwork && /^[^/\s]+\/[^/\s]+$/.test(modelName)) {
+    try {
+      const [configJson, apiInfo] = await Promise.all([
+        fetchJson(`https://huggingface.co/${modelName}/resolve/main/config.json`).catch(() => null),
+        fetchJson(`https://huggingface.co/api/models/${modelName}`).catch(() => null),
+      ]);
+      if (configJson) {
+        const config = parseHfConfigJson(configJson, modelName);
+        if (config) {
+          const total = apiInfo?.safetensors?.total;
+          if (Number.isFinite(Number(total)) && Number(total) > 0) config.paramCount = Number(total);
+          if (apiInfo?.safetensors?.parameters && !total) {
+            const sum = Object.values(apiInfo.safetensors.parameters).reduce((a, b) => a + Number(b || 0), 0);
+            if (sum > 0) config.paramCount = sum;
+          }
+          if (quantFromName) config.quant = quantFromName;
+          return { source: 'hf', config, approx: config.paramCount === null };
+        }
+      }
+    } catch {
+    
+    }
+  }
+
+  const registryEntry = modelName ? findRegistryEntry(modelName) : null;
+  if (registryEntry) {
+    return {
+      source: 'registry',
+      approx: true,
+      config: {
+        modelId: modelName,
+        arch: null,
+        name: registryEntry.label,
+        quant: quantFromName ?? registryEntry.defaultQuant ?? null,
+        layers: registryEntry.layers,
+        queryHeads: registryEntry.queryHeads,
+        kvHeads: registryEntry.kvHeads,
+        headDim: registryEntry.headDim,
+        hiddenSize: registryEntry.hiddenSize,
+        contextLength: registryEntry.contextLength,
+        expertCount: null,
+        swa: registryEntry.swa || null,
+        paramCount: Math.round(registryEntry.paramsB * 1e9),
+        paramsB: registryEntry.paramsB,
+        vision: registryEntry.vision || null,
+        registryNotes: registryEntry.notes || null,
+      },
+    };
+  }
+
+  if (overrideConfig) {
+    return { source: 'overrides', config: overrideConfig, approx: true };
+  }
+  return { source: 'none', config: null, approx: true };
+}
+
+function buildOverrideConfig(overrides = {}) {
+  const keys = ['layers', 'queryHeads', 'kvHeads', 'headDim', 'hiddenSize', 'paramCount', 'paramsB', 'contextLength', 'quant', 'expertCount'];
+  const picked = {};
+  let found = false;
+  for (const key of keys) {
+    if (overrides[key] !== undefined && overrides[key] !== null && overrides[key] !== '') {
+      picked[key] = overrides[key];
+      found = true;
+    }
+  }
+  if (!found) return null;
+  return {
+    modelId: overrides.modelId || null,
+    name: overrides.modelName || null,
+    arch: null,
+    quant: picked.quant ?? null,
+    layers: picked.layers ?? null,
+    queryHeads: picked.queryHeads ?? null,
+    kvHeads: picked.kvHeads ?? picked.queryHeads ?? null,
+    headDim: picked.headDim ?? (picked.hiddenSize && picked.queryHeads ? Math.round(picked.hiddenSize / picked.queryHeads) : null),
+    hiddenSize: picked.hiddenSize ?? null,
+    contextLength: picked.contextLength ?? null,
+    expertCount: picked.expertCount ?? null,
+    swa: overrides.swa || null,
+    paramCount: picked.paramCount ?? (picked.paramsB ? Math.round(Number(picked.paramsB) * 1e9) : null),
+    paramsB: picked.paramsB ?? null,
+    vision: overrides.vision || null,
+  };
+}