Appendix C — Data Dictionary | Lab Notes

El data dictionary completo — cada field, cada type, cada constraint para las data structures que usa el lab.

Propósito

Este appendix es la referencia canónica para las data structures que usa el lab. Cada typed artifact, cada configuration file, cada log record y cada API request y response está documentado aquí.

El data dictionary es el companion de la página Artifacts y de la página External Providers → Request Journal.

Conventions

Los field names van en snake_case.
Los fields Required se marcan con R. Los opcionales con O.
Los Types son tipos Python Pydantic-compatibles.
Las Constraints se documentan cuando existen (min/max, regex, enum).

Research Framework Schemas

`Task`

La mission task. Producido por F0.

Field	Type	Required	Constraints
`mission_id`	string	R	UUID prefix o stable identifier.
`raw_query`	string	R	La user query original, verbatim.
`parsed`	`ParsedQuery`	R
`created_at`	datetime	R	UTC.
`config`	object	O	Per-mission configuration.

`ParsedQuery`

La mission query estructurada. Parte de Task.

Field	Type	Required	Constraints
`topic`	string	R	El primary research topic.
`location`	string \| null	O	El target location, si hay.
`period`	string \| null	O	El target date range o period.
`budget_max`	float \| null	O	El maximum budget, si hay.
`budget_currency`	string	R	ISO 4217 currency code (default `EUR`).
`constraints`	list[string]	O	Mission constraints adicionales.

`Candidate`

Un potential match para una research query. Producido por F1.

Field	Type	Required	Constraints
`id`	string	R	UUID prefix.
`name`	string	R	Display name.
`aliases`	list[string]	O	Alternative names encontrados.
`category`	string	R	`hotel`, `restaurant`, `product`, etc.
`source_ids`	list[string]	R	Los `Source.id` values.
`metadata`	object	O	Fields category-specific.
`confidence`	float	R	0.0 a 1.0.

`CandidateList`

Una lista de candidates. Producida por F1.

Field	Type	Required	Constraints
`mission_id`	string	R
`created_at`	datetime	R	UTC.
`candidates`	list[Candidate]	R
`sources`	list[Source]	R

`Source`

Una referencia a una URL con metadata. Producido por cada phase que usa un adapter.

Field	Type	Required	Constraints
`id`	string	R	UUID prefix.
`title`	string	R	El source title.
`url`	string	R	La canonical source URL.
`publisher`	string	R	El publisher o host.
`phase`	string	R	La phase que produjo este source.
`retrieved_at`	datetime	R	UTC.

`Evidence`

Una pieza de evidence que sostiene un finding. Usado a lo largo de las phases.

Field	Type	Required	Constraints
`id`	string	R	UUID prefix.
`source_id`	string	R	El `Source.id` que produjo este evidence.
`quote`	string	R	El evidence text.
`context`	string	O	El context en el que aparece el evidence.
`confidence`	float	R	0.0 a 1.0.

`EvidenceBundle`

Una colección de evidence items.

Field	Type	Required	Constraints
`mission_id`	string	R
`created_at`	datetime	R	UTC.
`items`	list[Evidence]	R

`Review`

Una review individual.

Field	Type	Required	Constraints
`id`	string	R	UUID prefix.
`source_id`	string	R	El `Source.id`.
`author`	string	O	El nombre del reviewer (si está disponible).
`rating`	float	O	0.0 a 5.0.
`text`	string	R	El review text.
`language`	string	R	ISO 639-1 code.
`published_at`	datetime	O	UTC.
`sentiment`	object	O	Distribución `positive`, `neutral`, `negative`.

`ReviewSummary`

Reviews agregadas. Producidas por F2.

Field	Type	Required	Constraints
`candidate_id`	string	R	El `Candidate.id`.
`total_reviews`	integer	R	Non-negative.
`average_rating`	float \| null	O	0.0 a 5.0.
`sentiment`	object	O	Distribución de sentiment.
`topics`	list[object]	O	Cada item: `topic`, `count`, `sentiment`.
`sources`	list[Source]	R	Sources usadas para el summary.

`PriceSnapshot`

Una price observation individual. Producida por F4.

Field	Type	Required	Constraints
`candidate_id`	string	R	El `Candidate.id`.
`price`	float	R	Positive.
`currency`	string	R	ISO 4217.
`observed_at`	datetime	R	UTC.
`provider`	string	R	El provider (p. ej., `booking.com`).
`url`	string	O	La URL de la price observation.

`PriceSeries`

Una serie de price observations. Producida por F4.

Field	Type	Required	Constraints
`candidate_id`	string	R	El `Candidate.id`.
`snapshots`	list[PriceSnapshot]	R
`min`	float \| null	O	Min price.
`max`	float \| null	O	Max price.
`median`	float \| null	O	Median price.
`trend`	string	O	`up`, `down`, `flat`, `unknown`.
`sources`	list[Source]	R	Sources usadas para la series.

`Transcript`

Un video transcript. Producido por Y2.

Field	Type	Required	Constraints
`video_id`	string	R	YouTube video ID.
`url`	string	R	Video URL.
`language`	string	R	ISO 639-1 code.
`chunks`	list[TranscriptChunk]	R
`full_text`	string	R	Plain text concatenado.
`source`	string	R	`youtube_transcript_api` o `yt_dlp`.

`TranscriptChunk`

Un chunk de un transcript.

Field	Type	Required	Constraints
`start_s`	float	R	Start time en segundos.
`end_s`	float	R	End time en segundos.
`text`	string	R	Chunk text.

`PhaseResult`

El envelope para cada phase output.

