batchgrid

Run batch LLM inference over CSV/Excel files using natural language. Describe what you want done with the data, BatchGrid plans the task, estimates the cost, and processes every row in parallel with checkpoint/resume.

npx batchgrid customers.csv

Install

npm install -g batchgrid
# or just use it with npx
npx batchgrid path/to/file.csv

Quick start

# Just point it at a file — opens the interactive TUI
batchgrid data.csv

# `run` is implicit; this is equivalent
batchgrid run data.csv

# Verbose mode
batchgrid data.csv -v

You'll be asked once for an API key (OpenAI / Anthropic / Gemini / OpenRouter); it's stored locally in ~/.batchgrid/config.json. You can also use environment variables:

export OPENAI_API_KEY=sk-...
export ANTHROPIC_API_KEY=sk-ant-...
export GEMINI_API_KEY=AI...
export OPENROUTER_API_KEY=sk-or-...

Features

• Natural-language tasks — describe the job, BatchGrid generates the prompt and output schema
• Multi-provider — OpenAI, Anthropic, Google Gemini, OpenRouter (100+ models)
• Cost estimation — see token counts and USD before you run
• Parallel processing — configurable concurrency, automatic rate-limit backoff
• Checkpoint & resume — interrupted runs pick up where they left off
• CSV & Excel — read .csv, .xlsx, .xls; writes enriched output alongside source

Common flags

| Flag | Description | |------|-------------| | --prompt <text> | Skip the TUI and run with this task description | | --concurrency <n> | Parallel requests (default: 5) | | --provider <name> | openai | anthropic | gemini | openrouter | | --model <id> | Model identifier (e.g. gpt-4o-mini) | | --verbose | Print prompts, responses, and token usage | | --resume | Continue from the last checkpoint |

Run batchgrid --help for the full list.

How it works

1. Analyze — sample the file, detect column types, suggest tasks
2. Plan — convert your intent into a row-level prompt + structured output schema
3. Estimate — compute total tokens and cost before any LLM calls
4. Execute — process rows in parallel with backoff, checkpointing, and live progress
5. Write — append result columns to a new file (<name>.batchgrid.csv)

Related packages

• @batchgrid/core — the underlying library, usable from Node
• @batchgrid/mcp — Model Context Protocol server for Claude Desktop / Claude Code

License

MIT