expo-local-llm 0.1.0

package/build/useLocalLLM.js

@@ -0,0 +1,121 @@
+import { useEffect, useState, useCallback, useMemo } from "react";
+import ExpoLocalLlmModule from "./ExpoLocalLlmModule";
+import { createLLMSession } from "./LLMSession";
+export function useLocalLLM(options = {}) {
+    const [availability, setAvailability] = useState("unknown");
+    const [isGenerating, setIsGenerating] = useState(false);
+    const [streamedText, setStreamedText] = useState("");
+    const [downloadProgress, setDownloadProgress] = useState(null);
+    const [error, setError] = useState(null);
+    // Stabilize options to avoid unnecessary session recreation
+    const stableConfig = useMemo(() => options, [
+        options.instructions,
+        options.options?.temperature,
+        options.options?.maxTokens,
+        options.options?.topK,
+    ]);
+    const session = useMemo(() => {
+        if (!ExpoLocalLlmModule)
+            return null;
+        try {
+            return createLLMSession(stableConfig);
+        }
+        catch (e) {
+            return null;
+        }
+    }, [stableConfig]);
+    useEffect(() => {
+        if (!ExpoLocalLlmModule)
+            return;
+        setAvailability(ExpoLocalLlmModule.getAvailability());
+        const subs = [];
+        subs.push(ExpoLocalLlmModule.addListener("downloadProgress", (event) => {
+            setDownloadProgress(event.progress);
+        }));
+        subs.push(ExpoLocalLlmModule.addListener("availabilityChange", (event) => {
+            setAvailability(event.availability);
+        }));
+        if (session) {
+            subs.push(session.addListener("token", (event) => {
+                setStreamedText(event.accumulated);
+            }));
+            subs.push(session.addListener("streamComplete", (_event) => {
+                setIsGenerating(false);
+            }));
+            subs.push(session.addListener("streamError", (event) => {
+                setError(event.error);
+                setIsGenerating(false);
+            }));
+        }
+        return () => {
+            subs.forEach((s) => s.remove());
+            session?.release();
+        };
+    }, [session]);
+    const respond = useCallback(async (prompt) => {
+        if (!session)
+            throw new Error("Session not available");
+        setError(null);
+        setIsGenerating(true);
+        try {
+            const result = await session.respond(prompt);
+            return result;
+        }
+        catch (e) {
+            setError(e.message);
+            throw e;
+        }
+        finally {
+            setIsGenerating(false);
+        }
+    }, [session]);
+    const streamResponse = useCallback(async (prompt) => {
+        if (!session)
+            throw new Error("Session not available");
+        setError(null);
+        setStreamedText("");
+        setIsGenerating(true);
+        try {
+            await session.streamResponse(prompt);
+        }
+        catch (e) {
+            setError(e.message);
+            setIsGenerating(false);
+            throw e;
+        }
+    }, [session]);
+    const cancelStream = useCallback(async () => {
+        if (!session)
+            return;
+        await session.cancelStream();
+        setIsGenerating(false);
+    }, [session]);
+    const downloadModel = useCallback(async () => {
+        if (!ExpoLocalLlmModule)
+            return;
+        await ExpoLocalLlmModule.downloadModel();
+    }, []);
+    if (!ExpoLocalLlmModule) {
+        return {
+            availability: "notEligible",
+            session: null,
+            isGenerating: false,
+            streamedText: "",
+            downloadProgress: null,
+            error: null,
+        };
+    }
+    return {
+        availability,
+        session,
+        isGenerating,
+        streamedText,
+        downloadProgress,
+        error,
+        respond: session && availability === "available" ? respond : undefined,
+        streamResponse: session && availability === "available" ? streamResponse : undefined,
+        cancelStream: session && availability === "available" ? cancelStream : undefined,
+        downloadModel,
+    };
+}
+//# sourceMappingURL=useLocalLLM.js.map

package/build/useLocalLLM.js.map

@@ -0,0 +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          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"]}

package/expo-module.config.json

@@ -0,0 +1,9 @@
+{
+  "platforms": ["apple", "android"],
+  "apple": {
+    "modules": ["ExpoLocalLlmModule"]
+  },
+  "android": {
+    "modules": ["expo.modules.localllm.ExpoLocalLlmModule"]
+  }
+}

