@ruvector/ruvllm 4.0.0 → 4.1.0

package/dist/cjs/engine.d.ts

@@ -0,0 +1,160 @@
+/**
+ * RuvLLM Engine - Main orchestrator for self-learning LLM
+ */
+import { RuvLLMConfig, GenerationConfig, QueryResponse, RoutingDecision, MemoryResult, MemoryId, RuvLLMStats, Feedback, Embedding, BatchQueryRequest, BatchQueryResponse, ChatMessage, GenerationResult, LoadModelOptions, LoadedModelInfo } from './types';
+/** Returned by generate()/query() only with `allowPlaceholder` / `RUVLLM_ALLOW_MOCK=1`. */
+export declare const PLACEHOLDER_TEXT = "[RuvLLM placeholder: no language model is loaded; this text is not model output]";
+/**
+ * RuvLLM - Self-learning LLM orchestrator
+ *
+ * Combines SONA adaptive learning with HNSW memory, FastGRNN routing, and
+ * GGUF inference through the native candle backend.
+ *
+ * Text comes only from a model loaded with `loadModel()` (or the `modelPath`
+ * option). Without one, `generate()`, `query()`, `chat()` and
+ * `generateDetailed()` throw `RUVLLM_NO_LANGUAGE_MODEL`.
+ *
+ * @example
+ * ```typescript
+ * import { RuvLLM } from '@ruvector/ruvllm';
+ *
+ * const llm = new RuvLLM();
+ * llm.loadModel('./qwen2.5-0.5b-instruct-q4_k_m.gguf');
+ *
+ * const out = llm.chat([{ role: 'user', content: 'What is machine learning?' }], {
+ *   maxTokens: 128,
+ * });
+ * console.log(out.text, out.finishReason, out.completionTokens);
+ *
+ * // Routed query, answered by the loaded model
+ * const response = llm.query('What is machine learning?');
+ * llm.feedback({ requestId: response.requestId, rating: 5 });
+ * ```
+ */
+export declare class RuvLLM {
+    private native;
+    private nativeVersion;
+    private config;
+    private allowPlaceholder;
+    private fallbackState;
+    /**
+     * Create a new RuvLLM instance
+     */
+    constructor(config?: RuvLLMConfig);
+    /**
+     * Whether the native binary can load and run a language model. False
+     * without a native binary, for binaries that predate `loadModel` (the 2.0.x
+     * `@ruvector/ruvllm-<platform>` packages), and for binaries built without
+     * the `candle` inference backend.
+     */
+    supportsModelLoading(): boolean;
+    /** Error for a binary that has `loadModel` but no inference backend. */
+    private noBackendError;
+    /**
+     * Load a GGUF model (or a directory holding one) for `generate()`,
+     * `chat()` and `query()`. Supported GGUF architectures: llama, mistral,
+     * qwen2, qwen3; others fail with an error naming the architecture. The
+     * tokenizer comes from a `tokenizer.json` beside the file, else from the
+     * GGUF itself. Replaces any loaded model; if loading fails, no model is
+     * loaded. Synchronous: blocks the event loop while the weights load.
+     *
+     * @throws `RUVLLM_NATIVE_UNAVAILABLE` without a native binary,
+     *   `RUVLLM_NATIVE_TOO_OLD` when the binary predates model loading,
+     *   `RUVLLM_NO_INFERENCE_BACKEND` when it was built without `candle`,
+     *   `RUVLLM_MODEL_NOT_FOUND` / `RUVLLM_MODEL_LOAD_FAILED` from the backend.
+     */
+    loadModel(path: string, options?: LoadModelOptions): LoadedModelInfo;
+    /**
+     * Unload the language model and free its memory
+     */
+    unloadModel(): void;
+    /**
+     * Whether a language model is loaded
+     */
+    isModelLoaded(): boolean;
+    /**
+     * The loaded language model, or null
+     */
+    modelInfo(): LoadedModelInfo | null;
+    /**
+     * Route `text`, then answer it with the loaded model (as one user message
+     * under the model's chat template).
+     *
+     * @throws `RUVLLM_NO_LANGUAGE_MODEL` when no model is loaded, unless
+     *   `allowPlaceholder` is set (then `text` is `PLACEHOLDER_TEXT`).
+     */
+    query(text: string, config?: GenerationConfig): QueryResponse;
+    /**
+     * Continue `prompt` verbatim with the loaded model (no chat template; use
+     * `chat()` for instruction-tuned models). Returns the generated text.
+     *
+     * @throws `RUVLLM_NO_LANGUAGE_MODEL` when no model is loaded, unless
+     *   `allowPlaceholder` is set (then it returns `PLACEHOLDER_TEXT`).
+     */
+    generate(prompt: string, config?: GenerationConfig): string;
+    /**
+     * Like `generate()`, with token counts (from the model's tokenizer) and
+     * the finish reason. Always throws `RUVLLM_NO_LANGUAGE_MODEL` without a
+     * loaded model.
+     */
+    generateDetailed(prompt: string, config?: GenerationConfig): GenerationResult;
+    /**
+     * Run the loaded model on a conversation, formatted with the model's chat
+     * template (ChatML for Qwen, Llama 3 / Mistral formats for those models).
+     * Always throws `RUVLLM_NO_LANGUAGE_MODEL` without a loaded model.
+     */
+    chat(messages: ChatMessage[], config?: GenerationConfig): GenerationResult;
+    private requireModel;
+    private noModelError;
+    /** Throw `RUVLLM_NO_LANGUAGE_MODEL`, or return the labelled placeholder when opted in. */
+    private placeholderOrThrow;
+    /**
+     * Get routing decision for a query
+     */
+    route(text: string): RoutingDecision;
+    /**
+     * Search memory for similar content
+     */
+    searchMemory(text: string, k?: number): MemoryResult[];
+    /**
+     * Add content to memory
+     */
+    addMemory(content: string, metadata?: Record<string, unknown>): MemoryId;
+    /**
+     * Provide feedback for learning
+     */
+    feedback(fb: Feedback): boolean;
+    /**
+     * Get engine statistics
+     */
+    stats(): RuvLLMStats;
+    /**
+     * Force router learning cycle
+     */
+    forceLearn(): string;
+    /**
+     * Get embedding for text
+     */
+    embed(text: string): Embedding;
+    /**
+     * Compute similarity between two texts
+     */
+    similarity(text1: string, text2: string): number;
+    /**
+     * Check if SIMD is available
+     */
+    hasSimd(): boolean;
+    /**
+     * Get SIMD capabilities
+     */
+    simdCapabilities(): string[];
+    /**
+     * Batch query multiple prompts
+     */
+    batchQuery(request: BatchQueryRequest): BatchQueryResponse;
+    /**
+     * Check if native module is loaded
+     */
+    isNativeLoaded(): boolean;
+}
+//# sourceMappingURL=engine.d.ts.map

