> ## Documentation Index
> Fetch the complete documentation index at: https://ayakaleaf-pro.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# AI Integration

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

> [!NOTE]
>
> This feature is provided by [ayaka-notes/ayakaleaf-pro](https://github.com/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.

![](https://mintcdn.com/ayakaleaf-pro/UZ_4Jfz7cU6MnXtE/images/on-premises/image-49.png?fit=max\&auto=format\&n=UZ_4Jfz7cU6MnXtE\&q=85\&s=609d6a28104dfb16264790c00123eeb4)

### 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:

```dotenv theme={null}
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.

> [!NOTE]
>
> 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](https://github.com/router-for-me/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:

```sh theme={null}
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:

```dotenv theme={null}
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.

![](https://mintcdn.com/ayakaleaf-pro/x9kfDjtWlyyhG_mR/images/on-premises/img-2f5a5399.png?fit=max\&auto=format\&n=x9kfDjtWlyyhG_mR\&q=85\&s=3c52c12aa1551cda22f218ec2dfda63b)

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:

```dotenv theme={null}
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](https://ayakaleaf-pro.mintlify.site/on-premises/configuration/overleaf-toolkit/integrations/mcp-server.md).

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](https://ayakaleaf-pro.mintlify.site/on-premises/configuration/overleaf-toolkit/external-url.md) 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

> [accordion] 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.

> [accordion] 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:
>
> ```sh theme={null}
> 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.

> [accordion] 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.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.