Batch and dataset execution

Use a batch when one prompt should run independently over every row of a CSV, TSV,
or JSONL dataset. Holaryn versions the input, validates and estimates the job before
creation, applies concurrency and budgets, persists each attempt, and lets you
pause, resume, cancel, retry, inspect, and export without losing row linkage.

Import a dataset

Create dataset.json:

{
  "dataset_id": "support-messages",
  "name": "Support messages",
  "source": "D:/data/support.jsonl",
  "format": "jsonl",
  "identity_field": "id"
}

Then import and inspect its version, inferred schema, sample, and validation errors:

holaryn batch import dataset.json
holaryn batch datasets

CSV and TSV values infer as strings unless you provide schema_override, for
example "priority": "integer" or "resolved": "boolean". A content hash prevents
duplicate versions. The identity field must be a non-empty scalar and must be unique.

Define and preflight the job

Create batch.json:

{
  "batch_id": "classify-support-2026-07",
  "title": "Classify support messages",
  "dataset_version_id": "dsv_REPLACE_WITH_IMPORT_OUTPUT",
  "prompt_template": "Classify {text} for item {id}. Return a JSON label.",
  "output_schema": {
    "type": "object",
    "properties": {"label": {"type": "string"}},
    "required": ["label"],
    "additionalProperties": false
  },
  "concurrency": 4,
  "partition_size": 100,
  "timeout_seconds": 120,
  "max_retries": 1,
  "item_budget": {"tokens": 2000, "model_calls": 2, "active_seconds": 120},
  "global_budget": {"tokens": 200000, "model_calls": 200, "active_seconds": 3600},
  "item_forecast": {"tokens": 500, "model_calls": 1, "active_seconds": 10},
  "allowed_tools": [],
  "cross_row_memory": false
}

Run preflight before creation:

holaryn batch dry-run batch.json
holaryn batch create batch.json

Preflight shows sample rendered prompts, dataset/template errors, permission scope,
forecast usage, and both item/global budget fit. Placeholders are limited to simple
column names. Dataset values are JSON-quoted as untrusted content; template
expressions such as {user.secret} are rejected.

Run and supervise

Every lifecycle mutation uses the current optimistic revision printed by show:

holaryn batch start classify-support-2026-07 --expected-revision 1
holaryn batch show classify-support-2026-07
holaryn batch items classify-support-2026-07 --state failed
holaryn batch attempts classify-support-2026-07 --item-key ROW_SHA
holaryn batch pause classify-support-2026-07 --expected-revision 2 --reason "Provider maintenance"
holaryn batch resume classify-support-2026-07 --expected-revision 3
holaryn batch cancel classify-support-2026-07 --expected-revision 4 --reason "Input superseded"

The persistent host executes running jobs. Each row receives its own context and
memory database by default. Tools are absent unless named in allowed_tools, and an
allowlisted tool still follows ordinary unattended approval policy. A retry can use
fallback_profile without changing the original definition.

To retry all failures or a selected subset:

holaryn batch retry classify-support-2026-07 --expected-revision 5
holaryn batch retry classify-support-2026-07 --expected-revision 5 --item-key ROW_SHA

Retry returns the job to paused; inspect it, then resume with the new revision.

Expected item output

For an input row:

{"id": "case-17", "text": "I was charged twice"}

the rendered prompt identifies the fields as untrusted. A schema-valid model result
might be:

{"label": "billing"}

The item ledger keeps that result with case-17's deterministic item key, attempt
count, measured tokens/cost, trace id, and artifact references. Invalid JSON or a
schema mismatch becomes a stable failed-row error; it is never silently accepted.

Export and reports

holaryn batch report classify-support-2026-07
holaryn batch export classify-support-2026-07 D:/exports/support.jsonl --format jsonl
holaryn batch export classify-support-2026-07 D:/exports/support.csv --format csv
holaryn batch export classify-support-2026-07 D:/exports/support.parquet.jsonl --format parquet-ready

Exports preserve the input, output, state, error, usage, trace, and artifact links.
CSV cells beginning with spreadsheet formula characters are prefixed safely.
Parquet-ready output is linked JSONL plus a schema sidecar for a downstream Parquet
writer, not a binary Parquet file.

The Batches tab offers the same dataset import, strict definition/preflight, job
progress, item filtering/detail, lifecycle, retry, and export controls with keyboard
operation, screen-reader labels, and 200% zoom reflow.

For the threat model and restart guarantees, see
Batch runner architecture.

← Previous Autonomy and approvals Next → Browser agent