Research Framework

Status

Implemented. El orchestrator, las 8 phases, los 6 schemas, los 5 search adapters y las 7 domain tools están operational. El framework lo ejercita el Research Worker; el usuario típicamente interactúa con él a través de natural-language requests que el Coordinator forward.

Propósito

El Research Framework responde multi-step research questions ("find hotels in Barcelona for next September under 200 EUR with good reviews") haciendo:

1. Parsea la request en un Task estructurado.
2. Corre un phase DAG determinista que produce typed artifacts.
3. Agrega los artifacts en un report final.
4. Persiste la run para que se pueda resumir, auditar o reusar.

El framework es deterministic at the orchestration level (el DAG no branchea sobre el output del model) y probabilistic at the content level (los adapters y la synthesis pueden devolver resultados distintos para el mismo input). Este split es el design principle que hace el framework auditable.

Architecture

El framework tiene cuatro layers, cada una testeable de forma aislada:

Source layout

El framework vive en un único Python package con la siguiente estructura:

{framework-root}/
├── pyproject.toml
├── uv.lock
├── .agents/
│   └── skills/
│       └── scout-orchestrate/
│           └── SKILL.md
├── scout/
│   ├── __init__.py
│   ├── orchestrator/
│   │   ├── __init__.py
│   │   ├── dag.py
│   │   ├── runner.py
│   │   ├── state_store.py
│   │   ├── artifact_store.py
│   │   └── mission_runner.py
│   ├── phases/
│   │   ├── __init__.py
│   │   ├── f0_init.py
│   │   ├── f1_candidates.py
│   │   ├── f2_reviews.py
│   │   ├── f4_price.py
│   │   ├── p3_perplexity_synthesis.py
│   │   ├── y1_youtube.py
│   │   ├── y2_extract.py
│   │   └── f6_report.py
│   ├── schemas/
│   │   ├── __init__.py
│   │   ├── task.py
│   │   ├── candidates.py
│   │   ├── evidence.py
│   │   ├── sources.py
│   │   ├── reviews.py
│   │   ├── prices.py
│   │   ├── transcripts.py
│   │   └── phase_result.py
│   └── tools/
│       ├── __init__.py
│       ├── research_cli.py
│       ├── run_research.py
│       ├── run_research.sh
│       ├── perplexity_adapter.py
│       └── adapters/
│           ├── __init__.py
│           ├── tavily_adapter.py
│           ├── duckduckgo_adapter.py
│           ├── google_search_adapter.py
│           ├── youtube_transcript_api.py
│           └── yt_dlp_adapter.py
└── docs/
    ├── README.md
    ├── code-reference.md
    ├── architecture.md
    └── orchestrator/
        └── tools/
            ├── tool-a-research-init/
            ├── tool-b-hotel-research/
            ├── tool-c-review-research/
            ├── tool-d-photo-research/
            ├── tool-e-price-analysis/
            ├── tool-f-video-scrape/
            ├── tool-g-email-sender/
            └── tool-h-report-generator/

Los directory names en {framework-root} son placeholders; la real location es un path conocido por el agent. El framework en sí es portable.

Orchestrator

El orchestrator está en scout/orchestrator/. Tiene cinco componentes:

dag.py — Phase DAG

Define el dependency graph entre phases. Cada PhaseConfig declara:

• needs: artifacts que la phase requiere de phases anteriores.
• produces: artifacts que la phase escribe.
• parallel_group: integer opcional para agrupar parallel phases.
• retry: cuántas veces se puede re-ejecutar una phase.
• allow_partial: si succeeded_partial es un terminal state aceptable.

PhaseDAG es la data structure; PhaseKind distingue sequential y parallel phases.

runner.py — PhaseRunner

Ejecuta un PhaseDAG para una mission:

• Lee el current RunState del StateStore.
• Resuelve qué phases están ready para correr.
• Lanza las sequential phases una a una, las parallel con un ThreadPoolExecutor.
• Captura cada PhaseResult y lo escribe de vuelta al state.
• Re-lanza PhaseExecutionError cuando una phase está failed_terminal.

state_store.py — StateStore + RunState

La checkpoint layer. El orchestrator persiste RunState a <run_dir>/phase.json después de cada phase. RunState se carga al startup para que una run con crash se pueda resumir.

artifact_store.py — ArtifactStore

Lee/escribe typed artifacts a disco con schema validation. Usa un RLock per-path para permitir concurrent writes seguros desde parallel phases.

mission_runner.py — MissionRunner

El entrypoint de high-level. run_mission(mission_id, query, runs_dir) es lo que el CLI llama. Hace:

• Corre f0_init para crear el run directory y escribir task.json.
• Carga el DAG y corre las phases en orden.
• Devuelve el path al report final.

