@ruvector/ruvllm 4.0.1 → 4.1.0

package/bin/gpu-delegate.js

@@ -0,0 +1,67 @@
+'use strict';
+/**
+ * Run a CLI shipped by @ruvector/ruvllm-gpu-loop (the GPU job loop, adapter
+ * archives and bounded weight experiments that were @ruvector/ruvllm 4.0.x).
+ * Used by `ruvllm gpu ...` and the `ruvllm-gpu-loop` / `ruvllm-adapters` bins.
+ */
+const { spawnSync } = require('node:child_process');
+const { readFileSync } = require('node:fs');
+const { dirname, resolve } = require('node:path');
+
+const GPU_LOOP_PACKAGE = '@ruvector/ruvllm-gpu-loop';
+
+function resolveGpuBin(binName) {
+  let manifestPath;
+  try {
+    manifestPath = require.resolve(`${GPU_LOOP_PACKAGE}/package.json`);
+  } catch {
+    const error = new Error(
+      `"${binName}" is provided by the optional package ${GPU_LOOP_PACKAGE}, which is not installed ` +
+      `(optional dependencies are skipped by --omit=optional, and it requires Node 22+).\n` +
+      `Install it with: npm install ${GPU_LOOP_PACKAGE}`);
+    error.code = 'RUVLLM_GPU_LOOP_MISSING';
+    throw error;
+  }
+  const manifest = JSON.parse(readFileSync(manifestPath, 'utf8'));
+  const rel = manifest.bin && manifest.bin[binName];
+  if (typeof rel !== 'string') {
+    const error = new Error(`${GPU_LOOP_PACKAGE}@${manifest.version} has no "${binName}" command`);
+    error.code = 'RUVLLM_GPU_LOOP_BIN_MISSING';
+    throw error;
+  }
+  return resolve(dirname(manifestPath), rel);
+}
+
+/** Run `binName` from the GPU-loop package with `args`; exits with its status. */
+function delegate(binName, args) {
+  let binPath;
+  try {
+    binPath = resolveGpuBin(binName);
+  } catch (error) {
+    console.error(`Error: ${error.message}`);
+    process.exit(1);
+  }
+  const result = spawnSync(process.execPath, [binPath, ...args], { stdio: 'inherit' });
+  if (result.error) {
+    console.error(`Error: could not run ${binName}: ${result.error.message}`);
+    process.exit(1);
+  }
+  if (result.signal) process.kill(process.pid, result.signal);
+  process.exit(result.status === null ? 1 : result.status);
+}
+
+/**
+ * `ruvllm gpu <args>`:
+ *   gpu loop <args>      -> ruvllm-gpu-loop (status, tick, ...)
+ *   gpu adapters <args>  -> ruvllm-adapters (export, training-plan, select)
+ *   gpu <args>           -> ruvllm-gpu      (run, fixture, --help; the 4.0.x `ruvllm` CLI)
+ */
+function runGpuCommand(args) {
+  const [first, ...rest] = args;
+  if (first === 'loop') return delegate('ruvllm-gpu-loop', rest);
+  if (first === 'adapters') return delegate('ruvllm-adapters', rest);
+  if (first === undefined) return delegate('ruvllm-gpu', ['--help']);
+  return delegate('ruvllm-gpu', args);
+}
+
+module.exports = { GPU_LOOP_PACKAGE, resolveGpuBin, delegate, runGpuCommand };

package/bin/ruvllm-adapters.js

@@ -0,0 +1,5 @@
+#!/usr/bin/env node
+'use strict';
+// Compatibility bin: `ruvllm-adapters` shipped with @ruvector/ruvllm 4.0.x and now lives in
+// @ruvector/ruvllm-gpu-loop (installed as an optional dependency).
+require('./gpu-delegate.js').delegate('ruvllm-adapters', process.argv.slice(2));

package/bin/ruvllm-gpu-loop.js