package/ios/Enums.swift

@@ -0,0 +1,11 @@
+import ExpoModulesCore
+
+enum ModelAvailability: String, Enumerable {
+  case available
+  case notEnabled
+  case notReady
+  case notEligible
+  case downloadRequired
+  case downloading
+  case unknown
+}

package/ios/Exceptions.swift

@@ -0,0 +1,19 @@
+import ExpoModulesCore
+
+class NotSupportedException: Exception {
+  override var reason: String {
+    "Foundation Models requires iOS 26 or later"
+  }
+}
+
+class SessionInvalidException: Exception {
+  override var reason: String {
+    "LLM session is invalid or has been destroyed"
+  }
+}
+
+class StreamException: GenericException<String> {
+  override var reason: String {
+    "Stream error: \(param ?? "Unknown")"
+  }
+}

package/ios/ExpoLocalLlm.podspec

@@ -0,0 +1,26 @@
+require 'json'
+
+package = JSON.parse(File.read(File.join(__dir__, '..', 'package.json')))
+
+Pod::Spec.new do |s|
+  s.name           = 'ExpoLocalLlm'
+  s.version        = package['version']
+  s.summary        = package['description']
+  s.description    = package['description']
+  s.license        = package['license']
+  s.author         = package['author']
+  s.homepage       = package['homepage']
+  s.platforms      = { :ios => '16.0' }
+  s.swift_version  = '5.9'
+  s.source         = { git: '' }
+  s.static_framework = true
+
+  s.dependency 'ExpoModulesCore'
+  s.weak_frameworks = 'FoundationModels'
+
+  s.pod_target_xcconfig = {
+    'DEFINES_MODULE' => 'YES',
+  }
+
+  s.source_files = "**/*.{h,m,mm,swift,hpp,cpp}"
+end

package/ios/ExpoLocalLlmModule.swift

@@ -0,0 +1,56 @@
+import ExpoModulesCore
+
+public class ExpoLocalLlmModule: Module {
+  public func definition() -> ModuleDefinition {
+    Name("ExpoLocalLlm")
+
+    Events("downloadProgress", "availabilityChange")
+
+    Function("getAvailability") { () -> String in
+      if #available(iOS 26, *) {
+        return LLMSession.checkAvailability().rawValue
+      }
+      return ModelAvailability.notEligible.rawValue
+    }
+
+    AsyncFunction("downloadModel") {
+      // No-op on iOS — model is built into the OS
+    }
+
+    Class(LLMSession.self) {
+      Constructor { (config: SessionConfig) -> LLMSession in
+        let session = LLMSession()
+        try session.setup(config: config)
+        return session
+      }
+
+      AsyncFunction("respond") { (session: LLMSession, prompt: String) -> String in
+        return try await session.respond(to: prompt)
+      }
+
+      AsyncFunction("streamResponse") { (session: LLMSession, prompt: String) in
+        try session.startStream(prompt: prompt)
+      }
+
+      AsyncFunction("cancelStream") { (session: LLMSession) in
+        session.cancelStream()
+      }
+
+      Events("token", "streamComplete", "streamError")
+    }
+
+    OnAppEntersForeground {
+      // Re-check availability when user returns (may have toggled Apple Intelligence in Settings)
+      if #available(iOS 26, *) {
+        let current = LLMSession.checkAvailability().rawValue
+        self.sendEvent("availabilityChange", [
+          "availability": current
+        ])
+      }
+    }
+
+    OnAppEntersBackground {
+      // Cancel any active streams when app backgrounds
+    }
+  }
+}

package/ios/FoundationModelBridge.swift

