@ruvector/ruvllm 0.2.3 → 2.4.0

package/dist/esm/rlm/types.d.ts

@@ -0,0 +1,189 @@
+/**
+ * RLM (Retrieval Language Model) Type Definitions
+ *
+ * Types for the recursive retrieval-augmented generation system
+ * that breaks down complex queries into sub-queries and synthesizes
+ * answers from retrieved memory spans.
+ */
+/**
+ * Configuration for the RLM controller
+ *
+ * @example
+ * ```typescript
+ * const config: RlmConfig = {
+ *   maxDepth: 3,
+ *   maxSubQueries: 5,
+ *   tokenBudget: 4096,
+ *   enableCache: true,
+ *   cacheTtl: 300000, // 5 minutes
+ *   retrievalTopK: 10,
+ *   minQualityScore: 0.7,
+ *   enableReflection: true,
+ *   maxReflectionIterations: 2,
+ * };
+ * ```
+ */
+export interface RlmConfig {
+    /** Maximum recursion depth for sub-queries (default: 3) */
+    maxDepth?: number;
+    /** Maximum number of sub-queries per level (default: 5) */
+    maxSubQueries?: number;
+    /** Token budget for generation (default: 4096) */
+    tokenBudget?: number;
+    /** Enable response caching (default: true) */
+    enableCache?: boolean;
+    /** Cache TTL in milliseconds (default: 300000 = 5 minutes) */
+    cacheTtl?: number;
+    /** Number of memory spans to retrieve (default: 10) */
+    retrievalTopK?: number;
+    /** Minimum quality score to accept answer (default: 0.7) */
+    minQualityScore?: number;
+    /** Enable self-reflection loop (default: false) */
+    enableReflection?: boolean;
+    /** Maximum reflection iterations (default: 2) */
+    maxReflectionIterations?: number;
+}
+/**
+ * Answer produced by the RLM controller
+ *
+ * @example
+ * ```typescript
+ * const answer: RlmAnswer = {
+ *   text: 'Machine learning is a subset of artificial intelligence...',
+ *   confidence: 0.92,
+ *   qualityScore: 0.88,
+ *   sources: [
+ *     { id: 'mem-1', text: 'ML definition from textbook', similarityScore: 0.95, metadata: {} },
+ *   ],
+ *   subQueries: [
+ *     { query: 'What is artificial intelligence?', answer: 'AI is...', depth: 1 },
+ *   ],
+ *   tokenUsage: { prompt: 512, completion: 256, total: 768 },
+ *   cached: false,
+ * };
+ * ```
+ */
+export interface RlmAnswer {
+    /** The generated answer text */
+    text: string;
+    /** Overall confidence in the answer (0.0 - 1.0) */
+    confidence: number;
+    /** Quality score based on source coverage and coherence (0.0 - 1.0) */
+    qualityScore: number;
+    /** Memory spans used to generate the answer */
+    sources: MemorySpan[];
+    /** Sub-queries generated and answered (if recursive) */
+    subQueries?: SubQuery[];
+    /** Token usage statistics */
+    tokenUsage: TokenUsage;
+    /** Whether this answer was served from cache */
+    cached: boolean;
+}
+/**
+ * A span of memory retrieved for context
+ *
+ * @example
+ * ```typescript
+ * const span: MemorySpan = {
+ *   id: 'mem-abc123',
+ *   text: 'Relevant context from memory...',
+ *   similarityScore: 0.89,
+ *   source: 'documentation',
+ *   metadata: { timestamp: Date.now(), category: 'technical' },
+ * };
+ * ```
+ */
+export interface MemorySpan {
+    /** Unique identifier for the memory span */
+    id: string;
+    /** The text content of the memory span */
+    text: string;
+    /** Cosine similarity score to the query (0.0 - 1.0) */
+    similarityScore: number;
+    /** Optional source identifier (e.g., document name, URL) */
+    source?: string;
+    /** Additional metadata associated with this span */
+    metadata: Record<string, unknown>;
+}
+/**
+ * A sub-query generated during recursive retrieval
+ */
+export interface SubQuery {
+    /** The generated sub-query text */
+    query: string;
+    /** The answer to the sub-query */
+    answer: string;
+    /** Recursion depth at which this sub-query was generated */
+    depth: number;
+}
+/**
+ * Token usage statistics for a query
+ */
+export interface TokenUsage {
+    /** Tokens used in the prompt (including context) */
+    prompt: number;
+    /** Tokens generated in the completion */
+    completion: number;
+    /** Total tokens used (prompt + completion) */
+    total: number;
+}
+/**
+ * Streaming token event
+ *
+ * Discriminated union for streaming responses:
+ * - `type: 'token'` - A partial token was generated
+ * - `type: 'done'` - Generation complete with final answer
+ *
+ * @example
+ * ```typescript
+ * for await (const event of controller.queryStream('What is AI?')) {
+ *   if (event.type === 'token') {
+ *     process.stdout.write(event.text);
+ *   } else {
+ *     console.log('\n\nFinal answer:', event.answer.text);
+ *   }
+ * }
+ * ```
+ */
+export type StreamToken = {
+    /** Token event type */
+    type: 'token';
+    /** The partial text token */
+    text: string;
+    /** Always false for token events */
+    done: false;
+} | {
+    /** Done event type */
+    type: 'done';
+    /** The complete answer */
+    answer: RlmAnswer;
+    /** Always true for done events */
+    done: true;
+};
+/**
+ * Internal cache entry for RLM answers
+ */
+export interface RlmCacheEntry {
+    /** The cached answer */
+    answer: RlmAnswer;
+    /** Timestamp when the entry was cached */
+    timestamp: number;
+    /** Query hash for cache key */
+    queryHash: string;
+}
+/**
+ * Reflection result from self-evaluation loop
+ */
+export interface ReflectionResult {
+    /** Whether the answer passed reflection criteria */
+    passed: boolean;
+    /** Critique of the current answer */
+    critique?: string;
+    /** Suggested improvements */
+    suggestions?: string[];
+    /** Updated quality score after reflection */
+    updatedScore: number;
+    /** Number of reflection iterations performed */
+    iterations: number;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/esm/rlm/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../src/rlm/types.ts"],"names":[],"mappings":"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"}

package/dist/esm/rlm/types.js

@@ -0,0 +1,9 @@
+/**
+ * RLM (Retrieval Language Model) Type Definitions
+ *
+ * Types for the recursive retrieval-augmented generation system
+ * that breaks down complex queries into sub-queries and synthesizes
+ * answers from retrieved memory spans.
+ */
+export {};
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoidHlwZXMuanMiLCJzb3VyY2VSb290IjoiIiwic291cmNlcyI6WyIuLi8uLi8uLi9zcmMvcmxtL3R5cGVzLnRzIl0sIm5hbWVzIjpbXSwibWFwcGluZ3MiOiJBQUFBOzs7Ozs7R0FNRyIsInNvdXJjZXNDb250ZW50IjpbIi8qKlxuICogUkxNIChSZXRyaWV2YWwgTGFuZ3VhZ2UgTW9kZWwpIFR5cGUgRGVmaW5pdGlvbnNcbiAqXG4gKiBUeXBlcyBmb3IgdGhlIHJlY3Vyc2l2ZSByZXRyaWV2YWwtYXVnbWVudGVkIGdlbmVyYXRpb24gc3lzdGVtXG4gKiB0aGF0IGJyZWFrcyBkb3duIGNvbXBsZXggcXVlcmllcyBpbnRvIHN1Yi1xdWVyaWVzIGFuZCBzeW50aGVzaXplc1xuICogYW5zd2VycyBmcm9tIHJldHJpZXZlZCBtZW1vcnkgc3BhbnMuXG4gKi9cblxuLyoqXG4gKiBDb25maWd1cmF0aW9uIGZvciB0aGUgUkxNIGNvbnRyb2xsZXJcbiAqXG4gKiBAZXhhbXBsZVxuICogYGBgdHlwZXNjcmlwdFxuICogY29uc3QgY29uZmlnOiBSbG1Db25maWcgPSB7XG4gKiAgIG1heERlcHRoOiAzLFxuICogICBtYXhTdWJRdWVyaWVzOiA1LFxuICogICB0b2tlbkJ1ZGdldDogNDA5NixcbiAqICAgZW5hYmxlQ2FjaGU6IHRydWUsXG4gKiAgIGNhY2hlVHRsOiAzMDAwMDAsIC8vIDUgbWludXRlc1xuICogICByZXRyaWV2YWxUb3BLOiAxMCxcbiAqICAgbWluUXVhbGl0eVNjb3JlOiAwLjcsXG4gKiAgIGVuYWJsZVJlZmxlY3Rpb246IHRydWUsXG4gKiAgIG1heFJlZmxlY3Rpb25JdGVyYXRpb25zOiAyLFxuICogfTtcbiAqIGBgYFxuICovXG5leHBvcnQgaW50ZXJmYWNlIFJsbUNvbmZpZyB7XG4gIC8qKiBNYXhpbXVtIHJlY3Vyc2lvbiBkZXB0aCBmb3Igc3ViLXF1ZXJpZXMgKGRlZmF1bHQ6IDMpICovXG4gIG1heERlcHRoPzogbnVtYmVyO1xuXG4gIC8qKiBNYXhpbXVtIG51bWJlciBvZiBzdWItcXVlcmllcyBwZXIgbGV2ZWwgKGRlZmF1bHQ6IDUpICovXG4gIG1heFN1YlF1ZXJpZXM/OiBudW1iZXI7XG5cbiAgLyoqIFRva2VuIGJ1ZGdldCBmb3IgZ2VuZXJhdGlvbiAoZGVmYXVsdDogNDA5NikgKi9cbiAgdG9rZW5CdWRnZXQ/OiBudW1iZXI7XG5cbiAgLyoqIEVuYWJsZSByZXNwb25zZSBjYWNoaW5nIChkZWZhdWx0OiB0cnVlKSAqL1xuICBlbmFibGVDYWNoZT86IGJvb2xlYW47XG5cbiAgLyoqIENhY2hlIFRUTCBpbiBtaWxsaXNlY29uZHMgKGRlZmF1bHQ6IDMwMDAwMCA9IDUgbWludXRlcykgKi9cbiAgY2FjaGVUdGw/OiBudW1iZXI7XG5cbiAgLyoqIE51bWJlciBvZiBtZW1vcnkgc3BhbnMgdG8gcmV0cmlldmUgKGRlZmF1bHQ6IDEwKSAqL1xuICByZXRyaWV2YWxUb3BLPzogbnVtYmVyO1xuXG4gIC8qKiBNaW5pbXVtIHF1YWxpdHkgc2NvcmUgdG8gYWNjZXB0IGFuc3dlciAoZGVmYXVsdDogMC43KSAqL1xuICBtaW5RdWFsaXR5U2NvcmU/OiBudW1iZXI7XG5cbiAgLyoqIEVuYWJsZSBzZWxmLXJlZmxlY3Rpb24gbG9vcCAoZGVmYXVsdDogZmFsc2UpICovXG4gIGVuYWJsZVJlZmxlY3Rpb24/OiBib29sZWFuO1xuXG4gIC8qKiBNYXhpbXVtIHJlZmxlY3Rpb24gaXRlcmF0aW9ucyAoZGVmYXVsdDogMikgKi9cbiAgbWF4UmVmbGVjdGlvbkl0ZXJhdGlvbnM/OiBudW1iZXI7XG59XG5cbi8qKlxuICogQW5zd2VyIHByb2R1Y2VkIGJ5IHRoZSBSTE0gY29udHJvbGxlclxuICpcbiAqIEBleGFtcGxlXG4gKiBgYGB0eXBlc2NyaXB0XG4gKiBjb25zdCBhbnN3ZXI6IFJsbUFuc3dlciA9IHtcbiAqICAgdGV4dDogJ01hY2hpbmUgbGVhcm5pbmcgaXMgYSBzdWJzZXQgb2YgYXJ0aWZpY2lhbCBpbnRlbGxpZ2VuY2UuLi4nLFxuICogICBjb25maWRlbmNlOiAwLjkyLFxuICogICBxdWFsaXR5U2NvcmU6IDAuODgsXG4gKiAgIHNvdXJjZXM6IFtcbiAqICAgICB7IGlkOiAnbWVtLTEnLCB0ZXh0OiAnTUwgZGVmaW5pdGlvbiBmcm9tIHRleHRib29rJywgc2ltaWxhcml0eVNjb3JlOiAwLjk1LCBtZXRhZGF0YToge30gfSxcbiAqICAgXSxcbiAqICAgc3ViUXVlcmllczogW1xuICogICAgIHsgcXVlcnk6ICdXaGF0IGlzIGFydGlmaWNpYWwgaW50ZWxsaWdlbmNlPycsIGFuc3dlcjogJ0FJIGlzLi4uJywgZGVwdGg6IDEgfSxcbiAqICAgXSxcbiAqICAgdG9rZW5Vc2FnZTogeyBwcm9tcHQ6IDUxMiwgY29tcGxldGlvbjogMjU2LCB0b3RhbDogNzY4IH0sXG4gKiAgIGNhY2hlZDogZmFsc2UsXG4gKiB9O1xuICogYGBgXG4gKi9cbmV4cG9ydCBpbnRlcmZhY2UgUmxtQW5zd2VyIHtcbiAgLyoqIFRoZSBnZW5lcmF0ZWQgYW5zd2VyIHRleHQgKi9cbiAgdGV4dDogc3RyaW5nO1xuXG4gIC8qKiBPdmVyYWxsIGNvbmZpZGVuY2UgaW4gdGhlIGFuc3dlciAoMC4wIC0gMS4wKSAqL1xuICBjb25maWRlbmNlOiBudW1iZXI7XG5cbiAgLyoqIFF1YWxpdHkgc2NvcmUgYmFzZWQgb24gc291cmNlIGNvdmVyYWdlIGFuZCBjb2hlcmVuY2UgKDAuMCAtIDEuMCkgKi9cbiAgcXVhbGl0eVNjb3JlOiBudW1iZXI7XG5cbiAgLyoqIE1lbW9yeSBzcGFucyB1c2VkIHRvIGdlbmVyYXRlIHRoZSBhbnN3ZXIgKi9cbiAgc291cmNlczogTWVtb3J5U3BhbltdO1xuXG4gIC8qKiBTdWItcXVlcmllcyBnZW5lcmF0ZWQgYW5kIGFuc3dlcmVkIChpZiByZWN1cnNpdmUpICovXG4gIHN1YlF1ZXJpZXM/OiBTdWJRdWVyeVtdO1xuXG4gIC8qKiBUb2tlbiB1c2FnZSBzdGF0aXN0aWNzICovXG4gIHRva2VuVXNhZ2U6IFRva2VuVXNhZ2U7XG5cbiAgLyoqIFdoZXRoZXIgdGhpcyBhbnN3ZXIgd2FzIHNlcnZlZCBmcm9tIGNhY2hlICovXG4gIGNhY2hlZDogYm9vbGVhbjtcbn1cblxuLyoqXG4gKiBBIHNwYW4gb2YgbWVtb3J5IHJldHJpZXZlZCBmb3IgY29udGV4dFxuICpcbiAqIEBleGFtcGxlXG4gKiBgYGB0eXBlc2NyaXB0XG4gKiBjb25zdCBzcGFuOiBNZW1vcnlTcGFuID0ge1xuICogICBpZDogJ21lbS1hYmMxMjMnLFxuICogICB0ZXh0OiAnUmVsZXZhbnQgY29udGV4dCBmcm9tIG1lbW9yeS4uLicsXG4gKiAgIHNpbWlsYXJpdHlTY29yZTogMC44OSxcbiAqICAgc291cmNlOiAnZG9jdW1lbnRhdGlvbicsXG4gKiAgIG1ldGFkYXRhOiB7IHRpbWVzdGFtcDogRGF0ZS5ub3coKSwgY2F0ZWdvcnk6ICd0ZWNobmljYWwnIH0sXG4gKiB9O1xuICogYGBgXG4gKi9cbmV4cG9ydCBpbnRlcmZhY2UgTWVtb3J5U3BhbiB7XG4gIC8qKiBVbmlxdWUgaWRlbnRpZmllciBmb3IgdGhlIG1lbW9yeSBzcGFuICovXG4gIGlkOiBzdHJpbmc7XG5cbiAgLyoqIFRoZSB0ZXh0IGNvbnRlbnQgb2YgdGhlIG1lbW9yeSBzcGFuICovXG4gIHRleHQ6IHN0cmluZztcblxuICAvKiogQ29zaW5lIHNpbWlsYXJpdHkgc2NvcmUgdG8gdGhlIHF1ZXJ5ICgwLjAgLSAxLjApICovXG4gIHNpbWlsYXJpdHlTY29yZTogbnVtYmVyO1xuXG4gIC8qKiBPcHRpb25hbCBzb3VyY2UgaWRlbnRpZmllciAoZS5nLiwgZG9jdW1lbnQgbmFtZSwgVVJMKSAqL1xuICBzb3VyY2U/OiBzdHJpbmc7XG5cbiAgLyoqIEFkZGl0aW9uYWwgbWV0YWRhdGEgYXNzb2NpYXRlZCB3aXRoIHRoaXMgc3BhbiAqL1xuICBtZXRhZGF0YTogUmVjb3JkPHN0cmluZywgdW5rbm93bj47XG59XG5cbi8qKlxuICogQSBzdWItcXVlcnkgZ2VuZXJhdGVkIGR1cmluZyByZWN1cnNpdmUgcmV0cmlldmFsXG4gKi9cbmV4cG9ydCBpbnRlcmZhY2UgU3ViUXVlcnkge1xuICAvKiogVGhlIGdlbmVyYXRlZCBzdWItcXVlcnkgdGV4dCAqL1xuICBxdWVyeTogc3RyaW5nO1xuXG4gIC8qKiBUaGUgYW5zd2VyIHRvIHRoZSBzdWItcXVlcnkgKi9cbiAgYW5zd2VyOiBzdHJpbmc7XG5cbiAgLyoqIFJlY3Vyc2lvbiBkZXB0aCBhdCB3aGljaCB0aGlzIHN1Yi1xdWVyeSB3YXMgZ2VuZXJhdGVkICovXG4gIGRlcHRoOiBudW1iZXI7XG59XG5cbi8qKlxuICogVG9rZW4gdXNhZ2Ugc3RhdGlzdGljcyBmb3IgYSBxdWVyeVxuICovXG5leHBvcnQgaW50ZXJmYWNlIFRva2VuVXNhZ2Uge1xuICAvKiogVG9rZW5zIHVzZWQgaW4gdGhlIHByb21wdCAoaW5jbHVkaW5nIGNvbnRleHQpICovXG4gIHByb21wdDogbnVtYmVyO1xuXG4gIC8qKiBUb2tlbnMgZ2VuZXJhdGVkIGluIHRoZSBjb21wbGV0aW9uICovXG4gIGNvbXBsZXRpb246IG51bWJlcjtcblxuICAvKiogVG90YWwgdG9rZW5zIHVzZWQgKHByb21wdCArIGNvbXBsZXRpb24pICovXG4gIHRvdGFsOiBudW1iZXI7XG59XG5cbi8qKlxuICogU3RyZWFtaW5nIHRva2VuIGV2ZW50XG4gKlxuICogRGlzY3JpbWluYXRlZCB1bmlvbiBmb3Igc3RyZWFtaW5nIHJlc3BvbnNlczpcbiAqIC0gYHR5cGU6ICd0b2tlbidgIC0gQSBwYXJ0aWFsIHRva2VuIHdhcyBnZW5lcmF0ZWRcbiAqIC0gYHR5cGU6ICdkb25lJ2AgLSBHZW5lcmF0aW9uIGNvbXBsZXRlIHdpdGggZmluYWwgYW5zd2VyXG4gKlxuICogQGV4YW1wbGVcbiAqIGBgYHR5cGVzY3JpcHRcbiAqIGZvciBhd2FpdCAoY29uc3QgZXZlbnQgb2YgY29udHJvbGxlci5xdWVyeVN0cmVhbSgnV2hhdCBpcyBBST8nKSkge1xuICogICBpZiAoZXZlbnQudHlwZSA9PT0gJ3Rva2VuJykge1xuICogICAgIHByb2Nlc3Muc3Rkb3V0LndyaXRlKGV2ZW50LnRleHQpO1xuICogICB9IGVsc2Uge1xuICogICAgIGNvbnNvbGUubG9nKCdcXG5cXG5GaW5hbCBhbnN3ZXI6JywgZXZlbnQuYW5zd2VyLnRleHQpO1xuICogICB9XG4gKiB9XG4gKiBgYGBcbiAqL1xuZXhwb3J0IHR5cGUgU3RyZWFtVG9rZW4gPVxuICB8IHtcbiAgICAgIC8qKiBUb2tlbiBldmVudCB0eXBlICovXG4gICAgICB0eXBlOiAndG9rZW4nO1xuICAgICAgLyoqIFRoZSBwYXJ0aWFsIHRleHQgdG9rZW4gKi9cbiAgICAgIHRleHQ6IHN0cmluZztcbiAgICAgIC8qKiBBbHdheXMgZmFsc2UgZm9yIHRva2VuIGV2ZW50cyAqL1xuICAgICAgZG9uZTogZmFsc2U7XG4gICAgfVxuICB8IHtcbiAgICAgIC8qKiBEb25lIGV2ZW50IHR5cGUgKi9cbiAgICAgIHR5cGU6ICdkb25lJztcbiAgICAgIC8qKiBUaGUgY29tcGxldGUgYW5zd2VyICovXG4gICAgICBhbnN3ZXI6IFJsbUFuc3dlcjtcbiAgICAgIC8qKiBBbHdheXMgdHJ1ZSBmb3IgZG9uZSBldmVudHMgKi9cbiAgICAgIGRvbmU6IHRydWU7XG4gICAgfTtcblxuLyoqXG4gKiBJbnRlcm5hbCBjYWNoZSBlbnRyeSBmb3IgUkxNIGFuc3dlcnNcbiAqL1xuZXhwb3J0IGludGVyZmFjZSBSbG1DYWNoZUVudHJ5IHtcbiAgLyoqIFRoZSBjYWNoZWQgYW5zd2VyICovXG4gIGFuc3dlcjogUmxtQW5zd2VyO1xuXG4gIC8qKiBUaW1lc3RhbXAgd2hlbiB0aGUgZW50cnkgd2FzIGNhY2hlZCAqL1xuICB0aW1lc3RhbXA6IG51bWJlcjtcblxuICAvKiogUXVlcnkgaGFzaCBmb3IgY2FjaGUga2V5ICovXG4gIHF1ZXJ5SGFzaDogc3RyaW5nO1xufVxuXG4vKipcbiAqIFJlZmxlY3Rpb24gcmVzdWx0IGZyb20gc2VsZi1ldmFsdWF0aW9uIGxvb3BcbiAqL1xuZXhwb3J0IGludGVyZmFjZSBSZWZsZWN0aW9uUmVzdWx0IHtcbiAgLyoqIFdoZXRoZXIgdGhlIGFuc3dlciBwYXNzZWQgcmVmbGVjdGlvbiBjcml0ZXJpYSAqL1xuICBwYXNzZWQ6IGJvb2xlYW47XG5cbiAgLyoqIENyaXRpcXVlIG9mIHRoZSBjdXJyZW50IGFuc3dlciAqL1xuICBjcml0aXF1ZT86IHN0cmluZztcblxuICAvKiogU3VnZ2VzdGVkIGltcHJvdmVtZW50cyAqL1xuICBzdWdnZXN0aW9ucz86IHN0cmluZ1tdO1xuXG4gIC8qKiBVcGRhdGVkIHF1YWxpdHkgc2NvcmUgYWZ0ZXIgcmVmbGVjdGlvbiAqL1xuICB1cGRhdGVkU2NvcmU6IG51bWJlcjtcblxuICAvKiogTnVtYmVyIG9mIHJlZmxlY3Rpb24gaXRlcmF0aW9ucyBwZXJmb3JtZWQgKi9cbiAgaXRlcmF0aW9uczogbnVtYmVyO1xufVxuIl19

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@ruvector/ruvllm",
-  "version": "0.2.3",
-  "description": "Self-learning LLM orchestration with TRM recursive reasoning, SONA adaptive learning, HNSW memory, FastGRNN routing, and SIMD inference",
+  "version": "2.4.0",
+  "description": "Self-learning LLM orchestration with SONA adaptive learning, HNSW memory, RLM recursive retrieval, FastGRNN routing, and SIMD inference",
   "main": "dist/cjs/index.js",
   "module": "dist/esm/index.js",
   "types": "dist/cjs/index.d.ts",
@@ -65,20 +65,19 @@
     "ora": "^5.4.1"
   },
   "optionalDependencies": {
-    "@ruvector/ruvllm-linux-x64-gnu": "0.2.3",
-    "@ruvector/ruvllm-linux-arm64-gnu": "0.2.3",
-    "@ruvector/ruvllm-darwin-x64": "0.2.3",
-    "@ruvector/ruvllm-darwin-arm64": "0.2.3",
-    "@ruvector/ruvllm-win32-x64-msvc": "0.2.3"
+    "@ruvector/ruvllm-linux-x64-gnu": "2.3.0",
+    "@ruvector/ruvllm-linux-arm64-gnu": "2.3.0",
+    "@ruvector/ruvllm-darwin-x64": "2.3.0",
+    "@ruvector/ruvllm-darwin-arm64": "2.3.0",
+    "@ruvector/ruvllm-win32-x64-msvc": "2.3.0"
   },
   "keywords": [
     "ruvllm",
     "llm",
+    "rlm",
+    "retrieval-language-model",
     "self-learning",
     "adaptive-learning",
-    "trm",
-    "tiny-recursive-models",
-    "recursive-reasoning",
     "sona",
     "lora",
     "ewc",
@@ -95,7 +94,9 @@
     "deep-learning",
     "napi",
     "rust",
-    "ruvector"
+    "ruvector",
+    "rag",
+    "contrastive-learning"
   ],
   "author": "rUv Team <team@ruv.io>",
   "license": "MIT OR Apache-2.0",
