tokenrail 1.0.0__tar.gz

tokenrail-1.0.0/.github/workflows/ci.yml

@@ -0,0 +1,37 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.10", "3.11", "3.12", "3.13", "3.14"]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+      - name: Run tests
+        run: uv run --python ${{ matrix.python-version }} pytest -q
+
+  lint:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v5
+      - name: Ruff check
+        run: uv run ruff check src tests
+
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v5
+      - name: Build sdist and wheel
+        run: uv build

tokenrail-1.0.0/.github/workflows/release.yml

@@ -0,0 +1,43 @@
+name: Release
+
+on:
+  push:
+    tags: ["v*"]
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v5
+      - name: Check tag matches package version
+        run: |
+          PKG_VERSION=$(grep -m1 '^version' pyproject.toml | cut -d'"' -f2)
+          TAG_VERSION="${GITHUB_REF_NAME#v}"
+          if [ "$PKG_VERSION" != "$TAG_VERSION" ]; then
+            echo "Tag $GITHUB_REF_NAME does not match pyproject.toml version $PKG_VERSION" >&2
+            exit 1
+          fi
+      - name: Run tests
+        run: uv run pytest -q
+      - name: Build sdist and wheel
+        run: uv build
+      - uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+  publish:
+    needs: build
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+      url: https://pypi.org/p/tokenrail
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+      - uses: pypa/gh-action-pypi-publish@release/v1

tokenrail-1.0.0/.gitignore

@@ -0,0 +1,14 @@
+# Python-generated files
+__pycache__/
+*.py[oc]
+build/
+dist/
+wheels/
+*.egg-info
+
+# Virtual environments
+.venv
+
+# Other
+.env
+sample_out*

tokenrail-1.0.0/.python-version

@@ -0,0 +1 @@
+3.12

tokenrail-1.0.0/CHANGELOG.md

