feat(realtime): poll HTTP telemetry sources and publish vehicle positions

.env.dev

@@ -3,4 +3,13 @@ DEBUG=True
 DJANGO_SERVE_STATIC=True
 LOG_LEVEL=DEBUG
 CREATE_SUPERUSER=True
-RUN_MIGRATIONS=True
+RUN_MIGRATIONS=True
+
+# MQTT Configuration
+MQTT_HOST=telemetry-broker
+MQTT_PORT=1883
+
+# ETA model registry (dev default; seed once with seed_baseline_model)
+MODEL_REGISTRY_DIR=eta_models
+ETA_MAX_STOPS=10
+ETA_DEFAULT_UNCERTAINTY_S=120

.env.example

@@ -25,6 +25,10 @@ REDIS_PASSWORD=redispassword
 # Google Maps API Key
 API_TOKEN=
 
+# MQTT Configuration
+MQTT_HOST=telemetry-broker
+MQTT_PORT=1883
+
 # HiveMQ Configuration
 HIVEMQ_LOG_LEVEL=INFO
 
@@ -54,4 +58,10 @@ FLOWER_DOMAIN=tasks.databus.simovilab.com
 DOCS_DOMAIN=docs.databus.simovilab.com
 
 # Certificate in production
-CERT_RESOLVER=letsencrypt
+CERT_RESOLVER=letsencrypt
+
+# ETA model registry (used by gtfs_eta; set to a writable directory)
+# Seed the baseline model once: MODEL_REGISTRY_DIR=eta_models ./.venv/bin/python -m gtfs_eta.seed_baseline_model
+MODEL_REGISTRY_DIR=eta_models
+ETA_MAX_STOPS=3
+ETA_DEFAULT_UNCERTAINTY_S=120

backend/databus/celery.py

@@ -50,4 +50,8 @@ def debug_task(self):
         "task": "realtime_engine.tasks.scan_stale_runs",
         "schedule": timedelta(seconds=30),
     },
+    "fetch-positions": {
+        "task": "realtime_engine.tasks.fetch_positions",
+        "schedule": timedelta(seconds=10),
+    },
 }

backend/docker-entrypoint.sh

