Data Ingestion

GamiBot synchronises File (resource) and Folder activities from a Moodle course that has its own GamiBot block. Adding the block to an existing course queues eligible content already in that course. Subsequent uploads, edits, visibility changes and removals enter the same durable, site-wide queue. A global floating button or category block alone does not enable a course.

Moodle sends notifications to the configured ingestion endpoint; the receiver handles file retrieval and indexing. In the current service, Docling processes the files, Ollama serves the nomic-text embedding model, and Qdrant holds the index. The Moodle plugin does not itself extract text, generate embeddings or guarantee a particular file format. Its delivery limits pace requests to the receiver, not the receiver's internal processing.

What is eligible

The shared course index receives content only from a visible course, section and activity that is shown on the course page and not pending deletion. Stealth activities are excluded. Content in a subsection inherits the visibility and restrictions of its parents.

The plugin evaluates date-only availability rules, including opening and closing dates. Any rule tree containing student-specific or other non-date conditions, such as groups, grades, completion or profile rules, is excluded as a whole. The sending worker rechecks eligibility before every upload. A teacher's personal access does not override these shared-index rules. The webhook is not a per-student authorisation check for retrieval.

Global queue and pacing

Moodle editing actions queue work without waiting for network requests. The Synchronise GamiBot resource availability scheduled task discovers changed eligibility and delivers queued work every minute by default. Only one sender runs at a time, even with multiple Moodle cron workers. Across all courses and simultaneous edits, the defaults are:

Basic setting	Default	Effect
Ingestion requests per cron run	5	At most five delivery steps; each step sends at most one request. Range 1–100.
Minimum ingestion request interval	5 seconds	Minimum gap between request starts, shared by all courses and workers. Range 1–3600.

A run stops starting work after 30 seconds; long intervals and large folders continue in later runs. Failed requests remain queued, fail the scheduled task visibly and retry with exponential backoff from one minute to one hour. The queue keeps a folder cursor so a large folder does not restart each run. Increase the interval or reduce the batch size if the ingestion service is overloaded.

For a changed File or Folder, Moodle sends a module deletion before replacement uploads. Removing the last course-level GamiBot block or deleting a course queues cleanup. Removal is asynchronous: previously indexed material may remain in the receiver until its deletion is processed. Check pending removals when access to material must be withdrawn.

Webhook contract

Uploads are JSON POST requests with event: "file_uploaded", the configured secret, moodle_url, course_id, section_id, section_name, module_id, module_name, file_url, filename, mimetype and filesize. The file_url is a Moodle web-service file URL; the receiver needs suitable Moodle access to retrieve the bytes.

Deletions use event: "file_deleted", secret, moodle_url, course_id and module_id. The secret is a value in the JSON body; the Moodle sender does not add an HMAC signature. The receiver should authenticate that secret, use TLS, and treat deletion of all vectors for the Moodle site, course and module as idempotent. If it has its own internal queue, it must apply a module's deletion before later uploads for that module.

Moodle acknowledges a request only after an HTTP 2xx response. That response confirms receipt, not that indexing or deletion in the receiver has finished. An empty Moodle queue therefore does not prove the remote index is current.

Reconcile and inspect

Run Moodle cron at least once per minute. From the Moodle root, an administrator can queue a specific course, queue all enabled courses, or inspect pending work:

php local/gamibot_manager/cli/sync_resources.php --courseid=42
php local/gamibot_manager/cli/sync_resources.php --all
php local/gamibot_manager/cli/sync_resources.php --status
php local/gamibot_manager/cli/sync_resources.php --status --courseid=42

These commands queue or report work; cron sends it at the configured rate. Status includes pending modules, removals, retries and work held for a different ingestion endpoint. Changing the endpoint holds pending work for the old destination instead of sending it to the new one. Arrange cleanup at the old service or restore the old endpoint to process that work.

On upgrading an older installation whose receiver already contains vectors, arrange cleanup of the historical index for this Moodle site in the receiver, then use --all to queue current eligible files. The queue cannot discover vectors from already deleted Moodle modules. Course availability changes, cron backlog, retries and receiver processing mean there is no exact time guarantee.

See Moodle setup and test GamiBot.