batchor 0.0.1__tar.gz → 0.0.4__tar.gz

{batchor-0.0.1 → batchor-0.0.4}/.agents/plugins/marketplace.json

@@ -15,6 +15,18 @@
         "authentication": "ON_INSTALL"
       },
       "category": "Coding"
+    },
+    {
+      "name": "batchor",
+      "source": {
+        "source": "local",
+        "path": "./plugins/batchor"
+      },
+      "policy": {
+        "installation": "AVAILABLE",
+        "authentication": "ON_INSTALL"
+      },
+      "category": "Coding"
     }
   ]
 }

{batchor-0.0.1 → batchor-0.0.4}/.github/workflows/ci.yml

@@ -46,7 +46,7 @@ jobs:
     strategy:
       fail-fast: false
       matrix:
-        python-version: ["3.12", "3.13"]
+        python-version: ["3.12", "3.13", "3.14"]
 
     steps:
       - uses: actions/checkout@v4

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

@@ -1,7 +1,7 @@
 Metadata-Version: 2.4
 Name: batchor
-Version: 0.0.1
-Summary: Structured-first OpenAI Batch runner with typed Pydantic results.
+Version: 0.0.4
+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
 Project-URL: Issues, https://github.com/AnsonDev42/batchor/issues
@@ -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,openai,pydantic,sqlite
+Keywords: batch,cli,gemini,openai,pydantic,sqlite
 Classifier: Development Status :: 3 - Alpha
 Classifier: Environment :: Console
 Classifier: Intended Audience :: Developers
@@ -88,6 +88,7 @@ Classifier: Operating System :: OS Independent
 Classifier: Programming Language :: Python :: 3
 Classifier: Programming Language :: Python :: 3.12
 Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
 Classifier: Topic :: Software Development :: Libraries :: Python Modules
 Requires-Python: <4,>=3.12
 Requires-Dist: openai>=2.7.1
@@ -98,20 +99,26 @@ 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: gemini
+Requires-Dist: google-cloud-storage<4,>=3.4.0; extra == 'gemini'
+Requires-Dist: google-genai<2,>=1.55.0; extra == 'gemini'
 Description-Content-Type: text/markdown
 
 # batchor
 
-`batchor` is a durable OpenAI Batch runner for Python teams that want:
+`batchor` grew out of a recurring problem in academic research: running large datasets through LLMs in batch — reliably, reproducibly, and without reinventing the same glue code across every project. The patterns that kept emerging (durable state, typed results, safe resume after failure) were extracted into this library so they do not have to be rebuilt each time.
+
+`batchor` is a durable provider Batch runner for Python teams that want:
 
 - typed Pydantic results
 - resumable durable runs
 - replayable request artifacts
 - deterministic source checkpoints
+- provider-side enqueue limit controls to stay within token budgets
 - library-first run controls
 - a small operator CLI for CSV and JSONL jobs
 
-It is intentionally narrow today: OpenAI-first, SQLite-first, and library-first.
+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.
 
 ## What problem it solves
 
@@ -136,6 +143,7 @@ Most OpenAI Batch examples stop at "upload a JSONL file and poll until it finish
 Built-in implementations:
 
 - `OpenAIProviderConfig` + `OpenAIBatchProvider`
+- `GeminiProviderConfig` + `GeminiBatchProvider` for text-only Gemini Batch jobs
 - `SQLiteStorage`
 - `PostgresStorage` as an opt-in durable control-plane backend
 - `MemoryStateStore`
@@ -151,9 +159,12 @@ 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
+- 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
 - pause/resume/cancel and incremental terminal-result APIs are library-first today
+- OpenAI control-plane or batch-level 429 quota/billing exhaustion auto-pauses the run instead of burning attempts across the remaining backlog
 
 ## Mental model
 
@@ -173,6 +184,7 @@ Durability is split on purpose:
 - the artifact store keeps replayable request JSONL and downloaded raw batch payloads
 
 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.
 
 ## Architecture
 
