theus-cli 0.2.82 → 0.2.84

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

@@ -1,230 +0,0 @@
-# Guía de búsqueda e indexación
-
-La búsqueda permite encontrar momentos concretos dentro de videos usando consultas en lenguaje natural, palabras clave exactas o descripciones visuales de escenas.
-
-## Requisitos previos
-
-Los videos **deben estar indexados** antes de poder buscarse. La indexación es una operación única por video y por tipo de índice.
-
-## Indexación
-
-### Índice de habla (spoken word)
-
-Indexa el contenido de habla transcrito de un video para búsqueda semántica y de palabras clave:
-
-```python
-video = coll.get_video(video_id)
-
-# force=True hace la indexación idempotente — la omite si ya está indexado
-video.index_spoken_words(force=True)
-```
-
-Esto transcribe la pista de audio y construye un índice buscable sobre el contenido hablado. Requerido para la búsqueda semántica y la de palabras clave.
-
-**Parámetros:**
-
-| Parámetro | Tipo | Por defecto | Descripción |
-|-----------|------|-------------|-------------|
-| `language_code` | `str\|None` | `None` | Código de idioma del video |
-| `segmentation_type` | `SegmentationType` | `SegmentationType.sentence` | Tipo de segmentación (`sentence` o `llm`) |
-| `force` | `bool` | `False` | Ponlo en `True` para omitir si ya está indexado (evita el error "already exists") |
-| `callback_url` | `str\|None` | `None` | URL de webhook para notificación asíncrona |
-
-### Índice de escenas
-
-Indexa el contenido visual generando descripciones de IA de las escenas. Igual que la indexación de habla, lanza un error si ya existe un índice de escenas. Extrae el `scene_index_id` existente del mensaje de error.
-
-```python
-import re
-from videodb import SceneExtractionType
-
-try:
-    scene_index_id = video.index_scenes(
-        extraction_type=SceneExtractionType.shot_based,
-        prompt="Describe el contenido visual, los objetos, las acciones y el entorno de esta escena.",
-    )
-except Exception as e:
-    match = re.search(r"id\s+([a-f0-9]+)", str(e))
-    if match:
-        scene_index_id = match.group(1)
-    else:
-        raise
-```
-
-**Tipos de extracción:**
-
-| Tipo | Descripción | Ideal para |
-|------|-------------|----------|
-| `SceneExtractionType.shot_based` | Divide por límites de plano visual | Uso general, contenido con acción |
-| `SceneExtractionType.time_based` | Divide a intervalos fijos | Muestreo uniforme, contenido largo estático |
-| `SceneExtractionType.transcript` | Divide según segmentos de la transcripción | Límites de escena guiados por el habla |
-
-**Parámetros para `time_based`:**
-
-```python
-video.index_scenes(
-    extraction_type=SceneExtractionType.time_based,
-    extraction_config={"time": 5, "select_frames": ["first", "last"]},
-    prompt="Describe qué está pasando en esta escena.",
-)
-```
-
-## Tipos de búsqueda
-
-### Búsqueda semántica
-
-Consultas en lenguaje natural contrastadas con el contenido hablado:
-
-```python
-from videodb import SearchType
-
-results = video.search(
-    query="explicando los beneficios del machine learning",
-    search_type=SearchType.semantic,
-)
-```
-
-Devuelve segmentos ordenados por relevancia donde el contenido hablado coincide semánticamente con la consulta.
-
-### Búsqueda por palabra clave
-
-Coincidencia exacta de términos en el habla transcrita:
-
-```python
-results = video.search(
-    query="inteligencia artificial",
-    search_type=SearchType.keyword,
-)
-```
-
-Devuelve segmentos que contienen exactamente la palabra clave o frase.
-
-### Búsqueda de escenas
-
-Consultas de contenido visual contrastadas con las descripciones de escenas indexadas. Requiere una llamada previa a `index_scenes()`.
-
-`index_scenes()` devuelve un `scene_index_id`. Pásalo a `video.search()` para apuntar a un índice de escenas concreto (especialmente importante cuando un video tiene varios índices de escenas):
-
-```python
-from videodb import SearchType, IndexType
-from videodb.exceptions import InvalidRequestError
-
-# Busca usando búsqueda semántica contra el índice de escenas.
-# Usa score_threshold para filtrar ruido de baja relevancia (recomendado: 0.3+).
-try:
-    results = video.search(
-        query="persona escribiendo en una pizarra",
-        search_type=SearchType.semantic,
-        index_type=IndexType.scene,
-        scene_index_id=scene_index_id,
-        score_threshold=0.3,
-    )
-    shots = results.get_shots()
-except InvalidRequestError as e:
-    if "No results found" in str(e):
-        shots = []
-    else:
-        raise
-```
-
-**Notas importantes:**
-
-- Usa `SearchType.semantic` con `index_type=IndexType.scene` — es la combinación más fiable y funciona en todos los planes.
-- `SearchType.scene` existe pero puede no estar disponible en todos los planes (p. ej. el gratuito). Prefiere `SearchType.semantic` con `IndexType.scene`.
-- El parámetro `scene_index_id` es opcional. Si se omite, la búsqueda corre contra todos los índices de escenas del video. Pásalo para apuntar a un índice concreto.
-- Puedes crear varios índices de escenas por video (con distintos prompts o tipos de extracción) y buscarlos de forma independiente usando `scene_index_id`.
-
-### Búsqueda de escenas con filtrado por metadatos
-
-Al indexar escenas con metadatos personalizados, puedes combinar la búsqueda semántica con filtros de metadatos:
-
-```python
-from videodb import SearchType, IndexType
-
-results = video.search(
-    query="una escena de persecución hábil",
-    search_type=SearchType.semantic,
-    index_type=IndexType.scene,
-    scene_index_id=scene_index_id,
-    filter=[{"camera_view": "road_ahead"}, {"action_type": "chasing"}],
-)
-```
-
-Ver el [cookbook de scene_level_metadata_indexing](https://github.com/video-db/videodb-cookbook/blob/main/quickstart/scene_level_metadata_indexing.ipynb) para un ejemplo completo de indexación con metadatos personalizados y búsqueda filtrada.
-
-## Trabajar con los resultados
-
-### Obtener shots
-
-Accede a los segmentos de resultado individuales:
-
-```python
-results = video.search("tu consulta")
-
-for shot in results.get_shots():
-    print(f"Video: {shot.video_id}")
-    print(f"Inicio: {shot.start:.2f}s")
-    print(f"Fin: {shot.end:.2f}s")
-    print(f"Texto: {shot.text}")
-    print("---")
-```
-
-### Reproducir los resultados compilados
-
-Transmite todos los segmentos coincidentes como un único video compilado:
-
-```python
-results = video.search("tu consulta")
-stream_url = results.compile()
-results.play()  # abre el stream compilado en el navegador
-```
-
-### Extraer clips
-
-Descarga o transmite segmentos concretos del resultado:
-
-```python
-for shot in results.get_shots():
-    stream_url = shot.generate_stream()
-    print(f"Clip: {stream_url}")
-```
-
-## Búsqueda entre colecciones
-
-Busca en todos los videos de una colección:
-
-```python
-coll = conn.get_collection()
-
-# Busca en todos los videos de la colección
-results = coll.search(
-    query="demo del producto",
-    search_type=SearchType.semantic,
-)
-
-for shot in results.get_shots():
-    print(f"Video: {shot.video_id} [{shot.start:.1f}s - {shot.end:.1f}s]")
-```
-
-> **Nota:** la búsqueda a nivel de colección solo soporta `SearchType.semantic`. Usar `SearchType.keyword` o `SearchType.scene` con `coll.search()` lanza `NotImplementedError`. Para búsqueda por palabra clave o de escenas, usa `video.search()` en videos individuales.
-
-## Búsqueda + compilación
-
-Indexa, busca y compila los segmentos coincidentes en un único stream reproducible:
-
-```python
-video.index_spoken_words(force=True)
-results = video.search(query="tu consulta", search_type=SearchType.semantic)
-stream_url = results.compile()
-print(stream_url)
-```
-
-## Consejos
-
-- **Indexa una vez, busca muchas**: la indexación es la operación cara. Una vez indexado, las búsquedas son rápidas.
-- **Combina tipos de índice**: indexa habla y escenas para habilitar todos los tipos de búsqueda sobre el mismo video.
-- **Refina las consultas**: la búsqueda semántica funciona mejor con frases descriptivas en lenguaje natural que con palabras sueltas.
-- **Usa palabra clave para precisión**: cuando necesites coincidencias exactas, la búsqueda por palabra clave evita la deriva semántica.
-- **Maneja "No results found"**: `video.search()` lanza `InvalidRequestError` cuando no hay coincidencias. Envuelve siempre las búsquedas en try/except y trata `"No results found"` como un conjunto vacío.
-- **Filtra el ruido en escenas**: la búsqueda semántica de escenas puede devolver resultados poco relevantes con consultas vagas. Usa `score_threshold=0.3` (o mayor) para filtrar ruido.
-- **Indexación idempotente**: usa `index_spoken_words(force=True)` para reindexar con seguridad. `index_scenes()` no tiene parámetro `force` — envuélvelo en try/except y extrae el `scene_index_id` existente del error con `re.search(r"id\s+([a-f0-9]+)", str(e))`.

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

@@ -1,406 +0,0 @@
-# Streaming y reproducción
-
-VideoDB genera streams bajo demanda y devuelve URLs compatibles con HLS que se reproducen al instante en cualquier reproductor de video estándar. Sin tiempos de renderizado ni esperas de exportación: ediciones, búsquedas y composiciones se transmiten de inmediato.
-
-## Requisitos previos
-
-Los videos **deben estar subidos** a una colección antes de generar streams. Para streams basados en búsqueda, el video además debe estar **indexado** (palabras habladas y/o escenas). Ver [search.md](search.md) para los detalles de indexación.
-
-## Conceptos clave
-
-### Generación de streams
-
-Cada video, resultado de búsqueda y línea de tiempo en VideoDB puede producir una **URL de stream**. Esa URL apunta a un manifiesto HLS (HTTP Live Streaming) que se compila bajo demanda.
-
-```python
-# Desde un video
-stream_url = video.generate_stream()
-
-# Desde una línea de tiempo
-stream_url = timeline.generate_stream()
-
-# Desde resultados de búsqueda
-stream_url = results.compile()
-```
-
-## Transmitir un solo video
-
-### Reproducción básica
-
-```python
-import videodb
-
-conn = videodb.connect()
-coll = conn.get_collection()
-video = coll.get_video("tu-video-id")
-
-# Genera la URL del stream
-stream_url = video.generate_stream()
-print(f"Stream: {stream_url}")
-
-# Abre en el navegador por defecto
-video.play()
-```
-
-### Con subtítulos
-
-```python
-# Indexa y añade subtítulos primero
-video.index_spoken_words(force=True)
-stream_url = video.add_subtitle()
-
-# La URL devuelta ya incluye los subtítulos
-print(f"Stream con subtítulos: {stream_url}")
-```
-
-### Segmentos específicos
-
-Transmite solo una porción de un video pasando una línea de tiempo de rangos de marcas de tiempo:
-
-```python
-# Transmite los segundos 10-30 y 60-90
-stream_url = video.generate_stream(timeline=[(10, 30), (60, 90)])
-print(f"Stream de segmentos: {stream_url}")
-```
-
-## Transmitir composiciones de línea de tiempo
-
-Construye una composición multi-asset y transmítela en tiempo real:
-
-```python
-import videodb
-from videodb.timeline import Timeline
-from videodb.asset import VideoAsset, AudioAsset, ImageAsset, TextAsset, TextStyle
-
-conn = videodb.connect()
-coll = conn.get_collection()
-
-video = coll.get_video(video_id)
-music = coll.get_audio(music_id)
-
-timeline = Timeline(conn)
-
-# Contenido de video principal
-timeline.add_inline(VideoAsset(asset_id=video.id))
-
-# Superposición de música de fondo (empieza en el segundo 0)
-timeline.add_overlay(0, AudioAsset(asset_id=music.id))
-
-# Superposición de texto al inicio
-timeline.add_overlay(0, TextAsset(
-    text="Demo en vivo",
-    duration=3,
-    style=TextStyle(fontsize=48, fontcolor="white", boxcolor="#000000"),
-))
-
-# Genera el stream compuesto
-stream_url = timeline.generate_stream()
-print(f"Stream compuesto: {stream_url}")
-```
-
-**Importante:** `add_inline()` solo acepta `VideoAsset`. Usa `add_overlay()` para `AudioAsset`, `ImageAsset` y `TextAsset`.
-
-Para edición de línea de tiempo en detalle, ver [editor.md](editor.md).
-
-## Transmitir resultados de búsqueda
-
-Compila los resultados de búsqueda en un único stream con todos los segmentos coincidentes:
-
-```python
-from videodb import SearchType
-from videodb.exceptions import InvalidRequestError
-
-video.index_spoken_words(force=True)
-try:
-    results = video.search("anuncio clave", search_type=SearchType.semantic)
-
-    # Compila todos los shots coincidentes en un solo stream
-    stream_url = results.compile()
-    print(f"Stream de resultados: {stream_url}")
-
-    # O reprodúcelo directamente
-    results.play()
-except InvalidRequestError as exc:
-    if "No results found" in str(exc):
-        print("No se encontraron segmentos de anuncio coincidentes.")
-    else:
-        raise
-```
-
-### Transmitir coincidencias individuales
-
-```python
-from videodb.exceptions import InvalidRequestError
-
-try:
-    results = video.search("demo del producto", search_type=SearchType.semantic)
-    for i, shot in enumerate(results.get_shots()):
-        stream_url = shot.generate_stream()
-        print(f"Coincidencia {i+1} [{shot.start:.1f}s-{shot.end:.1f}s]: {stream_url}")
-except InvalidRequestError as exc:
-    if "No results found" in str(exc):
-        print("Ningún segmento de demo del producto coincidió con la consulta.")
-    else:
-        raise
-```
-
-## Reproducción de audio
-
-Obtén una URL de reproducción firmada para contenido de audio:
-
-```python
-audio = coll.get_audio(audio_id)
-playback_url = audio.generate_url()
-print(f"URL de audio: {playback_url}")
-```
-
-## Ejemplos de flujos completos
-
-### Pipeline búsqueda-a-stream
-
-Combina búsqueda, composición de línea de tiempo y streaming en un solo flujo:
-
-```python
-import videodb
-from videodb import SearchType
-from videodb.exceptions import InvalidRequestError
-from videodb.timeline import Timeline
-from videodb.asset import VideoAsset, TextAsset, TextStyle
-
-conn = videodb.connect()
-coll = conn.get_collection()
-video = coll.get_video("tu-video-id")
-
-video.index_spoken_words(force=True)
-
-# Busca los momentos clave
-queries = ["introducción", "demo principal", "preguntas y respuestas"]
-timeline = Timeline(conn)
-timeline_offset = 0.0
-
-for query in queries:
-    try:
-        results = video.search(query, search_type=SearchType.semantic)
-        shots = results.get_shots()
-    except InvalidRequestError as exc:
-        if "No results found" in str(exc):
-            shots = []
-        else:
-            raise
-
-    if not shots:
-        continue
-
-    # Añade la etiqueta de sección donde empieza este bloque en la línea de tiempo compilada
-    timeline.add_overlay(timeline_offset, TextAsset(
-        text=query.title(),
-        duration=2,
-        style=TextStyle(fontsize=36, fontcolor="white", boxcolor="#222222"),
-    ))
-
-    for shot in shots:
-        timeline.add_inline(
-            VideoAsset(asset_id=shot.video_id, start=shot.start, end=shot.end)
-        )
-        timeline_offset += shot.end - shot.start
-
-stream_url = timeline.generate_stream()
-print(f"Compilación dinámica: {stream_url}")
-```
-
-### Stream multi-video
-
-Combina clips de distintos videos en un solo stream:
-
-```python
-import videodb
-from videodb.timeline import Timeline
-from videodb.asset import VideoAsset
-
-conn = videodb.connect()
-coll = conn.get_collection()
-
-video_clips = [
-    {"id": "vid_001", "start": 0, "end": 15},
-    {"id": "vid_002", "start": 10, "end": 30},
-    {"id": "vid_003", "start": 5, "end": 25},
-]
-
-timeline = Timeline(conn)
-for clip in video_clips:
-    timeline.add_inline(
-        VideoAsset(asset_id=clip["id"], start=clip["start"], end=clip["end"])
-    )
-
-stream_url = timeline.generate_stream()
-print(f"Stream multi-video: {stream_url}")
-```
-
-### Ensamblado condicional de stream
-
-Construye un stream dinámicamente según la disponibilidad de resultados:
-
-```python
-import videodb
-from videodb import SearchType
-from videodb.exceptions import InvalidRequestError
-from videodb.timeline import Timeline
-from videodb.asset import VideoAsset, TextAsset, TextStyle
-
-conn = videodb.connect()
-coll = conn.get_collection()
-video = coll.get_video("tu-video-id")
-
-video.index_spoken_words(force=True)
-
-timeline = Timeline(conn)
-
-# Intenta encontrar contenido específico; si no, usa el video completo
-topics = ["palabras de apertura", "análisis técnico a fondo", "cierre"]
-
-found_any = False
-timeline_offset = 0.0
-for topic in topics:
-    try:
-        results = video.search(topic, search_type=SearchType.semantic)
-        shots = results.get_shots()
-    except InvalidRequestError as exc:
-        if "No results found" in str(exc):
-            shots = []
-        else:
-            raise
-
-    if shots:
-        found_any = True
-        timeline.add_overlay(timeline_offset, TextAsset(
-            text=topic.title(),
-            duration=2,
-            style=TextStyle(fontsize=32, fontcolor="white", boxcolor="#1a1a2e"),
-        ))
-        for shot in shots:
-            timeline.add_inline(
-                VideoAsset(asset_id=shot.video_id, start=shot.start, end=shot.end)
-            )
-            timeline_offset += shot.end - shot.start
-
-if found_any:
-    stream_url = timeline.generate_stream()
-    print(f"Stream curado: {stream_url}")
-else:
-    # Recurre al stream del video completo
-    stream_url = video.generate_stream()
-    print(f"Stream del video completo: {stream_url}")
-```
-
-### Resumen de un evento en vivo
-
-Procesa la grabación de un evento en un resumen transmitible con varias secciones:
-
-```python
-import videodb
-from videodb import SearchType
-from videodb.exceptions import InvalidRequestError
-from videodb.timeline import Timeline
-from videodb.asset import VideoAsset, AudioAsset, ImageAsset, TextAsset, TextStyle
-
-conn = videodb.connect()
-coll = conn.get_collection()
-
-# Sube la grabación del evento
-event = coll.upload(url="https://example.com/event-recording.mp4")
-event.index_spoken_words(force=True)
-
-# Genera música de fondo
-music = coll.generate_music(
-    prompt="música corporativa de fondo animada",
-    duration=120,
-)
-
-# Genera la imagen del título
-title_img = coll.generate_image(
-    prompt="tarjeta de título moderna para resumen de evento, fondo oscuro, profesional",
-    aspect_ratio="16:9",
-)
-
-# Construye la línea de tiempo del resumen
-timeline = Timeline(conn)
-timeline_offset = 0.0
-
-# Segmentos de video principales a partir de búsquedas
-try:
-    keynote = event.search("anuncio de la keynote", search_type=SearchType.semantic)
-    keynote_shots = keynote.get_shots()[:5]
-except InvalidRequestError as exc:
-    if "No results found" in str(exc):
-        keynote_shots = []
-    else:
-        raise
-if keynote_shots:
-    keynote_start = timeline_offset
-    for shot in keynote_shots:
-        timeline.add_inline(
-            VideoAsset(asset_id=shot.video_id, start=shot.start, end=shot.end)
-        )
-        timeline_offset += shot.end - shot.start
-else:
-    keynote_start = None
-
-try:
-    demo = event.search("demo del producto", search_type=SearchType.semantic)
-    demo_shots = demo.get_shots()[:5]
-except InvalidRequestError as exc:
-    if "No results found" in str(exc):
-        demo_shots = []
-    else:
-        raise
-if demo_shots:
-    demo_start = timeline_offset
-    for shot in demo_shots:
-        timeline.add_inline(
-            VideoAsset(asset_id=shot.video_id, start=shot.start, end=shot.end)
-        )
-        timeline_offset += shot.end - shot.start
-else:
-    demo_start = None
-
-# Superpone la imagen de la tarjeta de título
-timeline.add_overlay(0, ImageAsset(
-    asset_id=title_img.id, width=100, height=100, x=80, y=20, duration=5
-))
-
-# Superpone las etiquetas de sección en los offsets correctos
-if keynote_start is not None:
-    timeline.add_overlay(max(5, keynote_start), TextAsset(
-        text="Momentos clave de la keynote",
-        duration=3,
-        style=TextStyle(fontsize=40, fontcolor="white", boxcolor="#0d1117"),
-    ))
-if demo_start is not None:
-    timeline.add_overlay(max(5, demo_start), TextAsset(
-        text="Momentos clave de la demo",
-        duration=3,
-        style=TextStyle(fontsize=36, fontcolor="white", boxcolor="#0d1117"),
-    ))
-
-# Superpone la música de fondo
-timeline.add_overlay(0, AudioAsset(
-    asset_id=music.id, fade_in_duration=3
-))
-
-# Transmite el resumen final
-stream_url = timeline.generate_stream()
-print(f"Resumen del evento: {stream_url}")
-```
-
----
-
-## Consejos
-
-- **Compatibilidad HLS**: las URLs de stream devuelven manifiestos HLS (`.m3u8`). Funcionan nativamente en Safari, y en otros navegadores vía hls.js o librerías similares.
-- **Compilación bajo demanda**: los streams se compilan en el servidor al solicitarlos. La primera reproducción puede tener una breve demora de compilación; las siguientes reproducciones de la misma composición se cachean.
-- **Caché**: llamar a `video.generate_stream()` una segunda vez sin argumentos devuelve la URL de stream cacheada en lugar de recompilar.
-- **Streams de segmentos**: `video.generate_stream(timeline=[(start, end)])` es la forma más rápida de transmitir un clip específico sin construir un objeto `Timeline` completo.
-- **En línea vs superposición**: `add_inline()` solo acepta `VideoAsset` y coloca los assets secuencialmente en la pista principal. `add_overlay()` acepta `AudioAsset`, `ImageAsset` y `TextAsset` y los apila encima a partir de un tiempo de inicio dado.
-- **Valores por defecto de TextStyle**: `TextStyle` usa por defecto `font='Sans'`, `fontcolor='black'`. Usa `boxcolor` (no `bgcolor`) para el color de fondo del texto.
-- **Combina con generación**: usa `coll.generate_music(prompt, duration)` y `coll.generate_image(prompt, aspect_ratio)` para crear assets para composiciones de línea de tiempo.
-- **Reproducción**: `.play()` abre la URL del stream en el navegador por defecto del sistema. Para uso programático, trabaja directamente con la cadena de la URL.