batchor 0.0.4__tar.gz → 0.0.5__tar.gz

{batchor-0.0.4 → batchor-0.0.5}/.agents/skills/batchor-dev/SKILL.md

@@ -14,13 +14,14 @@ Use this skill for normal contributor work in this repository.
 3. Load only the design docs that match the task:
    - `docs/design_docs/ARCHITECTURE.md` for package layout and runtime boundaries
    - `docs/design_docs/OPENAI_BATCHING.md` for provider-specific batching behavior
+   - `docs/design_docs/ANTHROPIC_BATCHING.md` for Anthropic Message Batches behavior
    - `docs/design_docs/STORAGE_AND_RUNS.md` for durable state, run lifecycle, and retention
    - `docs/smoke-test.md` for the full validation matrix
 
 ## Repo map
 
 - `src/batchor/runtime/`: orchestration, run handles, validation, retry, token budgeting
-- `src/batchor/providers/`: provider interfaces and OpenAI Batch implementation
+- `src/batchor/providers/`: provider interfaces and OpenAI, Anthropic, and Gemini implementations
 - `src/batchor/storage/`: SQLite, Postgres, and in-memory durability backends
 - `src/batchor/sources/`: file-backed checkpointable item sources
 - `src/batchor/artifacts/`: durable request/output artifact handling

{batchor-0.0.4 → batchor-0.0.5}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: batchor
-Version: 0.0.4
+Version: 0.0.5
 Summary: Structured-first provider Batch runner with typed Pydantic results.
 Project-URL: Documentation, https://github.com/AnsonDev42/batchor#readme
 Project-URL: Repository, https://github.com/AnsonDev42/batchor
@@ -79,7 +79,7 @@ License: # PolyForm Noncommercial License 1.0.0
         
         **Use** means anything you do with the software requiring one of your licenses.
 License-File: LICENSE
-Keywords: batch,cli,gemini,openai,pydantic,sqlite
+Keywords: anthropic,batch,cli,gemini,openai,pydantic,sqlite
 Classifier: Development Status :: 3 - Alpha
 Classifier: Environment :: Console
 Classifier: Intended Audience :: Developers
@@ -99,6 +99,8 @@ Requires-Dist: python-dotenv<2,>=1.0.1
 Requires-Dist: sqlalchemy<3,>=2.0.43
 Requires-Dist: tiktoken>=0.12.0
 Requires-Dist: typer<1,>=0.16.0
+Provides-Extra: anthropic
+Requires-Dist: anthropic<1,>=0.71.0; extra == 'anthropic'
 Provides-Extra: gemini
 Requires-Dist: google-cloud-storage<4,>=3.4.0; extra == 'gemini'
 Requires-Dist: google-genai<2,>=1.55.0; extra == 'gemini'
@@ -118,7 +120,7 @@ Description-Content-Type: text/markdown
 - library-first run controls
 - a small operator CLI for CSV and JSONL jobs
 
-It is intentionally narrow today: OpenAI is the CLI default, Gemini is opt-in through `batchor[gemini]`, SQLite is the CLI durability backend, and the Python API exposes the broadest configuration surface.
+It is intentionally narrow today: OpenAI is the CLI default, Anthropic and Gemini are opt-in through provider extras, SQLite is the CLI durability backend, and the Python API exposes the broadest configuration surface.
 
 ## What problem it solves
 
@@ -143,6 +145,7 @@ Most OpenAI Batch examples stop at "upload a JSONL file and poll until it finish
 Built-in implementations:
 
 - `OpenAIProviderConfig` + `OpenAIBatchProvider`
+- `AnthropicProviderConfig` + `AnthropicBatchProvider` for Claude Message Batches
 - `GeminiProviderConfig` + `GeminiBatchProvider` for text-only Gemini Batch jobs
 - `SQLiteStorage`
 - `PostgresStorage` as an opt-in durable control-plane backend
@@ -159,7 +162,7 @@ Important constraints:
 - the CLI supports file-backed inputs only
 - users still own selecting and ordering input files or partitions
 - the built-in CLI uses SQLite durability only
-- the CLI supports OpenAI plus Gemini Developer API and Vertex AI text jobs
+- the CLI supports OpenAI, Anthropic, Gemini Developer API, and Vertex AI text jobs
 - Gemini support is text-only for now and does not build multimodal requests
 - structured-output rehydration requires an importable module-level Pydantic model
 - raw output artifacts are retained by default and must be exported before raw pruning
