batchgrid 0.1.0b1__tar.gz

batchgrid-0.1.0b1/.gitignore

@@ -0,0 +1,12 @@
+node_modules/
+dist/
+.env
+*.log
+.DS_Store
+.turbo/
+*.tsbuildinfo
+
+# Python package
+.venv/
+__pycache__/
+.pytest_cache/

batchgrid-0.1.0b1/PKG-INFO

@@ -0,0 +1,159 @@
+Metadata-Version: 2.5
+Name: batchgrid
+Version: 0.1.0b1
+Summary: Run a prompt, or a whole pipeline, over every row of a DataFrame or spreadsheet - with cost estimates, retries and resumable runs.
+Project-URL: Homepage, https://github.com/mertguvencli/batchgrid
+Project-URL: Source, https://github.com/mertguvencli/batchgrid/tree/main/python
+Project-URL: Issues, https://github.com/mertguvencli/batchgrid/issues
+Author: Mert Guvencli
+License-Expression: MIT
+Keywords: anthropic,batch,csv,dataframe,gemini,llm,openai,pandas
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Requires-Python: >=3.9
+Provides-Extra: dev
+Requires-Dist: pandas>=1.5; extra == 'dev'
+Requires-Dist: pytest>=7; extra == 'dev'
+Provides-Extra: pandas
+Requires-Dist: pandas>=1.5; extra == 'pandas'
+Provides-Extra: progress
+Requires-Dist: tqdm>=4.60; extra == 'progress'
+Description-Content-Type: text/markdown
+
+# 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.
+
+```python
+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](https://www.npmjs.com/package/batchgrid), 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
+
+```bash
+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:
+
+```python
+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:
+
+```python
+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`
+
+| Argument | Meaning |
+|---|---|
+| `data` | A CSV, TSV or Excel path, a pandas DataFrame, or `None` when the request brings its own rows |
+| `prompt` | What to do, in plain language. Pass either this or `plan` |
+| `plan` | A `Plan`, its dict, or a saved JSON file |
+| `model` | `"gpt-5.6"` or `"provider:model"`, e.g. `"anthropic:claude-sonnet-5"`. The default is the saved choice |
+| `rows` | Run only the first N rows, a cheap way to try a plan |
+| `concurrency` | The most requests running at once |
+| `output` | Where to write the result. The extension picks the format |
+| `max_cost` | In US dollars. The plan is priced first and nothing runs above it, or when the model has no price list |
+| `progress` | Show a progress bar when tqdm is installed. Defaults to on |
+| `on_event` | Called with each event the CLI reports: plan, progress, 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.
+
+```python
+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
+
+```bash
+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.

batchgrid-0.1.0b1/README.md

@@ -0,0 +1,133 @@
+# 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.
+
+```python
+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](https://www.npmjs.com/package/batchgrid), 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
+
+```bash
+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:
+
+```python
+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:
+
+```python
+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`
+
+| Argument | Meaning |
+|---|---|
+| `data` | A CSV, TSV or Excel path, a pandas DataFrame, or `None` when the request brings its own rows |
+| `prompt` | What to do, in plain language. Pass either this or `plan` |
+| `plan` | A `Plan`, its dict, or a saved JSON file |
+| `model` | `"gpt-5.6"` or `"provider:model"`, e.g. `"anthropic:claude-sonnet-5"`. The default is the saved choice |
+| `rows` | Run only the first N rows, a cheap way to try a plan |
+| `concurrency` | The most requests running at once |
+| `output` | Where to write the result. The extension picks the format |
+| `max_cost` | In US dollars. The plan is priced first and nothing runs above it, or when the model has no price list |
+| `progress` | Show a progress bar when tqdm is installed. Defaults to on |
+| `on_event` | Called with each event the CLI reports: plan, progress, 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.
+
+```python
+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
+
+```bash
+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.

batchgrid-0.1.0b1/pyproject.toml

@@ -0,0 +1,38 @@
+[build-system]
+requires = ["hatchling>=1.24"]
+build-backend = "hatchling.build"
+
+[project]
+name = "batchgrid"
+version = "0.1.0b1"
+description = "Run a prompt, or a whole pipeline, over every row of a DataFrame or spreadsheet - with cost estimates, retries and resumable runs."
+readme = "README.md"
+license = "MIT"
+requires-python = ">=3.9"
+authors = [{ name = "Mert Guvencli" }]
+keywords = ["llm", "batch", "pandas", "dataframe", "csv", "openai", "anthropic", "gemini"]
+classifiers = [
+  "Development Status :: 4 - Beta",
+  "Intended Audience :: Developers",
+  "Intended Audience :: Science/Research",
+  "License :: OSI Approved :: MIT License",
+  "Programming Language :: Python :: 3",
+  "Topic :: Scientific/Engineering :: Artificial Intelligence",
+]
+dependencies = []
+
+[project.optional-dependencies]
+pandas = ["pandas>=1.5"]
+progress = ["tqdm>=4.60"]
+dev = ["pytest>=7", "pandas>=1.5"]
+
+[project.urls]
+Homepage = "https://github.com/mertguvencli/batchgrid"
+Source = "https://github.com/mertguvencli/batchgrid/tree/main/python"
+Issues = "https://github.com/mertguvencli/batchgrid/issues"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/batchgrid"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]

batchgrid-0.1.0b1/src/batchgrid/__init__.py

@@ -0,0 +1,30 @@
+"""batchgrid - run a prompt, or a whole pipeline, over every row of a DataFrame or spreadsheet.
+
+    import batchgrid
+
+    result = batchgrid.run(df, "classify the sentiment of each review", max_cost=5)
+    result.data  # df with the new columns
+
+The work is done by the batchgrid CLI (Node.js 22+), which this package starts
+and follows; see find_cli() for how it is located.
+"""
+
+from ._api import Plan, Result, plan, resume, run
+from ._cli import CLI_SPEC, find_cli
+from .errors import BatchgridError, CostLimitError, MissingSecretsError, NoPlanError
+
+__version__ = "0.1.0b1"
+
+__all__ = [
+    "BatchgridError",
+    "CLI_SPEC",
+    "CostLimitError",
+    "MissingSecretsError",
+    "NoPlanError",
+    "Plan",
+    "Result",
+    "find_cli",
+    "plan",
+    "resume",
+    "run",
+]

batchgrid-0.1.0b1/src/batchgrid/_api.py

@@ -0,0 +1,457 @@
+"""plan(), run() and resume() - the Python face of the batchgrid CLI."""
+
+from __future__ import annotations
+
+import json
+import os
+import tempfile
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import TYPE_CHECKING, Any, Callable, Dict, List, Mapping, Optional, Sequence, Tuple, Union
+
+from ._cli import Event, find_cli, stream_events
+from .errors import BatchgridError, CostLimitError, MissingSecretsError, NoPlanError
+
+if TYPE_CHECKING:
+    import pandas as pd
+
+PathLike = Union[str, "os.PathLike[str]"]
+#: A file path, or a pandas DataFrame
+Data = Union[PathLike, "pd.DataFrame"]
+EventHandler = Callable[[Event], None]
+
+
+@dataclass
+class Plan:
+    """A workflow the planner wrote, with what it will cost.
+
+    Save it and pass it to ``run(plan=...)`` to repeat the exact same steps
+    later - running a saved plan does not ask the planner again.
+    """
+
+    steps: Dict[str, Any]
+    """The plan itself, as the engine reads it."""
+    summary: str = ""
+    """One readable paragraph: the steps and the columns they write."""
+    cost_usd: Optional[float] = None
+    """Estimated cost of the run in US dollars, or None when the model has no price list."""
+    cost_formatted: str = ""
+    rows: int = 0
+    """How many rows the run will process."""
+    missing_secrets: List[str] = field(default_factory=list)
+    """Service keys the plan needs that are not saved yet."""
+    cost: Dict[str, Any] = field(default_factory=dict)
+    """The full estimate: input and output tokens, model, pricing availability."""
+
+    @property
+    def title(self) -> str:
+        return str(self.steps.get("title") or self.steps.get("intent") or "")
+
+    def save(self, path: PathLike) -> Path:
+        """Write the plan as JSON - the same file ``batchgrid --plan`` reads."""
+        target = Path(path)
+        target.write_text(json.dumps(self.steps, indent=2) + "\n", encoding="utf-8")
+        return target
+
+    @classmethod
+    def load(cls, path: PathLike) -> "Plan":
+        """Read a plan saved with ``save()`` or ``batchgrid --save-plan``."""
+        data = json.loads(Path(path).read_text(encoding="utf-8"))
+        # A saved workflow exported from the app wraps the plan: { name, plan }
+        if isinstance(data, dict) and "steps" not in data and isinstance(data.get("plan"), dict):
+            data = data["plan"]
+        return cls(steps=data)
+
+    @classmethod
+    def _from_event(cls, event: Event) -> "Plan":
+        cost = event.get("cost") or {}
+        assert isinstance(cost, dict)
+        priced = bool(cost.get("pricingAvailable"))
+        return cls(
+            steps=event["plan"],  # type: ignore[arg-type]
+            summary=str(event.get("summary") or ""),
+            cost_usd=float(cost["estimatedCostUsd"]) if priced and "estimatedCostUsd" in cost else None,
+            cost_formatted=str(event.get("costFormatted") or ""),
+            rows=int(event.get("rows") or 0),  # type: ignore[arg-type]
+            missing_secrets=list(event.get("missingSecrets") or []),  # type: ignore[arg-type]
+            cost=cost,
+        )
+
+    def __str__(self) -> str:
+        parts = [self.summary or self.title]
+        if self.cost_formatted:
+            parts.append(self.cost_formatted)
+        return "\n\n".join(parts)
+
+    def _repr_markdown_(self) -> str:
+        cost = self.cost_formatted or "no estimate"
+        return f"**{self.title}** · {self.rows:,} rows · {cost}\n\n```\n{self.summary}\n```"
+
+
+@dataclass
+class Result:
+    """How a run ended."""
+
+    status: str
+    """``done``, or ``stopped`` when it was interrupted - resume() picks it up."""
+    total: int
+    success: int
+    failed: int
+    """Rows that failed after their retries; ``error_log_path`` has the reasons."""
+    input_tokens: int
+    output_tokens: int
+    duration_ms: int
+    output_path: Optional[Path]
+    """The file the run wrote: the input with the new columns, or a zip when it produced files."""
+    error_log_path: Optional[Path]
+    data: Optional["pd.DataFrame"] = None
+    """The result as a DataFrame, when the input was one."""
+
+    @classmethod
+    def _from_event(cls, event: Event) -> "Result":
+        tokens = event.get("tokens") or {}
+        assert isinstance(tokens, dict)
+        output = event.get("outputPath")
+        errors = event.get("errorLogPath")
+        return cls(
+            status=str(event.get("status")),
+            total=int(event.get("total") or 0),  # type: ignore[arg-type]
+            success=int(event.get("success") or 0),  # type: ignore[arg-type]
+            failed=int(event.get("failed") or 0),  # type: ignore[arg-type]
+            input_tokens=int(tokens.get("input") or 0),
+            output_tokens=int(tokens.get("output") or 0),
+            duration_ms=int(event.get("durationMs") or 0),  # type: ignore[arg-type]
+            output_path=Path(str(output)) if output else None,
+            error_log_path=Path(str(errors)) if errors else None,
+        )
+
+
+def plan(
+    data: Optional[Data],
+    prompt: str,
+    *,
+    model: Optional[str] = None,
+    rows: Optional[int] = None,
+    on_event: Optional[EventHandler] = None,
+    cli: Optional[Sequence[str]] = None,
+    env: Optional[Mapping[str, str]] = None,
+) -> Plan:
+    """Ask the planner for a workflow and price it, without running anything.
+
+    ``data`` is a CSV/TSV/Excel path or a pandas DataFrame, or None when the
+    request brings its own rows ("find 50 AI startups in Berlin").
+    ``model`` is a model name or ``provider:model``, e.g.
+    ``"anthropic:claude-sonnet-5"``; the default is the one saved in
+    ``batchgrid config``.
+    """
+    with _input_file(data) as (path, _):
+        events = _run_cli(
+            [*_input_args(path), "--prompt", prompt, *_common_args(model, rows, None)],
+            on_event,
+            cli,
+            env,
+        )
+    return _expect_plan(events)
+
+
+def run(
+    data: Optional[Data],
+    prompt: Optional[str] = None,
+    *,
+    plan: Union[Plan, Mapping[str, Any], PathLike, None] = None,
+    model: Optional[str] = None,
+    rows: Optional[int] = None,
+    concurrency: Optional[int] = None,
+    output: Optional[PathLike] = None,
+    max_cost: Optional[float] = None,
+    progress: bool = True,
+    on_event: Optional[EventHandler] = None,
+    cli: Optional[Sequence[str]] = None,
+    env: Optional[Mapping[str, str]] = None,
+) -> Result:
+    """Plan a request and run it over every row - or run a plan you already have.
+
+    Pass ``prompt`` to have the planner write the workflow, or ``plan`` (a
+    ``Plan``, its dict, or a saved JSON file) to repeat one exactly. With
+    ``max_cost``, the plan is priced first and nothing runs when the estimate
+    is higher - or when the model has no price list to estimate with.
+
+    For a DataFrame, the result's ``data`` is that DataFrame with the new
+    columns added. For a file, the output is written next to it (or to
+    ``output``) and ``output_path`` says where.
+
+    Ctrl+C stops the run and keeps the rows that finished; ``resume()`` with
+    the same data carries on from there.
+    """
+    if (prompt is None) == (plan is None):
+        raise ValueError("Pass either a prompt or a plan.")
+
+    with _input_file(data) as (path, frame):
+        if max_cost is not None:
+            # Price it on this data first, without running; the run then repeats this exact plan
+            with _plan_file(plan) as plan_path:
+                request = ["--plan", plan_path] if plan_path else ["--prompt", prompt or ""]
+                priced = _expect_plan(
+                    _run_cli([*_input_args(path), *request, *_common_args(model, rows, None)], on_event, cli, env)
+                )
+            _check_cost(priced, max_cost)
+            plan = priced
+
+        with _plan_file(plan) as plan_path:
+            request = ["--plan", plan_path] if plan_path else ["--prompt", prompt or ""]
+            args = [*_input_args(path), *request, "--yes", *_common_args(model, rows, concurrency)]
+            out = output if output is not None else (_frame_output(path) if frame is not None else None)
+            if out is not None:
+                args += ["--output", os.fspath(out)]
+            result = _expect_result(_run_cli(args, on_event, cli, env, progress=progress))
+        if frame is not None:
+            result.data = _merge_output(frame, result.output_path)
+    return result
+
+
+def resume(
+    data: Data,
+    *,
+    output: Optional[PathLike] = None,
+    progress: bool = True,
+    on_event: Optional[EventHandler] = None,
+    cli: Optional[Sequence[str]] = None,
+    env: Optional[Mapping[str, str]] = None,
+) -> Result:
+    """Finish a run that was stopped, on the same file or DataFrame.
+
+    Only the rows that had not finished are sent to the model.
+    """
+    with _input_file(data) as (path, frame):
+        out = output if output is not None else (_frame_output(path) if frame is not None else None)
+        args = [*_input_args(path), "--resume"]
+        if out is not None:
+            args += ["--output", os.fspath(out)]
+        result = _expect_result(_run_cli(args, on_event, cli, env, progress=progress))
+        if frame is not None:
+            result.data = _merge_output(frame, result.output_path)
+    return result
+
+
+# ── Running the CLI ────────────────────────────────────────────────────
+
+
+def _run_cli(
+    args: List[str],
+    on_event: Optional[EventHandler],
+    cli: Optional[Sequence[str]],
+    env: Optional[Mapping[str, str]],
+    progress: bool = False,
+) -> List[Event]:
+    bar = _ProgressBar() if progress else None
+    events: List[Event] = []
+    try:
+        for event in stream_events(find_cli(cli), [*args, "--json"], env):
+            events.append(event)
+            if bar is not None and event.get("type") == "progress":
+                bar.update(event)
+            if on_event is not None and event.get("type") != "exit":
+                on_event(event)
+    finally:
+        if bar is not None:
+            bar.close()
+    return events
+
+
+def _check_cost(p: Plan, max_cost: float) -> None:
+    if p.cost_usd is None:
+        # A plan without model calls costs nothing; one without a price list cannot be held to a limit
+        if p.cost and not p.cost.get("pricingAvailable", True):
+            raise CostLimitError(
+                f"There is no price list for {p.cost.get('model')}, so the run cannot be held to max_cost={max_cost}.",
+                p,
+            )
+        return
+    if p.cost_usd > max_cost:
+        raise CostLimitError(
+            f"The run is estimated at ${p.cost_usd:.4f}, above max_cost=${max_cost:.4f}. Nothing was run.",
+            p,
+        )
+
+
+def _failure(events: List[Event]) -> BatchgridError:
+    """The error the CLI reported - or, without one, what it printed on stderr"""
+    exit_event = events[-1] if events and events[-1].get("type") == "exit" else {}
+    stderr = str(exit_event.get("stderr") or "")
+    error = next((e for e in reversed(events) if e.get("type") == "error"), None)
+    if error is None:
+        hint = " The installed batchgrid CLI is too old - update it." if "unknown option" in stderr else ""
+        return BatchgridError("cli_failed", f"The batchgrid CLI stopped unexpectedly.{hint}\n{stderr}".rstrip(), stderr)
+
+    code, message = str(error.get("code")), str(error.get("message"))
+    if code == "no_plan":
+        reply = next((str(e["text"]) for e in reversed(events) if e.get("type") == "message"), None)
+        return NoPlanError(message, reply)
+    if code == "missing_secrets":
+        planned = next((e for e in events if e.get("type") == "plan"), {})
+        return MissingSecretsError(message, list(planned.get("missingSecrets") or []))  # type: ignore[arg-type]
+    return BatchgridError(code, message, stderr)
+
+
+def _expect_plan(events: List[Event]) -> Plan:
+    planned = next((e for e in events if e.get("type") == "plan"), None)
+    if planned is None or any(e.get("type") == "error" for e in events):
+        raise _failure(events)
+    return Plan._from_event(planned)
+
+
+def _expect_result(events: List[Event]) -> Result:
+    result = next((e for e in reversed(events) if e.get("type") == "result"), None)
+    if result is None or result.get("status") == "error":
+        raise _failure(events)
+    parsed = Result._from_event(result)
+    if any(e.get("type") == "error" for e in events) and parsed.status == "done":
+        # The rows ran, but something after them failed - writing the output
+        raise _failure(events)
+    return parsed
+
+
+def _input_args(path: Optional[str]) -> List[str]:
+    return [path] if path else []
+
+
+def _common_args(model: Optional[str], rows: Optional[int], concurrency: Optional[int]) -> List[str]:
+    args: List[str] = []
+    if model:
+        args += ["--model", model]
+    if rows is not None:
+        args += ["--rows", str(rows)]
+    if concurrency is not None:
+        args += ["--concurrency", str(concurrency)]
+    return args
+
+
+# ── Files in and out ───────────────────────────────────────────────────
+
+
+class _TempDir:
+    """One scratch directory per call, removed on exit"""
+
+    def __init__(self) -> None:
+        self.path: Optional[str] = None
+
+    def get(self) -> str:
+        if self.path is None:
+            self.path = tempfile.mkdtemp(prefix="batchgrid-")
+        return self.path
+
+    def cleanup(self) -> None:
+        if self.path is not None:
+            import shutil
+
+            shutil.rmtree(self.path, ignore_errors=True)
+
+
+class _input_file:
+    """The data as a path the CLI can open: a DataFrame is written to a CSV first"""
+
+    def __init__(self, data: Optional[Data]) -> None:
+        self.data = data
+        self.tmp = _TempDir()
+
+    def __enter__(self) -> Tuple[Optional[str], Optional["pd.DataFrame"]]:
+        if self.data is None:
+            return None, None
+        if _is_dataframe(self.data):
+            frame = self.data
+            path = os.path.join(self.tmp.get(), "data.csv")
+            # The same DataFrame writes the same bytes, so its checkpoint is found again on resume()
+            frame.rename(columns=str).to_csv(path, index=False)  # type: ignore[union-attr]
+            return path, frame  # type: ignore[return-value]
+        path = os.fspath(self.data)  # type: ignore[arg-type]
+        if not os.path.exists(path):
+            raise FileNotFoundError(path)
+        return os.path.abspath(path), None
+
+    def __exit__(self, *exc: object) -> None:
+        self.tmp.cleanup()
+
+
+class _plan_file:
+    """A plan as a JSON file for --plan, or None when the planner writes one"""
+
+    def __init__(self, value: Union[Plan, Mapping[str, Any], PathLike, None]) -> None:
+        self.value = value
+        self.tmp = _TempDir()
+
+    def __enter__(self) -> Optional[str]:
+        if self.value is None:
+            return None
+        if isinstance(self.value, Plan):
+            steps: Mapping[str, Any] = self.value.steps
+        elif isinstance(self.value, Mapping):
+            steps = self.value
+        else:
+            return os.path.abspath(os.fspath(self.value))
+        path = os.path.join(self.tmp.get(), "plan.json")
+        with open(path, "w", encoding="utf-8") as fh:
+            json.dump(steps, fh)
+        return path
+
+    def __exit__(self, *exc: object) -> None:
+        self.tmp.cleanup()
+
+
+def _frame_output(input_path: Optional[str]) -> str:
+    # Next to the temp input, so it is removed with it once read back
+    return os.path.join(os.path.dirname(input_path or ""), "output.csv")
+
+
+def _is_dataframe(value: object) -> bool:
+    return type(value).__module__.startswith("pandas") and type(value).__name__ == "DataFrame"
+
+
+def _merge_output(frame: "pd.DataFrame", output_path: Optional[Path]) -> Optional["pd.DataFrame"]:
+    """The input DataFrame with the run's new columns added.
+
+    The original columns keep their dtypes and the index is kept. When the
+    run reshaped the sheet - filtered rows, dropped columns - the output is
+    returned as read instead.
+    """
+    if output_path is None or output_path.suffix.lower() != ".csv" or not output_path.exists():
+        return None
+    import pandas as pd
+
+    out = pd.read_csv(output_path, dtype=str, keep_default_na=False)
+    names = [str(c) for c in frame.columns]
+    if len(out) != len(frame) or not set(names).issubset(out.columns):
+        return out
+    merged = frame.copy()
+    for column in out.columns:
+        if column not in names:
+            merged[column] = out[column].to_numpy()
+    return merged
+
+
+class _ProgressBar:
+    """A tqdm bar when tqdm is installed, otherwise nothing"""
+
+    def __init__(self) -> None:
+        self.bar: Any = None
+        try:
+            from tqdm.auto import tqdm
+
+            self._tqdm: Any = tqdm
+        except ImportError:
+            self._tqdm = None
+
+    def update(self, event: Event) -> None:
+        if self._tqdm is None:
+            return
+        total = int(event.get("total") or 0)  # type: ignore[arg-type]
+        if self.bar is None:
+            self.bar = self._tqdm(total=total, unit="row", desc="batchgrid")
+        if total and self.bar.total != total:
+            self.bar.total = total
+        self.bar.n = int(event.get("completed") or 0)  # type: ignore[arg-type]
+        self.bar.set_postfix(failed=int(event.get("failed") or 0), refresh=False)  # type: ignore[arg-type]
+        self.bar.refresh()
+
+    def close(self) -> None:
+        if self.bar is not None:
+            self.bar.close()

batchgrid-0.1.0b1/src/batchgrid/_cli.py

@@ -0,0 +1,146 @@
+"""Running the batchgrid CLI and reading the JSON events it prints.
+
+The engine is the Node CLI; this module only starts it with ``--json`` and
+turns its stdout into Python dicts. The event format is documented in the
+CLI README under "JSON output".
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import shlex
+import shutil
+import signal
+import subprocess
+import sys
+import threading
+from collections import deque
+from typing import Callable, Deque, Dict, Iterator, List, Mapping, Optional, Sequence
+
+#: The CLI releases this package speaks to: 0.2.0 was the first with ``--json``, and its events only gain fields
+CLI_SPEC = "batchgrid@>=0.2.0 <1"
+
+Event = Dict[str, object]
+
+
+def find_cli(cli: Optional[Sequence[str]] = None) -> List[str]:
+    """The command that starts the CLI.
+
+    In order: the ``cli`` argument, the ``BATCHGRID_CLI`` environment variable
+    (a command line, e.g. ``node /path/to/dist/index.js``), a ``batchgrid`` on
+    the PATH, then ``npx`` fetching the matching release.
+    """
+    if cli:
+        return list(cli)
+    from_env = os.environ.get("BATCHGRID_CLI", "").strip()
+    if from_env:
+        return shlex.split(from_env, posix=os.name != "nt")
+    installed = shutil.which("batchgrid")
+    if installed:
+        return [installed]
+    npx = shutil.which("npx")
+    if npx:
+        return [npx, "--yes", CLI_SPEC]
+    from .errors import BatchgridError
+
+    raise BatchgridError(
+        "cli_not_found",
+        "The batchgrid CLI was not found. Install Node.js 22 or newer "
+        "(https://nodejs.org), or point BATCHGRID_CLI at a batchgrid command.",
+    )
+
+
+def stream_events(
+    command: Sequence[str],
+    args: Sequence[str],
+    env: Optional[Mapping[str, str]] = None,
+) -> Iterator[Event]:
+    """Run the CLI and yield each JSON event as it is printed.
+
+    The last event is always a synthetic ``{"type": "exit", "code": ...,
+    "stderr": ...}``, so the caller sees how the process ended.
+
+    Ctrl+C (KeyboardInterrupt, also Jupyter's interrupt) is passed on to the
+    CLI as one SIGINT: the run stops, keeps its finished rows in the
+    checkpoint, and reports a ``stopped`` result before the interrupt is
+    raised again here.
+    """
+    full_env = {**os.environ, **(env or {}), "FORCE_COLOR": "0", "NO_COLOR": "1"}
+    popen_kwargs: Dict[str, object] = {}
+    if os.name == "nt":
+        popen_kwargs["creationflags"] = subprocess.CREATE_NEW_PROCESS_GROUP  # type: ignore[attr-defined]
+    else:
+        # Its own session, so a terminal's Ctrl+C reaches the CLI only through
+        # us - two SIGINTs would make it quit without saving
+        popen_kwargs["start_new_session"] = True
+
+    proc = subprocess.Popen(
+        [*command, *args],
+        stdin=subprocess.DEVNULL,
+        stdout=subprocess.PIPE,
+        stderr=subprocess.PIPE,
+        env=full_env,
+        text=True,
+        encoding="utf-8",
+        bufsize=1,
+        **popen_kwargs,  # type: ignore[arg-type]
+    )
+
+    # stderr is drained on its own thread so a chatty run cannot fill the pipe
+    stderr_tail: Deque[str] = deque(maxlen=40)
+    drain = threading.Thread(target=_drain, args=(proc.stderr, stderr_tail.append), daemon=True)
+    drain.start()
+
+    interrupted = False
+    try:
+        assert proc.stdout is not None
+        while True:
+            try:
+                line = proc.stdout.readline()
+            except KeyboardInterrupt:
+                if interrupted:
+                    proc.kill()
+                    raise
+                interrupted = True
+                _interrupt(proc)
+                continue
+            if not line:
+                break
+            line = line.strip()
+            if not line:
+                continue
+            try:
+                event = json.loads(line)
+            except ValueError:
+                # Not an event - an old CLI without --json, or stray output
+                stderr_tail.append(line)
+                continue
+            if isinstance(event, dict):
+                yield event
+        code = proc.wait()
+        drain.join(timeout=2)
+        yield {"type": "exit", "code": code, "stderr": "\n".join(stderr_tail)}
+    finally:
+        if proc.poll() is None:
+            proc.kill()
+            proc.wait()
+
+    if interrupted:
+        raise KeyboardInterrupt
+
+
+def _drain(pipe: Optional[object], sink: Callable[[str], None]) -> None:
+    if pipe is None:
+        return
+    for line in pipe:  # type: ignore[attr-defined]
+        sink(line.rstrip("\n"))
+
+
+def _interrupt(proc: "subprocess.Popen[str]") -> None:
+    if os.name == "nt":
+        # Windows has no SIGINT for another process group; CTRL_BREAK stops it at once
+        proc.send_signal(signal.CTRL_BREAK_EVENT)  # type: ignore[attr-defined]
+    else:
+        proc.send_signal(signal.SIGINT)
+    print("batchgrid: stopping the run and keeping finished rows…", file=sys.stderr)

batchgrid-0.1.0b1/src/batchgrid/errors.py

@@ -0,0 +1,55 @@
+"""Exceptions raised by batchgrid. Every one carries the CLI's error code."""
+
+from __future__ import annotations
+
+from typing import List, Optional
+
+
+class BatchgridError(Exception):
+    """A plan or a run could not go ahead.
+
+    ``code`` is the error code the CLI reported (``no_api_key``,
+    ``invalid_plan``, ``run_failed``...), or ``cli_failed`` when the CLI
+    stopped without saying why - ``stderr`` then holds its last output.
+    """
+
+    def __init__(self, code: str, message: str, stderr: str = "") -> None:
+        super().__init__(message)
+        self.code = code
+        self.message = message
+        self.stderr = stderr
+
+
+class NoPlanError(BatchgridError):
+    """The planner answered with a question instead of a plan.
+
+    ``reply`` is what it said - usually what it needs to know to make one.
+    """
+
+    def __init__(self, message: str, reply: Optional[str]) -> None:
+        super().__init__("no_plan", f"{message} The planner said: {reply}" if reply else message)
+        self.reply = reply
+
+
+class MissingSecretsError(BatchgridError):
+    """The plan calls a service whose key is not saved.
+
+    Save each one with ``batchgrid config --set-secret <name>:<value>``, or
+    set it in the environment, and run again.
+    """
+
+    def __init__(self, message: str, names: List[str]) -> None:
+        super().__init__("missing_secrets", message)
+        self.names = names
+
+
+class CostLimitError(BatchgridError):
+    """The estimated cost is above ``max_cost``, so nothing was run.
+
+    ``plan`` is the plan that was priced - inspect it, then run it with a
+    higher limit or on fewer rows.
+    """
+
+    def __init__(self, message: str, plan: object) -> None:
+        super().__init__("cost_limit", message)
+        self.plan = plan

batchgrid-0.1.0b1/tests/conftest.py

@@ -0,0 +1,154 @@
+"""Test fixtures: the real batchgrid CLI against a local stand-in for the OpenAI API.
+
+Nothing in the engine is stubbed. The CLI is the one built in packages/cli;
+only the model is replaced, by a server that answers the three kinds of call a
+run makes - column analysis, planning and one call per row.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import shutil
+import threading
+import time
+from http.server import BaseHTTPRequestHandler, ThreadingHTTPServer
+from pathlib import Path
+from typing import Any, Dict, Iterator, List
+
+import pytest
+
+REPO = Path(__file__).resolve().parents[2]
+CLI_ENTRY = REPO / "packages" / "cli" / "dist" / "index.js"
+
+PLAN: Dict[str, Any] = {
+    "title": "Classify sentiment",
+    "intent": "Label each review",
+    "sourceColumns": ["review"],
+    "steps": [
+        {
+            "id": "s1",
+            "kind": "llm",
+            "name": "Classify",
+            "promptTemplate": "Review: {{review}}",
+            "systemPrompt": "Classify the sentiment.",
+            "outputColumns": [{"name": "sentiment", "description": "positive or negative"}],
+        }
+    ],
+    "output": {"format": "csv"},
+}
+
+SUMMARY = {"description": "Product reviews", "columnDescriptions": [], "suggestions": []}
+
+
+class FakeModel:
+    """What the stand-in server answers, and what it was asked"""
+
+    def __init__(self) -> None:
+        self.planner_reply: Any = PLAN
+        self.row_delay = 0.0
+        self.calls: List[str] = []
+        self.lock = threading.Lock()
+
+    def answer(self, system: str, user: str) -> Any:
+        with self.lock:
+            self.calls.append(system[:40])
+        if system.startswith("You are a data analyst"):
+            return SUMMARY
+        if system.startswith("You are a batch workflow planner"):
+            return self.planner_reply
+        if self.row_delay:
+            time.sleep(self.row_delay)
+        return {"sentiment": "negative" if "Terrible" in user else "positive"}
+
+    @property
+    def row_calls(self) -> int:
+        return sum(1 for c in self.calls if c.startswith("Classify the sentiment."))
+
+    @property
+    def planner_calls(self) -> int:
+        return sum(1 for c in self.calls if c.startswith("You are a batch workflow planner"))
+
+
+def _handler(model: FakeModel) -> type:
+    class Handler(BaseHTTPRequestHandler):
+        def log_message(self, *args: object) -> None:
+            pass
+
+        def _send(self, body: Any) -> None:
+            data = json.dumps(body).encode()
+            self.send_response(200)
+            self.send_header("Content-Type", "application/json")
+            self.send_header("Content-Length", str(len(data)))
+            self.end_headers()
+            self.wfile.write(data)
+
+        def do_GET(self) -> None:
+            self._send({"object": "list", "data": [{"id": "gpt-5.6", "object": "model"}]})
+
+        def do_POST(self) -> None:
+            request = json.loads(self.rfile.read(int(self.headers["Content-Length"])))
+            messages = request["messages"]
+            system = next((m["content"] for m in messages if m["role"] == "system"), "")
+            user = "\n".join(m["content"] for m in messages if m["role"] == "user")
+            content = json.dumps(model.answer(system, user))
+            self._send(
+                {
+                    "id": "x",
+                    "object": "chat.completion",
+                    "created": 0,
+                    "model": request["model"],
+                    "choices": [{"index": 0, "finish_reason": "stop", "message": {"role": "assistant", "content": content}}],
+                    "usage": {"prompt_tokens": 10, "completion_tokens": 4, "total_tokens": 14},
+                }
+            )
+
+    return Handler
+
+
+@pytest.fixture
+def fake_model() -> Iterator[FakeModel]:
+    yield FakeModel()
+
+
+@pytest.fixture
+def cli_env(tmp_path: Path, fake_model: FakeModel) -> Iterator[Dict[str, str]]:
+    """Environment for the CLI: an isolated home, a key, and the stand-in model"""
+    # BATCHGRID_TEST_CLI tests an installed CLI instead, e.g. one from a packed tarball
+    installed = os.environ.get("BATCHGRID_TEST_CLI")
+    node = shutil.which("node")
+    if not installed and (node is None or not CLI_ENTRY.exists()):
+        pytest.skip("needs Node.js and a built CLI (pnpm --filter batchgrid build)")
+
+    server = ThreadingHTTPServer(("127.0.0.1", 0), _handler(fake_model))
+    thread = threading.Thread(target=server.serve_forever, daemon=True)
+    thread.start()
+
+    env = {
+        "BATCHGRID_CLI": f'"{installed}"' if installed else f'"{node}" "{CLI_ENTRY}"',
+        "BATCHGRID_HOME": str(tmp_path / "home"),
+        "OPENAI_API_KEY": "sk-test",
+        "OPENAI_BASE_URL": f"http://127.0.0.1:{server.server_port}/v1",
+    }
+    # Keys from the developer's own environment must not pick another provider
+    cleared = ["ANTHROPIC_API_KEY", "GOOGLE_API_KEY", "GEMINI_API_KEY", "OPENROUTER_API_KEY", "XAI_API_KEY"]
+    saved = {k: os.environ.get(k) for k in [*env, *cleared]}
+    os.environ.update(env)
+    for key in cleared:
+        os.environ.pop(key, None)
+    try:
+        yield env
+    finally:
+        server.shutdown()
+        for key, value in saved.items():
+            if value is None:
+                os.environ.pop(key, None)
+            else:
+                os.environ[key] = value
+
+
+@pytest.fixture
+def reviews_csv(tmp_path: Path) -> Path:
+    path = tmp_path / "reviews.csv"
+    path.write_text("review\nGreat product\nTerrible service\nOkay I guess\n", encoding="utf-8")
+    return path

batchgrid-0.1.0b1/tests/test_api.py

@@ -0,0 +1,157 @@
+from __future__ import annotations
+
+import _thread
+import sys
+import threading
+import time
+from pathlib import Path
+
+import pandas as pd
+import pytest
+
+import batchgrid
+from batchgrid import BatchgridError, CostLimitError, NoPlanError, Plan
+
+from conftest import PLAN, FakeModel
+
+pytestmark = pytest.mark.usefixtures("cli_env")
+
+
+def test_plan_prices_without_running(reviews_csv: Path, fake_model: FakeModel) -> None:
+    plan = batchgrid.plan(reviews_csv, "classify the sentiment of each review")
+
+    assert plan.title == "Classify sentiment"
+    assert plan.rows == 3
+    assert plan.missing_secrets == []
+    assert "sentiment" in plan.summary
+    assert fake_model.row_calls == 0
+
+
+def test_run_on_a_file_writes_the_output_next_to_it(reviews_csv: Path) -> None:
+    result = batchgrid.run(reviews_csv, "classify the sentiment of each review", progress=False)
+
+    assert (result.status, result.total, result.success, result.failed) == ("done", 3, 3, 0)
+    assert result.output_path == reviews_csv.with_name("reviews_output.csv")
+    assert "Terrible service,negative" in result.output_path.read_text(encoding="utf-8")
+    assert result.data is None
+
+
+def test_run_on_a_dataframe_adds_the_new_columns() -> None:
+    df = pd.DataFrame(
+        {"review": ["Great product", "Terrible service", "Okay I guess"], "stars": [5, 1, 3]},
+        index=["a", "b", "c"],
+    )
+
+    result = batchgrid.run(df, "classify the sentiment of each review", progress=False)
+
+    assert result.data is not None
+    assert list(result.data.columns) == ["review", "stars", "sentiment"]
+    assert list(result.data.index) == ["a", "b", "c"]
+    # The columns it had keep their types
+    assert result.data["stars"].dtype == df["stars"].dtype
+    assert result.data.loc["b", "sentiment"] == "negative"
+    # The caller's DataFrame is left as it was
+    assert list(df.columns) == ["review", "stars"]
+
+
+def test_a_saved_plan_runs_without_the_planner(reviews_csv: Path, tmp_path: Path, fake_model: FakeModel) -> None:
+    saved = batchgrid.plan(reviews_csv, "classify the sentiment of each review").save(tmp_path / "plan.json")
+    planner_calls = fake_model.planner_calls
+
+    result = batchgrid.run(reviews_csv, plan=Plan.load(saved), progress=False)
+
+    assert result.success == 3
+    assert fake_model.planner_calls == planner_calls
+
+
+def test_a_plan_dict_runs_as_is(reviews_csv: Path, fake_model: FakeModel) -> None:
+    result = batchgrid.run(reviews_csv, plan=PLAN, progress=False)
+    assert result.success == 3
+    assert fake_model.planner_calls == 0
+
+
+def test_max_cost_stops_before_any_row_runs(reviews_csv: Path, fake_model: FakeModel) -> None:
+    with pytest.raises(CostLimitError) as caught:
+        batchgrid.run(reviews_csv, "classify the sentiment of each review", max_cost=0.0000001, progress=False)
+
+    assert isinstance(caught.value.plan, Plan)
+    assert fake_model.row_calls == 0
+
+
+def test_max_cost_within_budget_runs_the_priced_plan(reviews_csv: Path, fake_model: FakeModel) -> None:
+    result = batchgrid.run(reviews_csv, "classify the sentiment of each review", max_cost=100, progress=False)
+
+    assert result.success == 3
+    # Priced once, then the same plan ran - the planner was asked once
+    assert fake_model.planner_calls == 1
+
+
+def test_a_plan_that_does_not_fit_the_sheet_is_refused(reviews_csv: Path, fake_model: FakeModel) -> None:
+    wrong = {**PLAN, "sourceColumns": ["body"], "steps": [{**PLAN["steps"][0], "promptTemplate": "{{body}}"}]}
+
+    with pytest.raises(BatchgridError) as caught:
+        batchgrid.run(reviews_csv, plan=wrong, progress=False)
+
+    assert caught.value.code == "invalid_plan"
+    assert fake_model.row_calls == 0
+
+
+def test_a_question_from_the_planner_is_raised_with_its_text(reviews_csv: Path, fake_model: FakeModel) -> None:
+    fake_model.planner_reply = {"kind": "message", "message": "Which column holds the review?"}
+
+    with pytest.raises(NoPlanError) as caught:
+        batchgrid.plan(reviews_csv, "do the thing")
+
+    assert caught.value.reply == "Which column holds the review?"
+
+
+def test_no_key_is_reported_by_code(reviews_csv: Path, monkeypatch: pytest.MonkeyPatch) -> None:
+    monkeypatch.delenv("OPENAI_API_KEY")
+    with pytest.raises(BatchgridError) as caught:
+        batchgrid.plan(reviews_csv, "classify")
+    assert caught.value.code == "no_api_key"
+
+
+def test_events_reach_the_callback(reviews_csv: Path) -> None:
+    seen = []
+    batchgrid.run(reviews_csv, "classify the sentiment of each review", progress=False, on_event=seen.append)
+
+    types = [e["type"] for e in seen]
+    assert "plan" in types
+    assert types[-1] == "result"
+
+
+def test_either_a_prompt_or_a_plan(reviews_csv: Path) -> None:
+    with pytest.raises(ValueError):
+        batchgrid.run(reviews_csv)
+    with pytest.raises(ValueError):
+        batchgrid.run(reviews_csv, "x", plan=PLAN)
+
+
+@pytest.mark.skipif(sys.platform == "win32", reason="SIGINT forwarding is POSIX-only")
+def test_ctrl_c_keeps_finished_rows_and_resume_finishes(tmp_path: Path, fake_model: FakeModel) -> None:
+    rows = "\n".join(f"Review number {i}" for i in range(40))
+    path = tmp_path / "many.csv"
+    path.write_text(f"review\n{rows}\n", encoding="utf-8")
+    fake_model.row_delay = 0.2
+
+    def interrupt_once_rows_run() -> None:
+        # Past the first few rows, so some have finished and are checkpointed
+        while fake_model.row_calls < 10:
+            time.sleep(0.02)
+        _thread.interrupt_main()
+
+    threading.Thread(target=interrupt_once_rows_run, daemon=True).start()
+    with pytest.raises(KeyboardInterrupt):
+        batchgrid.run(path, plan=PLAN, concurrency=2, progress=False)
+    stopped_after = fake_model.row_calls
+    assert stopped_after < 40
+
+    fake_model.row_delay = 0
+    result = batchgrid.resume(path, progress=False)
+
+    assert result.status == "done"
+    assert result.total == 40
+    # Only the unfinished rows went to the model again
+    assert fake_model.row_calls - stopped_after < 40
+    assert len(pd.read_csv(result.output_path)) == 40