@@ -0,0 +1,5 @@
+#!/usr/bin/env node
+'use strict';
+// Compatibility bin: `ruvllm-gpu-loop` shipped with @ruvector/ruvllm 4.0.x and now lives in
+// @ruvector/ruvllm-gpu-loop (installed as an optional dependency).
+require('./gpu-delegate.js').delegate('ruvllm-gpu-loop', process.argv.slice(2));

package/bin/serve.js

@@ -0,0 +1,265 @@
+'use strict';
+/**
+ * `ruvllm serve` - local HTTP server over a loaded GGUF model.
+ *
+ * Endpoints (the contract used by @claude-flow/providers' RuVector provider):
+ *   GET  /health               -> { status, model, sona, hnsw, native, version }
+ *   GET  /v1/models            -> OpenAI-style model list
+ *   POST /query                -> { query, session_id? } -> routed answer
+ *   POST /v1/chat/completions  -> OpenAI-compatible chat (stream or not)
+ *
+ * Strict by design: the server only starts once a model is loaded. A healthy
+ * /health tells clients that /query will be answered by a real model, so a
+ * server that cannot generate must not be running (clients then fall back,
+ * e.g. to Ollama). Generation is synchronous in the native binding, so
+ * requests are served one at a time; `stream: true` returns the finished
+ * completion as a single SSE chunk followed by [DONE] (no token streaming).
+ */
+const http = require('node:http');
+const { randomUUID } = require('node:crypto');
+
+const DEFAULT_HOST = '127.0.0.1';
+const DEFAULT_PORT = 3000;
+const MAX_BODY_BYTES = 1024 * 1024;
+
+function httpError(status, code, message) {
+  const error = new Error(message);
+  error.status = status;
+  error.code = code;
+  return error;
+}
+
+function readJson(req, limit) {
+  return new Promise((resolve, reject) => {
+    let size = 0;
+    const chunks = [];
+    req.on('data', (chunk) => {
+      size += chunk.length;
+      if (size > limit) {
+        reject(httpError(413, 'request_too_large', `request body exceeds ${limit} bytes`));
+        req.destroy();
+        return;
+      }
+      chunks.push(chunk);
+    });
+    req.on('end', () => {
+      try {
+        const text = Buffer.concat(chunks).toString('utf8');
+        const body = text.length ? JSON.parse(text) : {};
+        if (!body || typeof body !== 'object' || Array.isArray(body)) {
+          throw new Error('body must be a JSON object');
+        }
+        resolve(body);
+      } catch (error) {
+        reject(httpError(400, 'invalid_json', `invalid JSON body: ${error.message}`));
+      }
+    });
+    req.on('error', reject);
+  });
+}
+
+function send(res, status, payload) {
+  const body = JSON.stringify(payload);
+  res.writeHead(status, { 'content-type': 'application/json', 'content-length': Buffer.byteLength(body) });
+  res.end(body);
+}
+
+function finiteNumber(value, name, min, max) {
+  if (value === undefined || value === null) return undefined;
+  if (typeof value !== 'number' || !Number.isFinite(value) || value < min || value > max) {
+    throw httpError(400, 'invalid_request', `${name} must be a number in [${min}, ${max}]`);
+  }
+  return value;
+}
+
+/** Map OpenAI-style request fields onto the engine's GenerationConfig. */
+function generationConfig(body, defaults) {
+  const config = { ...defaults };
+  const maxTokens = finiteNumber(body.max_tokens ?? body.max_completion_tokens, 'max_tokens', 1, 1 << 20);
+  const temperature = finiteNumber(body.temperature, 'temperature', 0, 10);
+  const topP = finiteNumber(body.top_p, 'top_p', 0, 1);
+  const topK = finiteNumber(body.top_k, 'top_k', 0, 1 << 20);
+  const seed = finiteNumber(body.seed, 'seed', 0, Number.MAX_SAFE_INTEGER);
+  if (maxTokens !== undefined) config.maxTokens = Math.floor(maxTokens);
+  if (temperature !== undefined) config.temperature = temperature;
+  if (topP !== undefined) config.topP = topP;
+  if (topK !== undefined) config.topK = Math.floor(topK);
+  if (seed !== undefined) config.seed = Math.floor(seed);
+  if (body.stop !== undefined) {
+    const stop = typeof body.stop === 'string' ? [body.stop] : body.stop;
+    if (!Array.isArray(stop) || stop.some((s) => typeof s !== 'string')) {
+      throw httpError(400, 'invalid_request', 'stop must be a string or an array of strings');
+    }
+    config.stopSequences = stop;
+  }
+  return config;
+}
+
+function chatMessages(body) {
+  const { messages } = body;
+  if (!Array.isArray(messages) || messages.length === 0) {
+    throw httpError(400, 'invalid_request', 'messages must be a non-empty array');
+  }
+  return messages.map((m, i) => {
+    if (!m || !['system', 'user', 'assistant'].includes(m.role)) {
+      throw httpError(400, 'invalid_request', `messages[${i}].role must be system, user or assistant`);
+    }
+    let content = m.content;
+    if (Array.isArray(content)) {
+      content = content.map((part) => (part && part.type === 'text' && typeof part.text === 'string' ? part.text : '')).join('');
+    }
+    if (typeof content !== 'string') {
+      throw httpError(400, 'invalid_request', `messages[${i}].content must be a string`);
+    }
+    return { role: m.role, content };
+  });
+}
+
+function usage(promptTokens, completionTokens) {
+  const p = promptTokens || 0;
+  const c = completionTokens || 0;
+  return { prompt_tokens: p, completion_tokens: c, total_tokens: p + c };
+}
+
+/**
+ * Build the HTTP server around an engine that already has a model loaded.
+ * `engine` needs: query(text, config), chat(messages, config), route(text),
+ * isModelLoaded(), isNativeLoaded(). Exported for tests.
+ */
+function createServer(engine, options = {}) {
+  const modelId = options.modelId || 'ruvllm';
+  const version = options.version || 'unknown';
+  const defaults = options.defaults || {};
+  const limit = options.maxBodyBytes || MAX_BODY_BYTES;
+  const learning = options.learningEnabled !== false;
+
+  async function handle(req, res) {
+    const url = new URL(req.url, 'http://localhost');
+    const route = `${req.method} ${url.pathname}`;
+
+    if (route === 'GET /health') {
+      return send(res, 200, {
+        status: 'ok',
+        model: modelId,
+        modelLoaded: engine.isModelLoaded(),
+        native: engine.isNativeLoaded(),
+        sona: learning,
+        hnsw: engine.isNativeLoaded(),
+        version,
+      });
+    }
+
+    if (route === 'GET /v1/models') {
+      return send(res, 200, { object: 'list', data: [{ id: modelId, object: 'model', owned_by: 'ruvllm' }] });
+    }
+
+    if (route === 'POST /query') {
+      const body = await readJson(req, limit);
+      if (typeof body.query !== 'string' || body.query.length === 0) {
+        throw httpError(400, 'invalid_request', 'query must be a non-empty string');
+      }
+      const config = generationConfig(body, defaults);
+      const response = engine.query(body.query, config);
+      return send(res, 200, {
+        id: response.requestId || `ruvllm-${randomUUID()}`,
+        model: modelId,
+        content: response.text,
+        done: response.finishReason !== 'length',
+        finish_reason: response.finishReason || 'stop',
+        session_id: typeof body.session_id === 'string' ? body.session_id : undefined,
+        usage: usage(response.promptTokens, response.completionTokens),
+        router_metrics: { route: response.model, confidence: response.confidence, context_size: response.contextSize },
+        latency_ms: response.latencyMs,
+      });
+    }
+
+    if (route === 'POST /v1/chat/completions') {
+      const body = await readJson(req, limit);
+      const messages = chatMessages(body);
+      const config = generationConfig(body, defaults);
+      const result = engine.chat(messages, config);
+      const id = `chatcmpl-${randomUUID()}`;
+      const created = Math.floor(Date.now() / 1000);
+      const finish = result.finishReason === 'length' ? 'length' : 'stop';
+      if (body.stream === true) {
+        res.writeHead(200, { 'content-type': 'text/event-stream', 'cache-control': 'no-cache', connection: 'keep-alive' });
+        const chunk = (delta, finishReason, extra) => `data: ${JSON.stringify({
+          id, object: 'chat.completion.chunk', created, model: modelId,
+          choices: [{ index: 0, delta, finish_reason: finishReason }], ...extra,
+        })}\n\n`;
+        res.write(chunk({ role: 'assistant', content: result.text }, null));
+        res.write(chunk({}, finish, { usage: usage(result.promptTokens, result.completionTokens) }));
+        res.end('data: [DONE]\n\n');
+        return undefined;
+      }
+      return send(res, 200, {
+        id, object: 'chat.completion', created, model: modelId,
+        choices: [{ index: 0, message: { role: 'assistant', content: result.text }, finish_reason: finish }],
+        usage: usage(result.promptTokens, result.completionTokens),
+      });
+    }
+
+    throw httpError(404, 'not_found', `no route for ${route}`);
+  }
+
+  return http.createServer((req, res) => {
+    handle(req, res).catch((error) => {
+      if (res.headersSent) {
+        res.destroy(error);
+        return;
+      }
+      const status = error.status
+        || (error.code === 'RUVLLM_NO_LANGUAGE_MODEL' ? 503 : 500);
+      send(res, status, { error: { code: error.code || 'server_error', message: error.message } });
+    });
+  });
+}
+
+/**
+ * CLI entry: `ruvllm serve <model.gguf> [--host H] [--port P] [--max-context N]`.
+ * `RuvLLM` is passed in so this file does not load dist/ by itself.
+ */
+function runServe({ RuvLLM, version }, positional, flags) {
+  const modelPath = (typeof flags.model === 'string' && flags.model) || positional[0];
+  if (!modelPath) {
+    console.error('Error: ruvllm serve needs a model: ruvllm serve <path/to/model.gguf> (or --model <path>)');
+    console.error('Download one with: ruvllm models download claude-code');
+    process.exit(1);
+  }
+  const host = typeof flags.host === 'string' ? flags.host : DEFAULT_HOST;
+  const port = flags.port === undefined ? DEFAULT_PORT : Number(flags.port);
+  if (!Number.isInteger(port) || port < 0 || port > 65535) {
+    console.error('Error: --port must be an integer in [0, 65535]');
+    process.exit(1);
+  }
+
+  const llm = new RuvLLM({ learningEnabled: !flags['no-learning'] });
+  const loadOptions = {};
+  if (flags['max-context']) loadOptions.maxContext = parseInt(flags['max-context'], 10);
+  let info;
+  try {
+    info = llm.loadModel(modelPath, loadOptions);
+  } catch (error) {
+    console.error(`Error: ${error.message}`);
+    if (error.code) console.error(`(${error.code}; the server was not started)`);
+    process.exit(1);
+  }
+
+  const defaults = {};
+  if (flags['max-tokens']) defaults.maxTokens = parseInt(flags['max-tokens'], 10);
+  if (flags.temperature) defaults.temperature = parseFloat(flags.temperature);
+  const server = createServer(llm, {
+    modelId: info.name, version, defaults, learningEnabled: !flags['no-learning'],
+  });
+  server.listen(port, host, () => {
+    const address = server.address();
+    console.error(`Loaded ${info.name} (${info.architecture}, ${info.quantization ?? 'quantization unknown'})`);
+    console.error(`ruvllm serve listening on http://${address.address}:${address.port} (GET /health, POST /query, POST /v1/chat/completions)`);
+  });
+  const stop = () => server.close(() => process.exit(0));
+  process.once('SIGINT', stop);
+  process.once('SIGTERM', stop);
+  return server;
+}
+
+module.exports = { createServer, runServe, DEFAULT_HOST, DEFAULT_PORT };

