react-native-nitro-mlx 0.2.2 → 0.3.0

package/nitrogen/generated/shared/c++/ToolParameter.hpp

@@ -0,0 +1,87 @@
+///
+/// ToolParameter.hpp
+/// This file was generated by nitrogen. DO NOT MODIFY THIS FILE.
+/// https://github.com/mrousavy/nitro
+/// Copyright © 2026 Marc Rousavy @ Margelo
+///
+
+#pragma once
+
+#if __has_include(<NitroModules/JSIConverter.hpp>)
+#include <NitroModules/JSIConverter.hpp>
+#else
+#error NitroModules cannot be found! Are you sure you installed NitroModules properly?
+#endif
+#if __has_include(<NitroModules/NitroDefines.hpp>)
+#include <NitroModules/NitroDefines.hpp>
+#else
+#error NitroModules cannot be found! Are you sure you installed NitroModules properly?
+#endif
+#if __has_include(<NitroModules/JSIHelpers.hpp>)
+#include <NitroModules/JSIHelpers.hpp>
+#else
+#error NitroModules cannot be found! Are you sure you installed NitroModules properly?
+#endif
+
+
+
+#include <string>
+
+namespace margelo::nitro::mlxreactnative {
+
+  /**
+   * A struct which can be represented as a JavaScript object (ToolParameter).
+   */
+  struct ToolParameter {
+  public:
+    std::string name     SWIFT_PRIVATE;
+    std::string type     SWIFT_PRIVATE;
+    std::string description     SWIFT_PRIVATE;
+    bool required     SWIFT_PRIVATE;
+
+  public:
+    ToolParameter() = default;
+    explicit ToolParameter(std::string name, std::string type, std::string description, bool required): name(name), type(type), description(description), required(required) {}
+  };
+
+} // namespace margelo::nitro::mlxreactnative
+
+namespace margelo::nitro {
+
+  // C++ ToolParameter <> JS ToolParameter (object)
+  template <>
+  struct JSIConverter<margelo::nitro::mlxreactnative::ToolParameter> final {
+    static inline margelo::nitro::mlxreactnative::ToolParameter fromJSI(jsi::Runtime& runtime, const jsi::Value& arg) {
+      jsi::Object obj = arg.asObject(runtime);
+      return margelo::nitro::mlxreactnative::ToolParameter(
+        JSIConverter<std::string>::fromJSI(runtime, obj.getProperty(runtime, "name")),
+        JSIConverter<std::string>::fromJSI(runtime, obj.getProperty(runtime, "type")),
+        JSIConverter<std::string>::fromJSI(runtime, obj.getProperty(runtime, "description")),
+        JSIConverter<bool>::fromJSI(runtime, obj.getProperty(runtime, "required"))
+      );
+    }
+    static inline jsi::Value toJSI(jsi::Runtime& runtime, const margelo::nitro::mlxreactnative::ToolParameter& arg) {
+      jsi::Object obj(runtime);
+      obj.setProperty(runtime, "name", JSIConverter<std::string>::toJSI(runtime, arg.name));
+      obj.setProperty(runtime, "type", JSIConverter<std::string>::toJSI(runtime, arg.type));
+      obj.setProperty(runtime, "description", JSIConverter<std::string>::toJSI(runtime, arg.description));
+      obj.setProperty(runtime, "required", JSIConverter<bool>::toJSI(runtime, arg.required));
+      return obj;
+    }
+    static inline bool canConvert(jsi::Runtime& runtime, const jsi::Value& value) {
+      if (!value.isObject()) {
+        return false;
+      }
+      jsi::Object obj = value.getObject(runtime);
+      if (!nitro::isPlainObject(runtime, obj)) {
+        return false;
+      }
+      if (!JSIConverter<std::string>::canConvert(runtime, obj.getProperty(runtime, "name"))) return false;
+      if (!JSIConverter<std::string>::canConvert(runtime, obj.getProperty(runtime, "type"))) return false;
+      if (!JSIConverter<std::string>::canConvert(runtime, obj.getProperty(runtime, "description"))) return false;
+      if (!JSIConverter<bool>::canConvert(runtime, obj.getProperty(runtime, "required"))) return false;
+      return true;
+    }
+  };
+
+} // namespace margelo::nitro

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "react-native-nitro-mlx",
-  "version": "0.2.2",
+  "version": "0.3.0",
   "description": "Nitro module package",
   "main": "./lib/module/index.js",
   "module": "./lib/module/index.js",
