AI Integration

Configure AI chat, LaTeX error suggestions, user access, quotas, and optional search services.

This feature is provided by ayaka-notes/ayakaleaf-pro and is available from v6.3.0. We welcome your feedback if you encounter any problems.

AI assistant and LaTeX error assistant

Ayakaleaf Pro brings AI features into the editor in 2 ways.

• The AI Assistant can use your project documents and current selection as context to answer questions and suggest edits for you to review.
• The Error Assistant proposes a targeted fix when you select a LaTeX compilation error.

Toolkit configuration

Add the following to config/variables.env in your Toolkit deployment, replacing the example URL, key, and model with values from your provider:

AI_ENABLED=true
AI_BASE_URL=https://ai-gateway.example.com/v1
AI_API_KEY=REPLACE_WITH_YOUR_GATEWAY_API_KEY
AI_MODEL=YOUR_TEXT_MODEL_ID

Keep real API keys in your deployment environment file and out of version control. The values above are placeholders, not working credentials.

The quality of AI suggestions depends on the model you choose. If you already have a Codex or ChatGPT subscription, you can connect it via CLIProxyAPI’s OpenAI-compatible endpoint.

AI_BASE_URL is the OpenAI-compatible API base URL, including the provider’s version prefix where required. Do not append /chat/completions since we will append this internally. The gateway and model must support streaming chat completions and function tools. Both features send document context to this gateway; chat can also send uploaded images when using an image-capable model.

Toolkit forwards config/variables.env into the application container. Keep the variable names shown here; do not add an OVERLEAF_ prefix. From the Toolkit directory, recreate the application container after changing these variables:

bin/up -d

Gateway settings

Variable	Default	Purpose
AI_ENABLED	false	Set exactly true to enable chat and error suggestions for the instance. Unset or any other value keeps them disabled. A working gateway configuration is also required.
AI_BASE_URL	None; required	OpenAI-compatible API base URL.
AI_API_KEY	None; required	API key for that gateway, used by the server.
AI_MODEL	None; required	Text model used by the default chat configuration and by LaTeX error suggestions.
AI_IMAGE_MODEL	Unset	Optional image-capable model on the same gateway, using the same API key.
AI_MAX_STEPS	20	Maximum tool calls per user message in AI chat, including automatic continuations. Use a positive integer.
AI_PROXY_URL	Unset	Optional HTTP proxy URL for calls to the AI gateway. It does not configure the web or documentation search clients.
AI_TOKEN_QUOTA	0	Per-user token limit shared by chat and error suggestions for each period. Unset or 0 means unlimited; use a positive integer for a limit.
AI_TOKEN_QUOTA_PERIOD	month	month resets on the first day at 00:00 UTC; week resets Monday at 00:00 UTC. Other values use month.

For image uploads, set AI_IMAGE_MODEL to a model that accepts image input and supports the tools used by chat. Any chat request whose history contains an image attachment uses this model, including later messages in that conversation. Without this setting, image requests use the normal chat model, which must itself support images. LaTeX error suggestions continue to use AI_MODEL.

For example, to enable an image model and a weekly AI allowance:

AI_IMAGE_MODEL=YOUR_IMAGE_CAPABLE_MODEL_ID
AI_TOKEN_QUOTA=100000
AI_TOKEN_QUOTA_PERIOD=week

User access and consent

Instance availability and user permission are separate. AI_ENABLED and the gateway configuration control instance availability. A signed-in user must also pass the existing account checks:

• aiFeatures.enabled must not be false. This existing database field controls both chat and LaTeX error suggestions.
• The user’s effective features.aiUsageQuota must match the configured unlimited tier (unlimited by default), or the existing legacy features.aiErrorAssistant permission must be enabled. Effective features include applicable account feature overrides.

Enabling the checkbox alone does not change the user’s plan. The aiUsageQuota field is a permission tier, not a numeric token allowance. AI_TOKEN_QUOTA is a separate limit applied equally to each permitted user; the current module does not provide an individual numeric limit per account.

In the admin user list, select a user and open Update account info → AI features. Enable AI features updates aiFeatures.enabled when the account changes are saved. The server checks current permissions on new AI requests, including requests from an already open editor. Refresh the editor to update its visible controls after a permission change.

Usage and reset

The admin AI features tab shows the current period’s Usage, Limit, and Reset button on one row. Usage is read when the tab opens; it is not continuously refreshed. Reopen the tab after a chat or error suggestion finishes to see the latest count. Reset takes effect immediately and clears only that user’s current period counter, then reloads the displayed usage. It does not require saving the rest of the account form.

Chat and error suggestion usage share one Redis counter, updated from the model provider’s reported total tokens after a request completes. This includes input and output tokens across model steps. Input can include conversation history, document context, and tool results, so a follow-up can consume more tokens than the new message alone. Usage is recorded even when the limit is Unlimited. Requests without a reported token total do not add to the counter; historical unrecorded usage cannot be reconstructed by the module.

Quota checks happen before streaming. A request, or several concurrent requests, can exceed the remaining allowance before later requests are blocked. This is a usage allowance rather than a strict provider spending cap. If the quota lookup fails, the request is allowed and the failure is logged.

Both features use AI_TOKEN_QUOTA; error suggestions have no separate request-count limit. Resetting the counter does not change permission, consent, the configured limit, or the provider’s own billing records. Counters use UTC period keys and expire after 40 days; retaining Redis data preserves current usage across application restarts.

Optional search services

Web search uses a Tavily-compatible API. It is available when a search API key is configured. These settings are independent of the AI gateway:

Variable	Default	Purpose
TAVILY_API_KEY	Unset	Search API key. Takes precedence over WEB_SEARCH_API_KEY.
WEB_SEARCH_API_KEY	Unset	Alternative name for the search API key.
WEB_SEARCH_URL	https://api.tavily.com/search	Search endpoint; custom endpoints must accept the Tavily request and response format.
WEB_SEARCH_MAX_RESULTS	5	Results requested per search; use a positive integer supported by the service.
WEB_SEARCH_DEPTH	basic	Search depth, normally basic or advanced.
WEB_SEARCH_PROVIDER	tavily	The current implementation supports the Tavily-compatible protocol only; changing this value does not select another adapter.
DOCS_MCP_URL	https://docs.overleaf.com/~gitbook/mcp	Documentation search endpoint. Set to an empty string to disable documentation search.

For example:

TAVILY_API_KEY=REPLACE_WITH_YOUR_SEARCH_API_KEY
WEB_SEARCH_MAX_RESULTS=5
WEB_SEARCH_DEPTH=basic
DOCS_MCP_URL=https://docs.overleaf.com/~gitbook/mcp

Documentation search calls the configured GitBook MCP endpoint’s searchDocumentation tool and accepts JSON or SSE responses. This is an MCP client for documentation search; these modules do not expose project files as an MCP server or provide a general-purpose MCP server registry.

Search queries go to the configured search service. Search results can then be included in requests to the AI gateway. The chat’s Tools menu lets users enable or disable Web and Documentation for their requests; a tool must also be configured on the server to be available to the model.