Field	Type	Required	Constraints
`phase`	string	R	Phase identifier (p. ej., `f1_candidates`).
`status`	`PhaseStatus`	R	Lifecycle status.
`started_at`	datetime \| null	O	UTC.
`ended_at`	datetime \| null	O	UTC.
`attempts`	integer	O	Default `1`.
`output_artifacts`	list[string]	O	Artifact filenames producidos.
`errors`	list[object]	O	Cada item: `code`, `message`, `retryable`.
`metadata`	object	O	Metadata phase-specific.

`PhaseStatus` Enum

Value	Meaning
`pending`	La phase no ha empezado aún.
`running`	La phase se está ejecutando.
`succeeded`	La phase terminó y produjo todos los expected outputs.
`succeeded_partial`	La phase terminó pero faltan algunos outputs.
`failed_retryable`	La phase falló pero se puede reintentar.
`failed_terminal`	La phase falló y no se puede reintentar.
`skipped`	La phase fue intencionalmente no ejecutada.
`blocked_missing_input`	La phase no pudo empezar porque falta un input.
`stale`	El input de la phase se actualizó después de que corrió.

Mission State (`phase.json`)

El mission state. Lo escribe el orchestrator después de cada phase.

Field	Type	Required	Constraints
`mission_id`	string	R
`status`	string	R	`running`, `paused`, `completed`, `failed`.
`current_phase`	string \| null	O	La phase que está corriendo o acaba de terminar.
`phases`	object	R	Keyed por phase name; cada value es un phase record.
`created_at`	datetime	R	UTC.
`updated_at`	datetime	R	UTC.

Phase Record

Field	Type	Required	Constraints
`status`	`PhaseStatus`	R
`started_at`	datetime \| null	O	UTC.
`ended_at`	datetime \| null	O	UTC.
`attempts`	integer	O	Default `1`.
`output_artifacts`	list[string]	O	Artifact filenames producidos.
`error`	object	O	`code`, `message`, `retryable`.

Request Journal

El request journal record.

Field	Type	Required	Constraints
`ts`	datetime	R	UTC, ISO 8601 con millisecond precision.
`mission_id`	string	R
`phase`	string	R
`adapter`	string	R	`tavily`, `duckduckgo`, `google_search`, `youtube_transcript`, `yt_dlp`, `perplexity`.
`action`	string	R	`search`, `transcript`, `synthesize`, etc.
`token_name`	string \| null	O	El name del token usado. Nunca el value.
`request`	object	R	Redacted si contiene personal data.
`response_summary`	object	R	`status`, `items`, `duration_ms`, etc.
`result`	string	R	`succeeded`, `failed`, `partial`.
`error`	string \| null	O	Error message si `result` es `failed`.
`cost`	object	O	`tokens`, `usd`, etc., si aplica.

Token Pool State

El token pool state record.

Field	Type	Required	Constraints
`name`	string	R	El friendly name del token.
`total_requests`	integer	R	Cumulative.
`total_errors`	integer	R	Cumulative.
`last_error`	string \| null	O	Sanitized error message.
`last_success_at`	datetime \| null	O	UTC.
`status`	string	R	`active`, `quota_exhausted`, `error`.

Coordinator API

La HTTP API del Coordinator. La API completa está en Coordinator → User interface.

Request: `POST /v1/session/<id>/message`

Field	Type	Required	Constraints
`content`	string	R	El message del usuario.
`attachments`	list[object]	O	File attachments opcionales.

Response: `200 OK`

Field	Type	Required	Constraints
`request_id`	string	R
`content`	string	R	La response del Coordinator.
`attachments`	list[object]	O	File attachments opcionales.
`agent_calls`	list[object]	O	Las agent calls que se despacharon.

Scout API

La HTTP API del Scout. La API completa está en Research Worker → Configuration.

Request: `POST /v1/missions`

Field	Type	Required	Constraints
`mission_id`	string	R
`query`	string	R
`config`	object	O	Per-mission configuration.

Response: `200 OK`

Field	Type	Required	Constraints
`mission_id`	string	R
`status`	string	R	`accepted`, `rejected`.
`report_path`	string	O	Path al report (cuando termina).

Configuration Files

`openclaw.json`

El main configuration file. Sanitized example:

{
  "agents": {
    "defaults": {
      "workspace": "{workspace-root}",
      "model": {
        "primary": "minimax-portal/MiniMax-M3"
      },
      "heartbeat": {
        "every": "30m",
        "timeoutSeconds": 120,
        "lightContext": true,
        "isolatedSession": true
      }
    },
    "list": [
      {
        "id": "main",
        "workspace": "{workspace-root}",
        "model": {
          "primary": "minimax-portal/MiniMax-M3"
        }
      },
      {
        "id": "scout",
        "workspace": "{workspace-root-scout}",
        "model": {
          "primary": "minimax-portal/MiniMax-M3"
        }
      }
    ]
  }
}

`token_pool_config.json`

El token pool configuration.

Field	Type	Required	Constraints
`providers`	object	R	Keyed por provider name.
`providers.<name>.tokens`	list[object]	R	Los tokens para el provider.
`providers.<name>.strategy`	string	R	`round-robin`, `weighted-round-robin`, `least-used`, `failover`.

`tools.json`

El tool registry para un proyecto.

Field	Type	Required	Constraints
`version`	string	R	Semantic version.
`tools`	list[object]	R	Las tool entries.
`tools[].name`	string	R
`tools[].description`	string	R
`tools[].location`	string	R	Path al entry point de la tool.
`tools[].status`	string	R	`ready`, `planned`, `deprecated`.
`tools[].capabilities`	list[string]	R
`tools[].tags`	list[string]	R