@@ -0,0 +1,61 @@
+# Changelog
+
+All notable changes to this project are documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [1.0.0] - 2026-06-11
+
+First stable release. The public API surface is now covered by semantic
+versioning: `RailClient`, `BatchExecutor`, `batch_items_from_queries`,
+`RollingMetricsMonitor`, `ResultsJsonlSink`, `PerRequestJsonSink`,
+`OpenAIProvider`, and the types exported from `tokenrail`.
+
+### Added
+
+- `py.typed` marker — the package now ships inline type information (PEP 561).
+- `tokenrail.__version__`.
+- Docstrings across the public API.
+- Complete packaging metadata (license, classifiers, project URLs).
+- CI test workflow across Python 3.10–3.14.
+- First release published to [PyPI](https://pypi.org/project/tokenrail/);
+  releases are published automatically from `v*` tags via PyPI Trusted
+  Publishing.
+
+### Changed
+
+- Minimum supported Python lowered from 3.11 to 3.10.
+- `catalog.get_model_pricing` no longer carries a dead `service_tier` branch;
+  non-default tiers explicitly fall back to default-tier pricing.
+
+## [0.2.1] - 2026-06-10
+
+### Added
+
+- Client-side RPM and TPM submit throttling in `BatchExecutor`
+  (`max_rpm` / `max_tpm`).
+
+### Removed
+
+- vLLM provider support; the library is OpenAI-only.
+
+## [0.1.3] - 2026-05-20
+
+### Changed
+
+- Removed the custom OpenAI retry loop in favor of the SDK's built-in
+  `max_retries`.
+
+## [0.1.2] - 2026-05-15
+
+### Added
+
+- ETA progress reporting in `RollingMetricsMonitor`.
+
+## [0.1.0] - 2026-05-13
+
+### Added
+
+- Initial release: `RailClient`, `BatchExecutor`, rolling metrics monitor,
+  JSONL and per-request sinks, model capability/pricing catalog.

tokenrail-1.0.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Takumi Shibata
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

tokenrail-1.0.0/PKG-INFO

@@ -0,0 +1,143 @@
+Metadata-Version: 2.4
+Name: tokenrail
+Version: 1.0.0
+Summary: Thin client and batch execution helpers for OpenAI Responses API workloads.
+Project-URL: Homepage, https://github.com/takumi0shibata/tokenrail
+Project-URL: Repository, https://github.com/takumi0shibata/tokenrail
+Project-URL: Issues, https://github.com/takumi0shibata/tokenrail/issues
+Project-URL: Changelog, https://github.com/takumi0shibata/tokenrail/blob/main/CHANGELOG.md
+Author: Takumi Shibata
+License-Expression: MIT
+License-File: LICENSE
+Keywords: batch,cost-tracking,llm,openai,rate-limit,responses-api,token
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Requires-Dist: openai>=1.108.0
+Description-Content-Type: text/markdown
+
+# tokenrail
+
+[![CI](https://github.com/takumi0shibata/tokenrail/actions/workflows/ci.yml/badge.svg)](https://github.com/takumi0shibata/tokenrail/actions/workflows/ci.yml)
+[![PyPI](https://img.shields.io/pypi/v/tokenrail)](https://pypi.org/project/tokenrail/)
+[![Python 3.10+](https://img.shields.io/badge/python-3.10%2B-blue)](https://pypi.org/project/tokenrail/)
+[![License: MIT](https://img.shields.io/badge/license-MIT-green)](LICENSE)
+
+`tokenrail` is a small Python library for running OpenAI Responses API jobs with a `client.responses.create(...)`-style surface.
+
+It focuses on:
+
+- thread-based OpenAI batch execution
+- client-side RPM / TPM submit throttling
+- per-model token / cost monitoring with ETA progress reporting
+- resumable JSONL and per-request result writing
+
+Fully typed (PEP 561), supports Python 3.10+.
+
+## Installation
+
+```bash
+uv add tokenrail
+# or
+pip install tokenrail
+```
+
+To track an unreleased revision instead, depend on the Git repository directly:
+
+```toml
+[tool.uv.sources]
+tokenrail = { git = "https://github.com/takumi0shibata/tokenrail", tag = "v1.0.0" }
+```
+
+Set your OpenAI API key in the consuming project before use:
+
+```bash
+export OPENAI_API_KEY=...
+```
+
+## Quick start
+
+```python
+from tokenrail import BatchExecutor, ResultsJsonlSink, PerRequestJsonSink, RailClient, RollingMetricsMonitor
+from tokenrail.executor import batch_items_from_queries
+
+client = RailClient.openai(max_retries=6)
+
+queries = {
+    "1": [{"role": "user", "content": "Summarize this paper in 3 bullets."}],
+    "2": [{"role": "user", "content": "Extract the key assumptions."}],
+}
+
+items = batch_items_from_queries(
+    queries,
+    model="gpt-5.4-mini-2026-03-17",
+    reasoning_effort="medium",
+    verbosity="low",
+)
+
+# Consolidate only the necessary elements from all processing results into a single file.
+result_sink = ResultsJsonlSink(
+    "out/results.jsonl",
+    projector=lambda response: {
+        "id": response.id,
+        "text": response.output_text,
+        "model": response.model,
+        "usage": response.usage.to_dict(),
+    },
+)
+# Save the raw output of each query.
+per_request_sink = PerRequestJsonSink("out/")
+
+executor = BatchExecutor(
+    client=client,
+    max_workers=16,
+    max_rpm=500,
+    max_tpm=200_000,
+    sinks=[result_sink, per_request_sink],
+    monitor=RollingMetricsMonitor(),
+)
+
+stats = executor.run(items)
+print(stats.to_dict())
+```
+
+## Configuration notes
+
+- `max_retries` configures the OpenAI Python SDK client's built-in retry behavior. `tokenrail` does not add its own retry loop on top.
+- `max_rpm` and `max_tpm` are optional client-side submit limits. When a limit is set, `BatchExecutor` waits before submitting more work instead of raising its effective concurrency above the configured rate.
+- Request failures are captured as error records (written to sinks and counted in stats) rather than raised, so one failing item does not abort the batch.
+- `base_url` is passed through to the OpenAI Python SDK for callers that need an SDK-level custom endpoint.
+
+## Resume behavior
+
+`BatchExecutor` reads completed ids from the first configured sink before it starts. Re-running the same job with the same output path skips records that are already present, then writes only the remaining requests.
+
+If you use a custom `projector` with `ResultsJsonlSink`, make sure it keeps an `"id"` field — resume relies on it.
+
+## Cost tracking
+
+- Costs are estimated from a checked-in per-model pricing table (`tokenrail.catalog`). Models without a pricing entry get `cost=None`; prices may lag behind OpenAI's official pricing page, which is always authoritative.
+- OpenAI cost allocation is inferred from `billing.payer` in the response body. When `payer == "openai"`, the nominal request cost is counted as OpenAI-covered rather than developer-billed.
+- `reasoning_effort` is gated to `gpt-5` / `o`-series style models in the checked-in capability registry.
+
+## Development
+
+```bash
+uv sync
+uv run pytest
+uv run ruff check src tests
+```
+
+## License
+
+[MIT](LICENSE)

tokenrail-1.0.0/README.md

@@ -0,0 +1,115 @@
+# tokenrail
+
+[![CI](https://github.com/takumi0shibata/tokenrail/actions/workflows/ci.yml/badge.svg)](https://github.com/takumi0shibata/tokenrail/actions/workflows/ci.yml)
+[![PyPI](https://img.shields.io/pypi/v/tokenrail)](https://pypi.org/project/tokenrail/)
+[![Python 3.10+](https://img.shields.io/badge/python-3.10%2B-blue)](https://pypi.org/project/tokenrail/)
+[![License: MIT](https://img.shields.io/badge/license-MIT-green)](LICENSE)
+
+`tokenrail` is a small Python library for running OpenAI Responses API jobs with a `client.responses.create(...)`-style surface.
+
+It focuses on:
+
+- thread-based OpenAI batch execution
+- client-side RPM / TPM submit throttling
+- per-model token / cost monitoring with ETA progress reporting
+- resumable JSONL and per-request result writing
+
+Fully typed (PEP 561), supports Python 3.10+.
+
+## Installation
+
+```bash
+uv add tokenrail
+# or
+pip install tokenrail
+```
+
+To track an unreleased revision instead, depend on the Git repository directly:
+
+```toml
+[tool.uv.sources]
+tokenrail = { git = "https://github.com/takumi0shibata/tokenrail", tag = "v1.0.0" }
+```
+
+Set your OpenAI API key in the consuming project before use:
+
+```bash
+export OPENAI_API_KEY=...
+```
+
+## Quick start
+
+```python
+from tokenrail import BatchExecutor, ResultsJsonlSink, PerRequestJsonSink, RailClient, RollingMetricsMonitor
+from tokenrail.executor import batch_items_from_queries
+
+client = RailClient.openai(max_retries=6)
+
+queries = {
+    "1": [{"role": "user", "content": "Summarize this paper in 3 bullets."}],
+    "2": [{"role": "user", "content": "Extract the key assumptions."}],
+}
+
+items = batch_items_from_queries(
+    queries,
+    model="gpt-5.4-mini-2026-03-17",
+    reasoning_effort="medium",
+    verbosity="low",
+)
+
+# Consolidate only the necessary elements from all processing results into a single file.
+result_sink = ResultsJsonlSink(
+    "out/results.jsonl",
+    projector=lambda response: {
+        "id": response.id,
+        "text": response.output_text,
+        "model": response.model,
+        "usage": response.usage.to_dict(),
+    },
+)
+# Save the raw output of each query.
+per_request_sink = PerRequestJsonSink("out/")
+
+executor = BatchExecutor(
+    client=client,
+    max_workers=16,
+    max_rpm=500,
+    max_tpm=200_000,
+    sinks=[result_sink, per_request_sink],
+    monitor=RollingMetricsMonitor(),
+)
+
+stats = executor.run(items)
+print(stats.to_dict())
+```
+
+## Configuration notes
+
+- `max_retries` configures the OpenAI Python SDK client's built-in retry behavior. `tokenrail` does not add its own retry loop on top.
+- `max_rpm` and `max_tpm` are optional client-side submit limits. When a limit is set, `BatchExecutor` waits before submitting more work instead of raising its effective concurrency above the configured rate.
+- Request failures are captured as error records (written to sinks and counted in stats) rather than raised, so one failing item does not abort the batch.
+- `base_url` is passed through to the OpenAI Python SDK for callers that need an SDK-level custom endpoint.
+
+## Resume behavior
+
+`BatchExecutor` reads completed ids from the first configured sink before it starts. Re-running the same job with the same output path skips records that are already present, then writes only the remaining requests.
+
+If you use a custom `projector` with `ResultsJsonlSink`, make sure it keeps an `"id"` field — resume relies on it.
+
+## Cost tracking
+
+- Costs are estimated from a checked-in per-model pricing table (`tokenrail.catalog`). Models without a pricing entry get `cost=None`; prices may lag behind OpenAI's official pricing page, which is always authoritative.
+- OpenAI cost allocation is inferred from `billing.payer` in the response body. When `payer == "openai"`, the nominal request cost is counted as OpenAI-covered rather than developer-billed.
+- `reasoning_effort` is gated to `gpt-5` / `o`-series style models in the checked-in capability registry.
+
+## Development
+
+```bash
+uv sync
+uv run pytest
+uv run ruff check src tests
+```
+
+## License
+
+[MIT](LICENSE)

tokenrail-1.0.0/pyproject.toml

@@ -0,0 +1,67 @@
+[project]
+name = "tokenrail"
+version = "1.0.0"
+description = "Thin client and batch execution helpers for OpenAI Responses API workloads."
+readme = "README.md"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [
+    { name = "Takumi Shibata" },
+]
+requires-python = ">=3.10"
+keywords = [
+    "openai",
+    "responses-api",
+    "batch",
+    "llm",
+    "rate-limit",
+    "token",
+    "cost-tracking",
+]
+classifiers = [
+    "Development Status :: 5 - Production/Stable",
+    "Intended Audience :: Developers",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Programming Language :: Python :: 3.14",
+    "Topic :: Scientific/Engineering :: Artificial Intelligence",
+    "Topic :: Software Development :: Libraries :: Python Modules",
+    "Typing :: Typed",
+]
+dependencies = [
+    "openai>=1.108.0",
+]
+
+[project.urls]
+Homepage = "https://github.com/takumi0shibata/tokenrail"
+Repository = "https://github.com/takumi0shibata/tokenrail"
+Issues = "https://github.com/takumi0shibata/tokenrail/issues"
+Changelog = "https://github.com/takumi0shibata/tokenrail/blob/main/CHANGELOG.md"
+
+[build-system]
+requires = ["hatchling>=1.27.0"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/tokenrail"]
+
+[dependency-groups]
+dev = [
+    "pytest>=8.0.0",
+    "python-dotenv>=1.2.2",
+    "ruff>=0.8.0",
+]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+
+[tool.ruff]
+line-length = 120
+target-version = "py310"
+
+[tool.ruff.lint]
+select = ["E", "F", "W", "I", "UP", "B"]

tokenrail-1.0.0/src/tokenrail/__init__.py

@@ -0,0 +1,31 @@
+"""Thin client and batch execution helpers for OpenAI Responses API workloads.
+
+tokenrail wraps the OpenAI Responses API with a ``client.responses.create(...)``-style
+surface and adds thread-based batch execution, client-side RPM/TPM submit throttling,
+per-model token/cost monitoring, and resumable JSONL / per-request result writing.
+"""
+
+from .client import RailClient
+from .executor import BatchExecutor, batch_items_from_queries
+from .monitor import RollingMetricsMonitor
+from .providers import OpenAIProvider
+from .sinks import PerRequestJsonSink, ResultsJsonlSink
+from .types import BatchItem, CostBreakdown, NormalizedResponse, StatsSnapshot, UsageBreakdown
+
+__version__ = "1.0.0"
+
+__all__ = [
+    "__version__",
+    "BatchExecutor",
+    "BatchItem",
+    "CostBreakdown",
+    "NormalizedResponse",
+    "OpenAIProvider",
+    "PerRequestJsonSink",
+    "RailClient",
+    "ResultsJsonlSink",
+    "RollingMetricsMonitor",
+    "StatsSnapshot",
+    "UsageBreakdown",
+    "batch_items_from_queries",
+]