> For the complete documentation index, see [llms.txt](https://ayakaleaf-pro.ayaka.space/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://ayakaleaf-pro.ayaka.space/on-premises/configuration/overleaf-toolkit/ai-integration.md).
# AI Integration
Configure AI chat, LaTeX error suggestions, user access, quotas, and optional search services.
{% hint style="info" %}
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.
{% endhint %}
## 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:
```dotenv
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.
{% hint style="info" %}
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.
{% endhint %}
`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:
```sh
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:
```dotenv
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:
```dotenv
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.
---
# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.
## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.
Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:
```
GET https://ayakaleaf-pro.ayaka.space/on-premises/configuration/overleaf-toolkit/ai-integration.md?ask=&goal=
```
`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `build a script that syncs our docs to a CMS` lets GitBook tailor the answer to that use case.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.
Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
