YAML And Execution

YAML is the bridge between the docs navigator and runtime execution. A selected tree path should be serializable, inspectable, editable, and executable.

Generate YAML

macroforecast-navigate replications synthetic-replication-roundtrip \
  --write-yaml /tmp/synthetic-replication.yaml

In the Navigator App, the YAML preview can also be copied or downloaded after editing a path. The app can import package recipe YAML generated by the navigator so the same route can be inspected again in the tree.

Resolve YAML

macroforecast-navigate resolve /tmp/synthetic-replication.yaml

Run only when execution_status is executable.

The browser app is a path editor and YAML generator. It does not replace macroforecast-navigate resolve, which remains the authoritative preflight before execution.

Run YAML

macroforecast-navigate run /tmp/synthetic-replication.yaml \
  --local-raw-source tests/fixtures/fred_md_ar_sample.csv \
  --output-root /tmp/macroforecast-synthetic

The command returns:

{
  "execution_status": "executed",
  "artifact_dir": "/tmp/macroforecast-synthetic/runs/...",
  "run_id": "..."
}

Notebook Pattern

from pathlib import Path
import yaml

from macroforecast.navigator import replication_recipe_yaml
from macroforecast import compile_recipe_dict, run_compiled_recipe

recipe = yaml.safe_load(replication_recipe_yaml("synthetic-replication-roundtrip"))
compiled = compile_recipe_dict(recipe)

result = run_compiled_recipe(
    compiled.compiled,
    output_root="/tmp/macroforecast-synthetic",
    local_raw_source=Path("tests/fixtures/fred_md_ar_sample.csv"),
)

Expected Outputs

The exact set depends on the selected path, but ordinary executable runs should write:

  • manifest.json;

  • predictions.csv;

  • metrics.json;

  • comparison_summary.json;

  • evaluation_summary.json;

  • optional evaluation reports such as evaluation_report.md or evaluation_report.tex when Layer 4 report_style requests them;

  • optional payload files such as forecast_payloads.jsonl;

  • optional Layer 6 inference artifacts such as stat_tests.json and compatibility sidecars such as stat_test_dm_modified.json.

When To Use API Docs

Use API docs after YAML execution works and you need function signatures, extension hooks, or custom plugin internals. For choosing a path, use the navigator pages first.