π 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
TypeScript agentic-aiagentic-frameworkagentic-workflowagentsai-agentsai-assistantai-skillsautonomous-agentsclaudecodexdsh-pluginharnessmcp-servermulti-agentmulti-agent-systemsnpmskillsswarmswarm-intelligencetypescript
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.tsnew file mode 100644index 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.tsindex 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.tsnew file mode 100644index 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;+ }+}