@ruvector/ruvllm 2.7.0 → 3.0.0

package/dist/esm/engine.d.ts

@@ -1,48 +1,113 @@
 /**
  * RuvLLM Engine - Main orchestrator for self-learning LLM
  */
-import { RuvLLMConfig, GenerationConfig, QueryResponse, RoutingDecision, MemoryResult, MemoryId, RuvLLMStats, Feedback, Embedding, BatchQueryRequest, BatchQueryResponse } from './types.js';
+import { RuvLLMConfig, GenerationConfig, QueryResponse, RoutingDecision, MemoryResult, MemoryId, RuvLLMStats, Feedback, Embedding, BatchQueryRequest, BatchQueryResponse, ChatMessage, GenerationResult, LoadModelOptions, LoadedModelInfo } from './types.js';
+/** 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 SIMD-optimized inference.
+ * 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({ embeddingDim: 768 });
+ * const llm = new RuvLLM();
+ * llm.loadModel('./qwen2.5-0.5b-instruct-q4_k_m.gguf');
  *
- * // Query with automatic routing
- * const response = await llm.query('What is machine learning?');
- * console.log(response.text);
+ * const out = llm.chat([{ role: 'user', content: 'What is machine learning?' }], {
+ *   maxTokens: 128,
+ * });
+ * console.log(out.text, out.finishReason, out.completionTokens);
  *
- * // Provide feedback for learning
+ * // 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);
     /**
-     * Query the LLM with automatic routing
+     * 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;
     /**
-     * Generate text with SIMD-optimized inference
+     * Continue `prompt` verbatim with the loaded model (no chat template; use
+     * `chat()` for instruction-tuned models). Returns the generated text.
      *
-     * Note: the native engine has no language-model weights, so its text is
-     * not model output; the first call emits a `RUVLLM_NO_LANGUAGE_MODEL`
-     * warning (or throws with `strict: true`). Without the native module this
-     * returns an informational message.
+     * @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
      */

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

@@ -1 +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,EACnB,MAAM,SAAS,CAAC;AA+DjB;;;;;;;;;;;;;;;;;;;GAmBG;AACH,qBAAa,MAAM;IACjB,OAAO,CAAC,MAAM,CAA6B;IAC3C,OAAO,CAAC,MAAM,CAAe;IAG7B,OAAO,CAAC,aAAa,CAInB;IAEF;;OAEG;gBACS,MAAM,CAAC,EAAE,YAAY;IAwBjC;;OAEG;IACH,KAAK,CAAC,IAAI,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,gBAAgB,GAAG,aAAa;IA6B7D;;;;;;;OAOG;IACH,QAAQ,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,gBAAgB,GAAG,MAAM;IA0B3D;;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"}
+{"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"}