batchgrid 0.1.0b1__py3-none-any.whl

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/_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/_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/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.dist-info/METADATA

@@ -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.dist-info/RECORD

@@ -0,0 +1,8 @@
+batchgrid/__init__.py,sha256=R_5Ckff_R3mp2iy4x0u6NxW-I6ZHN6Qyx8xK_LLb8b4,779
+batchgrid/_api.py,sha256=Q56_C66-WHrezUSwSp9Lc25DTy4ygco30Aq8u2Yo-tA,17558
+batchgrid/_cli.py,sha256=Db7IcrfNEB3uVuYjWaQr328gqa4k7WZYtx1nUnrHdbY,4864
+batchgrid/errors.py,sha256=36zxxjPc9yt5kKJ105oEgZETgeSEqv8uLrbhC9Pw5Cs,1757
+batchgrid/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+batchgrid-0.1.0b1.dist-info/METADATA,sha256=wysHtSm2ppcZIvq2r1G3qJXhx_nY7srCFr4sPH6anno,6180
+batchgrid-0.1.0b1.dist-info/WHEEL,sha256=W3fkpkm7-wf9vBI5Z-7s0eWkeM-spu78I8Neb98DeEg,87
+batchgrid-0.1.0b1.dist-info/RECORD,,

batchgrid-0.1.0b1.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.32.4
+Root-Is-Purelib: true
+Tag: py3-none-any