ruvector 0.2.23 → 0.2.25

package/dist/core/router-wrapper.d.ts

@@ -0,0 +1,75 @@
+/**
+ * Router Wrapper - Semantic router for AI agent intent matching
+ *
+ * Wraps @ruvector/router for vector-based intent classification.
+ * Perfect for hooks to route tasks to the right agent.
+ */
+export declare function isRouterAvailable(): boolean;
+export interface Route {
+    name: string;
+    utterances: string[];
+    metadata?: Record<string, any>;
+}
+export interface RouteMatch {
+    route: string;
+    score: number;
+    metadata?: Record<string, any>;
+}
+/**
+ * Semantic Router for agent task routing
+ */
+export declare class SemanticRouter {
+    private inner;
+    private routes;
+    constructor(options?: {
+        dimension?: number;
+        threshold?: number;
+    });
+    /**
+     * Set the embedder function for converting text to vectors.
+     * Required before match() can accept string input.
+     */
+    setEmbedder(embedder: (text: string) => Promise<Float32Array>): void;
+    /**
+     * Add a route with example utterances (sync, requires pre-computed embedding)
+     */
+    addRoute(name: string, utterances: string[], metadata?: Record<string, any>, embedding?: Float32Array | number[]): void;
+    /**
+     * Add a route with automatic embedding computation (requires setEmbedder)
+     */
+    addRouteAsync(name: string, utterances: string[], metadata?: Record<string, any>): Promise<void>;
+    /**
+     * Add multiple routes at once
+     */
+    addRoutes(routes: Route[]): void;
+    /**
+     * Match input to best route (async, accepts string if embedder is set, or Float32Array)
+     */
+    match(input: string | Float32Array): Promise<RouteMatch | null>;
+    /**
+     * Get top-k route matches (async)
+     */
+    matchTopK(input: string | Float32Array, k?: number): Promise<RouteMatch[]>;
+    /**
+     * Match with a pre-computed embedding (synchronous)
+     */
+    matchWithEmbedding(embedding: Float32Array, k?: number): RouteMatch[];
+    /**
+     * Get all registered routes
+     */
+    getRoutes(): Route[];
+    /**
+     * Remove a route
+     */
+    removeRoute(name: string): boolean;
+    /**
+     * Clear all routes
+     */
+    clear(): void;
+}
+/**
+ * Create a pre-configured agent router for hooks
+ */
+export declare function createAgentRouter(): SemanticRouter;
+export default SemanticRouter;
+//# sourceMappingURL=router-wrapper.d.ts.map

package/dist/core/router-wrapper.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"router-wrapper.d.ts","sourceRoot":"","sources":["../../src/core/router-wrapper.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAqBH,wBAAgB,iBAAiB,IAAI,OAAO,CAO3C;AAED,MAAM,WAAW,KAAK;IACpB,IAAI,EAAE,MAAM,CAAC;IACb,UAAU,EAAE,MAAM,EAAE,CAAC;IACrB,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC;CAChC;AAED,MAAM,WAAW,UAAU;IACzB,KAAK,EAAE,MAAM,CAAC;IACd,KAAK,EAAE,MAAM,CAAC;IACd,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC;CAChC;AAED;;GAEG;AACH,qBAAa,cAAc;IACzB,OAAO,CAAC,KAAK,CAAM;IACnB,OAAO,CAAC,MAAM,CAAiC;gBAEnC,OAAO,GAAE;QAAE,SAAS,CAAC,EAAE,MAAM,CAAC;QAAC,SAAS,CAAC,EAAE,MAAM,CAAA;KAAO;IAQpE;;;OAGG;IACH,WAAW,CAAC,QAAQ,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,OAAO,CAAC,YAAY,CAAC,GAAG,IAAI;IAIpE;;OAEG;IACH,QAAQ,CAAC,IAAI,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,EAAE,EAAE,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,EAAE,SAAS,CAAC,EAAE,YAAY,GAAG,MAAM,EAAE,GAAG,IAAI;IAUvH;;OAEG;IACG,aAAa,CAAC,IAAI,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,EAAE,EAAE,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC;IAStG;;OAEG;IACH,SAAS,CAAC,MAAM,EAAE,KAAK,EAAE,GAAG,IAAI;IAMhC;;OAEG;IACG,KAAK,CAAC,KAAK,EAAE,MAAM,GAAG,YAAY,GAAG,OAAO,CAAC,UAAU,GAAG,IAAI,CAAC;IAWrE;;OAEG;IACG,SAAS,CAAC,KAAK,EAAE,MAAM,GAAG,YAAY,EAAE,CAAC,GAAE,MAAU,GAAG,OAAO,CAAC,UAAU,EAAE,CAAC;IASnF;;OAEG;IACH,kBAAkB,CAAC,SAAS,EAAE,YAAY,EAAE,CAAC,GAAE,MAAU,GAAG,UAAU,EAAE;IASxE;;OAEG;IACH,SAAS,IAAI,KAAK,EAAE;IAIpB;;OAEG;IACH,WAAW,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO;IAMlC;;OAEG;IACH,KAAK,IAAI,IAAI;CAId;AAED;;GAEG;AACH,wBAAgB,iBAAiB,IAAI,cAAc,CA8FlD;AAED,eAAe,cAAc,CAAC"}

