API
getAvailability()getImageAnalysisAvailability()downloadModel()configureFallbackModel(...)warmup(...)createChat(...)deleteChat(...)generateText(...)streamText(...)cancelGeneration(...)addListener('availabilityChange', ...)addListener('systemAvailabilityChange', ...)addListener('downloadProgress', ...)addListener('textChunk', ...)addListener('generationStateChange', ...)removeAllListeners()generateImage(...)systemAvailability()download()prompt(...)endSession(...)- Interfaces
- Type Aliases
Public on-device LLM plugin contract.
method getAvailability()
getAvailability() => Promise<GetAvailabilityResult>
Returns detailed text-model availability. Web feature-detects Chrome's Prompt API; unsupported browsers return unavailable.
Returns: Promise<GetAvailabilityResult>
Since: 2.0.0
method getImageAnalysisAvailability()
getImageAnalysisAvailability() => Promise<GetImageAnalysisAvailabilityResult>
Returns image-analysis availability and the native backend that would handle vision input.
On iOS 27 builds compiled with Xcode 27 / Swift 6.4, returns the text-model status plus
backend: 'foundation-models' and maxImages: 4. Builds made with older Xcode report
unavailable and cannot include iOS 27 vision support. Android reports Gemini Nano prompt
APIs or a configured LiteRT-LM fallback. Web currently reports unavailable for image analysis.
Returns: Promise<GetImageAnalysisAvailabilityResult>
Since: 2.1.0
method downloadModel()
downloadModel() => Promise<void>
Starts an Android or Chrome Web model download. On Web, invoke from a user gesture; Chrome manages the model.
Since: 2.0.0
method configureFallbackModel(...)
configureFallbackModel(options: ConfigureFallbackModelOptions) => Promise<void>
Initializes an explicit Android LiteRT-LM fallback model. Gemini Nano remains preferred when available.
Configuring a model performs local file I/O and may take significant time. iOS and Web reject this API.
| Param | Type |
|---|---|
options |
ConfigureFallbackModelOptions |
Since: 2.0.0
method warmup(...)
warmup(options?: WarmupOptions | undefined) => Promise<void>
Warms model resources. Web creates and destroys a temporary text session; promptPrefix is iOS-only.
| Param | Type |
|---|---|
options |
WarmupOptions |
Since: 1.0.0
method createChat(...)
createChat(options?: CreateChatOptions | undefined) => Promise<CreateChatResult>
Creates a chat owned by the plugin until deletion.
| Param | Type |
|---|---|
options |
CreateChatOptions |
Returns: Promise<CreateChatResult>
Since: 2.0.0
method deleteChat(...)
deleteChat(options: DeleteChatOptions) => Promise<void>
Deletes a chat and cancels its generation.
| Param | Type |
|---|---|
options |
DeleteChatOptions |
Since: 2.0.0
method generateText(...)
generateText(options: GenerateTextOptions) => Promise<GenerateTextResult>
Generates complete text.
| Param | Type |
|---|---|
options |
GenerateTextOptions |
Returns: Promise<GenerateTextResult>
Since: 2.0.0
method streamText(...)
streamText(options: StreamTextOptions) => Promise<StreamTextResult>
Streams native chunks and returns complete text.
| Param | Type |
|---|---|
options |
GenerateTextOptions |
Returns: Promise<GenerateTextResult>
Since: 2.0.0
method cancelGeneration(...)
cancelGeneration(options: CancelGenerationOptions) => Promise<void>
Cancels an in-flight generation.
| Param | Type |
|---|---|
options |
CancelGenerationOptions |
Since: 2.0.0
method addListener('availabilityChange', ...)
addListener(eventName: 'availabilityChange', listenerFunc: AvailabilityChangeListener) => Promise<PluginListenerHandle>
Listens for availability changes. Web emits changes observed during availability checks and session creation/download.
| Param | Type |
|---|---|
eventName |
'availabilityChange' |
listenerFunc |
AvailabilityChangeListener |
Returns: Promise<PluginListenerHandle>
Since: 2.0.0
method addListener('systemAvailabilityChange', ...)
addListener(eventName: 'systemAvailabilityChange', listenerFunc: SystemAvailabilityChangeListener) => Promise<PluginListenerHandle>
| Param | Type |
|---|---|
eventName |
'systemAvailabilityChange' |
listenerFunc |
SystemAvailabilityChangeListener |
Returns: Promise<PluginListenerHandle>
Since: 1.0.0
method addListener('downloadProgress', ...)
addListener(eventName: 'downloadProgress', listenerFunc: DownloadProgressListener) => Promise<PluginListenerHandle>
Listens for Android or Chrome Web download progress.
| Param | Type |
|---|---|
eventName |
'downloadProgress' |
listenerFunc |
DownloadProgressListener |
Returns: Promise<PluginListenerHandle>
Since: 2.0.0
method addListener('textChunk', ...)
addListener(eventName: 'textChunk', listenerFunc: TextChunkListener) => Promise<PluginListenerHandle>
Listens for native text chunks.
| Param | Type |
|---|---|
eventName |
'textChunk' |
listenerFunc |
TextChunkListener |
Returns: Promise<PluginListenerHandle>
Since: 2.0.0
method addListener('generationStateChange', ...)
addListener(eventName: 'generationStateChange', listenerFunc: GenerationStateChangeListener) => Promise<PluginListenerHandle>
Listens for generation start, completion, cancellation, and failure.
| Param | Type |
|---|---|
eventName |
'generationStateChange' |
listenerFunc |
GenerationStateChangeListener |
Returns: Promise<PluginListenerHandle>
Since: 2.1.0
method removeAllListeners()
removeAllListeners() => Promise<void>
Removes every plugin listener.
Since: 1.0.0
method generateImage(...)
generateImage(options: GenerateImageOptions) => Promise<GenerateImageResponse>
Generates PNG images on iOS.
| Param | Type |
|---|---|
options |
GenerateImageOptions |
Returns: Promise<GenerateImageResponse>
Since: 1.0.0
method systemAvailability()
systemAvailability() => Promise<SystemAvailabilityResponse>
Returns: Promise<SystemAvailabilityResponse>
Since: 1.0.0
method download()
download() => Promise<void>
Since: 1.0.0
method prompt(...)
prompt(options: PromptOptions) => Promise<PromptResponse>
| Param | Type |
|---|---|
options |
PromptOptions |
Returns: Promise<PromptResponse>
Since: 1.0.0
method endSession(...)
endSession(options: EndSessionOptions) => Promise<void>
Ends a legacy session. Already-ended or unknown session identifiers succeed without effect.
| Param | Type |
|---|---|
options |
EndSessionOptions |
Since: 1.0.0
Interfaces
interface GetAvailabilityResult
Result returned by availability checks.
| Prop | Type | Description | Since |
|---|---|---|---|
status |
Availability |
Current text-model availability. | 2.0.0 |
interface GetImageAnalysisAvailabilityResult
Result returned by image-analysis availability checks.
| Prop | Type | Description | Since |
|---|---|---|---|
status |
Availability |
Current image-analysis availability. | 2.1.0 |
backend |
ImageAnalysisBackend |
Native backend that would handle image analysis when available. | 2.1.0 |
maxImages |
number |
Maximum images accepted in one generation for the active backend. | 2.1.0 |
interface ConfigureFallbackModelOptions
Configures an opt-in Android LiteRT-LM fallback used when Gemini Nano is unavailable.
The model must already exist as an app asset or a readable app-managed file. iOS and Web reject this API.
| Prop | Type | Description | Since |
|---|---|---|---|
path |
string |
.litertlm model path. Use /android_asset/... for bundled assets or an absolute app-managed file path. |
2.0.0 |
maxTokens |
number |
Combined context capacity passed to LiteRT-LM. Defaults to 4096. | 2.0.0 |
maxImages |
number |
Maximum images accepted by one generation for a vision-capable model. Defaults to 1. | 2.0.0 |
supportsImages |
boolean |
Initializes LiteRT-LM's vision pipeline. Defaults to true; set to false only for a text-only model. |
2.0.0 |
interface WarmupOptions
Warmup options. Android performs global model warmup; iOS can prewarm a chat.
Web creates and releases a temporary session, optionally using a chat's context.
| Prop | Type | Description | Since |
|---|---|---|---|
chatId |
string |
Explicit chat identifier to prewarm on iOS or use as context for Web warmup. | 2.0.0 |
sessionId |
string |
1.0.0 | |
promptPrefix |
string |
Optional prompt prefix used by Foundation Models. | 1.0.0 |
interface CreateChatResult
Result containing the plugin-owned chat identifier.
| Prop | Type | Description | Since |
|---|---|---|---|
id |
string |
Identifier required by generation and deletion calls. | 2.0.0 |
interface CreateChatOptions
Options for creating an owned chat.
| Prop | Type | Description | Since |
|---|---|---|---|
instructions |
string |
Persistent system instructions for this chat. | 2.0.0 |
history |
ChatHistoryOptions |
History limits applied on iOS, Android, and Web. | 2.0.0 |
interface ChatHistoryOptions
Chat history limits. All implementations retain instructions and discard oldest whole turns.
| Prop | Type | Description | Since |
|---|---|---|---|
maxMessages |
number |
Maximum retained messages. Defaults to 20. | 2.0.0 |
maxCharacters |
number |
Maximum retained message characters. Defaults to 12000. | 2.0.0 |
interface DeleteChatOptions
Options for deleting a chat.
| Prop | Type | Description | Since |
|---|---|---|---|
id |
string |
Chat identifier returned by createChat(). |
2.0.0 |
interface GenerateTextResult
Result of a text generation.
| Prop | Type | Description | Since |
|---|---|---|---|
text |
string |
Complete generated text. | 2.0.0 |
generationId |
string |
Identifier that can correlate diagnostics with a generation. | 2.0.0 |
interface GenerateTextOptions
Options for a non-streaming generation.
| Prop | Type | Description | Since |
|---|---|---|---|
chatId |
string |
Chat identifier returned by createChat(). |
2.0.0 |
prompt |
string |
User prompt. | 2.0.0 |
images |
ImageInput[] |
Images supplied to a vision-capable backend. On iOS 27+ (builds compiled with Xcode 27 / Swift 6.4), Foundation Models Attachment accepts up to 4 images of at most 32 MiB each via readable absolute paths, file:// URLs, raw Base64, or Base64 data URLs; after a successful generation, attachments are removed from retained chat history while the text prompt and response remain. Android uses Gemini Nano prompt APIs or a configured LiteRT-LM fallback with absolute/file:///content:///Base64 input and ML Kit aggregate pixel limits. Web and text-only backends reject image input with LOCAL_LLM_UNSUPPORTED. |
2.1.0 |
imagePaths |
string[] |
Local image paths supplied to a vision-capable Android LiteRT-LM fallback model. Absolute paths, file:// URLs, and readable content:// URIs are accepted. This compatibility path retains the v2.0 LiteRT-LM routing even when ML Kit is available. |
2.0.0 |
options |
GenerationOptions |
Optional generation controls. | 2.0.0 |
interface ImageUriInput
Local URI image input.
| Prop | Type | Description | Since |
|---|---|---|---|
uri |
string |
Image URI. iOS accepts readable absolute local paths and file:// URLs. Android accepts absolute paths, file:// URLs, and content:// URIs. |
2.1.0 |
base64 |
Base64 and URI inputs are mutually exclusive. | 2.1.0 |
interface Base64ImageInput
Base64-encoded image input.
| Prop | Type | Description | Since |
|---|---|---|---|
base64 |
string |
Raw Base64 image bytes or a data:image/...;base64,... URL. The decoded image must not exceed 32 MiB. |
2.1.0 |
uri |
Base64 and URI inputs are mutually exclusive. | 2.1.0 |
interface GenerationOptions
Cross-platform text generation controls. Unsupported values are rejected, not clamped. Chrome Web requires these controls to be omitted.
| Prop | Type | Description | Since |
|---|---|---|---|
temperature |
number |
Sampling temperature. | 2.0.0 |
topK |
number |
Samples from the k most likely tokens. | 2.0.0 |
maxOutputTokens |
number |
Maximum generated tokens. | 2.0.0 |
interface CancelGenerationOptions
Options for cancelling an in-flight generation.
| Prop | Type | Description | Since |
|---|---|---|---|
chatId |
string |
Chat that owns the generation. | 2.0.0 |
generationId |
string |
Optional generation identifier; a mismatch is treated as not found. | 2.0.0 |
interface PluginListenerHandle
| Prop | Type |
|---|---|
remove |
() => Promise<void> |
interface SystemAvailabilityResponse
| Prop | Type | Description | Since |
|---|---|---|---|
status |
LLMAvailability |
Legacy availability value. Detailed states are folded into the original four-value contract. | 1.0.0 |
interface DownloadProgressEvent
Model download progress. Intermediate Android events omit progress because ML Kit has no total byte count.
| Prop | Type | Description | Since |
|---|---|---|---|
progress |
number |
Known normalized progress: 0 at start and 1 at completion. | 2.0.0 |
downloadedBytes |
number |
Bytes downloaded so far when supplied by ML Kit. | 2.0.0 |
totalBytes |
number |
Total bytes, when a platform SDK supplies it. Currently omitted on Android. | 2.0.0 |
interface TextChunkEvent
Incremental text emitted by streamText().
| Prop | Type | Description | Since |
|---|---|---|---|
chatId |
string |
Chat that owns the generation. | 2.0.0 |
generationId |
string |
Identifier of this generation. | 2.0.0 |
text |
string |
Newly generated text only, not the accumulated snapshot. | 2.0.0 |
interface GenerationStateChangeEvent
Lifecycle event emitted for both generateText() and streamText().
| Prop | Type | Description | Since |
|---|---|---|---|
chatId |
string |
Chat that owns the generation. | 2.1.0 |
generationId |
string |
Native generation identifier, available from the started event. |
2.1.0 |
state |
GenerationState |
Current lifecycle state. | 2.1.0 |
errorCode |
LocalLLMErrorCode |
Stable error code for cancelled and failed states. |
2.1.0 |
interface GenerateImageResponse
Image generation result.
| Prop | Type | Description | Since |
|---|---|---|---|
pngBase64Images |
string[] |
Raw base64 PNG images without a data-URI prefix. | 1.0.0 |
interface GenerateImageOptions
Image generation options. Image generation is available only on iOS 18.4+.
| Prop | Type | Description | Since |
|---|---|---|---|
prompt |
string |
Image description. | 1.0.0 |
promptImages |
string[] |
Optional base64 reference images. | 1.0.0 |
count |
number |
Number of variations. Defaults to 1. | 1.0.0 |
interface PromptResponse
Legacy prompt response.
| Prop | Type | Description | Since |
|---|---|---|---|
text |
string |
Complete generated text. | 1.0.0 |
interface PromptOptions
Legacy prompt options.
| Prop | Type | Description | Since |
|---|---|---|---|
sessionId |
string |
Optional legacy session identifier. | 1.0.0 |
instructions |
string |
Instructions used when the legacy session is first created. | 1.0.0 |
options |
LLMOptions |
Legacy generation controls. | 1.0.0 |
prompt |
string |
User prompt. | 1.0.0 |
interface LLMOptions
| Prop | Type | Description | Since |
|---|---|---|---|
temperature |
number |
Sampling temperature. | 1.0.0 |
maximumOutputTokens |
number |
Maximum generated tokens. | 1.0.0 |
interface EndSessionOptions
Legacy session deletion options.
| Prop | Type | Description | Since |
|---|---|---|---|
sessionId |
string |
Legacy session identifier. | 1.0.0 |
Type Aliases
type alias Availability
The semantic availability of the on-device text model.
'available' | 'device-not-eligible' | 'not-enabled' | 'downloadable' | 'downloading' | 'not-ready' | 'unavailable'
type alias ImageAnalysisBackend
Native backend selected for on-device image analysis.
'foundation-models' | 'ml-kit-prompt' | 'litert-lm'
type alias ImageInput
Image reference for vision-capable text generation.
type alias StreamTextOptions
Options for native streaming generation.
type alias StreamTextResult
Final result of a native streaming generation.
type alias AvailabilityChangeListener
Listener for availability changes.
(event: GetAvailabilityResult): void
type alias SystemAvailabilityChangeListener
(event: SystemAvailabilityResponse): void
type alias LLMAvailability
'available' | 'unavailable' | 'notready' | 'downloadable'
type alias DownloadProgressListener
Listener for model download progress.
(event: DownloadProgressEvent): void
type alias TextChunkListener
Listener for native generation chunks.
(event: TextChunkEvent): void
type alias GenerationStateChangeListener
Listener for native generation lifecycle changes.
(event: GenerationStateChangeEvent): void
type alias GenerationState
Native generation lifecycle state.
'started' | 'completed' | 'cancelled' | 'failed'
type alias LocalLLMErrorCode
Stable Local LLM error codes.
'LOCAL_LLM_NOT_AVAILABLE' | 'LOCAL_LLM_DEVICE_NOT_ELIGIBLE' | 'LOCAL_LLM_NOT_ENABLED' | 'LOCAL_LLM_MODEL_NOT_READY' | 'LOCAL_LLM_MODEL_DOWNLOAD_REQUIRED' | 'LOCAL_LLM_CONTEXT_WINDOW_EXCEEDED' | 'LOCAL_LLM_CHAT_NOT_FOUND' | 'LOCAL_LLM_CHAT_BUSY' | 'LOCAL_LLM_GENERATION_NOT_FOUND' | 'LOCAL_LLM_GENERATION_CANCELLED' | 'LOCAL_LLM_INVALID_OPTIONS' | 'LOCAL_LLM_UNSUPPORTED' | 'LOCAL_LLM_IMAGE_NOT_READABLE' | 'LOCAL_LLM_IMAGE_TOO_LARGE' | 'LOCAL_LLM_GENERATION_FAILED' | 'LOCAL_LLM_IMAGE_GENERATION_FAILED' | 'LOCAL_LLM_UNKNOWN_ERROR'