package/dist/cjs/engine.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"engine.d.ts","sourceRoot":"","sources":["../../src/engine.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,EACL,YAAY,EACZ,gBAAgB,EAChB,aAAa,EACb,eAAe,EACf,YAAY,EACZ,QAAQ,EACR,WAAW,EACX,QAAQ,EACR,SAAS,EACT,iBAAiB,EACjB,kBAAkB,EAClB,WAAW,EAEX,gBAAgB,EAChB,gBAAgB,EAChB,eAAe,EAChB,MAAM,SAAS,CAAC;AAsHjB,2FAA2F;AAC3F,eAAO,MAAM,gBAAgB,qFACuD,CAAC;AAErF;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,qBAAa,MAAM;IACjB,OAAO,CAAC,MAAM,CAA6B;IAC3C,OAAO,CAAC,aAAa,CAAuB;IAC5C,OAAO,CAAC,MAAM,CAAe;IAC7B,OAAO,CAAC,gBAAgB,CAAU;IAGlC,OAAO,CAAC,aAAa,CAInB;IAEF;;OAEG;gBACS,MAAM,CAAC,EAAE,YAAY;IA4BjC;;;;;OAKG;IACH,oBAAoB,IAAI,OAAO;IAQ/B,wEAAwE;IACxE,OAAO,CAAC,cAAc;IAUtB;;;;;;;;;;;;OAYG;IACH,SAAS,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,gBAAgB,GAAG,eAAe;IA2BpE;;OAEG;IACH,WAAW,IAAI,IAAI;IAInB;;OAEG;IACH,aAAa,IAAI,OAAO;IAIxB;;OAEG;IACH,SAAS,IAAI,eAAe,GAAG,IAAI;IAKnC;;;;;;OAMG;IACH,KAAK,CAAC,IAAI,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,gBAAgB,GAAG,aAAa;IA8B7D;;;;;;OAMG;IACH,QAAQ,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,gBAAgB,GAAG,MAAM;IAK3D;;;;OAIG;IACH,gBAAgB,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,gBAAgB,GAAG,gBAAgB;IAO7E;;;;OAIG;IACH,IAAI,CAAC,QAAQ,EAAE,WAAW,EAAE,EAAE,MAAM,CAAC,EAAE,gBAAgB,GAAG,gBAAgB;IAK1E,OAAO,CAAC,YAAY;IAKpB,OAAO,CAAC,YAAY;IA0BpB,0FAA0F;IAC1F,OAAO,CAAC,kBAAkB;IAW1B;;OAEG;IACH,KAAK,CAAC,IAAI,EAAE,MAAM,GAAG,eAAe;IAsBpC;;OAEG;IACH,YAAY,CAAC,IAAI,EAAE,MAAM,EAAE,CAAC,SAAK,GAAG,YAAY,EAAE;IAmClD;;OAEG;IACH,SAAS,CAAC,OAAO,EAAE,MAAM,EAAE,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,QAAQ;IAexE;;OAEG;IACH,QAAQ,CAAC,EAAE,EAAE,QAAQ,GAAG,OAAO;IAO/B;;OAEG;IACH,KAAK,IAAI,WAAW;IA8BpB;;OAEG;IACH,UAAU,IAAI,MAAM;IAOpB;;OAEG;IACH,KAAK,CAAC,IAAI,EAAE,MAAM,GAAG,SAAS;IAmB9B;;OAEG;IACH,UAAU,CAAC,KAAK,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,MAAM;IA6BhD;;OAEG;IACH,OAAO,IAAI,OAAO;IAOlB;;OAEG;IACH,gBAAgB,IAAI,MAAM,EAAE;IAO5B;;OAEG;IACH,UAAU,CAAC,OAAO,EAAE,iBAAiB,GAAG,kBAAkB;IAS1D;;OAEG;IACH,cAAc,IAAI,OAAO;CAG1B"}