@@ -0,0 +1,59 @@
+import FoundationModels
+
+@available(iOS 26, *)
+enum FoundationModelBridge {
+  static func checkAvailability() -> ModelAvailability {
+    let availability = SystemLanguageModel.default.availability
+    switch availability {
+    case .available:
+      return .available
+    case .notAvailable(let reason):
+      switch reason {
+      case .deviceNotEligible:
+        return .notEligible
+      case .modelNotReady:
+        return .notReady
+      case .appleIntelligenceNotEnabled:
+        return .notEnabled
+      @unknown default:
+        return .unknown
+      }
+    @unknown default:
+      return .unknown
+    }
+  }
+
+  static func createSession(instructions: String?) -> LanguageModelSession {
+    if let instructions {
+      return LanguageModelSession(instructions: instructions)
+    }
+    return LanguageModelSession()
+  }
+
+  static func respond(session: Any, prompt: String) async throws -> String {
+    guard let session = session as? LanguageModelSession else {
+      throw SessionInvalidException()
+    }
+    let response = try await session.respond(to: prompt)
+    return response.content
+  }
+
+  static func stream(session: Any, prompt: String) -> AsyncThrowingStream<String, Error> {
+    guard let session = session as? LanguageModelSession else {
+      return AsyncThrowingStream { $0.finish(throwing: SessionInvalidException()) }
+    }
+    return AsyncThrowingStream { continuation in
+      Task {
+        do {
+          let stream = session.streamResponse(to: prompt)
+          for try await partial in stream {
+            continuation.yield(partial.content)
+          }
+          continuation.finish()
+        } catch {
+          continuation.finish(throwing: error)
+        }
+      }
+    }
+  }
+}

package/ios/LLMSession.swift

@@ -0,0 +1,68 @@
+import ExpoModulesCore
+import Foundation
+
+class LLMSession: SharedObject {
+  private var nativeSession: Any?
+  private var streamTask: Task<Void, Never>?
+
+  static func checkAvailability() -> ModelAvailability {
+    guard #available(iOS 26, *) else {
+      return .notEligible
+    }
+    return FoundationModelBridge.checkAvailability()
+  }
+
+  func setup(config: SessionConfig) throws {
+    guard #available(iOS 26, *) else {
+      throw NotSupportedException()
+    }
+    nativeSession = FoundationModelBridge.createSession(instructions: config.instructions)
+  }
+
+  func respond(to prompt: String) async throws -> String {
+    guard #available(iOS 26, *), let session = nativeSession else {
+      throw NotSupportedException()
+    }
+    return try await FoundationModelBridge.respond(session: session, prompt: prompt)
+  }
+
+  func startStream(prompt: String) throws {
+    guard #available(iOS 26, *), let session = nativeSession else {
+      throw NotSupportedException()
+    }
+
+    streamTask?.cancel()
+
+    let weakSelf = self
+    streamTask = Task {
+      var accumulated = ""
+      do {
+        let stream = FoundationModelBridge.stream(session: session, prompt: prompt)
+        for try await token in stream {
+          accumulated += token
+          weakSelf.emit(event: "token", arguments: [
+            "token": token,
+            "accumulated": accumulated
+          ])
+        }
+        weakSelf.emit(event: "streamComplete", arguments: [
+          "text": accumulated
+        ])
+      } catch {
+        if Task.isCancelled { return }
+        weakSelf.emit(event: "streamError", arguments: [
+          "error": error.localizedDescription
+        ])
+      }
+    }
+  }
+
+  func cancelStream() {
+    streamTask?.cancel()
+    streamTask = nil
+  }
+
+  deinit {
+    streamTask?.cancel()
+  }
+}

package/ios/Records.swift

@@ -0,0 +1,12 @@
+import ExpoModulesCore
+
+struct SessionConfig: Record {
+  @Field var instructions: String?
+  @Field var options: GenerationOptions?
+}
+
+struct GenerationOptions: Record {
+  @Field var temperature: Double?
+  @Field var maxTokens: Int?
+  @Field var topK: Int?
+}

package/package.json

