expo-ai-kit 0.1.21 → 0.2.0

package/build/models.js

@@ -0,0 +1,45 @@
+/**
+ * Model Registry
+ *
+ * Defines all downloadable models known to expo-ai-kit.
+ * getDownloadableModels() reads from this registry and enriches
+ * each entry with on-device status from the native layer.
+ */
+export const MODEL_REGISTRY = [
+    {
+        id: 'gemma-e2b',
+        name: 'Gemma 4 E2B',
+        parameterCount: '2.3B',
+        quantization: 'Q4_K_M',
+        downloadUrl: 'https://huggingface.co/google/gemma-4-e2b-it-GGUF/resolve/main/gemma-4-e2b-it-Q4_K_M.gguf',
+        sha256: '', // TODO: Fill with actual hash once model file is verified
+        sizeBytes: 1_400_000_000, // ~1.4GB
+        // Conservative limit for 4GB RAM devices. Base model supports 128k but
+        // KV cache won't fit. TODO: Benchmark during Phase 2 testing.
+        contextWindow: 8_000,
+        minRamBytes: 4_000_000_000, // 4GB
+        supportedPlatforms: ['ios', 'android'],
+    },
+    {
+        id: 'gemma-e4b',
+        name: 'Gemma 4 E4B',
+        parameterCount: '4.5B',
+        quantization: 'Q4_K_M',
+        downloadUrl: 'https://huggingface.co/google/gemma-4-e4b-it-GGUF/resolve/main/gemma-4-e4b-it-Q4_K_M.gguf',
+        sha256: '', // TODO: Fill with actual hash once model file is verified
+        sizeBytes: 2_800_000_000, // ~2.8GB
+        // Conservative limit for 6GB RAM devices. Base model supports 128k but
+        // KV cache won't fit. TODO: Benchmark during Phase 2 testing.
+        contextWindow: 16_000,
+        minRamBytes: 6_000_000_000, // 6GB
+        supportedPlatforms: ['ios', 'android'],
+    },
+];
+/**
+ * Look up a model registry entry by ID.
+ * Returns undefined if not found.
+ */
+export function getRegistryEntry(modelId) {
+    return MODEL_REGISTRY.find((m) => m.id === modelId);
+}
+//# sourceMappingURL=models.js.map

package/build/models.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"models.js","sourceRoot":"","sources":["../src/models.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAgCH,MAAM,CAAC,MAAM,cAAc,GAAyB;IAClD;QACE,EAAE,EAAE,WAAW;QACf,IAAI,EAAE,aAAa;QACnB,cAAc,EAAE,MAAM;QACtB,YAAY,EAAE,QAAQ;QACtB,WAAW,EACT,2FAA2F;QAC7F,MAAM,EAAE,EAAE,EAAE,0DAA0D;QACtE,SAAS,EAAE,aAAa,EAAE,SAAS;QACnC,uEAAuE;QACvE,8DAA8D;QAC9D,aAAa,EAAE,KAAK;QACpB,WAAW,EAAE,aAAa,EAAE,MAAM;QAClC,kBAAkB,EAAE,CAAC,KAAK,EAAE,SAAS,CAAC;KACvC;IACD;QACE,EAAE,EAAE,WAAW;QACf,IAAI,EAAE,aAAa;QACnB,cAAc,EAAE,MAAM;QACtB,YAAY,EAAE,QAAQ;QACtB,WAAW,EACT,2FAA2F;QAC7F,MAAM,EAAE,EAAE,EAAE,0DAA0D;QACtE,SAAS,EAAE,aAAa,EAAE,SAAS;QACnC,uEAAuE;QACvE,8DAA8D;QAC9D,aAAa,EAAE,MAAM;QACrB,WAAW,EAAE,aAAa,EAAE,MAAM;QAClC,kBAAkB,EAAE,CAAC,KAAK,EAAE,SAAS,CAAC;KACvC;CACF,CAAC;AAEF;;;GAGG;AACH,MAAM,UAAU,gBAAgB,CAAC,OAAe;IAC9C,OAAO,cAAc,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,EAAE,KAAK,OAAO,CAAC,CAAC;AACtD,CAAC","sourcesContent":["/**\n * Model Registry\n *\n * Defines all downloadable models known to expo-ai-kit.\n * getDownloadableModels() reads from this registry and enriches\n * each entry with on-device status from the native layer.\n */\n\nexport type ModelRegistryEntry = {\n  /** Unique model identifier used in setModel/downloadModel */\n  id: string;\n  /** Human-readable model name */\n  name: string;\n  /** Parameter count label */\n  parameterCount: string;\n  /** Quantization variant */\n  quantization: string;\n  /** URL to download the GGUF model file */\n  downloadUrl: string;\n  /** SHA256 hash for integrity verification after download */\n  sha256: string;\n  /** Download file size in bytes */\n  sizeBytes: number;\n  /**\n   * Practical context window (max tokens) for this model on constrained devices.\n   *\n   * These are conservative defaults, NOT the base model's theoretical max (128k).\n   * On a memory-constrained mobile device running quantized inference, KV cache\n   * cannot fit the full 128k context. These values should be benchmarked and\n   * adjusted during Phase 2 testing with real devices.\n   */\n  contextWindow: number;\n  /** Minimum device RAM in bytes required to run this model */\n  minRamBytes: number;\n  /** Platforms this model can run on */\n  supportedPlatforms: ('ios' | 'android')[];\n};\n\nexport const MODEL_REGISTRY: ModelRegistryEntry[] = [\n  {\n    id: 'gemma-e2b',\n    name: 'Gemma 4 E2B',\n    parameterCount: '2.3B',\n    quantization: 'Q4_K_M',\n    downloadUrl:\n      'https://huggingface.co/google/gemma-4-e2b-it-GGUF/resolve/main/gemma-4-e2b-it-Q4_K_M.gguf',\n    sha256: '', // TODO: Fill with actual hash once model file is verified\n    sizeBytes: 1_400_000_000, // ~1.4GB\n    // Conservative limit for 4GB RAM devices. Base model supports 128k but\n    // KV cache won't fit. TODO: Benchmark during Phase 2 testing.\n    contextWindow: 8_000,\n    minRamBytes: 4_000_000_000, // 4GB\n    supportedPlatforms: ['ios', 'android'],\n  },\n  {\n    id: 'gemma-e4b',\n    name: 'Gemma 4 E4B',\n    parameterCount: '4.5B',\n    quantization: 'Q4_K_M',\n    downloadUrl:\n      'https://huggingface.co/google/gemma-4-e4b-it-GGUF/resolve/main/gemma-4-e4b-it-Q4_K_M.gguf',\n    sha256: '', // TODO: Fill with actual hash once model file is verified\n    sizeBytes: 2_800_000_000, // ~2.8GB\n    // Conservative limit for 6GB RAM devices. Base model supports 128k but\n    // KV cache won't fit. TODO: Benchmark during Phase 2 testing.\n    contextWindow: 16_000,\n    minRamBytes: 6_000_000_000, // 6GB\n    supportedPlatforms: ['ios', 'android'],\n  },\n];\n\n/**\n * Look up a model registry entry by ID.\n * Returns undefined if not found.\n */\nexport function getRegistryEntry(modelId: string): ModelRegistryEntry | undefined {\n  return MODEL_REGISTRY.find((m) => m.id === modelId);\n}\n"]}