@@ -196,7 +196,7 @@ wait_for_database() {
 
 run_makemigrations() {
     if is_true "${DEBUG:-False}"; then
-        APPS_TO_MIGRATE=("feed" "schedule_engine" "realtime_engine")
+        APPS_TO_MIGRATE=("feed" "schedule_engine" "realtime_engine" "operations")
         log "Creating migrations for: ${APPS_TO_MIGRATE[*]}"
         uv run python manage.py makemigrations "${APPS_TO_MIGRATE[@]}" || warn "No changes detected for migrations"
     else

backend/eta_models/polyreg_distance_global_baseline_v0_meta.json

@@ -0,0 +1,16 @@
+{
+  "model_type": "polyreg_distance",
+  "route_id": null,
+  "route_specific": false,
+  "degree": 1,
+  "alpha": 1.0,
+  "dataset": "synthetic_constant_speed",
+  "n_samples": 1000,
+  "metrics": {
+    "test_mae_seconds": 30.0,
+    "test_mae_minutes": 0.5
+  },
+  "model_key": "polyreg_distance_global_baseline_v0",
+  "saved_at": "2026-06-25T18:06:35.423137",
+  "model_path": "polyreg_distance_global_baseline_v0.pkl"
+}

backend/eta_models/registry.json

@@ -0,0 +1,10 @@
+{
+  "polyreg_distance_global_baseline_v0": {
+    "model_path": "polyreg_distance_global_baseline_v0.pkl",
+    "meta_path": "polyreg_distance_global_baseline_v0_meta.json",
+    "saved_at": "2026-06-25T18:06:35.423137",
+    "model_type": "polyreg_distance",
+    "route_id": null,
+    "dataset": "synthetic_constant_speed"
+  }
+}

backend/gtfs-eta/README.md

@@ -0,0 +1,34 @@
+# gtfs_eta
+
+Inference-only ETA library: given a vehicle position and the upcoming stops on
+its trip, predict arrival times from trained models stored in a model registry.
+
+This is the **consumption half** of the ETA model lifecycle. It is consumed by
+databus (`runs/domain/progression/stop_times.py`) to populate the
+`run:<id>:stop_time_updates` projection that backs the GTFS-RT trip-updates feed.
+
+## Provenance & intent
+
+- **Vendored, not original.** The canonical source — including model training —
+  lives in `gtfs-django` (`feature/eta_prediction`). This package is the slimmed
+  inference half: estimator, feature engineering, and the model registry loader,
+  with heavy training/serving deps dropped (`xgboost` is an optional extra).
+- **Candidate for extraction.** It is namespaced (`gtfs_eta.*`) and databus
+  depends on it through a single narrow seam (a lazy import in `stop_times.py`
+  plus the workspace dependency). If a second consumer appears, or it needs an
+  independent release cadence, it should move to its own package/repo — pulled
+  the same way `gtfs-io` and `gtfs-django` are — and the move stays mechanical.
+  Keep the databus → `gtfs_eta` seam narrow to preserve that.
+
+## Model registry
+
+Models are loaded from `MODEL_REGISTRY_DIR` (a `registry.json` index plus per-model
+`*.pkl` / `*_meta.json`). Paths are resolved **relative to the registry directory**,
+so the registry is relocatable: bind-mount it anywhere, check a placeholder into
+version control, or have an external retraining suite write into it.
+
+A deterministic placeholder global baseline can be (re)generated with:
+
+```bash
+MODEL_REGISTRY_DIR=eta_models python -m gtfs_eta.seed_baseline_model
+```

backend/gtfs-eta/gtfs_eta/__init__.py

@@ -0,0 +1,2 @@
+"""gtfs_eta — namespaced ETA-prediction package for the SIMOVI databus."""
+__version__ = "0.1.0"

backend/gtfs-eta/gtfs_eta/core/__init__.py

@@ -0,0 +1 @@
+# gtfs_eta.core

backend/gtfs-eta/gtfs_eta/core/config.py

@@ -0,0 +1,28 @@
+"""
+Runtime configuration for gtfs_eta.
+
+The registry dir is NOT derived from __file__ — it comes solely from the
+MODEL_REGISTRY_DIR environment variable (or the registry's own discovery
+logic).  This module only exposes the defaults that are safe to use at
+import time without side effects.
+"""
+
+# Default timezone and region for Costa Rica operations
+DEFAULT_TIMEZONE: str = "America/Costa_Rica"
+DEFAULT_REGION: str = "CR"
+
+# Weather defaults (used when no live weather feed is available)
+DEFAULT_TEMPERATURE_C: float = 25.0
+DEFAULT_PRECIPITATION_MM: float = 0.0
+DEFAULT_WIND_SPEED_KMH: float | None = None
+
+
+def get_config() -> dict:
+    """Return the active configuration as a plain dict."""
+    return {
+        "default_timezone": DEFAULT_TIMEZONE,
+        "default_region": DEFAULT_REGION,
+        "default_temperature_c": DEFAULT_TEMPERATURE_C,
+        "default_precipitation_mm": DEFAULT_PRECIPITATION_MM,
+        "default_wind_speed_kmh": DEFAULT_WIND_SPEED_KMH,
+    }

backend/gtfs-eta/gtfs_eta/core/exceptions.py

@@ -0,0 +1,13 @@
+"""Custom exceptions for gtfs_eta."""
+
+
+class GTFSEtaError(Exception):
+    """Base error for the gtfs_eta package."""
+
+
+class ModelNotFoundError(GTFSEtaError):
+    """Raised when a requested model is not in the registry."""
+
+
+class PredictionError(GTFSEtaError):
+    """Raised when a model prediction fails."""

backend/gtfs-eta/gtfs_eta/core/logging.py

@@ -0,0 +1,15 @@
+"""Logging helpers for gtfs_eta."""
+import logging
+
+
+def get_logger(name: str, level: str = "INFO") -> logging.Logger:
+    """Return a named logger with a consistent format."""
+    logger = logging.getLogger(name)
+    if not logger.handlers:
+        handler = logging.StreamHandler()
+        handler.setFormatter(
+            logging.Formatter("%(asctime)s - %(name)s - %(levelname)s - %(message)s")
+        )
+        logger.addHandler(handler)
+    logger.setLevel(getattr(logging, level.upper(), logging.INFO))
+    return logger

backend/gtfs-eta/gtfs_eta/core/validation.py

@@ -0,0 +1,15 @@
+"""Input validation helpers for gtfs_eta."""
+from typing import Any
+
+
+def require_keys(d: dict, keys: list[str], context: str = "") -> None:
+    """Raise ValueError if any key is missing from d."""
+    missing = [k for k in keys if k not in d]
+    if missing:
+        raise ValueError(f"Missing required keys {missing} in {context or 'input'}")
+
+
+def require_positive(value: Any, name: str) -> None:
+    """Raise ValueError if value is not a positive number."""
+    if value is None or float(value) <= 0:
+        raise ValueError(f"{name} must be a positive number, got {value!r}")

backend/gtfs-eta/gtfs_eta/eta_service/__init__.py

@@ -0,0 +1 @@
+# gtfs_eta.eta_service