Artifacts

The typed files a research mission writes to disk. Each artifact is validated by a Pydantic schema. The framework's auditability depends on every artifact being typed, versioned, and reproducible.

Purpose

This page lists the artifacts that the research framework produces, where they live, what schema validates them, and what they are used for. The phases that produce them are in Mission DAG; the lifecycle is in Mission Lifecycle.

Run directory layout

Every mission writes to a single directory:

<runs_dir>/<mission_id>/
├── task.json
├── phase.json
├── candidates.json
├── reviews.json
├── prices.json
├── youtube_search.json
├── transcripts.json
├── synthesis.json           # only if P3 ran
├── report.md
└── logs/
    └── mission.log

Each JSON artifact is validated by a Pydantic schema on write. Invalid artifacts are rejected with a clear error message.

`task.json`

The mission task. Produced by F0.

Field	Type	Description
`mission_id`	string	Stable mission identifier.
`raw_query`	string	The original user-supplied query, verbatim.
`parsed`	`ParsedQuery`	The parsed structure (topic, location, etc.).
`created_at`	datetime (UTC)	When the task was created.
`config`	object	Optional run configuration (flags, overrides).

ParsedQuery:

Field	Type	Description
`topic`	string	Primary research topic.
`location`	string \| null	Target location, if any.
`period`	string \| null	Target date range or period.
`budget_max`	float \| null	Maximum budget, if any.
`budget_currency`	string	ISO-style currency code (default `EUR`).
`constraints`	list[string]	Additional constraints.

`candidates.json`

The candidate list. Produced by F1.

Field	Type	Description
`mission_id`	string	Back-reference to the task.
`created_at`	datetime (UTC)	When the list was finalized.
`candidates`	list[Candidate]	The deduplicated, normalized candidates.
`sources`	list[Source]	All sources used to discover the candidates.

Candidate:

Field	Type	Description
`id`	string	Stable candidate ID (UUID prefix).
`name`	string	Display name.
`aliases`	list[string]	Alternative names found.
`category`	string	Candidate category (e.g., `hotel`, `restaurant`).
`source_ids`	list[string]	The `Source.id` values that produced this candidate.
`metadata`	object	Free-form metadata (depends on category).
`confidence`	float	Confidence score from 0.0 to 1.0.

`reviews.json`

Aggregated reviews. Produced by F2.

Field	Type	Description
`mission_id`	string	Back-reference.
`created_at`	datetime (UTC)	When the summary was finalized.
`summaries`	list[ReviewSummary]	One summary per candidate.
`partial`	bool	Whether any reviews were missing.

ReviewSummary:

Field	Type	Description
`candidate_id`	string	Back-reference to the candidate.
`total_reviews`	integer	Number of reviews aggregated.
`average_rating`	float \| null	Average rating on the original scale.
`sentiment`	object	Sentiment distribution (positive, neutral, negative).
`topics`	list[object]	Topic aggregates (topic, count, sentiment).
`sources`	list[Source]	Sources used for the summary.

`prices.json`

Price series. Produced by F4.

Field	Type	Description
`mission_id`	string	Back-reference.
`created_at`	datetime (UTC)	When the series was finalized.
`currency`	string	ISO-style currency code.
`series`	list[PriceSeries]	One series per candidate.
`partial`	bool	Whether any prices were missing.

PriceSeries:

Field	Type	Description
`candidate_id`	string	Back-reference.
`snapshots`	list[PriceSnapshot]	Time-stamped price observations.
`min`	float \| null	Minimum observed price.
`max`	float \| null	Maximum observed price.
`median`	float \| null	Median price.
`trend`	string	`up`, `down`, `flat`, or `unknown`.
`sources`	list[Source]	Sources used for the series.

`youtube_search.json`

YouTube search hits. Produced by Y1.

Field	Type	Description
`mission_id`	string	Back-reference.
`created_at`	datetime (UTC)	When the search ran.
`results`	list[object]	One record per video found.
`partial`	bool	Whether any searches failed.

Each result has: candidate_id, video_id, title, channel, url, published_at, duration_s, view_count, relevance_score.

`transcripts.json`

YouTube transcripts. Produced by Y2.

Field	Type	Description
`mission_id`	string	Back-reference.
`created_at`	datetime (UTC)	When the extraction ran.
`transcripts`	list[Transcript]	One transcript per video.
`partial`	bool	Whether any extractions failed.

Transcript:

Field	Type	Description
`video_id`	string	YouTube video ID.
`url`	string	Video URL.
`language`	string	Transcript language.
`chunks`	list[TranscriptChunk]	Time-stamped chunks.
`full_text`	string	Concatenated plain text.
`source`	string	`youtube_transcript_api` or `yt_dlp`.

`synthesis.json` (optional)

Narrative summaries. Produced by P3 (Perplexity).

Field	Type	Description
`mission_id`	string	Back-reference.
`created_at`	datetime (UTC)	When the synthesis ran.
`summaries`	list[object]	One narrative per top candidate.
`tokens_used`	integer	Total tokens consumed by Perplexity.

Each summary has: candidate_id, summary (narrative text), highlights (list of strings), caveats (list of strings).

Marks the current phase as failed_terminal.
Writes the validation error to the state.
Halts the mission.

The Coordinator surfaces the error to the user. The user can either:

Fix the data and retry.
Skip the phase (if allow_partial is true) and continue.
Cancel the mission.

Reproducibility

A mission is reproducible if and only if:

The same task.json is used as the input.
All adapter responses are deterministic for the same query at the same time (true for DuckDuckGo, approximately true for Tavily and Google, false for Perplexity).

The framework does not guarantee reproducibility, but the audit trail makes it possible to detect divergence and investigate.

Purpose

Run directory layout

`task.json`

`candidates.json`

`reviews.json`

`prices.json`

`youtube_search.json`

`transcripts.json`

`synthesis.json` (optional)

`report.md`

`phase.json`

Validation

Reproducibility

See also

On this page