@@ -187,6 +199,7 @@ graph LR
 
     subgraph providers["providers/"]
         OpenAI["OpenAIBatchProvider"]
+        Gemini["GeminiBatchProvider"]
     end
 
     subgraph sources["sources/"]
@@ -206,6 +219,7 @@ graph LR
     User -->|"start() / run_and_wait()"| BatchRunner
     BatchRunner --> Run
     BatchRunner --> OpenAI
+    BatchRunner --> Gemini
     BatchRunner --> SQLite
     BatchRunner --> LocalFS
     Files -->|"BatchItem stream"| BatchRunner
@@ -241,28 +255,45 @@ Operational semantics for resume, run control, and artifact retention live in
 pip install batchor
 ```
 
-## Repo Agent Setup
+For Gemini Batch support, install the optional extra:
+
+```bash
+pip install "batchor[gemini]"
+```
+
+## Agent setup
 
-This repo now includes local AI-agent scaffolding so a contributor agent can pick up repo conventions without extra global setup:
+Batchor keeps contributor tooling separate from the tools intended for researchers and downstream projects:
 
-- repo-local skill: `.agents/skills/batchor-dev/`
-- repo-local plugin marketplace: `.agents/plugins/marketplace.json`
-- repo-local MCP plugin: `plugins/batchor-agent-tools/`
-- VS Code workspace MCP config: `.vscode/mcp.json`
+- `plugins/batchor/` is the user-facing Codex plugin. Its `$use-batchor` skill and MCP helpers turn datasets and prompts into safe CLI or Python workflows without assuming a Batchor source checkout.
+- `.agents/skills/batchor-dev/` and `plugins/batchor-agent-tools/` are contributor-only. They teach agents how to change this repository, find design docs, and run its validation suite.
+- `.agents/plugins/marketplace.json` registers both plugins for local development.
+- `.vscode/mcp.json` configures the contributor MCP for this workspace.
 
-The skill captures repo-specific workflow and validation guidance. The MCP plugin exposes a small repo-aware guide for project overview, docs entry points, and validation commands.
+The PyPI package remains the runtime dependency: `pip install batchor` installs the library and CLI. Agent skills and MCP configuration are distributed as the separate `batchor` plugin so Python environments do not receive Codex-specific files implicitly.
+
+To try the user plugin from a local checkout:
+
+```bash
+codex plugin marketplace add /path/to/batchor
+codex plugin add batchor@batchor-local
+```
+
+Start a new Codex task after installation, then ask: `Use $use-batchor to turn my CSV and research prompt into a resumable batch job.`
 
 Supported Python versions:
 
 - `3.12`
 - `3.13`
+- `3.14`
 
 ## Authentication
 
 For Python API usage, auth resolution is:
 
-1. explicit `OpenAIProviderConfig(api_key=...)`
-2. ambient `OPENAI_API_KEY`
+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`
+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`.
 
@@ -291,6 +322,43 @@ run = runner.run_and_wait(
 print(run.results()[0].output_text)
 ```
 
+### Gemini text job
+
+```python
+from batchor import BatchItem, BatchJob, BatchRunner, GeminiProviderConfig, 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=GeminiProviderConfig(
+            model="gemini-2.5-flash",
+            api_key="YOUR_GEMINI_API_KEY",
+        ),
+    )
+)
+
+print(run.results()[0].output_text)
+```
+
+Gemini support currently builds text-only `GenerateContent` batch requests. It uses Gemini JSONL `key` values internally while keeping `batchor`'s durable item and attempt tracking unchanged.
+
+For Vertex AI, provide a Cloud Storage staging prefix and use Application Default Credentials:
+
+```python
+provider_config = GeminiProviderConfig(
+    model="gemini-2.5-flash",
+    vertexai=True,
+    project="my-project",
+    location="europe-west8",
+    gcs_uri="gs://my-bucket/batchor",
+)
+```
+
+Vertex AI stages JSONL input and output in that prefix. The Gemini Developer API uses inline requests for batches below 20 MB and the Files API for larger batches; `input_mode=` can override that automatic choice. Vertex request/output correlation uses a generated request label because Vertex output does not include the Developer API JSONL `key`.
+
 ### Structured output
 
 ```python
@@ -334,6 +402,8 @@ run.wait()
 print(run.results()[0].output)
 ```
 