package/dist/cjs/benchmarks/embedding-benchmark.d.ts

@@ -0,0 +1,102 @@
+/**
+ * Embedding Quality Benchmark for RuvLTRA Models
+ *
+ * Tests embedding quality for Claude Code use cases:
+ * - Code similarity detection
+ * - Task clustering
+ * - Semantic search accuracy
+ */
+export interface EmbeddingPair {
+    id: string;
+    text1: string;
+    text2: string;
+    similarity: 'high' | 'medium' | 'low' | 'none';
+    category: string;
+}
+export interface EmbeddingResult {
+    pairId: string;
+    expectedSimilarity: string;
+    computedScore: number;
+    correct: boolean;
+    latencyMs: number;
+}
+export interface ClusterTestCase {
+    id: string;
+    items: string[];
+    expectedCluster: string;
+}
+export interface EmbeddingBenchmarkResults {
+    similarityAccuracy: number;
+    similarityByCategory: Record<string, number>;
+    avgSimilarityLatencyMs: number;
+    clusterPurity: number;
+    silhouetteScore: number;
+    searchMRR: number;
+    searchNDCG: number;
+    similarityResults: EmbeddingResult[];
+    totalPairs: number;
+}
+/**
+ * Ground truth similarity pairs for testing
+ * Tests whether embeddings correctly capture semantic similarity
+ */
+export declare const SIMILARITY_TEST_PAIRS: EmbeddingPair[];
+/**
+ * Search relevance test cases
+ * Query + documents with relevance scores
+ */
+export interface SearchTestCase {
+    id: string;
+    query: string;
+    documents: {
+        text: string;
+        relevance: number;
+    }[];
+}
+export declare const SEARCH_TEST_CASES: SearchTestCase[];
+/**
+ * Cluster test cases - items that should cluster together
+ */
+export declare const CLUSTER_TEST_CASES: ClusterTestCase[];
+/**
+ * Check if computed similarity matches expected category
+ */
+export declare function isCorrectSimilarity(expected: 'high' | 'medium' | 'low' | 'none', computed: number): boolean;
+/**
+ * Calculate Mean Reciprocal Rank for search results
+ */
+export declare function calculateMRR(rankings: {
+    relevant: boolean;
+}[][]): number;
+/**
+ * Calculate NDCG for search results
+ */
+export declare function calculateNDCG(results: {
+    relevance: number;
+}[], idealOrder: {
+    relevance: number;
+}[]): number;
+/**
+ * Calculate silhouette score for clustering
+ */
+export declare function calculateSilhouette(embeddings: number[][], labels: number[]): number;
+/**
+ * Run the embedding benchmark
+ */
+export declare function runEmbeddingBenchmark(embedder: (text: string) => number[], similarityFn: (a: number[], b: number[]) => number): EmbeddingBenchmarkResults;
+/**
+ * Format embedding benchmark results for display
+ */
+export declare function formatEmbeddingResults(results: EmbeddingBenchmarkResults): string;
+declare const _default: {
+    SIMILARITY_TEST_PAIRS: EmbeddingPair[];
+    SEARCH_TEST_CASES: SearchTestCase[];
+    CLUSTER_TEST_CASES: ClusterTestCase[];
+    runEmbeddingBenchmark: typeof runEmbeddingBenchmark;
+    formatEmbeddingResults: typeof formatEmbeddingResults;
+    isCorrectSimilarity: typeof isCorrectSimilarity;
+    calculateMRR: typeof calculateMRR;
+    calculateNDCG: typeof calculateNDCG;
+};
+export default _default;
+//# sourceMappingURL=embedding-benchmark.d.ts.map

