batchor 0.0.3__tar.gz → 0.0.4__tar.gz

{batchor-0.0.3 → 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.3 → batchor-0.0.4}/PKG-INFO

@@ -1,7 +1,7 @@
 Metadata-Version: 2.4
 Name: batchor
-Version: 0.0.3
-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
@@ -99,13 +99,16 @@ 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` 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 OpenAI Batch runner for Python teams that want:
+`batchor` is a durable provider Batch runner for Python teams that want:
 
 - typed Pydantic results
 - resumable durable runs
@@ -115,7 +118,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-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
 
@@ -140,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`
@@ -155,6 +159,8 @@ 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
@@ -193,6 +199,7 @@ graph LR
 
     subgraph providers["providers/"]
         OpenAI["OpenAIBatchProvider"]
+        Gemini["GeminiBatchProvider"]
     end
 
     subgraph sources["sources/"]
@@ -212,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
@@ -247,16 +255,31 @@ 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:
 
-This repo now includes local AI-agent scaffolding so a contributor agent can pick up repo conventions without extra global setup:
+```bash
+pip install "batchor[gemini]"
+```
+
+## Agent 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:
 
@@ -268,8 +291,9 @@ Supported Python versions:
 
 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`.
 
@@ -298,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
@@ -351,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
@@ -498,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

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

@@ -2,7 +2,7 @@
 
 `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 OpenAI Batch runner for Python teams that want:
+`batchor` is a durable provider Batch runner for Python teams that want:
 
 - typed Pydantic results
 - resumable durable runs
@@ -12,7 +12,7 @@
 - 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
 
@@ -37,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`
@@ -52,6 +53,8 @@ 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
@@ -90,6 +93,7 @@ graph LR
 
     subgraph providers["providers/"]
         OpenAI["OpenAIBatchProvider"]
+        Gemini["GeminiBatchProvider"]
     end
 
     subgraph sources["sources/"]
@@ -109,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
@@ -144,16 +149,31 @@ 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:
 
-This repo now includes local AI-agent scaffolding so a contributor agent can pick up repo conventions without extra global setup:
+```bash
+pip install "batchor[gemini]"
+```
+
+## Agent 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:
 
@@ -165,8 +185,9 @@ Supported Python versions:
 
 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`.
 
@@ -195,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
@@ -248,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
@@ -395,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

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

@@ -11,6 +11,8 @@ batchor/
   .agents/
   docs/
   plugins/
+    batchor/
+    batchor-agent-tools/
   src/batchor/
     artifacts/
     cli.py