+While waiting, `batchor` polls active batches before submitting more work. If a refresh consumes a completed batch, records terminal item state, or submits another provider batch, `Run.wait()` immediately continues draining instead of sleeping for the next poll interval.
+
 Structured-output models are validated up front against the OpenAI strict-schema subset used by `batchor`.
 
 - root schema must be an object
@@ -342,6 +412,8 @@ Structured-output models are validated up front against the OpenAI strict-schema
 
 If you need a field to be optional in Python, model it as nullable in the schema shape OpenAI accepts rather than relying on omitted required fields.
 
+The same `structured_output=` API is available with `GeminiProviderConfig`; batchor sends the schema through Gemini `generation_config.response_json_schema` and validates the returned JSON text with the same Pydantic model.
+
 ### Rehydrate a durable run
 
 ```python
@@ -479,6 +551,8 @@ run.cancel()
 
 Run control and incremental terminal-result APIs are Python-first in this release. The CLI does not yet expose `pause`, `resume`, `cancel`, or incremental terminal-result export commands.
 
+OpenAI insufficient-quota failures during upload/create/polling, or as a batch-level terminal error, are treated as an automatic pause with `summary().control_reason == "openai_insufficient_quota"`. Row-level insufficient-quota records inside a completed batch output stay item-scoped: those rows become retryable without consuming attempts, emit `openai_insufficient_quota` failure telemetry, and use retry backoff before resubmission. Auto-pause does not replace an in-progress cancellation.
+
 ## CLI quickstart
 
 The CLI is intentionally narrower than the Python API:
@@ -487,6 +561,31 @@ The CLI is intentionally narrower than the Python API:
 - CSV and JSONL only
 - SQLite-backed durable runs only
 
+OpenAI remains the default provider. For Gemini, install `batchor[gemini]` and select the backend explicitly or let `auto` follow `GOOGLE_GENAI_USE_VERTEXAI`:
+
+```bash
+batchor start \
+  --input input/items.jsonl \
+  --id-field id \
+  --prompt-field text \
+  --provider gemini \
+  --model gemini-2.5-flash \
+  --gemini-backend developer
+```
+
+Vertex AI additionally needs a writable staging prefix:
+
+```bash
+batchor start \
+  --input input/items.jsonl \
+  --id-field id \
+  --prompt-field text \
+  --provider gemini \
+  --model gemini-2.5-flash \
+  --gemini-backend vertex \
+  --gcs-uri gs://my-bucket/batchor
+```
+
 Start a run from JSONL:
 
 ```bash
@@ -539,12 +638,13 @@ def observer(event: RunEvent) -> None:
 runner = BatchRunner(observer=observer)
 ```
 
-Current events include run creation/resume, item ingestion, batch submission/polling/completion, item completion/failure, and artifact export/prune.
+Current events include run creation/resume, automatic quota pause, item ingestion, batch submission/polling/completion, item completion/failure, and artifact export/prune.
 
 ## Storage notes
 
 - SQLite remains the default durable backend.
-- `PostgresStorage` is available for shared control-plane state, but the CLI remains SQLite-only today.
+- `PostgresStorage` is available for shared control-plane state, but the CLI remains SQLite-only today. Plain `postgresql://` and `postgres://` DSNs are normalized to the package's psycopg v3 driver URL.
+- Item `attempt_count` means consumed provider attempts: successful submitted completions increment it, counted item-level failures increment it, and local or batch-level retry/reset paths that did not consume an item attempt leave it unchanged.
 - Durable artifacts now go through an `ArtifactStore` seam. The built-in implementation is `LocalArtifactStore`, intended for local disk or a shared mounted volume.
 - Fresh-process resume requeues any locally claimed but not yet submitted items before continuing, so a process crash after request-artifact persistence does not strand work in `queued_local`.
 