package/build/types.d.ts

@@ -259,6 +259,81 @@ export type UseOnDeviceAIReturn = {
     /** Whether the availability check is still in progress */
     isChecking: boolean;
 };
+/**
+ * A built-in model provided by the OS (e.g. Apple Foundation Models, ML Kit).
+ * These are always available on supported devices -- no download needed.
+ */
+export type BuiltInModel = {
+    /** Unique model identifier (e.g. 'apple-fm', 'mlkit') */
+    id: string;
+    /** Human-readable model name */
+    name: string;
+    /** Whether this model is available on the current device/OS */
+    available: boolean;
+    /** Platform this model is associated with */
+    platform: 'ios' | 'android';
+    /** Maximum context window in tokens */
+    contextWindow: number;
+};
+/**
+ * A downloadable model that the user manages (download, load, delete).
+ * These require explicit download before use.
+ */
+export type DownloadableModel = {
+    /** Unique model identifier (e.g. 'gemma-e2b', 'gemma-e4b') */
+    id: string;
+    /** Human-readable model name */
+    name: string;
+    /** Parameter count label (e.g. '2.3B') */
+    parameterCount: string;
+    /** Download file size in bytes */
+    sizeBytes: number;
+    /** Maximum context window in tokens */
+    contextWindow: number;
+    /** Minimum device RAM in bytes required to run */
+    minRamBytes: number;
+    /** Current lifecycle status */
+    status: DownloadableModelStatus;
+};
+/**
+ * Lifecycle status of a downloadable model.
+ *
+ * - 'not-downloaded': Model file is not on disk
+ * - 'downloading': Model file is being downloaded
+ * - 'loading': File is on disk, model is being loaded into memory for inference
+ * - 'ready': Model is loaded in memory and ready for inference
+ */
+export type DownloadableModelStatus = 'not-downloaded' | 'downloading' | 'loading' | 'ready';
+/**
+ * Error codes for model-related operations.
+ */
+export type ModelErrorCode = 'MODEL_NOT_FOUND' | 'MODEL_NOT_DOWNLOADED' | 'DOWNLOAD_FAILED' | 'DOWNLOAD_CORRUPT' | 'DOWNLOAD_STORAGE_FULL' | 'INFERENCE_OOM' | 'INFERENCE_FAILED' | 'MODEL_LOAD_FAILED' | 'DEVICE_NOT_SUPPORTED';
+/**
+ * Structured error for model operations.
+ */
+export declare class ModelError extends Error {
+    code: ModelErrorCode;
+    modelId: string;
+    constructor(code: ModelErrorCode, modelId: string, message?: string);
+}
+/**
+ * Event payload for model download progress.
+ */
+export type ModelDownloadProgressEvent = {
+    /** Model being downloaded */
+    modelId: string;
+    /** Download progress from 0 to 1 */
+    progress: number;
+};
+/**
+ * Event payload for model state changes.
+ */
+export type ModelStateChangeEvent = {
+    /** Model whose state changed */
+    modelId: string;
+    /** New status */
+    status: DownloadableModelStatus;
+};
 /**
  * Options for creating a ChatMemoryManager.
  */
