Optiserver

Plataforma de analítica de video basada en eventos.

Procesa flujos de cámaras IP, ejecuta algoritmos de visión computacional y genera observaciones, eventos y evidencia visual consultables.

Estado: la Etapa 0 y la Etapa 1 del rework están completas (2026-10-06). El storage global corre en su propio proceso, los nodos emiten comandos, la evidencia vive en event.snapshot_key, la API escribe por comando y el esquema está en SQLAlchemy Core + Alembic. Lo próximo es la Etapa 2 (dominio y salud). Plan en REWORK.md; bugs abiertos en docs/ops/known-bugs.md.

Requisitos

• Docker + Docker Compose — PostgreSQL y MediaMTX.
• uv — gestor de dependencias y entornos Python.
• Modelos ONNX — yolox_nano.onnx (el que usa el sistema) ya viene versionado en data/models/; ver docs/guides/modelos.md.

Inicio rápido

# 1. Sincronizar entorno Python
uv sync

# 2. Levantar infraestructura
docker compose up -d postgres mediamtx

# 3. Aplicar migraciones
uv run alembic upgrade head

# 4. Iniciar el sistema
uv run optiserver

El servidor queda en http://localhost:8000 (API en /api/v1, dashboard en /).

Registrar una cámara

curl -X POST http://localhost:8000/api/v1/cameras \
  -H "Content-Type: application/json" \
  -d '{"name": "Entrada", "rtsp_url": "rtsp://localhost:8554/cam-test"}'

⚠️ Registrar una cámara no activa ningún análisis. El pipeline por defecto es solo camera_worker: decodifica frames y los descarta. Hay que configurarle el pipeline con PUT /api/v1/cameras/{id}/pipeline. Ver docs/reference/nodos.md.

Probar con un video en vez de una cámara

# Publicar un video propio en MediaMTX, en bucle
ffmpeg -re -stream_loop -1 -i /ruta/a/tu/video.mp4 -c copy \
  -rtsp_transport tcp -f rtsp rtsp://localhost:8554/cam-test

Después, apuntar la cámara a rtsp://localhost:8554/cam-test y configurarle el pipeline. Detalle en docs/guides/quickstart.md.

No hay video de ejemplo versionado: el proyecto no depende de un archivo de muestra. Para ver la cadena completa sin ningún asset alcanza uv run playground --chain events --source synthetic --extractor yolo_detector --simulated.

Estructura

optiserver/
├── src/optiserver/
│   ├── api/              # API REST: cámaras y pipelines + health
│   ├── supervisor/       # Supervisor + Pipeline (un proceso por nodo)
│   ├── nodes/            # Los 6 nodos, mensajes IPC, registry y validador de DAG
│   ├── storage/          # Esquema (tables.py), motor, repositorio y storage
│   ├── dashboard/        # Vistas Jinja2 + estáticos
│   └── tools/            # CLIs: test-detector, infer-image, playground
├── alembic.ini           # Config de Alembic (el DSN sale de la app)
├── migrations/           # Migraciones Alembic
├── docs/                 # Documentación (empezar por docs/README.md)
├── tests/unit/           # 256 tests unitarios
├── tests/integration/    # 9 tests de integración (portón offline, storage como proceso, dashboard, reinicio dirigido)
├── REWORK.md             # Plan de rework vigente
└── uv.lock               # Lockfile versionado (lo usa el Dockerfile)

Desarrollo

uv run pytest                          # 265 tests, ~14 s (necesita PostgreSQL)
uv run optiserver                      # sistema completo
uv run playground --help               # experimentar con nodos aislados
uv run test-detector --help            # probar un extractor contra un RTSP
uv run infer-image --help              # inferencia sobre una imagen suelta

Guía de experimentación: docs/guides/experimentos.md.

Documentación

Empezar por docs/README.md. Orden sugerido: visión → arquitectura → modelo de datos → nodos → rework.