Background Workers & Cloud Tasks
Relevant source files
The following files were used as context for generating this wiki page:
The Omi ecosystem utilizes a distributed architecture for handling long-running, asynchronous, and scheduled operations through background workers and cloud task queues. This system ensures that the primary user-facing services, such as the REST API and real-time audio processing, remain responsive by offloading computationally expensive or time-sensitive lifecycle tasks to dedicated workers.
The architecture primarily relies on Google Cloud Run for hosting the backend-sync service, which processes jobs dispatched via Google Cloud Tasks. These tasks handle a variety of operations ranging from local file synchronization and audio merging to proactive task extraction and notification dispatching.
Sources: AGENTS.md:120-136, README.md:100-115
Architecture and Data Flow
The background task system is divided into synchronous execution for immediate needs and asynchronous job queues for scalable processing.
Cloud Task Dispatching
The backend-sync service uses Cloud Tasks to manage and execute jobs. When SYNC_DISPATCH_MODE is set to cloud_tasks, the system stages raw audio in Google Cloud Storage (GCS) and enqueues jobs to specific queues.
The diagram shows the logic path for dispatching jobs to background workers via Cloud Tasks versus inline execution.
Sources: AGENTS.md:120-128, backend/utils/cloud_tasks.py
Key Task Queues
| Queue Name | Service Endpoint | Purpose |
|---|---|---|
sync-jobs | /v2/sync-jobs/run | Handles decode, Voice Activity Detection (VAD), and Speech-to-Text (STT) for local files. |
audio-merge | /v2/audio-merge-jobs/run | Builds 30-day MP3 artifacts for playback. |
notifications-job | modal/job.py | Cron-based job for sending push notifications via Firestore/Redis. |
agent-vm-reaper | backend/charts/agent-vm-reaper | Cron-based cleanup of stale GCE VMs from desktop agent sandboxes. |
Sources: AGENTS.md:106-110, AGENTS.md:120-128
Desktop Proactive Workers
The macOS desktop application implements local background workers using the TaskAssistant. This worker monitors screen content and conversation context to proactively identify and extract tasks.
Task Extraction Lifecycle
The TaskAssistant actor operates as an event-driven background worker. It utilizes two main triggers:
- Context Switch: Triggered when a user switches between applications or windows.
- Timer Fallback: A safety-net timer that fires after a configurable
extractionInterval(defaulting to 10 minutes) if no context switch has occurred.
This diagram illustrates the event-driven lifecycle of the desktop background task extractor.
Sources: desktop/macos/Desktop/Sources/ProactiveAssistants/Assistants/TaskExtraction/TaskAssistant.swift:108-160, desktop/macos/Desktop/Sources/ProactiveAssistants/Assistants/TaskExtraction/TaskAssistantSettings.swift:125-130
Configuration Parameters
| Parameter | Type | Default | Description |
|---|---|---|---|
extractionInterval | TimeInterval | 600.0s | Frequency of fallback analysis in the absence of app switches. |
minConfidence | Double | 0.75 | The minimum AI confidence score required to save an extracted task. |
allowedApps | Set | (Whitelist) | List of applications permitted for background screen analysis. |
Backend Lifecycle Workers
Backend workers manage the persistence and cleanup of temporary data. The short_term_lifecycle_worker.py (referenced in development guides) is responsible for handling high-risk workflows such as retries, idempotency, and side-effect fanout.
Executor Pooling
To prevent blocking the asyncio event loop in Python-based workers, blocking calls are offloaded to specific thread pools:
db_executor: Used for Firestore and Redis CRUD operations.storage_executor: Used for Google Cloud Storage (GCS) and file I/O operations.postprocess_executor: Used for coordinators and general background processing.
Sources: AGENTS.md:40-52, backend/jobs/short_term_lifecycle_worker.py
Summary
Background workers and Cloud Tasks form the backbone of Omi's asynchronous processing. By separating real-time audio ingestion from intensive tasks like audio merging, STT synchronization, and proactive screen analysis, the system maintains high performance across desktop and mobile platforms. The use of specialized executors in the backend and event-driven actors on the desktop ensures that background work is performed efficiently without degrading the user experience.