feat: add animated loading placeholder for AI response generation

[Afdaan]

Description

This Pull Request introduces a significant user experience improvement for the bot. Instead of only displaying the default "Typing..." status indicator, the bot now sends an initial quote block placeholder message containing an animated loading text while the AI response is being generated.

This approach provides immediate visual feedback to the user and creates a more responsive interaction pattern, similar to modern AI interfaces such as ChatGPT or Claude when generating longer responses.

The loading message dynamically updates its text at regular intervals until the final response is ready.

Key Features

Standard Chat and Conversations

Displays an animated loading message:

Alya is thinking...

The placeholder text updates periodically while the model generates a response.

Media and Document Analysis (!ask)

Displays an animated loading message indicating that the content is being analyzed:

Alya is analyzing the provided content...

Roast Mode (!roast and !gitroast)

Displays an animated loading message before generating the roast response:

Alya is preparing a roast...

Voice Messages (TTS)

For voice responses, a loading message is displayed while the text-to-speech process runs:

Alya is recording a voice note...

The loading message is automatically deleted immediately before the generated voice message is sent by the Alya-TTS microservice.

Technical Changes and Refactoring

To comply with the project Code Standards and follow DRY and Single Responsibility principles, several structural improvements were implemented.

Centralized Animation Helper

All duplicated animation loops previously implemented inside individual handlers have been extracted into a shared helper function:

start_loading_animation()

Location:

utils/telegram_helpers.py

This centralization ensures consistent behavior across handlers and simplifies maintenance.

Garbage Collection Protection for Background Tasks

A global set named:

_active_animations

is used to maintain a strong reference to running asyncio animation tasks. Without this reference, Python’s garbage collector could prematurely terminate background tasks when new events arrive during the loading phase.

This ensures animation tasks remain active until explicitly cancelled.

Telegram Rate Limit Handling

The animation task now handles Telegram Flood Limit responses. When a rate limit occurs, the task reads the Retry-After value returned by the Telegram API and dynamically adjusts the animation interval to prevent repeated API violations.

TTS Microservice Payload Support

The TTS request payload now includes the following field:

loading_message_id

This allows the external Alya-TTS FastAPI microservice to directly delete the loading placeholder message before sending the final send_voice response.

This ensures the user only sees the final voice message without any intermediate loading artifacts.

Files Modified

• handlers/conversation.py
• handlers/voice.py
• utils/analyze.py
• utils/roast.py
• utils/telegram_helpers.py
• utils/tts_queue.py

Deployment Notes

The external Alya-TTS Microservice requires a manual restart to apply the updated FastAPI payload schema.