Batches

A batch executes an explicit collection of independently authored RunSpecs under one grouped lifecycle. It adds planning, bounded concurrency, recovery, attempt history, and comparable summary artifacts without forcing the cases into one shared base input.

Use a sweep when the cases are parameter variants of one RunSpec.

Batch Manifest

The input is a batch_v1 YAML or JSON manifest:

schema_version: batch_v1
batch:
  cases:
    - label: polar-walker
      runspec: cases/architecture-polar-walker.yaml
    - label: molniya
      runspec: cases/architecture-molniya.yaml
  summary:
    fields:
      - coverage.union_coverage_fraction
    write_csv: true

Case paths resolve relative to the manifest and must remain inside its input tree. Labels and paths must be unique. Each referenced input must be a single-run RunSpec rather than a sweep.

Plan And Run

Use the curated architecture comparison after copying the packaged resources:

astraeus batch plan astraeus-resources/examples/user/architecture-comparison-batch.yaml
astraeus batch run astraeus-resources/examples/user/architecture-comparison-batch.yaml --workers 2

Planning validates and materializes the child RunSpecs without executing them. Running creates isolated child processes and writes grouped results as each case finishes. Serial execution is the default.

Useful options mirror sweeps:

Option	Purpose
--batch-id <id>	Choose the grouped bundle name.
--output-root <path>	Change the default runs/batches root.
--profile-root <path>	Resolve imports used by child RunSpecs.
--max-cases <n>	Set a soft warning threshold for case count.
--workers <n>	Set bounded local concurrency.
--write-summary-csv	Add a tabular summary export.

Results

runs/batches/<batch_id>/
|-- batch_plan.json
|-- batch_attempts.json
|-- batch_results.json
|-- batch_summary.json
|-- batch_summary.csv
`-- cases/<case_id>/
    |-- runspec.json
    `-- attempts/<attempt_id>/
        `-- <standard run artifacts>

Read the bundle in this order:

1. batch_plan.json for input provenance and child references
2. batch_results.json for current case outcomes
3. batch_attempts.json for execution and recovery history
4. batch_summary.json for the current one-row-per-case comparison
5. child run artifacts for detailed interpretation

The optional CSV is a convenience export; the JSON summary is the contract. Mixed or failed current outcomes are still written and return exit code 4.

Resume And Rerun

astraeus batch resume runs/batches/<batch_id>
astraeus batch resume runs/batches/<batch_id> --retry-failed
astraeus batch rerun runs/batches/<batch_id> --failed
astraeus batch rerun runs/batches/<batch_id> --case <case_id>
astraeus batch rerun runs/batches/<batch_id> --all

resume continues incomplete current cases. --retry-failed includes failed cases. rerun requires an explicit failed, named, or complete selection and creates new attempts without discarding the earlier evidence.

Inspect individual child attempts through the normal run artifact tools. Use the grouped summary for navigation and comparison, and the model-specific artifacts for detailed result review.