package/dist/cjs/benchmarks/embedding-benchmark.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"embedding-benchmark.d.ts","sourceRoot":"","sources":["../../../src/benchmarks/embedding-benchmark.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,MAAM,WAAW,aAAa;IAC5B,EAAE,EAAE,MAAM,CAAC;IACX,KAAK,EAAE,MAAM,CAAC;IACd,KAAK,EAAE,MAAM,CAAC;IACd,UAAU,EAAE,MAAM,GAAG,QAAQ,GAAG,KAAK,GAAG,MAAM,CAAC;IAC/C,QAAQ,EAAE,MAAM,CAAC;CAClB;AAED,MAAM,WAAW,eAAe;IAC9B,MAAM,EAAE,MAAM,CAAC;IACf,kBAAkB,EAAE,MAAM,CAAC;IAC3B,aAAa,EAAE,MAAM,CAAC;IACtB,OAAO,EAAE,OAAO,CAAC;IACjB,SAAS,EAAE,MAAM,CAAC;CACnB;AAED,MAAM,WAAW,eAAe;IAC9B,EAAE,EAAE,MAAM,CAAC;IACX,KAAK,EAAE,MAAM,EAAE,CAAC;IAChB,eAAe,EAAE,MAAM,CAAC;CACzB;AAED,MAAM,WAAW,yBAAyB;IAExC,kBAAkB,EAAE,MAAM,CAAC;IAC3B,oBAAoB,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC7C,sBAAsB,EAAE,MAAM,CAAC;IAG/B,aAAa,EAAE,MAAM,CAAC;IACtB,eAAe,EAAE,MAAM,CAAC;IAGxB,SAAS,EAAE,MAAM,CAAC;IAClB,UAAU,EAAE,MAAM,CAAC;IAGnB,iBAAiB,EAAE,eAAe,EAAE,CAAC;IACrC,UAAU,EAAE,MAAM,CAAC;CACpB;AAED;;;GAGG;AACH,eAAO,MAAM,qBAAqB,EAAE,aAAa,EA8ChD,CAAC;AAEF;;;GAGG;AACH,MAAM,WAAW,cAAc;IAC7B,EAAE,EAAE,MAAM,CAAC;IACX,KAAK,EAAE,MAAM,CAAC;IACd,SAAS,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,SAAS,EAAE,MAAM,CAAA;KAAE,EAAE,CAAC;CAClD;AAED,eAAO,MAAM,iBAAiB,EAAE,cAAc,EAwD7C,CAAC;AAEF;;GAEG;AACH,eAAO,MAAM,kBAAkB,EAAE,eAAe,EAwD/C,CAAC;AAYF;;GAEG;AACH,wBAAgB,mBAAmB,CACjC,QAAQ,EAAE,MAAM,GAAG,QAAQ,GAAG,KAAK,GAAG,MAAM,EAC5C,QAAQ,EAAE,MAAM,GACf,OAAO,CAGT;AAED;;GAEG;AACH,wBAAgB,YAAY,CAC1B,QAAQ,EAAE;IAAE,QAAQ,EAAE,OAAO,CAAA;CAAE,EAAE,EAAE,GAClC,MAAM,CASR;AAED;;GAEG;AACH,wBAAgB,aAAa,CAC3B,OAAO,EAAE;IAAE,SAAS,EAAE,MAAM,CAAA;CAAE,EAAE,EAChC,UAAU,EAAE;IAAE,SAAS,EAAE,MAAM,CAAA;CAAE,EAAE,GAClC,MAAM,CAUR;AAED;;GAEG;AACH,wBAAgB,mBAAmB,CACjC,UAAU,EAAE,MAAM,EAAE,EAAE,EACtB,MAAM,EAAE,MAAM,EAAE,GACf,MAAM,CA8CR;AAUD;;GAEG;AACH,wBAAgB,qBAAqB,CACnC,QAAQ,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,MAAM,EAAE,EACpC,YAAY,EAAE,CAAC,CAAC,EAAE,MAAM,EAAE,EAAE,CAAC,EAAE,MAAM,EAAE,KAAK,MAAM,GACjD,yBAAyB,CA0G3B;AAED;;GAEG;AACH,wBAAgB,sBAAsB,CAAC,OAAO,EAAE,yBAAyB,GAAG,MAAM,CAyDjF;;;;;;;;;;;AAED,wBASE"}