327 lines
6.3 KiB
Markdown
327 lines
6.3 KiB
Markdown
# Agent Tools — Lista propuesta
|
||
|
||
Este documento resume las tools propuestas para el agente de NeuralCut. La idea es mantenerlas **primitivas, acotadas y componibles**, no crear una tool por cada feature de marketing.
|
||
|
||
## Principio
|
||
|
||
El agente debe combinar primitives simples:
|
||
|
||
- primero entiende el proyecto/assets,
|
||
- luego decide qué acción hacer,
|
||
- después ejecuta operaciones concretas del editor.
|
||
|
||
No queremos tools gigantes tipo “hazme un reel completo”. Eso debe ser un flujo del agente usando varias tools pequeñas.
|
||
|
||
---
|
||
|
||
## Tools de contexto y percepción
|
||
|
||
### `list_project_assets`
|
||
|
||
Lista assets conocidos del proyecto.
|
||
|
||
```ts
|
||
{
|
||
filter?: "all" | "used" | "unused";
|
||
type?: "all" | "video" | "audio" | "image";
|
||
}
|
||
```
|
||
|
||
Uso:
|
||
- saber qué archivos existen,
|
||
- distinguir assets usados/no usados,
|
||
- decidir qué asset cargar o editar.
|
||
|
||
---
|
||
|
||
### `list_timeline`
|
||
|
||
Lista el estado actual del timeline.
|
||
|
||
```ts
|
||
{}
|
||
```
|
||
|
||
Uso:
|
||
- saber qué clips/textos/stickers/effects existen,
|
||
- obtener `trackId` y `elementId`,
|
||
- preparar operaciones como cortar, borrar o editar.
|
||
|
||
---
|
||
|
||
### `load_asset_context`
|
||
|
||
Carga un asset en el contexto multimodal del agente usando Gemini.
|
||
|
||
```ts
|
||
{
|
||
assetId: string;
|
||
}
|
||
```
|
||
|
||
Uso:
|
||
- subir/procesar video, audio o imagen con Gemini,
|
||
- dejar el asset disponible para razonamiento posterior,
|
||
- cachear la referencia para no subirlo repetidamente.
|
||
|
||
> Esta reemplaza la idea anterior de `analyze_video({ question })` o `analyze_asset({ analysisType })`. La tool no “pregunta”; solo carga el asset al contexto.
|
||
|
||
---
|
||
|
||
### `get_asset_context` *(infra interna, no tool visible)*
|
||
|
||
Recupera información/cache de un asset ya cargado.
|
||
|
||
```ts
|
||
{
|
||
assetId: string;
|
||
}
|
||
```
|
||
|
||
Uso:
|
||
- reutilizar análisis/contexto previo,
|
||
- evitar re-upload,
|
||
- permitir que el agente sepa si un asset ya está disponible para Gemini.
|
||
|
||
> Esta NO debería exponerse necesariamente como tool al LLM. Es más sano tratarla como infraestructura interna del agente/orquestador: `load_asset_context` carga y cachea; el orquestador/store puede consultar el cache e inyectar ese estado en el prompt/contexto sin hacer que el modelo llame una tool administrativa.
|
||
|
||
---
|
||
|
||
## Tools de edición primitivas
|
||
|
||
### `split`
|
||
|
||
Hace splits/cortes en uno o más puntos de tiempo del timeline, sin borrar contenido.
|
||
|
||
```ts
|
||
{
|
||
times: number[]; // timeline seconds
|
||
}
|
||
```
|
||
|
||
Uso:
|
||
- cortar en un punto específico,
|
||
- aislar una sección antes de borrarla con otra tool usando dos tiempos,
|
||
- preparar edición por rangos,
|
||
- separar intro/outro sin eliminar nada,
|
||
- dejarle al agente una primitive composable para flujos más grandes.
|
||
|
||
> `split` NO elimina material. Si el usuario pide “eliminá esta parte”, el agente debe componer `split` con `delete_timeline_elements`.
|
||
|
||
---
|
||
|
||
### `add_media_to_timeline`
|
||
|
||
Agrega un asset existente al timeline.
|
||
|
||
```ts
|
||
{
|
||
assetId: string;
|
||
startTime: number;
|
||
trackType: "main" | "overlay" | "audio";
|
||
}
|
||
```
|
||
|
||
Uso:
|
||
- insertar clips,
|
||
- agregar música,
|
||
- poner b-roll,
|
||
- agregar imágenes/logos.
|
||
|
||
---
|
||
|
||
### `delete_timeline_elements`
|
||
|
||
Elimina uno o más elementos específicos del timeline.
|
||
|
||
```ts
|
||
{
|
||
elementIds: string[];
|
||
}
|
||
```
|
||
|
||
Uso:
|
||
- borrar clips,
|
||
- borrar textos,
|
||
- borrar stickers,
|
||
- borrar efectos standalone si aplica.
|
||
|
||
> Para borrar un rango, el agente debe hacer `split({ times: [start, end] })`, volver a listar/identificar los elementos aislados si hace falta, y luego llamar `delete_timeline_elements`.
|
||
|
||
---
|
||
|
||
### `add_text`
|
||
|
||
Agrega texto visual al timeline.
|
||
|
||
```ts
|
||
{
|
||
text: string;
|
||
start: number;
|
||
end: number;
|
||
position: "top" | "center" | "bottom";
|
||
style?: "plain" | "subtitle" | "hook" | "label";
|
||
}
|
||
```
|
||
|
||
Uso:
|
||
- subtítulos,
|
||
- hooks,
|
||
- títulos,
|
||
- labels,
|
||
- texto explicativo.
|
||
|
||
---
|
||
|
||
### `update_text`
|
||
|
||
Actualiza un texto existente.
|
||
|
||
```ts
|
||
{
|
||
trackId: string;
|
||
elementId: string;
|
||
text?: string;
|
||
start?: number;
|
||
end?: number;
|
||
position?: "top" | "center" | "bottom";
|
||
}
|
||
```
|
||
|
||
Uso:
|
||
- corregir texto,
|
||
- cambiar timing,
|
||
- mover captions/hooks.
|
||
|
||
---
|
||
|
||
### `add_sticker`
|
||
|
||
Agrega un sticker al timeline.
|
||
|
||
```ts
|
||
{
|
||
stickerId: string;
|
||
start: number;
|
||
end: number;
|
||
position: "top-left" | "top-right" | "center" | "bottom-left" | "bottom-right";
|
||
}
|
||
```
|
||
|
||
Uso:
|
||
- agregar elementos visuales simples,
|
||
- reacciones,
|
||
- énfasis gráfico.
|
||
|
||
---
|
||
|
||
### `set_volume`
|
||
|
||
Ajusta volumen de un elemento de audio/video.
|
||
|
||
```ts
|
||
{
|
||
trackId: string;
|
||
elementId: string;
|
||
volume: number; // 0–1
|
||
}
|
||
```
|
||
|
||
Uso:
|
||
- bajar música,
|
||
- subir voz,
|
||
- mutear clip,
|
||
- balance básico.
|
||
|
||
---
|
||
|
||
### `apply_effect`
|
||
|
||
Aplica un efecto existente a un clip.
|
||
|
||
```ts
|
||
{
|
||
trackId: string;
|
||
elementId: string;
|
||
effectType: "blur";
|
||
params?: {
|
||
intensity?: number;
|
||
};
|
||
}
|
||
```
|
||
|
||
Uso:
|
||
- aplicar blur.
|
||
|
||
> El repo actualmente tiene infraestructura de efectos, pero el efecto real registrado parece ser solo `blur`. Corrección de color/LUTs todavía no está disponible.
|
||
|
||
---
|
||
|
||
## Tools existentes o en standby
|
||
|
||
### `transcribe_video`
|
||
|
||
Transcribe audio de video/audio usando Whisper local.
|
||
|
||
```ts
|
||
{
|
||
assetId?: string;
|
||
language?: string;
|
||
modelId?: string;
|
||
}
|
||
```
|
||
|
||
Uso:
|
||
- subtítulos,
|
||
- captions,
|
||
- búsqueda de frases exactas,
|
||
- edición por texto.
|
||
|
||
Estado:
|
||
- implementada,
|
||
- útil como herramienta secundaria,
|
||
- no debe ser la tool principal para entender el video si Gemini puede cargar el asset multimodalmente.
|
||
|
||
---
|
||
|
||
## Ideas descartadas o diferidas
|
||
|
||
### `analyze_video({ question })`
|
||
|
||
Descartada como primitive principal porque mete “chat dentro de la tool”. Mejor usar `load_asset_context` y dejar que el agente razone con el contexto cargado.
|
||
|
||
### `analyze_asset({ analysisType })`
|
||
|
||
Descartada porque `analysisType` introduce categorías artificiales. Gemini debe cargar el asset completo al contexto; el agente decide qué hacer después.
|
||
|
||
### `remove_silences`
|
||
|
||
Diferida/no prioritaria porque se puede expresar como flujo con `split` + `delete_timeline_elements`.
|
||
|
||
### `generate_subtitles`
|
||
|
||
Diferida porque se puede construir con `transcribe_video` + `add_text`.
|
||
|
||
### `color_correct` / `apply_lut`
|
||
|
||
Diferida porque el repo actual no parece tener corrección de color/LUTs implementados todavía.
|
||
|
||
---
|
||
|
||
## Orden recomendado
|
||
|
||
1. `list_project_assets`
|
||
2. `list_timeline`
|
||
3. `load_asset_context`
|
||
4. `split`
|
||
5. `delete_timeline_elements`
|
||
6. `add_text`
|
||
7. `add_media_to_timeline`
|
||
8. `set_volume`
|
||
9. `add_sticker`
|
||
10. `apply_effect`
|
||
|
||
Infra interna asociada:
|
||
|
||
- `get_asset_context` / cache lookup para `assetId -> Gemini fileUri/status/summary`, no necesariamente visible para el LLM.
|