Flujo de datos

Los datos que se mueven por el lab: qué cruza cada frontera, en qué formato y con qué garantías.

Propósito

Esta página documenta el flujo de datos a través de la arquitectura del lab. Complementa la Vista general del sistema y la Arquitectura del sistema con detalles concretos sobre los datos que cruzan cada frontera, en qué formato y con qué garantías.

Fronteras y datos

El lab tiene 8 capas (ver Arquitectura del sistema → El modelo de 8 capas). Los datos cruzan las fronteras entre estas capas. Cada cruce tiene un formato, una dirección y un conjunto de garantías.

Frontera	Dirección	Formato	Garantía
User ↔ Coordinator	Ambas	Lenguaje natural	Best effort
Coordinator ↔ Agent	Abajo	Request (JSON)	At-most-once
Agent ↔ Coordinator	Arriba	Response (JSON)	At-least-once
Agent ↔ Framework	Abajo	Method call	Síncrona
Framework ↔ Tool	Abajo	Function call	Síncrona
Tool ↔ Adapter	Abajo	Function call	Síncrona
Adapter ↔ External	Abajo	HTTP/HTTPS	Por adaptador
Coordinator ↔ State	Ambas	File I/O	Atomic write
Framework ↔ State	Ambas	File I/O	Atomic write

Las garantías se documentan en detalle más abajo.

User ↔ Coordinator

El usuario se comunica con el Coordinator en lenguaje natural. El Coordinator parsea la petición, resuelve el intent y devuelve una respuesta en lenguaje natural.

Aspecto	Detalle
Formato	Lenguaje natural (texto UTF-8).
Dirección	Ambas.
Codificación	UTF-8.
Límite tamaño	Ninguno aplicado (el Coordinator trunca entradas muy largas).
Garantía	Best effort. El Coordinator puede malinterpretar peticiones ambiguas.
Logging	El Coordinator loguea cada petición y respuesta.

El Coordinator puede devolver artefactos (rutas de ficheros, imágenes, etc.) junto con la respuesta en lenguaje natural.

Coordinator ↔ Agent

El Coordinator dispatcha una petición a un agente a través de su interfaz pública. El formato es JSON.

Aspecto	Detalle
Formato	JSON.
Dirección	Abajo (request) y arriba (response).
Codificación	UTF-8.
Límite tamaño	1 MB por mensaje (configurable).
Garantía	At-most-once (el Coordinator no reintenta).
Timeout	60s (configurable por agente).
Logging	El Coordinator loguea la petición y la respuesta.

El esquema de request es:

{
  "request_id": "string",
  "agent": "string",
  "task": "string",
  "params": "object",
  "context": "object"
}

El esquema de response es:

{
  "request_id": "string",
  "status": "ok | failed | partial",
  "result": "object",
  "error": "string | null",
  "duration_ms": "integer"
}

Agent ↔ Framework

El agente invoca el framework a través de method calls. Las llamadas son síncronas.

Aspecto	Detalle
Formato	Method call en proceso.
Dirección	Abajo.
Codificación	Objetos Python nativos.
Límite tamaño	Sin límite duro (los artefactos grandes se escriben a disco).
Garantía	Síncrona; el agente espera el resultado del framework.
Logging	El framework loguea cada llamada.

La API pública del Research Framework está documentada en Research Framework → Source layout.

Framework ↔ Tool

El framework invoca herramientas a través de function calls. Las llamadas son síncronas y devuelven resultados tipados.

Aspecto	Detalle
Formato	Function call con argumentos tipados.
Dirección	Abajo.
Codificación	Objetos Python nativos.
Límite tamaño	Sin límite duro.
Garantía	Síncrona; el framework espera el resultado de la herramienta.
Logging	La herramienta loguea cada invocación.

El contrato de herramienta está documentado en Capa de Tooling.

Tool ↔ Adapter

Una herramienta que necesita hablar con un servicio externo invoca un adaptador. El adaptador traduce la petición genérica de la herramienta al formato específico del proveedor.

Aspecto	Detalle
Formato	Function call con argumentos tipados.
Dirección	Abajo.
Codificación	Objetos Python nativos.
Límite tamaño	Sin límite duro.
Garantía	Síncrona; la herramienta espera el resultado del adaptador.
Logging	El adaptador loguea cada llamada en el request journal.

El contrato de adaptador está documentado en External Providers → Adapter contract.

Adapter ↔ External

El adaptador habla con el servicio externo a través de HTTP o HTTPS. El formato y las garantías dependen del proveedor.

Aspecto	Detalle
Formato	HTTP / HTTPS.
Dirección	Abajo.
Codificación	JSON (la mayoría de proveedores) o form-encoded.
Límite tamaño	Por proveedor (típicamente 1-10 MB por request).
Garantía	Por adaptador (el adaptador gestiona los reintentos).
Timeout	30s por request (configurable por adaptador).
Logging	El adaptador loguea cada llamada en el request journal.

El request journal está documentado en External Providers → Request journal.

Coordinator ↔ State

El Coordinator lee y escribe la capa de estado. La capa de estado incluye MEMORY.md, los logs diarios, el session state y los skill artifacts.

Aspecto	Detalle
Formato	Markdown (para `MEMORY.md` y logs diarios) o JSON (para session state y skill artifacts).
Dirección	Ambas.
Codificación	UTF-8.
Límite tamaño	1 MB por fichero (el Coordinator parte ficheros más grandes).
Garantía	Atomic write (el Coordinator escribe a un fichero temp y renombra).
Logging	El Coordinator loguea cada lectura y cada escritura.

La capa de estado está documentada en Memoria y contexto.

Framework ↔ State

El framework lee y escribe la capa de estado para los artefactos de investigación. Los artefactos son ficheros JSON validados por esquemas de Pydantic.

Aspecto	Detalle
Formato	JSON (validado por esquemas de Pydantic).
Dirección	Ambas.
Codificación	UTF-8.
Límite tamaño	Sin límite duro.
Garantía	Atomic write; validación en lectura y escritura.
Logging	El framework loguea cada lectura y cada escritura.

Los esquemas de artefactos están documentados en Artifacts y el Diccionario de datos.

Flujo de datos end-to-end

El flujo de datos end-to-end para una petición de investigación es:

Loading diagram…

Flujo de investigación end-to-end — cada cruce de datos es auditable.

El flujo muestra cada cruce de datos. Cada cruce es auditable.

Persistencia de datos

El lab persiste datos en las siguientes ubicaciones:

Dato	Ubicación	Formato
Memoria de largo plazo	`{workspace-root}/MEMORY.md`	Markdown
Logs diarios	`{workspace-root}/memory/YYYY-MM-DD.md`	Markdown
Session state	`{workspace-root}/sessions/<id>/session.json`	JSON
Skill artifacts	`{workspace-root}/skills/...`	Markdown
Research artifacts	`{research-root}/runs/<mission_id>/*`	JSON
Request journal	`{framework-root}/runtime/request_journal.jsonl`	JSONL
Token pool state	`{framework-root}/runtime/token_pool_state.json`	JSON
Mission state	`{research-root}/runs/<mission_id>/phase.json`	JSON
Audit reports	`{workspace-root}/security/audits/...`	Markdown

La política de retención está documentada en Mission Lifecycle → Retention and archival.