@@ -273,6 +348,13 @@ export type ChatMemoryOptions = {
      * Optional system prompt to prepend to every generated prompt.
      */
     systemPrompt?: string;
+    /**
+     * Maximum context window in tokens. When set, trimHistory will also
+     * trim messages that exceed this token budget (in addition to maxTurns).
+     * Whichever limit is hit first triggers trimming.
+     * @default Infinity (no token-based trimming)
+     */
+    contextWindow?: number;
 };
 /**
  * A snapshot of the current chat memory state.

package/build/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH,MAAM,MAAM,OAAO,GAAG,QAAQ,GAAG,MAAM,GAAG,WAAW,CAAC;AAEtD;;GAEG;AACH,MAAM,MAAM,UAAU,GAAG;IACvB,IAAI,EAAE,OAAO,CAAC;IACd,OAAO,EAAE,MAAM,CAAC;CACjB,CAAC;AAEF;;GAEG;AACH,MAAM,MAAM,cAAc,GAAG;IAC3B;;;OAGG;IACH,YAAY,CAAC,EAAE,MAAM,CAAC;CACvB,CAAC;AAEF;;GAEG;AACH,MAAM,MAAM,WAAW,GAAG;IACxB,kCAAkC;IAClC,IAAI,EAAE,MAAM,CAAC;CACd,CAAC;AAEF;;GAEG;AACH,MAAM,MAAM,gBAAgB,GAAG;IAC7B;;;OAGG;IACH,YAAY,CAAC,EAAE,MAAM,CAAC;CACvB,CAAC;AAEF;;GAEG;AACH,MAAM,MAAM,cAAc,GAAG;IAC3B,mDAAmD;IACnD,SAAS,EAAE,MAAM,CAAC;IAClB,uCAAuC;IACvC,KAAK,EAAE,MAAM,CAAC;IACd,8BAA8B;IAC9B,eAAe,EAAE,MAAM,CAAC;IACxB,sCAAsC;IACtC,MAAM,EAAE,OAAO,CAAC;CACjB,CAAC;AAEF;;GAEG;AACH,MAAM,MAAM,iBAAiB,GAAG,CAAC,KAAK,EAAE,cAAc,KAAK,IAAI,CAAC;AAMhE;;GAEG;AACH,MAAM,MAAM,mBAAmB,GAAG;IAChC;;;OAGG;IACH,MAAM,CAAC,EAAE,OAAO,GAAG,QAAQ,GAAG,MAAM,CAAC;IACrC;;;OAGG;IACH,KAAK,CAAC,EAAE,WAAW,GAAG,SAAS,GAAG,MAAM,CAAC;CAC1C,CAAC;AAEF;;GAEG;AACH,MAAM,MAAM,mBAAmB,GAAG;IAChC;;OAEG;IACH,EAAE,EAAE,MAAM,CAAC;IACX;;OAEG;IACH,IAAI,CAAC,EAAE,MAAM,CAAC;IACd;;;OAGG;IACH,IAAI,CAAC,EAAE,QAAQ,GAAG,UAAU,GAAG,SAAS,CAAC;CAC1C,CAAC;AAEF;;GAEG;AACH,MAAM,MAAM,iBAAiB,GAAG;IAC9B;;OAEG;IACH,KAAK,EACD,QAAQ,GACR,QAAQ,GACR,cAAc,GACd,UAAU,GACV,SAAS,GACT,UAAU,GACV,QAAQ,GACR,UAAU,CAAC;CAChB,CAAC;AAEF;;GAEG;AACH,MAAM,MAAM,0BAA0B,GAAG;IACvC;;;OAGG;IACH,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB,CAAC;AAEF;;GAEG;AACH,MAAM,MAAM,wBAAwB,GAAG;IACrC;;;OAGG;IACH,MAAM,CAAC,EAAE,OAAO,GAAG,QAAQ,GAAG,UAAU,CAAC;CAC1C,CAAC;AAMF;;GAEG;AACH,MAAM,MAAM,iBAAiB,GAAG;IAC9B;;;OAGG;IACH,KAAK,CAAC,EAAE,MAAM,CAAC;IACf;;OAEG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB;;;OAGG;IACH,IAAI,CAAC,EAAE,QAAQ,GAAG,QAAQ,GAAG,cAAc,GAAG,UAAU,GAAG,SAAS,CAAC;CACtE,CAAC;AAEF;;GAEG;AACH,MAAM,MAAM,aAAa,GAAG;IAC1B,yBAAyB;IACzB,IAAI,EAAE,MAAM,CAAC;CACd,CAAC;AAEF;;GAEG;AACH,MAAM,MAAM,kBAAkB,GAAG;IAC/B,qCAAqC;IACrC,WAAW,EAAE,aAAa,EAAE,CAAC;IAC7B,uCAAuC;IACvC,GAAG,EAAE,MAAM,CAAC;CACb,CAAC;AAEF;;GAEG;AACH,MAAM,MAAM,oBAAoB,GAAG;IACjC;;;OAGG;IACH,KAAK,CAAC,EAAE,MAAM,CAAC;IACf;;;OAGG;IACH,IAAI,CAAC,EAAE,QAAQ,GAAG,QAAQ,GAAG,cAAc,GAAG,UAAU,GAAG,SAAS,CAAC;IACrE;;OAEG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB,CAAC;AAEF;;GAEG;AACH,MAAM,MAAM,sBAAsB,GAAG;IACnC;;;OAGG;IACH,KAAK,CAAC,EAAE,MAAM,CAAC;IACf;;;OAGG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB;;OAEG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB,CAAC;AAMF;;GAEG;AACH,MAAM,MAAM,cAAc,GAAG;IAC3B,yCAAyC;IACzC,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,iEAAiE;IACjE,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,4CAA4C;IAC5C,eAAe,CAAC,EAAE,UAAU,EAAE,CAAC;IAC/B,2CAA2C;IAC3C,QAAQ,CAAC,EAAE,CAAC,QAAQ,EAAE,WAAW,KAAK,IAAI,CAAC;IAC3C,oCAAoC;IACpC,OAAO,CAAC,EAAE,CAAC,KAAK,EAAE,KAAK,KAAK,IAAI,CAAC;CAClC,CAAC;AAEF;;GAEG;AACH,MAAM,MAAM,aAAa,GAAG;IAC1B,uCAAuC;IACvC,QAAQ,EAAE,UAAU,EAAE,CAAC;IACvB,+BAA+B;IAC/B,KAAK,EAAE,MAAM,CAAC;IACd,+BAA+B;IAC/B,QAAQ,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,IAAI,CAAC;IAClC,6DAA6D;IAC7D,WAAW,EAAE,CAAC,IAAI,CAAC,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;IAC9C,uDAAuD;IACvD,WAAW,EAAE,OAAO,CAAC;IACrB,0CAA0C;IAC1C,IAAI,EAAE,MAAM,IAAI,CAAC;IACjB,oDAAoD;IACpD,KAAK,EAAE,MAAM,IAAI,CAAC;IAClB,oCAAoC;IACpC,KAAK,EAAE,KAAK,GAAG,IAAI,CAAC;CACrB,CAAC;AAEF;;GAEG;AACH,MAAM,MAAM,oBAAoB,GAAG;IACjC,+BAA+B;IAC/B,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,uCAAuC;IACvC,QAAQ,CAAC,EAAE,CAAC,QAAQ,EAAE,WAAW,KAAK,IAAI,CAAC;IAC3C,oCAAoC;IACpC,OAAO,CAAC,EAAE,CAAC,KAAK,EAAE,KAAK,KAAK,IAAI,CAAC;CAClC,CAAC;AAEF;;GAEG;AACH,MAAM,MAAM,mBAAmB,GAAG;IAChC,kCAAkC;IAClC,UAAU,EAAE,MAAM,CAAC;IACnB,0CAA0C;IAC1C,SAAS,EAAE,OAAO,CAAC;IACnB,gDAAgD;IAChD,QAAQ,EAAE,CAAC,MAAM,EAAE,MAAM,KAAK,OAAO,CAAC,MAAM,CAAC,CAAC;IAC9C,kCAAkC;IAClC,IAAI,EAAE,MAAM,IAAI,CAAC;IACjB,oCAAoC;IACpC,KAAK,EAAE,KAAK,GAAG,IAAI,CAAC;CACrB,CAAC;AAEF;;GAEG;AACH,MAAM,MAAM,mBAAmB,GAAG;IAChC,wCAAwC;IACxC,WAAW,EAAE,OAAO,CAAC;IACrB,0DAA0D;IAC1D,UAAU,EAAE,OAAO,CAAC;CACrB,CAAC;AAMF;;GAEG;AACH,MAAM,MAAM,iBAAiB,GAAG;IAC9B;;;;OAIG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB;;OAEG;IACH,YAAY,CAAC,EAAE,MAAM,CAAC;CACvB,CAAC;AAEF;;GAEG;AACH,MAAM,MAAM,kBAAkB,GAAG;IAC/B,uCAAuC;IACvC,QAAQ,EAAE,UAAU,EAAE,CAAC;IACvB,iCAAiC;IACjC,YAAY,EAAE,MAAM,GAAG,SAAS,CAAC;IACjC,qCAAqC;IACrC,SAAS,EAAE,MAAM,CAAC;IAClB,4BAA4B;IAC5B,QAAQ,EAAE,MAAM,CAAC;CAClB,CAAC"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"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"}

package/build/types.js

@@ -1,2 +1,14 @@
-export {};
+/**
+ * Structured error for model operations.
+ */
+export class ModelError extends Error {
+    code;
+    modelId;
+    constructor(code, modelId, message) {
+        super(message ?? `${code}: ${modelId}`);
+        this.name = 'ModelError';
+        this.code = code;
+        this.modelId = modelId;
+    }
+}
 //# sourceMappingURL=types.js.map