@@ -591,51 +691,6 @@ The default pytest configuration enforces an `85%` coverage floor.
 
 GitHub Actions pull requests run:
 
-- `test (3.12)` and `test (3.13)`: `uv run ty check src` plus `uv run pytest -q`
-- `docs`: `uv run mkdocs build --strict`
-- `build (3.13)`: `uv build`
-- `postgres-contract`: `uv run pytest tests/unit/test_batchor_storage_contracts.py --no-cov -q` with an ephemeral PostgreSQL service
-
-The live OpenAI smoke remains manual-only and is not part of required CI.
-
-Manual live OpenAI smoke:
-
-```bash
-export OPENAI_API_KEY=sk-...
-export BATCHOR_RUN_LIVE_TESTS=1
-uv run pytest tests/integration/test_batchor_live_openai.py --no-cov -q
-```
-
-If `BATCHOR_LIVE_OPENAI_MODEL` is unset, the harness defaults to `gpt-5-nano`.
-If `BATCHOR_LIVE_OPENAI_REASONING_EFFORT` is unset, no reasoning field is sent.
-The live smoke also requires an OpenAI account with Batch API access and available billing quota.
-
-## Documentation guide
-
-- `docs/design_docs/ARCHITECTURE.md`: canonical runtime diagrams and module boundaries
-- `docs/design_docs/STORAGE_AND_RUNS.md`: durable run, resume, and artifact lifecycle semantics
-- `docs/getting-started/use-cases.md`: practical single-file, multi-file, and pipeline examples
-- `docs/getting-started/python-api.md`: Python-first workflows
-- `docs/getting-started/cli.md`: operator CLI workflows
-- `docs/reference/api.md`: generated API surface
-- `docs/design_docs/ARCHITECTURE.md`: package boundaries
-- `docs/design_docs/OPENAI_BATCHING.md`: OpenAI-specific behavior
-- `docs/design_docs/STORAGE_AND_RUNS.md`: durability, rehydration, and artifacts
-- `docs/smoke-test.md`: minimum validation bar
-
-## Scope
-
-Today `batchor` is intentionally narrow:
-
-- one built-in provider: OpenAI Batch
-- one default durable backend: SQLite
-- one opt-in durable backend: Postgres
-- one ephemeral backend: in-memory storage
-- structured output is Python API-first
-- CLI job creation is file-backed and supports both text and structured-output jobs
-
-Anything outside that scope should be treated as out of scope or `TBD`, not implied support.
-
 ## License
 
 This project is licensed under PolyForm Noncommercial 1.0.0. See [LICENSE](LICENSE).

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

@@ -1,15 +1,18 @@
 # batchor
 
-`batchor` is a durable OpenAI Batch runner for Python teams that want:
+`batchor` grew out of a recurring problem in academic research: running large datasets through LLMs in batch — reliably, reproducibly, and without reinventing the same glue code across every project. The patterns that kept emerging (durable state, typed results, safe resume after failure) were extracted into this library so they do not have to be rebuilt each time.
+
+`batchor` is a durable provider Batch runner for Python teams that want:
 
 - typed Pydantic results
 - resumable durable runs
 - replayable request artifacts
 - deterministic source checkpoints
+- provider-side enqueue limit controls to stay within token budgets
 - library-first run controls
 - a small operator CLI for CSV and JSONL jobs
 
-It is intentionally narrow today: OpenAI-first, SQLite-first, and library-first.
+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.
 
 ## What problem it solves
 