@@ -0,0 +1,61 @@
+{
+  "name": "expo-local-llm",
+  "version": "0.1.0",
+  "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",
+  "files": [
+    "build",
+    "src",
+    "ios",
+    "android",
+    "expo-module.config.json"
+  ],
+  "scripts": {
+    "build": "expo-module build",
+    "clean": "expo-module clean",
+    "lint": "expo-module lint",
+    "test": "expo-module test",
+    "prepare": "expo-module prepare",
+    "prepublishOnly": "expo-module prepublishOnly",
+    "expo-module": "expo-module",
+    "open:ios": "xed example/ios",
+    "open:android": "open -a \"Android Studio\" example/android"
+  },
+  "keywords": [
+    "react-native",
+    "expo",
+    "expo-local-llm",
+    "llm",
+    "on-device",
+    "apple-intelligence",
+    "gemini-nano",
+    "foundation-models"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/GijungKim/expo-local-llm"
+  },
+  "bugs": {
+    "url": "https://github.com/GijungKim/expo-local-llm/issues"
+  },
+  "author": "GijungKim <tonykim970@gmail.com>",
+  "license": "MIT",
+  "homepage": "https://github.com/GijungKim/expo-local-llm#readme",
+  "dependencies": {},
+  "devDependencies": {
+    "@types/react": "~19.1.1",
+    "expo-module-scripts": "^55.0.2",
+    "expo": "^55.0.8",
+    "react-native": "0.82.1"
+  },
+  "jest": {
+    "preset": "jest-expo/node"
+  },
+  "peerDependencies": {
+    "expo": ">=52.0.0",
+    "expo-modules-core": ">=2.0.0",
+    "react": ">=18.0.0",
+    "react-native": ">=0.76.0"
+  }
+}

package/src/ExpoLocalLlm.types.ts

@@ -0,0 +1,47 @@
+export type ModelAvailability =
+  | "available"
+  | "notEnabled"
+  | "notReady"
+  | "notEligible"
+  | "downloadRequired"
+  | "downloading"
+  | "unknown";
+
+export type GenerationOptions = {
+  temperature?: number;
+  maxTokens?: number;
+  topK?: number;
+};
+
+export type SessionConfig = {
+  instructions?: string;
+  options?: GenerationOptions;
+};
+
+export type TokenEvent = {
+  token: string;
+  accumulated: string;
+};
+
+export type StreamCompleteEvent = {
+  text: string;
+};
+
+export type StreamErrorEvent = {
+  error: string;
+};
+
+export type DownloadProgress = {
+  progress: number;
+};
+
+export type LLMSessionEvents = {
+  token: (event: TokenEvent) => void;
+  streamComplete: (event: StreamCompleteEvent) => void;
+  streamError: (event: StreamErrorEvent) => void;
+};
+
+export type ExpoLocalLlmModuleEvents = {
+  downloadProgress: (event: DownloadProgress) => void;
+  availabilityChange: (event: { availability: ModelAvailability }) => void;
+};

package/src/ExpoLocalLlmModule.ts

@@ -0,0 +1,19 @@
+import { NativeModule, requireNativeModule } from "expo-modules-core";
+
+import type { ExpoLocalLlmModuleEvents } from "./ExpoLocalLlm.types";
+
+declare class ExpoLocalLlmModuleType extends NativeModule<ExpoLocalLlmModuleEvents> {
+  getAvailability(): string;
+  downloadModel(): Promise<void>;
+  LLMSession: any;
+}
+
+let nativeModule: ExpoLocalLlmModuleType | null;
+
+try {
+  nativeModule = requireNativeModule<ExpoLocalLlmModuleType>("ExpoLocalLlm");
+} catch {
+  nativeModule = null;
+}
+
+export default nativeModule;

package/src/LLMSession.ts

@@ -0,0 +1,19 @@
+import { SharedObject, UnavailabilityError } from "expo-modules-core";
+
+import type { SessionConfig, LLMSessionEvents } from "./ExpoLocalLlm.types";
+import ExpoLocalLlmModule from "./ExpoLocalLlmModule";
+
+export class LLMSession extends SharedObject<LLMSessionEvents> {
+  // Methods are implemented natively via the Class() DSL.
+  // TypeScript declarations provide type safety only.
+  respond!: (prompt: string) => Promise<string>;
+  streamResponse!: (prompt: string) => Promise<void>;
+  cancelStream!: () => Promise<void>;
+}
+
+export function createLLMSession(config: SessionConfig = {}): LLMSession {
+  if (!ExpoLocalLlmModule) {
+    throw new UnavailabilityError("ExpoLocalLlm", "createLLMSession");
+  }
+  return new ExpoLocalLlmModule.LLMSession(config) as LLMSession;
+}