package/dist/core/router-wrapper.js

@@ -0,0 +1,243 @@
+"use strict";
+/**
+ * Router Wrapper - Semantic router for AI agent intent matching
+ *
+ * Wraps @ruvector/router for vector-based intent classification.
+ * Perfect for hooks to route tasks to the right agent.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SemanticRouter = void 0;
+exports.isRouterAvailable = isRouterAvailable;
+exports.createAgentRouter = createAgentRouter;
+let routerModule = null;
+let loadError = null;
+function getRouterModule() {
+    if (routerModule)
+        return routerModule;
+    if (loadError)
+        throw loadError;
+    try {
+        routerModule = require('@ruvector/router');
+        return routerModule;
+    }
+    catch (e) {
+        loadError = new Error(`@ruvector/router not installed: ${e.message}\n` +
+            `Install with: npm install @ruvector/router`);
+        throw loadError;
+    }
+}
+function isRouterAvailable() {
+    try {
+        getRouterModule();
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Semantic Router for agent task routing
+ */
+class SemanticRouter {
+    constructor(options = {}) {
+        this.routes = new Map();
+        const router = getRouterModule();
+        this.inner = new router.SemanticRouter({
+            dimension: options.dimension ?? 384,
+            threshold: options.threshold ?? 0.7,
+        });
+    }
+    /**
+     * Set the embedder function for converting text to vectors.
+     * Required before match() can accept string input.
+     */
+    setEmbedder(embedder) {
+        this.inner.setEmbedder(embedder);
+    }
+    /**
+     * Add a route with example utterances (sync, requires pre-computed embedding)
+     */
+    addRoute(name, utterances, metadata, embedding) {
+        this.routes.set(name, { name, utterances, metadata });
+        this.inner.addIntent({
+            name,
+            utterances,
+            metadata,
+            embedding,
+        });
+    }
+    /**
+     * Add a route with automatic embedding computation (requires setEmbedder)
+     */
+    async addRouteAsync(name, utterances, metadata) {
+        this.routes.set(name, { name, utterances, metadata });
+        await this.inner.addIntentAsync({
+            name,
+            utterances,
+            metadata,
+        });
+    }
+    /**
+     * Add multiple routes at once
+     */
+    addRoutes(routes) {
+        for (const route of routes) {
+            this.addRoute(route.name, route.utterances, route.metadata);
+        }
+    }
+    /**
+     * Match input to best route (async, accepts string if embedder is set, or Float32Array)
+     */
+    async match(input) {
+        const results = await this.inner.route(input, 1);
+        if (!results || results.length === 0)
+            return null;
+        return {
+            route: results[0].intent,
+            score: results[0].score,
+            metadata: results[0].metadata,
+        };
+    }
+    /**
+     * Get top-k route matches (async)
+     */
+    async matchTopK(input, k = 3) {
+        const results = await this.inner.route(input, k);
+        return (results || []).map((r) => ({
+            route: r.intent,
+            score: r.score,
+            metadata: r.metadata,
+        }));
+    }
+    /**
+     * Match with a pre-computed embedding (synchronous)
+     */
+    matchWithEmbedding(embedding, k = 1) {
+        const results = this.inner.routeWithEmbedding(embedding, k);
+        return (results || []).map((r) => ({
+            route: r.intent,
+            score: r.score,
+            metadata: r.metadata,
+        }));
+    }
+    /**
+     * Get all registered routes
+     */
+    getRoutes() {
+        return Array.from(this.routes.values());
+    }
+    /**
+     * Remove a route
+     */
+    removeRoute(name) {
+        if (!this.routes.has(name))
+            return false;
+        this.routes.delete(name);
+        return this.inner.removeIntent(name);
+    }
+    /**
+     * Clear all routes
+     */
+    clear() {
+        this.routes.clear();
+        this.inner.clear();
+    }
+}
+exports.SemanticRouter = SemanticRouter;
+/**
+ * Create a pre-configured agent router for hooks
+ */
+function createAgentRouter() {
+    const router = new SemanticRouter({ threshold: 0.6 });
+    // Add common agent routes
+    router.addRoutes([
+        {
+            name: 'coder',
+            utterances: [
+                'implement feature',
+                'write code',
+                'create function',
+                'add method',
+                'build component',
+                'fix bug',
+                'update implementation',
+            ],
+            metadata: { type: 'development' },
+        },
+        {
+            name: 'reviewer',
+            utterances: [
+                'review code',
+                'check quality',
+                'find issues',
+                'suggest improvements',
+                'analyze code',
+                'code review',
+            ],
+            metadata: { type: 'review' },
+        },
+        {
+            name: 'tester',
+            utterances: [
+                'write tests',
+                'add test cases',
+                'create unit tests',
+                'test coverage',
+                'integration tests',
+                'verify functionality',
+            ],
+            metadata: { type: 'testing' },
+        },
+        {
+            name: 'researcher',
+            utterances: [
+                'research topic',
+                'find information',
+                'explore options',
+                'investigate',
+                'analyze requirements',
+                'understand codebase',
+            ],
+            metadata: { type: 'research' },
+        },
+        {
+            name: 'architect',
+            utterances: [
+                'design system',
+                'architecture',
+                'structure project',
+                'plan implementation',
+                'design patterns',
+                'system design',
+            ],
+            metadata: { type: 'architecture' },
+        },
+        {
+            name: 'devops',
+            utterances: [
+                'deploy',
+                'ci/cd',
+                'docker',
+                'kubernetes',
+                'infrastructure',
+                'build pipeline',
+                'github actions',
+            ],
+            metadata: { type: 'devops' },
+        },
+        {
+            name: 'security',
+            utterances: [
+                'security audit',
+                'vulnerability',
+                'authentication',
+                'authorization',
+                'secure code',
+                'penetration test',
+            ],
+            metadata: { type: 'security' },
+        },
+    ]);
+    return router;
+}
+exports.default = SemanticRouter;