@@ -34,6 +37,7 @@ Most OpenAI Batch examples stop at "upload a JSONL file and poll until it finish
 Built-in implementations:
 
 - `OpenAIProviderConfig` + `OpenAIBatchProvider`
+- `GeminiProviderConfig` + `GeminiBatchProvider` for text-only Gemini Batch jobs
 - `SQLiteStorage`
 - `PostgresStorage` as an opt-in durable control-plane backend
 - `MemoryStateStore`
@@ -49,9 +53,12 @@ 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
+- 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
 - pause/resume/cancel and incremental terminal-result APIs are library-first today
+- OpenAI control-plane or batch-level 429 quota/billing exhaustion auto-pauses the run instead of burning attempts across the remaining backlog
 
 ## Mental model
 
@@ -71,6 +78,7 @@ Durability is split on purpose:
 - the artifact store keeps replayable request JSONL and downloaded raw batch payloads
 
 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.
 
 ## Architecture
 
@@ -85,6 +93,7 @@ graph LR
 
     subgraph providers["providers/"]
         OpenAI["OpenAIBatchProvider"]
+        Gemini["GeminiBatchProvider"]
     end
 
     subgraph sources["sources/"]
@@ -104,6 +113,7 @@ graph LR
     User -->|"start() / run_and_wait()"| BatchRunner
     BatchRunner --> Run
     BatchRunner --> OpenAI
+    BatchRunner --> Gemini
     BatchRunner --> SQLite
     BatchRunner --> LocalFS
     Files -->|"BatchItem stream"| BatchRunner
@@ -139,28 +149,45 @@ Operational semantics for resume, run control, and artifact retention live in
 pip install batchor
 ```
 
-## Repo Agent Setup
+For Gemini Batch support, install the optional extra:
+
+```bash
+pip install "batchor[gemini]"
+```
+
+## Agent setup
 
-This repo now includes local AI-agent scaffolding so a contributor agent can pick up repo conventions without extra global setup:
+Batchor keeps contributor tooling separate from the tools intended for researchers and downstream projects:
 
-- repo-local skill: `.agents/skills/batchor-dev/`
-- repo-local plugin marketplace: `.agents/plugins/marketplace.json`
-- repo-local MCP plugin: `plugins/batchor-agent-tools/`
-- VS Code workspace MCP config: `.vscode/mcp.json`
+- `plugins/batchor/` is the user-facing Codex plugin. Its `$use-batchor` skill and MCP helpers turn datasets and prompts into safe CLI or Python workflows without assuming a Batchor source checkout.
+- `.agents/skills/batchor-dev/` and `plugins/batchor-agent-tools/` are contributor-only. They teach agents how to change this repository, find design docs, and run its validation suite.
+- `.agents/plugins/marketplace.json` registers both plugins for local development.
+- `.vscode/mcp.json` configures the contributor MCP for this workspace.
 
-The skill captures repo-specific workflow and validation guidance. The MCP plugin exposes a small repo-aware guide for project overview, docs entry points, and validation commands.
+The PyPI package remains the runtime dependency: `pip install batchor` installs the library and CLI. Agent skills and MCP configuration are distributed as the separate `batchor` plugin so Python environments do not receive Codex-specific files implicitly.
+
+To try the user plugin from a local checkout:
+
+```bash
+codex plugin marketplace add /path/to/batchor
+codex plugin add batchor@batchor-local
+```
+
+Start a new Codex task after installation, then ask: `Use $use-batchor to turn my CSV and research prompt into a resumable batch job.`
 
 Supported Python versions:
 
 - `3.12`
 - `3.13`
+- `3.14`
 
 ## Authentication
 
 For Python API usage, auth resolution is:
 
-1. explicit `OpenAIProviderConfig(api_key=...)`
-2. ambient `OPENAI_API_KEY`
+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`
+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`.
 
@@ -189,6 +216,43 @@ run = runner.run_and_wait(
 print(run.results()[0].output_text)
 ```
 
