claude-flow 3.7.0-alpha.47 → 3.7.0-alpha.49

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "claude-flow",
-  "version": "3.7.0-alpha.47",
+  "version": "3.7.0-alpha.49",
   "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/mcp-tools/embeddings-tools.js

@@ -1029,5 +1029,162 @@ export const embeddingsTools = [
             return { success: true, snapshots: registry.list() };
         },
     },
+    // ============================================================
+    // ADR-121 Phase 8 (CLI) — AnnRouter MCP tools (alpha.48)
+    // ============================================================
+    //
+    // Composition layer: agents declare the workload shape
+    // (corpusSize/persistent/mutable) and the router picks between
+    // HNSW / RaBitQ / DiskANN. The decision is returned to the agent
+    // so they can see what was picked + why (useful for routing
+    // explanations + cost attribution).
+    {
+        name: 'embeddings_ann_router_build',
+        description: "Build an ANN index using AnnRouter — auto-selects between HNSW / RaBitQ / DiskANN based on workload. Use when you have a corpus to index and don't want to choose between the three backings yourself — declare the workload ({corpusSize, persistent, mutable}) and the router picks. Pair with embeddings_ann_router_search to query, embeddings_ann_router_status to see what was picked. For direct DiskANN control (e.g. for known billion-scale persistent indexes), use embeddings_diskann_build instead.",
+        category: 'embeddings',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                name: { type: 'string', description: 'Handle name. Must be unique per process.' },
+                workload: {
+                    type: 'object',
+                    properties: {
+                        corpusSize: { type: 'number', description: 'Approximate corpus size.' },
+                        dimension: { type: 'number' },
+                        persistent: { type: 'boolean', description: 'Survive process restarts? Forces DiskANN.' },
+                        mutable: { type: 'boolean', description: 'Streaming inserts/deletes after build? Prefers HNSW.' },
+                        storagePath: { type: 'string', description: 'On-disk path; required when persistent=true.' },
+                    },
+                    required: ['corpusSize', 'dimension'],
+                },
+                entries: {
+                    type: 'array',
+                    items: {
+                        type: 'object',
+                        properties: { id: { type: 'string' }, vector: { type: 'array', items: { type: 'number' } } },
+                        required: ['id', 'vector'],
+                    },
+                },
+            },
+            required: ['name', 'workload', 'entries'],
+        },
+        handler: async (input) => {
+            const { getAnnRouterRegistry } = await import('../memory/ann-router-registry.js');
+            const registry = getAnnRouterRegistry();
+            try {
+                const result = await registry.build({
+                    name: input.name,
+                    workload: input.workload,
+                    entries: input.entries,
+                });
+                return { success: true, name: input.name, ...result };
+            }
+            catch (err) {
+                return { success: false, name: input.name, error: err instanceof Error ? err.message : String(err) };
+            }
+        },
+    },
+    {
+        name: 'embeddings_ann_router_search',
+        description: 'Search a named AnnRouter handle for the k nearest neighbors. Returns hits with the routing-decision-aware score (cosine sim for HNSW; L2 distance for RaBitQ/DiskANN — interpret relative to embeddings_ann_router_status). For raw DiskANN search use embeddings_diskann_search; for raw HNSW use SearchableEmbeddingCache.search directly.',
+        category: 'embeddings',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                name: { type: 'string' },
+                vector: { type: 'array', items: { type: 'number' } },
+                k: { type: 'number' },
+            },
+            required: ['name', 'vector', 'k'],
+        },
+        handler: async (input) => {
+            const { getAnnRouterRegistry } = await import('../memory/ann-router-registry.js');
+            const registry = getAnnRouterRegistry();
+            try {
+                const hits = await registry.search(input.name, new Float32Array(input.vector), input.k);
+                return { success: true, name: input.name, k: input.k, hits };
+            }
+            catch (err) {
+                return { success: false, name: input.name, error: err instanceof Error ? err.message : String(err) };
+            }
+        },
+    },
+    {
+        name: 'embeddings_ann_router_status',
+        description: 'List all AnnRouter handles, each with its decided backing, routing reason, and current count. Use to inventory routed indexes + confirm the router picked what you expected. For peer-dep family availability use embeddings_check_ruvector_sidecar.',
+        category: 'embeddings',
+        inputSchema: { type: 'object', properties: {} },
+        handler: async () => {
+            const { getAnnRouterRegistry } = await import('../memory/ann-router-registry.js');
+            const registry = getAnnRouterRegistry();
+            return { success: true, handles: registry.list() };
+        },
+    },
+    // ============================================================
+    // ADR-121 Phase 9 — one-call RAG retrieval (alpha.49 CLI)
+    // ============================================================
+    {
+        name: 'embeddings_search_text',
+        description: "Embed a text query and search a named AnnRouter handle in a single call — the standard RAG retrieval shape. Eliminates the two-call dance of `embeddings_generate` then `embeddings_ann_router_search`. Returns hits plus per-stage latency (embeddingMs + searchMs) so callers can attribute cost. Pair with embeddings_ann_router_build to build the index first. For raw vector input (no embedding step) use embeddings_ann_router_search.",
+        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 nearest neighbors.' },
+            },
+            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 tv = validateText(text, 'text');
+            if (!tv.valid)
+                return { success: false, error: tv.error };
+            // 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;
+            // Stage 2 — search the named router handle.
+            const { getAnnRouterRegistry } = await import('../memory/ann-router-registry.js');
+            const registry = getAnnRouterRegistry();
+            const searchT0 = Date.now();
+            try {
+                const hits = await registry.search(name, new Float32Array(embedding), k);
+                const searchMs = Date.now() - searchT0;
+                return {
+                    success: true,
+                    name,
+                    k,
+                    hits,
+                    latency: { embeddingMs, searchMs, totalMs: embeddingMs + searchMs },
+                    embeddingDimension: embedding.length,
+                };
+            }
+            catch (err) {
+                return {
+                    success: false,
+                    name,
+                    error: err instanceof Error ? err.message : String(err),
+                    latency: { embeddingMs, searchMs: 0 },
+                };
+            }
+        },
+    },
 ];
 //# sourceMappingURL=embeddings-tools.js.map