@@ -11,7 +11,7 @@
     "build": "rm -rf lib && bun typecheck && bob build",
     "typecheck": "tsc --noEmit",
     "clean": "rm -rf android/build node_modules/**/android/build lib android/.cxx node_modules/**/android/.cxx",
-    "release": "release-it",
+    "release": "release-it && npm publish",
     "specs": "bun typecheck && nitrogen --logLevel=\\\"debug\\\" && bun run build",
     "specs:pod": "bun specs && bun --cwd ../example pod"
   },
@@ -68,13 +68,14 @@
   "peerDependencies": {
     "react": "*",
     "react-native": "*",
-    "react-native-nitro-modules": "*"
+    "react-native-nitro-modules": "*",
+    "zod": ">=4.0.0"
+  },
+  "dependencies": {
+    "zod": "^4.3.5"
   },
   "release-it": {
-    "npm": {
-      "publish": true,
-      "skipVersion": true
-    },
+    "npm": false,
     "github": {
       "release": true,
       "releaseName": "v${version}"

package/src/index.ts

@@ -1,4 +1,4 @@
-export { LLM, type Message } from './llm'
+export { LLM, type Message, type ToolCallInfo, type ToolCallUpdate } from './llm'
 export { ModelManager } from './modelManager'
 export {
   MLXModel,
@@ -8,6 +8,13 @@ export {
   ModelProvider,
   type ModelQuantization,
 } from './models'
-
-export type { GenerationStats, LLM as LLMSpec, LLMLoadOptions } from './specs/LLM.nitro'
+export type {
+  GenerationStats,
+  LLM as LLMSpec,
+  LLMLoadOptions,
+  ToolDefinition,
+  ToolParameter,
+  ToolParameterType,
+} from './specs/LLM.nitro'
 export type { ModelManager as ModelManagerSpec } from './specs/ModelManager.nitro'
+export { createTool, type TypeSafeToolDefinition } from './tool-utils'

package/src/llm.ts

@@ -8,6 +8,16 @@ export type Message = {
   content: string
 }
 
+export type ToolCallInfo = {
+  name: string
+  arguments: Record<string, unknown>
+}
+
+export type ToolCallUpdate = {
+  toolCall: ToolCallInfo
+  allToolCalls: ToolCallInfo[]
+}
+
 function getInstance(): LLMSpec {
   if (!instance) {
     instance = NitroModules.createHybridObject<LLMSpec>('LLM')
@@ -58,13 +68,42 @@ export const LLM = {
   },
 
   /**
-   * Stream a response token by token.
+   * Stream a response token by token with optional tool calling support.
+   * Tools must be provided when loading the model via `load()` options.
+   * Tools are automatically executed when the model calls them.
    * @param prompt - The input text to generate a response for
    * @param onToken - Callback invoked for each generated token
+   * @param onToolCall - Optional callback invoked when a tool is called.
+   *   Receives the current tool call and an accumulated array of all tool calls so far.
    * @returns The complete generated text
    */
-  stream(prompt: string, onToken: (token: string) => void): Promise<string> {
-    return getInstance().stream(prompt, onToken)
+  stream(
+    prompt: string,
+    onToken: (token: string) => void,
+    onToolCall?: (update: ToolCallUpdate) => void,
+  ): Promise<string> {
+    const accumulatedToolCalls: ToolCallInfo[] = []
+
+    return getInstance().stream(prompt, onToken, (name: string, argsJson: string) => {
+      if (onToolCall) {
+        try {
+          const args = JSON.parse(argsJson) as Record<string, unknown>
+          const toolCall = { name, arguments: args }
+          accumulatedToolCalls.push(toolCall)
+          onToolCall({
+            toolCall,
+            allToolCalls: [...accumulatedToolCalls],
+          })
+        } catch {
+          const toolCall = { name, arguments: {} }
+          accumulatedToolCalls.push(toolCall)
+          onToolCall({
+            toolCall,
+            allToolCalls: [...accumulatedToolCalls],
+          })
+        }
+      }
+    })
   },
 
   /**

package/src/specs/LLM.nitro.ts

@@ -1,4 +1,4 @@
-import type { HybridObject } from 'react-native-nitro-modules'
+import type { AnyMap, HybridObject } from 'react-native-nitro-modules'
 
 /**
  * Statistics from the last text generation.
@@ -19,6 +19,26 @@ export interface LLMMessage {
   content: string
 }
 
+/**
+ * Parameter definition for a tool.
+ */
+export interface ToolParameter {
+  name: string
+  type: string
+  description: string
+  required: boolean
+}
+
+/**
+ * Tool definition that can be called by the model.
+ */
+export interface ToolDefinition {
+  name: string
+  description: string
+  parameters: ToolParameter[]
+  handler: (args: AnyMap) => Promise<AnyMap>
+}
+
 /** Options for loading a model.
  */
 export interface LLMLoadOptions {
@@ -28,6 +48,8 @@ export interface LLMLoadOptions {
   additionalContext?: LLMMessage[]
   /** Whether to automatically manage message history */
   manageHistory?: boolean
+  /** Tools available for the model to call */
+  tools?: ToolDefinition[]
 }
 
 /**
@@ -50,12 +72,18 @@ export interface LLM extends HybridObject<{ ios: 'swift' }> {
   generate(prompt: string): Promise<string>
 
   /**
-   * Stream a response token by token.
+   * Stream a response token by token with optional tool calling support.
+   * Tools are automatically executed when the model calls them.
    * @param prompt - The input text to generate a response for
    * @param onToken - Callback invoked for each generated token
+   * @param onToolCall - Optional callback invoked when a tool is called (for UI feedback)
    * @returns The complete generated text
    */
-  stream(prompt: string, onToken: (token: string) => void): Promise<string>
+  stream(
+    prompt: string,
+    onToken: (token: string) => void,
+    onToolCall?: (toolName: string, args: string) => void,
+  ): Promise<string>
 
   /**
    * Stop the current generation.
@@ -96,3 +124,9 @@ export interface LLM extends HybridObject<{ ios: 'swift' }> {
   /** System prompt used when loading the model */
   systemPrompt: string
 }
+
+/**
+ * Supported parameter types for tool definitions.
+ * Used for type safety in createTool().
+ */
+export type ToolParameterType = 'string' | 'number' | 'boolean' | 'array' | 'object'

package/src/tool-utils.ts

@@ -0,0 +1,74 @@
+import type { AnyMap } from 'react-native-nitro-modules'
+import type { z } from 'zod'
+import type { ToolDefinition, ToolParameter, ToolParameterType } from './specs/LLM.nitro'
+
+type ZodObjectSchema = z.ZodObject<z.core.$ZodShape>
+type InferArgs<T extends ZodObjectSchema> = z.infer<T>
+
+export interface TypeSafeToolDefinition<T extends ZodObjectSchema> {
+  name: string
+  description: string
+  arguments: T
+  handler: (args: InferArgs<T>) => Promise<Record<string, unknown>>
+}
+
+function getZodTypeString(zodType: z.ZodType): ToolParameterType {
+  const typeName = zodType._zod.def.type
+  switch (typeName) {
+    case 'string':
+      return 'string'
+    case 'number':
+    case 'int':
+      return 'number'
+    case 'boolean':
+      return 'boolean'
+    case 'array':
+      return 'array'
+    case 'object':
+      return 'object'
+    case 'optional':
+      return getZodTypeString((zodType as z.ZodOptional<z.ZodType>)._zod.def.innerType)
+    case 'default':
+      return getZodTypeString((zodType as z.ZodDefault<z.ZodType>)._zod.def.innerType)
+    default:
+      return 'string'
+  }
+}
+
+function isZodOptional(zodType: z.ZodType): boolean {
+  const typeName = zodType._zod.def.type
+  return typeName === 'optional' || typeName === 'default'
+}
+
+function zodSchemaToParameters(schema: ZodObjectSchema): ToolParameter[] {
+  const shape = schema._zod.def.shape
+  const parameters: ToolParameter[] = []
+
+  for (const [key, zodType] of Object.entries(shape)) {
+    const zType = zodType as z.ZodType
+    parameters.push({
+      name: key,
+      type: getZodTypeString(zType),
+      description: zType.description ?? '',
+      required: !isZodOptional(zType),
+    })
+  }
+
+  return parameters
+}
+
+export function createTool<T extends ZodObjectSchema>(
+  definition: TypeSafeToolDefinition<T>,
+): ToolDefinition {
+  return {
+    name: definition.name,
+    description: definition.description,
+    parameters: zodSchemaToParameters(definition.arguments),
+    handler: async (args: AnyMap) => {
+      const argsObj = args as unknown as Record<string, unknown>
+      const parsedArgs = definition.arguments.parse(argsObj)
+      const result = await definition.handler(parsedArgs)
+      return result as unknown as AnyMap
+    },
+  }
+}