package/dist/core/rvf-wrapper.d.ts

@@ -0,0 +1,86 @@
+/**
+ * RVF Wrapper - Persistent vector store via @ruvector/rvf
+ *
+ * Wraps @ruvector/rvf RvfDatabase through thin convenience functions.
+ * Falls back to clear error messages when the package is not installed.
+ */
+export declare function isRvfAvailable(): boolean;
+export interface RvfStoreOptions {
+    dimensions: number;
+    metric?: 'l2' | 'cosine' | 'dotproduct';
+    compression?: 'none' | 'scalar' | 'product';
+    m?: number;
+    efConstruction?: number;
+}
+export interface RvfEntry {
+    id: string;
+    vector: Float32Array | number[];
+    metadata?: Record<string, any>;
+}
+export interface RvfResult {
+    id: string;
+    distance: number;
+}
+export interface RvfStoreStatus {
+    totalVectors: number;
+    totalSegments: number;
+    fileSizeBytes: number;
+    epoch: number;
+    compactionState: string;
+    deadSpaceRatio: number;
+    readOnly: boolean;
+}
+export interface RvfQueryOpts {
+    efSearch?: number;
+    filter?: any;
+    timeoutMs?: number;
+}
+export type RvfStore = any;
+/**
+ * Create a new RVF store at the given path.
+ */
+export declare function createRvfStore(path: string, options: RvfStoreOptions): Promise<RvfStore>;
+/**
+ * Open an existing RVF store for read-write access.
+ */
+export declare function openRvfStore(path: string): Promise<RvfStore>;
+/**
+ * Ingest a batch of vectors into an open store.
+ */
+export declare function rvfIngest(store: RvfStore, entries: RvfEntry[]): Promise<{
+    accepted: number;
+    rejected: number;
+    epoch: number;
+}>;
+/**
+ * Query for the k nearest neighbors.
+ */
+export declare function rvfQuery(store: RvfStore, vector: Float32Array | number[], k: number, options?: RvfQueryOpts): Promise<RvfResult[]>;
+/**
+ * Soft-delete vectors by their IDs.
+ */
+export declare function rvfDelete(store: RvfStore, ids: string[]): Promise<{
+    deleted: number;
+    epoch: number;
+}>;
+/**
+ * Get the current store status.
+ */
+export declare function rvfStatus(store: RvfStore): Promise<RvfStoreStatus>;
+/**
+ * Run compaction to reclaim dead space.
+ */
+export declare function rvfCompact(store: RvfStore): Promise<{
+    segmentsCompacted: number;
+    bytesReclaimed: number;
+    epoch: number;
+}>;
+/**
+ * Derive a child store from a parent for lineage tracking.
+ */
+export declare function rvfDerive(store: RvfStore, childPath: string): Promise<RvfStore>;
+/**
+ * Close the store, releasing the writer lock and flushing data.
+ */
+export declare function rvfClose(store: RvfStore): Promise<void>;
+//# sourceMappingURL=rvf-wrapper.d.ts.map

