batch-api-orchestrator

Imported from borghei/claude-skills (engineering/batch-api-orchestrator/SKILL.md). Install upstream with npx skills add borghei/claude-skills --skill batch-api-orchestrator. Copyright stays with the author (MIT + Commons Clause).

Batch API Orchestrator

Category: Engineering Domain: AI Engineering

Overview

Decide when to run LLM work through an asynchronous batch API versus realtime/streaming, then design the job so it is cheap, idempotent, and resilient to partial failure. Batch APIs typically cost roughly half of realtime in exchange for higher latency (results arrive over minutes to hours, not milliseconds), which makes them ideal for evals, backfills, embeddings, and bulk classification/extraction — and wrong for anything a human is waiting on. This skill is model- and vendor-agnostic: it reasons about the batch pattern, not any one provider's API.

Clarify First

Before recommending or designing a batch job, settle the inputs below. When one is missing or vague and would change the result, ask about it; when it wouldn't, use a sensible default and say which one you used.

• Latency tolerance: is a human waiting (interactive), or can results land in minutes/hours? (sets --latency-tolerance and the batch-vs-realtime verdict).
• Volume & token shape: how many requests, and the average input/output tokens each? (sets --requests, --avg-input-tokens, --avg-output-tokens for the cost estimate).
• Pricing & discount: your realtime per-token prices and the batch discount your vendor offers (sets --realtime-input-price, --realtime-output-price, --batch-discount; defaults are neutral placeholders, not real prices).

Ask about the two or three inputs that matter most for this request. If the user says "just draft it," proceed and list your assumptions.

Quick Start

cd engineering/batch-api-orchestrator

# 1. Should this be batch or realtime, and what does it cost?
python scripts/batch_cost_estimator.py \
  --requests 50000 --avg-input-tokens 800 --avg-output-tokens 200 \
  --realtime-input-price 3.0 --realtime-output-price 15.0 \
  --batch-discount 0.5 --latency-tolerance hours

# 2. Plan the chunking / idempotency / retry strategy for the job
python scripts/batch_job_planner.py \
  --total-items 50000 --max-batch-size 10000 --retry-policy exponential --json

Tools Overview

Both scripts: Python 3 standard library only, argparse CLI, --json and human-readable output. Run --help for full usage.

Workflows

1. Decide batch vs realtime, then size the cost

1. Gather volume and token shape (--requests, --avg-input-tokens, --avg-output-tokens).
2. Plug in your vendor prices and batch discount — never assume them.
3. Run batch_cost_estimator.py with the real --latency-tolerance (realtime, minutes, or hours).
4. Read the verdict: if work is interactive, the tool recommends realtime regardless of savings; otherwise it quantifies the batch savings.
5. Sanity-check against the decision tree in references/batch-patterns-and-decision-tree.md.

2. Design a resilient bulk job

1. Run batch_job_planner.py with --total-items, --max-batch-size, and a --retry-policy.
2. Adopt the generated idempotency-key scheme so re-submitting a chunk never double-charges or double-writes.
3. Wire result reconciliation: match every output back to its request id, and collect the unmatched into a dead-letter set.
4. Apply the partial-failure handling (retry only failed items, never the whole batch) from the reference.
5. Choose polling vs callback for completion, per the reference guidance.

Scope & Limitations

In Scope:

• The batch versus realtime decision, based on latency tolerance (realtime, minutes, hours, days)
• Cost comparison of realtime and batch runs with batch_cost_estimator.py from request volume, average token counts, the user's own per-token prices and batch discount
• Job plans from batch_job_planner.py: chunk sizes, an idempotency-key scheme, retry policy (exponential, fixed or none) and partial-failure handling
• Job design guidance from the references: reconciliation by request id, dead-letter sets, polling versus callbacks, chunk sizing and break-even modelling

Out of Scope:

• Submitting, polling or downloading batch jobs; the skill does not call any vendor API or include client code for one
• Wider LLM cost work such as token counting, caching and model routing (see engineering/llm-cost-optimizer/)
• Designing the evaluations that often run as batch jobs (see engineering/agentic-evaluation-framework/ and engineering/agent-harness/)
• Streaming and interactive request handling

Important Caveats:

• The default prices in batch_cost_estimator.py are neutral placeholders, not real prices. Estimates mean something only after the user supplies current vendor prices and discount.
• The roughly half-price batch discount is a rule of thumb. Discounts, maximum batch sizes, completion windows and result retention differ by vendor and change over time.
• Estimates assume every request costs the average token count. Long-tail inputs, retries and failed items add cost the model does not show.

Reference Documentation

• references/batch-patterns-and-decision-tree.md — when-to-batch decision tree; job design (idempotency keys, partial failures, reconciliation, polling vs callback); fitting use cases (evals, backfills, embeddings, bulk classification/extraction); and anti-patterns such as batching interactive requests.
• references/cost-and-throughput-economics.md — the cost/throughput tradeoff in depth: the ~half-cost rule of thumb, throughput vs latency, queueing, chunk sizing, and how to model the break-even between a faster realtime path and a cheaper batch path.

Common Patterns

• Batch the patient, stream the impatient — if no human is blocked on the result, default to batch for the cost win; reserve realtime/streaming for interactive UX.
• Idempotency key per item — derive a stable key (e.g. hash of input + job version) so retries and re-submissions are safe and never double-billed.
• Retry the item, not the batch — on partial failure, re-enqueue only the failed request ids; resubmitting the whole chunk wastes money and re-runs successes.
• Reconcile by request id — never rely on output ordering; join results back to inputs by id and route the unmatched to a dead-letter queue for inspection.
• Right-size chunks — split by the vendor's max-batch limit and by your own blast-radius tolerance, not into one giant job whose failure is all-or-nothing.
• Embeddings and evals are the sweet spot — large, latency-insensitive, embarrassingly parallel workloads capture the full batch discount with the least risk.