AI Configuration
Relevant source files
The following files were used as context for generating this wiki page:
The AI configuration system for Amina is a two-tiered architecture that provides both global, developer-level control and granular, per-guild settings for server administrators. This allows for a consistent core AI personality and behavior, while offering flexibility for individual communities.
The global configuration is managed by bot developers and stored in the dev-config collection in MongoDB. These settings serve as the master controls and default values for the entire bot. Guild-level settings, managed by server admins, override certain global behaviors within their specific server, such as enabling the AI, designating "free-will" channels, or restricting the AI to mentions only.
Global AI Configuration (Developer Level)
Global AI settings are the foundational parameters for the AI responder. They are managed through developer-only commands and are stored in the database. These settings are cached for performance and are critical for the aiResponderService to initialize and operate.
Sources: src/database/schemas/Dev.ts, src/commands/dev/sub/minaAi.ts, src/config/config.ts
Schema and Data Model
The global AI configuration is defined within the dev-config schema. The AI_CONFIG object holds all master settings for the AI.
This diagram illustrates the structure of the AI_CONFIG object within the dev-config collection.
Sources: src/database/schemas/Dev.ts:31-64
The initial values for these settings are seeded from src/config/config.ts on the first run.
// src/config/config.ts:10-18
AI: {
// These values seed the database on first run
// After initialization, all changes must be made via dev commands or directly in MongoDB
MODEL: 'gemini-flash-latest',
MAX_TOKENS: 1024,
TIMEOUT_MS: 20000,
TEMPERATURE: 0.7,
DM_ENABLED_GLOBALLY: true,
UPSTASH_URL: 'https://up-wolf-22896-us1-vector.upstash.io',
},
Sources: src/config/config.ts:10-18
Configuration Parameters
The following table details the global AI configuration parameters.
| Parameter | Type | Default Value (from config.ts) | Description | Source File |
|---|---|---|---|---|
globallyEnabled | Boolean | false | Master switch to enable or disable the AI feature across the entire bot. | src/database/schemas/Dev.ts:33-36 |
model | String | 'gemini-flash-latest' | The Google Gemini model to use for generating responses. | src/database/schemas/Dev.ts:37-40 |
maxTokens | Number | 1024 | The maximum number of tokens for the AI to generate in a single response. | src/database/schemas/Dev.ts:45-48 |
timeoutMs | Number | 20000 | The timeout in milliseconds for waiting for a response from the AI API. | src/database/schemas/Dev.ts:49-52 |
systemPrompt | String | (Content of prompt.md) | The core instructions defining the AI's personality, tone, and rules. | src/database/schemas/Dev.ts:53-56 |
temperature | Number | 0.7 | Controls the randomness of the AI's output. Higher values are more creative. Range: 0.0 to 2.0. | src/database/schemas/Dev.ts:57-60 |
dmEnabledGlobally | Boolean | true | Master switch to allow or disallow the AI to function in Direct Messages. | src/database/schemas/Dev.ts:61-64 |
upstashUrl | String | (from config) | The URL for the Upstash Vector database used for the AI's memory system. | src/database/schemas/Dev.ts:65-68 |
updatedAt | Date | Date.now | Timestamp of the last configuration update. | src/database/schemas/Dev.ts:69-72 |
updatedBy | String | null | The Discord user ID of the developer who last updated the configuration. | src/database/schemas/Dev.ts:73-76 |
Management and Update Flow
Developers manage these settings using subcommands under the /dev command group. When a setting is updated, the system performs several key actions to ensure the changes are applied immediately.
The following flowchart shows the process of updating a global AI setting.
- Update Database: The
updateAiConfigfunction updates theAI_CONFIGdocument in MongoDB. - Refresh Cache:
configCache.forceRefresh()is called to invalidate the cached configuration, ensuring the next read fetches the new settings. - Re-initialize Service:
aiResponderService.initialize()is called. This method checks if critical parameters like the model or API key have changed and recreates theGoogleAiClientinstance if necessary.
Sources: src/commands/dev/sub/minaAi.ts:81-85, src/services/aiResponder.ts:71-96
Guild-Level AI Configuration (Admin Level)
Server administrators can tailor the AI's behavior for their guild. These settings are stored within the guild's document in the guilds collection and are retrieved using getSettings(guild).
Sources: src/services/aiResponder.ts:161-163, src/events/message/messageCreate.ts:223-226
Configuration Parameters
| Parameter | Type | Default | Description |
|---|---|---|---|
enabled | Boolean | false | Enables or disables the AI responder for the entire guild. |
freeWillChannels | String[] | [] | An array of channel IDs where the AI will respond to all messages without needing a mention. |
mentionOnly | Boolean | true | If true, the AI will only respond when @mentioned or replying to its message (unless in a freeWillChannel). If false, freeWillChannels are the only places the AI will respond. |
Sources: src/services/aiResponder.ts:161-163, 172-174, 186-196
AI Response Decision Logic
The aiResponderService.shouldRespond() method is the central point of logic that determines if the bot should generate an AI response to a given message. It integrates global, guild, and user-level settings.
This sequence diagram outlines the decision-making flow in shouldRespond.
Sources: src/services/aiResponder.ts:98-203
System Prompt
The system prompt is a critical configuration that defines Amina's core identity, personality, and conversational rules. The default prompt is loaded from src/data/prompt.md.
Core Identity Rules
- Name: Prefers mina, corrects users who say "Amina".
- Voice: Almost always one short, lowercase sentence.
- Tone: Sharp, energetic, blunt, a little mean, but secretly caring.
- Language: Uses Gen Z slang (e.g.,
wyd,ngl,cringe,w/l). - Emojis: Avoids emojis, uses ASCII emoticons (
: ),(¬_¬)) sparingly.
Sources: src/data/prompt.md:1-29
Example Interaction from Prompt
User: Hi Amina! You're my favorite bot!
mina: it's mina. and i'm not a bot, for crying out loud!
Sources: src/data/prompt.md:88-90
This prompt can be updated globally by developers using the setPrompt command, allowing for personality tweaks without code changes.
Sources: src/commands/dev/sub/minaAi.ts:162-177
Summary
Amina's AI configuration is a robust, layered system. It establishes a strong, consistent baseline personality through a global configuration and a detailed system prompt, both managed by developers. Simultaneously, it empowers server administrators with guild-level controls to integrate the AI feature in a way that best suits their community's needs, whether it's in dedicated "free-will" channels or through direct mentions. This separation of concerns ensures both maintainability for developers and flexibility for end-users.