@@ -118,6 +119,7 @@
   "files": [
     "dist",
     "bin",
+    "scripts",
     "*.node",
     "README.md"
   ]

package/scripts/ensemble-model-compare.js

@@ -0,0 +1,287 @@
+#!/usr/bin/env node
+/**
+ * Ensemble Model Comparison
+ *
+ * Strategies:
+ * 1. Task prefix - prepend context to make tasks more aligned with descriptions
+ * 2. Ensemble voting - combine multiple description variants
+ * 3. Agent-specific thresholds based on training patterns
+ */
+
+const { execSync } = require('child_process');
+const { existsSync } = require('fs');
+const { join } = require('path');
+const { homedir } = require('os');
+
+const MODELS_DIR = join(homedir(), '.ruvllm', 'models');
+const RUVLTRA_MODEL = join(MODELS_DIR, 'ruvltra-claude-code-0.5b-q4_k_m.gguf');
+const QWEN_MODEL = join(MODELS_DIR, 'qwen2.5-0.5b-instruct-q4_k_m.gguf');
+
+// Original V1 descriptions (best baseline)
+const DESCRIPTIONS_V1 = {
+  coder: 'implement create write build add code function class component feature',
+  researcher: 'research find investigate analyze explore search discover examine',
+  reviewer: 'review check evaluate assess inspect examine code quality',
+  tester: 'test unit integration e2e coverage mock assertion spec',
+  architect: 'design architecture schema system structure plan database',
+  'security-architect': 'security vulnerability xss injection audit cve authentication',
+  debugger: 'debug fix bug error issue broken crash exception trace',
+  documenter: 'document readme jsdoc comment explain describe documentation',
+  refactorer: 'refactor extract rename consolidate clean restructure simplify',
+  optimizer: 'optimize performance slow fast cache speed memory latency',
+  devops: 'deploy ci cd kubernetes docker pipeline container infrastructure',
+  'api-docs': 'openapi swagger api documentation graphql schema endpoint',
+  planner: 'plan estimate prioritize sprint roadmap schedule milestone',
+};
+
+// V6: Keywords reformulated as action phrases
+const DESCRIPTIONS_V6 = {
+  coder: 'implement new functionality write code build features create components',
+  researcher: 'research and analyze investigate patterns explore best practices',
+  reviewer: 'review code quality check pull requests evaluate implementations',
+  tester: 'write tests create test coverage add unit and integration tests',
+  architect: 'design system architecture plan database schemas structure systems',
+  'security-architect': 'audit security vulnerabilities check xss and injection attacks',
+  debugger: 'debug and fix bugs trace errors resolve exceptions',
+  documenter: 'write documentation add jsdoc comments create readme files',
+  refactorer: 'refactor code modernize to async await restructure modules',
+  optimizer: 'optimize performance improve speed cache data reduce latency',
+  devops: 'deploy to cloud setup ci cd pipelines manage containers kubernetes',
+  'api-docs': 'generate openapi documentation create swagger api specs',
+  planner: 'plan sprints create roadmaps estimate timelines schedule milestones',
+};
+
+// Task prefixes to try
+const TASK_PREFIXES = [
+  '',                           // No prefix (baseline)
+  'Task: ',                     // Simple task prefix
+  'The developer needs to: ',   // Contextual prefix
+  'Claude Code task - ',        // Model-specific prefix
+];
+
+const ROUTING_TESTS = [
+  { task: 'Implement a binary search function in TypeScript', expected: 'coder' },
+  { task: 'Write unit tests for the authentication module', expected: 'tester' },
+  { task: 'Review the pull request for security vulnerabilities', expected: 'reviewer' },
+  { task: 'Research best practices for React state management', expected: 'researcher' },
+  { task: 'Design the database schema for user profiles', expected: 'architect' },
+  { task: 'Fix the null pointer exception in the login handler', expected: 'debugger' },
+  { task: 'Audit the API endpoints for XSS vulnerabilities', expected: 'security-architect' },
+  { task: 'Write JSDoc comments for the utility functions', expected: 'documenter' },
+  { task: 'Refactor the payment module to use async/await', expected: 'refactorer' },
+  { task: 'Optimize the database queries for the dashboard', expected: 'optimizer' },
+  { task: 'Set up the CI/CD pipeline for the microservices', expected: 'devops' },
+  { task: 'Generate OpenAPI documentation for the REST API', expected: 'api-docs' },
+  { task: 'Create a sprint plan for the next two weeks', expected: 'planner' },
+  { task: 'Build a React component for user registration', expected: 'coder' },
+  { task: 'Debug memory leak in the WebSocket handler', expected: 'debugger' },
+  { task: 'Investigate slow API response times', expected: 'researcher' },
+  { task: 'Check code for potential race conditions', expected: 'reviewer' },
+  { task: 'Add integration tests for the payment gateway', expected: 'tester' },
+  { task: 'Plan the architecture for real-time notifications', expected: 'architect' },
+  { task: 'Cache the frequently accessed user data', expected: 'optimizer' },
+];
+
+function getEmbedding(modelPath, text) {
+  try {
+    const sanitized = text.replace(/"/g, '\\"').replace(/\n/g, ' ');
+    const result = execSync(
+      `llama-embedding -m "${modelPath}" -p "${sanitized}" --embd-output-format json 2>/dev/null`,
+      { encoding: 'utf-8', maxBuffer: 10 * 1024 * 1024 }
+    );
+    const json = JSON.parse(result);
+    return json.data[json.data.length - 1].embedding;
+  } catch {
+    return null;
+  }
+}
+
+function cosineSimilarity(a, b) {
+  if (!a || !b || a.length !== b.length) return 0;
+  let dot = 0, normA = 0, normB = 0;
+  for (let i = 0; i < a.length; i++) {
+    dot += a[i] * b[i];
+    normA += a[i] * a[i];
+    normB += b[i] * b[i];
+  }
+  return dot / (Math.sqrt(normA) * Math.sqrt(normB) || 1);
+}
+
+function routeTask(taskEmbedding, agentEmbeddings) {
+  let bestAgent = 'coder';
+  let bestSim = -1;
+  const allScores = {};
+  for (const [agent, emb] of Object.entries(agentEmbeddings)) {
+    const sim = cosineSimilarity(taskEmbedding, emb);
+    allScores[agent] = sim;
+    if (sim > bestSim) {
+      bestSim = sim;
+      bestAgent = agent;
+    }
+  }
+  return { agent: bestAgent, confidence: bestSim, scores: allScores };
+}
+
+/**
+ * Ensemble routing - vote across multiple description sets
+ */
+function routeTaskEnsemble(taskEmbedding, allAgentEmbeddings) {
+  const votes = {};
+  const agents = Object.keys(allAgentEmbeddings[0]);
+
+  for (const agent of agents) votes[agent] = 0;
+
+  // Each embedding set votes
+  for (const agentEmbeddings of allAgentEmbeddings) {
+    const { agent } = routeTask(taskEmbedding, agentEmbeddings);
+    votes[agent] = (votes[agent] || 0) + 1;
+  }
+
+  // Return agent with most votes
+  let bestAgent = 'coder';
+  let maxVotes = 0;
+  for (const [agent, count] of Object.entries(votes)) {
+    if (count > maxVotes) {
+      maxVotes = count;
+      bestAgent = agent;
+    }
+  }
+
+  return { agent: bestAgent, votes, voteCount: maxVotes };
+}
+
+function runBenchmark(modelPath, descriptions, prefix = '') {
+  const agentEmbeddings = {};
+  for (const [agent, desc] of Object.entries(descriptions)) {
+    agentEmbeddings[agent] = getEmbedding(modelPath, desc);
+  }
+
+  let correct = 0;
+  for (const test of ROUTING_TESTS) {
+    const taskEmb = getEmbedding(modelPath, prefix + test.task);
+    const { agent } = routeTask(taskEmb, agentEmbeddings);
+    if (agent === test.expected) correct++;
+  }
+
+  return { accuracy: correct / ROUTING_TESTS.length, correct, total: ROUTING_TESTS.length };
+}
+
+function runEnsembleBenchmark(modelPath, descriptionSets, prefix = '') {
+  // Precompute embeddings for all description sets
+  const allAgentEmbeddings = descriptionSets.map(descriptions => {
+    const embeds = {};
+    for (const [agent, desc] of Object.entries(descriptions)) {
+      embeds[agent] = getEmbedding(modelPath, desc);
+    }
+    return embeds;
+  });
+
+  let correct = 0;
+  const results = [];
+  for (const test of ROUTING_TESTS) {
+    const taskEmb = getEmbedding(modelPath, prefix + test.task);
+    const { agent, votes } = routeTaskEnsemble(taskEmb, allAgentEmbeddings);
+    const isCorrect = agent === test.expected;
+    if (isCorrect) correct++;
+    results.push({ task: test.task, expected: test.expected, got: agent, correct: isCorrect, votes });
+  }
+
+  return { accuracy: correct / ROUTING_TESTS.length, correct, total: ROUTING_TESTS.length, results };
+}
+
+async function main() {
+  console.log('\n╔═══════════════════════════════════════════════════════════════════════════════════╗');
+  console.log('║              ENSEMBLE & PREFIX MODEL COMPARISON                                   ║');
+  console.log('╚═══════════════════════════════════════════════════════════════════════════════════╝\n');
+
+  if (!existsSync(RUVLTRA_MODEL)) {
+    console.error('RuvLTRA model not found.');
+    process.exit(1);
+  }
+
+  // Test prefix variations
+  console.log('─────────────────────────────────────────────────────────────────');
+  console.log('                   PREFIX VARIATIONS (RuvLTRA)');
+  console.log('─────────────────────────────────────────────────────────────────\n');
+
+  const prefixResults = {};
+  for (const prefix of TASK_PREFIXES) {
+    const label = prefix || '(no prefix)';
+    process.stdout.write(`  Testing "${label.padEnd(25)}"... `);
+    const result = runBenchmark(RUVLTRA_MODEL, DESCRIPTIONS_V1, prefix);
+    prefixResults[label] = result;
+    console.log(`${(result.accuracy * 100).toFixed(1)}%`);
+  }
+
+  // Find best prefix
+  const bestPrefix = Object.entries(prefixResults).reduce((a, b) =>
+    a[1].accuracy > b[1].accuracy ? a : b
+  );
+
+  console.log(`\n  Best prefix: "${bestPrefix[0]}" = ${(bestPrefix[1].accuracy * 100).toFixed(1)}%`);
+
+  // Test ensemble voting
+  console.log('\n─────────────────────────────────────────────────────────────────');
+  console.log('                   ENSEMBLE VOTING (RuvLTRA)');
+  console.log('─────────────────────────────────────────────────────────────────\n');
+
+  process.stdout.write('  Computing V1 + V6 ensemble... ');
+  const ensembleResult = runEnsembleBenchmark(RUVLTRA_MODEL, [DESCRIPTIONS_V1, DESCRIPTIONS_V6], '');
+  console.log(`${(ensembleResult.accuracy * 100).toFixed(1)}%`);
+
+  // Compare with Qwen
+  console.log('\n─────────────────────────────────────────────────────────────────');
+  console.log('                   QWEN COMPARISON');
+  console.log('─────────────────────────────────────────────────────────────────\n');
+
+  process.stdout.write('  Qwen V1 baseline... ');
+  const qwenV1 = runBenchmark(QWEN_MODEL, DESCRIPTIONS_V1, '');
+  console.log(`${(qwenV1.accuracy * 100).toFixed(1)}%`);
+
+  process.stdout.write('  Qwen V1+V6 ensemble... ');
+  const qwenEnsemble = runEnsembleBenchmark(QWEN_MODEL, [DESCRIPTIONS_V1, DESCRIPTIONS_V6], '');
+  console.log(`${(qwenEnsemble.accuracy * 100).toFixed(1)}%`);
+
+  // Final results table
+  console.log('\n═══════════════════════════════════════════════════════════════════════════════════');
+  console.log('                              FINAL RESULTS');
+  console.log('═══════════════════════════════════════════════════════════════════════════════════\n');
+
+  const fmt = (v) => `${(v * 100).toFixed(1)}%`.padStart(10);
+
+  console.log('┌───────────────────────────────┬────────────┬────────────┐');
+  console.log('│ Strategy                      │   RuvLTRA  │    Qwen    │');
+  console.log('├───────────────────────────────┼────────────┼────────────┤');
+  console.log(`│ V1 Baseline                   │${fmt(prefixResults['(no prefix)'].accuracy)} │${fmt(qwenV1.accuracy)} │`);
+  console.log(`│ V1 + Best Prefix              │${fmt(bestPrefix[1].accuracy)} │     -      │`);
+  console.log(`│ V1+V6 Ensemble                │${fmt(ensembleResult.accuracy)} │${fmt(qwenEnsemble.accuracy)} │`);
+  console.log('└───────────────────────────────┴────────────┴────────────┘');
+
+  // Best overall
+  const ruvBest = Math.max(
+    prefixResults['(no prefix)'].accuracy,
+    bestPrefix[1].accuracy,
+    ensembleResult.accuracy
+  );
+  const qwenBest = Math.max(qwenV1.accuracy, qwenEnsemble.accuracy);
+
+  console.log(`\n  RuvLTRA Best: ${(ruvBest * 100).toFixed(1)}%`);
+  console.log(`  Qwen Best:    ${(qwenBest * 100).toFixed(1)}%`);
+  console.log(`  Advantage:    RuvLTRA +${((ruvBest - qwenBest) * 100).toFixed(1)} points`);
+
+  // Show detailed ensemble results
+  console.log('\n─────────────────────────────────────────────────────────────────');
+  console.log('             ENSEMBLE VOTING DETAILS (RuvLTRA)');
+  console.log('─────────────────────────────────────────────────────────────────\n');
+
+  for (const r of ensembleResult.results) {
+    const mark = r.correct ? '✓' : '✗';
+    const task = r.task.slice(0, 45).padEnd(45);
+    const exp = r.expected.padEnd(18);
+    console.log(`${mark} ${task} ${exp}${r.correct ? '' : '→ ' + r.got}`);
+  }
+
+  console.log('\n');
+}
+
+main().catch(console.error);