claude-flow 3.7.0-alpha.50 → 3.7.0-alpha.52

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "claude-flow",
-  "version": "3.7.0-alpha.50",
+  "version": "3.7.0-alpha.52",
   "description": "Ruflo - Enterprise AI agent orchestration for Claude Code. Deploy 60+ specialized agents in coordinated swarms with self-learning, fault-tolerant consensus, vector memory, and MCP integration",
   "main": "dist/index.js",
   "type": "module",

package/v3/@claude-flow/cli/dist/src/__probe.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=__probe.d.ts.map

package/v3/@claude-flow/cli/dist/src/__probe.js

@@ -0,0 +1,5 @@
+import * as e from '@claude-flow/embeddings';
+const fn = e.mmrRerank;
+const f2 = e.averagePairwiseSimilarity;
+console.log(fn, f2);
+//# sourceMappingURL=__probe.js.map

package/v3/@claude-flow/cli/dist/src/mcp-tools/embeddings-tools.js

@@ -1279,5 +1279,290 @@ export const embeddingsTools = [
             };
         },
     },
+    // ============================================================
+    // ADR-121 Phase 11 — RRF ensemble retrieval (alpha.52 CLI)
+    // ============================================================
+    //
+    // Question-reformulation pipelines produce N parallel result lists.
+    // Reciprocal Rank Fusion (Cormack-Clarke-Büttcher 2009) fuses them
+    // into a single ranking without needing score comparability across
+    // lists. Composes `embeddings_search_text_batch` (N parallel
+    // searches) with `reciprocalRankFusion` (rank-level merge).
+    //
+    // Standard production ensemble-RAG pattern. Pairs naturally with
+    // LLM query rewriting upstream (expand "how does auth work?" into
+    // {"how does authentication work?", "what's the login flow?",
+    //  "describe the OAuth2 handshake"} → batch search each →
+    // RRF-fuse) — recovers more relevant docs than a single search.
+    {
+        name: 'embeddings_search_text_ensemble',
+        description: "Embed N text query variants, search a named AnnRouter handle for each in parallel, then RRF-fuse (Reciprocal Rank Fusion, Cormack-Clarke-Büttcher 2009) the N hit-lists into a single merged top-k ranking. Standard production shape for question-reformulation RAG: agents expand one user question into N variants, retrieve top-k for each, get a single fused list back — items appearing high in MORE variants outrank items appearing high in only one. Returns fused hits with per-list ranks for transparency + aggregate latency. λ-equivalent here is `kRrf` (default 60 per SIGIR 2009). Per-list `listWeights` available for biased ensemble (e.g. weight the original-query list 2× over reformulations). For non-fused multi-query results use embeddings_search_text_batch; for single-query diverse retrieval use embeddings_search_text_diverse.",
+        category: 'embeddings',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                texts: {
+                    type: 'array',
+                    items: { type: 'string' },
+                    description: 'Array of query text variants. Order preserved in per-list ranks.',
+                },
+                name: { type: 'string', description: 'AnnRouter handle name (set by embeddings_ann_router_build).' },
+                k: { type: 'number', description: 'Number of fused results to return.' },
+                perQueryK: {
+                    type: 'number',
+                    description: 'Top-k per query before fusion. Default 2*k. Larger = wider candidate pool, more compute.',
+                },
+                kRrf: {
+                    type: 'number',
+                    description: 'RRF smoothing constant. Default 60 (SIGIR 2009). Smaller = top-rank dominance.',
+                },
+                listWeights: {
+                    type: 'array',
+                    items: { type: 'number' },
+                    description: 'Per-query weights. Length must equal texts.length. Default = 1 each.',
+                },
+            },
+            required: ['texts', 'name', 'k'],
+        },
+        handler: async (input) => {
+            const config = loadConfig();
+            if (!config) {
+                return { success: false, error: 'Embeddings not initialized. Run embeddings_init first.' };
+            }
+            const texts = input.texts;
+            const name = input.name;
+            const k = input.k;
+            const perQueryK = typeof input.perQueryK === 'number' && input.perQueryK >= 1
+                ? input.perQueryK
+                : Math.max(k * 2, k);
+            const kRrf = typeof input.kRrf === 'number' && input.kRrf > 0 ? input.kRrf : 60;
+            const listWeights = Array.isArray(input.listWeights) ? input.listWeights : undefined;
+            if (!Array.isArray(texts) || texts.length === 0) {
+                return { success: false, error: 'texts must be a non-empty array' };
+            }
+            if (!Number.isInteger(k) || k < 1) {
+                return { success: false, error: 'k must be a positive integer' };
+            }
+            for (let i = 0; i < texts.length; i++) {
+                if (typeof texts[i] !== 'string') {
+                    return { success: false, error: `texts[${i}] is not a string` };
+                }
+            }
+            if (listWeights && listWeights.length !== texts.length) {
+                return {
+                    success: false,
+                    error: `listWeights.length (${listWeights.length}) must match texts.length (${texts.length})`,
+                };
+            }
+            const { getAnnRouterRegistry } = await import('../memory/ann-router-registry.js');
+            const registry = getAnnRouterRegistry();
+            // Stage 1 — embed all queries in parallel.
+            const embedT0 = Date.now();
+            let embeddings;
+            try {
+                embeddings = await Promise.all(texts.map(t => generateRealEmbedding(t, config.dimension)));
+            }
+            catch (err) {
+                return { success: false, name, error: `batch embed failed: ${err instanceof Error ? err.message : String(err)}` };
+            }
+            const embeddingMs = Date.now() - embedT0;
+            // Stage 2 — search each variant in parallel. Per-query errors
+            // become empty result lists (the variant just doesn't contribute
+            // to the fusion) rather than aborting the ensemble.
+            const searchT0 = Date.now();
+            const perQueryResults = await Promise.all(embeddings.map(async (emb, i) => {
+                try {
+                    const hits = await registry.search(name, new Float32Array(emb), perQueryK);
+                    return { index: i, text: texts[i], hits, success: true };
+                }
+                catch (err) {
+                    return {
+                        index: i,
+                        text: texts[i],
+                        hits: [],
+                        success: false,
+                        error: err instanceof Error ? err.message : String(err),
+                    };
+                }
+            }));
+            const searchMs = Date.now() - searchT0;
+            // Stage 3 — RRF fusion across the per-query lists.
+            const { reciprocalRankFusion } = await import('@claude-flow/embeddings/rrf');
+            const fuseT0 = Date.now();
+            const lists = perQueryResults.map(r => r.hits.map(h => ({ id: h.id, payload: { score: h.score } })));
+            const fused = reciprocalRankFusion(lists, { k, kRrf, listWeights });
+            const fuseMs = Date.now() - fuseT0;
+            const successCount = perQueryResults.filter(r => r.success).length;
+            return {
+                success: successCount === perQueryResults.length,
+                name,
+                k,
+                queryCount: texts.length,
+                perQueryK,
+                kRrf,
+                listWeights: listWeights ?? null,
+                successCount,
+                failureCount: perQueryResults.length - successCount,
+                hits: fused,
+                perQuery: perQueryResults.map(r => ({
+                    index: r.index,
+                    text: r.text,
+                    success: r.success,
+                    hitCount: r.hits.length,
+                    error: r.success ? undefined : r.error,
+                })),
+                latency: {
+                    embeddingMs,
+                    searchMs,
+                    fuseMs,
+                    totalMs: embeddingMs + searchMs + fuseMs,
+                    avgPerQueryMs: Math.round(((embeddingMs + searchMs) / texts.length) * 100) / 100,
+                },
+                embeddingDimension: embeddings[0]?.length,
+            };
+        },
+    },
+    // ============================================================
+    // ADR-121 Phase 10 — MMR diversity rerank (alpha.51 CLI)
+    // ============================================================
+    //
+    // Plain top-k often returns near-duplicate chunks. MMR picks a
+    // diversified top-k by trading off relevance against redundancy
+    // (Carbonell & Goldstein 1998). Fetches `fetchMultiplier * k`
+    // candidates from AnnRouter, then reranks to k via mmrRerank.
+    //
+    // Pairs with embeddings_search_text (relevance only). Same caller
+    // contract — text + handle name + k — plus optional `lambda` and
+    // `fetchMultiplier`. Returns diversity stats so callers can
+    // confirm the rerank actually spread the result.
+    {
+        name: 'embeddings_search_text_diverse',
+        description: "Embed a text query, fetch a wider candidate pool from a named AnnRouter handle, and rerank with MMR (Maximal Marginal Relevance) to return a diverse top-k. Use when plain top-k tends to return near-duplicates (e.g. corpora with many paraphrased chunks). λ controls relevance/diversity tradeoff: 1.0 = same as embeddings_search_text, 0.5 = balanced (default), 0.0 = pure diversity. fetchMultiplier controls how many candidates to consider before reranking (default 5×k). Returns hits + diversification stats (averagePairwiseSimilarity — lower is more diverse). For plain (non-diversified) RAG use embeddings_search_text.",
+        category: 'embeddings',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                text: { type: 'string', description: 'Query text. Will be embedded inline.' },
+                name: { type: 'string', description: 'AnnRouter handle name (set by embeddings_ann_router_build).' },
+                k: { type: 'number', description: 'Number of diverse nearest neighbors to return.' },
+                lambda: {
+                    type: 'number',
+                    description: 'Relevance/diversity tradeoff in [0,1]. 1=pure relevance, 0=pure diversity. Default 0.5.',
+                },
+                fetchMultiplier: {
+                    type: 'number',
+                    description: 'Candidate pool size = fetchMultiplier * k. Larger = more candidates to diversify from, more compute. Default 5.',
+                },
+            },
+            required: ['text', 'name', 'k'],
+        },
+        handler: async (input) => {
+            const config = loadConfig();
+            if (!config) {
+                return { success: false, error: 'Embeddings not initialized. Run embeddings_init first.' };
+            }
+            const text = input.text;
+            const name = input.name;
+            const k = input.k;
+            const lambda = typeof input.lambda === 'number' ? input.lambda : 0.5;
+            const fetchMultiplier = typeof input.fetchMultiplier === 'number' && input.fetchMultiplier >= 1
+                ? input.fetchMultiplier
+                : 5;
+            const tv = validateText(text, 'text');
+            if (!tv.valid)
+                return { success: false, error: tv.error };
+            if (!Number.isInteger(k) || k < 1) {
+                return { success: false, error: 'k must be a positive integer' };
+            }
+            // Stage 1 — embed the query.
+            const embedT0 = Date.now();
+            let embedding;
+            try {
+                embedding = await generateRealEmbedding(text, config.dimension);
+            }
+            catch (err) {
+                return { success: false, error: `embed failed: ${err instanceof Error ? err.message : String(err)}` };
+            }
+            const embeddingMs = Date.now() - embedT0;
+            const queryVec = new Float32Array(embedding);
+            // Stage 2 — fetch a wider pool of candidates from the router.
+            const { getAnnRouterRegistry } = await import('../memory/ann-router-registry.js');
+            const registry = getAnnRouterRegistry();
+            const fetchK = Math.max(k, Math.floor(k * fetchMultiplier));
+            const searchT0 = Date.now();
+            let candidatesRaw;
+            try {
+                candidatesRaw = await registry.search(name, queryVec, fetchK);
+            }
+            catch (err) {
+                return {
+                    success: false,
+                    name,
+                    error: err instanceof Error ? err.message : String(err),
+                    latency: { embeddingMs, searchMs: 0, rerankMs: 0 },
+                };
+            }
+            const searchMs = Date.now() - searchT0;
+            // Filter to candidates that have a vector (MMR needs it).
+            // Routers that don't surface vectors (rare) degrade to
+            // plain top-k for safety rather than throwing.
+            const candidatesWithVec = candidatesRaw.filter(c => c.vector != null);
+            if (candidatesWithVec.length === 0) {
+                return {
+                    success: true,
+                    name,
+                    k,
+                    hits: candidatesRaw.slice(0, k),
+                    mmr: { applied: false, reason: 'no candidate vectors available — degraded to plain top-k' },
+                    latency: { embeddingMs, searchMs, rerankMs: 0, totalMs: embeddingMs + searchMs },
+                };
+            }
+            // Stage 3 — MMR rerank.
+            // Sub-path import bypasses the index barrel — TS resolves the
+            // mmr.d.ts directly via the './*' export condition, which
+            // sidesteps a stale-cache issue with the aggregate index.d.ts.
+            const { mmrRerank, averagePairwiseSimilarity } = await import('@claude-flow/embeddings/mmr');
+            const rerankT0 = Date.now();
+            const picked = mmrRerank(candidatesWithVec.map(c => ({
+                id: c.id,
+                vector: c.vector,
+                score: c.score,
+                payload: c.payload,
+            })), queryVec, { k, lambda });
+            const rerankMs = Date.now() - rerankT0;
+            const avgPairSim = averagePairwiseSimilarity(picked);
+            // Strip vectors from the response to keep stdout sane.
+            // Callers wanting the vectors can re-fetch via search.
+            const hits = picked.map(p => ({
+                id: p.id,
+                score: p.relevance,
+                mmrScore: p.mmrScore,
+                relevance: p.relevance,
+                redundancy: p.redundancy,
+                pickOrder: p.pickOrder,
+                payload: p.payload,
+            }));
+            return {
+                success: true,
+                name,
+                k,
+                hits,
+                mmr: {
+                    applied: true,
+                    lambda,
+                    fetchMultiplier,
+                    candidatesConsidered: candidatesWithVec.length,
+                    averagePairwiseSimilarity: avgPairSim,
+                },
+                latency: {
+                    embeddingMs,
+                    searchMs,
+                    rerankMs,
+                    totalMs: embeddingMs + searchMs + rerankMs,
+                },
+                embeddingDimension: embedding.length,
+            };
+        },
+    },
 ];
 //# sourceMappingURL=embeddings-tools.js.map

