AI
AI provider, rate limits, and circuit breaker configuration.
The AI settings configure an optional OpenAI-compatible LLM integration. All settings are in the [AI] section of config.ini and managed through Settings > AI in the web UI.
All AI features are disabled when AI_API_KEY is not set. The app works fully without AI configuration.
Provider
| Setting | Type | Default | Description |
|---|---|---|---|
AI_BASE_URL | string | — | OpenAI-compatible API base URL. Examples: http://localhost:11434/v1 (Ollama), https://openrouter.ai/api/v1 (OpenRouter). |
AI_API_KEY | string | — | API key for the provider. Stored encrypted in config.ini. |
AI_MODEL | string | — | Model identifier (e.g., llama3.2:latest, gpt-4o-mini). |
Any endpoint that supports the OpenAI chat completions API works — Ollama, LM Studio, LiteLLM, OpenRouter, OpenAI, and others.
HTTPS required for remote endpoints
Non-localhost endpoints must use HTTPS. Local endpoints (localhost, 127.0.0.1) are allowed over HTTP.
Rate Limits
| Setting | Type | Default | Description |
|---|---|---|---|
AI_TIMEOUT | int | 30 | Maximum seconds to wait for an AI response. Requests exceeding this are cancelled. |
AI_RPM_LIMIT | int | 20 | Maximum requests per minute (sliding window). |
AI_DAILY_TOKEN_LIMIT | int | 100000 | Maximum total tokens (prompt + completion) per day. Resets at midnight. |
If you're using a local model (Ollama, LM Studio), you can safely increase these limits since there are no API costs. For hosted providers, set limits that match your plan to avoid unexpected charges.
Circuit Breaker
The circuit breaker prevents cascading failures when the AI endpoint is unavailable.
| Setting | Type | Default | Description |
|---|---|---|---|
AI_CIRCUIT_THRESHOLD | int | 5 | Consecutive failures before the circuit opens (stops sending requests). |
AI_CIRCUIT_COOLDOWN | int | 300 | Seconds before the circuit transitions from open to half-open, allowing a test request through. |
States
| State | Behavior |
|---|---|
| Closed | Normal operation — all requests proceed. |
| Open | All AI requests are skipped. Core operations continue without AI. |
| Half-open | One test request is allowed through. Success closes the circuit; failure re-opens it. |
The current circuit breaker state is visible in Settings > AI under the AI Status section.
Database Tables
AI features use three tables, created automatically:
| Table | Purpose |
|---|---|
ai_activity_log | Logs every AI action with feature type, token usage, latency, and success/failure. |
ai_metadata_history | Stores original metadata values before AI enrichment or reconciliation, enabling revert. |
ai_cache | Caches AI responses to avoid redundant calls for the same input. |
API Endpoints
| Method | Endpoint | Description |
|---|---|---|
GET | /api/ai/status | AI configuration status and usage metrics. |
POST | /api/ai/test | Test connection with provided credentials. |
GET | /api/activity | AI activity feed (supports limit and offset params). |
POST | /api/ai/chat/stream | Streaming chat responses via SSE. |
GET | /api/ai/suggestions | Cached weekly pull list suggestions. |
All endpoints require session authentication.
See the AI Features guide for usage details.