package/v3/@claude-flow/cli/dist/src/memory/ann-router-registry.d.ts

@@ -0,0 +1,61 @@
+/**
+ * Process-level registry of named AnnRouter handles backing the
+ * `embeddings_ann_router_*` MCP tools.
+ *
+ * Mirrors the shape of `diskann-registry.ts` but for the unified
+ * routing layer. Lifecycle:
+ *   - `build({ name, workload, entries })` creates an AnnRouter with
+ *     the given workload, adds the entries, calls build, stashes the
+ *     handle under `name`. Returns the routing decision so agents
+ *     can see which backing was picked + why.
+ *   - `search(name, vector, k)` runs top-k against the named handle.
+ *   - `list()` returns all handles with their decision + count.
+ *
+ * ADR-121 Phase 8 (CLI) — cli alpha.48.
+ */
+export interface AnnRouterBuildInput {
+    readonly name: string;
+    readonly workload: {
+        readonly corpusSize: number;
+        readonly dimension: number;
+        readonly persistent?: boolean;
+        readonly mutable?: boolean;
+        readonly storagePath?: string;
+    };
+    readonly entries: ReadonlyArray<{
+        id: string;
+        vector: number[];
+    }>;
+}
+export interface AnnRouterDecisionView {
+    readonly backing: string;
+    readonly reason: string;
+    readonly degraded: boolean;
+    readonly degradationReason?: string;
+}
+export interface AnnRouterBuildResult {
+    readonly decision: AnnRouterDecisionView;
+    readonly count: number;
+    readonly buildMs: number;
+}
+export interface AnnRouterSearchHit {
+    readonly id: string;
+    readonly score: number;
+}
+export interface AnnRouterHandleInfo {
+    readonly name: string;
+    readonly decision: AnnRouterDecisionView;
+    readonly count: number;
+}
+declare class AnnRouterRegistry {
+    private readonly entries;
+    private ctor;
+    private loadCtor;
+    build(input: AnnRouterBuildInput): Promise<AnnRouterBuildResult>;
+    search(name: string, vector: Float32Array, k: number): Promise<AnnRouterSearchHit[]>;
+    list(): AnnRouterHandleInfo[];
+    clear(): void;
+}
+export declare function getAnnRouterRegistry(): AnnRouterRegistry;
+export {};
+//# sourceMappingURL=ann-router-registry.d.ts.map

package/v3/@claude-flow/cli/dist/src/memory/ann-router-registry.js

@@ -0,0 +1,72 @@
+/**
+ * Process-level registry of named AnnRouter handles backing the
+ * `embeddings_ann_router_*` MCP tools.
+ *
+ * Mirrors the shape of `diskann-registry.ts` but for the unified
+ * routing layer. Lifecycle:
+ *   - `build({ name, workload, entries })` creates an AnnRouter with
+ *     the given workload, adds the entries, calls build, stashes the
+ *     handle under `name`. Returns the routing decision so agents
+ *     can see which backing was picked + why.
+ *   - `search(name, vector, k)` runs top-k against the named handle.
+ *   - `list()` returns all handles with their decision + count.
+ *
+ * ADR-121 Phase 8 (CLI) — cli alpha.48.
+ */
+class AnnRouterRegistry {
+    entries = new Map();
+    ctor = null;
+    async loadCtor() {
+        if (this.ctor)
+            return this.ctor;
+        const mod = await import('@claude-flow/embeddings/ann-router');
+        this.ctor = mod.AnnRouter;
+        return this.ctor;
+    }
+    async build(input) {
+        const Ctor = await this.loadCtor();
+        const t0 = Date.now();
+        const router = await Ctor.create(input.workload);
+        const float32 = input.entries.map(e => ({
+            id: e.id,
+            vector: new Float32Array(e.vector),
+        }));
+        await router.add(float32);
+        await router.build();
+        const buildMs = Date.now() - t0;
+        this.entries.set(input.name, { router, decision: router.decision });
+        return {
+            decision: router.decision,
+            count: router.count(),
+            buildMs,
+        };
+    }
+    async search(name, vector, k) {
+        const entry = this.entries.get(name);
+        if (!entry) {
+            throw new Error(`embeddings_ann_router_search: no router named "${name}" — call embeddings_ann_router_build first`);
+        }
+        return entry.router.search(vector, k);
+    }
+    list() {
+        const out = [];
+        for (const [name, entry] of this.entries) {
+            out.push({
+                name,
+                decision: entry.decision,
+                count: entry.router.count(),
+            });
+        }
+        return out;
+    }
+    clear() {
+        this.entries.clear();
+    }
+}
+let singleton = null;
+export function getAnnRouterRegistry() {
+    if (!singleton)
+        singleton = new AnnRouterRegistry();
+    return singleton;
+}
+//# sourceMappingURL=ann-router-registry.js.map

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

@@ -1,6 +1,6 @@
 {
   "name": "@claude-flow/cli",
-  "version": "3.7.0-alpha.47",
+  "version": "3.7.0-alpha.49",
   "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",