+### Gemini text job
+
+```python
+from batchor import BatchItem, BatchJob, BatchRunner, GeminiProviderConfig, 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=GeminiProviderConfig(
+            model="gemini-2.5-flash",
+            api_key="YOUR_GEMINI_API_KEY",
+        ),
+    )
+)
+
+print(run.results()[0].output_text)
+```
+
+Gemini support currently builds text-only `GenerateContent` batch requests. It uses Gemini JSONL `key` values internally while keeping `batchor`'s durable item and attempt tracking unchanged.
+
+For Vertex AI, provide a Cloud Storage staging prefix and use Application Default Credentials:
+
+```python
+provider_config = GeminiProviderConfig(
+    model="gemini-2.5-flash",
+    vertexai=True,
+    project="my-project",
+    location="europe-west8",
+    gcs_uri="gs://my-bucket/batchor",
+)
+```
+
+Vertex AI stages JSONL input and output in that prefix. The Gemini Developer API uses inline requests for batches below 20 MB and the Files API for larger batches; `input_mode=` can override that automatic choice. Vertex request/output correlation uses a generated request label because Vertex output does not include the Developer API JSONL `key`.
+
 ### Structured output
 
 ```python
@@ -232,6 +296,8 @@ run.wait()
 print(run.results()[0].output)
 ```
 
+While waiting, `batchor` polls active batches before submitting more work. If a refresh consumes a completed batch, records terminal item state, or submits another provider batch, `Run.wait()` immediately continues draining instead of sleeping for the next poll interval.
+
 Structured-output models are validated up front against the OpenAI strict-schema subset used by `batchor`.
 
 - root schema must be an object
@@ -240,6 +306,8 @@ Structured-output models are validated up front against the OpenAI strict-schema
 
 If you need a field to be optional in Python, model it as nullable in the schema shape OpenAI accepts rather than relying on omitted required fields.
 
+The same `structured_output=` API is available with `GeminiProviderConfig`; batchor sends the schema through Gemini `generation_config.response_json_schema` and validates the returned JSON text with the same Pydantic model.
+
 ### Rehydrate a durable run
 
 ```python
@@ -377,6 +445,8 @@ run.cancel()
 
 Run control and incremental terminal-result APIs are Python-first in this release. The CLI does not yet expose `pause`, `resume`, `cancel`, or incremental terminal-result export commands.
 
+OpenAI insufficient-quota failures during upload/create/polling, or as a batch-level terminal error, are treated as an automatic pause with `summary().control_reason == "openai_insufficient_quota"`. Row-level insufficient-quota records inside a completed batch output stay item-scoped: those rows become retryable without consuming attempts, emit `openai_insufficient_quota` failure telemetry, and use retry backoff before resubmission. Auto-pause does not replace an in-progress cancellation.
+
 ## CLI quickstart
 
 The CLI is intentionally narrower than the Python API:
@@ -385,6 +455,31 @@ The CLI is intentionally narrower than the Python API:
 - CSV and JSONL only
 - SQLite-backed durable runs only
 
+OpenAI remains the default provider. For Gemini, install `batchor[gemini]` and select the backend explicitly or let `auto` follow `GOOGLE_GENAI_USE_VERTEXAI`:
+
+```bash
+batchor start \
+  --input input/items.jsonl \
+  --id-field id \
+  --prompt-field text \
+  --provider gemini \
+  --model gemini-2.5-flash \
+  --gemini-backend developer
+```
+
+Vertex AI additionally needs a writable staging prefix:
+
+```bash
+batchor start \
+  --input input/items.jsonl \
+  --id-field id \
+  --prompt-field text \
+  --provider gemini \
+  --model gemini-2.5-flash \
+  --gemini-backend vertex \
+  --gcs-uri gs://my-bucket/batchor
+```
+
 Start a run from JSONL:
 
 ```bash