El module también exporta helpers: get_mission_state, get_mission_artifacts y register_phase_handler (para custom phases).

Phases

Una phase es una única función Python que toma (mission_id, runs_dir) y devuelve un PhaseResult. El framework viene con 8 phases.

El DAG completo está en Mission DAG. El phase lifecycle (input, output, retry, failure) está en Mission Lifecycle.

Schemas

Los schemas son modelos Pydantic v2 en scout/schemas/. Son el contract entre layers y la validation layer para artifacts. Ocho files:

PhaseStatus es el único enum y tiene 9 values:

class PhaseStatus(str, Enum):
    pending              = "pending"
    running              = "running"
    succeeded            = "succeeded"
    succeeded_partial    = "succeeded_partial"
    failed_retryable     = "failed_retryable"
    failed_terminal      = "failed_terminal"
    skipped              = "skipped"
    blocked_missing_input = "blocked_missing_input"
    stale                = "stale"

La schema reference completa está en Data Dictionary.

Adapters

Los adapters traducen las llamadas de phase en provider-specific HTTP requests. Están en scout/tools/adapters/.

El Perplexity adapter vive un nivel arriba (scout/tools/) porque es más que un search adapter — es el synthesis engine para P3. Tiene su propia configuration, token pool y request journal documentados en External Providers.

Todos los demás adapters comparten un common contract:

def search(query: str, *, limit: int = 10, **opts) -> list[Source]:
    """Return a list of Source objects matching the query."""

Los adapters devuelven objects Source de schemas/sources.py para que el resto del framework sea provider-agnostic.

Domain tools

El framework incluye 7 domain-specific tools que envuelven end-to-end workflows (p. ej., "research a hotel", "research a video"). Cada una es un package autocontenido con su propio src/, tests/, skills/ y docs/.

Todas las tools comparten el directory pattern de Tool Structure → Directory Layout.

Entry points

El framework tiene dos CLI entry points:

research_cli.py — Orchestrator CLI

python -m scout.tools.research_cli run \
  --mission-id hotel-barcelona-2026-09 \
  --query "find hotels in Barcelona for September 2026 under 200 EUR with good reviews" \
  --runs-dir /tmp/scoute/runs

Devuelve el path al final report.md.

run_research.py — Phase-by-phase runner

python -m scout.tools.run_research \
  hotel-barcelona-2026-09 \
  "find hotels in Barcelona for September 2026 under 200 EUR" \
  --runs-dir /tmp/scoute/runs

Corre las phases una a una con full logging per phase. Usado para debugging y para el step-by-step mode del agent.

run_research.sh — Wrapper script

Bash wrapper sobre run_research.py que setea environment variables (SCOUTE_RESEARCH_ROOT, PYTHONPATH) y corre dentro del virtual environment del framework.

Configuration

El framework se configura a través de environment variables y un per-tool config file.

Tool-specific configuration (p. ej., Tavily key, Google cx) la carga cada adapter desde un JSON file bajo {framework-root}/config/.

Failure model

El framework distingue entre failures retryable y terminal. La classification está encoded en PhaseStatus:

La retry policy del orchestrator es configurable per phase (PhaseConfig.retry). Cuando se agotan los retries, la phase pasa a failed_terminal y la mission se detiene.

Auditability

Cada run produce un audit trail completo:

• task.json: la query original y la parsed structure.
• phase.json: el state de cada phase en cada checkpoint.
• Todos los artifacts (typed por schema).
• report.md: el final aggregated output.
• El log propio del framework (uno por mission).

Se le puede pedir al Coordinator que muestre el audit trail de cualquier mission en cualquier momento. Ver Audit Model.

Performance

Una research mission típica (1 phase F0, 1 F1 con 20 candidates, 3 parallel phases F2/F4/Y1, 1 Y2, 1 P3, 1 F6) tarda 2-5 minutos wall-clock, dependiendo de adapter latency y parallel worker count. El bottleneck suele ser las review y price phases; la YouTube phase puede tardar más cuando participan muchos candidates.

Extensibility

El framework está diseñado para extenderse de tres maneras:

1. New adapter. Implementar el contract search en scout/tools/adapters/ y registrarlo en la adapter factory de tools/research_cli.py.
2. New phase. Implementar una función run(mission_id, runs_dir) en scout/phases/, exportarla de phases/__init__.py, y añadir un PhaseConfig en dag.py.
3. New domain tool. Crear un nuevo package bajo docs/orchestrator/tools/ con la standard structure src/, tests/, skills/, docs/.

Ver Tool Spec y Tool Structure para los templates.

See also

• Mission DAG
• Mission Lifecycle
• Artifacts
• External Providers
• Research Worker
• Tooling Layer → Media Tools
• Audit Model
• Failure Catalog