AI Integration
OpenTodoList can use local or online AI providers to transform unstructured input into structured OpenTodoList data. Recipe import is the first workflow built on this integration; the same foundation can support additional item types, such as complete todo lists, in the future.
AI is only used when you explicitly start an AI action. Currently, this means selecting Parse with AI during a recipe import.
Online providers receive the content you submit
OpenTodoList does not send library data in the background. An on-device provider keeps AI processing on the device. When an online provider is active, check its privacy policy before using the feature. If you submit a URL, OpenTodoList first downloads its readable text and then passes that text to the active provider.
Configuration
Open Settings, find AI Integration, and configure these values:
| Setting | Description |
|---|---|
| Provider | Selects an individual provider or automatic on-device-first routing. |
| Allow automatic fallback to the online provider | When automatic routing is selected, permits OpenTodoList to use the configured OpenAI-compatible provider if no local provider is available. This is disabled by default. |
| API Base URL | Base URL of an OpenAI-compatible API. OpenTodoList appends /chat/completions when needed. |
| Model | Exact model identifier expected by the provider. |
| Structured Output | Selects how the provider is asked to produce JSON. See Output modes. |
| API Key | Optional for local providers, but usually required for hosted services. Select Save to put it in the device's credential storage or Clear to remove it. |
API keys are supplied by you at runtime. They are not included in the OpenTodoList application or source code. The provider may require a paid plan, available credit, or may impose rate limits independently of OpenTodoList.
The settings page shows the provider that would currently handle an AI action and whether processing stays on the device or sends content online. Selecting an online provider explicitly always allows that provider to be used.
Apple on-device model
On supported Apple devices, OpenTodoList can use Apple's Foundation Models framework. This provider requires iOS 26 or macOS 26 or newer, a device that supports Apple Intelligence, and Apple Intelligence to be enabled. It does not require an API key or send the submitted content to an AI service.
For direct macOS downloads, this provider is included in the Apple Silicon
(arm64) package. The legacy Intel (x86_64) package does not include it
because Apple Intelligence is unavailable on Intel Macs.
On a fresh Apple installation, Automatic (prefer on-device) is selected. If the model is unavailable because the device is unsupported, Apple Intelligence is disabled, or its model is still downloading, OpenTodoList shows the reason. It does not silently switch to an online provider. You can either select the OpenAI-compatible provider yourself or explicitly enable online fallback.
An existing OpenAI-compatible configuration remains selected when upgrading, so upgrades do not unexpectedly change a working setup.
Example: Groq
The following configuration has been tested successfully:
| Setting | Value |
|---|---|
| API Base URL | https://api.groq.com/openai/v1 |
| Model | openai/gpt-oss-120b |
| Structured Output | Strict JSON schema |
| API Key | A Groq API key |
Groq documents both its
OpenAI-compatible endpoint and the
models supporting strict structured output.
During testing, openai/gpt-oss-20b sometimes returned
json_validate_failed; switching to openai/gpt-oss-120b resolved the issue.
Example: OpenAI
Use https://api.openai.com/v1 as the API Base URL and an API model available
to your account. For strict mode, select a model that supports both Chat
Completions and Structured Outputs. The
OpenAI model catalogue lists
the currently available models and their capabilities.
Output modes
JSON object (compatible) asks the model to return valid JSON and describes the required OpenTodoList data structure in the prompt. It works with more OpenAI-compatible servers, but the provider does not guarantee that every field has the expected type.
Strict JSON schema sends a schema for the requested OpenTodoList data to the provider. A supporting model is constrained to return the expected fields and value types. This is the preferred option when the provider and model support it. Providers that do not implement strict structured output can reject the request with an HTTP 400 error; use compatible mode in that case.
The schema is selected by the action. For example, recipe import requests recipe fields. A future todo-list importer could use the same provider configuration with a todo-list-specific schema.
Troubleshooting
The page that started the AI action shows the HTTP status and provider error details. The message can be selected on desktop or copied with a long press on mobile. Typical errors include:
- HTTP 400: The model may not support the selected output mode, or it failed to generate valid JSON. Try compatible mode or another model.
- HTTP 401/403: Check the API key and whether it has permission to use the selected model.
- HTTP 429: The provider rejected the request because of a rate limit or insufficient quota. Check the provider account and billing status.
URL imports support public HTTP and HTTPS pages containing text, HTML, JSON, or XML, up to 2 MiB. They do not execute JavaScript or sign in to websites. If a page cannot be read, paste its visible text instead.
Provider model names and capabilities can change. Consult the provider's documentation if a previously working configuration stops working.