@@ -22,13 +24,14 @@ batchor/
   tests/
 ```
 
-Repo-local contributor tooling also lives outside the shipped Python package:
+Agent tooling lives outside the shipped Python package so Python installation does not mutate or assume a particular coding-agent environment:
 
 - `.agents/skills/batchor-dev/` contains the repo skill for AI-agent onboarding
 - `.agents/plugins/marketplace.json` registers repo-local plugins for Codex-style discovery
-- `plugins/batchor-agent-tools/` contains the repo-local MCP server and plugin manifest
+- `plugins/batchor-agent-tools/` contains contributor-only repo guidance and validation tools
+- `plugins/batchor/` contains the downstream user skill and repo-independent workflow MCP for researchers and agents integrating Batchor into other projects
 
-These directories are contributor tooling only and are not part of the published `src/batchor` package.
+These directories are not part of the published `src/batchor` package. PyPI distributes the runtime and CLI; the agent marketplace distributes agent-specific skills and MCP configuration.
 
 The package is organized around one core concern: durable batch execution. Most modules exist to support one of five responsibilities:
 
@@ -58,6 +61,7 @@ graph TB
     subgraph providers["providers/"]
         BatchProvider["BatchProvider (ABC)"]
         OpenAIProvider["OpenAIBatchProvider"]
+        GeminiProvider["GeminiBatchProvider"]
         ProviderRegistry
     end
 
@@ -91,6 +95,7 @@ graph TB
     MemoryStateStore -.->|implements| StateStore
     BatchRunner -->|submits/polls| BatchProvider
     OpenAIProvider -.->|implements| BatchProvider
+    GeminiProvider -.->|implements| BatchProvider
     BatchRunner -->|stores artifacts| ArtifactStore
     LocalArtifactStore -.->|implements| ArtifactStore
     BatchRunner -->|creates via| ProviderRegistry
@@ -120,6 +125,10 @@ The public runtime model centers on four types:
 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.
+Provider hooks also own response-text extraction so structured-output parsing can stay generic across provider payload shapes.
+
 ## Main user-facing flow
 
 The normal public flow is:
@@ -137,7 +146,7 @@ Internally that expands to:
 4. Claim a bounded submission window from pending items.
 5. Build or replay request JSONL rows.
 6. Persist request artifacts before upload.
-7. Submit one or more OpenAI batch files.
+7. Submit one or more provider batch files.
 8. Poll active batches.
 9. Download output/error files.
 10. Parse terminal item results back into the state store.
@@ -201,7 +210,7 @@ sequenceDiagram
         BatchRunner->>Provider: upload_input_file(local_path)
         Provider-->>BatchRunner: remote_file_id
         BatchRunner->>Provider: create_batch(remote_file_id)
-        Provider-->>BatchRunner: BatchRemoteRecord (status=validating)
+        Provider-->>BatchRunner: BatchRemoteRecord (status=submitted/validating)
         BatchRunner->>StateStore: register_batch()
         BatchRunner->>StateStore: mark_items_submitted()
     end
@@ -423,7 +432,7 @@ That split gives `batchor`:
 ## Current invariants
 
 1. Public execution is run-oriented: `start()`, `get_run()`, `run_and_wait()`.
-2. OpenAI Batch is the only built-in provider.
+2. OpenAI Batch 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.
@@ -456,7 +465,7 @@ The code is shaped for future providers and backends, but within explicit bounda
 
 ## Current gaps
 
-- the only built-in provider is OpenAI Batch
+- Gemini request construction is text-only
 - the only built-in artifact backend is local filesystem storage
 - arbitrary non-checkpointable iterables do not support mid-ingest crash recovery
 - the CLI does not expose the full Python API surface

batchor-0.0.4/docs/design_docs/GEMINI_BATCHING.md

@@ -0,0 +1,96 @@
+# Gemini Batching
+
+This document describes the Gemini-specific behavior inside `batchor`.
+
+Status: implemented for text-only Python API and CLI jobs through both the Gemini Developer API and Vertex AI. Multimodal request construction remains out of scope.
+
+## API split
+
+The two Google backends do not expose the same batch transport:
+
+| Backend | Input | Output | Authentication |
+| --- | --- | --- | --- |
+| Gemini Developer API | inline requests below 20 MB; Files API JSONL for larger batches | inline responses or a Files API JSONL file | API key |
+| Vertex AI | Cloud Storage JSONL (BigQuery is supported by Google but not by batchor) | Cloud Storage JSONL | Application Default Credentials |
+
+`GeminiProviderConfig.input_mode="auto"` follows that table. `inline`, `file`, and `gcs` are explicit overrides, and incompatible backend/mode combinations fail locally.
+
+Vertex selection is explicit through `vertexai=True` or ambient through `GOOGLE_GENAI_USE_VERTEXAI=true`. Project and location resolve from config first, then `GOOGLE_CLOUD_PROJECT` and `GOOGLE_CLOUD_LOCATION`. Vertex also requires `gcs_uri="gs://bucket/prefix"` for request and output staging.
+
+## Request construction and correlation
+
+Developer file requests use the documented JSONL shape:
+
+```json
+{"key":"row1:a1","request":{"contents":[{"role":"user","parts":[{"text":"Summarize this text"}]}]}}
+```
+
+Inline mode converts those durable request artifacts to SDK `InlinedRequest` objects and carries the key in request metadata. Returned inline metadata is converted back to the same JSONL-style record before the generic runtime consumes it.
+
+Vertex output returns the original `request`, a `response`, and a string `status`; it does not return the Developer API `key`. For Vertex, batchor hashes the internal attempt identifier into a GCP-safe `request.labels.batchor_key` value. The original request and label round-trip through GCS output, so the runtime can correlate each row without relying on output ordering.
+
+`PromptParts.prompt` becomes a user text part. `PromptParts.system_prompt` becomes `system_instruction`. `GeminiProviderConfig.generation_config` is copied into every request.
+
+Structured jobs additionally set:
+
+```json
+{
+  "generation_config": {
+    "response_mime_type": "application/json",
+    "response_json_schema": {"type": "object"}
+  }
+}
+```
+
+The schema comes from the same `structured_output=` Pydantic model used by OpenAI jobs and returned JSON is validated with that model.
+
+## Lifecycle
+
+Developer API auto mode:
+
+1. use inline requests when the staged JSONL is under 20 MB, otherwise upload it through the Files API
+2. create and poll the batch with `client.batches`
+3. normalize inline responses or download the result file
+
+Vertex AI:
+
+1. upload the durable request JSONL under `gcs_uri/inputs/`
+2. create a batch with that `gs://` source and a unique `gcs_uri/outputs/` destination
+3. poll with `client.batches.get`
+4. read every output object from the returned `output_info.gcs_output_directory`
+
+Terminal states normalize to batchor's generic `completed`, `failed`, `cancelled`, and `expired` states. Vertex rows with a non-empty `status` become item errors; rows with an object `response` and empty status become successes.
+
+## Durable replay
+
+Provider-specific request rows remain in batchor's local artifact store. Retry or fresh-process resume replaces only the provider correlation identifier. Developer rows update `key`; Vertex rows update the hashed correlation label. The prompt and generation request otherwise remain unchanged.
+
+GCS input/output objects are remote provider payloads, separate from batchor's durable local artifact store. A failed create deletes its just-uploaded input on a best-effort basis. Successfully submitted Vertex payloads follow the bucket's retention/lifecycle policy.
+
+## Limits verified July 10, 2026
+
+Current official Vertex behavior:
+
+- no predefined Gemini batch inference quota or enqueue-token limit; work can queue against a shared resource pool
+- at most 200,000 requests per job
+- at most 1 GB for a Cloud Storage input file
+- jobs can queue for up to 72 hours and generally process within 24 hours after starting
+
+Batchor therefore does not apply OpenAI enqueue-token budgeting to Gemini. Generic `ChunkPolicy` defaults remain more conservative at 50,000 requests and 150 MiB, and callers may raise them within Google's limits.
+
+Developer API limits differ: inline batch creation must stay below 20 MB, input files may be up to 2 GB, concurrent batches are currently limited to 100, and model/tier-specific enqueued-token limits still apply. Batchor automatically switches Developer auto mode from inline to Files API by request size; it does not yet model Developer tier-specific token quotas.
+
+## Current limits
+
+- the CLI exposes the common text-job configuration; advanced source, storage, and lifecycle composition remains Python-first.
+- text request construction only.
+- Vertex BigQuery input/output is not implemented.
+- provider-side remote cancellation is not implemented.
+
+## References
+
+- [Vertex AI Gemini batch inference](https://cloud.google.com/vertex-ai/generative-ai/docs/multimodal/batch-prediction-gemini)
+- [Vertex AI batch inference from Cloud Storage](https://cloud.google.com/vertex-ai/generative-ai/docs/multimodal/batch-prediction-from-cloud-storage)
+- [Vertex AI quotas and limits](https://cloud.google.com/vertex-ai/docs/quotas)
+- [Gemini Developer API Batch API](https://ai.google.dev/gemini-api/docs/batch-api)
+- [Google Gen AI Python SDK batch documentation](https://googleapis.github.io/python-genai/#batch-prediction)

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

@@ -2,10 +2,12 @@
 
 This document describes the OpenAI-specific behavior inside `batchor`.
 
-`batchor` is not a generic batch abstraction with many first-party providers yet. The OpenAI path is the primary implemented path, so a lot of runtime behavior is defined around OpenAI Batch semantics.
+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.
 
 ## Current behavior
 
+The Python API and CLI both support OpenAI. The CLI is OpenAI-only today.
+
 ## Request construction
 
 The built-in provider converts each prepared item into one OpenAI Batch JSONL request row.
@@ -187,7 +189,6 @@ Provider-side remote batch cancellation is not implemented in v1.
 
 ## Current limits
 
-- only the built-in OpenAI Batch provider path is implemented
 - the docs do not yet provide a full capability matrix across all OpenAI endpoint features
 - artifact storage is still local-filesystem-only
 

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

@@ -8,11 +8,12 @@ This file tracks important work that should be explicit in the extracted reposit
 - 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 providers beyond OpenAI
+- additional provider coverage beyond OpenAI and text-only Gemini
 - artifact store abstraction
 - partial-result streaming APIs
 - richer CLI or operator workflow beyond the current file-backed text-job surface

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

@@ -74,7 +74,7 @@ Postgres is also implemented for shared control-plane state when callers explici
 
 In-memory storage exists for tests and short-lived local runs.
 
-The SQLite/OpenAI path is covered by the default smoke test. Postgres storage compatibility is validated in a dedicated storage-contract CI job and requires `BATCHOR_TEST_POSTGRES_DSN` for equivalent local coverage.
+The SQLite/OpenAI path is covered by the default smoke test. Gemini provider wiring is covered with fake-client integration tests, and an opt-in live Vertex/GCS smoke test covers the real control and payload planes. Postgres storage compatibility is validated in a dedicated storage-contract CI job and requires `BATCHOR_TEST_POSTGRES_DSN` for equivalent local coverage.
 
 ## Storage responsibilities
 
@@ -179,7 +179,7 @@ Successful rehydration depends on:
 Fresh-process resume also requeues any `queued_local` items back to `pending` before submission resumes.
 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.
+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.
 For composite sources, that includes the same ordered child identities; changing the child order or swapping one file changes the logical source identity.
@@ -194,6 +194,7 @@ Built-in deterministic sources currently include:
 For checkpointed ingestion, durable stores append materialized item chunks and advance the ingest checkpoint in one storage operation. Parquet and composite sources can also identify an end-of-source checkpoint from cheap metadata, so a resume after all rows were materialized but before the final completion flag was written can mark ingestion complete without re-reading the source data or re-rendering prompts.
 
 Once an item has a durable request artifact pointer, `batchor` prunes large inline request-building fields from the control-plane store and relies on the artifact for later retries.
+Provider-specific request rows are preserved in those artifacts. During replay, OpenAI updates `custom_id`; Gemini updates either the Developer API `key` or the Vertex correlation label. All map back to the same internal durable attempt identifier.
 
 ## Artifact lifecycle