expo-local-llm 0.1.3 → 0.2.1

package/README.md

@@ -6,7 +6,7 @@ Expo module for on-device LLM inference. Wraps Apple Foundation Models (iOS 26+)
 
 | Platform | Requirement |
 |----------|-------------|
-| iOS | iOS 26+ with Apple Intelligence enabled. Loads on iOS 16+ without crashing (returns `notEligible`). |
+| iOS | iOS 26+ with Apple Intelligence enabled. Loads on iOS 16+ without crashing (returns `notEligible`). Host project must target iOS 16.0+. |
 | Android | Device with Gemini Nano support (Pixel 8+, Galaxy S25+). Model may require download. |
 
 ## Installation
@@ -58,6 +58,55 @@ function Chat() {
 }
 ```
 
+### Tool Calling (iOS 26+)
+
+```tsx
+import { useLocalLLM } from 'expo-local-llm';
+
+function WeatherChat() {
+  const { streamResponse, streamedText, activeToolCalls, error } = useLocalLLM({
+    instructions: 'You are a helpful weather assistant.',
+    tools: [
+      {
+        name: 'getWeather',
+        description: 'Get the current weather for a city',
+        parameters: {
+          city: { type: 'string', description: 'The city name' },
+        },
+        handler: async (args) => {
+          const res = await fetch(`https://api.example.com/weather?city=${args.city}`);
+          return JSON.stringify(await res.json());
+        },
+      },
+    ],
+  });
+
+  return (
+    <View>
+      {activeToolCalls.length > 0 && (
+        <Text>Using {activeToolCalls.map((c) => c.toolName).join(', ')}...</Text>
+      )}
+      <Text>{streamedText}</Text>
+    </View>
+  );
+}
+```
+
+### Structured Output
+
+```tsx
+const { respond } = useLocalLLM({
+  responseFormat: 'json',
+  schema: {
+    name: { type: 'string', description: 'Recipe name' },
+    ingredients: { type: 'array', description: 'List of ingredients' },
+    steps: { type: 'array', description: 'Cooking steps' },
+  },
+});
+
+const recipe = JSON.parse(await respond('Give me a pasta recipe'));
+```
+
 ## API
 
 ### `useLocalLLM(options?)`
@@ -70,6 +119,10 @@ function Chat() {
 | `options.temperature` | `number` | Sampling temperature |
 | `options.maxTokens` | `number` | Max output tokens (capped at 256 on Android) |
 | `options.topK` | `number` | Top-K sampling |
+| `tools` | `ToolDefinition[]` | Tools the model can invoke (iOS 26+ only) |
+| `toolTimeout` | `number` | Seconds before an unresolved tool call times out (default 30) |
+| `responseFormat` | `"text" \| "json"` | Set to `"json"` for structured JSON output |
+| `schema` | `Record<string, any>` | JSON schema for structured output (used with `responseFormat: "json"`) |
 
 #### Returns
 
@@ -80,8 +133,10 @@ function Chat() {
 | `streamedText` | `string` | Accumulated text from current stream |
 | `downloadProgress` | `number \| null` | Download progress 0-1 (Android only) |
 | `error` | `string \| null` | Last error message |
+| `activeToolCalls` | `ActiveToolCall[]` | In-flight tool calls (`{ callId, toolName }`) |
 | `respond` | `(prompt: string) => Promise<string>` | Non-streaming generation. `undefined` when unavailable. |
-| `streamResponse` | `(prompt: string) => Promise<void>` | Streaming generation (updates `streamedText`). `undefined` when unavailable. |
+| `session` | `LLMSession \| null` | The native session object. `null` when unavailable. |
+| `streamResponse` | `(prompt: string) => Promise<void>` | Streaming generation (updates `streamedText`). `undefined` when model not `available`. |
 | `cancelStream` | `() => Promise<void>` | Cancel active stream. `undefined` when unavailable. |
 | `downloadModel` | `() => Promise<void>` | Trigger model download (Android). `undefined` when unavailable. |
 
@@ -101,9 +156,62 @@ function Chat() {
 
 ## Known Limitations
 
-- **v0.1.0**: Only one active stream at a time. Events are not scoped to session ID.
-- **Android**: Gemini Nano SDK is in beta. API surface may change.
-- No tool calling or structured output yet.
+- Only one active stream at a time. Events are not scoped to session ID.
+- **Android**: Gemini Nano SDK is in beta. API surface may change — not yet validated on device.
+- **iOS**: Apple's Foundation Model may refuse certain categories of prompts (e.g. personal health data interpretation) due to built-in safety guardrails.
+- Methods (`respond`, `streamResponse`, `cancelStream`) are only defined when `availability === 'available'`.
+- Tool calling is iOS 26+ only. Android will throw at session creation if tools are passed.
+- Structured output uses instruction-based JSON guidance, not Apple's constrained decoding.
+
+## Why an Expo module?
+
+This is built as an [Expo Module](https://docs.expo.dev/modules/overview/), not
+a bare React Native library. Here's why:
+
+- **`expo install` and go** — no manual Xcode/Gradle linking, no `pod install`
+  surprises. Works with `npx expo prebuild` and managed workflow out of the box.
+- **SharedObject lifecycle** — `LLMSession` extends Expo's `SharedObject`, which
+  handles native memory management, event subscriptions, and cleanup
+  automatically when the JS object is garbage collected. In bare RN you'd wire
+  this yourself with `NativeEventEmitter` and manual release calls.
+- **Class DSL** — the native module exposes `LLMSession` as a first-class JS
+  object with instance methods (`session.respond()`, `session.streamResponse()`)
+  rather than flat module-level functions with session IDs. This is an Expo
+  Modules API feature that doesn't exist in the classic RN bridge.
+- **Cross-platform parity** — Expo's Kotlin DSL mirrors the Swift DSL, so the
+  iOS and Android modules have the same structure. Adding Android tool calling
+  later means implementing the same interface, not building a separate bridge.
+
+If you're on bare React Native without Expo, this module won't work — you'd need
+to add `expo-modules-core` as a dependency or use a different library.
+
+## How is this different from @callstack/ai? (as of March 2026)
+
+[@callstack/ai](https://github.com/callstackincubator/ai) is a full-featured
+framework that supports multiple on-device backends (Apple Foundation Models,
+Llama/GGUF, MLC) with Vercel AI SDK integration, generative UI, and DevTools.
+
+`expo-local-llm` takes a different approach:
+
+| | `expo-local-llm` | `@callstack/ai` |
+|---|---|---|
+| **Philosophy** | Thin bridge to the OS-provided model | Multi-backend AI framework |
+| **iOS model** | Apple Foundation Models (system-provided) | Apple Foundation Models, Llama, MLC |
+| **Android model** | Gemini Nano (system-provided) | No Android support |
+| **Model management** | None — the OS handles it | You configure/download models |
+| **Bundle size impact** | Near zero | Depends on backend + model weights |
+| **Tool calling** | Yes (iOS 26+) | Yes |
+| **Structured output** | Yes (instruction-based) | Yes |
+| **Expo native module** | Yes — `expo install` and go | Bare React Native setup |
+| **Dependencies** | None | Vercel AI SDK, Jotai, backend runtimes |
+
+**Choose `expo-local-llm` if** you want the simplest path to on-device LLM in
+an Expo app and are happy using whatever model the OS provides. There's nothing
+to configure, no weights to bundle, and it works on both iOS and Android.
+
+**Choose `@callstack/ai` if** you need to pick specific models (Llama 3.2,
+Phi-3, Mistral), want Vercel AI SDK compatibility, or need the generative UI
+and DevTools ecosystem.
 
 ## License
 

package/android/src/main/java/expo/modules/localllm/Exceptions.kt

@@ -10,3 +10,6 @@ class SessionInvalidException :
 
 class StreamException(message: String) :
   CodedException("ERR_STREAM", message, null)
+
+class ToolNotSupportedException :
+  CodedException("ERR_TOOL_NOT_SUPPORTED", "Tool calling is not supported on Android yet", null)

package/android/src/main/java/expo/modules/localllm/ExpoLocalLlmModule.kt

@@ -32,6 +32,9 @@ class ExpoLocalLlmModule : Module() {
 
     Class(LLMSession::class) {
       Constructor { config: SessionConfig ->
+        if (!config.tools.isNullOrEmpty()) {
+          throw ToolNotSupportedException()
+        }
         LLMSession(appContext.reactContext!!, config)
       }
 
@@ -47,6 +50,24 @@ class ExpoLocalLlmModule : Module() {
         session.cancelStream()
       }
 
+      // Tool calling stubs — not yet supported on Android
+      Function("registerTool") { _: LLMSession, _: ToolConfig ->
+        throw ToolNotSupportedException()
+      }
+
+      Function("unregisterTool") { _: LLMSession, _: String ->
+        throw ToolNotSupportedException()
+      }
+
+      Function("resolveToolCall") { _: LLMSession, _: String, _: String ->
+        throw ToolNotSupportedException()
+      }
+
+      Function("rejectToolCall") { _: LLMSession, _: String, _: String ->
+        throw ToolNotSupportedException()
+      }
+
+      Events("token", "streamComplete", "streamError", "toolCall")
     }
 
     OnActivityDestroys {

package/android/src/main/java/expo/modules/localllm/Records.kt

@@ -9,6 +9,18 @@ class SessionConfig : Record {
 
   @Field
   var options: GenerationOptionsRecord? = null
+
+  @Field
+  var tools: List<ToolConfig>? = null
+
+  @Field
+  var toolTimeout: Double? = null
+
+  @Field
+  var responseFormat: String? = null
+
+  @Field
+  var schema: Map<String, Any>? = null
 }
 
 class GenerationOptionsRecord : Record {
@@ -21,3 +33,14 @@ class GenerationOptionsRecord : Record {
   @Field
   var topK: Int? = null
 }
+
+class ToolConfig : Record {
+  @Field
+  var name: String = ""
+
+  @Field
+  var description: String = ""
+
+  @Field
+  var parameters: Map<String, Any> = emptyMap()
+}

package/build/ExpoLocalLlm.types.d.ts

@@ -4,9 +4,40 @@ export type GenerationOptions = {
     maxTokens?: number;
     topK?: number;
 };
+export type ToolParameterType = "string" | "number" | "boolean";
+export type ToolParameter = {
+    type: ToolParameterType;
+    description: string;
+    enum?: string[];
+};
+export type ToolDefinition = {
+    name: string;
+    description: string;
+    parameters: Record<string, ToolParameter>;
+    handler: (args: Record<string, any>) => Promise<string>;
+};
+export type ToolConfig = {
+    name: string;
+    description: string;
+    parameters: Record<string, ToolParameter>;
+};
+export type ToolCallEvent = {
+    callId: string;
+    toolName: string;
+    arguments: Record<string, any>;
+};
+export type ActiveToolCall = {
+    callId: string;
+    toolName: string;
+};
+export type ResponseFormat = "text" | "json";
 export type SessionConfig = {
     instructions?: string;
     options?: GenerationOptions;
+    tools?: ToolDefinition[];
+    toolTimeout?: number;
+    responseFormat?: ResponseFormat;
+    schema?: Record<string, any>;
 };
 export type TokenEvent = {
     token: string;
@@ -25,6 +56,7 @@ export type LLMSessionEvents = {
     token: (event: TokenEvent) => void;
     streamComplete: (event: StreamCompleteEvent) => void;
     streamError: (event: StreamErrorEvent) => void;
+    toolCall: (event: ToolCallEvent) => void;
 };
 export type ExpoLocalLlmModuleEvents = {
     downloadProgress: (event: DownloadProgress) => void;

package/build/ExpoLocalLlm.types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"ExpoLocalLlm.types.d.ts","sourceRoot":"","sources":["../src/ExpoLocalLlm.types.ts"],"names":[],"mappings":"AAAA,MAAM,MAAM,iBAAiB,GACzB,WAAW,GACX,YAAY,GACZ,UAAU,GACV,aAAa,GACb,kBAAkB,GAClB,aAAa,GACb,SAAS,CAAC;AAEd,MAAM,MAAM,iBAAiB,GAAG;IAC9B,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,IAAI,CAAC,EAAE,MAAM,CAAC;CACf,CAAC;AAEF,MAAM,MAAM,aAAa,GAAG;IAC1B,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,OAAO,CAAC,EAAE,iBAAiB,CAAC;CAC7B,CAAC;AAEF,MAAM,MAAM,UAAU,GAAG;IACvB,KAAK,EAAE,MAAM,CAAC;IACd,WAAW,EAAE,MAAM,CAAC;CACrB,CAAC;AAEF,MAAM,MAAM,mBAAmB,GAAG;IAChC,IAAI,EAAE,MAAM,CAAC;CACd,CAAC;AAEF,MAAM,MAAM,gBAAgB,GAAG;IAC7B,KAAK,EAAE,MAAM,CAAC;CACf,CAAC;AAEF,MAAM,MAAM,gBAAgB,GAAG;IAC7B,QAAQ,EAAE,MAAM,CAAC;CAClB,CAAC;AAEF,MAAM,MAAM,gBAAgB,GAAG;IAC7B,KAAK,EAAE,CAAC,KAAK,EAAE,UAAU,KAAK,IAAI,CAAC;IACnC,cAAc,EAAE,CAAC,KAAK,EAAE,mBAAmB,KAAK,IAAI,CAAC;IACrD,WAAW,EAAE,CAAC,KAAK,EAAE,gBAAgB,KAAK,IAAI,CAAC;CAChD,CAAC;AAEF,MAAM,MAAM,wBAAwB,GAAG;IACrC,gBAAgB,EAAE,CAAC,KAAK,EAAE,gBAAgB,KAAK,IAAI,CAAC;IACpD,kBAAkB,EAAE,CAAC,KAAK,EAAE;QAAE,YAAY,EAAE,iBAAiB,CAAA;KAAE,KAAK,IAAI,CAAC;CAC1E,CAAC"}
+{"version":3,"file":"ExpoLocalLlm.types.d.ts","sourceRoot":"","sources":["../src/ExpoLocalLlm.types.ts"],"names":[],"mappings":"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"}

package/build/ExpoLocalLlm.types.js.map

@@ -1 +1 @@
-{"version":3,"file":"ExpoLocalLlm.types.js","sourceRoot":"","sources":["../src/ExpoLocalLlm.types.ts"],"names":[],"mappings":"","sourcesContent":["export type ModelAvailability =\n  | \"available\"\n  | \"notEnabled\"\n  | \"notReady\"\n  | \"notEligible\"\n  | \"downloadRequired\"\n  | \"downloading\"\n  | \"unknown\";\n\nexport type GenerationOptions = {\n  temperature?: number;\n  maxTokens?: number;\n  topK?: number;\n};\n\nexport type SessionConfig = {\n  instructions?: string;\n  options?: GenerationOptions;\n};\n\nexport type TokenEvent = {\n  token: string;\n  accumulated: string;\n};\n\nexport type StreamCompleteEvent = {\n  text: string;\n};\n\nexport type StreamErrorEvent = {\n  error: string;\n};\n\nexport type DownloadProgress = {\n  progress: number;\n};\n\nexport type LLMSessionEvents = {\n  token: (event: TokenEvent) => void;\n  streamComplete: (event: StreamCompleteEvent) => void;\n  streamError: (event: StreamErrorEvent) => void;\n};\n\nexport type ExpoLocalLlmModuleEvents = {\n  downloadProgress: (event: DownloadProgress) => void;\n  availabilityChange: (event: { availability: ModelAvailability }) => void;\n};\n"]}
+{"version":3,"file":"ExpoLocalLlm.types.js","sourceRoot":"","sources":["../src/ExpoLocalLlm.types.ts"],"names":[],"mappings":"","sourcesContent":["export type ModelAvailability =\n  | \"available\"\n  | \"notEnabled\"\n  | \"notReady\"\n  | \"notEligible\"\n  | \"downloadRequired\"\n  | \"downloading\"\n  | \"unknown\";\n\nexport type GenerationOptions = {\n  temperature?: number;\n  maxTokens?: number;\n  topK?: number;\n};\n\n// Tool calling types\n\nexport type ToolParameterType = \"string\" | \"number\" | \"boolean\";\n\nexport type ToolParameter = {\n  type: ToolParameterType;\n  description: string;\n  enum?: string[];\n};\n\nexport type ToolDefinition = {\n  name: string;\n  description: string;\n  parameters: Record<string, ToolParameter>;\n  handler: (args: Record<string, any>) => Promise<string>;\n};\n\nexport type ToolConfig = {\n  name: string;\n  description: string;\n  parameters: Record<string, ToolParameter>;\n};\n\nexport type ToolCallEvent = {\n  callId: string;\n  toolName: string;\n  arguments: Record<string, any>;\n};\n\nexport type ActiveToolCall = {\n  callId: string;\n  toolName: string;\n};\n\n// Structured output types\n\nexport type ResponseFormat = \"text\" | \"json\";\n\nexport type SessionConfig = {\n  instructions?: string;\n  options?: GenerationOptions;\n  tools?: ToolDefinition[];\n  toolTimeout?: number;\n  responseFormat?: ResponseFormat;\n  schema?: Record<string, any>;\n};\n\nexport type TokenEvent = {\n  token: string;\n  accumulated: string;\n};\n\nexport type StreamCompleteEvent = {\n  text: string;\n};\n\nexport type StreamErrorEvent = {\n  error: string;\n};\n\nexport type DownloadProgress = {\n  progress: number;\n};\n\nexport type LLMSessionEvents = {\n  token: (event: TokenEvent) => void;\n  streamComplete: (event: StreamCompleteEvent) => void;\n  streamError: (event: StreamErrorEvent) => void;\n  toolCall: (event: ToolCallEvent) => void;\n};\n\nexport type ExpoLocalLlmModuleEvents = {\n  downloadProgress: (event: DownloadProgress) => void;\n  availabilityChange: (event: { availability: ModelAvailability }) => void;\n};\n"]}

package/build/LLMSession.d.ts

@@ -1,9 +1,13 @@
 import { SharedObject } from "expo-modules-core";
-import type { SessionConfig, LLMSessionEvents } from "./ExpoLocalLlm.types";
+import type { SessionConfig, LLMSessionEvents, ToolConfig } from "./ExpoLocalLlm.types";
 export declare class LLMSession extends SharedObject<LLMSessionEvents> {
     respond: (prompt: string) => Promise<string>;
     streamResponse: (prompt: string) => Promise<void>;
     cancelStream: () => Promise<void>;
+    registerTool: (config: ToolConfig) => void;
+    unregisterTool: (name: string) => void;
+    resolveToolCall: (callId: string, result: string) => void;
+    rejectToolCall: (callId: string, error: string) => void;
 }
 export declare function createLLMSession(config?: SessionConfig): LLMSession;
 //# sourceMappingURL=LLMSession.d.ts.map

package/build/LLMSession.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"LLMSession.d.ts","sourceRoot":"","sources":["../src/LLMSession.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAuB,MAAM,mBAAmB,CAAC;AAEtE,OAAO,KAAK,EAAE,aAAa,EAAE,gBAAgB,EAAE,MAAM,sBAAsB,CAAC;AAG5E,qBAAa,UAAW,SAAQ,YAAY,CAAC,gBAAgB,CAAC;IAG5D,OAAO,EAAG,CAAC,MAAM,EAAE,MAAM,KAAK,OAAO,CAAC,MAAM,CAAC,CAAC;IAC9C,cAAc,EAAG,CAAC,MAAM,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;IACnD,YAAY,EAAG,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC;CACpC;AAED,wBAAgB,gBAAgB,CAAC,MAAM,GAAE,aAAkB,GAAG,UAAU,CAKvE"}
+{"version":3,"file":"LLMSession.d.ts","sourceRoot":"","sources":["../src/LLMSession.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAuB,MAAM,mBAAmB,CAAC;AAEtE,OAAO,KAAK,EACV,aAAa,EACb,gBAAgB,EAChB,UAAU,EACX,MAAM,sBAAsB,CAAC;AAG9B,qBAAa,UAAW,SAAQ,YAAY,CAAC,gBAAgB,CAAC;IAG5D,OAAO,EAAG,CAAC,MAAM,EAAE,MAAM,KAAK,OAAO,CAAC,MAAM,CAAC,CAAC;IAC9C,cAAc,EAAG,CAAC,MAAM,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;IACnD,YAAY,EAAG,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC;IACnC,YAAY,EAAG,CAAC,MAAM,EAAE,UAAU,KAAK,IAAI,CAAC;IAC5C,cAAc,EAAG,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC;IACxC,eAAe,EAAG,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,KAAK,IAAI,CAAC;IAC3D,cAAc,EAAG,CAAC,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,KAAK,IAAI,CAAC;CAC1D;AAED,wBAAgB,gBAAgB,CAAC,MAAM,GAAE,aAAkB,GAAG,UAAU,CAWvE"}

package/build/LLMSession.js

@@ -6,11 +6,20 @@ export class LLMSession extends SharedObject {
     respond;
     streamResponse;
     cancelStream;
+    registerTool;
+    unregisterTool;
+    resolveToolCall;
+    rejectToolCall;
 }
 export function createLLMSession(config = {}) {
     if (!ExpoLocalLlmModule) {
         throw new UnavailabilityError("ExpoLocalLlm", "createLLMSession");
     }
-    return new ExpoLocalLlmModule.LLMSession(config);
+    // Strip handler functions before passing to native — native doesn't need them
+    const nativeConfig = {
+        ...config,
+        tools: config.tools?.map(({ handler, ...rest }) => rest),
+    };
+    return new ExpoLocalLlmModule.LLMSession(nativeConfig);
 }
 //# sourceMappingURL=LLMSession.js.map

package/build/LLMSession.js.map

@@ -1 +1 @@
-{"version":3,"file":"LLMSession.js","sourceRoot":"","sources":["../src/LLMSession.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,mBAAmB,EAAE,MAAM,mBAAmB,CAAC;AAGtE,OAAO,kBAAkB,MAAM,sBAAsB,CAAC;AAEtD,MAAM,OAAO,UAAW,SAAQ,YAA8B;IAC5D,wDAAwD;IACxD,oDAAoD;IACpD,OAAO,CAAuC;IAC9C,cAAc,CAAqC;IACnD,YAAY,CAAuB;CACpC;AAED,MAAM,UAAU,gBAAgB,CAAC,SAAwB,EAAE;IACzD,IAAI,CAAC,kBAAkB,EAAE,CAAC;QACxB,MAAM,IAAI,mBAAmB,CAAC,cAAc,EAAE,kBAAkB,CAAC,CAAC;IACpE,CAAC;IACD,OAAO,IAAI,kBAAkB,CAAC,UAAU,CAAC,MAAM,CAAe,CAAC;AACjE,CAAC","sourcesContent":["import { SharedObject, UnavailabilityError } from \"expo-modules-core\";\n\nimport type { SessionConfig, LLMSessionEvents } from \"./ExpoLocalLlm.types\";\nimport ExpoLocalLlmModule from \"./ExpoLocalLlmModule\";\n\nexport class LLMSession extends SharedObject<LLMSessionEvents> {\n  // Methods are implemented natively via the Class() DSL.\n  // TypeScript declarations provide type safety only.\n  respond!: (prompt: string) => Promise<string>;\n  streamResponse!: (prompt: string) => Promise<void>;\n  cancelStream!: () => Promise<void>;\n}\n\nexport function createLLMSession(config: SessionConfig = {}): LLMSession {\n  if (!ExpoLocalLlmModule) {\n    throw new UnavailabilityError(\"ExpoLocalLlm\", \"createLLMSession\");\n  }\n  return new ExpoLocalLlmModule.LLMSession(config) as LLMSession;\n}\n"]}
+{"version":3,"file":"LLMSession.js","sourceRoot":"","sources":["../src/LLMSession.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,mBAAmB,EAAE,MAAM,mBAAmB,CAAC;AAOtE,OAAO,kBAAkB,MAAM,sBAAsB,CAAC;AAEtD,MAAM,OAAO,UAAW,SAAQ,YAA8B;IAC5D,wDAAwD;IACxD,oDAAoD;IACpD,OAAO,CAAuC;IAC9C,cAAc,CAAqC;IACnD,YAAY,CAAuB;IACnC,YAAY,CAAgC;IAC5C,cAAc,CAA0B;IACxC,eAAe,CAA4C;IAC3D,cAAc,CAA2C;CAC1D;AAED,MAAM,UAAU,gBAAgB,CAAC,SAAwB,EAAE;IACzD,IAAI,CAAC,kBAAkB,EAAE,CAAC;QACxB,MAAM,IAAI,mBAAmB,CAAC,cAAc,EAAE,kBAAkB,CAAC,CAAC;IACpE,CAAC;IAED,8EAA8E;IAC9E,MAAM,YAAY,GAAG;QACnB,GAAG,MAAM;QACT,KAAK,EAAE,MAAM,CAAC,KAAK,EAAE,GAAG,CAAC,CAAC,EAAE,OAAO,EAAE,GAAG,IAAI,EAAE,EAAE,EAAE,CAAC,IAAI,CAAC;KACzD,CAAC;IACF,OAAO,IAAI,kBAAkB,CAAC,UAAU,CAAC,YAAY,CAAe,CAAC;AACvE,CAAC","sourcesContent":["import { SharedObject, UnavailabilityError } from \"expo-modules-core\";\n\nimport type {\n  SessionConfig,\n  LLMSessionEvents,\n  ToolConfig,\n} from \"./ExpoLocalLlm.types\";\nimport ExpoLocalLlmModule from \"./ExpoLocalLlmModule\";\n\nexport class LLMSession extends SharedObject<LLMSessionEvents> {\n  // Methods are implemented natively via the Class() DSL.\n  // TypeScript declarations provide type safety only.\n  respond!: (prompt: string) => Promise<string>;\n  streamResponse!: (prompt: string) => Promise<void>;\n  cancelStream!: () => Promise<void>;\n  registerTool!: (config: ToolConfig) => void;\n  unregisterTool!: (name: string) => void;\n  resolveToolCall!: (callId: string, result: string) => void;\n  rejectToolCall!: (callId: string, error: string) => void;\n}\n\nexport function createLLMSession(config: SessionConfig = {}): LLMSession {\n  if (!ExpoLocalLlmModule) {\n    throw new UnavailabilityError(\"ExpoLocalLlm\", \"createLLMSession\");\n  }\n\n  // Strip handler functions before passing to native — native doesn't need them\n  const nativeConfig = {\n    ...config,\n    tools: config.tools?.map(({ handler, ...rest }) => rest),\n  };\n  return new ExpoLocalLlmModule.LLMSession(nativeConfig) as LLMSession;\n}\n"]}

package/build/useLocalLLM.d.ts

@@ -1,4 +1,4 @@
-import type { ModelAvailability, SessionConfig } from "./ExpoLocalLlm.types";
+import type { ModelAvailability, SessionConfig, ActiveToolCall } from "./ExpoLocalLlm.types";
 import { LLMSession } from "./LLMSession";
 type UseLocalLLMOptions = SessionConfig;
 type UseLocalLLMResult = {
@@ -8,6 +8,7 @@ type UseLocalLLMResult = {
     streamedText: string;
     downloadProgress: number | null;
     error: string | null;
+    activeToolCalls: ActiveToolCall[];
     respond?: (prompt: string) => Promise<string>;
     streamResponse?: (prompt: string) => Promise<void>;
     cancelStream?: () => Promise<void>;

package/build/useLocalLLM.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"useLocalLLM.d.ts","sourceRoot":"","sources":["../src/useLocalLLM.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EACV,iBAAiB,EACjB,aAAa,EAKd,MAAM,sBAAsB,CAAC;AAE9B,OAAO,EAAoB,UAAU,EAAE,MAAM,cAAc,CAAC;AAE5D,KAAK,kBAAkB,GAAG,aAAa,CAAC;AAExC,KAAK,iBAAiB,GAAG;IACvB,YAAY,EAAE,iBAAiB,CAAC;IAChC,OAAO,EAAE,UAAU,GAAG,IAAI,CAAC;IAC3B,YAAY,EAAE,OAAO,CAAC;IACtB,YAAY,EAAE,MAAM,CAAC;IACrB,gBAAgB,EAAE,MAAM,GAAG,IAAI,CAAC;IAChC,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;IACrB,OAAO,CAAC,EAAE,CAAC,MAAM,EAAE,MAAM,KAAK,OAAO,CAAC,MAAM,CAAC,CAAC;IAC9C,cAAc,CAAC,EAAE,CAAC,MAAM,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;IACnD,YAAY,CAAC,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC;IACnC,aAAa,CAAC,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC;CACrC,CAAC;AAEF,wBAAgB,WAAW,CACzB,OAAO,GAAE,kBAAuB,GAC/B,iBAAiB,CAkJnB"}
+{"version":3,"file":"useLocalLLM.d.ts","sourceRoot":"","sources":["../src/useLocalLLM.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EACV,iBAAiB,EACjB,aAAa,EAOb,cAAc,EACf,MAAM,sBAAsB,CAAC;AAE9B,OAAO,EAAoB,UAAU,EAAE,MAAM,cAAc,CAAC;AAE5D,KAAK,kBAAkB,GAAG,aAAa,CAAC;AAExC,KAAK,iBAAiB,GAAG;IACvB,YAAY,EAAE,iBAAiB,CAAC;IAChC,OAAO,EAAE,UAAU,GAAG,IAAI,CAAC;IAC3B,YAAY,EAAE,OAAO,CAAC;IACtB,YAAY,EAAE,MAAM,CAAC;IACrB,gBAAgB,EAAE,MAAM,GAAG,IAAI,CAAC;IAChC,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;IACrB,eAAe,EAAE,cAAc,EAAE,CAAC;IAClC,OAAO,CAAC,EAAE,CAAC,MAAM,EAAE,MAAM,KAAK,OAAO,CAAC,MAAM,CAAC,CAAC;IAC9C,cAAc,CAAC,EAAE,CAAC,MAAM,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;IACnD,YAAY,CAAC,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC;IACnC,aAAa,CAAC,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC;CACrC,CAAC;AAEF,wBAAgB,WAAW,CACzB,OAAO,GAAE,kBAAuB,GAC/B,iBAAiB,CA0PnB"}

package/build/useLocalLLM.js

@@ -1,4 +1,4 @@
-import { useEffect, useState, useCallback, useMemo } from "react";
+import { useEffect, useState, useCallback, useMemo, useRef } from "react";
 import ExpoLocalLlmModule from "./ExpoLocalLlmModule";
 import { createLLMSession } from "./LLMSession";
 export function useLocalLLM(options = {}) {
@@ -7,20 +7,47 @@ export function useLocalLLM(options = {}) {
     const [streamedText, setStreamedText] = useState("");
     const [downloadProgress, setDownloadProgress] = useState(null);
     const [error, setError] = useState(null);
+    const [activeToolCalls, setActiveToolCalls] = useState([]);
+    // Keep a ref to the current tool handlers so the event listener
+    // always sees the latest handlers without needing to recreate the session.
+    const toolHandlersRef = useRef(new Map());
+    // Update handler ref whenever tools change
+    useEffect(() => {
+        const handlers = new Map();
+        if (options.tools) {
+            for (const tool of options.tools) {
+                handlers.set(tool.name, tool.handler);
+            }
+        }
+        toolHandlersRef.current = handlers;
+    }, [options.tools]);
     // Stabilize options to avoid unnecessary session recreation
+    // Include tool names/descriptions so session recreates when tools change structurally
+    const toolsFingerprint = useMemo(() => options.tools
+        ?.map((t) => `${t.name}:${t.description}:${JSON.stringify(t.parameters)}`)
+        .join("|") ?? "", [options.tools]);
+    // Fingerprint the schema so session recreates when it changes
+    const schemaFingerprint = useMemo(() => (options.schema ? JSON.stringify(options.schema) : ""), [options.schema]);
     const stableConfig = useMemo(() => options, [
         options.instructions,
         options.options?.temperature,
         options.options?.maxTokens,
         options.options?.topK,
+        options.toolTimeout,
+        options.responseFormat,
+        schemaFingerprint,
+        toolsFingerprint,
     ]);
     const session = useMemo(() => {
         if (!ExpoLocalLlmModule)
             return null;
         try {
-            return createLLMSession(stableConfig);
+            const s = createLLMSession(stableConfig);
+            setError(null);
+            return s;
         }
         catch (e) {
+            setError(e.message ?? "Failed to create LLM session");
             return null;
         }
     }, [stableConfig]);
@@ -47,6 +74,54 @@ export function useLocalLLM(options = {}) {
                 setError(event.error);
                 setIsGenerating(false);
             }));
+            // Tool call event listener
+            subs.push(session.addListener("toolCall", (event) => {
+                const activeCall = { callId: event.callId, toolName: event.toolName };
+                setActiveToolCalls((prev) => [...prev, activeCall]);
+                const removeActiveCall = () => {
+                    setActiveToolCalls((prev) => prev.filter((c) => c.callId !== event.callId));
+                };
+                const handler = toolHandlersRef.current.get(event.toolName);
+                if (!handler) {
+                    removeActiveCall();
+                    try {
+                        session.rejectToolCall(event.callId, `No handler registered for tool: ${event.toolName}`);
+                    }
+                    catch {
+                        // Ignore if session is already torn down
+                    }
+                    return;
+                }
+                let result;
+                try {
+                    result = handler(event.arguments);
+                }
+                catch (e) {
+                    // Handler threw synchronously before returning a promise
+                    removeActiveCall();
+                    try {
+                        session.rejectToolCall(event.callId, e.message || "Tool handler failed");
+                    }
+                    catch {
+                        // Ignore if session is already torn down
+                    }
+                    return;
+                }
+                result
+                    .then((value) => {
+                    removeActiveCall();
+                    session.resolveToolCall(event.callId, value);
+                })
+                    .catch((e) => {
+                    removeActiveCall();
+                    try {
+                        session.rejectToolCall(event.callId, e.message || "Tool handler failed");
+                    }
+                    catch {
+                        // Ignore if session is already torn down
+                    }
+                });
+            }));
         }
         return () => {
             subs.forEach((s) => s.remove());
@@ -104,6 +179,7 @@ export function useLocalLLM(options = {}) {
             streamedText: "",
             downloadProgress: null,
             error: null,
+            activeToolCalls: [],
         };
     }
     return {
@@ -113,6 +189,7 @@ export function useLocalLLM(options = {}) {
         streamedText,
         downloadProgress,
         error,
+        activeToolCalls,
         respond: session && availability === "available" ? respond : undefined,
         streamResponse: session && availability === "available" ? streamResponse : undefined,
         cancelStream: session && availability === "available" ? cancelStream : undefined,

package/build/useLocalLLM.js.map

@@ -1 +1 @@
-{"version":3,"file":"useLocalLLM.js","sourceRoot":"","sources":["../src/useLocalLLM.ts"],"names":[],"mappings":"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","sourcesContent":["import { useEffect, useState, useCallback, useMemo } from \"react\";\n\nimport type {\n  ModelAvailability,\n  SessionConfig,\n  TokenEvent,\n  StreamCompleteEvent,\n  StreamErrorEvent,\n  DownloadProgress,\n} from \"./ExpoLocalLlm.types\";\nimport ExpoLocalLlmModule from \"./ExpoLocalLlmModule\";\nimport { createLLMSession, LLMSession } from \"./LLMSession\";\n\ntype UseLocalLLMOptions = SessionConfig;\n\ntype UseLocalLLMResult = {\n  availability: ModelAvailability;\n  session: LLMSession | null;\n  isGenerating: boolean;\n  streamedText: string;\n  downloadProgress: number | null;\n  error: string | null;\n  respond?: (prompt: string) => Promise<string>;\n  streamResponse?: (prompt: string) => Promise<void>;\n  cancelStream?: () => Promise<void>;\n  downloadModel?: () => Promise<void>;\n};\n\nexport function useLocalLLM(\n  options: UseLocalLLMOptions = {}\n): UseLocalLLMResult {\n  const [availability, setAvailability] =\n    useState<ModelAvailability>(\"unknown\");\n  const [isGenerating, setIsGenerating] = useState(false);\n  const [streamedText, setStreamedText] = useState(\"\");\n  const [downloadProgress, setDownloadProgress] = useState<number | null>(null);\n  const [error, setError] = useState<string | null>(null);\n\n  // Stabilize options to avoid unnecessary session recreation\n  const stableConfig = useMemo(\n    () => options,\n    [\n      options.instructions,\n      options.options?.temperature,\n      options.options?.maxTokens,\n      options.options?.topK,\n    ]\n  );\n\n  const session = useMemo(() => {\n    if (!ExpoLocalLlmModule) return null;\n    try {\n      return createLLMSession(stableConfig);\n    } catch (e: any) {\n      return null;\n    }\n  }, [stableConfig]);\n\n  useEffect(() => {\n    if (!ExpoLocalLlmModule) return;\n\n    setAvailability(ExpoLocalLlmModule.getAvailability() as ModelAvailability);\n\n    const subs: { remove(): void }[] = [];\n\n    subs.push(\n      ExpoLocalLlmModule.addListener(\n        \"downloadProgress\",\n        (event: DownloadProgress) => {\n          setDownloadProgress(event.progress);\n        }\n      )\n    );\n    subs.push(\n      ExpoLocalLlmModule.addListener(\"availabilityChange\", (event) => {\n        setAvailability(event.availability);\n      })\n    );\n\n    if (session) {\n      subs.push(\n        session.addListener(\"token\", (event: TokenEvent) => {\n          setStreamedText(event.accumulated);\n        })\n      );\n      subs.push(\n        session.addListener(\"streamComplete\", (event: StreamCompleteEvent) => {\n          setStreamedText(event.text);\n          setIsGenerating(false);\n        })\n      );\n      subs.push(\n        session.addListener(\"streamError\", (event: StreamErrorEvent) => {\n          setError(event.error);\n          setIsGenerating(false);\n        })\n      );\n    }\n\n    return () => {\n      subs.forEach((s) => s.remove());\n      session?.release();\n    };\n  }, [session]);\n\n  const respond = useCallback(\n    async (prompt: string): Promise<string> => {\n      if (!session) throw new Error(\"Session not available\");\n      setError(null);\n      setIsGenerating(true);\n      try {\n        const result = await session.respond(prompt);\n        return result;\n      } catch (e: any) {\n        setError(e.message);\n        throw e;\n      } finally {\n        setIsGenerating(false);\n      }\n    },\n    [session]\n  );\n\n  const streamResponse = useCallback(\n    async (prompt: string): Promise<void> => {\n      if (!session) throw new Error(\"Session not available\");\n      setError(null);\n      setStreamedText(\"\");\n      setIsGenerating(true);\n      try {\n        await session.streamResponse(prompt);\n      } catch (e: any) {\n        setError(e.message);\n        setIsGenerating(false);\n        throw e;\n      }\n    },\n    [session]\n  );\n\n  const cancelStream = useCallback(async (): Promise<void> => {\n    if (!session) return;\n    await session.cancelStream();\n    setIsGenerating(false);\n  }, [session]);\n\n  const downloadModel = useCallback(async (): Promise<void> => {\n    if (!ExpoLocalLlmModule) return;\n    await ExpoLocalLlmModule.downloadModel();\n  }, []);\n\n  if (!ExpoLocalLlmModule) {\n    return {\n      availability: \"notEligible\",\n      session: null,\n      isGenerating: false,\n      streamedText: \"\",\n      downloadProgress: null,\n      error: null,\n    };\n  }\n\n  return {\n    availability,\n    session,\n    isGenerating,\n    streamedText,\n    downloadProgress,\n    error,\n    respond: session && availability === \"available\" ? respond : undefined,\n    streamResponse:\n      session && availability === \"available\" ? streamResponse : undefined,\n    cancelStream:\n      session && availability === \"available\" ? cancelStream : undefined,\n    downloadModel,\n  };\n}\n"]}
+{"version":3,"file":"useLocalLLM.js","sourceRoot":"","sources":["../src/useLocalLLM.ts"],"names":[],"mappings":"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","sourcesContent":["import { useEffect, useState, useCallback, useMemo, useRef } from \"react\";\n\nimport type {\n  ModelAvailability,\n  SessionConfig,\n  TokenEvent,\n  StreamCompleteEvent,\n  StreamErrorEvent,\n  DownloadProgress,\n  ToolDefinition,\n  ToolCallEvent,\n  ActiveToolCall,\n} from \"./ExpoLocalLlm.types\";\nimport ExpoLocalLlmModule from \"./ExpoLocalLlmModule\";\nimport { createLLMSession, LLMSession } from \"./LLMSession\";\n\ntype UseLocalLLMOptions = SessionConfig;\n\ntype UseLocalLLMResult = {\n  availability: ModelAvailability;\n  session: LLMSession | null;\n  isGenerating: boolean;\n  streamedText: string;\n  downloadProgress: number | null;\n  error: string | null;\n  activeToolCalls: ActiveToolCall[];\n  respond?: (prompt: string) => Promise<string>;\n  streamResponse?: (prompt: string) => Promise<void>;\n  cancelStream?: () => Promise<void>;\n  downloadModel?: () => Promise<void>;\n};\n\nexport function useLocalLLM(\n  options: UseLocalLLMOptions = {}\n): UseLocalLLMResult {\n  const [availability, setAvailability] =\n    useState<ModelAvailability>(\"unknown\");\n  const [isGenerating, setIsGenerating] = useState(false);\n  const [streamedText, setStreamedText] = useState(\"\");\n  const [downloadProgress, setDownloadProgress] = useState<number | null>(null);\n  const [error, setError] = useState<string | null>(null);\n  const [activeToolCalls, setActiveToolCalls] = useState<ActiveToolCall[]>([]);\n\n  // Keep a ref to the current tool handlers so the event listener\n  // always sees the latest handlers without needing to recreate the session.\n  const toolHandlersRef = useRef<Map<string, ToolDefinition[\"handler\"]>>(\n    new Map()\n  );\n\n  // Update handler ref whenever tools change\n  useEffect(() => {\n    const handlers = new Map<string, ToolDefinition[\"handler\"]>();\n    if (options.tools) {\n      for (const tool of options.tools) {\n        handlers.set(tool.name, tool.handler);\n      }\n    }\n    toolHandlersRef.current = handlers;\n  }, [options.tools]);\n\n  // Stabilize options to avoid unnecessary session recreation\n  // Include tool names/descriptions so session recreates when tools change structurally\n  const toolsFingerprint = useMemo(\n    () =>\n      options.tools\n        ?.map((t) => `${t.name}:${t.description}:${JSON.stringify(t.parameters)}`)\n        .join(\"|\") ?? \"\",\n    [options.tools]\n  );\n\n  // Fingerprint the schema so session recreates when it changes\n  const schemaFingerprint = useMemo(\n    () => (options.schema ? JSON.stringify(options.schema) : \"\"),\n    [options.schema]\n  );\n\n  const stableConfig = useMemo(\n    () => options,\n    [\n      options.instructions,\n      options.options?.temperature,\n      options.options?.maxTokens,\n      options.options?.topK,\n      options.toolTimeout,\n      options.responseFormat,\n      schemaFingerprint,\n      toolsFingerprint,\n    ]\n  );\n\n  const session = useMemo(() => {\n    if (!ExpoLocalLlmModule) return null;\n    try {\n      const s = createLLMSession(stableConfig);\n      setError(null);\n      return s;\n    } catch (e: any) {\n      setError(e.message ?? \"Failed to create LLM session\");\n      return null;\n    }\n  }, [stableConfig]);\n\n  useEffect(() => {\n    if (!ExpoLocalLlmModule) return;\n\n    setAvailability(ExpoLocalLlmModule.getAvailability() as ModelAvailability);\n\n    const subs: { remove(): void }[] = [];\n\n    subs.push(\n      ExpoLocalLlmModule.addListener(\n        \"downloadProgress\",\n        (event: DownloadProgress) => {\n          setDownloadProgress(event.progress);\n        }\n      )\n    );\n    subs.push(\n      ExpoLocalLlmModule.addListener(\"availabilityChange\", (event) => {\n        setAvailability(event.availability);\n      })\n    );\n\n    if (session) {\n      subs.push(\n        session.addListener(\"token\", (event: TokenEvent) => {\n          setStreamedText(event.accumulated);\n        })\n      );\n      subs.push(\n        session.addListener(\"streamComplete\", (event: StreamCompleteEvent) => {\n          setStreamedText(event.text);\n          setIsGenerating(false);\n        })\n      );\n      subs.push(\n        session.addListener(\"streamError\", (event: StreamErrorEvent) => {\n          setError(event.error);\n          setIsGenerating(false);\n        })\n      );\n\n      // Tool call event listener\n      subs.push(\n        session.addListener(\"toolCall\", (event: ToolCallEvent) => {\n          const activeCall = { callId: event.callId, toolName: event.toolName };\n          setActiveToolCalls((prev) => [...prev, activeCall]);\n\n          const removeActiveCall = () => {\n            setActiveToolCalls((prev) =>\n              prev.filter((c) => c.callId !== event.callId)\n            );\n          };\n\n          const handler = toolHandlersRef.current.get(event.toolName);\n          if (!handler) {\n            removeActiveCall();\n            try {\n              session.rejectToolCall(\n                event.callId,\n                `No handler registered for tool: ${event.toolName}`\n              );\n            } catch {\n              // Ignore if session is already torn down\n            }\n            return;\n          }\n\n          let result: Promise<string>;\n          try {\n            result = handler(event.arguments);\n          } catch (e: any) {\n            // Handler threw synchronously before returning a promise\n            removeActiveCall();\n            try {\n              session.rejectToolCall(\n                event.callId,\n                e.message || \"Tool handler failed\"\n              );\n            } catch {\n              // Ignore if session is already torn down\n            }\n            return;\n          }\n\n          result\n            .then((value) => {\n              removeActiveCall();\n              session.resolveToolCall(event.callId, value);\n            })\n            .catch((e: any) => {\n              removeActiveCall();\n              try {\n                session.rejectToolCall(\n                  event.callId,\n                  e.message || \"Tool handler failed\"\n                );\n              } catch {\n                // Ignore if session is already torn down\n              }\n            });\n        })\n      );\n    }\n\n    return () => {\n      subs.forEach((s) => s.remove());\n      session?.release();\n    };\n  }, [session]);\n\n  const respond = useCallback(\n    async (prompt: string): Promise<string> => {\n      if (!session) throw new Error(\"Session not available\");\n      setError(null);\n      setIsGenerating(true);\n      try {\n        const result = await session.respond(prompt);\n        return result;\n      } catch (e: any) {\n        setError(e.message);\n        throw e;\n      } finally {\n        setIsGenerating(false);\n      }\n    },\n    [session]\n  );\n\n  const streamResponse = useCallback(\n    async (prompt: string): Promise<void> => {\n      if (!session) throw new Error(\"Session not available\");\n      setError(null);\n      setStreamedText(\"\");\n      setIsGenerating(true);\n      try {\n        await session.streamResponse(prompt);\n      } catch (e: any) {\n        setError(e.message);\n        setIsGenerating(false);\n        throw e;\n      }\n    },\n    [session]\n  );\n\n  const cancelStream = useCallback(async (): Promise<void> => {\n    if (!session) return;\n    await session.cancelStream();\n    setIsGenerating(false);\n  }, [session]);\n\n  const downloadModel = useCallback(async (): Promise<void> => {\n    if (!ExpoLocalLlmModule) return;\n    await ExpoLocalLlmModule.downloadModel();\n  }, []);\n\n  if (!ExpoLocalLlmModule) {\n    return {\n      availability: \"notEligible\",\n      session: null,\n      isGenerating: false,\n      streamedText: \"\",\n      downloadProgress: null,\n      error: null,\n      activeToolCalls: [],\n    };\n  }\n\n  return {\n    availability,\n    session,\n    isGenerating,\n    streamedText,\n    downloadProgress,\n    error,\n    activeToolCalls,\n    respond: session && availability === \"available\" ? respond : undefined,\n    streamResponse:\n      session && availability === \"available\" ? streamResponse : undefined,\n    cancelStream:\n      session && availability === \"available\" ? cancelStream : undefined,\n    downloadModel,\n  };\n}\n"]}

package/ios/DynamicTool.swift

@@ -0,0 +1,154 @@
+import Foundation
+import FoundationModels
+
+// MARK: - Tool errors
+
+enum DynamicToolError: LocalizedError {
+  case timeout
+  case handlerFailed(String)
+
+  var errorDescription: String? {
+    switch self {
+    case .timeout:
+      return "Tool call timed out waiting for JavaScript response"
+    case .handlerFailed(let message):
+      return "Tool handler error: \(message)"
+    }
+  }
+}
+
+// MARK: - Generable arguments wrapper
+
+/// A fixed @Generable struct that wraps tool parameters as a JSON string.
+/// The tool's description tells the model what JSON shape to produce.
+@available(iOS 26, *)
+@Generable
+struct DynamicArguments {
+  @Guide(description: "A JSON object string containing the tool's parameters")
+  var parametersJSON: String
+}
+
+// MARK: - DynamicTool
+
+/// A generic Tool conformance that delegates execution back to JavaScript.
+/// When the model invokes this tool, it serializes arguments and sends an event
+/// to JS, then awaits a result via Swift async continuations.
+@available(iOS 26, *)
+final class DynamicTool: Tool {
+  let name: String
+  let description: String
+
+  typealias Arguments = DynamicArguments
+
+  /// Callback invoked when the model calls this tool.
+  /// Parameters: (callId, toolName, argumentsJSON) -> Void
+  private let onToolCall: @Sendable (String, String, String) -> Void
+
+  /// Pending continuations keyed by callId, awaiting JS results.
+  private let continuationStore: ToolContinuationStore
+
+  /// Timeout in seconds for JS to respond.
+  private let timeoutSeconds: TimeInterval
+
+  init(
+    name: String,
+    description: String,
+    parameterSchema: [String: Any],
+    timeoutSeconds: TimeInterval = 30,
+    continuationStore: ToolContinuationStore,
+    onToolCall: @Sendable @escaping (String, String, String) -> Void
+  ) {
+    self.name = name
+    // Embed the parameter schema in the description so the model knows
+    // what JSON shape to produce for parametersJSON.
+    let schemaDesc = DynamicTool.buildSchemaDescription(from: parameterSchema)
+    self.description = "\(description)\n\nThe parametersJSON must be a JSON object with these fields:\n\(schemaDesc)"
+    self.onToolCall = onToolCall
+    self.continuationStore = continuationStore
+    self.timeoutSeconds = timeoutSeconds
+  }
+
+  func call(arguments: DynamicArguments) async throws -> String {
+    let callId = UUID().uuidString
+
+    // Send event to JS
+    onToolCall(callId, name, arguments.parametersJSON)
+
+    // Wait for JS to resolve this call
+    return try await withCheckedThrowingContinuation { continuation in
+      continuationStore.store(callId: callId, continuation: continuation)
+
+      // Schedule timeout
+      Task {
+        try? await Task.sleep(for: .seconds(timeoutSeconds))
+        if let timedOut = continuationStore.remove(callId: callId) {
+          timedOut.resume(throwing: DynamicToolError.timeout)
+        }
+      }
+    }
+  }
+
+  /// Builds a human-readable schema description from the parameter dictionary.
+  private static func buildSchemaDescription(from schema: [String: Any]) -> String {
+    var lines: [String] = []
+    for (key, value) in schema {
+      if let param = value as? [String: Any] {
+        let type = param["type"] as? String ?? "string"
+        let desc = param["description"] as? String ?? ""
+        var line = "- \(key) (\(type)): \(desc)"
+        if let enumValues = param["enum"] as? [String] {
+          line += " [possible values: \(enumValues.joined(separator: ", "))]"
+        }
+        lines.append(line)
+      }
+    }
+    return lines.joined(separator: "\n")
+  }
+}
+
+// MARK: - ToolContinuationStore
+
+/// Thread-safe store for pending tool call continuations.
+@available(iOS 26, *)
+final class ToolContinuationStore: @unchecked Sendable {
+  private var continuations: [String: CheckedContinuation<String, Error>] = [:]
+  private let lock = NSLock()
+
+  func store(callId: String, continuation: CheckedContinuation<String, Error>) {
+    lock.lock()
+    continuations[callId] = continuation
+    lock.unlock()
+  }
+
+  func remove(callId: String) -> CheckedContinuation<String, Error>? {
+    lock.lock()
+    let cont = continuations.removeValue(forKey: callId)
+    lock.unlock()
+    return cont
+  }
+
+  /// Resolve a pending continuation with a result string.
+  func resolve(callId: String, result: String) -> Bool {
+    guard let continuation = remove(callId: callId) else { return false }
+    continuation.resume(returning: result)
+    return true
+  }
+
+  /// Reject a pending continuation with an error.
+  func reject(callId: String, error: Error) -> Bool {
+    guard let continuation = remove(callId: callId) else { return false }
+    continuation.resume(throwing: error)
+    return true
+  }
+
+  /// Cancel all pending continuations (e.g., on session teardown).
+  func cancelAll() {
+    lock.lock()
+    let pending = continuations
+    continuations.removeAll()
+    lock.unlock()
+    for (_, continuation) in pending {
+      continuation.resume(throwing: CancellationError())
+    }
+  }
+}

package/ios/Exceptions.swift

@@ -17,3 +17,27 @@ class StreamException: GenericException<String> {
     "Stream error: \(param ?? "Unknown")"
   }
 }
+
+class ToolTimeoutException: Exception {
+  override var reason: String {
+    "Tool call timed out waiting for JavaScript response"
+  }
+}
+
+class ToolCallException: GenericException<String> {
+  override var reason: String {
+    "Tool call error: \(param ?? "Unknown")"
+  }
+}
+
+class ToolNotFoundException: GenericException<String> {
+  override var reason: String {
+    "No pending tool call found with ID: \(param ?? "Unknown")"
+  }
+}
+
+class ToolNotSupportedException: Exception {
+  override var reason: String {
+    "Tool calling is not supported on this platform"
+  }
+}

package/ios/ExpoLocalLlmModule.swift

@@ -36,6 +36,22 @@ public class ExpoLocalLlmModule: Module {
         session.cancelStream()
       }
 
+      // Tool calling support
+      Function("registerTool") { (session: LLMSession, config: ToolConfig) in
+        session.registerTool(config: config)
+      }
+
+      Function("unregisterTool") { (session: LLMSession, name: String) in
+        session.unregisterTool(name: name)
+      }
+
+      Function("resolveToolCall") { (session: LLMSession, callId: String, result: String) in
+        try session.resolveToolCall(callId: callId, result: result)
+      }
+
+      Function("rejectToolCall") { (session: LLMSession, callId: String, error: String) in
+        try session.rejectToolCall(callId: callId, error: error)
+      }
     }
 
     OnAppEntersForeground {

package/ios/FoundationModelBridge.swift

@@ -23,11 +23,18 @@ enum FoundationModelBridge {
     }
   }
 
-  static func createSession(instructions: String?) -> LanguageModelSession {
-    if let instructions {
-      return LanguageModelSession(instructions: instructions)
+  static func createSession(instructions: String?, tools: [any Tool] = []) -> LanguageModelSession {
+    if tools.isEmpty {
+      if let instructions {
+        return LanguageModelSession(instructions: instructions)
+      }
+      return LanguageModelSession()
+    } else {
+      if let instructions {
+        return LanguageModelSession(tools: tools, instructions: instructions)
+      }
+      return LanguageModelSession(tools: tools)
     }
-    return LanguageModelSession()
   }
 
   static func respond(session: Any, prompt: String) async throws -> String {

package/ios/LLMSession.swift

@@ -4,6 +4,11 @@ import Foundation
 class LLMSession: SharedObject {
   private var nativeSession: Any?
   private var streamTask: Task<Void, Never>?
+  private var registeredTools: [String: Any] = [:]  // name -> DynamicTool (type-erased)
+  private var continuationStore: Any?  // ToolContinuationStore (type-erased for availability)
+  private var toolConfigs: [ToolConfig] = []
+  private var sessionInstructions: String?
+  private var toolTimeout: TimeInterval = 30
 
   static func checkAvailability() -> ModelAvailability {
     guard #available(iOS 26, *) else {
@@ -16,9 +21,134 @@ class LLMSession: SharedObject {
     guard #available(iOS 26, *) else {
       throw NotSupportedException()
     }
-    nativeSession = FoundationModelBridge.createSession(instructions: config.instructions)
+
+    // Build instructions, appending JSON schema guidance if structured output requested
+    var instructions = config.instructions ?? ""
+    if config.responseFormat == "json" {
+      let schemaClause: String
+      if let schema = config.schema,
+         let data = try? JSONSerialization.data(withJSONObject: schema, options: .prettyPrinted),
+         let schemaStr = String(data: data, encoding: .utf8) {
+        schemaClause = "Respond ONLY with a valid JSON object matching this schema:\n\(schemaStr)"
+      } else {
+        schemaClause = "Respond ONLY with a valid JSON object."
+      }
+      if instructions.isEmpty {
+        instructions = schemaClause
+      } else {
+        instructions += "\n\n\(schemaClause)"
+      }
+    }
+    sessionInstructions = instructions.isEmpty ? nil : instructions
+    toolTimeout = config.toolTimeout ?? 30
+
+    if let tools = config.tools, !tools.isEmpty {
+      toolConfigs = tools
+      let store = ToolContinuationStore()
+      continuationStore = store
+      rebuildTools(store: store)
+    } else {
+      nativeSession = FoundationModelBridge.createSession(instructions: sessionInstructions)
+    }
+  }
+
+  // MARK: - Tool Management
+
+  func registerTool(config: ToolConfig) {
+    guard #available(iOS 26, *) else { return }
+
+    toolConfigs.removeAll { $0.name == config.name }
+    toolConfigs.append(config)
+
+    let store: ToolContinuationStore
+    if let existing = continuationStore as? ToolContinuationStore {
+      store = existing
+    } else {
+      store = ToolContinuationStore()
+      continuationStore = store
+    }
+
+    rebuildTools(store: store)
+  }
+
+  func unregisterTool(name: String) {
+    guard #available(iOS 26, *) else { return }
+
+    toolConfigs.removeAll { $0.name == name }
+    registeredTools.removeValue(forKey: name)
+
+    if let store = continuationStore as? ToolContinuationStore {
+      rebuildTools(store: store)
+    }
+  }
+
+  func resolveToolCall(callId: String, result: String) throws {
+    guard #available(iOS 26, *) else {
+      throw NotSupportedException()
+    }
+    guard let store = continuationStore as? ToolContinuationStore else {
+      throw ToolNotFoundException(callId)
+    }
+    if !store.resolve(callId: callId, result: result) {
+      throw ToolNotFoundException(callId)
+    }
+  }
+
+  func rejectToolCall(callId: String, error: String) throws {
+    guard #available(iOS 26, *) else {
+      throw NotSupportedException()
+    }
+    guard let store = continuationStore as? ToolContinuationStore else {
+      throw ToolNotFoundException(callId)
+    }
+    if !store.reject(callId: callId, error: DynamicToolError.handlerFailed(error)) {
+      throw ToolNotFoundException(callId)
+    }
+  }
+
+  // MARK: - Session Rebuild
+
+  @available(iOS 26, *)
+  private func rebuildTools(store: ToolContinuationStore) {
+    // Cancel any pending tool calls from the old session
+    store.cancelAll()
+
+    var tools: [any Tool] = []
+    registeredTools.removeAll()
+
+    for config in toolConfigs {
+      let tool = DynamicTool(
+        name: config.name,
+        description: config.description,
+        parameterSchema: config.parameters,
+        timeoutSeconds: toolTimeout,
+        continuationStore: store
+      ) { [weak self] callId, toolName, argumentsJSON in
+        guard let self else { return }
+        // Parse the JSON string into a dictionary for the JS event
+        var args: [String: Any] = [:]
+        if let data = argumentsJSON.data(using: .utf8),
+           let parsed = try? JSONSerialization.jsonObject(with: data) as? [String: Any] {
+          args = parsed
+        }
+        self.emit(event: "toolCall", arguments: [
+          "callId": callId,
+          "toolName": toolName,
+          "arguments": args,
+        ])
+      }
+      registeredTools[config.name] = tool
+      tools.append(tool)
+    }
+
+    nativeSession = FoundationModelBridge.createSession(
+      instructions: sessionInstructions,
+      tools: tools
+    )
   }
 
+  // MARK: - Generation
+
   func respond(to prompt: String) async throws -> String {
     guard #available(iOS 26, *), let session = nativeSession else {
       throw NotSupportedException()
@@ -66,5 +196,8 @@ class LLMSession: SharedObject {
 
   deinit {
     streamTask?.cancel()
+    if #available(iOS 26, *), let store = continuationStore as? ToolContinuationStore {
+      store.cancelAll()
+    }
   }
 }

package/ios/Records.swift

@@ -3,6 +3,10 @@ import ExpoModulesCore
 struct SessionConfig: Record {
   @Field var instructions: String?
   @Field var options: GenerationOptions?
+  @Field var tools: [ToolConfig]?
+  @Field var toolTimeout: Double?
+  @Field var responseFormat: String?
+  @Field var schema: [String: Any]?
 }
 
 struct GenerationOptions: Record {
@@ -10,3 +14,15 @@ struct GenerationOptions: Record {
   @Field var maxTokens: Int?
   @Field var topK: Int?
 }
+
+struct ToolConfig: Record {
+  @Field var name: String = ""
+  @Field var description: String = ""
+  @Field var parameters: [String: Any] = [:]
+}
+
+struct ToolCallEvent: Record {
+  @Field var callId: String = ""
+  @Field var toolName: String = ""
+  @Field var arguments: [String: Any] = [:]
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "expo-local-llm",
-  "version": "0.1.3",
+  "version": "0.2.1",
   "description": "Expo module for on-device LLM inference via Apple Foundation Models (iOS) and Gemini Nano (Android)",
   "main": "build/index.js",
   "types": "build/index.d.ts",

package/src/ExpoLocalLlm.types.ts

@@ -13,9 +13,51 @@ export type GenerationOptions = {
   topK?: number;
 };
 
+// Tool calling types
+
+export type ToolParameterType = "string" | "number" | "boolean";
+
+export type ToolParameter = {
+  type: ToolParameterType;
+  description: string;
+  enum?: string[];
+};
+
+export type ToolDefinition = {
+  name: string;
+  description: string;
+  parameters: Record<string, ToolParameter>;
+  handler: (args: Record<string, any>) => Promise<string>;
+};
+
+export type ToolConfig = {
+  name: string;
+  description: string;
+  parameters: Record<string, ToolParameter>;
+};
+
+export type ToolCallEvent = {
+  callId: string;
+  toolName: string;
+  arguments: Record<string, any>;
+};
+
+export type ActiveToolCall = {
+  callId: string;
+  toolName: string;
+};
+
+// Structured output types
+
+export type ResponseFormat = "text" | "json";
+
 export type SessionConfig = {
   instructions?: string;
   options?: GenerationOptions;
+  tools?: ToolDefinition[];
+  toolTimeout?: number;
+  responseFormat?: ResponseFormat;
+  schema?: Record<string, any>;
 };
 
 export type TokenEvent = {
@@ -39,6 +81,7 @@ export type LLMSessionEvents = {
   token: (event: TokenEvent) => void;
   streamComplete: (event: StreamCompleteEvent) => void;
   streamError: (event: StreamErrorEvent) => void;
+  toolCall: (event: ToolCallEvent) => void;
 };
 
 export type ExpoLocalLlmModuleEvents = {

package/src/LLMSession.ts

@@ -1,6 +1,10 @@
 import { SharedObject, UnavailabilityError } from "expo-modules-core";
 
-import type { SessionConfig, LLMSessionEvents } from "./ExpoLocalLlm.types";
+import type {
+  SessionConfig,
+  LLMSessionEvents,
+  ToolConfig,
+} from "./ExpoLocalLlm.types";
 import ExpoLocalLlmModule from "./ExpoLocalLlmModule";
 
 export class LLMSession extends SharedObject<LLMSessionEvents> {
@@ -9,11 +13,21 @@ export class LLMSession extends SharedObject<LLMSessionEvents> {
   respond!: (prompt: string) => Promise<string>;
   streamResponse!: (prompt: string) => Promise<void>;
   cancelStream!: () => Promise<void>;
+  registerTool!: (config: ToolConfig) => void;
+  unregisterTool!: (name: string) => void;
+  resolveToolCall!: (callId: string, result: string) => void;
+  rejectToolCall!: (callId: string, error: string) => void;
 }
 
 export function createLLMSession(config: SessionConfig = {}): LLMSession {
   if (!ExpoLocalLlmModule) {
     throw new UnavailabilityError("ExpoLocalLlm", "createLLMSession");
   }
-  return new ExpoLocalLlmModule.LLMSession(config) as LLMSession;
+
+  // Strip handler functions before passing to native — native doesn't need them
+  const nativeConfig = {
+    ...config,
+    tools: config.tools?.map(({ handler, ...rest }) => rest),
+  };
+  return new ExpoLocalLlmModule.LLMSession(nativeConfig) as LLMSession;
 }

package/src/useLocalLLM.ts

@@ -1,4 +1,4 @@
-import { useEffect, useState, useCallback, useMemo } from "react";
+import { useEffect, useState, useCallback, useMemo, useRef } from "react";
 
 import type {
   ModelAvailability,
@@ -7,6 +7,9 @@ import type {
   StreamCompleteEvent,
   StreamErrorEvent,
   DownloadProgress,
+  ToolDefinition,
+  ToolCallEvent,
+  ActiveToolCall,
 } from "./ExpoLocalLlm.types";
 import ExpoLocalLlmModule from "./ExpoLocalLlmModule";
 import { createLLMSession, LLMSession } from "./LLMSession";
@@ -20,6 +23,7 @@ type UseLocalLLMResult = {
   streamedText: string;
   downloadProgress: number | null;
   error: string | null;
+  activeToolCalls: ActiveToolCall[];
   respond?: (prompt: string) => Promise<string>;
   streamResponse?: (prompt: string) => Promise<void>;
   cancelStream?: () => Promise<void>;
@@ -35,8 +39,41 @@ export function useLocalLLM(
   const [streamedText, setStreamedText] = useState("");
   const [downloadProgress, setDownloadProgress] = useState<number | null>(null);
   const [error, setError] = useState<string | null>(null);
+  const [activeToolCalls, setActiveToolCalls] = useState<ActiveToolCall[]>([]);
+
+  // Keep a ref to the current tool handlers so the event listener
+  // always sees the latest handlers without needing to recreate the session.
+  const toolHandlersRef = useRef<Map<string, ToolDefinition["handler"]>>(
+    new Map()
+  );
+
+  // Update handler ref whenever tools change
+  useEffect(() => {
+    const handlers = new Map<string, ToolDefinition["handler"]>();
+    if (options.tools) {
+      for (const tool of options.tools) {
+        handlers.set(tool.name, tool.handler);
+      }
+    }
+    toolHandlersRef.current = handlers;
+  }, [options.tools]);
 
   // Stabilize options to avoid unnecessary session recreation
+  // Include tool names/descriptions so session recreates when tools change structurally
+  const toolsFingerprint = useMemo(
+    () =>
+      options.tools
+        ?.map((t) => `${t.name}:${t.description}:${JSON.stringify(t.parameters)}`)
+        .join("|") ?? "",
+    [options.tools]
+  );
+
+  // Fingerprint the schema so session recreates when it changes
+  const schemaFingerprint = useMemo(
+    () => (options.schema ? JSON.stringify(options.schema) : ""),
+    [options.schema]
+  );
+
   const stableConfig = useMemo(
     () => options,
     [
@@ -44,14 +81,21 @@ export function useLocalLLM(
       options.options?.temperature,
       options.options?.maxTokens,
       options.options?.topK,
+      options.toolTimeout,
+      options.responseFormat,
+      schemaFingerprint,
+      toolsFingerprint,
     ]
   );
 
   const session = useMemo(() => {
     if (!ExpoLocalLlmModule) return null;
     try {
-      return createLLMSession(stableConfig);
+      const s = createLLMSession(stableConfig);
+      setError(null);
+      return s;
     } catch (e: any) {
+      setError(e.message ?? "Failed to create LLM session");
       return null;
     }
   }, [stableConfig]);
@@ -95,6 +139,68 @@ export function useLocalLLM(
           setIsGenerating(false);
         })
       );
+
+      // Tool call event listener
+      subs.push(
+        session.addListener("toolCall", (event: ToolCallEvent) => {
+          const activeCall = { callId: event.callId, toolName: event.toolName };
+          setActiveToolCalls((prev) => [...prev, activeCall]);
+
+          const removeActiveCall = () => {
+            setActiveToolCalls((prev) =>
+              prev.filter((c) => c.callId !== event.callId)
+            );
+          };
+
+          const handler = toolHandlersRef.current.get(event.toolName);
+          if (!handler) {
+            removeActiveCall();
+            try {
+              session.rejectToolCall(
+                event.callId,
+                `No handler registered for tool: ${event.toolName}`
+              );
+            } catch {
+              // Ignore if session is already torn down
+            }
+            return;
+          }
+
+          let result: Promise<string>;
+          try {
+            result = handler(event.arguments);
+          } catch (e: any) {
+            // Handler threw synchronously before returning a promise
+            removeActiveCall();
+            try {
+              session.rejectToolCall(
+                event.callId,
+                e.message || "Tool handler failed"
+              );
+            } catch {
+              // Ignore if session is already torn down
+            }
+            return;
+          }
+
+          result
+            .then((value) => {
+              removeActiveCall();
+              session.resolveToolCall(event.callId, value);
+            })
+            .catch((e: any) => {
+              removeActiveCall();
+              try {
+                session.rejectToolCall(
+                  event.callId,
+                  e.message || "Tool handler failed"
+                );
+              } catch {
+                // Ignore if session is already torn down
+              }
+            });
+        })
+      );
     }
 
     return () => {
@@ -157,6 +263,7 @@ export function useLocalLLM(
       streamedText: "",
       downloadProgress: null,
       error: null,
+      activeToolCalls: [],
     };
   }
 
@@ -167,6 +274,7 @@ export function useLocalLLM(
     streamedText,
     downloadProgress,
     error,
+    activeToolCalls,
     respond: session && availability === "available" ? respond : undefined,
     streamResponse:
       session && availability === "available" ? streamResponse : undefined,