package/build/types.js.map

@@ -1 +1 @@
-{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"","sourcesContent":["/**\n * Role in a conversation message.\n */\nexport type LLMRole = 'system' | 'user' | 'assistant';\n\n/**\n * A single message in a conversation.\n */\nexport type LLMMessage = {\n  role: LLMRole;\n  content: string;\n};\n\n/**\n * Options for sendMessage.\n */\nexport type LLMSendOptions = {\n  /**\n   * Default system prompt to use if no system message is provided in the messages array.\n   * If a system message exists in the array, this is ignored.\n   */\n  systemPrompt?: string;\n};\n\n/**\n * Response from sendMessage.\n */\nexport type LLMResponse = {\n  /** The generated response text */\n  text: string;\n};\n\n/**\n * Options for streamMessage.\n */\nexport type LLMStreamOptions = {\n  /**\n   * Default system prompt to use if no system message is provided in the messages array.\n   * If a system message exists in the array, this is ignored.\n   */\n  systemPrompt?: string;\n};\n\n/**\n * Event payload for streaming tokens.\n */\nexport type LLMStreamEvent = {\n  /** Unique identifier for this streaming session */\n  sessionId: string;\n  /** The token/chunk of text received */\n  token: string;\n  /** Accumulated text so far */\n  accumulatedText: string;\n  /** Whether this is the final chunk */\n  isDone: boolean;\n};\n\n/**\n * Callback function for streaming events.\n */\nexport type LLMStreamCallback = (event: LLMStreamEvent) => void;\n\n// ============================================================================\n// Prompt Helper Types\n// ============================================================================\n\n/**\n * Options for the summarize helper.\n */\nexport type LLMSummarizeOptions = {\n  /**\n   * Target length for the summary.\n   * @default 'medium'\n   */\n  length?: 'short' | 'medium' | 'long';\n  /**\n   * Style of summary to generate.\n   * @default 'paragraph'\n   */\n  style?: 'paragraph' | 'bullets' | 'tldr';\n};\n\n/**\n * Options for the translate helper.\n */\nexport type LLMTranslateOptions = {\n  /**\n   * Target language to translate to.\n   */\n  to: string;\n  /**\n   * Source language (auto-detected if not provided).\n   */\n  from?: string;\n  /**\n   * Tone/formality of the translation.\n   * @default 'neutral'\n   */\n  tone?: 'formal' | 'informal' | 'neutral';\n};\n\n/**\n * Options for the rewrite helper.\n */\nexport type LLMRewriteOptions = {\n  /**\n   * Style to rewrite in.\n   */\n  style:\n    | 'formal'\n    | 'casual'\n    | 'professional'\n    | 'friendly'\n    | 'concise'\n    | 'detailed'\n    | 'simple'\n    | 'academic';\n};\n\n/**\n * Options for the extractKeyPoints helper.\n */\nexport type LLMExtractKeyPointsOptions = {\n  /**\n   * Maximum number of key points to extract.\n   * @default 5\n   */\n  maxPoints?: number;\n};\n\n/**\n * Options for the answerQuestion helper.\n */\nexport type LLMAnswerQuestionOptions = {\n  /**\n   * How detailed the answer should be.\n   * @default 'medium'\n   */\n  detail?: 'brief' | 'medium' | 'detailed';\n};\n\n// ============================================================================\n// Smart Suggestions Types\n// ============================================================================\n\n/**\n * Options for the suggest helper.\n */\nexport type LLMSuggestOptions = {\n  /**\n   * Number of suggestions to generate.\n   * @default 3\n   */\n  count?: number;\n  /**\n   * Optional context to inform the suggestions (e.g., surrounding text, app context).\n   */\n  context?: string;\n  /**\n   * Tone of the suggestions.\n   * @default 'neutral'\n   */\n  tone?: 'formal' | 'casual' | 'professional' | 'friendly' | 'neutral';\n};\n\n/**\n * A single suggestion item.\n */\nexport type LLMSuggestion = {\n  /** The suggested text */\n  text: string;\n};\n\n/**\n * Response from suggest/smartReply containing multiple suggestions.\n */\nexport type LLMSuggestResponse = {\n  /** Array of generated suggestions */\n  suggestions: LLMSuggestion[];\n  /** Raw response text from the model */\n  raw: string;\n};\n\n/**\n * Options for the smartReply helper.\n */\nexport type LLMSmartReplyOptions = {\n  /**\n   * Number of reply suggestions to generate.\n   * @default 3\n   */\n  count?: number;\n  /**\n   * Tone of the reply suggestions.\n   * @default 'neutral'\n   */\n  tone?: 'formal' | 'casual' | 'professional' | 'friendly' | 'neutral';\n  /**\n   * Optional persona/context for the replier (e.g., \"customer support agent\", \"friendly colleague\").\n   */\n  persona?: string;\n};\n\n/**\n * Options for the autocomplete helper.\n */\nexport type LLMAutocompleteOptions = {\n  /**\n   * Number of completions to generate.\n   * @default 3\n   */\n  count?: number;\n  /**\n   * Maximum length of each completion in words.\n   * @default 10\n   */\n  maxWords?: number;\n  /**\n   * Optional context to inform the completions (e.g., what the user is writing about).\n   */\n  context?: string;\n};\n\n// ============================================================================\n// Hook Types\n// ============================================================================\n\n/**\n * Options for the useChat hook.\n */\nexport type UseChatOptions = {\n  /** System prompt for the AI assistant */\n  systemPrompt?: string;\n  /** Maximum conversation turns to keep in memory (default: 10) */\n  maxTurns?: number;\n  /** Initial messages to populate the chat */\n  initialMessages?: LLMMessage[];\n  /** Callback when a response is complete */\n  onFinish?: (response: LLMResponse) => void;\n  /** Callback when an error occurs */\n  onError?: (error: Error) => void;\n};\n\n/**\n * Return type for the useChat hook.\n */\nexport type UseChatReturn = {\n  /** All messages in the conversation */\n  messages: LLMMessage[];\n  /** Current input text value */\n  input: string;\n  /** Set the input text value */\n  setInput: (input: string) => void;\n  /** Send the current input (or provided text) as a message */\n  sendMessage: (text?: string) => Promise<void>;\n  /** Whether the AI is currently streaming a response */\n  isStreaming: boolean;\n  /** Stop the current streaming response */\n  stop: () => void;\n  /** Clear all messages and reset the conversation */\n  clear: () => void;\n  /** The most recent error, if any */\n  error: Error | null;\n};\n\n/**\n * Options for the useCompletion hook.\n */\nexport type UseCompletionOptions = {\n  /** System prompt for the AI */\n  systemPrompt?: string;\n  /** Callback when completion is done */\n  onFinish?: (response: LLMResponse) => void;\n  /** Callback when an error occurs */\n  onError?: (error: Error) => void;\n};\n\n/**\n * Return type for the useCompletion hook.\n */\nexport type UseCompletionReturn = {\n  /** The current completion text */\n  completion: string;\n  /** Whether a completion is in progress */\n  isLoading: boolean;\n  /** Request a completion for the given prompt */\n  complete: (prompt: string) => Promise<string>;\n  /** Stop the current completion */\n  stop: () => void;\n  /** The most recent error, if any */\n  error: Error | null;\n};\n\n/**\n * Return type for the useOnDeviceAI hook.\n */\nexport type UseOnDeviceAIReturn = {\n  /** Whether on-device AI is available */\n  isAvailable: boolean;\n  /** Whether the availability check is still in progress */\n  isChecking: boolean;\n};\n\n// ============================================================================\n// Chat Memory Types\n// ============================================================================\n\n/**\n * Options for creating a ChatMemoryManager.\n */\nexport type ChatMemoryOptions = {\n  /**\n   * Maximum number of conversation turns to keep in memory.\n   * A turn is one user message + one assistant response.\n   * @default 10\n   */\n  maxTurns?: number;\n  /**\n   * Optional system prompt to prepend to every generated prompt.\n   */\n  systemPrompt?: string;\n};\n\n/**\n * A snapshot of the current chat memory state.\n */\nexport type ChatMemorySnapshot = {\n  /** All messages currently in memory */\n  messages: LLMMessage[];\n  /** The system prompt (if any) */\n  systemPrompt: string | undefined;\n  /** Current number of turns stored */\n  turnCount: number;\n  /** Maximum turns allowed */\n  maxTurns: number;\n};\n"]}
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAqXA;;GAEG;AACH,MAAM,OAAO,UAAW,SAAQ,KAAK;IACnC,IAAI,CAAiB;IACrB,OAAO,CAAS;IAEhB,YAAY,IAAoB,EAAE,OAAe,EAAE,OAAgB;QACjE,KAAK,CAAC,OAAO,IAAI,GAAG,IAAI,KAAK,OAAO,EAAE,CAAC,CAAC;QACxC,IAAI,CAAC,IAAI,GAAG,YAAY,CAAC;QACzB,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC;QACjB,IAAI,CAAC,OAAO,GAAG,OAAO,CAAC;IACzB,CAAC;CACF","sourcesContent":["/**\n * Role in a conversation message.\n */\nexport type LLMRole = 'system' | 'user' | 'assistant';\n\n/**\n * A single message in a conversation.\n */\nexport type LLMMessage = {\n  role: LLMRole;\n  content: string;\n};\n\n/**\n * Options for sendMessage.\n */\nexport type LLMSendOptions = {\n  /**\n   * Default system prompt to use if no system message is provided in the messages array.\n   * If a system message exists in the array, this is ignored.\n   */\n  systemPrompt?: string;\n};\n\n/**\n * Response from sendMessage.\n */\nexport type LLMResponse = {\n  /** The generated response text */\n  text: string;\n};\n\n/**\n * Options for streamMessage.\n */\nexport type LLMStreamOptions = {\n  /**\n   * Default system prompt to use if no system message is provided in the messages array.\n   * If a system message exists in the array, this is ignored.\n   */\n  systemPrompt?: string;\n};\n\n/**\n * Event payload for streaming tokens.\n */\nexport type LLMStreamEvent = {\n  /** Unique identifier for this streaming session */\n  sessionId: string;\n  /** The token/chunk of text received */\n  token: string;\n  /** Accumulated text so far */\n  accumulatedText: string;\n  /** Whether this is the final chunk */\n  isDone: boolean;\n};\n\n/**\n * Callback function for streaming events.\n */\nexport type LLMStreamCallback = (event: LLMStreamEvent) => void;\n\n// ============================================================================\n// Prompt Helper Types\n// ============================================================================\n\n/**\n * Options for the summarize helper.\n */\nexport type LLMSummarizeOptions = {\n  /**\n   * Target length for the summary.\n   * @default 'medium'\n   */\n  length?: 'short' | 'medium' | 'long';\n  /**\n   * Style of summary to generate.\n   * @default 'paragraph'\n   */\n  style?: 'paragraph' | 'bullets' | 'tldr';\n};\n\n/**\n * Options for the translate helper.\n */\nexport type LLMTranslateOptions = {\n  /**\n   * Target language to translate to.\n   */\n  to: string;\n  /**\n   * Source language (auto-detected if not provided).\n   */\n  from?: string;\n  /**\n   * Tone/formality of the translation.\n   * @default 'neutral'\n   */\n  tone?: 'formal' | 'informal' | 'neutral';\n};\n\n/**\n * Options for the rewrite helper.\n */\nexport type LLMRewriteOptions = {\n  /**\n   * Style to rewrite in.\n   */\n  style:\n    | 'formal'\n    | 'casual'\n    | 'professional'\n    | 'friendly'\n    | 'concise'\n    | 'detailed'\n    | 'simple'\n    | 'academic';\n};\n\n/**\n * Options for the extractKeyPoints helper.\n */\nexport type LLMExtractKeyPointsOptions = {\n  /**\n   * Maximum number of key points to extract.\n   * @default 5\n   */\n  maxPoints?: number;\n};\n\n/**\n * Options for the answerQuestion helper.\n */\nexport type LLMAnswerQuestionOptions = {\n  /**\n   * How detailed the answer should be.\n   * @default 'medium'\n   */\n  detail?: 'brief' | 'medium' | 'detailed';\n};\n\n// ============================================================================\n// Smart Suggestions Types\n// ============================================================================\n\n/**\n * Options for the suggest helper.\n */\nexport type LLMSuggestOptions = {\n  /**\n   * Number of suggestions to generate.\n   * @default 3\n   */\n  count?: number;\n  /**\n   * Optional context to inform the suggestions (e.g., surrounding text, app context).\n   */\n  context?: string;\n  /**\n   * Tone of the suggestions.\n   * @default 'neutral'\n   */\n  tone?: 'formal' | 'casual' | 'professional' | 'friendly' | 'neutral';\n};\n\n/**\n * A single suggestion item.\n */\nexport type LLMSuggestion = {\n  /** The suggested text */\n  text: string;\n};\n\n/**\n * Response from suggest/smartReply containing multiple suggestions.\n */\nexport type LLMSuggestResponse = {\n  /** Array of generated suggestions */\n  suggestions: LLMSuggestion[];\n  /** Raw response text from the model */\n  raw: string;\n};\n\n/**\n * Options for the smartReply helper.\n */\nexport type LLMSmartReplyOptions = {\n  /**\n   * Number of reply suggestions to generate.\n   * @default 3\n   */\n  count?: number;\n  /**\n   * Tone of the reply suggestions.\n   * @default 'neutral'\n   */\n  tone?: 'formal' | 'casual' | 'professional' | 'friendly' | 'neutral';\n  /**\n   * Optional persona/context for the replier (e.g., \"customer support agent\", \"friendly colleague\").\n   */\n  persona?: string;\n};\n\n/**\n * Options for the autocomplete helper.\n */\nexport type LLMAutocompleteOptions = {\n  /**\n   * Number of completions to generate.\n   * @default 3\n   */\n  count?: number;\n  /**\n   * Maximum length of each completion in words.\n   * @default 10\n   */\n  maxWords?: number;\n  /**\n   * Optional context to inform the completions (e.g., what the user is writing about).\n   */\n  context?: string;\n};\n\n// ============================================================================\n// Hook Types\n// ============================================================================\n\n/**\n * Options for the useChat hook.\n */\nexport type UseChatOptions = {\n  /** System prompt for the AI assistant */\n  systemPrompt?: string;\n  /** Maximum conversation turns to keep in memory (default: 10) */\n  maxTurns?: number;\n  /** Initial messages to populate the chat */\n  initialMessages?: LLMMessage[];\n  /** Callback when a response is complete */\n  onFinish?: (response: LLMResponse) => void;\n  /** Callback when an error occurs */\n  onError?: (error: Error) => void;\n};\n\n/**\n * Return type for the useChat hook.\n */\nexport type UseChatReturn = {\n  /** All messages in the conversation */\n  messages: LLMMessage[];\n  /** Current input text value */\n  input: string;\n  /** Set the input text value */\n  setInput: (input: string) => void;\n  /** Send the current input (or provided text) as a message */\n  sendMessage: (text?: string) => Promise<void>;\n  /** Whether the AI is currently streaming a response */\n  isStreaming: boolean;\n  /** Stop the current streaming response */\n  stop: () => void;\n  /** Clear all messages and reset the conversation */\n  clear: () => void;\n  /** The most recent error, if any */\n  error: Error | null;\n};\n\n/**\n * Options for the useCompletion hook.\n */\nexport type UseCompletionOptions = {\n  /** System prompt for the AI */\n  systemPrompt?: string;\n  /** Callback when completion is done */\n  onFinish?: (response: LLMResponse) => void;\n  /** Callback when an error occurs */\n  onError?: (error: Error) => void;\n};\n\n/**\n * Return type for the useCompletion hook.\n */\nexport type UseCompletionReturn = {\n  /** The current completion text */\n  completion: string;\n  /** Whether a completion is in progress */\n  isLoading: boolean;\n  /** Request a completion for the given prompt */\n  complete: (prompt: string) => Promise<string>;\n  /** Stop the current completion */\n  stop: () => void;\n  /** The most recent error, if any */\n  error: Error | null;\n};\n\n/**\n * Return type for the useOnDeviceAI hook.\n */\nexport type UseOnDeviceAIReturn = {\n  /** Whether on-device AI is available */\n  isAvailable: boolean;\n  /** Whether the availability check is still in progress */\n  isChecking: boolean;\n};\n\n// ============================================================================\n// Model Types\n// ============================================================================\n\n/**\n * A built-in model provided by the OS (e.g. Apple Foundation Models, ML Kit).\n * These are always available on supported devices -- no download needed.\n */\nexport type BuiltInModel = {\n  /** Unique model identifier (e.g. 'apple-fm', 'mlkit') */\n  id: string;\n  /** Human-readable model name */\n  name: string;\n  /** Whether this model is available on the current device/OS */\n  available: boolean;\n  /** Platform this model is associated with */\n  platform: 'ios' | 'android';\n  /** Maximum context window in tokens */\n  contextWindow: number;\n};\n\n/**\n * A downloadable model that the user manages (download, load, delete).\n * These require explicit download before use.\n */\nexport type DownloadableModel = {\n  /** Unique model identifier (e.g. 'gemma-e2b', 'gemma-e4b') */\n  id: string;\n  /** Human-readable model name */\n  name: string;\n  /** Parameter count label (e.g. '2.3B') */\n  parameterCount: string;\n  /** Download file size in bytes */\n  sizeBytes: number;\n  /** Maximum context window in tokens */\n  contextWindow: number;\n  /** Minimum device RAM in bytes required to run */\n  minRamBytes: number;\n  /** Current lifecycle status */\n  status: DownloadableModelStatus;\n};\n\n/**\n * Lifecycle status of a downloadable model.\n *\n * - 'not-downloaded': Model file is not on disk\n * - 'downloading': Model file is being downloaded\n * - 'loading': File is on disk, model is being loaded into memory for inference\n * - 'ready': Model is loaded in memory and ready for inference\n */\nexport type DownloadableModelStatus =\n  | 'not-downloaded'\n  | 'downloading'\n  | 'loading'\n  | 'ready';\n\n/**\n * Error codes for model-related operations.\n */\nexport type ModelErrorCode =\n  | 'MODEL_NOT_FOUND'\n  | 'MODEL_NOT_DOWNLOADED'\n  | 'DOWNLOAD_FAILED'\n  | 'DOWNLOAD_CORRUPT'\n  | 'DOWNLOAD_STORAGE_FULL'\n  | 'INFERENCE_OOM'\n  | 'INFERENCE_FAILED'\n  | 'MODEL_LOAD_FAILED'\n  | 'DEVICE_NOT_SUPPORTED';\n\n/**\n * Structured error for model operations.\n */\nexport class ModelError extends Error {\n  code: ModelErrorCode;\n  modelId: string;\n\n  constructor(code: ModelErrorCode, modelId: string, message?: string) {\n    super(message ?? `${code}: ${modelId}`);\n    this.name = 'ModelError';\n    this.code = code;\n    this.modelId = modelId;\n  }\n}\n\n/**\n * Event payload for model download progress.\n */\nexport type ModelDownloadProgressEvent = {\n  /** Model being downloaded */\n  modelId: string;\n  /** Download progress from 0 to 1 */\n  progress: number;\n};\n\n/**\n * Event payload for model state changes.\n */\nexport type ModelStateChangeEvent = {\n  /** Model whose state changed */\n  modelId: string;\n  /** New status */\n  status: DownloadableModelStatus;\n};\n\n// ============================================================================\n// Chat Memory Types\n// ============================================================================\n\n/**\n * Options for creating a ChatMemoryManager.\n */\nexport type ChatMemoryOptions = {\n  /**\n   * Maximum number of conversation turns to keep in memory.\n   * A turn is one user message + one assistant response.\n   * @default 10\n   */\n  maxTurns?: number;\n  /**\n   * Optional system prompt to prepend to every generated prompt.\n   */\n  systemPrompt?: string;\n  /**\n   * Maximum context window in tokens. When set, trimHistory will also\n   * trim messages that exceed this token budget (in addition to maxTurns).\n   * Whichever limit is hit first triggers trimming.\n   * @default Infinity (no token-based trimming)\n   */\n  contextWindow?: number;\n};\n\n/**\n * A snapshot of the current chat memory state.\n */\nexport type ChatMemorySnapshot = {\n  /** All messages currently in memory */\n  messages: LLMMessage[];\n  /** The system prompt (if any) */\n  systemPrompt: string | undefined;\n  /** Current number of turns stored */\n  turnCount: number;\n  /** Maximum turns allowed */\n  maxTurns: number;\n};\n"]}

