react-native-nobodywho 0.1.2 → 0.2.1

package/README.md

@@ -30,13 +30,31 @@ This library uses the **GGUF format** — a binary format optimized for fast loa
 - iOS: iPhone 11 or newer with at least 4 GB of RAM.
 - Android: Snapdragon 855 / Adreno 640 / 6 GB RAM or better.
 
+## Model Loading
+
+Models can be loaded from a local file path or downloaded automatically from HuggingFace:
+
+```typescript
+import { Model } from "react-native-nobodywho";
+
+// Download from HuggingFace (cached automatically)
+const model = await Model.load({
+  modelPath: "hf://NobodyWho/Qwen_Qwen3-0.6B-GGUF/Qwen_Qwen3-0.6B-Q4_K_M.gguf",
+});
+
+// Or load from a local file
+const model = await Model.load({ modelPath: "/path/to/model.gguf" });
+```
+
+Downloaded models are cached on disk and reused on subsequent loads.
+
 ## Chat
 
 ```typescript
 import { Chat } from "react-native-nobodywho";
 
 const chat = await Chat.fromPath({
-  modelPath: "/path/to/model.gguf",
+  modelPath: "hf://NobodyWho/Qwen_Qwen3-0.6B-GGUF/Qwen_Qwen3-0.6B-Q4_K_M.gguf",
   systemPrompt: "You are a helpful assistant.",
 });
 

package/generated/cpp/nobodywho.cpp

@@ -249,7 +249,7 @@ void uniffi_nobodywho_uniffi_fn_init_callback_vtable_rusttoolcallback(
 float uniffi_nobodywho_uniffi_fn_func_cosine_similarity(
     RustBuffer a, RustBuffer b, RustCallStatus *uniffi_out_err);
 /*handle*/ uint64_t uniffi_nobodywho_uniffi_fn_func_load_model(
-    RustBuffer model_path, int8_t use_gpu, RustBuffer image_model_path);
+    RustBuffer model_path, int8_t use_gpu, RustBuffer projection_model_path);
 /*handle*/ uint64_t uniffi_nobodywho_uniffi_fn_func_sampler_preset_default(
     RustCallStatus *uniffi_out_err);
 /*handle*/ uint64_t uniffi_nobodywho_uniffi_fn_func_sampler_preset_dry(

package/generated/ts/nobodywho-ffi.ts

@@ -76,7 +76,7 @@ interface NativeModuleInterface {
     ubrn_uniffi_nobodywho_uniffi_fn_method_samplerconfig_to_json(ptr: bigint, uniffi_out_err: UniffiRustCallStatus): Uint8Array;
     ubrn_uniffi_nobodywho_uniffi_fn_init_callback_vtable_rusttoolcallback(vtable: UniffiVTableCallbackInterfaceRustToolCallback): void;
     ubrn_uniffi_nobodywho_uniffi_fn_func_cosine_similarity(a: Uint8Array, b: Uint8Array, uniffi_out_err: UniffiRustCallStatus): number;
-    ubrn_uniffi_nobodywho_uniffi_fn_func_load_model(modelPath: Uint8Array, useGpu: number, imageModelPath: Uint8Array): bigint;
+    ubrn_uniffi_nobodywho_uniffi_fn_func_load_model(modelPath: Uint8Array, useGpu: number, projectionModelPath: Uint8Array): bigint;
     ubrn_uniffi_nobodywho_uniffi_fn_func_sampler_preset_default(uniffi_out_err: UniffiRustCallStatus): bigint;
     ubrn_uniffi_nobodywho_uniffi_fn_func_sampler_preset_dry(uniffi_out_err: UniffiRustCallStatus): bigint;
     ubrn_uniffi_nobodywho_uniffi_fn_func_sampler_preset_grammar(grammar: Uint8Array, uniffi_out_err: UniffiRustCallStatus): bigint;

package/generated/ts/nobodywho.ts

@@ -95,18 +95,22 @@ export function cosineSimilarity(a: Array</*f32*/number>, b: Array</*f32*/number
     ));
     }
 /**
- * Load a GGUF model from disk.
+ * Load a GGUF model from a local path or remote URL.
+ *
+ * Accepts local filesystem paths, `hf://owner/repo/file.gguf` for HuggingFace downloads,
+ * or `https://` URLs. Downloaded models are cached automatically.
+ *
  * This is a free function instead of an async constructor because
  * uniffi-bindgen-react-native generates invalid JS (`async static` instead
  * of `static async`) for async constructors.
  */
