Skip to content

armgit / ruflo

Public Imported from GitHub
0

🌊 The original agent harness. Deploy intelligent multi-player swarms, coordinate autonomous workflows, and build conversational AI systems. Features adaptive memory, self-learning intelligence, federation, vector RAG integration, and native Claude Code / Codex / Hermes and many more Integrated

feat(embeddings): wire Lattice WASM as the primary embedder tier β€” fail-closed, model-capable (embedding substrate upgrade) (#2581)

rUvfe7eaa66c770
diff --git a/v3/@claude-flow/cli/__tests__/lattice-wasm.test.ts b/v3/@claude-flow/cli/__tests__/lattice-wasm.test.ts
new file mode 100644
index 0000000000..8864ac5c06
--- /dev/null
+++ b/v3/@claude-flow/cli/__tests__/lattice-wasm.test.ts
@@ -0,0 +1,23 @@
+/**
+ * Lattice WASM embedder adapter β€” fail-closed degradation (embedding substrate).
+ * The package is optional + not installed in CI, so these assert the ZERO-
+ * REGRESSION path: absent Lattice β‡’ unavailable + null, callers fall through.
+ */
+import { describe, it, expect } from 'vitest';
+import {
+ latticeAvailable, latticeEmbed, latticeModels, LATTICE_WASM_PKG, DEFAULT_LATTICE_MODEL,
+} from '../src/ruvector/lattice-wasm.js';
+
+describe('lattice-wasm adapter (fail-closed)', () => {
+ it('reports unavailable and returns null when the package is absent', async () => {
+ expect(await latticeAvailable()).toBe(false); // optional dep not installed
+ expect(await latticeEmbed('hello world')).toBeNull(); // β†’ caller falls through to next tier
+ expect(await latticeEmbed('x', 'qwen3-0.6b')).toBeNull(); // GPU model path also degrades
+ expect(latticeModels()).toEqual([]); // no models advertised until available
+ });
+
+ it('exposes a configurable package specifier and a default model', () => {
+ expect(LATTICE_WASM_PKG).toContain('lattice'); // overridable via RUFLO_LATTICE_WASM_PKG
+ expect(DEFAULT_LATTICE_MODEL).toBeTruthy(); // selectable via RUFLO_EMBED_MODEL
+ });
+});
diff --git a/v3/@claude-flow/cli/src/mcp-tools/neural-tools.ts b/v3/@claude-flow/cli/src/mcp-tools/neural-tools.ts
index 85105b4c02..3fa2ec2fcc 100644
--- a/v3/@claude-flow/cli/src/mcp-tools/neural-tools.ts
+++ b/v3/@claude-flow/cli/src/mcp-tools/neural-tools.ts
@@ -97,14 +97,33 @@ function ensureEmbeddings(): Promise<void> {
if (embeddingsPromise) return embeddingsPromise;
embeddingsPromise = (async () => {
try {
+ // Tier -1 (PRIMARY): Lattice WASM β€” real multi-model semantic embeddings
+ // (miniLM / bge / paraphrase-miniLM / GPU qwen3-0.6b) ahead of everything.
+ // Optional + FAIL-CLOSED: absent/init-fail β‡’ fall straight through to the
+ // existing ruvector-ONNX β†’ hash tiers with zero regression.
+ try {
+ const lat = await import('../ruvector/lattice-wasm.js').catch(() => null);
+ if (lat && await lat.latticeAvailable()) {
+ const model = lat.DEFAULT_LATTICE_MODEL;
+ realEmbeddings = {
+ embed: async (text: string) => {
+ const v = await lat.latticeEmbed(text, model);
+ if (!v || !v.length) throw new Error('lattice embed failed'); // β†’ generateEmbedding falls to next tier
+ return v;
+ },
+ };
+ embeddingServiceName = `lattice-wasm/${model} (${lat.latticeModels().length} model${lat.latticeModels().length === 1 ? '' : 's'})`;
+ }
+ } catch { /* lattice absent β€” fall through */ }
+
// Tier 0: [email protected] β€” bundled all-MiniLM-L6-v2 + parallel worker pool.
// Probe with isOnnxAvailable() and verify an actual embed succeeds (avoids
// the type-load-success-but-runtime-fails trap from ADR-086). The probe now
// runs on first embed request instead of at import time.
// NOTE: ruvector's embed() returns `{embedding, dimension, timeMs}` β€” we
// unwrap to plain number[] for the shared interface.
- const rv = await import('ruvector').catch(() => null) as any;
- if (rv?.embed && typeof rv.embed === 'function' && rv.isOnnxAvailable?.()) {
+ const rv = !realEmbeddings ? await import('ruvector').catch(() => null) as any : null;
+ if (!realEmbeddings && rv?.embed && typeof rv.embed === 'function' && rv.isOnnxAvailable?.()) {
try {
if (typeof rv.initOnnxEmbedder === 'function') await rv.initOnnxEmbedder();
const probe = await rv.embed('probe');
diff --git a/v3/@claude-flow/cli/src/ruvector/lattice-wasm.ts b/v3/@claude-flow/cli/src/ruvector/lattice-wasm.ts
new file mode 100644
index 0000000000..a2cda46b8c
--- /dev/null
+++ b/v3/@claude-flow/cli/src/ruvector/lattice-wasm.ts
@@ -0,0 +1,126 @@
+/**
+ * Lattice WASM embedder adapter β€” the primary embedding tier (ADR: embedding
+ * substrate upgrade). Replaces hash placeholders with real semantic embeddings
+ * and adds multiple models (miniLM, bge, multi-paraphrase-miniLM, GPU qwen3-0.6B).
+ *
+ * Built on the proven `@ruvector/ruvllm-wasm` optional-dependency convention:
+ * - dynamically imported (never a hard dependency),
+ * - WASM initialized from bundled bytes,
+ * - fully FAIL-CLOSED: if the package is absent, the WASM fails to init, or the
+ * embed API differs, `latticeAvailable()` returns false and callers fall
+ * through to the existing ruvector-ONNX β†’ hash tiers with ZERO regression.
+ *
+ * The package specifier is configurable (`RUFLO_LATTICE_WASM_PKG`) so the exact
+ * published name can be set without a code change; the API is probed tolerantly.
+ * Opt-in for the GPU model: qwen3 is only selected when explicitly requested.
+ */
+import { createRequire } from 'module';
+import { readFileSync } from 'fs';
+
+const require_ = createRequire(import.meta.url);
+
+/** Default package name (ruvnet WASM convention); override with RUFLO_LATTICE_WASM_PKG. */
+export const LATTICE_WASM_PKG = process.env.RUFLO_LATTICE_WASM_PKG || '@ruvector/lattice-wasm';
+
+export type LatticeModel = 'minilm' | 'bge' | 'paraphrase-minilm' | 'qwen3-0.6b' | string;
+export const DEFAULT_LATTICE_MODEL: LatticeModel = (process.env.RUFLO_EMBED_MODEL as LatticeModel) || 'minilm';
+
+/* eslint-disable @typescript-eslint/no-explicit-any */
+let _mod: any = null;
+let _ready = false;
+let _probed = false;
+let _available = false;
+let _models: LatticeModel[] = [];
+
+async function loadModule(): Promise<any> {
+ if (_mod) return _mod;
+ const spec: string = LATTICE_WASM_PKG;
+ _mod = await import(spec).catch(() => null); // optional β€” absent β‡’ null β‡’ unavailable
+ return _mod;
+}
+
+async function ensureInit(): Promise<boolean> {
+ if (_ready) return true;
+ const mod = await loadModule();
+ if (!mod) return false;
+ try {
+ // ruvnet WASM convention: initSync({ module: <wasm bytes> }); tolerate variants.
+ if (!_ready && typeof mod.initSync === 'function') {
+ let wasmBytes: Buffer | undefined;
+ for (const cand of ['lattice_wasm_bg.wasm', 'lattice_bg.wasm', 'index_bg.wasm']) {
+ try { wasmBytes = readFileSync(require_.resolve(`${LATTICE_WASM_PKG}/${cand}`)); break; } catch { /* try next */ }
+ }
+ mod.initSync(wasmBytes ? { module: wasmBytes } : undefined);
+ } else if (typeof mod.default === 'function') {
+ await mod.default(); // some wasm-bindgen builds export an async default init
+ }
+ _ready = true;
+ return true;
+ } catch {
+ return false; // init failed β‡’ fail closed
+ }
+}
+
+/** Extract a plain number[] from whatever shape the module's embed returns. */
+function toVec(r: unknown): number[] | null {
+ const v = (r && typeof r === 'object' && 'embedding' in (r as any)) ? (r as any).embedding : r;
+ if (!v) return null;
+ if (Array.isArray(v)) return v as number[];
+ if ((v as ArrayLike<number>).length !== undefined) return Array.from(v as ArrayLike<number>);
+ return null;
+}
+
+/** Is the Lattice WASM embedder installed + initializable? Cached; never throws. */
+export async function latticeAvailable(): Promise<boolean> {
+ if (_probed) return _available;
+ _probed = true;
+ try {
+ if (!(await ensureInit())) { _available = false; return false; }
+ const mod = _mod;
+ // discover models (tolerant): listModels() / models / MODELS
+ try {
+ const list = typeof mod.listModels === 'function' ? mod.listModels() : (mod.models ?? mod.MODELS);
+ if (Array.isArray(list) && list.length) _models = list as LatticeModel[];
+ } catch { /* leave default */ }
+ if (!_models.length) _models = [DEFAULT_LATTICE_MODEL];
+ // verify an actual embed succeeds (the ADR-086 "loads but runtime-fails" trap).
+ const probe = await latticeEmbedRaw('probe', DEFAULT_LATTICE_MODEL);
+ _available = !!probe && probe.length > 0;
+ return _available;
+ } catch {
+ _available = false;
+ return false;
+ }
+}
+
+/** The models Lattice reports (empty until availability is probed). */
+export function latticeModels(): LatticeModel[] { return [..._models]; }
+
+async function latticeEmbedRaw(text: string, model: LatticeModel): Promise<number[] | null> {
+ const mod = _mod;
+ if (!mod) return null;
+ // tolerant API probing across plausible wasm-bindgen surfaces.
+ const attempts: Array<() => Promise<unknown> | unknown> = [
+ () => typeof mod.embed === 'function' ? mod.embed(text, model) : undefined,
+ () => typeof mod.embed === 'function' ? mod.embed(text) : undefined,
+ () => typeof mod.embedText === 'function' ? mod.embedText(text, model) : undefined,
+ () => typeof mod.Embedder === 'function' ? new mod.Embedder(model).embed(text) : undefined,
+ ];
+ for (const a of attempts) {
+ try { const r = await a(); const v = toVec(r); if (v) return v; } catch { /* try next surface */ }
+ }
+ return null;
+}
+
+/**
+ * Embed `text` with `model` via Lattice WASM. Returns null on any failure so the
+ * caller can fall through to the next tier. Never throws.
+ */
+export async function latticeEmbed(text: string, model: LatticeModel = DEFAULT_LATTICE_MODEL): Promise<number[] | null> {
+ try {
+ if (!(await latticeAvailable())) return null;
+ return await latticeEmbedRaw(text, model);
+ } catch {
+ return null;
+ }
+}