batchgrid for Python

Run a prompt, or a whole pipeline, over every row of a DataFrame or spreadsheet. You get a cost estimate before anything runs, parallel calls with retries and rate-limit backoff, and runs that resume after an interruption.

import pandas as pd
import batchgrid

df = pd.read_csv("reviews.csv")
result = batchgrid.run(df, "classify the sentiment and extract keywords", max_cost=5)
result.data  # df with the new columns

Beta. This package drives the batchgrid CLI, so it needs Node.js 22 or newer. It uses a batchgrid on your PATH, or fetches the CLI with npx on first use.

Install

pip install "batchgrid[pandas,progress]"

pandas is needed for DataFrame input and progress adds a tqdm progress bar. File paths work without either.

Set the key of the provider you use, either as an environment variable (OPENAI_API_KEY, ANTHROPIC_API_KEY, GOOGLE_API_KEY, OPENROUTER_API_KEY, XAI_API_KEY) or once with npx batchgrid config --set-key openai:sk-….

Plan, check, run

Planning asks a model, so the same request can produce a slightly different plan each time. Look at the plan and its cost first, then run it:

plan = batchgrid.plan(df, "classify the sentiment of each review")
print(plan)            # the steps, the columns they write, the estimated cost
plan.cost_usd          # 0.08

result = batchgrid.run(df, plan=plan)

A pipeline that must behave the same on every run should save the plan once and run that file. Running a saved plan does not ask the planner again:

plan.save("sentiment.json")

# later, in the pipeline
result = batchgrid.run("next_week.csv", plan="sentiment.json", max_cost=10)

The file is the same one batchgrid --save-plan writes and batchgrid --plan reads.

Reference

batchgrid.run(data, prompt=None, *, plan=None, ...) -> Result

Result has status (done or stopped), total, success, failed, input_tokens, output_tokens, duration_ms, output_path, error_log_path, and data. For DataFrame input, data is a copy of your DataFrame with the new columns added, with its index and dtypes kept. If a plan filters rows or drops columns, data holds the output as it was written.

Rows that still fail after their retries do not raise an error. Check result.failed, and look in result.error_log_path for the reasons.

batchgrid.plan(data, prompt, *, model=None, rows=None) -> Plan

Plans the request and prices it without running anything. Plan has title, summary, cost_usd, cost_formatted, rows, missing_secrets, the raw steps, and save(path) / Plan.load(path).

batchgrid.resume(data) -> Result

Ctrl+C (or a Jupyter interrupt) stops a run and keeps the rows that finished. Call resume with the same file or DataFrame to finish it. Only the unfinished rows are sent to the model.

try:
    result = batchgrid.run(df, plan="sentiment.json")
except KeyboardInterrupt:
    result = batchgrid.resume(df)

Errors

Everything raises batchgrid.BatchgridError, and its code says what went wrong:

• no_api_key: no provider key is set.
• invalid_plan: the plan does not fit the data.
• no_plan: the planner asked a question instead of returning a plan. This raises NoPlanError, and its reply holds the question.
• missing_secrets: the plan needs keys that are not saved. This raises MissingSecretsError, and its names lists them.
• cost_limit: the run would go over max_cost. This raises CostLimitError, and its plan holds the priced plan.
• run_failed: the run itself failed.

Choosing the CLI

The package looks for the CLI in this order:

1. the cli=[...] argument
2. the BATCHGRID_CLI environment variable, e.g. node /path/to/cli/dist/index.js
3. a batchgrid on the PATH
4. npx "batchgrid@>=0.2.0 <1"

Development

pnpm --filter batchgrid build   # the tests drive the real CLI
cd python
uv venv && uv pip install -e ".[dev,progress]"
.venv/bin/python -m pytest

The tests replace only the model: a local server stands in for the OpenAI API.