@@ -185,6 +188,14 @@ Durability is split on purpose:
 
 That split is what allows retries and fresh-process resume without keeping every request inline in the control-plane store.
 On resume, existing active provider batches are polled before `batchor` materializes or submits new local work, so completed batches and retry backoff are reconciled first. Deterministic sources also use stored checkpoint completion metadata to avoid opening a fully materialized Parquet or composite source just to discover there are no rows left.
+Incomplete checkpointed ingestion keeps the run non-terminal. In the process that
+started the job, `Run.resume()` can continue from the attached source. After a
+fresh-process rehydration, call `start(job, run_id=...)`; `refresh()` otherwise
+raises `RunIngestionSourceRequiredError` instead of silently completing only the
+already-materialized rows.
+Cancelling an incompletely ingested checkpointed source abandons its
+unmaterialized tail and finalizes the checkpoint after active batches drain, so
+the cancelled run can still reach a terminal lifecycle state.
 
 ## Architecture
 
@@ -195,10 +206,12 @@ graph LR
     subgraph runtime["runtime/"]
         BatchRunner
         Run["Run handle"]
+        Executor["RunExecutor"]
     end
 
     subgraph providers["providers/"]
         OpenAI["OpenAIBatchProvider"]
+        Anthropic["AnthropicBatchProvider"]
         Gemini["GeminiBatchProvider"]
     end
 
@@ -218,7 +231,9 @@ graph LR
 
     User -->|"start() / run_and_wait()"| BatchRunner
     BatchRunner --> Run
+    BatchRunner --> Executor
     BatchRunner --> OpenAI
+    BatchRunner --> Anthropic
     BatchRunner --> Gemini
     BatchRunner --> SQLite
     BatchRunner --> LocalFS
@@ -261,6 +276,12 @@ For Gemini Batch support, install the optional extra:
 pip install "batchor[gemini]"
 ```
 
+For Anthropic Message Batches support:
+
+```bash
+pip install "batchor[anthropic]"
+```
+
 ## Agent setup
 
 Batchor keeps contributor tooling separate from the tools intended for researchers and downstream projects:
@@ -291,8 +312,8 @@ Supported Python versions:
 
 For Python API usage, auth resolution is:
 
-1. explicit provider config credentials such as `OpenAIProviderConfig(api_key=...)` or `GeminiProviderConfig(api_key=...)`
-2. ambient provider environment variables, currently `OPENAI_API_KEY` or `GEMINI_API_KEY`
+1. explicit provider config credentials such as `OpenAIProviderConfig(api_key=...)`, `AnthropicProviderConfig(api_key=...)`, or `GeminiProviderConfig(api_key=...)`
+2. ambient provider environment variables: `OPENAI_API_KEY`, `ANTHROPIC_API_KEY`, or `GEMINI_API_KEY`
 3. Vertex AI Application Default Credentials when `GeminiProviderConfig(vertexai=True, ...)` or `GOOGLE_GENAI_USE_VERTEXAI=true` is used
 
 The Python library does not auto-load `.env`.
@@ -322,6 +343,29 @@ run = runner.run_and_wait(
 print(run.results()[0].output_text)
 ```
 