package/ios/ExpoAiKit.podspec

@@ -15,7 +15,7 @@ Pod::Spec.new do |s|
     :tvos => '15.1'
   }
   s.swift_version  = '5.9'
-  s.source         = { git: 'https://github.com/laraelmas/expo-ai-kit' }
+  s.source         = { git: 'https://github.com/saidkaban/expo-ai-kit' }
   s.static_framework = true
 
   s.dependency 'ExpoModulesCore'

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "expo-ai-kit",
-  "version": "0.1.21",
+  "version": "0.2.0",
   "description": "Expo AI Kit module",
   "main": "build/index.js",
   "types": "build/index.d.ts",
@@ -34,11 +34,11 @@
     "expo-ai-kit",
     "ExpoAiKit"
   ],
-  "repository": "https://github.com/laraelmas/expo-ai-kit",
+  "repository": "https://github.com/saidkaban/expo-ai-kit",
   "bugs": {
-    "url": "https://github.com/laraelmas/expo-ai-kit/issues"
+    "url": "https://github.com/saidkaban/expo-ai-kit/issues"
   },
-  "author": "Lara Elmas (https://github.com/laraelmas)",
+  "author": "Said Kaban (https://github.com/saidkaban)",
   "license": "MIT",
   "homepage": "https://expo-ai-kit.dev",
   "dependencies": {},

