react-native-nobodywho 0.1.2 → 0.3.0

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.3.0",
   "description": "Run LLMs locally with offline inference — React Native bindings",
   "main": "src/wrapper.ts",
   "types": "src/wrapper.ts",
@@ -47,5 +47,10 @@
   },
   "dependencies": {
     "uniffi-bindgen-react-native": "0.30.0-1"
+  },
+  "devDependencies": {
+    "@types/jest": "^30.0.0",
+    "jest": "^30.3.0",
+    "ts-jest": "^29.4.9"
   }
 }

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 { 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 { 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 RustModelInterface,
+} 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: RustModelInterface;
+
+  /** @internal */
+  private constructor(inner: RustModelInterface) {
+    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/tool.ts

@@ -5,12 +5,20 @@ import {
 } from "../generated/ts/nobodywho";
 
 /**
- * Convert a value from JSON based on the JSON Schema type.
+ * Recursively convert a value from JSON based on a JSON Schema type.
+ *
+ * Supports primitives (`string`, `number`, `integer`, `boolean`),
+ * arrays (`{ type: "array", items: ... }`), and nested objects
+ * (`{ type: "object", properties: { ... } }`).
  */
 function convertValue(
   value: unknown,
   schema: Record<string, unknown>,
 ): unknown {
+  if (value === null || value === undefined) {
+    return value;
+  }
+
   switch (schema.type) {
     case "integer":
     case "number":
@@ -19,6 +27,25 @@ function convertValue(
       return typeof value === "string" ? value === "true" : Boolean(value);
     case "string":
       return String(value);
+    case "array": {
+      if (!Array.isArray(value)) return value;
+      const itemSchema = schema.items as Record<string, unknown> | undefined;
+      if (!itemSchema) return value;
+      return value.map((item) => convertValue(item, itemSchema));
+    }
+    case "object": {
+      if (typeof value !== "object" || Array.isArray(value)) return value;
+      const properties = schema.properties as
+        | Record<string, Record<string, unknown>>
+        | undefined;
+      if (!properties) return value;
+      const obj = value as Record<string, unknown>;
+      const result: Record<string, unknown> = {};
+      for (const [key, propSchema] of Object.entries(properties)) {
+        result[key] = key in obj ? convertValue(obj[key], propSchema) : undefined;
+      }
+      return result;
+    }
     default:
       return value;
   }
@@ -78,3 +105,6 @@ export class Tool {
     return this._inner.getSchemaJson();
   }
 }
+
+/** @internal Exported for testing only. */
+export { convertValue as _convertValue };

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.