package/src/__tests__/ExpoLocalLlm.test.ts

@@ -0,0 +1,82 @@
+jest.mock("expo-modules-core", () => ({
+  requireNativeModule: jest.fn(() => {
+    throw new Error("Native module not available");
+  }),
+  NativeModule: class {},
+  SharedObject: class {},
+  UnavailabilityError: class UnavailabilityError extends Error {
+    constructor(moduleName: string, functionName: string) {
+      super(`${moduleName}.${functionName} is not available`);
+    }
+  },
+}));
+
+import { LLMSession, createLLMSession, ExpoLocalLlmModule } from "../index";
+
+describe("ExpoLocalLlm", () => {
+  describe("exports", () => {
+    it("exports LLMSession class", () => {
+      expect(LLMSession).toBeDefined();
+      expect(typeof LLMSession).toBe("function");
+    });
+
+    it("exports createLLMSession function", () => {
+      expect(createLLMSession).toBeDefined();
+      expect(typeof createLLMSession).toBe("function");
+    });
+
+    it("exports ExpoLocalLlmModule as null when native module is unavailable", () => {
+      expect(ExpoLocalLlmModule).toBeNull();
+    });
+  });
+
+  describe("createLLMSession", () => {
+    it("throws when native module is not loaded", () => {
+      expect(() => createLLMSession()).toThrow();
+    });
+
+    it("throws with module name in message", () => {
+      expect(() => createLLMSession({ instructions: "test" })).toThrow(
+        /ExpoLocalLlm/
+      );
+    });
+  });
+
+  describe("ModelAvailability values", () => {
+    it("all values are valid strings", () => {
+      const values = [
+        "available",
+        "notEnabled",
+        "notReady",
+        "notEligible",
+        "downloadRequired",
+        "downloading",
+        "unknown",
+      ];
+      expect(values).toHaveLength(7);
+      values.forEach((v) => expect(typeof v).toBe("string"));
+    });
+  });
+
+  describe("SessionConfig", () => {
+    it("accepts config with all fields", () => {
+      const config = {
+        instructions: "You are a health assistant",
+        options: {
+          temperature: 0.7,
+          maxTokens: 256,
+          topK: 40,
+        },
+      };
+      expect(config.instructions).toBe("You are a health assistant");
+      expect(config.options.temperature).toBe(0.7);
+      expect(config.options.maxTokens).toBe(256);
+      expect(config.options.topK).toBe(40);
+    });
+
+    it("accepts empty config", () => {
+      const config = {};
+      expect(config).toEqual({});
+    });
+  });
+});

package/src/__tests__/useLocalLLM.test.ts

@@ -0,0 +1,30 @@
+jest.mock("expo-modules-core", () => ({
+  requireNativeModule: jest.fn(() => {
+    throw new Error("Native module not available");
+  }),
+  NativeModule: class {},
+  SharedObject: class {},
+  UnavailabilityError: class UnavailabilityError extends Error {
+    constructor(moduleName: string, functionName: string) {
+      super(`${moduleName}.${functionName} is not available`);
+    }
+  },
+}));
+
+jest.mock("react", () => ({
+  ...jest.requireActual("react"),
+}));
+
+import ExpoLocalLlmModule from "../ExpoLocalLlmModule";
+
+describe("useLocalLLM prerequisites", () => {
+  it("native module is null in test environment", () => {
+    expect(ExpoLocalLlmModule).toBeNull();
+  });
+
+  it("useLocalLLM can be imported", () => {
+    const mod = require("../useLocalLLM");
+    expect(mod.useLocalLLM).toBeDefined();
+    expect(typeof mod.useLocalLLM).toBe("function");
+  });
+});

package/src/index.ts

@@ -0,0 +1,4 @@
+export { useLocalLLM } from "./useLocalLLM";
+export { LLMSession, createLLMSession } from "./LLMSession";
+export { default as ExpoLocalLlmModule } from "./ExpoLocalLlmModule";
+export * from "./ExpoLocalLlm.types";