package/v3/@claude-flow/cli/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@claude-flow/cli",
-  "version": "3.7.0-alpha.50",
+  "version": "3.7.0-alpha.52",
   "type": "module",
   "description": "Ruflo CLI - Enterprise AI agent orchestration with 60+ specialized agents, swarm coordination, MCP server, self-learning hooks, and vector memory for Claude Code",
   "main": "dist/src/index.js",
@@ -104,14 +104,14 @@
     "semver": "^7.6.0",
     "yaml": "^2.8.0",
     "@claude-flow/memory": "^3.0.0-alpha.17",
-    "@claude-flow/embeddings": "^3.0.0-alpha.26",
+    "@claude-flow/embeddings": "^3.0.0-alpha.32",
     "@claude-flow/security": "^3.0.0-alpha.8",
     "@claude-flow/swarm": "^3.0.0-alpha.8"
   },
   "optionalDependencies": {
     "@claude-flow/aidefence": "^3.0.2",
     "@claude-flow/codex": "^3.0.0-alpha.8",
-    "@claude-flow/embeddings": "^3.0.0-alpha.26",
+    "@claude-flow/embeddings": "^3.0.0-alpha.32",
     "@claude-flow/guidance": "^3.0.0-alpha.1",
     "@claude-flow/memory": "^3.0.0-alpha.17",
     "@claude-flow/plugin-gastown-bridge": "^0.1.3",