+### Anthropic text job
+
+```python
+from batchor import AnthropicProviderConfig, BatchItem, BatchJob, BatchRunner, PromptParts
+
+
+runner = BatchRunner(storage="memory")
+run = runner.run_and_wait(
+    BatchJob(
+        items=[BatchItem(item_id="row1", payload="Summarize this text")],
+        build_prompt=lambda item: PromptParts(prompt=item.payload),
+        provider_config=AnthropicProviderConfig(
+            model="claude-sonnet-4-5",
+            max_tokens=1024,
+        ),
+    )
+)
+
+print(run.results()[0].output_text)
+```
+
+Anthropic support maps Batchor attempt identifiers deterministically to Claude-safe `custom_id` values and supports system prompts, `message_params`, and structured outputs through `output_config.format`.
+
 ### Gemini text job
 
 ```python

{batchor-0.0.4 → batchor-0.0.5}/README.md

@@ -12,7 +12,7 @@
 - library-first run controls
 - a small operator CLI for CSV and JSONL jobs
 
-It is intentionally narrow today: OpenAI is the CLI default, Gemini is opt-in through `batchor[gemini]`, SQLite is the CLI durability backend, and the Python API exposes the broadest configuration surface.
+It is intentionally narrow today: OpenAI is the CLI default, Anthropic and Gemini are opt-in through provider extras, SQLite is the CLI durability backend, and the Python API exposes the broadest configuration surface.
 
 ## What problem it solves
 
@@ -37,6 +37,7 @@ Most OpenAI Batch examples stop at "upload a JSONL file and poll until it finish
 Built-in implementations:
 
 - `OpenAIProviderConfig` + `OpenAIBatchProvider`
+- `AnthropicProviderConfig` + `AnthropicBatchProvider` for Claude Message Batches
 - `GeminiProviderConfig` + `GeminiBatchProvider` for text-only Gemini Batch jobs
 - `SQLiteStorage`
 - `PostgresStorage` as an opt-in durable control-plane backend
@@ -53,7 +54,7 @@ Important constraints:
 - the CLI supports file-backed inputs only
 - users still own selecting and ordering input files or partitions
 - the built-in CLI uses SQLite durability only
-- the CLI supports OpenAI plus Gemini Developer API and Vertex AI text jobs
+- the CLI supports OpenAI, Anthropic, Gemini Developer API, and Vertex AI text jobs
 - Gemini support is text-only for now and does not build multimodal requests
 - structured-output rehydration requires an importable module-level Pydantic model
 - raw output artifacts are retained by default and must be exported before raw pruning
@@ -79,6 +80,14 @@ Durability is split on purpose:
 
 That split is what allows retries and fresh-process resume without keeping every request inline in the control-plane store.
 On resume, existing active provider batches are polled before `batchor` materializes or submits new local work, so completed batches and retry backoff are reconciled first. Deterministic sources also use stored checkpoint completion metadata to avoid opening a fully materialized Parquet or composite source just to discover there are no rows left.
+Incomplete checkpointed ingestion keeps the run non-terminal. In the process that
+started the job, `Run.resume()` can continue from the attached source. After a
+fresh-process rehydration, call `start(job, run_id=...)`; `refresh()` otherwise
+raises `RunIngestionSourceRequiredError` instead of silently completing only the
+already-materialized rows.
+Cancelling an incompletely ingested checkpointed source abandons its
+unmaterialized tail and finalizes the checkpoint after active batches drain, so
+the cancelled run can still reach a terminal lifecycle state.
 
 ## Architecture
 
@@ -89,10 +98,12 @@ graph LR
     subgraph runtime["runtime/"]
         BatchRunner
         Run["Run handle"]
+        Executor["RunExecutor"]
     end
 
     subgraph providers["providers/"]
         OpenAI["OpenAIBatchProvider"]
+        Anthropic["AnthropicBatchProvider"]
         Gemini["GeminiBatchProvider"]
     end
 
@@ -112,7 +123,9 @@ graph LR
 
     User -->|"start() / run_and_wait()"| BatchRunner
     BatchRunner --> Run
+    BatchRunner --> Executor
     BatchRunner --> OpenAI
+    BatchRunner --> Anthropic
     BatchRunner --> Gemini
     BatchRunner --> SQLite
     BatchRunner --> LocalFS
@@ -155,6 +168,12 @@ For Gemini Batch support, install the optional extra:
 pip install "batchor[gemini]"
 ```
 
+For Anthropic Message Batches support:
+
+```bash
+pip install "batchor[anthropic]"
+```
+
 ## Agent setup
 
 Batchor keeps contributor tooling separate from the tools intended for researchers and downstream projects:
@@ -185,8 +204,8 @@ Supported Python versions:
 
 For Python API usage, auth resolution is:
 
-1. explicit provider config credentials such as `OpenAIProviderConfig(api_key=...)` or `GeminiProviderConfig(api_key=...)`
-2. ambient provider environment variables, currently `OPENAI_API_KEY` or `GEMINI_API_KEY`
+1. explicit provider config credentials such as `OpenAIProviderConfig(api_key=...)`, `AnthropicProviderConfig(api_key=...)`, or `GeminiProviderConfig(api_key=...)`
+2. ambient provider environment variables: `OPENAI_API_KEY`, `ANTHROPIC_API_KEY`, or `GEMINI_API_KEY`
 3. Vertex AI Application Default Credentials when `GeminiProviderConfig(vertexai=True, ...)` or `GOOGLE_GENAI_USE_VERTEXAI=true` is used
 
 The Python library does not auto-load `.env`.
