diff --git a/propuesta_tecnica.md b/propuesta_tecnica.md index d5734ade..1efc129b 100644 --- a/propuesta_tecnica.md +++ b/propuesta_tecnica.md @@ -30,6 +30,30 @@ **Entregable:** MVP funcional desplegado en web, con un agente capaz de ejecutar al menos 8 "skills" de edición a partir de instrucciones en lenguaje natural. +### 1.1. Estado actual de la dirección técnica + +> **Nota para agentes y desarrolladores nuevos:** este documento empezó como propuesta general. La dirección actual del proyecto se refinó durante la implementación inicial. Para tareas concretas de tools, usar también `docs/agent-tools.md` y `docs/agent-tool-specs.md` como referencia operativa. + +Decisiones vigentes: + +- El agente ya no debe diseñarse como una lista de “features IA” aisladas, sino como un **orquestador con tools primitivas, pequeñas y componibles**. +- La base del producto es que el agente pueda **entender assets multimodales** con Gemini y luego ejecutar acciones determinísticas sobre el editor. +- `transcribe_video` existe y es útil, pero queda como **tool secundaria** para subtítulos/captions/búsqueda textual. No debe ser la herramienta principal de comprensión del video. +- La herramienta principal de percepción a implementar es `load_asset_context`, que carga un asset en el contexto multimodal de Gemini y cachea su referencia. +- `get_asset_context` es infraestructura interna/cache, no necesariamente una tool visible al LLM. +- Las tools de edición deben mapearse a acciones reales del editor: cortar, agregar texto, insertar media, borrar elementos, volumen, stickers y efectos existentes. +- El repo actual tiene infraestructura de efectos, pero el efecto real registrado parece ser **solo `blur`**; corrección de color/LUTs queda fuera del scope inmediato. +- El core actual del agente es **provider-agnostic** con providers configurables por `LLM_PROVIDER`, `LLM_API_KEY`, `LLM_MODEL`, `LLM_BASE_URL`. +- Ya existen adapters para `openai-compatible` y `gemini`. +- Gemini es el proveedor prioritario para video understanding. `LLM_PROVIDER=gemini` con `LLM_MODEL=gemini-3-flash-preview` es la configuración deseada para pruebas de la killer feature. + +Roadmap vigente de alto nivel: + +1. **Contexto y percepción:** `list_project_assets`, `list_timeline`, `load_asset_context`. +2. **Edición básica:** `cut_segment`, `add_text`, `add_media_to_timeline`, `delete_element`. +3. **Ajustes simples:** `set_volume`, `add_sticker`, `apply_effect`. +4. **UX avanzada:** referencias `@asset`, progreso de uploads/procesamiento, previews/aprobaciones. + --- ## 2. Problema y solución @@ -194,17 +218,20 @@ El agente conversacional (orquestación, tool calling, providers, streaming) se | OpenAI | GPT-5 | Alternativa | | Local | Qwen3-8B | Para desarrollo | -**Estrategia:** usar Haiku para 80% de decisiones (rápidas/simples) y escalar a Opus solo para razonamiento complejo. +**Estrategia vigente:** el agente debe ser provider-agnostic. En desarrollo/demo se prioriza Gemini por video understanding. Otros providers OpenAI-compatible/Groq/Ollama pueden usarse para chat y tool calling textual, pero no reemplazan la capacidad multimodal nativa de Gemini. #### Video Understanding (la killer feature) | Proveedor | Modelo | Cuándo usarlo | |---|---|---| -| **Google** | **Gemini 2.5 Flash** | Producción/demo. Procesa hasta 6h de video con timestamps nativos. | +| **Google** | **Gemini 3 Flash / `gemini-3-flash-preview`** | Proveedor prioritario para demo y video understanding multimodal. | +| **Google** | **Gemini 2.5 Flash** | Fallback/alternativa si Gemini 3 Flash está saturado o no disponible. | | **Google** | Gemini 2.5 Pro | Casos complejos. Más caro. | | **Local** | **Qwen2.5-VL-7B** | Desarrollo local. Gratis. Entiende video con timestamps nativamente. | | **Local** | Qwen2.5-VL-3B | Laptops con menos recursos. | +**Dirección vigente:** Gemini no debe usarse solo como LLM de texto. La ventaja real es cargar el asset de video/audio/imagen al contexto multimodal del modelo mediante Files API o mecanismo equivalente. Esa capacidad se modela en el agente con `load_asset_context`. + #### Transcripción (Speech-to-Text) | Proveedor | Modelo | Notas | @@ -381,7 +408,40 @@ ANTHROPIC_API_KEY=... ## 7. Detalle de tools del agente -Cada tool es una función pura que el LLM puede invocar. Se definen con JSON Schema para que el LLM sepa cuándo llamarlas. +Cada tool es una función que el LLM puede invocar con entrada estructurada. Se definen con schema para que el modelo sepa cuándo llamarlas y para que el orquestador pueda validar argumentos antes de ejecutar. + +> **Actualización importante:** la lista original por tiers queda como referencia histórica de ideas posibles. La dirección vigente del proyecto es usar **tools primitivas y componibles**. Para implementación, usar como fuente principal `docs/agent-tool-specs.md`. + +### 7.0. Tools primitivas vigentes + +Estas son las tools que el equipo debe priorizar. Son suficientemente pequeñas para implementarse y testearse por separado, pero combinables para resolver tareas complejas. + +| Tool | Propósito | Estado / prioridad | +|---|---|---| +| `list_project_assets` | Lista assets del proyecto, usados/no usados y por tipo | Prioridad alta | +| `list_timeline` | Devuelve resumen estructurado del timeline con `trackId`/`elementId` | Prioridad alta | +| `load_asset_context` | Carga un asset en el contexto multimodal de Gemini y cachea la referencia | Prioridad crítica / killer feature | +| `cut_segment` | Corta/remueve rangos de tiempo | Prioridad alta | +| `add_text` | Agrega texto visual: hooks, títulos, labels, subtítulos básicos | Prioridad alta | +| `update_text` | Modifica texto existente | Prioridad media | +| `add_media_to_timeline` | Inserta video/audio/imagen existente al timeline | Prioridad alta | +| `delete_element` | Borra un elemento específico del timeline | Prioridad alta | +| `set_volume` | Ajusta volumen de audio/video | Prioridad media | +| `add_sticker` | Inserta sticker existente | Prioridad media | +| `apply_effect` | Aplica efectos existentes; por ahora principalmente `blur` | Prioridad baja/media | + +`transcribe_video` se mantiene como tool secundaria para captions, subtítulos y edición basada en texto. No debe reemplazar a `load_asset_context` para comprensión multimodal. + +### 7.0.1. Referencias operativas + +- `docs/agent-tools.md` — lista conceptual de tools y decisiones. +- `docs/agent-tool-specs.md` — contratos de input/output, requirements y errores esperados para cada tool. + +--- + +### Lista histórica original + +La siguiente lista se conserva como material de ideación, pero no debe tomarse como backlog implementable directo. ### Tier 1 — Fundamentales (MVP must-have) @@ -769,21 +829,28 @@ Esto no reemplaza la primera feature de producto; la **habilita**. - Como sistema, las tools comparten un contrato estable de entrada y salida - Como equipo, podemos alternar entre providers mock, locales y cloud sin cambiar la lógica de negocio -**Must-have (Sprint 3-5):** -- Como usuario, subo un video y el agente me lo transcribe -- Como usuario, le pido cortar un segmento específico por timestamp -- Como usuario, le pido que me identifique las escenas -- Como usuario, le pregunto sobre el contenido del video y me responde +**Must-have actualizado:** +- Como usuario, puedo chatear con un agente conectado a un provider real (`LLM_PROVIDER`). +- Como sistema, puedo alternar entre providers (`gemini`, `openai-compatible`) sin cambiar el core del agente. +- Como agente, puedo listar assets del proyecto y saber cuáles están en el timeline. +- Como agente, puedo cargar un asset con Gemini usando `load_asset_context` para entenderlo multimodalmente. +- Como usuario, puedo preguntarle al agente sobre el contenido del video después de que el asset esté cargado en contexto. +- Como usuario, puedo pedir cortes básicos por timestamp usando `cut_segment`. +- Como usuario, puedo pedir texto visual básico usando `add_text`. -**Should-have (Sprint 6-8):** -- Como usuario, le pido subtítulos con un estilo específico -- Como usuario, le pido convertir a vertical siguiendo mi cara -- Como usuario, le pido un resumen automático de los mejores momentos +**Should-have actualizado:** +- Como usuario, puedo insertar assets existentes al timeline con `add_media_to_timeline`. +- Como usuario, puedo borrar elementos específicos con `delete_element`. +- Como usuario, puedo ajustar volumen con `set_volume`. +- Como usuario, puedo agregar stickers con `add_sticker`. +- Como usuario, puedo aplicar efectos existentes con `apply_effect` (inicialmente `blur`). **Nice-to-have (Sprint 9+):** - Como usuario, puedo deshacer acciones del agente - Como usuario, el agente me muestra un preview antes de aplicar cambios grandes - Como usuario, comparto el proyecto por URL +- Como usuario, puedo referenciar assets con `@asset`. +- Como sistema, cacheo referencias Gemini de assets cargados para evitar re-upload. ---