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 and PDF files when using a model that accepts them.

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_PDF_MODEL	Unset	Optional model on the same gateway for chats with PDF files, using the same API key. From v6.4.0.
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.

PDF attachments are introduced from v6.4.0 and later. Users can attach PDF files of up to 2 MB, like images. The chat sends each PDF file as it is, as a Chat Completions file part, so the gateway and model must accept PDF input: OpenAI’s vision models do, while many self-hosted gateways, such as vLLM, accept images but refuse PDF files. Set AI_PDF_MODEL to a model that reads PDF files; any chat whose history contains a PDF file uses it, including later messages and any images in that conversation, so it should accept images too. Without this setting, PDF chats use AI_MODEL. When the model refuses a PDF file, the chat tells the user to ask the administrator to set AI_PDF_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 check: aiFeatures.enabled must not be false. This existing database field controls both chat and LaTeX error suggestions. When it is unset, AI features are enabled for the user.

AI_TOKEN_QUOTA is a 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. A user without permission still sees the AI assistant in the editor, but cannot send messages.

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. To let AI clients outside Ayakaleaf work on a project, see MCP Server.

Reading web pages is introduced from v6.4.0 and later. The chat can read a page by its URL, such as a link the user gives or a search result. It fetches the page through the linked URL proxy, the same service that fetches files from external URLs, so the network restrictions described in External URL apply to it too. No further setting is needed.

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.

Q&A

The AI assistant does not appear in the editor

Answer: The AI assistant appears in the editor’s left rail only when AI_ENABLED=true and AI_BASE_URL, AI_API_KEY and AI_MODEL are all set. If one of them is missing, the AI assistant is hidden for every user.

After changing config/variables.env, recreate the container with bin/up -d. Refreshing the browser alone does not apply new variables. The Enable AI features switch in the admin panel does not show or hide the AI assistant; it only decides whether the user can send messages.

I send a message, but the AI assistant does not reply

Answer: First, check that the user has accepted the AI consent card shown in the AI assistant. Messages cannot be sent before that.

Then look for errors in the web service log:

bin/logs web

Log message	Meaning
workbench AI chat requested but no AI gateway is configured	One of AI_ENABLED, AI_BASE_URL, AI_API_KEY or AI_MODEL is missing in the running container. Recreate it with bin/up -d.
workbench chat stream error	The gateway returned an error. The user sees “The AI service returned an error”. The logged error shows the gateway’s status code and message.
workbench chat failed	The request failed before or while streaming, for example because the gateway cannot be reached.

If your provider’s dashboard shows no usage, the request did not reach the provider. Common causes are:

• AI_BASE_URL is wrong, for example a missing or extra /v1, or /chat/completions appended to it.
• The server cannot reach the gateway. If outgoing traffic must go through a proxy, set AI_PROXY_URL.
• AI_MODEL is not a model ID that the gateway knows.

If the provider shows requests but the chat still fails, check that the model supports streaming chat completions and function tools.

Is the chat history kept?

Answer: No. A chat is only kept in the open browser tab. Refreshing or closing the page clears it, and Start new chat replaces the current chat. There is no list of earlier chats, and each project shows one chat at a time.