@batchgrid/core

Platform-agnostic core library that powers BatchGrid. Provider abstraction, planner, pipeline runner, pricing, token estimation, and checkpointing — usable from any Node project (CLI, server, MCP, custom tool).

npm install @batchgrid/core

Looking for the CLI? Install batchgrid. Building an MCP integration? See @batchgrid/mcp.

What's inside

| Module | Purpose | |--------|---------| | createProvider | Unified provider interface for OpenAI, Anthropic, Gemini, OpenRouter | | analyzeData | Sample a dataset, infer column types and task suggestions | | createPlan | Turn a natural-language intent into a row prompt + output schema | | estimateCost | Token count and USD estimate before running | | runPipeline | Parallel execution with backoff, retries, and checkpoint hooks | | getModelsByProvider | Fetch available models and pricing | | loadCheckpoint / createCheckpointWriter | Resume long runs across processes |

Quick example

import {
  createProvider,
  createPlan,
  estimateCost,
  runPipeline,
} from "@batchgrid/core";

const provider = createProvider({
  name: "openai",
  apiKey: process.env.OPENAI_API_KEY!,
  model: "gpt-4o-mini",
});

const rows = [
  { name: "Alice", company: "Acme Corp" },
  { name: "Bob", company: "Globex" },
];

const plan = await createPlan({
  provider,
  intent: "For each row, classify the company's industry",
  headers: ["name", "company"],
  sampleRows: rows.slice(0, 5),
});

const estimate = await estimateCost({ plan, rows, provider });
console.log(`Estimated cost: $${estimate.estimatedCostUsd}`);

const results = await runPipeline({
  plan,
  rows,
  provider,
  concurrency: 5,
});

Providers

All providers share a single chat({ system, messages }) interface. BatchGrid handles JSON-mode coercion, retries, and rate-limit backoff per provider.

| Provider | Env var | Notes | |----------|---------|-------| | openai | OPENAI_API_KEY | GPT-4o, GPT-4o-mini, o-series | | anthropic | ANTHROPIC_API_KEY | Claude Sonnet, Haiku, Opus | | gemini | GEMINI_API_KEY | Gemini Flash, Pro | | openrouter | OPENROUTER_API_KEY | 100+ models via one key |

Design

• Pure functions, injectable adapters — no filesystem, network, or process assumptions baked in. Adapters for logging, hashing, pricing cache, and checkpoint storage are passed in by the caller, so the same core runs identically in CLI, server, MCP, and browser environments.
• Streaming-friendly — runPipeline accepts row iterables and emits progress events.
• Type-first — every public surface is fully typed; bring-your-own zod schemas for plan output.

License

MIT