Framework
El modelo conceptual: cómo se relacionan las 8 capas, de qué es responsable cada capa y los contratos entre ellas.
Propósito
Esta página es el modelo conceptual que une el lab. Describe las 8 capas, los contratos entre ellas y los patrones que implementan los componentes concretos del lab.
Las 8 capas se introducen en Arquitectura del sistema → El modelo de 8 capas. Esta página es la referencia más profunda.
El patrón
El lab sigue un patrón de orquestador en capas con estas propiedades:
- Cada capa tiene una única responsabilidad.
- Cada capa se comunica con las capas adyacentes a través de un contrato tipado.
- Cada capa es testeable de forma independiente.
- El orquestador es el único lugar que conoce múltiples capas.
El patrón es una generalización de la estructura del research framework (orquestador, fases, esquemas, adaptadores). El lab aplica el mismo patrón a niveles superiores (interfaz de usuario, coordinación, agentes).
Responsabilidades por capa
Capa 1: Interfaz de usuario
La interfaz de usuario es el canal en lenguaje natural entre el usuario y el Coordinator. Tiene tres responsabilidades:
- Parsear la petición en lenguaje natural del usuario.
- Renderizar la respuesta del Coordinator para el usuario.
- Mantener la sesión (historial, tarea actual, peticiones en curso).
La interfaz de usuario NO decide qué hacer con la petición. Esa es la labor del Coordinator.
La interfaz de usuario está implementada por el gateway del Coordinator y la capa de sesión del framework.
Capa 2: Coordinación
El Coordinator es la única capa que conoce múltiples agentes. Sus responsabilidades:
- Resolver el intent del usuario en una o más llamadas a agentes.
- Enrutar las llamadas a los agentes apropiados.
- Gestionar la sesión y la memoria.
- Agregar los resultados de múltiples agentes cuando la petición abarca varios.
- Loguear cada petición y cada respuesta.
El Coordinator NO ejecuta tareas. Es un router y un gestor de estado.
Capa 3: Agente
Cada agente es un rol especializado con sus propias herramientas y su propio ciclo de vida. Los agentes son:
- Coordinator — el agente de control principal.
- Coding Assistant — el brazo de implementación.
- Research Worker — el especialista en investigación.
- Media Agent — el especialista en entretenimiento.
- Web Agent — la capacidad de automatización de navegador.
Las responsabilidades de un agente son:
- Ejecutar las tareas que recibe.
- Usar las herramientas que tiene permitido invocar.
- Devolver un resultado estructurado al Coordinator.
- Loguear sus acciones para el audit trail.
Un agente NO llama a otros agentes directamente. Toda la comunicación inter-agente pasa por el Coordinator.
Capa 4: Framework
Un framework es un orquestador de dominio específico. El lab tiene dos:
- Research Framework — orquesta el DAG de fases de investigación.
- Coding Sub-agent — orquesta el flujo de escritura de código (pero la orquestación es mínima; el sub-agent hace la mayor parte del trabajo).
Las responsabilidades de un framework:
- Descomponer la tarea del agente en pasos.
- Planificar los pasos (secuencial, paralelo).
- Validar las entradas y salidas.
- Hacer checkpoint del estado entre pasos.
- Reintentar los pasos fallidos con backoff.
Un framework NO habla directamente con servicios externos. Delega en herramientas.
Capa 5: Herramienta
Una herramienta es una capacidad tipada y determinista. El lab tiene docenas de herramientas, organizadas por categoría:
- Media tools — torrent-finder, subtitle-finder, etc.
- Research tools — adaptadores de búsqueda, APIs de transcripción, etc.
- Web tools — la herramienta browser.
- Code tools — codex, git, npm, pytest.
Las responsabilidades de una herramienta:
- Aceptar una entrada tipada.
- Realizar una acción determinista.
- Devolver una salida tipada.
- Loguear su invocación para el audit trail.
Una herramienta NO razona sobre el intent del usuario. Hace lo que se le dice.
Capa 6: Adaptador
Un adaptador traduce una petición genérica de la herramienta al formato específico del proveedor. El lab tiene adaptadores para:
- Búsqueda — Tavily, DuckDuckGo, Google.
- Vídeo — YouTube Transcript, yt-dlp.
- Síntesis — Perplexity.
Las responsabilidades de un adaptador:
- Traducir la petición de la herramienta al formato del proveedor.
- Autenticar con el proveedor.
- Gestionar los límites de tasa del proveedor.
- Traducir la respuesta del proveedor de vuelta al formato de la herramienta.
Un adaptador NO razona sobre la petición. Es un traductor.
Capa 7: Estado
La capa de estado es donde el lab recuerda. El estado incluye:
- Memoria de largo plazo (
MEMORY.md). - Logs diarios (
memory/YYYY-MM-DD.md). - Session state (en memoria + ficheros de sesión).
- Skill artifacts (SKILL.md, TOOL.md).
- Research artifacts (las salidas tipadas del framework).
- Audit trail (request journal, mission state).
Las responsabilidades de la capa de estado:
- Persistir datos entre sesiones.
- Validar datos en lectura y escritura.
- Expirar datos según la política de retención.
- Proveer los datos a las capas que los necesitan.
Capa 8: Externa
La capa externa es todo con lo que el lab habla:
- Model providers — para el Coordinator y el coding sub-agent.
- Search providers — para los adaptadores de investigación.
- Streaming services — para el Media Agent.
- Dispositivos — dispositivos Cast, hosts VLC.
La capa externa no está bajo el control del lab. El lab gestiona los fallos externos mediante reintentos, fallbacks y el audit trail.
Contratos entre capas
Cada contrato entre capas adyacentes tiene:
- Dirección (arriba, abajo, ambas).
- Formato (JSON, function call, file I/O, etc.).
- Garantía (at-most-once, at-least-once, síncrona, etc.).
- Validación (esquema, tipo, rango, etc.).
Los contratos están documentados en Flujo de datos → Fronteras y datos.
Patrones
El lab reutiliza un pequeño conjunto de patrones:
Patrón Adapter
El patrón adapter traduce entre una interfaz genérica y una específica del proveedor. El patrón aparece en:
- Los adaptadores del research framework (Tavily, DuckDuckGo, etc.).
- Los backends Chromecast y VLC del Media Agent.
- La invocación CLI del coding sub-agent.
El patrón adapter está documentado en External Providers.
Patrón Orchestrator
El patrón orchestrator descompone una tarea compleja en pasos, los planifica y valida sus resultados. El patrón aparece en:
- El orquestador del research framework.
- El resolvedor de intent del Coordinator.
El patrón orchestrator está documentado en Research Framework.
Patrón Tool
El patrón tool envuelve una capacidad determinista en una interfaz tipada. El patrón aparece en:
- Las herramientas CLI del lab (torrent-finder, etc.).
- Los adaptadores MCP.
- Los adaptadores de investigación.
El patrón tool está documentado en Capa de Tooling.
Patrón Skill
El patrón skill describe una capacidad en un fichero markdown. El patrón aparece en:
- El skill loader del Coordinator.
- Los skills del coding sub-agent.
El patrón skill está documentado en Tool Spec.
Patrón Checkpoint
El patrón checkpoint persiste el estado de una tarea de larga duración a disco. El patrón aparece en:
- El mission state del research framework.
- El checkpoint de tool-a-research-init del coding sub-agent.
El patrón checkpoint está documentado en Mission Lifecycle → Checkpointing.
Dónde aparece el patrón
| Patrón | Instancia concreta |
|---|---|
| Adapter | Adaptadores de investigación, Cast, VLC, Perplexity |
| Orchestrator | Research framework, resolvedor de intent del Coordinator |
| Tool | Herramientas CLI, adaptadores MCP, adaptadores de investigación |
| Skill | Skills del Coordinator, skills del coding sub-agent |
| Checkpoint | Mission state de investigación, checkpoint de tool-a-research-init |
La reutilización de patrones es lo que hace coherente al lab. Un nuevo componente que sigue el mismo patrón es fácil de integrar; un nuevo componente que rompe el patrón es difícil.
Cómo extender el lab
Para extender el lab:
- Añadir una herramienta. Implementa un CLI o un adaptador MCP siguiendo el patrón de Capa de Tooling. Registra la herramienta en el
tools.jsonapropiado. - Añadir una herramienta de dominio al research framework. Crea un nuevo paquete bajo
docs/orchestrator/tools/con la estructura estándar. Regístrala en el orquestador. - Añadir un adaptador. Implementa un adaptador siguiendo el patrón de External Providers. Regístralo en el framework.
- Añadir un agente. Crea un nuevo agente con su propio gateway (si es necesario), sus propias herramientas y su propio contexto. Documenta las fronteras en Context Boundaries.
- Añadir un patrón. Documenta el patrón en esta página. Referéncialo desde las páginas existentes.
Los puntos de extensión están diseñados para ser pequeños y enfocados. Cada extensión debería tocar el menor número de ficheros posible.