batchwork-ai 0.1.1__tar.gz → 0.2.0__tar.gz

{batchwork_ai-0.1.1 → batchwork_ai-0.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: batchwork-ai
-Version: 0.1.1
+Version: 0.2.0
 Summary: Unified async batch API for AI providers
 Keywords: ai,anthropic,batch,gemini,llm,openai
 Author: Ajanraj
@@ -16,6 +16,7 @@ Classifier: Programming Language :: Python :: 3.12
 Classifier: Programming Language :: Python :: 3.13
 Classifier: Programming Language :: Python :: 3.14
 Classifier: Typing :: Typed
+Requires-Dist: click>=8.4,<9
 Requires-Dist: httpcore>=1,<2
 Requires-Dist: httpx>=0.28,<1
 Requires-Dist: pydantic>=2.11,<3
@@ -24,18 +25,23 @@ Maintainer: Ajanraj
 Maintainer-email: Ajanraj <hey@ajanraj.com>
 Requires-Python: >=3.11
 Project-URL: Documentation, https://batchwork.ajanraj.com
+Project-URL: Issues, https://github.com/ajanraj/batchwork-ai/issues
+Project-URL: Repository, https://github.com/ajanraj/batchwork-ai
 Provides-Extra: redis
 Description-Content-Type: text/markdown
 
 # Batchwork
 
-Unified async batch API for OpenAI, Anthropic, Google Gemini, Groq, Mistral, Together AI, and xAI. Access provider-native batch pricing—often up to 50% lower than standard synchronous requests—through one typed interface while Batchwork handles provider-specific serialization, submission, polling, and result normalization. Pricing and eligibility remain provider- and model-specific. Built for Python by Ajanraj.
+![Batchwork — one typed API for provider-native AI batch jobs](docs/public/og-image.png)
+
+Unified async batch API for OpenAI, Anthropic, Google Gemini, Groq, Mistral, Together AI, and xAI. Providers price eligible batch requests up to 50% below standard synchronous calls, and Batchwork gives you that pricing through one typed Python interface and one CLI. It handles provider-specific serialization, submission, polling, and result parsing so you do not have to. Pricing and eligibility remain provider- and model-specific.
 
 - One typed API for provider-native batch jobs
 - Text, embedding, and image workloads
 - Normalized jobs, results, usage, and errors
 - Messages, tools, structured content, and remote media
 - Polling, persistent stores, and signed webhooks
+- A `batchwork` CLI and Agent Skill for terminals, scripts, and coding agents
 - No provider SDK or JavaScript runtime dependencies
 
 📖 **Full documentation: [batchwork.ajanraj.com](https://batchwork.ajanraj.com)**
@@ -64,6 +70,40 @@ export OPENAI_API_KEY="..."
 
 See [Configuration](https://batchwork.ajanraj.com/docs/configuration) for every provider credential, endpoint override, model format, and batch limit.
 
+### Command-line tool
+
+The same package ships a `batchwork` command, so you can submit and manage batches without writing Python. Install it with `uv tool`:
+
+```bash
+uv tool install batchwork-ai
+batchwork --version
+```
+
+Human quick start:
+
+```bash
+batchwork submit text prompts.txt --model openai/gpt-5
+batchwork list
+batchwork status BW_RECORD_ID
+batchwork results BW_RECORD_ID
+```
+
+Agent and automation quick start:
+
+```bash
+batchwork --jsonl --quiet run text requests.jsonl --model openai/gpt-5
+```
+
+Machine output uses schema version 1. Global controls such as `--jsonl`, `--profile`, and `--quiet` precede the command. Preserve the first emitted job identity, capture stdout/stderr/exit status separately, and never retry an acceptance-ambiguous submission automatically. Image files are written only when `--output-dir` is explicit.
+
+If you use a coding agent, the `batchwork-ai` Agent Skill teaches it the same contract, including when to ask before spending money and how to resume interrupted jobs:
+
+```bash
+npx skills add ajanraj/batchwork-ai@batchwork-ai
+```
+
+See the [CLI guide](https://batchwork.ajanraj.com/docs/cli), [configuration and registry reference](https://batchwork.ajanraj.com/docs/reference/cli-configuration-registry), [machine schema](https://batchwork.ajanraj.com/docs/reference/cli-machine-schema), and [exit catalog](https://batchwork.ajanraj.com/docs/guides/cli-exits).
+
 ## Quickstart
 
 ```python

{batchwork_ai-0.1.1 → batchwork_ai-0.2.0}/README.md

@@ -1,12 +1,15 @@
 # Batchwork
 
-Unified async batch API for OpenAI, Anthropic, Google Gemini, Groq, Mistral, Together AI, and xAI. Access provider-native batch pricing—often up to 50% lower than standard synchronous requests—through one typed interface while Batchwork handles provider-specific serialization, submission, polling, and result normalization. Pricing and eligibility remain provider- and model-specific. Built for Python by Ajanraj.
+![Batchwork — one typed API for provider-native AI batch jobs](docs/public/og-image.png)
+
+Unified async batch API for OpenAI, Anthropic, Google Gemini, Groq, Mistral, Together AI, and xAI. Providers price eligible batch requests up to 50% below standard synchronous calls, and Batchwork gives you that pricing through one typed Python interface and one CLI. It handles provider-specific serialization, submission, polling, and result parsing so you do not have to. Pricing and eligibility remain provider- and model-specific.
 
 - One typed API for provider-native batch jobs
 - Text, embedding, and image workloads
 - Normalized jobs, results, usage, and errors
 - Messages, tools, structured content, and remote media
 - Polling, persistent stores, and signed webhooks
+- A `batchwork` CLI and Agent Skill for terminals, scripts, and coding agents
 - No provider SDK or JavaScript runtime dependencies
 
 📖 **Full documentation: [batchwork.ajanraj.com](https://batchwork.ajanraj.com)**
@@ -35,6 +38,40 @@ export OPENAI_API_KEY="..."
 
 See [Configuration](https://batchwork.ajanraj.com/docs/configuration) for every provider credential, endpoint override, model format, and batch limit.
 
+### Command-line tool
+
+The same package ships a `batchwork` command, so you can submit and manage batches without writing Python. Install it with `uv tool`:
+
+```bash
+uv tool install batchwork-ai
+batchwork --version
+```
+
+Human quick start:
+
+```bash
+batchwork submit text prompts.txt --model openai/gpt-5
+batchwork list
+batchwork status BW_RECORD_ID
+batchwork results BW_RECORD_ID
+```
+
+Agent and automation quick start:
+
+```bash
+batchwork --jsonl --quiet run text requests.jsonl --model openai/gpt-5
+```
+
+Machine output uses schema version 1. Global controls such as `--jsonl`, `--profile`, and `--quiet` precede the command. Preserve the first emitted job identity, capture stdout/stderr/exit status separately, and never retry an acceptance-ambiguous submission automatically. Image files are written only when `--output-dir` is explicit.
+
+If you use a coding agent, the `batchwork-ai` Agent Skill teaches it the same contract, including when to ask before spending money and how to resume interrupted jobs:
+
+```bash
+npx skills add ajanraj/batchwork-ai@batchwork-ai
+```
+
+See the [CLI guide](https://batchwork.ajanraj.com/docs/cli), [configuration and registry reference](https://batchwork.ajanraj.com/docs/reference/cli-configuration-registry), [machine schema](https://batchwork.ajanraj.com/docs/reference/cli-machine-schema), and [exit catalog](https://batchwork.ajanraj.com/docs/guides/cli-exits).
+
 ## Quickstart
 
 ```python

{batchwork_ai-0.1.1 → batchwork_ai-0.2.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "uv_build"
 
 [project]
 name = "batchwork-ai"
-version = "0.1.1"
+version = "0.2.0"
 description = "Unified async batch API for AI providers"
 readme = "README.md"
 requires-python = ">=3.11"
@@ -25,19 +25,26 @@ classifiers = [
   "Typing :: Typed",
 ]
 dependencies = [
+  "click>=8.4,<9",
   "httpcore>=1,<2",
   "httpx>=0.28,<1",
   "pydantic>=2.11,<3",
 ]
 
+[project.scripts]
+batchwork = "batchwork.cli:main"
+
 [project.optional-dependencies]
 redis = ["upstash-redis>=1.4,<2"]
 
 [project.urls]
 Documentation = "https://batchwork.ajanraj.com"
+Issues = "https://github.com/ajanraj/batchwork-ai/issues"
+Repository = "https://github.com/ajanraj/batchwork-ai"
 
 [dependency-groups]
 dev = [
+  "jsonschema>=4.25,<5",
   "pytest>=8.4,<9",
   "pytest-asyncio>=1,<2",
   "pytest-cov>=6.2,<7",

{batchwork_ai-0.1.1 → batchwork_ai-0.2.0}/src/batchwork/__init__.py

@@ -1,5 +1,7 @@
 """Unified async batch API for AI providers."""
 
+from importlib.metadata import version
+
 from .client import Batchwork
 from .errors import (
     BatchClosedError,
@@ -50,7 +52,9 @@ from .types import (
     AssistantContentPart,
     AssistantMessage,
     BatchDefaults,
+    BatchEmbeddingDefaults,
     BatchEmbeddingRequest,
+    BatchEmbeddingRequestSettings,
     BatchImage,
     BatchImageDefaults,
     BatchImageRequest,
@@ -129,7 +133,7 @@ from .types import (
     utc_datetime,
 )
 
-__version__ = "0.1.1"
+__version__ = version("batchwork-ai")
 
 __all__ = [
     "TERMINAL_STATUSES",
@@ -138,7 +142,9 @@ __all__ = [
     "AtomicWebhookReplayStore",
     "BatchClosedError",
     "BatchDefaults",
+    "BatchEmbeddingDefaults",
     "BatchEmbeddingRequest",
+    "BatchEmbeddingRequestSettings",
     "BatchImage",
     "BatchImageDefaults",
     "BatchImageRequest",

batchwork_ai-0.2.0/src/batchwork/_bounded_json.py

@@ -0,0 +1,27 @@
+"""Incremental compact JSON encoding with a strict byte ceiling."""
+
+from __future__ import annotations
+
+import json
+from collections.abc import Mapping
+
+
+class JsonSizeExceeded(ValueError):
+    """Raised as soon as compact JSON crosses its byte ceiling."""
+
+    def __init__(self, maximum: int, known_size: int | None = None) -> None:
+        super().__init__()
+        self.maximum = maximum
+        self.known_size = known_size
+
+
+def encode_bounded_json(value: Mapping[str, object], maximum: int) -> bytes:
+    """Encode compact JSON, stopping at the first encoded chunk over ``maximum``."""
+    chunks = iter(json.JSONEncoder(ensure_ascii=False, separators=(",", ":")).iterencode(value))
+    encoded = bytearray()
+    for chunk in chunks:
+        part = chunk.encode()
+        if len(encoded) + len(part) > maximum:
+            raise JsonSizeExceeded(maximum, len(encoded) + len(part))
+        encoded.extend(part)
+    return bytes(encoded)

batchwork_ai-0.2.0/src/batchwork/_limits.py

@@ -0,0 +1,18 @@
+"""Fixed package and CLI v1 safety boundaries."""
+
+MAX_REQUESTS = 50_000
+MAX_REQUEST_BYTES = 20 * 1024 * 1024
+MAX_UPLOAD_BYTES = 200 * 1024 * 1024
+
+MAX_SOURCE_BYTES = 256 * 1024 * 1024
+MAX_RECORD_BYTES = 24 * 1024 * 1024
+MAX_PROVIDER_OPTIONS_BYTES = 1024 * 1024
+MAX_DECODED_MEDIA_BYTES = 20 * 1024 * 1024
+MAX_AGGREGATE_MEDIA_BYTES = 200 * 1024 * 1024
+MAX_PROVIDER_RESPONSE_BYTES = 320 * 1024 * 1024
+MAX_RESULT_RECORD_BYTES = 320 * 1024 * 1024
+MAX_AGGREGATE_RESULTS_BYTES = 1024 * 1024 * 1024
+
+LARGE_BATCH_REQUESTS = 10_000
+LARGE_BATCH_UPLOAD_BYTES = 50 * 1024 * 1024
+LARGE_BATCH_IMAGES = 100

batchwork_ai-0.2.0/src/batchwork/_provider_failure.py

@@ -0,0 +1,119 @@
+"""Safe, structured failures raised by provider HTTP helpers."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from datetime import UTC, datetime
+from email.utils import parsedate_to_datetime
+from enum import StrEnum
+from typing import Final
+
+import httpx
+
+from .errors import BatchworkError
+
+_REQUEST_ID_HEADERS: Final = (
+    "x-request-id",
+    "request-id",
+    "anthropic-request-id",
+    "x-goog-request-id",
+    "x-amzn-requestid",
+    "x-amz-request-id",
+)
+_MAX_REQUEST_ID_LENGTH: Final = 256
+_MAX_RETRY_AFTER_SECONDS: Final = 3600
+_RETRYABLE_CLIENT_STATUSES: Final = frozenset({408, 425, 429})
+
+
+class ProviderFailureKind(StrEnum):
+    """Failure categories safe for caller policy decisions."""
+
+    AUTHENTICATION = "authentication"
+    AUTHORIZATION = "authorization"
+    NOT_FOUND = "not_found"
+    REJECTED = "rejected"
+    UNAVAILABLE = "unavailable"
+    TRANSPORT = "transport"
+    PROTOCOL = "protocol"
+
+
+@dataclass(frozen=True, slots=True)
+class ProviderFailure:
+    """Provider failure metadata with no request, response body, or headers."""
+
+    kind: ProviderFailureKind
+    status_code: int | None = None
+    request_id: str | None = None
+    retry_after_seconds: int | None = None
+
+
+class ProviderFailureError(BatchworkError):
+    """A compatibility-preserving ``BatchworkError`` with safe failure metadata."""
+
+    def __init__(self, message: str, failure: ProviderFailure) -> None:
+        super().__init__(message)
+        self.failure = failure
+
+
+def http_failure(response: httpx.Response) -> ProviderFailure:
+    """Classify a non-success response without retaining it."""
+    status_code = response.status_code
+    if status_code == 401:
+        kind = ProviderFailureKind.AUTHENTICATION
+    elif status_code == 403:
+        kind = ProviderFailureKind.AUTHORIZATION
+    elif status_code == 404:
+        kind = ProviderFailureKind.NOT_FOUND
+    elif status_code in _RETRYABLE_CLIENT_STATUSES or status_code >= 500:
+        kind = ProviderFailureKind.UNAVAILABLE
+    else:
+        kind = ProviderFailureKind.REJECTED
+    return ProviderFailure(
+        kind=kind,
+        status_code=status_code,
+        request_id=_request_id(response),
+        retry_after_seconds=_retry_after_seconds(response),
+    )
+
+
+def transport_failure() -> ProviderFailure:
+    return ProviderFailure(kind=ProviderFailureKind.TRANSPORT)
+
+
+def protocol_failure(response: httpx.Response) -> ProviderFailure:
+    return ProviderFailure(
+        kind=ProviderFailureKind.PROTOCOL,
+        status_code=response.status_code,
+        request_id=_request_id(response),
+    )
+
+
+def _request_id(response: httpx.Response) -> str | None:
+    for name in _REQUEST_ID_HEADERS:
+        value = response.headers.get(name)
+        if value is not None and _safe_request_id(value):
+            return value
+    return None
+
+
+def _safe_request_id(value: str) -> bool:
+    return 0 < len(value) <= _MAX_REQUEST_ID_LENGTH and value.isascii() and value.isprintable()
+
+
+def _retry_after_seconds(response: httpx.Response) -> int | None:
+    value = response.headers.get("retry-after")
+    if value is None:
+        return None
+    try:
+        seconds = int(value)
+    except ValueError:
+        try:
+            retry_at = parsedate_to_datetime(value)
+        except (TypeError, ValueError):
+            return None
+        if retry_at.tzinfo is None:
+            retry_at = retry_at.replace(tzinfo=UTC)
+        seconds = max(0, int((retry_at - datetime.now(UTC)).total_seconds()))
+    if seconds < 0:
+        return None
+    return min(seconds, _MAX_RETRY_AFTER_SECONDS)