theus-cli 0.2.83 → 0.2.84

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

@@ -1,564 +0,0 @@
-# Referencia de RTStream
-
-Detalles a nivel de código para las operaciones de RTStream. Para la guía de flujo, ver [rtstream.md](rtstream.md).
-Para orientación de uso y elección de flujo, empieza por [../SKILL.md](../SKILL.md).
-
-Basado en [docs.videodb.io](https://docs.videodb.io/pages/ingest/live-streams/realtime-apis.md).
-
----
-
-## Métodos RTStream de Collection
-
-Métodos de `Collection` para gestionar RTStreams:
-
-| Método | Devuelve | Descripción |
-|--------|----------|-------------|
-| `coll.connect_rtstream(url, name, ...)` | `RTStream` | Crea un RTStream nuevo desde una URL RTSP/RTMP |
-| `coll.get_rtstream(id)` | `RTStream` | Obtiene un RTStream existente por ID |
-| `coll.list_rtstreams(limit, offset, status, name, ordering)` | `List[RTStream]` | Lista todos los RTStreams de la colección |
-| `coll.search(query, namespace="rtstream")` | `RTStreamSearchResult` | Busca en todos los RTStreams |
-
-### Conectar un RTStream
-
-```python
-import videodb
-
-conn = videodb.connect()
-coll = conn.get_collection()
-
-rtstream = coll.connect_rtstream(
-    url="rtmp://tu-servidor-de-stream/live/stream-key",
-    name="Mi stream en vivo",
-    media_types=["video"],  # o ["audio", "video"]
-    sample_rate=30,         # opcional
-    store=True,             # habilita el almacenamiento de la grabación para exportar
-    enable_transcript=True, # opcional
-    ws_connection_id=ws_id, # opcional, para eventos en tiempo real
-)
-```
-
-### Obtener un RTStream existente
-
-```python
-rtstream = coll.get_rtstream("rts-xxx")
-```
-
-### Listar RTStreams
-
-```python
-rtstreams = coll.list_rtstreams(
-    limit=10,
-    offset=0,
-    status="connected",  # filtro opcional
-    name="reunion",      # filtro opcional
-    ordering="-created_at",
-)
-
-for rts in rtstreams:
-    print(f"{rts.id}: {rts.name} - {rts.status}")
-```
-
-### Desde una sesión de captura
-
-Con la sesión de captura activa, recupera los objetos RTStream:
-
-```python
-session = conn.get_capture_session(session_id)
-
-mics = session.get_rtstream("mic")
-displays = session.get_rtstream("screen")
-system_audios = session.get_rtstream("system_audio")
-```
-
-O usa los datos `rtstreams` del evento WebSocket `capture_session.active`:
-
-```python
-for rts in rtstreams:
-    rtstream = coll.get_rtstream(rts["rtstream_id"])
-```
-
----
-
-## Métodos de RTStream
-
-| Método | Devuelve | Descripción |
-|--------|----------|-------------|
-| `rtstream.start()` | `None` | Inicia la ingesta |
-| `rtstream.stop()` | `None` | Detiene la ingesta |
-| `rtstream.generate_stream(start, end)` | `str` | Transmite un segmento grabado (timestamps Unix) |
-| `rtstream.export(name=None)` | `RTStreamExportResult` | Exporta a un video permanente |
-| `rtstream.index_visuals(prompt, ...)` | `RTStreamSceneIndex` | Crea un índice visual con análisis de IA |
-| `rtstream.index_audio(prompt, ...)` | `RTStreamSceneIndex` | Crea un índice de audio con resúmenes del LLM |
-| `rtstream.list_scene_indexes()` | `List[RTStreamSceneIndex]` | Lista todos los índices de escenas del stream |
-| `rtstream.get_scene_index(index_id)` | `RTStreamSceneIndex` | Obtiene un índice de escenas concreto |
-| `rtstream.search(query, ...)` | `RTStreamSearchResult` | Busca en el contenido indexado |
-| `rtstream.start_transcript(ws_connection_id, engine)` | `dict` | Inicia la transcripción en vivo |
-| `rtstream.get_transcript(page, page_size, start, end, since)` | `dict` | Obtiene páginas de la transcripción |
-| `rtstream.stop_transcript(engine)` | `dict` | Detiene la transcripción |
-
----
-
-## Iniciar y detener
-
-```python
-# Inicia la ingesta
-rtstream.start()
-
-# ... el stream se está grabando ...
-
-# Detiene la ingesta
-rtstream.stop()
-```
-
----
-
-## Generar streams
-
-Usa timestamps Unix (no offsets en segundos) para generar un stream de reproducción del contenido grabado:
-
-```python
-import time
-
-start_ts = time.time()
-rtstream.start()
-
-# Deja que grabe un rato...
-time.sleep(60)
-
-end_ts = time.time()
-rtstream.stop()
-
-# Genera una URL de stream para el segmento grabado
-stream_url = rtstream.generate_stream(start=start_ts, end=end_ts)
-print(f"Stream grabado: {stream_url}")
-```
-
----
-
-## Exportar a video
-
-Exporta el stream grabado a un video permanente en la colección:
-
-```python
-export_result = rtstream.export(name="Grabación de reunión 2024-01-15")
-
-print(f"ID del video: {export_result.video_id}")
-print(f"URL del stream: {export_result.stream_url}")
-print(f"URL del reproductor: {export_result.player_url}")
-print(f"Duración: {export_result.duration}s")
-```
-
-### Propiedades de RTStreamExportResult
-
-| Propiedad | Tipo | Descripción |
-|-----------|------|-------------|
-| `video_id` | `str` | ID del video exportado |
-| `stream_url` | `str` | URL del stream HLS |
-| `player_url` | `str` | URL del reproductor web |
-| `name` | `str` | Nombre del video |
-| `duration` | `float` | Duración en segundos |
-
----
-
-## Pipelines de IA
-
-Los pipelines de IA procesan los streams en vivo y envían los resultados vía WebSocket.
-
-### Métodos de pipelines de IA de RTStream
-
-| Método | Devuelve | Descripción |
-|--------|----------|-------------|
-| `rtstream.index_audio(prompt, batch_config, ...)` | `RTStreamSceneIndex` | Inicia la indexación de audio con resúmenes del LLM |
-| `rtstream.index_visuals(prompt, batch_config, ...)` | `RTStreamSceneIndex` | Inicia la indexación visual del contenido en pantalla |
-
-### Indexación de audio
-
-Genera resúmenes del LLM sobre el contenido de audio a intervalos:
-
-```python
-audio_index = rtstream.index_audio(
-    prompt="Resume lo que se está discutiendo",
-    batch_config={"type": "word", "value": 50},
-    model_name=None,       # opcional
-    name="audio_reunion",  # opcional
-    ws_connection_id=ws_id,
-)
-```
-
-**Opciones de batch_config para audio:**
-
-| Tipo | Valor | Descripción |
-|------|-------|-------------|
-| `"word"` | cantidad | Segmenta cada N palabras |
-| `"sentence"` | cantidad | Segmenta cada N oraciones |
-| `"time"` | segundos | Segmenta cada N segundos |
-
-Ejemplos:
-```python
-{"type": "word", "value": 50}      # cada 50 palabras
-{"type": "sentence", "value": 5}   # cada 5 oraciones
-{"type": "time", "value": 30}      # cada 30 segundos
-```
-
-Los resultados llegan por el canal WebSocket `audio_index`.
-
-### Indexación visual
-
-Genera descripciones de IA del contenido visual:
-
-```python
-scene_index = rtstream.index_visuals(
-    prompt="Describe lo que está pasando en pantalla",
-    batch_config={"type": "time", "value": 2, "frame_count": 5},
-    model_name="basic",
-    name="monitor_pantalla",  # opcional
-    ws_connection_id=ws_id,
-)
-```
-
-**Parámetros:**
-
-| Parámetro | Tipo | Descripción |
-|-----------|------|-------------|
-| `prompt` | `str` | Instrucciones para el modelo de IA (admite salida JSON estructurada) |
-| `batch_config` | `dict` | Controla el muestreo de frames (ver abajo) |
-| `model_name` | `str` | Nivel de modelo: `"mini"`, `"basic"`, `"pro"`, `"ultra"` |
-| `name` | `str` | Nombre del índice (opcional) |
-| `ws_connection_id` | `str` | ID de conexión WebSocket para recibir resultados |
-
-**batch_config visual:**
-
-| Clave | Tipo | Descripción |
-|-------|------|-------------|
-| `type` | `str` | Solo se soporta `"time"` para visuales |
-| `value` | `int` | Tamaño de la ventana en segundos |
-| `frame_count` | `int` | Número de frames a extraer por ventana |
-
-Ejemplo: `{"type": "time", "value": 2, "frame_count": 5}` muestrea 5 frames cada 2 segundos y los envía al modelo.
-
-**Salida JSON estructurada:**
-
-Usa un prompt que solicite formato JSON para respuestas estructuradas:
-
-```python
-scene_index = rtstream.index_visuals(
-    prompt="""Analiza la pantalla y devuelve un objeto JSON con:
-{
-  "app_name": "nombre de la aplicación activa",
-  "activity": "qué está haciendo el usuario",
-  "ui_elements": ["lista de elementos de UI visibles"],
-  "contains_text": true/false,
-  "dominant_colors": ["lista de colores principales"]
-}
-Devuelve solo JSON válido.""",
-    batch_config={"type": "time", "value": 3, "frame_count": 3},
-    model_name="pro",
-    ws_connection_id=ws_id,
-)
-```
-
-Los resultados llegan por el canal WebSocket `scene_index`.
-
----
-
-## Resumen de batch_config
-
-| Tipo de indexación | Opciones de `type` | `value` | Claves extra |
-|--------------------|--------------------|---------|--------------|
-| **Audio** | `"word"`, `"sentence"`, `"time"` | palabras/oraciones/segundos | - |
-| **Visual** | solo `"time"` | segundos | `frame_count` |
-
-Ejemplos:
-```python
-# Audio: cada 50 palabras
-{"type": "word", "value": 50}
-
-# Audio: cada 30 segundos
-{"type": "time", "value": 30}
-
-# Visual: 5 frames cada 2 segundos
-{"type": "time", "value": 2, "frame_count": 5}
-```
-
----
-
-## Transcripción
-
-Transcripción en tiempo real vía WebSocket:
-
-```python
-# Inicia la transcripción en vivo
-rtstream.start_transcript(
-    ws_connection_id=ws_id,
-    engine=None,  # opcional, por defecto "assemblyai"
-)
-
-# Obtiene páginas de la transcripción (con filtros opcionales)
-transcript = rtstream.get_transcript(
-    page=1,
-    page_size=100,
-    start=None,   # opcional: filtro de timestamp inicial
-    end=None,     # opcional: filtro de timestamp final
-    since=None,   # opcional: para sondeo, obtiene transcripciones posteriores a este timestamp
-    engine=None,
-)
-
-# Detiene la transcripción
-rtstream.stop_transcript(engine=None)
-```
-
-Los resultados de transcripción llegan por el canal WebSocket `transcript`.
-
----
-
-## RTStreamSceneIndex
-
-Al llamar a `index_audio()` o `index_visuals()`, el método devuelve un objeto `RTStreamSceneIndex`. Este objeto representa el índice en ejecución y provee métodos para gestionar escenas y alertas.
-
-```python
-# index_visuals devuelve un RTStreamSceneIndex
-scene_index = rtstream.index_visuals(
-    prompt="Describe lo que hay en pantalla",
-    ws_connection_id=ws_id,
-)
-
-# index_audio también devuelve un RTStreamSceneIndex
-audio_index = rtstream.index_audio(
-    prompt="Resume la discusión",
-    ws_connection_id=ws_id,
-)
-```
-
-### Propiedades de RTStreamSceneIndex
-
-| Propiedad | Tipo | Descripción |
-|-----------|------|-------------|
-| `rtstream_index_id` | `str` | ID único del índice |
-| `rtstream_id` | `str` | ID del RTStream padre |
-| `extraction_type` | `str` | Tipo de extracción (`time` o `transcript`) |
-| `extraction_config` | `dict` | Configuración de la extracción |
-| `prompt` | `str` | El prompt usado para el análisis |
-| `name` | `str` | Nombre del índice |
-| `status` | `str` | Estado (`connected`, `stopped`) |
-
-### Métodos de RTStreamSceneIndex
-
-| Método | Devuelve | Descripción |
-|--------|----------|-------------|
-| `index.get_scenes(start, end, page, page_size)` | `dict` | Obtiene las escenas indexadas |
-| `index.start()` | `None` | Inicia/reanuda el índice |
-| `index.stop()` | `None` | Detiene el índice |
-| `index.create_alert(event_id, callback_url, ws_connection_id)` | `str` | Crea una alerta para detección de eventos |
-| `index.list_alerts()` | `list` | Lista todas las alertas de este índice |
-| `index.enable_alert(alert_id)` | `None` | Habilita una alerta |
-| `index.disable_alert(alert_id)` | `None` | Deshabilita una alerta |
-
-### Obtener escenas
-
-Sondea las escenas indexadas desde el índice:
-
-```python
-result = scene_index.get_scenes(
-    start=None,      # opcional: timestamp inicial
-    end=None,        # opcional: timestamp final
-    page=1,
-    page_size=100,
-)
-
-for scene in result["scenes"]:
-    print(f"[{scene['start']}-{scene['end']}] {scene['text']}")
-
-if result["next_page"]:
-    # obtener la siguiente página
-    pass
-```
-
-### Gestionar índices de escenas
-
-```python
-# Lista todos los índices del stream
-indexes = rtstream.list_scene_indexes()
-
-# Obtiene un índice concreto por ID
-scene_index = rtstream.get_scene_index(index_id)
-
-# Detiene un índice
-scene_index.stop()
-
-# Reinicia un índice
-scene_index.start()
-```
-
----
-
-## Eventos
-
-Los eventos son reglas de detección reutilizables. Créalos una vez y adjúntalos a cualquier índice mediante alertas.
-
-### Métodos de eventos de Connection
-
-| Método | Devuelve | Descripción |
-|--------|----------|-------------|
-| `conn.create_event(event_prompt, label)` | `str` (event_id) | Crea un evento de detección |
-| `conn.list_events()` | `list` | Lista todos los eventos |
-
-### Crear un evento
-
-```python
-event_id = conn.create_event(
-    event_prompt="El usuario abrió la aplicación Slack",
-    label="slack_abierto",
-)
-```
-
-### Listar eventos
-
-```python
-events = conn.list_events()
-for event in events:
-    print(f"{event['event_id']}: {event['label']}")
-```
-
----
-
-## Alertas
-
-Las alertas conectan eventos con índices para recibir notificaciones en tiempo real. Cuando la IA detecta contenido que coincide con la descripción del evento, se envía una alerta.
-
-### Crear una alerta
-
-```python
-# Obtén el RTStreamSceneIndex desde index_visuals
-scene_index = rtstream.index_visuals(
-    prompt="Describe qué aplicación está abierta en pantalla",
-    ws_connection_id=ws_id,
-)
-
-# Crea una alerta sobre el índice
-alert_id = scene_index.create_alert(
-    event_id=event_id,
-    callback_url="https://tu-backend.com/alerts",  # para entrega por webhook
-    ws_connection_id=ws_id,  # para entrega por WebSocket (opcional)
-)
-```
-
-**Nota:** `callback_url` es obligatorio. Pasa una cadena vacía `""` si solo usas entrega por WebSocket.
-
-### Gestionar alertas
-
-```python
-# Lista todas las alertas de un índice
-alerts = scene_index.list_alerts()
-
-# Habilita/deshabilita alertas
-scene_index.disable_alert(alert_id)
-scene_index.enable_alert(alert_id)
-```
-
-### Entrega de alertas
-
-| Método | Latencia | Caso de uso |
-|--------|----------|-------------|
-| WebSocket | Tiempo real | Paneles, UI en vivo |
-| Webhook | < 1 segundo | Servidor-a-servidor, automatización |
-
-### Evento de alerta por WebSocket
-
-```json
-{
-  "channel": "alert",
-  "rtstream_id": "rts-xxx",
-  "data": {
-    "event_label": "slack_abierto",
-    "timestamp": 1710000012340,
-    "text": "El usuario abrió la aplicación Slack"
-  }
-}
-```
-
-### Payload del webhook
-
-```json
-{
-  "event_id": "event-xxx",
-  "label": "slack_abierto",
-  "confidence": 0.95,
-  "explanation": "El usuario abrió la aplicación Slack",
-  "timestamp": "2024-01-15T10:30:45Z",
-  "start_time": 1234.5,
-  "end_time": 1238.0,
-  "stream_url": "https://stream.videodb.io/v3/...",
-  "player_url": "https://console.videodb.io/player?url=..."
-}
-```
-
----
-
-## Integración con WebSocket
-
-Todos los resultados de IA en tiempo real se entregan vía WebSocket. Pasa `ws_connection_id` a:
-- `rtstream.start_transcript()`
-- `rtstream.index_audio()`
-- `rtstream.index_visuals()`
-- `scene_index.create_alert()`
-
-### Canales WebSocket
-
-| Canal | Origen | Contenido |
-|-------|--------|-----------|
-| `transcript` | `start_transcript()` | Voz a texto en tiempo real |
-| `scene_index` | `index_visuals()` | Resultados de análisis visual |
-| `audio_index` | `index_audio()` | Resultados de análisis de audio |
-| `alert` | `create_alert()` | Notificaciones de alertas |
-
-Para las estructuras de eventos WebSocket y el uso de ws_listener, ver [capture-reference.md](capture-reference.md).
-
----
-
-## Flujo completo
-
-```python
-import time
-import videodb
-from videodb.exceptions import InvalidRequestError
-
-conn = videodb.connect()
-coll = conn.get_collection()
-
-# 1. Conecta e inicia la grabación
-rtstream = coll.connect_rtstream(
-    url="rtmp://tu-servidor-de-stream/live/stream-key",
-    name="Standup semanal",
-    store=True,
-)
-rtstream.start()
-
-# 2. Graba durante la duración de la reunión
-start_ts = time.time()
-time.sleep(1800)  # 30 minutos
-end_ts = time.time()
-rtstream.stop()
-
-# Genera una URL de reproducción inmediata para la ventana capturada
-stream_url = rtstream.generate_stream(start=start_ts, end=end_ts)
-print(f"Stream grabado: {stream_url}")
-
-# 3. Exporta a un video permanente
-export_result = rtstream.export(name="Grabación del standup semanal")
-print(f"Video exportado: {export_result.video_id}")
-
-# 4. Indexa el video exportado para búsqueda
-video = coll.get_video(export_result.video_id)
-video.index_spoken_words(force=True)
-
-# 5. Busca los puntos de acción
-try:
-    results = video.search("puntos de acción y próximos pasos")
-    stream_url = results.compile()
-    print(f"Clip de puntos de acción: {stream_url}")
-except InvalidRequestError as exc:
-    if "No results found" in str(exc):
-        print("No se detectaron puntos de acción en la grabación.")
-    else:
-        raise
-```

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

@@ -1,65 +0,0 @@
-# Guía de RTStream
-
-## Resumen
-
-RTStream permite la ingesta en tiempo real de streams de video en vivo (RTSP/RTMP) y de sesiones de captura de escritorio. Una vez conectado, puedes grabar, indexar, buscar y exportar contenido de fuentes en vivo.
-
-Para los detalles a nivel de código (métodos del SDK, parámetros, ejemplos), ver [rtstream-reference.md](rtstream-reference.md).
-
-## Casos de uso
-
-- **Seguridad y monitoreo**: conectar cámaras RTSP, detectar eventos, disparar alertas
-- **Transmisiones en vivo**: ingerir streams RTMP, indexar en tiempo real, habilitar búsqueda instantánea
-- **Grabación de reuniones**: capturar pantalla y audio del escritorio, transcribir en vivo, exportar grabaciones
-- **Procesamiento de eventos**: monitorear feeds en vivo, ejecutar análisis con IA, responder al contenido detectado
-
-## Inicio rápido
-
-1. **Conéctate a un stream en vivo** (URL RTSP/RTMP) u obtén el RTStream desde una sesión de captura
-
-2. **Inicia la ingesta** para empezar a grabar el contenido en vivo
-
-3. **Inicia los pipelines de IA** para indexación en tiempo real (audio, visual, transcripción)
-
-4. **Monitorea los eventos** vía WebSocket para resultados de IA y alertas en vivo
-
-5. **Detén la ingesta** al terminar
-
-6. **Exporta a video** para almacenamiento permanente y procesamiento posterior
-
-7. **Busca en la grabación** para encontrar momentos específicos
-
-## Fuentes de RTStream
-
-### Desde streams RTSP/RTMP
-
-Conéctate directamente a una fuente de video en vivo:
-
-```python
-rtstream = coll.connect_rtstream(
-    url="rtmp://tu-servidor-de-stream/live/stream-key",
-    name="Mi stream en vivo",
-)
-```
-
-### Desde sesiones de captura
-
-Obtén los RTStreams de una captura de escritorio (micrófono, pantalla, audio del sistema):
-
-```python
-session = conn.get_capture_session(session_id)
-
-mics = session.get_rtstream("mic")
-displays = session.get_rtstream("screen")
-system_audios = session.get_rtstream("system_audio")
-```
-
-Para el flujo de sesiones de captura, ver [capture.md](capture.md).
-
----
-
-## Scripts
-
-| Script | Descripción |
-|--------|-------------|
-| `scripts/ws_listener.py` | Listener de eventos WebSocket para resultados de IA en tiempo real |