@@ -437,12 +532,13 @@ def observer(event: RunEvent) -> None:
 runner = BatchRunner(observer=observer)
 ```
 
-Current events include run creation/resume, item ingestion, batch submission/polling/completion, item completion/failure, and artifact export/prune.
+Current events include run creation/resume, automatic quota pause, item ingestion, batch submission/polling/completion, item completion/failure, and artifact export/prune.
 
 ## Storage notes
 
 - SQLite remains the default durable backend.
-- `PostgresStorage` is available for shared control-plane state, but the CLI remains SQLite-only today.
+- `PostgresStorage` is available for shared control-plane state, but the CLI remains SQLite-only today. Plain `postgresql://` and `postgres://` DSNs are normalized to the package's psycopg v3 driver URL.
+- Item `attempt_count` means consumed provider attempts: successful submitted completions increment it, counted item-level failures increment it, and local or batch-level retry/reset paths that did not consume an item attempt leave it unchanged.
 - Durable artifacts now go through an `ArtifactStore` seam. The built-in implementation is `LocalArtifactStore`, intended for local disk or a shared mounted volume.
 - Fresh-process resume requeues any locally claimed but not yet submitted items before continuing, so a process crash after request-artifact persistence does not strand work in `queued_local`.
 
@@ -489,51 +585,6 @@ The default pytest configuration enforces an `85%` coverage floor.
 
 GitHub Actions pull requests run:
 
-- `test (3.12)` and `test (3.13)`: `uv run ty check src` plus `uv run pytest -q`
-- `docs`: `uv run mkdocs build --strict`
-- `build (3.13)`: `uv build`
-- `postgres-contract`: `uv run pytest tests/unit/test_batchor_storage_contracts.py --no-cov -q` with an ephemeral PostgreSQL service
-
-The live OpenAI smoke remains manual-only and is not part of required CI.
-
-Manual live OpenAI smoke:
-
-```bash
-export OPENAI_API_KEY=sk-...
-export BATCHOR_RUN_LIVE_TESTS=1
-uv run pytest tests/integration/test_batchor_live_openai.py --no-cov -q
-```
-
-If `BATCHOR_LIVE_OPENAI_MODEL` is unset, the harness defaults to `gpt-5-nano`.
-If `BATCHOR_LIVE_OPENAI_REASONING_EFFORT` is unset, no reasoning field is sent.
-The live smoke also requires an OpenAI account with Batch API access and available billing quota.
-
-## Documentation guide
-
-- `docs/design_docs/ARCHITECTURE.md`: canonical runtime diagrams and module boundaries
-- `docs/design_docs/STORAGE_AND_RUNS.md`: durable run, resume, and artifact lifecycle semantics
-- `docs/getting-started/use-cases.md`: practical single-file, multi-file, and pipeline examples
-- `docs/getting-started/python-api.md`: Python-first workflows
-- `docs/getting-started/cli.md`: operator CLI workflows
-- `docs/reference/api.md`: generated API surface
-- `docs/design_docs/ARCHITECTURE.md`: package boundaries
-- `docs/design_docs/OPENAI_BATCHING.md`: OpenAI-specific behavior
-- `docs/design_docs/STORAGE_AND_RUNS.md`: durability, rehydration, and artifacts
-- `docs/smoke-test.md`: minimum validation bar
-
-## Scope
-
-Today `batchor` is intentionally narrow:
-
-- one built-in provider: OpenAI Batch
-- one default durable backend: SQLite
-- one opt-in durable backend: Postgres
-- one ephemeral backend: in-memory storage
-- structured output is Python API-first
-- CLI job creation is file-backed and supports both text and structured-output jobs
-
-Anything outside that scope should be treated as out of scope or `TBD`, not implied support.
-
 ## License
 
 This project is licensed under PolyForm Noncommercial 1.0.0. See [LICENSE](LICENSE).