package/dist/core/rvf-wrapper.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"rvf-wrapper.d.ts","sourceRoot":"","sources":["../../src/core/rvf-wrapper.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAoBH,wBAAgB,cAAc,IAAI,OAAO,CAOxC;AAMD,MAAM,WAAW,eAAe;IAC9B,UAAU,EAAE,MAAM,CAAC;IACnB,MAAM,CAAC,EAAE,IAAI,GAAG,QAAQ,GAAG,YAAY,CAAC;IACxC,WAAW,CAAC,EAAE,MAAM,GAAG,QAAQ,GAAG,SAAS,CAAC;IAC5C,CAAC,CAAC,EAAE,MAAM,CAAC;IACX,cAAc,CAAC,EAAE,MAAM,CAAC;CACzB;AAED,MAAM,WAAW,QAAQ;IACvB,EAAE,EAAE,MAAM,CAAC;IACX,MAAM,EAAE,YAAY,GAAG,MAAM,EAAE,CAAC;IAChC,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC;CAChC;AAED,MAAM,WAAW,SAAS;IACxB,EAAE,EAAE,MAAM,CAAC;IACX,QAAQ,EAAE,MAAM,CAAC;CAClB;AAED,MAAM,WAAW,cAAc;IAC7B,YAAY,EAAE,MAAM,CAAC;IACrB,aAAa,EAAE,MAAM,CAAC;IACtB,aAAa,EAAE,MAAM,CAAC;IACtB,KAAK,EAAE,MAAM,CAAC;IACd,eAAe,EAAE,MAAM,CAAC;IACxB,cAAc,EAAE,MAAM,CAAC;IACvB,QAAQ,EAAE,OAAO,CAAC;CACnB;AAED,MAAM,WAAW,YAAY;IAC3B,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,MAAM,CAAC,EAAE,GAAG,CAAC;IACb,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAMD,MAAM,MAAM,QAAQ,GAAG,GAAG,CAAC;AAM3B;;GAEG;AACH,wBAAsB,cAAc,CAClC,IAAI,EAAE,MAAM,EACZ,OAAO,EAAE,eAAe,GACvB,OAAO,CAAC,QAAQ,CAAC,CAGnB;AAED;;GAEG;AACH,wBAAsB,YAAY,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,QAAQ,CAAC,CAGlE;AAED;;GAEG;AACH,wBAAsB,SAAS,CAC7B,KAAK,EAAE,QAAQ,EACf,OAAO,EAAE,QAAQ,EAAE,GAClB,OAAO,CAAC;IAAE,QAAQ,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,CAAC,CAEhE;AAED;;GAEG;AACH,wBAAsB,QAAQ,CAC5B,KAAK,EAAE,QAAQ,EACf,MAAM,EAAE,YAAY,GAAG,MAAM,EAAE,EAC/B,CAAC,EAAE,MAAM,EACT,OAAO,CAAC,EAAE,YAAY,GACrB,OAAO,CAAC,SAAS,EAAE,CAAC,CAEtB;AAED;;GAEG;AACH,wBAAsB,SAAS,CAC7B,KAAK,EAAE,QAAQ,EACf,GAAG,EAAE,MAAM,EAAE,GACZ,OAAO,CAAC;IAAE,OAAO,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,CAAC,CAE7C;AAED;;GAEG;AACH,wBAAsB,SAAS,CAAC,KAAK,EAAE,QAAQ,GAAG,OAAO,CAAC,cAAc,CAAC,CAExE;AAED;;GAEG;AACH,wBAAsB,UAAU,CAC9B,KAAK,EAAE,QAAQ,GACd,OAAO,CAAC;IAAE,iBAAiB,EAAE,MAAM,CAAC;IAAC,cAAc,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,CAAC,CAE/E;AAED;;GAEG;AACH,wBAAsB,SAAS,CAC7B,KAAK,EAAE,QAAQ,EACf,SAAS,EAAE,MAAM,GAChB,OAAO,CAAC,QAAQ,CAAC,CAEnB;AAED;;GAEG;AACH,wBAAsB,QAAQ,CAAC,KAAK,EAAE,QAAQ,GAAG,OAAO,CAAC,IAAI,CAAC,CAE7D"}