-export async function loadModel(modelPath: string, useGpu: boolean, imageModelPath: string | undefined, asyncOpts_?: { signal: AbortSignal }): Promise<ModelInterface> /*throws*/ {
+export async function loadModel(modelPath: string, useGpu: boolean, projectionModelPath: string | undefined, asyncOpts_?: { signal: AbortSignal }): Promise<ModelInterface> /*throws*/ {
     const __stack = uniffiIsDebug ? new Error().stack : undefined;
     try {
         return await uniffiRustCallAsync(
             /*rustCaller:*/ uniffiCaller,
             /*rustFutureFunc:*/ () => {
-                return nativeModule().ubrn_uniffi_nobodywho_uniffi_fn_func_load_model(FfiConverterString.lower(modelPath),FfiConverterBool.lower(useGpu),FfiConverterOptionalString.lower(imageModelPath)
+                return nativeModule().ubrn_uniffi_nobodywho_uniffi_fn_func_load_model(FfiConverterString.lower(modelPath),FfiConverterBool.lower(useGpu),FfiConverterOptionalString.lower(projectionModelPath)
                 );
             },
             /*pollFunc:*/ nativeModule().ubrn_ffi_nobodywho_uniffi_rust_future_poll_u64,
@@ -2840,7 +2844,7 @@ function uniffiEnsureInitialized() {
     if (nativeModule().ubrn_uniffi_nobodywho_uniffi_checksum_func_cosine_similarity() !== 63439) {
         throw new UniffiInternalError.ApiChecksumMismatch("uniffi_nobodywho_uniffi_checksum_func_cosine_similarity");
     }
-    if (nativeModule().ubrn_uniffi_nobodywho_uniffi_checksum_func_load_model() !== 19243) {
+    if (nativeModule().ubrn_uniffi_nobodywho_uniffi_checksum_func_load_model() !== 57455) {
         throw new UniffiInternalError.ApiChecksumMismatch("uniffi_nobodywho_uniffi_checksum_func_load_model");
     }
     if (nativeModule().ubrn_uniffi_nobodywho_uniffi_checksum_func_sampler_preset_default() !== 10834) {

package/ios/Nobodywho.h

@@ -4,7 +4,7 @@
 #endif
 
 #ifdef RCT_NEW_ARCH_ENABLED
-#import "RNNativeModuleSpec.h"
+#import "NobodywhoSpec.h"
 
 @interface Nobodywho : NSObject <NativeNobodywhoSpec>
 #else

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "react-native-nobodywho",
-  "version": "0.1.2",
+  "version": "0.2.1",
   "description": "Run LLMs locally with offline inference — React Native bindings",
   "main": "src/wrapper.ts",
   "types": "src/wrapper.ts",

package/src/chat.ts

@@ -1,10 +1,9 @@
 import {
   RustChat,
-  loadModel,
-  type ModelInterface,
-  type SamplerConfigInterface,
-  type Message,
+  SamplerConfig,
 } from "../generated/ts/nobodywho";
+import { Model } from "./model";
+import { type ChatMessage, fromInternal, toInternal } from "./message";
 import { TokenStream } from "./streaming";
 import type { Prompt } from "./prompt";
 import type { Tool } from "./tool";
@@ -17,7 +16,7 @@ import type { Tool } from "./tool";
  *
  * @example
  * ```typescript
- * const model = await loadModel("model.gguf", true);
+ * const model = await Model.load({ modelPath: "model.gguf" });
  * const chat = new Chat({
  *   model,
  *   systemPrompt: "You are a helpful assistant.",
@@ -32,15 +31,15 @@ export class Chat {
   private readonly _inner: RustChat;
 
   constructor(opts: {
-    model: ModelInterface;
+    model: Model;
     systemPrompt?: string;
     contextSize?: number;
     templateVariables?: Map<string, boolean>;
     tools?: Tool[];
-    sampler?: SamplerConfigInterface;
+    sampler?: SamplerConfig;
   }) {
     this._inner = new RustChat(
-      opts.model,
+      opts.model._inner,
       opts.systemPrompt ?? undefined,
       opts.contextSize ?? 4096,
       opts.templateVariables ?? undefined,
@@ -64,18 +63,18 @@ export class Chat {
   static async fromPath(opts: {
     modelPath: string;
     useGpu?: boolean;
-    imageModelPath?: string;
+    projectionModelPath?: string;
     systemPrompt?: string;
     contextSize?: number;
     templateVariables?: Map<string, boolean>;
     tools?: Tool[];
-    sampler?: SamplerConfigInterface;
+    sampler?: SamplerConfig;
   }): Promise<Chat> {
-    const model = await loadModel(
-      opts.modelPath,
-      opts.useGpu ?? true,
-      opts.imageModelPath,
-    );
+    const model = await Model.load({
+      modelPath: opts.modelPath,
+      useGpu: opts.useGpu,
+      projectionModelPath: opts.projectionModelPath,
+    });
     return new Chat({ model, ...opts });
   }
 
@@ -109,13 +108,14 @@ export class Chat {
   }
 
   /** Get the current chat history as a list of messages. */
-  async getChatHistory(): Promise<Message[]> {
-    return this._inner.getChatHistory();
+  async getChatHistory(): Promise<ChatMessage[]> {
+    const internal = await this._inner.getChatHistory();
+    return internal.map(fromInternal);
   }
 
   /** Set the chat history from a list of messages. */
-  async setChatHistory(messages: Message[]): Promise<void> {
-    return this._inner.setChatHistory(messages);
+  async setChatHistory(messages: ChatMessage[]): Promise<void> {
+    return this._inner.setChatHistory(messages.map(toInternal));
   }
 
   /** Get the current system prompt. */
@@ -144,7 +144,7 @@ export class Chat {
   }
 
   /** Set the sampler configuration. */
-  async setSamplerConfig(sampler: SamplerConfigInterface): Promise<void> {
+  async setSamplerConfig(sampler: SamplerConfig): Promise<void> {
     return this._inner.setSamplerConfig(sampler);
   }
 
@@ -152,4 +152,12 @@ export class Chat {
   async getSamplerConfigJson(): Promise<string> {
     return this._inner.getSamplerConfigJson();
   }
+
+  /**
+   * Immediately free the underlying Rust resources (model context, KV cache, etc.).
+   * After calling this, the Chat instance is no longer usable.
+   */
+  destroy(): void {
+    this._inner.uniffiDestroy();
+  }
 }

package/src/cross_encoder.ts

@@ -0,0 +1,67 @@
+import { CrossEncoder as RustCrossEncoder } from "../generated/ts/nobodywho";
+import { Model } from "./model";
+
+/**
+ * A cross-encoder for ranking documents by relevance to a query.
+ *
+ * Wraps the internal CrossEncoder with an ergonomic API including
+ * a `fromPath` factory for one-step model loading.
+ *
+ * @example
+ * ```typescript
+ * const crossEncoder = await CrossEncoder.fromPath({
+ *   modelPath: "crossencoder.gguf",
+ * });
+ * const scores = await crossEncoder.rank("query", ["doc1", "doc2"]);
+ * const sorted = await crossEncoder.rankAndSort("query", ["doc1", "doc2"]);
+ * ```
+ */
+export class CrossEncoder {
+  /** @internal */
+  private readonly _inner: RustCrossEncoder;
+
+  constructor(opts: { model: Model; contextSize?: number }) {
+    this._inner = new RustCrossEncoder(
+      opts.model._inner,
+      opts.contextSize ?? undefined,
+    );
+  }
+
+  /**
+   * Create a cross-encoder directly from a model path.
+   * Loads the model and creates the cross-encoder in one step.
+   */
+  static async fromPath(opts: {
+    modelPath: string;
+    useGpu?: boolean;
+    contextSize?: number;
+  }): Promise<CrossEncoder> {
+    const model = await Model.load({ modelPath: opts.modelPath, useGpu: opts.useGpu });
+    return new CrossEncoder({ model, ...opts });
+  }
+
+  /** Rank documents by relevance to a query. Returns similarity scores. */
+  async rank(query: string, documents: string[]): Promise<number[]> {
+    return this._inner.rank(query, documents);
+  }
+
+  /**
+   * Rank documents and return them sorted by descending relevance.
+   * Returns an array of [document, score] pairs.
+   */
+  async rankAndSort(
+    query: string,
+    documents: string[],
+  ): Promise<[string, number][]> {
+    const json = await this._inner.rankAndSortJson(query, documents);
+    return JSON.parse(json);
+  }
+
+  /**
+   * Immediately free the underlying Rust resources.
+   * After calling this, the CrossEncoder instance is no longer usable.
+   */
+  destroy(): void {
+    this._inner.uniffiDestroy();
+  }
+}

package/src/encoder.ts

@@ -0,0 +1,51 @@
+import { Encoder as RustEncoder } from "../generated/ts/nobodywho";
+import { Model } from "./model";
+
+/**
+ * An embedding encoder for generating text embeddings.
+ *
+ * Wraps the internal Encoder with an ergonomic API including
+ * a `fromPath` factory for one-step model loading.
+ *
+ * @example
+ * ```typescript
+ * const encoder = await Encoder.fromPath({
+ *   modelPath: "embeddings.gguf",
+ * });
+ * const embedding = await encoder.encode("Hello world");
+ * ```
+ */
+export class Encoder {
+  /** @internal */
+  private readonly _inner: RustEncoder;
+
+  constructor(opts: { model: Model; contextSize?: number }) {
+    this._inner = new RustEncoder(opts.model._inner, opts.contextSize ?? undefined);
+  }
+
+  /**
+   * Create an encoder directly from a model path.
+   * Loads the model and creates the encoder in one step.
+   */
+  static async fromPath(opts: {
+    modelPath: string;
+    useGpu?: boolean;
+    contextSize?: number;
+  }): Promise<Encoder> {
+    const model = await Model.load({ modelPath: opts.modelPath, useGpu: opts.useGpu });
+    return new Encoder({ model, ...opts });
+  }
+
+  /** Encode text into an embedding vector. */
+  async encode(text: string): Promise<number[]> {
+    return this._inner.encode(text);
+  }
+
+  /**
+   * Immediately free the underlying Rust resources.
+   * After calling this, the Encoder instance is no longer usable.
+   */
+  destroy(): void {
+    this._inner.uniffiDestroy();
+  }
+}

package/src/message.ts

@@ -0,0 +1,75 @@
+import {
+  Message as InternalMessage,
+  Message_Tags,
+  Role,
+  type Asset,
+  type ToolCall,
+} from "../generated/ts/nobodywho";
+
+/**
+ * A chat message. The `role` field combined with the presence of
+ * `toolCalls` or `name` determines the message type:
+ *
+ * - **User/Assistant/System message:** `{ role, content, assets? }`
+ * - **Tool call request:** `{ role: Role.Assistant, content, toolCalls }`
+ * - **Tool response:** `{ role: Role.Tool, name, content }`
+ *
+ * @example
+ * ```typescript
+ * const history = await chat.getChatHistory();
+ * for (const msg of history) {
+ *   if ("toolCalls" in msg) {
+ *     console.log("Tool calls:", msg.toolCalls);
+ *   } else if ("name" in msg) {
+ *     console.log("Tool response:", msg.name, msg.content);
+ *   } else {
+ *     console.log(msg.role, msg.content);
+ *   }
+ * }
+ * ```
+ */
+export type ChatMessage =
+  | { role: Role.User | Role.Assistant | Role.System; content: string; assets?: Asset[] }
+  | { role: Role.Assistant; content: string; toolCalls: ToolCall[] }
+  | { role: Role.Tool; name: string; content: string };
+
+/** @internal Convert internal Message to ChatMessage */
+export function fromInternal(msg: InternalMessage): ChatMessage {
+  if (msg.tag === Message_Tags.Message) {
+    const { role, content, assets } = msg.inner;
+    return {
+      role: role as Role.User | Role.Assistant | Role.System,
+      content,
+      ...(assets.length > 0 ? { assets } : {}),
+    };
+  } else if (msg.tag === Message_Tags.ToolCalls) {
+    const { role, content, toolCalls } = msg.inner;
+    return { role: role as Role.Assistant, content, toolCalls };
+  } else {
+    const { role, name, content } = msg.inner;
+    return { role: role as Role.Tool, name, content };
+  }
+}
+
+/** @internal Convert ChatMessage to internal Message */
+export function toInternal(msg: ChatMessage): InternalMessage {
+  if ("toolCalls" in msg) {
+    return new InternalMessage.ToolCalls({
+      role: msg.role,
+      content: msg.content,
+      toolCalls: msg.toolCalls,
+    });
+  } else if ("name" in msg) {
+    return new InternalMessage.ToolResp({
+      role: msg.role,
+      name: msg.name,
+      content: msg.content,
+    });
+  } else {
+    return new InternalMessage.Message({
+      role: msg.role,
+      content: msg.content,
+      assets: msg.assets ?? [],
+    });
+  }
+}

package/src/model.ts

@@ -0,0 +1,63 @@
+import {
+  loadModel,
+  type ModelInterface,
+} from "../generated/ts/nobodywho";
+
+/**
+ * A loaded LLM model that can be shared across Chat, Encoder, and CrossEncoder instances.
+ *
+ * @example
+ * ```typescript
+ * // Load from a local file
+ * const model = await Model.load({ modelPath: "model.gguf" });
+ * const chat = new Chat({ model, systemPrompt: "You are helpful." });
+ *
+ * // Download from HuggingFace (cached automatically)
+ * const model = await Model.load({
+ *   modelPath: "hf://NobodyWho/Qwen_Qwen3-0.6B-GGUF/Qwen_Qwen3-0.6B-Q4_K_M.gguf",
+ * });
+ *
+ * // With vision support
+ * const visionModel = await Model.load({
+ *   modelPath: "model.gguf",
+ *   projectionModelPath: "mmproj.gguf",
+ * });
+ * ```
+ */
+export class Model {
+  /** @internal */
+  readonly _inner: ModelInterface;
+
+  /** @internal */
+  private constructor(inner: ModelInterface) {
+    this._inner = inner;
+  }
+
+  /**
+   * Load a GGUF model from a local path or remote URL.
+   *
+   * @param opts.modelPath - Path to the GGUF model file, or a `hf://owner/repo/file.gguf` / `https://` URL to download and cache automatically
+   * @param opts.useGpu - Use GPU acceleration if available (default: true)
+   * @param opts.projectionModelPath - Path to a multimodal projector file for vision models
+   */
+  static async load(opts: {
+    modelPath: string;
+    useGpu?: boolean;
+    projectionModelPath?: string;
+  }): Promise<Model> {
+    const inner = await loadModel(
+      opts.modelPath,
+      opts.useGpu ?? true,
+      opts.projectionModelPath,
+    );
+    return new Model(inner);
+  }
+
+  /**
+   * Immediately free the underlying Rust resources (model weights, GPU memory).
+   * After calling this, the Model instance is no longer usable.
+   */
+  destroy(): void {
+    (this._inner as any).uniffiDestroy();
+  }
+}

package/src/sampler_presets.ts

@@ -1,5 +1,5 @@
-import type { SamplerConfigInterface } from "../generated/ts/nobodywho";
 import {
+  type SamplerConfig,
   samplerPresetDefault,
   samplerPresetDry,
   samplerPresetGrammar,
@@ -23,42 +23,42 @@ export class SamplerPresets {
   private constructor() {}
 
   /** Get the default sampler configuration. */
-  static default(): SamplerConfigInterface {
+  static default(): SamplerConfig {
     return samplerPresetDefault();
   }
 
   /** Create a sampler with top-k filtering only. */
-  static topK(topK: number): SamplerConfigInterface {
+  static topK(topK: number): SamplerConfig {
     return samplerPresetTopK(topK);
   }
 
   /** Create a sampler with nucleus (top-p) sampling. */
-  static topP(topP: number): SamplerConfigInterface {
+  static topP(topP: number): SamplerConfig {
     return samplerPresetTopP(topP);
   }
 
   /** Create a greedy sampler (always picks most probable token). */
-  static greedy(): SamplerConfigInterface {
+  static greedy(): SamplerConfig {
     return samplerPresetGreedy();
   }
 
   /** Create a sampler with temperature scaling. */
-  static temperature(temperature: number): SamplerConfigInterface {
+  static temperature(temperature: number): SamplerConfig {
     return samplerPresetTemperature(temperature);
   }
 
   /** Create a DRY sampler preset to reduce repetition. */
-  static dry(): SamplerConfigInterface {
+  static dry(): SamplerConfig {
     return samplerPresetDry();
   }
 
   /** Create a sampler configured for JSON output generation. */
-  static json(): SamplerConfigInterface {
+  static json(): SamplerConfig {
     return samplerPresetJson();
   }
 
   /** Create a sampler with a custom grammar constraint. */
-  static grammar(grammar: string): SamplerConfigInterface {
+  static grammar(grammar: string): SamplerConfig {
     return samplerPresetGrammar(grammar);
   }
 }

package/src/wrapper.ts

@@ -2,45 +2,37 @@
  * NobodyWho — React Native bindings for local LLM inference.
  *
  * This is the public entry point. It re-exports the public API:
- * - Wrapper classes: Chat, Tool, TokenStream (wrapping internal Rust* types)
- * - Direct re-exports: Model, Encoder, CrossEncoder, SamplerBuilder, SamplerConfig, etc.
- * - Utilities: SamplerPresets, loadModel, cosineSimilarity
+ * - Wrapper classes: Model, Chat, Encoder, CrossEncoder, Tool, TokenStream, Prompt
+ * - Direct re-exports: SamplerBuilder, SamplerConfig, Role
+ * - Types: ChatMessage, Asset, ToolCall
+ * - Utilities: SamplerPresets, cosineSimilarity
  *
  * This file is NOT generated — it is safe to edit.
  */
 
-// Wrapper classes that hide the internal Rust* types.
+// Wrapper classes
+export { Model } from "./model";
 export { Chat } from "./chat";
+export { Encoder } from "./encoder";
+export { CrossEncoder } from "./cross_encoder";
 export { Prompt } from "./prompt";
 export { Tool } from "./tool";
 export { TokenStream } from "./streaming";
 
+// Message types
+export type { ChatMessage } from "./message";
+
 // Re-export types that don't need wrapping.
 export {
-  Model,
-  Encoder,
-  CrossEncoder,
   SamplerBuilder,
   SamplerConfig,
   Role,
-  Message,
-  Message_Tags,
-  PromptPart,
-  PromptPart_Tags,
   cosineSimilarity,
-  loadModel,
-  uniffiInitAsync,
 } from "./index";
 
 export type {
-  ModelInterface,
-  EncoderInterface,
-  CrossEncoderInterface,
-  SamplerBuilderInterface,
-  SamplerConfigInterface,
   Asset,
   ToolCall,
-  ToolParameter,
 } from "./index";
 
 // Ergonomic wrapper additions.