> ## Documentation Index
> Fetch the complete documentation index at: https://docs.volvox.bot/llms.txt
> Use this file to discover all available pages before exploring further.
# AI Conversations with Neural Chat
> Neural Chat lets Discord members talk to AI with mention-aware replies, per-channel modes, quiet mode, memory, history search, and flagging.
# AI conversations (Neural Chat)
Neural Chat lets your server members interact with AI directly in Discord. Members can mention the bot, reply to it, or use channels you configure for AI responses. The dashboard stores conversation history for review.
## What it does
* **AI chat** — Members talk to the bot through mentions, replies, and configured channel modes
* **Per-channel modes** — Set channels to Off, Mention, or Vibe
* **Conversation history** — Replay, search, and review AI conversations
* **Flagging** — Flag inappropriate AI responses for review
* **Search** — Search across all conversations by keyword or member
* **Response control** — Use quiet mode, blocked channels, cooldowns, and daily budgets to keep replies under control
## Settings location
| Feature area | Dashboard location |
| ----------------------------------------------------------------------------------- | ------------------------------------------ |
| AI chat behavior, system prompt, blocked channels, and per-channel modes | **Settings -> AI & Automation -> AI Chat** |
| Classifier, response model, role filters, budgets, cooldowns, and performance knobs | **Settings -> AI & Automation -> Triage** |
| Memory retrieval depth and automatic memory extraction | **Settings -> AI & Automation -> Memory** |
## How to use
1. Enable AI chat in **Settings -> AI & Automation -> AI Chat**.
2. Set the global channel mode: **Off**, **Mention**, or **Vibe**.
3. Add per-channel overrides where you want different behavior.
4. Block any channels where AI should never respond.
5. Review conversation history under **Dashboard -> Conversations**.
6. Flag and filter conversations as needed.
AI conversations may occasionally produce unexpected responses. Use flagging to catch and review issues.
## Conversations dashboard
The **Conversations** page at `/dashboard/conversations` is the review surface for Neural Chat history. It lists AI conversations, participants, channels, status, flags, and recent activity. Opening a conversation detail page shows the replay for that thread.
Use it to search conversation history, review flagged replies, inspect context around an AI response, and decide whether a prompt or moderation setting needs tuning.
## AI chat settings
The **AI Chat** settings tab at `/dashboard/settings/ai-automation?tab=ai-chat` controls core Neural Chat behavior: enablement, model routing, system prompt, channel response mode, blocked channels, mass-ping handling, and per-channel overrides.
## Quiet mode
Quiet mode temporarily stops Neural Chat from replying in one channel. It also pauses vibe-mode triage accumulation for that channel, so the bot stays out of the conversation until quiet mode expires or a moderator turns it off.
| Command | What it does |
| ----------------------------------------- | -------------------------------------------------- |
| `/quiet on` | Quiet the current channel for the default duration |
| `/quiet on duration:1h` | Quiet the current channel for a custom duration |
| `/quiet on channel:#support duration:30m` | Quiet another channel |
| `/quiet off` | Resume AI replies in the current channel |
| `/quiet status` | Check whether quiet mode is active |
Quiet mode is per-channel, not server-wide. The default duration is 30 minutes, and durations are clamped between 1 minute and the configured maximum. By default, moderators can change quiet mode; servers can configure `quietMode.allowedRoles` for `any`, `admin`, `moderator`, or specific role IDs. Members can also mention the bot with commands like `@Volvox quiet for 30 minutes` or `@Volvox unquiet`.
## Channel modes
Set channel behavior under **Settings -> AI & Automation -> AI Chat -> Per-Channel AI Mode**.
| Mode | Behavior |
| ------- | ---------------------------------------------------------------- |
| Off | The bot does not respond in the channel |
| Mention | The bot responds to direct mentions and replies |
| Vibe | The bot watches the channel context and decides when to chime in |
The **Global Fallback Mode** applies to channels without an override. Use per-channel overrides for support, announcements, off-topic channels, or any place that needs different AI behavior.
## Configuration
| Setting | Description |
| ----------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| AI enabled | Toggle AI conversations |
| System prompt | Custom instructions for the AI |
| Per-channel AI mode | Configure Off, Mention, or Vibe behavior globally and per channel |
| Response boundaries | Select channels where AI should never respond |
| Ignore mass pings | When on (default), only direct `@Bot` mentions trigger a reply — `@everyone`, `@here`, and role pings are ignored. Turn off to let the bot respond to mass pings too. |
| Triage | Configure classifier and response models, role filters, budgets, cooldowns, and status/debug behavior |
| Output Safety Guardrail | Run a classifier on every bot triage response and block unsafe output before it reaches Discord |
| Memory | Set retrieval depth and automatic memory extraction |
| Quiet mode | Temporarily suppress AI replies in a channel |
## Memory settings
The **Memory** settings tab at `/dashboard/settings/ai-automation?tab=memory` controls how much user and channel context Neural Chat can retrieve and whether the bot extracts memories from conversations automatically.
Keep memory conservative for privacy-sensitive communities. Increase retrieval only when long-running personalized context is worth the extra latency and provider cost.
## Output safety guardrail
The Output Safety Guardrail runs a lightweight AI classifier on every triage response the bot is about to post. If the classifier flags the response as unsafe, the bot silently drops it instead of sending it to Discord. Unsafe verdicts are logged to Sentry so you can review them later.
Turn it on when you want a second pass on bot output — for example, in larger servers, communities with younger members, or anywhere a single off-tone reply is worse than no reply at all.
### When to use it
* You run a moderated community and want belt-and-suspenders coverage on AI replies.
* You've tightened your system prompt but still see occasional edge-case responses you'd rather not ship.
* You're rolling out Neural Chat to a new audience and want extra caution while you tune thresholds.
The classifier only inspects bot output. Member messages and moderation actions are unaffected.
### Enable it
1. Open **Settings -> AI & Automation -> Triage**.
2. In the **Behavior** section, toggle **Output Safety Guardrail** on.
3. Save. The bot starts classifying triage responses immediately — no restart required.
The toggle is off by default. Safety check usage is recorded in the AI usage ledger under the `safety` type so you can track its cost alongside classify, respond, and Content Safety `automod` calls.
### Operational tuning (self-hosters)
The per-server toggle controls whether the guardrail runs. Model selection and runtime behavior are set per deployment through environment variables:
```bash .env theme={null}
# Classifier model (default: z-ai:glm-5.2)
SAFETY_GUARDRAIL_MODEL=z-ai:glm-5.2
# Request timeout in milliseconds (default: 5000)
SAFETY_GUARDRAIL_TIMEOUT_MS=5000
# Maximum tokens for the classifier verdict (default: 128)
SAFETY_GUARDRAIL_MAX_TOKENS=128
# Block responses when the classifier errors or times out (default: true)
# Set to "false" to let responses through on classifier failure.
SAFETY_GUARDRAIL_FAIL_CLOSED=true
```
The default classifier model — `z-ai:glm-5.2` — requires `ZHIPU_API_KEY`. Select any chat-completion model from a provider you have credentials for. With `SAFETY_GUARDRAIL_FAIL_CLOSED=true`, the bot treats classifier timeouts and errors as unsafe and drops the response. Set it to `false` if you'd rather let responses through when the classifier is unavailable.
Managed users on volvox.bot get safe defaults — just flip the toggle. Self-hosters tune the env vars above and restart the bot.
## Search guardrails
When triage decides a prompt needs fresh or external information, Neural Chat only attaches web-search tools for providers with a verified compatible implementation. The current supported provider paths are:
| Provider | Search path |
| ---------- | ---------------------------------------------------- |
| Z.AI | Coding Plan MCP web-search server |
| OpenRouter | OpenRouter provider-exported `webSearch` server tool |
MiniMax, Moonshot, and Fireworks stay search-disabled in the provider catalog until their endpoints have a verified tool shape. If a server selects a model without search support, the prompt receives a `SEARCH_UNAVAILABLE` directive so the bot avoids pretending to have live web access.
## Available models
Every AI model dropdown in the dashboard lists only models you can actually use right now. The same filtering applies across AI Chat, Content Safety, Triage, and TL;DR settings. Two gates run before a model shows up:
* **Credential gate** — The model's provider must have an API key configured on the bot. If `OPENAI_API_KEY`, `FIREWORKS_API_KEY`, or another provider key is missing, every model from that provider is hidden.
* **Tier gate** — The model's tier must match your server's entitlement. `z-ai:glm-5.2` is the free default for every server, and the Z.AI GLM family is available on the free tier. Models marked `premium` show only for paid-tier servers.
The config API, dashboard webhook, and Discord `/config set` command enforce the same tier gate when saving model settings, so direct writes cannot assign paid-tier models to a free server. Global config writes are treated as free-tier defaults; use per-server config for paid-tier overrides.
Self-hosters grant premium model access by setting `PREMIUM_GUILD_IDS` on the bot/API process to a comma-separated list of Discord server IDs, then restarting:
```bash .env theme={null}
PREMIUM_GUILD_IDS=123456789012345678,987654321098765432
```
If your saved model is no longer available — for example, the provider key was rotated out or the model moved to premium — the dropdown still surfaces it as **Current saved model: `provider:model`**. The value stays stored so you don't lose it. When the provider has no configured key, the entry is prefixed with **⚠** and labeled **provider not configured**. At runtime, free-tier servers fall back to `z-ai:glm-5.2` instead of sending traffic to paid-tier saved models. Select any visible option to replace the saved value.
If the dropdown is empty and shows **No configured models available**, no provider has credentials configured on this deployment. Self-hosters can fix this by adding a provider key to `.env` and restarting:
```bash .env theme={null}
# Enable any one of these to populate the model dropdowns
OPENAI_API_KEY=sk-...
ANTHROPIC_API_KEY=sk-ant-...
FIREWORKS_API_KEY=fw_...
ZHIPU_API_KEY=...
```
Z.AI models (`z-ai:glm-5.2`, `z-ai:glm-5.1`, and `z-ai:glm-5-turbo`) authenticate with `ZHIPU_API_KEY` and route through the Z.AI Coding Plan endpoint at `https://api.z.ai/api/coding/paas/v4`. GLM 5.2 is the free-tier default, and GLM 5.1 plus GLM 5 Turbo are also free-tier options. These models support thinking mode, which lets the provider spend extra reasoning effort before producing the final answer. For triage, set `triage.thinkingTokens` above `0` to enable thinking, or `0` to disable it; Z.AI treats that value as an enable/disable switch.
Managed users on volvox.bot don't need to do anything — the hosted deployment keeps provider keys in place, and the dropdown reflects whichever providers are live.
### Providers API
Dashboards and integrations can read the same availability data from the bot API:
```http theme={null}
GET /api/v1/providers/configured?guildId=123456789012345678
Authorization: Bearer
```
```json Response theme={null}
{
"configuredProviders": ["z-ai"],
"guildTier": "free"
}
```
`configuredProviders` lists every provider that has an API key set and at least one visible model matching the server's tier. `guildTier` is `free` or `premium`. Pair this with the static model catalog to apply the same filtering anywhere you render a model picker.
`guildId` is required and must be a Discord snowflake. The caller must be an admin of that server — requests without the parameter are rejected with a 400, and non-admin callers receive a 403. The dashboard hook caches each server's response for 30 seconds and keeps the previous data visible during revalidation, so model pickers don't flicker when you switch config pages.