Moodle Messaging Bot

Separate message creation from Moodle delivery with a persistent queue and recovery from authenticated-session expiry. Optionally, a monitored conversation can trigger AI replies.

The service targets UFSC’s in-person Moodle installation and its CAS flow. It is not a generic connector for all Moodle installations. Without a configured conversation, it processes the existing queue and maintains the session; automatic replies require additional configuration.

bot.py organizes authentication and dispatch, reader and keep-alive workers with asyncio. HTTPX maintains the HTTP session; asyncpg accesses a queue with PENDING, SENT and FAILED states.

The reader polls the latest message in the configured conversation. When enabled, AI.py calls Gemini and places the reply into the same outgoing queue. The dispatcher splits long text into chunks before sending it through Moodle AJAX endpoints.

The relational queue preserves content and delivery status across restarts, but selecting pending messages neither locks nor claims rows for concurrent workers. The current design assumes one process per queue.

Using the web session follows the target Moodle implementation at the cost of depending on cookies, sesskey and CAS details. These consequences are inferred from the code and documented boundaries.

Review covered workers, the SQL schema and documentation. No automated suite was found in the reviewed inventory. Future tests should simulate session expiry, failure after partial delivery and concurrent messages; no login, Gemini calls or real message delivery occurred in this review.

There is no exactly-once delivery guarantee or automatic retry of FAILED rows. The reader fetches only the latest message per cycle and can miss messages in a busy conversation.

Python dependency versions are not pinned. With AI enabled, incoming text is sent to Gemini; the queue stores content, and logs can include message excerpts. The project requires authorized conversation access and environment-specific configuration.

Start with the queue schema, then follow dispatcher_loop, reader_loop and send_message in bot.py. The guide explains local configuration and session recovery.

The commands below only prepare the Python environment and check syntax. For an authorized run, the README covers PostgreSQL, environment variables and python bot.py. TEST_CONTENT can enqueue a message on every startup; leave it unset when only preparing the environment.