Groq AI Chat Integration

Relevant source files

The following files were used as context for generating this wiki page:

• core/commands.py
• core/bot.py
• core/database.py
• core/integrations.py
• core/helpers.py
• requirements.txt

Introduction

The Groq AI Chat Integration serves as the primary intelligence engine for the GentelmeN-CorE bot. It leverages the Groq SDK to provide high-speed Large Language Model (LLM) capabilities, supporting text-based chat, voice transcription (Whisper), and context-aware responses. This integration is designed to handle multi-turn conversations by maintaining a short-term memory of user interactions and dynamically switching between different AI models based on user preference.

Sources: core/bot.py:16-17, core/commands.py:204-230

Architecture and Core Components

The system is built on a modular architecture where the Groq client is initialized at the application level and passed to command handlers. The integration spans across database management for user preferences, memory handling for conversation history, and external tool integration for real-time web searches.

System Configuration

The integration requires a GROQ_KEY environment variable to initialize the Groq client. The application fails fast if this key is missing.

Configuration	Source	Purpose
GROQ_KEY	Environment Variable	API key for authenticating with Groq Cloud
MAX_HISTORY	core/commands.py	Limit for message history (set to 40)
DEFAULT_MODEL	core/database.py	llama-3.3-70b-versatile

Sources: core/bot.py:12-21, core/commands.py:16, core/database.py:44

Data Flow for Chat Processing

When a user sends a message that does not match a specific command, it is routed to the ai_chat handler. The handler performs the following steps:

1. Retrieves user preferences (language and preferred model) from the PostgreSQL database or local cache.
2. Constructs a system message based on the user's language setting.
3. Injects real-time context if the user's query pertains to prices or news using the Brave Search integration.
4. Appends the new message to the user's conversation history.
5. Calls the Groq API to generate a completion.

The flow shows how user messages are enriched with context and history before reaching the LLM.
Sources: core/commands.py:204-230, core/database.py:41-61

Voice Integration (Whisper)

The system supports voice messages by utilizing Groq's implementation of the Whisper-large-v3 model. Voice files (.ogg) are downloaded from Telegram, saved to a temporary file, and sent to the Groq audio transcriptions API.

Transcription Logic

If the transcribed text contains specific triggers like "rysuj" (draw), the system routes the request to the image generation module. Otherwise, it forwards the text to the standard AI chat logic.

Model and Language Selection

Users can customize their AI experience through specific commands that update their profile in the database.

Supported Models

The integration supports multiple models via Groq, which can be toggled using Telegram commands:

• Llama 3.3 70B: /llama (Standard versatile model)
• Llama 3.1 8B: /fast (Instant response model)
• Qwen 2.5 32B: /qwen (Alternative model)

Sources: core/commands.py:133-145

Database Schema for AI Prefs

The users table tracks these settings to ensure consistency across sessions.

Field	Type	Description
user_id	BIGINT (PK)	Unique Telegram User ID
language	TEXT	Preferred AI language (default 'EN')
model_name	TEXT	Target Groq model identifier

Sources: core/database.py:17-25

Memory Management

Conversation context is maintained in a global dictionary user_history. Each entry is a list of JSON objects containing role and content.

• Memory Limit: History is capped at MAX_HISTORY (40 messages) to manage context window limits and token costs.
• Reset Mechanism: The /reset or /clear commands allow users to purge their conversation history manually.

Sources: core/commands.py:15-16, core/commands.py:116-121, core/commands.py:226-228

Implementation Details

Response Generation (ai_chat)

The ai_chat function is the core implementation of the Groq integration.

# core/commands.py:204-230
def ai_chat(m):
    _bot.send_chat_action(m.chat.id, 'typing')
    user_id = m.from_user.id
    user_lang, user_model = get_user_data(user_id)

    sys_msg = (
        f"Jesteś GeNCorE. Mów po polsku..." if user_lang == 'PL' 
        else f"You are GeNCorE. Speak English..."
    )

    # Optional Web Context Enrichment
    if any(w in m.text.lower() for w in ["cena", "news", "bitcoin"]):
        web_info = search_brave(m.text, count=2)
        if web_info:
            sys_msg += f"\nNet Info:\n{web_info}"

    # History handling and API call
    messages = [{"role": "system", "content": sys_msg}] + user_history[user_id]
    reply = _groq_client.chat.completions.create(
        messages=messages, 
        model=user_model
    ).choices[0].message.content

Sources: core/commands.py:204-230

Utility Functions

The inteligentna_odpowiedz (intelligent response) helper ensures that responses are sent correctly within Telegram threads and supports Markdown formatting generated by the AI.

Sources: core/helpers.py:1-15

Conclusion

The Groq AI Chat Integration provides a robust and flexible interface for LLM interactions. By combining high-performance models with database-backed persistence and external search tools, the system delivers contextually aware and personalized conversational experiences. The inclusion of Whisper-based voice support and multi-model switching makes it a versatile component of the GentelmeN-CorE architecture.