How to use this plugin?

Before using any feature of this plugin, you should call the following client actions: CheckLocalLLMPlugin and SystemAvailability.

CheckLocalLLMPlugin checks if the plugin is available at runtime. In most cases it should return IsAvailable=True, but in case of False check the returned Error for more information.

Afterwards, you can call the SystemAvailability client action to check whether on-device AI is available on the device. It returns a LLMAvailability output with one of the following values:

• Available — The model is ready to use.
• Downloadable — The model exists but needs to be downloaded first (Android only). More info below.
• NotReady — The model is present but not yet ready to be used. This can happen if the model is still being downloaded or initialized.
• Unavailable — The model is not available on the device. This can be because the device does not meet the hardware requirements, or because the user has not enabled Gemini Nano / Apple Intelligence on their device.

If LLMAvailability is Unavailable, you will not be able to use any other plugin feature. In that case you should show an appropriate message to the user and abort the operation.

Downloading the model (Android only)

If SystemAvailability returns Downloadable, the next step before sending prompts is to call the Download client action to start the model download. This client action is only available on Android — on iOS the operating system manages the model automatically and Download is not supported.

To be notified of when the model is downloaded and ready, you can drag the LocalLLMSystemAvailabilityEvent block to your screen. This block fires a SystemAvailabilityChange whenever the system availability status changes and provides the updated LLMAvailability value, so you can react as soon as the model transitions to Available and proceed with your flow.

(Optional) Warming up the model

Once the model is available, you can optionally call Warmup before sending your first prompt to reduce the latency of that first response.

Note the following platform differences:

• On Android, Warmup ignores both the SessionId and PromptPrefix inputs.
• On iOS, you must provide a SessionId, because the warmup applies to a specific session. You optionally can provide a PromptPrefix input, so the model can pre-initialize with that prefix in mind e.g. 'You are a helpful assistant that provides concise answers'. This is especially useful if you know in advance the kind of interactions users are meant to have with the model.

Sending a prompt

When the model is ready, drag the Prompt client action to the place in your flow where you want to trigger AI inference. The only mandatory input is Prompt — the text you want to send to the model. The client action returns a structure with a Text output containing the model's response.

You can also provide these optional inputs:

• SessionId — a string identifier for the conversation. Reusing the same SessionId across multiple Prompt calls enables multi-turn conversations where the model retains context from previous exchanges.
• Instructions — a system-level instruction to guide the model's behavior throughout the conversation, for example "You are a helpful customer support assistant."
• Additional model options available with the PromptLLMOptions structure.

After the client action runs, you should check if Success is True (if False means an error occurred, refer to error handling below in this documentation); if so proceed with your logic based on the Text output returned.

Ending a session

When a conversation is complete, you can call EndSession and provide the SessionId to free up the resources associated with that session.

Generating images (iOS only)

The GenerateImage client action creates an image from a text prompt. This feature is available only on iOS, and requires iOS 18.4 or later. The mandatory input is Prompt — a description of the image you want to generate. You may optionally provide reference images using PromptImages attribute (you can get images from the user's device using supported Components like Camera Plugin or Upload Widget), and you can generate multiple variants of an image using Count (by default only one is generated).

After the client action runs, you should check if Success is True (if False means an error occurred, refer to error handling below in this documentation); if so you can use the returned list of images (list of Binary Data, of size Count) to display in your screen or save in the device (e.g. using the supported File Plugin).

Error handling

The plugin's client actions return an Error if Success=False. The error includes an ErrorCode output that identifies the problem, and an ErrorMessage that can provide more information. Available error codes are:

• LOCAL_LLM_UNSUPPORTED_PLATFORM — The device OS or hardware does not support on-device AI.
• LOCAL_LLM_NOT_ENABLED — On-device AI is supported on the device but has not been enabled by the user. On iOS, Apple Intelligence must be enabled in the device settings.
• LOCAL_LLM_NOT_READY — The model is present but is still downloading or initializing. Try again later.
• LOCAL_LLM_UNAVAILABLE — The model is currently unavailable for unspecified reasons.
• LOCAL_LLM_RESPONSE_IN_PROGRESS — A prompt was sent while the session is still generating a previous response. Wait for the current response to complete before sending a new one.
• LOCAL_LLM_NOT_INITIALIZED — The plugin failed to initialize properly.
• LOCAL_LLM_MISSING_PARAMETER — A required parameter was not provided to the client action.
• LOCAL_LLM_WEB_NOT_SUPPORTED — The client action was called on a web platform, which is not supported by this plugin.
• LOCAL_LLM_IMAGE_GENERATION_FAILED — Image generation failed (iOS only).
• LOCAL_LLM_FEATURE_NOT_SUPPORTED_ON_ANDROID — The requested feature is not available on Android (e.g. GenerateImage).
• LOCAL_LLM_FEATURE_NOT_SUPPORTED_ON_IOS — The requested feature is not available on iOS (e.g. Download).
• LOCAL_LLM_UNKNOWN_ERROR — An unexpected error occurred in the underlying platform SDK.

Always handle errors returned by plugin client actions and, if applicable, show meaningful feedback to the user.

Additional references

This plugin uses a Capacitor Labs Local LLM plugin, source available here. Alternatively to using the contact e-mail, you may report a bug request by opening a GitHub issue there.