Artifacts

Los typed files que una research mission escribe a disco. Cada artifact se valida con un Pydantic schema. La auditability del framework depende de que cada artifact sea typed, versioned y reproducible.

Propósito

Esta página lista los artifacts que el research framework produce, dónde viven, qué schema los valida y para qué se usan. Las phases que los producen están en Mission DAG; el lifecycle está en Mission Lifecycle.

Run directory layout

Cada mission escribe a un único directory:

<runs_dir>/<mission_id>/
├── task.json
├── phase.json
├── candidates.json
├── reviews.json
├── prices.json
├── youtube_search.json
├── transcripts.json
├── synthesis.json           # solo si P3 corrió
├── report.md
└── logs/
    └── mission.log

Cada JSON artifact se valida con un Pydantic schema al escribir. Los artifacts inválidos se rechazan con un clear error message.

`task.json`

La mission task. Producido por F0.

Field	Type	Description
`mission_id`	string	Stable mission identifier.
`raw_query`	string	La query original del usuario, verbatim.
`parsed`	`ParsedQuery`	La parsed structure (topic, location, etc.).
`created_at`	datetime (UTC)	Cuándo se creó la task.
`config`	object	Run configuration opcional (flags, overrides).

ParsedQuery:

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

`candidates.json`

La candidate list. Producida por F1.

Field	Type	Description
`mission_id`	string	Back-reference a la task.
`created_at`	datetime (UTC)	Cuándo se finalizó la list.
`candidates`	list[Candidate]	Los candidates deduplicados y normalizados.
`sources`	list[Source]	Todas las sources usadas para descubrir los candidates.

Candidate:

Field	Type	Description
`id`	string	Stable candidate ID (UUID prefix).
`name`	string	Display name.
`aliases`	list[string]	Alternative names encontrados.
`category`	string	Candidate category (p. ej., `hotel`, `restaurant`).
`source_ids`	list[string]	Los `Source.id` values que produjeron este candidate.
`metadata`	object	Free-form metadata (depende de category).
`confidence`	float	Confidence score de 0.0 a 1.0.

`reviews.json`

Reviews agregadas. Producidas por F2.

Field	Type	Description
`mission_id`	string	Back-reference.
`created_at`	datetime (UTC)	Cuándo se finalizó el summary.
`summaries`	list[ReviewSummary]	Un summary per candidate.
`partial`	bool	Si falta alguna review.

ReviewSummary:

Field	Type	Description
`candidate_id`	string	Back-reference al candidate.
`total_reviews`	integer	Número de reviews agregadas.
`average_rating`	float \| null	Average rating en la scale original.
`sentiment`	object	Distribución de sentiment (positive, neutral, negative).
`topics`	list[object]	Topic aggregates (topic, count, sentiment).
`sources`	list[Source]	Sources usadas para el summary.

`prices.json`

Price series. Producidas por F4.

Field	Type	Description
`mission_id`	string	Back-reference.
`created_at`	datetime (UTC)	Cuándo se finalizó la series.
`currency`	string	ISO-style currency code.
`series`	list[PriceSeries]	Una series per candidate.
`partial`	bool	Si falta algún price.

PriceSeries:

Field	Type	Description
`candidate_id`	string	Back-reference.
`snapshots`	list[PriceSnapshot]	Observaciones de price time-stamped.
`min`	float \| null	Minimum observed price.
`max`	float \| null	Maximum observed price.
`median`	float \| null	Median price.
`trend`	string	`up`, `down`, `flat`, o `unknown`.
`sources`	list[Source]	Sources usadas para la series.

`youtube_search.json`

YouTube search hits. Producido por Y1.

Field	Type	Description
`mission_id`	string	Back-reference.
`created_at`	datetime (UTC)	Cuándo corrió la search.
`results`	list[object]	Un record per video encontrado.
`partial`	bool	Si alguna search falló.

Cada result tiene: candidate_id, video_id, title, channel, url, published_at, duration_s, view_count, relevance_score.

`transcripts.json`

YouTube transcripts. Producido por Y2.

Field	Type	Description
`mission_id`	string	Back-reference.
`created_at`	datetime (UTC)	Cuándo corrió la extraction.
`transcripts`	list[Transcript]	Un transcript per video.
`partial`	bool	Si alguna extraction falló.

Transcript:

Field	Type	Description
`video_id`	string	YouTube video ID.
`url`	string	Video URL.
`language`	string	Transcript language.
`chunks`	list[TranscriptChunk]	Chunks time-stamped.
`full_text`	string	Plain text concatenado.
`source`	string	`youtube_transcript_api` o `yt_dlp`.

`synthesis.json` (optional)

Narrative summaries. Producido por P3 (Perplexity).

Field	Type	Description
`mission_id`	string	Back-reference.
`created_at`	datetime (UTC)	Cuándo corrió la synthesis.
`summaries`	list[object]	Un narrative per top candidate.
`tokens_used`	integer	Total tokens consumidos por Perplexity.

Cada summary tiene: candidate_id, summary (narrative text), highlights (list of strings), caveats (list of strings).

Marca la current phase como failed_terminal.
Escribe el validation error al state.
Detiene la mission.

El Coordinator surface el error al usuario. El usuario puede:

Arreglar los datos y reintentar.
Saltarse la phase (si allow_partial es true) y continuar.
Cancelar la mission.

Reproducibility

Una mission es reproducible si y solo si:

Se usa el mismo task.json como input.
Todas las adapter responses son deterministas para la misma query al mismo tiempo (true para DuckDuckGo, aproximadamente true para Tavily y Google, false para Perplexity).

El framework no garantiza reproducibility, pero el audit trail hace posible detectar divergence e investigar.

Propósito

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