@@ -216,6 +235,29 @@ run = runner.run_and_wait(
 print(run.results()[0].output_text)
 ```
 
+### Anthropic text job
+
+```python
+from batchor import AnthropicProviderConfig, BatchItem, BatchJob, BatchRunner, PromptParts
+
+
+runner = BatchRunner(storage="memory")
+run = runner.run_and_wait(
+    BatchJob(
+        items=[BatchItem(item_id="row1", payload="Summarize this text")],
+        build_prompt=lambda item: PromptParts(prompt=item.payload),
+        provider_config=AnthropicProviderConfig(
+            model="claude-sonnet-4-5",
+            max_tokens=1024,
+        ),
+    )
+)
+
+print(run.results()[0].output_text)
+```
+
+Anthropic support maps Batchor attempt identifiers deterministically to Claude-safe `custom_id` values and supports system prompts, `message_params`, and structured outputs through `output_config.format`.
+
 ### Gemini text job
 
 ```python

batchor-0.0.5/docs/design_docs/ANTHROPIC_BATCHING.md

@@ -0,0 +1,33 @@
+# Anthropic Batching
+
+The built-in Anthropic provider targets the Claude Message Batches API.
+
+## Request mapping
+
+Each Batchor item attempt becomes one Anthropic batch request:
+
+- Batchor's durable correlation identifier is deterministically hashed into Anthropic's 64-character-safe `custom_id` alphabet
+- `PromptParts.prompt` becomes one user message
+- `PromptParts.system_prompt` becomes the top-level `system` parameter
+- `model` and `max_tokens` come from `AnthropicProviderConfig`
+- `message_params` supplies optional Messages API parameters
+- structured output schemas use `output_config.format`
+
+Batchor rejects provider-owned fields in `message_params` so replayed requests cannot silently change model, token limit, messages, system prompt, or streaming behavior.
+
+## Submission and lifecycle
+
+Anthropic accepts request objects directly rather than an uploaded JSONL file. The provider therefore stages Batchor's durable request artifact in memory only for the upload/create boundary, then calls `messages.batches.create(requests=...)`.
+
+Anthropic `in_progress` maps to Batchor's active status and `ended` maps to `completed`. Once ended, the provider streams `messages.batches.results(...)` into Batchor's raw output artifact. Result order is not assumed; correlation always uses `custom_id`.
+
+The four Anthropic result types map as follows:
+
+- `succeeded`: Batchor success
+- `errored`, `canceled`, and `expired`: Batchor item error, subject to the configured retry policy
+
+## Limits and retention
+
+Anthropic currently limits a Message Batch to 100,000 requests or 256 MB. Batchor's default chunk limits are lower than both limits. Claude batch results remain available from Anthropic for 29 days; Batchor downloads and retains them according to its artifact policy, so durable runs do not depend on that remote retention window after ingestion.
+
+Message Batches are not eligible for Anthropic Zero Data Retention. Users should account for Anthropic's batch retention policy when selecting workloads.

{batchor-0.0.4 → batchor-0.0.5}/docs/design_docs/ARCHITECTURE.md

@@ -61,6 +61,7 @@ graph TB
     subgraph providers["providers/"]
         BatchProvider["BatchProvider (ABC)"]
         OpenAIProvider["OpenAIBatchProvider"]
+        AnthropicProvider["AnthropicBatchProvider"]
         GeminiProvider["GeminiBatchProvider"]
         ProviderRegistry
     end
@@ -95,6 +96,7 @@ graph TB
     MemoryStateStore -.->|implements| StateStore
     BatchRunner -->|submits/polls| BatchProvider
     OpenAIProvider -.->|implements| BatchProvider
+    AnthropicProvider -.->|implements| BatchProvider
     GeminiProvider -.->|implements| BatchProvider
     BatchRunner -->|stores artifacts| ArtifactStore
     LocalArtifactStore -.->|implements| ArtifactStore
@@ -126,7 +128,7 @@ one logical source, while callers remain responsible for selecting and ordering
 the child sources up front.
 
 Provider adaptation is intentionally concentrated behind `BatchProvider`.
-The runtime stores one durable internal custom identifier per item attempt, while each provider maps that identifier to its own request shape. OpenAI uses `custom_id`; the Gemini Developer API uses `key`; Vertex AI uses a request label that is returned with the original request in GCS output.
+The runtime stores one durable internal custom identifier per item attempt, while each provider maps that identifier to its own request shape. OpenAI and Anthropic use `custom_id`; the Gemini Developer API uses `key`; Vertex AI uses a request label that is returned with the original request in GCS output.
 Provider hooks also own response-text extraction so structured-output parsing can stay generic across provider payload shapes.
 
 ## Main user-facing flow
@@ -311,6 +313,7 @@ Owns provider-facing abstractions and implementations:
 - base provider contract
 - provider registry
 - OpenAI Batch implementation
+- Anthropic Message Batches implementation
 
 The provider layer is responsible for:
 
@@ -350,8 +353,12 @@ Owns execution behavior:
 
 This is where the durable lifecycle lives. It bridges the domain models, providers, storage, and artifact store.
 
-The public facade is still `BatchRunner` plus `Run`, but the current internal layering under `runtime/` is intentionally split so execution concerns do not collapse back into one file:
+The public facade is still `BatchRunner` plus `Run`. A deep internal
+`RunExecutor` module owns execution attachment and the ordered advance cycle,
+returning a structured outcome that reports durable progress.
+The supporting implementation under `runtime/` remains split by concern:
 
+- `execution.py`: claim recovery on execution attachment, source-availability checks, and ordered ingest/poll/cancel/submit advancement
 - `context.py`: persisted config building, resume config comparison, output-model resolution, and provider-backed `RunContext` creation
 - `ingestion.py`: checkpoint-aware item materialization, ingest checkpoint updates, and resume-aware ingestion flow
 - `submission.py`: pending-item claiming, request replay/build, token-budget gating, request artifact persistence, and batch submission
@@ -432,7 +439,7 @@ That split gives `batchor`:
 ## Current invariants
 
 1. Public execution is run-oriented: `start()`, `get_run()`, `run_and_wait()`.
-2. OpenAI Batch and text-only Gemini Batch are built-in Python and CLI providers; OpenAI remains the CLI default.
+2. OpenAI Batch, Anthropic Message Batches, and text-only Gemini Batch are built-in Python and CLI providers; OpenAI remains the CLI default.
 3. SQLite is the default durable backend.
 4. Postgres is an opt-in durable backend for shared control-plane state.
 5. Structured outputs require a module-level Pydantic v2 model for rehydration.
@@ -450,7 +457,11 @@ That split gives `batchor`:
 17. Run lifecycle status and run control state are separate; pause/cancel do not redefine terminal lifecycle semantics.
 18. Incremental terminal-result reads are sequence-based and only return items that have already reached a terminal item state.
 19. Built-in deterministic-source resume currently covers CSV, JSONL, and Parquet; arbitrary iterables still do not become durable by magic.
-20. `BatchItem.metadata["batchor_lineage"]` is reserved for lightweight source/join metadata when provided by built-in adapters or callers.
+20. An incomplete ingest checkpoint prevents terminal lifecycle status. A fresh
+    process must reattach the source with `start(job, run_id=...)` before execution
+    can advance, unless cancellation intentionally abandons the unmaterialized
+    source tail and finalizes the checkpoint.
+21. `BatchItem.metadata["batchor_lineage"]` is reserved for lightweight source/join metadata when provided by built-in adapters or callers.
 
 ## Extension seams
 

{batchor-0.0.4 → batchor-0.0.5}/docs/design_docs/OPENAI_BATCHING.md

@@ -2,11 +2,11 @@
 
 This document describes the OpenAI-specific behavior inside `batchor`.
 
-OpenAI remains the default and most feature-complete provider path. Gemini has its own design note in [`GEMINI_BATCHING.md`](GEMINI_BATCHING.md), while this page focuses only on OpenAI Batch semantics.
+OpenAI remains the default and most feature-complete provider path. Anthropic and Gemini have their own design notes in [`ANTHROPIC_BATCHING.md`](ANTHROPIC_BATCHING.md) and [`GEMINI_BATCHING.md`](GEMINI_BATCHING.md), while this page focuses only on OpenAI Batch semantics.
 
 ## Current behavior
 
-The Python API and CLI both support OpenAI. The CLI is OpenAI-only today.
+The Python API and CLI both support OpenAI, which remains the CLI default.
 
 ## Request construction
 
@@ -58,6 +58,9 @@ That currently includes CSV, JSONL, Parquet, and `CompositeItemSource` for order
 When `CompositeItemSource` is used, child-source row IDs are auto-namespaced into run-unique `item_id` values, while the original row ID is preserved in lineage metadata.
 Custom non-file sources must implement a durable checkpoint contract explicitly; arbitrary iterables and live DB cursors are still `TBD`.
 Before resumed ingestion continues, active OpenAI batches are polled once. If that poll consumes terminal batches or records enqueue/backoff failures, those state changes are applied before any new prompt rendering, request replay, or submission happens.
+The execution cycle reports durable progress explicitly to `Run.wait()`, so the
+wait loop immediately drains productive poll/submission cycles and sleeps only
+when a cycle makes no durable progress, respecting any persisted retry backoff.
 
 ## Raw output retention
 

{batchor-0.0.4 → batchor-0.0.5}/docs/design_docs/ROADMAP.md

@@ -4,17 +4,13 @@ This file tracks important work that should be explicit in the extracted reposit
 
 ## Next Practical Steps
 
-- add Postgres storage backend
-- extend resumable ingestion beyond the built-in CSV/JSONL sources
 - add automated retention windows on top of the explicit export/prune lifecycle
-- add more input adapters beyond CSV and JSONL
-- expose non-OpenAI providers through CLI workflows once provider-specific auth and flags are stable
 - add CLI structured-output workflows if the importability story can stay durable and predictable
 
 ## Longer-Term Ideas
 
-- additional provider coverage beyond OpenAI and text-only Gemini
-- artifact store abstraction
+- additional provider coverage beyond OpenAI, Anthropic, and text-only Gemini
+- remote/shared artifact store implementations beyond the local filesystem abstraction
 - partial-result streaming APIs
 - richer CLI or operator workflow beyond the current file-backed text-job surface
 

{batchor-0.0.4 → batchor-0.0.5}/docs/design_docs/STORAGE_AND_RUNS.md

@@ -37,7 +37,7 @@ Important semantics:
 
 - `status` is cached from the last summary read or refresh
 - `refresh()` performs one poll-and-submit pass
-- `wait()` repeatedly refreshes until the run is terminal, and skips the poll-interval sleep after refreshes that complete items, fail items, or submit additional batches
+- `wait()` repeatedly advances through the internal executor until the run is terminal, and skips the poll-interval sleep when the structured cycle outcome reports durable progress
 - `results()` and artifact lifecycle operations are terminal-only
 - terminal currently means either `completed` or `completed_with_failures`
 - `read_terminal_results()` and `export_terminal_results()` are incremental APIs for already-terminal items and are safe to call before the whole run finishes
@@ -177,11 +177,18 @@ Successful rehydration depends on:
 - credentials being available when a refresh needs to talk to the provider
 
 Fresh-process resume also requeues any `queued_local` items back to `pending` before submission resumes.
+This recovery happens when an execution owner advances the run, not when a
+caller merely reads a handle with `get_run()` or changes control state.
 When `start(job, run_id=...)` resumes a run with active provider batches, it first performs a poll-only reconciliation pass. Terminal provider batches are consumed, failed batches update retry backoff, and any active backoff prevents new source materialization or submission until the backoff expires.
 
 Resume compatibility intentionally ignores non-persisted secret fields such as provider API keys. Rehydrated OpenAI runs need `OPENAI_API_KEY` when no explicit in-memory config is supplied. Gemini Developer API runs need `GEMINI_API_KEY`; Vertex runs need Application Default Credentials plus the persisted or ambient project, location, and GCS prefix configuration.
 
 For deterministic-source resume, the caller must also reuse the same `run_id` and provide the same source identity/fingerprint.
+An incomplete ingest checkpoint is part of terminal-state calculation. In the
+same process, `Run.resume()` continues ingestion when the original job remains
+attached. A rehydrated run without that source stays non-terminal and raises
+`RunIngestionSourceRequiredError` from `refresh()`/`wait()`, directing the caller
+to `start(job, run_id=...)`.
 For composite sources, that includes the same ordered child identities; changing the child order or swapping one file changes the logical source identity.
 
 Built-in deterministic sources currently include:
@@ -240,6 +247,12 @@ Semantics:
 - `resume` restarts those local activities from persisted state
 - `cancel` stops new ingestion/submission, keeps polling active provider batches, and then permanently fails remaining local non-terminal items with `error_class="run_cancelled"`
 
+If checkpointed ingestion is incomplete when cancellation is requested, the
+unmaterialized source tail is intentionally abandoned. After active batches
+drain and remaining materialized items are cancelled, the stored ingest
+checkpoint is finalized so the run can become terminal without reopening the
+source.
+
 Manual pauses record `control_reason="manual"`. OpenAI upload/create/polling and batch-level insufficient-quota pauses record `control_reason="openai_insufficient_quota"`, clear batch-control-plane backoff, and preserve affected items for later retry without consuming attempts.
 
 Row-level insufficient-quota records inside completed batch outputs do not pause the run. Those items are stored as `failed_retryable` with `error_class="openai_insufficient_quota"`, do not consume attempts, and rely on retry backoff before they are submitted again.

{batchor-0.0.4 → batchor-0.0.5}/docs/doc-map.md

@@ -19,6 +19,7 @@ This page explains what each document is for so readers do not have to guess whi
 | `design_docs/BOUNDARY_AND_PHILOSOPHY.md` | Ownership boundary between `batchor`, storage/artifacts, and user pipelines. |
 | `design_docs/ARCHITECTURE.md` | Canonical runtime diagrams, package structure, main flows, and extension seams. |
 | `design_docs/OPENAI_BATCHING.md` | OpenAI request construction, token budgeting, splitting, and batch polling behavior. |
+| `design_docs/ANTHROPIC_BATCHING.md` | Anthropic Message Batches request construction, polling, result parsing, limits, and retention. |
 | `design_docs/GEMINI_BATCHING.md` | Gemini text-only request construction, batch polling, response parsing, and current limits. |
 | `design_docs/STORAGE_AND_RUNS.md` | Durable `Run` lifecycle, rehydration, checkpoints, control state, artifact retention, and operator semantics. |
 | `design_docs/STORAGE_MIGRATIONS.md` | SQLite schema-versioning and migration guidance. |
@@ -40,3 +41,4 @@ This page explains what each document is for so readers do not have to guess whi
 - Incremental terminal-result reads/exports are documented in the Python API and storage docs.
 - Raw output/error artifact retention is now configurable per run through `ArtifactPolicy`.
 - Gemini text-only Batch support is available through the Python API and default provider registry.
+- Anthropic Message Batches support is available through the Python API, CLI, and default provider registry.

{batchor-0.0.4 → batchor-0.0.5}/docs/getting-started/cli.md

@@ -40,6 +40,13 @@ pip install "batchor[gemini]"
 echo "GEMINI_API_KEY=..." > .env
 ```
 
+For Anthropic:
+
+```bash
+pip install "batchor[anthropic]"
+echo "ANTHROPIC_API_KEY=..." > .env
+```
+
 ## Start a run from JSONL
 
 ```bash
@@ -66,6 +73,20 @@ Use `--prompt-template` when the prompt should be derived from several fields.
 
 Exactly one of `--prompt-field` or `--prompt-template` is required.
 
+## Start an Anthropic run
+
+```bash
+batchor start \
+  --input input/items.jsonl \
+  --id-field id \
+  --prompt-field text \
+  --provider anthropic \
+  --model claude-sonnet-4-5 \
+  --anthropic-max-tokens 1024
+```
+
+Use `--anthropic-message-params` for an additional JSON object such as `'{"temperature":0.2}'`.
+
 ## Start a Gemini Developer API run
 
 ```bash

{batchor-0.0.4 → batchor-0.0.5}/docs/getting-started/installation.md

@@ -22,6 +22,12 @@ pip install "batchor[gemini]"
 
 Gemini support is text-only and is available through both the Python API and CLI.
 
+Anthropic support uses the optional Anthropic SDK dependency:
+
+```bash
+pip install "batchor[anthropic]"
+```
+
 ## What gets installed
 
 The package includes:
@@ -29,6 +35,7 @@ The package includes:
 - the Python library
 - the `batchor` CLI
 - the built-in OpenAI provider integration
+- the built-in Anthropic provider integration when `batchor[anthropic]` is installed
 - the built-in Gemini provider integration when `batchor[gemini]` is installed
 - SQLite and Postgres storage implementations
 
@@ -63,11 +70,16 @@ For Gemini Developer API usage, authentication resolution is:
 1. `GeminiProviderConfig(api_key=...)`
 2. `GEMINI_API_KEY`
 
+For Anthropic usage, authentication resolution is:
+
+1. `AnthropicProviderConfig(api_key=...)`
+2. `ANTHROPIC_API_KEY`
+
 Vertex AI uses Application Default Credentials and resolves project/location from explicit `GeminiProviderConfig` fields or `GOOGLE_CLOUD_PROJECT` and `GOOGLE_CLOUD_LOCATION`. Vertex batches also require a writable `gs://` staging prefix.
 
 The Python library does not auto-load `.env`.
 
-The CLI loads a local `.env` as a convenience for operator usage. It resolves `OPENAI_API_KEY` for OpenAI, `GEMINI_API_KEY` for the Gemini Developer API, and the documented Google Cloud environment variables for Vertex AI. Rehydrated `status`, `wait`, and result operations load the same `.env` before reconstructing a provider.
+The CLI loads a local `.env` as a convenience for operator usage. It resolves `OPENAI_API_KEY`, `ANTHROPIC_API_KEY`, `GEMINI_API_KEY`, and the documented Google Cloud environment variables for Vertex AI. Rehydrated `status`, `wait`, and result operations load the same `.env` before reconstructing a provider.
 
 ## Storage defaults
 

{batchor-0.0.4 → batchor-0.0.5}/docs/getting-started/python-api.md

@@ -39,6 +39,31 @@ print(run.results()[0].output_text)
 
 Use `storage="memory"` only for tests or short-lived local experiments. For durable runs, use the default SQLite storage or an explicit backend.
 
+## Anthropic text job
+
+Install `batchor[anthropic]`, then use the same runner lifecycle with an Anthropic provider config:
+
+```python
+from batchor import AnthropicProviderConfig, BatchItem, BatchJob, BatchRunner, PromptParts
+
+
+runner = BatchRunner(storage="memory")
+run = runner.run_and_wait(
+    BatchJob(
+        items=[BatchItem(item_id="row1", payload="Summarize this text")],
+        build_prompt=lambda item: PromptParts(prompt=item.payload),
+        provider_config=AnthropicProviderConfig(
+            model="claude-sonnet-4-5",
+            max_tokens=1024,
+        ),
+    )
+)
+
+print(run.results()[0].output_text)
+```
+
+If `api_key` is omitted, the provider resolves `ANTHROPIC_API_KEY`. Extra Messages API parameters such as `temperature` can be supplied through `message_params`; Batchor reserves the fields it constructs itself.
+
 ## Gemini text job
 
 Gemini Batch support is available through the Python API after installing `batchor[gemini]`.
@@ -131,6 +156,7 @@ Notes:
 - `output` is the parsed Pydantic object
 - `output_text` preserves the raw text that was parsed
 - with `GeminiProviderConfig`, the same `structured_output=` argument is sent through Gemini `generation_config.response_json_schema`
+- with `AnthropicProviderConfig`, it is sent through Anthropic `output_config.format`
 
 ## Durable run lifecycle
 

{batchor-0.0.4 → batchor-0.0.5}/docs/index.md

@@ -56,7 +56,7 @@ If that is the mental model you were missing from the generated docs, start with
 
 ## Current surface
 
-- Built-in providers: OpenAI Batch, plus text-only Gemini Batch for Python API usage
+- Built-in providers: OpenAI Batch, Anthropic Message Batches, and text-only Gemini Batch through Python and CLI workflows
 - Durable storage: SQLite by default, Postgres as an opt-in control-plane backend
 - Ephemeral storage: in-memory state store
 - Artifact backend: local filesystem via `LocalArtifactStore`

{batchor-0.0.4 → batchor-0.0.5}/docs/policies/contributing.md

@@ -13,7 +13,7 @@ Before submitting changes:
 Please keep changes aligned with the documented package boundary:
 
 - durable batch execution
-- OpenAI Batch provider support
+- OpenAI, Anthropic, and Gemini Batch provider support
 - SQLite-backed local durability by default
 
 Out-of-scope proposals are still useful, but should usually start as an issue discussing fit before implementation.

{batchor-0.0.4 → batchor-0.0.5}/docs/reference/api.md

@@ -20,6 +20,7 @@ Most users only need a small subset of the package:
 - `BatchRunner`: start, resume, and run orchestration
 - `Run`: refresh, wait, inspect, export, and prune
 - `OpenAIProviderConfig`: built-in provider config
+- `AnthropicProviderConfig`: built-in Anthropic Message Batches config
 - `GeminiProviderConfig`: built-in Gemini provider config for text batch jobs; the common fields are also exposed by the CLI
 - `SQLiteStorage` and `PostgresStorage`: durable control-plane backends
 - `CompositeItemSource`, `CsvItemSource`, `JsonlItemSource`, and `ParquetItemSource`: deterministic item streaming
@@ -73,6 +74,15 @@ This is the built-in Gemini Batch implementation. Most consumers only need `Gemi
       show_root_heading: true
       heading_level: 2
 
+## Anthropic provider
+
+Install `batchor[anthropic]` for the SDK dependency. Most consumers only need `AnthropicProviderConfig`.
+
+::: batchor.providers.anthropic
+    options:
+      show_root_heading: true
+      heading_level: 2
+
 ## Sources
 
 These sources support durable resume through source fingerprints and checkpoints.