package/dist/core/rvf-wrapper.js

@@ -0,0 +1,102 @@
+"use strict";
+/**
+ * RVF Wrapper - Persistent vector store via @ruvector/rvf
+ *
+ * Wraps @ruvector/rvf RvfDatabase through thin convenience functions.
+ * Falls back to clear error messages when the package is not installed.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.isRvfAvailable = isRvfAvailable;
+exports.createRvfStore = createRvfStore;
+exports.openRvfStore = openRvfStore;
+exports.rvfIngest = rvfIngest;
+exports.rvfQuery = rvfQuery;
+exports.rvfDelete = rvfDelete;
+exports.rvfStatus = rvfStatus;
+exports.rvfCompact = rvfCompact;
+exports.rvfDerive = rvfDerive;
+exports.rvfClose = rvfClose;
+let rvfModule = null;
+let loadError = null;
+function getRvfModule() {
+    if (rvfModule)
+        return rvfModule;
+    if (loadError)
+        throw loadError;
+    try {
+        rvfModule = require('@ruvector/rvf');
+        return rvfModule;
+    }
+    catch (e) {
+        loadError = new Error('@ruvector/rvf is not installed. Run: npm install @ruvector/rvf');
+        throw loadError;
+    }
+}
+function isRvfAvailable() {
+    try {
+        getRvfModule();
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+// ---------------------------------------------------------------------------
+// Wrapper functions
+// ---------------------------------------------------------------------------
+/**
+ * Create a new RVF store at the given path.
+ */
+async function createRvfStore(path, options) {
+    const mod = getRvfModule();
+    return mod.RvfDatabase.create(path, options);
+}
+/**
+ * Open an existing RVF store for read-write access.
+ */
+async function openRvfStore(path) {
+    const mod = getRvfModule();
+    return mod.RvfDatabase.open(path);
+}
+/**
+ * Ingest a batch of vectors into an open store.
+ */
+async function rvfIngest(store, entries) {
+    return store.ingestBatch(entries);
+}
+/**
+ * Query for the k nearest neighbors.
+ */
+async function rvfQuery(store, vector, k, options) {
+    return store.query(vector, k, options);
+}
+/**
+ * Soft-delete vectors by their IDs.
+ */
+async function rvfDelete(store, ids) {
+    return store.delete(ids);
+}
+/**
+ * Get the current store status.
+ */
+async function rvfStatus(store) {
+    return store.status();
+}
+/**
+ * Run compaction to reclaim dead space.
+ */
+async function rvfCompact(store) {
+    return store.compact();
+}
+/**
+ * Derive a child store from a parent for lineage tracking.
+ */
+async function rvfDerive(store, childPath) {
+    return store.derive(childPath);
+}
+/**
+ * Close the store, releasing the writer lock and flushing data.
+ */
+async function rvfClose(store) {
+    return store.close();
+}