Appendix C — Data Dictionary | Lab Notes

The complete data dictionary — every field, every type, every constraint for the data structures used in the lab.

Purpose

This appendix is the canonical reference for the data structures used in the lab. Every typed artifact, every configuration file, every log record, and every API request and response is documented here.

The data dictionary is the companion to the Artifacts page and the External Providers → Request Journal page.

Conventions

Field names are in snake_case.
Required fields are marked with R. Optional fields are marked with O.
Types are Pydantic-compatible Python types.
Constraints are documented when they exist (min/max, regex, enum).

Research Framework Schemas

`Task`

The mission task. Produced by F0.

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

`ParsedQuery`

The structured mission query. Part of Task.

Field	Type	Required	Constraints
`topic`	string	R	The primary research topic.
`location`	string \| null	O	The target location, if any.
`period`	string \| null	O	The target date range or period.
`budget_max`	float \| null	O	The maximum budget, if any.
`budget_currency`	string	R	ISO 4217 currency code (default `EUR`).
`constraints`	list[string]	O	Additional mission constraints.

`Candidate`

A potential match for a research query. Produced by F1.

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

`CandidateList`

A list of candidates. Produced by F1.

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

`Source`

A reference to a URL with metadata. Produced by every phase that uses an adapter.

Field	Type	Required	Constraints
`id`	string	R	UUID prefix.
`title`	string	R	The source title.
`url`	string	R	The canonical source URL.
`publisher`	string	R	The publisher or host.
`phase`	string	R	The phase that produced this source.
`retrieved_at`	datetime	R	UTC.

`Evidence`

A piece of evidence supporting a finding. Used across phases.

Field	Type	Required	Constraints
`id`	string	R	UUID prefix.
`source_id`	string	R	The `Source.id` that produced this evidence.
`quote`	string	R	The evidence text.
`context`	string	O	The context in which the evidence appears.
`confidence`	float	R	0.0 to 1.0.

`EvidenceBundle`

A collection of evidence items.

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

`Review`

A single review.

Field	Type	Required	Constraints
`id`	string	R	UUID prefix.
`source_id`	string	R	The `Source.id`.
`author`	string	O	The reviewer's name (if available).
`rating`	float	O	0.0 to 5.0.
`text`	string	R	The review text.
`language`	string	R	ISO 639-1 code.
`published_at`	datetime	O	UTC.
`sentiment`	object	O	`positive`, `neutral`, `negative` distribution.

`ReviewSummary`

Aggregated reviews. Produced by F2.

Field	Type	Required	Constraints
`candidate_id`	string	R	The `Candidate.id`.
`total_reviews`	integer	R	Non-negative.
`average_rating`	float \| null	O	0.0 to 5.0.
`sentiment`	object	O	Sentiment distribution.
`topics`	list[object]	O	Each item: `topic`, `count`, `sentiment`.
`sources`	list[Source]	R	Sources used for the summary.

`PriceSnapshot`

A single price observation. Produced by F4.

Field	Type	Required	Constraints
`candidate_id`	string	R	The `Candidate.id`.
`price`	float	R	Positive.
`currency`	string	R	ISO 4217.
`observed_at`	datetime	R	UTC.
`provider`	string	R	The provider (e.g., `booking.com`).
`url`	string	O	The URL of the price observation.

`PriceSeries`

A series of price observations. Produced by F4.

Field	Type	Required	Constraints
`candidate_id`	string	R	The `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 used for the series.

`Transcript`

A video transcript. Produced by 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	Concatenated plain text.
`source`	string	R	`youtube_transcript_api` or `yt_dlp`.

`TranscriptChunk`

A chunk of a transcript.

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

`PhaseResult`

The envelope for every phase output.

Field	Type	Required	Constraints
`phase`	string	R	Phase identifier (e.g., `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 produced.
`errors`	list[object]	O	Each item: `code`, `message`, `retryable`.
`metadata`	object	O	Phase-specific metadata.

`PhaseStatus` Enum

Value	Meaning
`pending`	The phase has not started yet.
`running`	The phase is currently executing.
`succeeded`	The phase completed and produced all expected outputs.
`succeeded_partial`	The phase completed but some outputs are missing.
`failed_retryable`	The phase failed but can be retried.
`failed_terminal`	The phase failed and cannot be retried.
`skipped`	The phase was intentionally not executed.
`blocked_missing_input`	The phase could not start because an input is missing.
`stale`	The phase's input was updated after the phase ran.

Mission State (`phase.json`)

The mission state. Written by the orchestrator after every phase.

Field	Type	Required	Constraints
`mission_id`	string	R
`status`	string	R	`running`, `paused`, `completed`, `failed`.
`current_phase`	string \| null	O	The phase that is running or just completed.
`phases`	object	R	Keyed by phase name; each value is a 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 produced.
`error`	object	O	`code`, `message`, `retryable`.

Request Journal

The request journal record.

Field	Type	Required	Constraints
`ts`	datetime	R	UTC, ISO 8601 with 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	The name of the token used. Never the value.
`request`	object	R	Redacted if it contains personal data.
`response_summary`	object	R	`status`, `items`, `duration_ms`, etc.
`result`	string	R	`succeeded`, `failed`, `partial`.
`error`	string \| null	O	Error message if `result` is `failed`.
`cost`	object	O	`tokens`, `usd`, etc., if applicable.

Token Pool State

The token pool state record.

Field	Type	Required	Constraints
`name`	string	R	The token's friendly name.
`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

The Coordinator's HTTP API. The full API is in Coordinator → User interface.

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

Field	Type	Required	Constraints
`content`	string	R	The user's message.
`attachments`	list[object]	O	Optional file attachments.

Response: `200 OK`

Field	Type	Required	Constraints
`request_id`	string	R
`content`	string	R	The Coordinator's response.
`attachments`	list[object]	O	Optional file attachments.
`agent_calls`	list[object]	O	The agent calls that were dispatched.

Scout API

The Scout's HTTP API. The full API is in 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 to the report (when complete).

Configuration Files

`openclaw.json`

The 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`

The token pool configuration.

Field	Type	Required	Constraints
`providers`	object	R	Keyed by provider name.
`providers.<name>.tokens`	list[object]	R	The tokens for the provider.
`providers.<name>.strategy`	string	R	`round-robin`, `weighted-round-robin`, `least-used`, `failover`.

`tools.json`

The tool registry for a project.

Field	Type	Required	Constraints
`version`	string	R	Semantic version.
`tools`	list[object]	R	The tool entries.
`tools[].name`	string	R
`tools[].description`	string	R
`tools[].location`	string	R	Path to the tool's entry point.
`tools[].status`	string	R	`ready`, `planned`, `deprecated`.
`tools[].capabilities`	list[string]	R
`tools[].tags`	list[string]	R

Appendix C — Data Dictionary

Purpose

Conventions

Research Framework Schemas

`Task`

`ParsedQuery`

`Candidate`

`CandidateList`

`Source`

`Evidence`

`EvidenceBundle`

`Review`

`ReviewSummary`

`PriceSnapshot`

`PriceSeries`

`Transcript`

`TranscriptChunk`

`PhaseResult`

`PhaseStatus` Enum

Mission State (`phase.json`)

Phase Record

Request Journal

Token Pool State

Coordinator API

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

Response: `200 OK`

Scout API

Request: `POST /v1/missions`

Response: `200 OK`

Configuration Files

`openclaw.json`

`token_pool_config.json`

`tools.json`

See also

On this page