theus-cli 0.2.83 → 0.2.84

package/vendor/theus-arsenal/skills/videodb/reference/capture-reference.md

@@ -1,407 +0,0 @@
-# Referencia de captura
-
-Detalles a nivel de código para las sesiones de captura de VideoDB. Para la guía de flujo, ver [capture.md](capture.md).
-
----
-
-## Eventos WebSocket
-
-Eventos en tiempo real de las sesiones de captura y los pipelines de IA. Sin webhooks ni sondeo.
-
-Usa [scripts/ws_listener.py](../scripts/ws_listener.py) para conectarte y volcar los eventos en `${VIDEODB_EVENTS_DIR:-$HOME/.theus/arsenal/videodb}/videodb_events.jsonl`.
-
-### Canales de eventos
-
-| Canal | Origen | Contenido |
-|-------|--------|-----------|
-| `capture_session` | Ciclo de vida de la sesión | Cambios de estado |
-| `transcript` | `start_transcript()` | Voz a texto |
-| `visual_index` / `scene_index` | `index_visuals()` | Análisis visual |
-| `audio_index` | `index_audio()` | Análisis de audio |
-| `alert` | `create_alert()` | Notificaciones de alertas |
-
-### Eventos del ciclo de vida de la sesión
-
-| Evento | Estado | Datos clave |
-|--------|--------|-------------|
-| `capture_session.created` | `created` | — |
-| `capture_session.starting` | `starting` | — |
-| `capture_session.active` | `active` | `rtstreams[]` |
-| `capture_session.stopping` | `stopping` | — |
-| `capture_session.stopped` | `stopped` | — |
-| `capture_session.exported` | `exported` | `exported_video_id`, `stream_url`, `player_url` |
-| `capture_session.failed` | `failed` | `error` |
-
-### Estructuras de eventos
-
-**Evento de transcripción:**
-```json
-{
-  "channel": "transcript",
-  "rtstream_id": "rts-xxx",
-  "rtstream_name": "mic:default",
-  "data": {
-    "text": "Agendemos la reunión para el jueves",
-    "is_final": true,
-    "start": 1710000001234,
-    "end": 1710000002345
-  }
-}
-```
-
-**Evento de índice visual:**
-```json
-{
-  "channel": "visual_index",
-  "rtstream_id": "rts-xxx",
-  "rtstream_name": "display:1",
-  "data": {
-    "text": "El usuario está viendo una conversación de Slack con 3 mensajes sin leer",
-    "start": 1710000012340,
-    "end": 1710000018900
-  }
-}
-```
-
-**Evento de índice de audio:**
-```json
-{
-  "channel": "audio_index",
-  "rtstream_id": "rts-xxx",
-  "rtstream_name": "mic:default",
-  "data": {
-    "text": "Discusión sobre agendar una reunión de equipo",
-    "start": 1710000021500,
-    "end": 1710000029200
-  }
-}
-```
-
-**Evento de sesión activa:**
-```json
-{
-  "event": "capture_session.active",
-  "capture_session_id": "cap-xxx",
-  "status": "active",
-  "data": {
-    "rtstreams": [
-      { "rtstream_id": "rts-1", "name": "mic:default", "media_types": ["audio"] },
-      { "rtstream_id": "rts-2", "name": "system_audio:default", "media_types": ["audio"] },
-      { "rtstream_id": "rts-3", "name": "display:1", "media_types": ["video"] }
-    ]
-  }
-}
-```
-
-**Evento de sesión exportada:**
-```json
-{
-  "event": "capture_session.exported",
-  "capture_session_id": "cap-xxx",
-  "status": "exported",
-  "data": {
-    "exported_video_id": "v_xyz789",
-    "stream_url": "https://stream.videodb.io/...",
-    "player_url": "https://console.videodb.io/player?url=..."
-  }
-}
-```
-
-> Para los detalles más recientes, ver la [documentación de Realtime Context de VideoDB](https://docs.videodb.io/pages/ingest/capture-sdks/realtime-context.md).
-
----
-
-## Persistencia de eventos
-
-Usa `ws_listener.py` para volcar todos los eventos WebSocket a un archivo JSONL para análisis posterior.
-
-### Iniciar el listener y obtener el ID del WebSocket
-
-```bash
-# Inicia con --clear para limpiar los eventos antiguos (recomendado en sesiones nuevas)
-python scripts/ws_listener.py --clear &
-
-# Añade a los eventos existentes (para reconexiones)
-python scripts/ws_listener.py &
-```
-
-O especifica un directorio de salida propio:
-
-```bash
-python scripts/ws_listener.py --clear /ruta/a/salida &
-# O vía variable de entorno:
-VIDEODB_EVENTS_DIR=/ruta/a/salida python scripts/ws_listener.py --clear &
-```
-
-El script imprime `WS_ID=<connection_id>` en la primera línea y luego escucha indefinidamente.
-
-**Obtener el ws_id:**
-```bash
-cat "${VIDEODB_EVENTS_DIR:-$HOME/.theus/arsenal/videodb}/videodb_ws_id"
-```
-
-**Detener el listener:**
-```bash
-kill "$(cat "${VIDEODB_EVENTS_DIR:-$HOME/.theus/arsenal/videodb}/videodb_ws_pid")"
-```
-
-**Funciones que aceptan `ws_connection_id`:**
-
-| Función | Propósito |
-|---------|-----------|
-| `conn.create_capture_session()` | Eventos del ciclo de vida de la sesión |
-| Métodos de RTStream | Ver [rtstream-reference.md](rtstream-reference.md) |
-
-**Archivos de salida** (en el directorio de salida, por defecto `~/.theus/arsenal/videodb`):
-- `videodb_ws_id` - ID de la conexión WebSocket
-- `videodb_events.jsonl` - Todos los eventos
-- `videodb_ws_pid` - PID del proceso para terminarlo fácilmente
-
-**Características:**
-- Flag `--clear` para limpiar el archivo de eventos al iniciar (úsalo en sesiones nuevas)
-- Reconexión automática con backoff exponencial ante caídas de conexión
-- Apagado limpio con SIGINT/SIGTERM
-- Registro del estado de la conexión
-
-### Formato JSONL
-
-Cada línea es un objeto JSON con marcas de tiempo añadidas:
-
-```json
-{"ts": "2026-03-02T10:15:30.123Z", "unix_ts": 1772446530.123, "channel": "visual_index", "data": {"text": "..."}}
-{"ts": "2026-03-02T10:15:31.456Z", "unix_ts": 1772446531.456, "event": "capture_session.active", "capture_session_id": "cap-xxx"}
-```
-
-### Leer eventos
-
-```python
-import json
-import time
-from pathlib import Path
-
-events_path = Path.home() / ".theus" / "arsenal" / "videodb" / "videodb_events.jsonl"
-transcripts = []
-recent = []
-visual = []
-
-cutoff = time.time() - 600
-with events_path.open(encoding="utf-8") as handle:
-    for line in handle:
-        event = json.loads(line)
-        if event.get("channel") == "transcript":
-            transcripts.append(event)
-        if event.get("unix_ts", 0) > cutoff:
-            recent.append(event)
-        if (
-            event.get("channel") == "visual_index"
-            and "code" in event.get("data", {}).get("text", "").lower()
-        ):
-            visual.append(event)
-```
-
----
-
-## Conexión WebSocket
-
-Conéctate para recibir resultados de IA en tiempo real de los pipelines de transcripción e indexación.
-
-```python
-ws_wrapper = conn.connect_websocket()
-ws = await ws_wrapper.connect()
-ws_id = ws.connection_id
-```
-
-| Propiedad / Método | Tipo | Descripción |
-|--------------------|------|-------------|
-| `ws.connection_id` | `str` | ID único de la conexión (pásalo a los métodos de pipelines de IA) |
-| `ws.receive()` | `AsyncIterator[dict]` | Iterador asíncrono que produce mensajes en tiempo real |
-
----
-
-## CaptureSession
-
-### Métodos de Connection
-
-| Método | Devuelve | Descripción |
-|--------|----------|-------------|
-| `conn.create_capture_session(end_user_id, collection_id, ws_connection_id, metadata)` | `CaptureSession` | Crea una sesión de captura nueva |
-| `conn.get_capture_session(capture_session_id)` | `CaptureSession` | Recupera una sesión de captura existente |
-| `conn.generate_client_token()` | `str` | Genera un token de autenticación del lado cliente |
-
-### Crear una sesión de captura
-
-```python
-from pathlib import Path
-
-ws_id = (Path.home() / ".theus" / "arsenal" / "videodb" / "videodb_ws_id").read_text().strip()
-
-session = conn.create_capture_session(
-    end_user_id="usuario-123",  # obligatorio
-    collection_id="default",
-    ws_connection_id=ws_id,
-    metadata={"app": "mi-app"},
-)
-print(f"ID de sesión: {session.id}")
-```
-
-> **Nota:** `end_user_id` es obligatorio e identifica al usuario que inicia la captura. Para pruebas o demos, sirve cualquier identificador único (p. ej. `"demo-user"`, `"test-123"`).
-
-### Propiedades de CaptureSession
-
-| Propiedad | Tipo | Descripción |
-|-----------|------|-------------|
-| `session.id` | `str` | ID único de la sesión de captura |
-
-### Métodos de CaptureSession
-
-| Método | Devuelve | Descripción |
-|--------|----------|-------------|
-| `session.get_rtstream(type)` | `list[RTStream]` | Obtiene los RTStreams por tipo: `"mic"`, `"screen"` o `"system_audio"` |
-
-### Generar un token de cliente
-
-```python
-token = conn.generate_client_token()
-```
-
----
-
-## CaptureClient
-
-El cliente corre en la máquina del usuario y maneja permisos, descubrimiento de canales y streaming.
-
-```python
-from videodb.capture import CaptureClient
-
-client = CaptureClient(client_token=token)
-```
-
-### Métodos de CaptureClient
-
-| Método | Devuelve | Descripción |
-|--------|----------|-------------|
-| `await client.request_permission(type)` | `None` | Solicita permiso del dispositivo (`"microphone"`, `"screen_capture"`) |
-| `await client.list_channels()` | `Channels` | Descubre los canales de audio/video disponibles |
-| `await client.start_capture_session(capture_session_id, channels, primary_video_channel_id)` | `None` | Inicia el streaming de los canales seleccionados |
-| `await client.stop_capture()` | `None` | Detiene la sesión de captura de forma ordenada |
-| `await client.shutdown()` | `None` | Libera los recursos del cliente |
-
-### Solicitar permisos
-
-```python
-await client.request_permission("microphone")
-await client.request_permission("screen_capture")
-```
-
-### Iniciar una sesión
-
-```python
-selected_channels = [c for c in [mic, display, system_audio] if c]
-await client.start_capture_session(
-    capture_session_id=session.id,
-    channels=selected_channels,
-    primary_video_channel_id=display.id if display else None,
-)
-```
-
-### Detener una sesión
-
-```python
-await client.stop_capture()
-await client.shutdown()
-```
-
----
-
-## Canales
-
-Devueltos por `client.list_channels()`. Agrupa los dispositivos disponibles por tipo.
-
-```python
-channels = await client.list_channels()
-for ch in channels.all():
-    print(f"  {ch.id} ({ch.type}): {ch.name}")
-
-mic = channels.mics.default
-display = channels.displays.default
-system_audio = channels.system_audio.default
-```
-
-### Grupos de canales
-
-| Propiedad | Tipo | Descripción |
-|-----------|------|-------------|
-| `channels.mics` | `ChannelGroup` | Micrófonos disponibles |
-| `channels.displays` | `ChannelGroup` | Pantallas disponibles |
-| `channels.system_audio` | `ChannelGroup` | Fuentes de audio del sistema disponibles |
-
-### Métodos y propiedades de ChannelGroup
-
-| Miembro | Tipo | Descripción |
-|---------|------|-------------|
-| `group.default` | `Channel` | Canal por defecto del grupo (o `None`) |
-| `group.all()` | `list[Channel]` | Todos los canales del grupo |
-
-### Propiedades de Channel
-
-| Propiedad | Tipo | Descripción |
-|-----------|------|-------------|
-| `ch.id` | `str` | ID único del canal |
-| `ch.type` | `str` | Tipo de canal (`"mic"`, `"display"`, `"system_audio"`) |
-| `ch.name` | `str` | Nombre legible del canal |
-| `ch.store` | `bool` | Si se persiste la grabación (ponlo en `True` para guardarla) |
-
-Sin `store = True`, los streams se procesan en tiempo real pero no se guardan.
-
----
-
-## RTStreams y pipelines de IA
-
-Con la sesión activa, recupera los objetos RTStream con `session.get_rtstream()`.
-
-Para los métodos de RTStream (indexación, transcripción, alertas, batch config), ver [rtstream-reference.md](rtstream-reference.md).
-
----
-
-## Ciclo de vida de la sesión
-
-```
-  create_capture_session()
-          │
-          v
-  ┌───────────────┐
-  │    created     │
-  └───────┬───────┘
-          │  client.start_capture_session()
-          v
-  ┌───────────────┐     WebSocket: capture_session.starting
-  │   starting     │ ──> Los canales de captura se conectan
-  └───────┬───────┘
-          │
-          v
-  ┌───────────────┐     WebSocket: capture_session.active
-  │    active      │ ──> Inicia los pipelines de IA
-  └───────┬──────────────┐
-          │              │
-          │              v
-          │      ┌───────────────┐     WebSocket: capture_session.failed
-          │      │    failed      │ ──> Inspecciona el error y reintenta la configuración
-          │      └───────────────┘
-          │      error de captura irrecuperable
-          │
-          │  client.stop_capture()
-          v
-  ┌───────────────┐     WebSocket: capture_session.stopping
-  │   stopping     │ ──> Finaliza los streams
-  └───────┬───────┘
-          │
-          v
-  ┌───────────────┐     WebSocket: capture_session.stopped
-  │   stopped      │ ──> Todos los streams finalizados
-  └───────┬───────┘
-          │  (si store=True)
-          v
-  ┌───────────────┐     WebSocket: capture_session.exported
-  │   exported     │ ──> Accede a video_id, stream_url, player_url
-  └───────────────┘
-```

package/vendor/theus-arsenal/skills/videodb/reference/capture.md

@@ -1,101 +0,0 @@
-# Guía de captura
-
-## Resumen
-
-VideoDB Capture permite grabar pantalla y audio en tiempo real con procesamiento de IA. La captura de escritorio actualmente solo funciona en **macOS**.
-
-Para detalles a nivel de código (métodos del SDK, estructuras de eventos, pipelines de IA), ver [capture-reference.md](capture-reference.md).
-
-## Inicio rápido
-
-1. **Inicia el listener WebSocket**: `python scripts/ws_listener.py --clear &`
-2. **Ejecuta el código de captura** (ver el flujo completo de captura más abajo)
-3. **Los eventos se escriben en**: `${VIDEODB_EVENTS_DIR:-$HOME/.theus/arsenal/videodb}/videodb_events.jsonl`
-
----
-
-## Flujo de captura completo
-
-No se requieren webhooks ni polling. El WebSocket entrega todos los eventos, incluido el ciclo de vida de la sesión.
-
-> **CRÍTICO:** el `CaptureClient` debe permanecer en ejecución durante toda la captura. Ejecuta el binario grabador local que envía los datos de pantalla/audio a VideoDB. Si el proceso Python que creó el `CaptureClient` termina, el binario grabador muere y la captura se detiene silenciosamente. Ejecuta siempre el código de captura como un **proceso en segundo plano de larga vida** (p. ej. `nohup python capture_script.py &`) y usa manejo de señales (`asyncio.Event` + `SIGINT`/`SIGTERM`) para mantenerlo vivo hasta que lo detengas explícitamente.
-
-1. **Inicia el listener WebSocket** en segundo plano con el flag `--clear` para limpiar eventos antiguos. Espera a que cree el archivo con el ID del WebSocket.
-
-2. **Lee el ID del WebSocket**. Este ID es necesario para la sesión de captura y los pipelines de IA.
-
-3. **Crea una sesión de captura** y genera un token de cliente para el cliente de escritorio.
-
-4. **Inicializa el CaptureClient** con el token. Solicita permisos de micrófono y captura de pantalla.
-
-5. **Lista y selecciona canales** (mic, display, system_audio). Establece `store = True` en los canales que quieras persistir como video.
-
-6. **Inicia la sesión** con los canales seleccionados.
-
-7. **Espera a que la sesión esté activa** leyendo eventos hasta ver `capture_session.active`. Este evento contiene el arreglo `rtstreams`. Guarda la info de la sesión (ID de sesión, IDs de RTStream) en un archivo (p. ej. `~/.theus/arsenal/videodb/videodb_capture_info.json`) para que otros scripts la puedan leer.
-
-8. **Mantén vivo el proceso.** Usa `asyncio.Event` con manejadores de señales para `SIGINT`/`SIGTERM` para bloquear hasta que se detenga explícitamente. Escribe un archivo PID (p. ej. `~/.theus/arsenal/videodb/videodb_capture_pid`) para poder detener el proceso luego con `kill $(cat ~/.theus/arsenal/videodb/videodb_capture_pid)`. El archivo PID debe sobrescribirse en cada ejecución para que las reejecuciones siempre tengan el PID correcto.
-
-9. **Inicia los pipelines de IA** (en un comando/script separado) sobre cada RTStream para indexación de audio e indexación visual. Lee los IDs de RTStream del archivo de info de sesión guardado.
-
-10. **Escribe la lógica de procesamiento de eventos** (en un comando/script separado) para leer eventos en tiempo real según tu caso de uso. Ejemplos:
-    - Registrar actividad de Slack cuando `visual_index` mencione "Slack"
-    - Resumir discusiones cuando lleguen eventos `audio_index`
-    - Disparar alertas cuando aparezcan palabras clave concretas en `transcript`
-    - Rastrear uso de aplicaciones a partir de las descripciones de pantalla
-
-11. **Detén la captura** al terminar — envía SIGTERM al proceso de captura. Este debe llamar a `client.stop_capture()` y `client.shutdown()` en su manejador de señales.
-
-12. **Espera la exportación** leyendo eventos hasta ver `capture_session.exported`. Este evento contiene `exported_video_id`, `stream_url` y `player_url`. Puede tardar varios segundos tras detener la captura.
-
-13. **Detén el listener WebSocket** tras recibir el evento de exportación. Usa `kill $(cat ~/.theus/arsenal/videodb/videodb_ws_pid)` para terminarlo limpiamente.
-
----
-
-## Secuencia de apagado
-
-El orden correcto de apagado es importante para asegurar que se capturen todos los eventos:
-
-1. **Detén la sesión de captura** — `client.stop_capture()` y luego `client.shutdown()`
-2. **Espera el evento de exportación** — sondea `~/.theus/arsenal/videodb/videodb_events.jsonl` buscando `capture_session.exported`
-3. **Detén el listener WebSocket** — `kill $(cat ~/.theus/arsenal/videodb/videodb_ws_pid)`
-
-NO mates el listener WebSocket antes de recibir el evento de exportación, o perderás las URLs finales del video.
-
----
-
-## Scripts
-
-| Script | Descripción |
-|--------|-------------|
-| `scripts/ws_listener.py` | Listener de eventos WebSocket (vuelca a JSONL) |
-
-### Uso de ws_listener.py
-
-```bash
-# Iniciar el listener en segundo plano (añade a los eventos existentes)
-python scripts/ws_listener.py &
-
-# Iniciar el listener con limpieza (sesión nueva, borra eventos antiguos)
-python scripts/ws_listener.py --clear &
-
-# Directorio de salida personalizado
-python scripts/ws_listener.py --clear /ruta/a/eventos &
-
-# Detener el listener
-kill $(cat ~/.theus/arsenal/videodb/videodb_ws_pid)
-```
-
-**Opciones:**
-- `--clear`: limpia el archivo de eventos antes de iniciar. Úsalo al empezar una sesión de captura nueva.
-
-**Archivos de salida:**
-- `videodb_events.jsonl` - Todos los eventos WebSocket
-- `videodb_ws_id` - ID de la conexión WebSocket (para el parámetro `ws_connection_id`)
-- `videodb_ws_pid` - PID del proceso (para detener el listener)
-
-**Características:**
-- Reconexión automática con backoff exponencial ante cortes de conexión
-- Apagado limpio con SIGINT/SIGTERM
-- Archivo PID para gestión sencilla del proceso
-- Registro del estado de la conexión