Image Generation Workflow

Relevant source files

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

• core/commands.py
• core/integrations.py
• core/helpers.py
• core/bot.py
• tests/test_commands.py

The Image Generation Workflow in the GentelmeN-CorE project is a specialized system that allows users to generate visual art directly through a Telegram interface using natural language prompts. This workflow integrates external AI models provided by Hugging Face to transform text descriptions into digital images.

The system supports two primary entry points: explicit text commands (/rysuj) and voice-to-image conversion. Once a request is received, the bot processes the prompt, communicates with the Hugging Face Inference API, and returns the generated image as a photo message to the user.

Sources: core/commands.py:207-255, core/integrations.py:27-51

System Architecture and Components

The workflow is built on a modular architecture where the Telegram bot acts as the orchestrator, and specialized integration modules handle the external API communication.

Key Components

Component	Description	Primary File
Command Handler	Parses /rysuj commands and extracts the image prompt.	core/commands.py
Voice Processor	Transcribes audio via Groq Whisper and routes "rysuj" keywords to the generation logic.	core/commands.py
Integration Layer	Manages HTTP requests to Hugging Face Inference API.	core/integrations.py
Helper Module	Provides standardized messaging and error reporting.	core/helpers.py

Sources: core/commands.py:207-255, core/integrations.py:27-51, core/helpers.py:1-15

Data Flow Diagram

The following diagram illustrates the flow from user input to image delivery.

Implementation Details

Text Command Processing

The primary entry point is the generate_image(m) function. This function uses string splitting to isolate the prompt from the command, handling cases where the bot might be addressed with a suffix (e.g., /rysuj@BotName).

def generate_image(m):
    parts = m.text.split(maxsplit=1)
    prompt = parts[1].strip() if len(parts) > 1 else ''
    if not prompt:
        return inteligentna_odpowiedz(_bot, m.chat.id, "🎨 Użyj: `/rysuj cyber cat`", m.message_thread_id)
    
    _bot.send_chat_action(m.chat.id, 'upload_photo')
    image, error = generate_image_hf(prompt)
    # ... handles response

Sources: core/commands.py:207-222

Voice-to-Image Workflow

The handle_voice(m) function extends the generation capabilities by transcribing user audio using the whisper-large-v3 model. If the resulting transcription begins with "rysuj" or "/rysuj", the system programmatically invokes the image generation logic.

External Integration (Hugging Face)

The core generation logic resides in core/integrations.py. It utilizes the black-forest-labs/FLUX.1-schnell model via the Hugging Face Inference API. The request is performed as an authenticated POST request containing the prompt as a JSON input.

API Configuration:

• Endpoint: https://api-inference.huggingface.co/models/black-forest-labs/FLUX.1-schnell
• Authentication: Bearer Token (HF_TOKEN)
• Timeout: 30 seconds

Sources: core/integrations.py:27-51

Error Handling and Validation

The workflow includes multiple layers of validation to ensure system stability:

1. Prompt Validation: If a user sends /rysuj without a description, the system returns a usage hint instead of calling the API.
2. Environment Check: The generate_image_hf function checks for the existence of HF_TOKEN. If missing, it returns a specific error message.
3. API Resilience: The system explicitly catches requests.Timeout and requests.RequestException to prevent the bot from crashing during network instability.
4. Cleanup: In the voice workflow, temporary files used for audio processing are guaranteed to be deleted via a finally block, regardless of whether the transcription succeeded.

Sources: core/commands.py:207-214, core/commands.py:253-255, core/integrations.py:29-51, tests/test_commands.py:317-340

Testing Coverage

Unit tests for this workflow verify that:

• Prompts are correctly extracted regardless of bot suffixes.
• Empty prompts trigger the correct usage message.
• The system handles Hugging Face server errors (e.g., 503 Service Unavailable).
• The system handles network timeouts gracefully.

Sources: tests/test_commands.py:231-267, tests/test_commands.py:380-410