package/src/ExpoAiKitModule.ts

@@ -1,12 +1,23 @@
 import { requireNativeModule } from 'expo-modules-core';
 import type { EventSubscription } from 'expo-modules-core';
-import { LLMMessage, LLMResponse, LLMStreamEvent } from './types';
+import {
+  LLMMessage,
+  LLMResponse,
+  LLMStreamEvent,
+  BuiltInModel,
+  DownloadableModelStatus,
+  ModelDownloadProgressEvent,
+  ModelStateChangeEvent,
+} from './types';
 
 export type ExpoAiKitModuleEvents = {
   onStreamToken: (event: LLMStreamEvent) => void;
+  onDownloadProgress: (event: ModelDownloadProgressEvent) => void;
+  onModelStateChange: (event: ModelStateChangeEvent) => void;
 };
 
 export interface ExpoAiKitNativeModule {
+  // Existing inference API
   isAvailable(): boolean;
   sendMessage(
     messages: LLMMessage[],
@@ -18,6 +29,29 @@ export interface ExpoAiKitNativeModule {
     sessionId: string
   ): Promise<void>;
   stopStreaming(sessionId: string): Promise<void>;
+
+  // Model discovery
+  getBuiltInModels(): BuiltInModel[];
+  getDownloadableModelStatus(modelId: string): DownloadableModelStatus;
+
+  // Model selection & memory management
+  // setModel is async: switching to a downloadable model loads it into memory.
+  // Auto-unloads the previous downloadable model (only one loaded at a time).
+  setModel(modelId: string): Promise<void>;
+  getActiveModel(): string;
+  // Explicitly free memory from the loaded downloadable model.
+  // Reverts to the platform built-in model.
+  unloadModel(): Promise<void>;
+
+  // Model lifecycle (downloadable models only)
+  downloadModel(
+    modelId: string,
+    url: string,
+    sha256: string
+  ): Promise<void>;
+  deleteModel(modelId: string): Promise<void>;
+
+  // Event subscription
   addListener<K extends keyof ExpoAiKitModuleEvents>(
     eventName: K,
     listener: ExpoAiKitModuleEvents[K]

package/src/hooks.ts

@@ -1,6 +1,14 @@
 import { useState, useEffect, useRef, useCallback } from 'react';
-import { isAvailable, streamMessage } from './index';
+import {
+  isAvailable,
+  streamMessage,
+  getBuiltInModels as getBuiltInModelsApi,
+  getDownloadableModels as getDownloadableModelsApi,
+  downloadModel as downloadModelApi,
+  deleteModel as deleteModelApi,
+} from './index';
 import { ChatMemoryManager } from './memory';
+import ExpoAiKitModule from './ExpoAiKitModule';
 import type {
   LLMMessage,
   UseChatOptions,
@@ -8,6 +16,10 @@ import type {
   UseCompletionOptions,
   UseCompletionReturn,
   UseOnDeviceAIReturn,
+  BuiltInModel,
+  DownloadableModel,
+  DownloadableModelStatus,
+  ModelError,
 } from './types';
 
 // Cache availability result across all hook instances
@@ -329,3 +341,162 @@ export function useCompletion(options: UseCompletionOptions = {}): UseCompletion
     error,
   };
 }
+
+/**
+ * React hook for managing a downloadable model's lifecycle.
+ *
+ * Tracks download status, progress, and provides download/delete controls.
+ *
+ * @param modelId - The downloadable model ID (e.g. 'gemma-e2b')
+ * @returns Model status, progress, and control functions
+ *
+ * @example
+ * ```tsx
+ * function ModelManager() {
+ *   const { status, progress, download, delete: remove, error } = useModel('gemma-e2b');
+ *
+ *   if (status === 'not-downloaded') {
+ *     return <Button title="Download" onPress={download} />;
+ *   }
+ *   if (status === 'downloading') {
+ *     return <Text>Downloading: {Math.round(progress * 100)}%</Text>;
+ *   }
+ *   if (status === 'loading') {
+ *     return <Text>Loading model...</Text>;
+ *   }
+ *   return <Text>Model ready!</Text>;
+ * }
+ * ```
+ */
+export function useModel(modelId: string): {
+  status: DownloadableModelStatus;
+  progress: number;
+  download: () => Promise<void>;
+  delete: () => Promise<void>;
+  error: ModelError | null;
+} {
+  const [status, setStatus] = useState<DownloadableModelStatus>('not-downloaded');
+  const [progress, setProgress] = useState(0);
+  const [error, setError] = useState<ModelError | null>(null);
+  const mountedRef = useRef(true);
+
+  useEffect(() => {
+    // Query initial status
+    try {
+      const initialStatus = ExpoAiKitModule.getDownloadableModelStatus(modelId);
+      setStatus(initialStatus);
+    } catch {
+      // Model not found or native module not ready
+    }
+
+    // Listen for state changes
+    const stateSubscription = ExpoAiKitModule.addListener(
+      'onModelStateChange',
+      (event) => {
+        if (event.modelId === modelId && mountedRef.current) {
+          setStatus(event.status);
+        }
+      }
+    );
+
+    // Listen for download progress
+    const progressSubscription = ExpoAiKitModule.addListener(
+      'onDownloadProgress',
+      (event) => {
+        if (event.modelId === modelId && mountedRef.current) {
+          setProgress(event.progress);
+        }
+      }
+    );
+
+    return () => {
+      mountedRef.current = false;
+      stateSubscription.remove();
+      progressSubscription.remove();
+    };
+  }, [modelId]);
+
+  const download = useCallback(async () => {
+    setError(null);
+    setProgress(0);
+    try {
+      await downloadModelApi(modelId, {
+        onProgress: (p) => {
+          if (mountedRef.current) setProgress(p);
+        },
+      });
+    } catch (err) {
+      if (mountedRef.current) {
+        setError(err as ModelError);
+      }
+    }
+  }, [modelId]);
+
+  const del = useCallback(async () => {
+    setError(null);
+    try {
+      await deleteModelApi(modelId);
+      if (mountedRef.current) {
+        setStatus('not-downloaded');
+        setProgress(0);
+      }
+    } catch (err) {
+      if (mountedRef.current) {
+        setError(err as ModelError);
+      }
+    }
+  }, [modelId]);
+
+  return { status, progress, download, delete: del, error };
+}
+
+/**
+ * React hook to discover all available models (built-in and downloadable).
+ *
+ * @returns Built-in models, downloadable models, and loading state
+ *
+ * @example
+ * ```tsx
+ * function ModelPicker() {
+ *   const { builtIn, downloadable, isLoading } = useAvailableModels();
+ *
+ *   if (isLoading) return <Text>Loading models...</Text>;
+ *
+ *   return (
+ *     <View>
+ *       <Text>Built-in: {builtIn.map(m => m.name).join(', ')}</Text>
+ *       <Text>Downloadable: {downloadable.map(m => m.name).join(', ')}</Text>
+ *     </View>
+ *   );
+ * }
+ * ```
+ */
+export function useAvailableModels(): {
+  builtIn: BuiltInModel[];
+  downloadable: DownloadableModel[];
+  isLoading: boolean;
+} {
+  const [builtIn, setBuiltIn] = useState<BuiltInModel[]>([]);
+  const [downloadable, setDownloadable] = useState<DownloadableModel[]>([]);
+  const [isLoading, setIsLoading] = useState(true);
+
+  useEffect(() => {
+    let mounted = true;
+
+    Promise.all([getBuiltInModelsApi(), getDownloadableModelsApi()]).then(
+      ([bi, dl]) => {
+        if (mounted) {
+          setBuiltIn(bi);
+          setDownloadable(dl);
+          setIsLoading(false);
+        }
+      }
+    );
+
+    return () => {
+      mounted = false;
+    };
+  }, []);
+
+  return { builtIn, downloadable, isLoading };
+}