hedge-python 0.1.0__tar.gz → 0.2.0__tar.gz

{hedge_python-0.1.0 → hedge_python-0.2.0}/.github/workflows/ci.yml

@@ -10,6 +10,9 @@ concurrency:
   group: ${{ github.workflow }}-${{ github.ref }}
   cancel-in-progress: true
 
+env:
+  FORCE_JAVASCRIPT_ACTIONS_TO_NODE24: true
+
 jobs:
   lint:
     name: Lint & Type Check
@@ -64,7 +67,7 @@ jobs:
         with:
           python-version: "3.13"
       - run: uv sync --all-extras
-      - run: uv run pytest tests/ --cov=src/hedge --cov-report=xml --cov-report=term-missing
+      - run: uv run pytest tests/ --cov=src/hedge --cov-report=xml --cov-report=term-missing --ignore=tests/benchmark
       - uses: codecov/codecov-action@v4
         with:
           file: coverage.xml

{hedge_python-0.1.0 → hedge_python-0.2.0}/CHANGELOG.md

@@ -5,6 +5,38 @@ All notable changes to this project will be 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).
 
+## [0.2.0] - 2026-06-12
+
+### Added
+
+- **niquests adapter**: `HedgedNiquestsSession` — drop-in wrapper for
+  `niquests.AsyncSession` with adaptive hedging on `GET`/`HEAD`/`OPTIONS`.
+- **tornado adapter**: `HedgedTornadoClient` — wraps
+  `tornado.httpclient.AsyncHTTPClient` with adaptive hedging via `fetch()`.
+- **OpenAI integration example** (`examples/openai_hedged.py`): demonstrates
+  injecting `HedgedHttpxTransport` into `openai.AsyncOpenAI` via `http_client`.
+- New examples: `examples/niquests_basic.py`, `examples/tornado_basic.py`.
+- Lazy-import registry refactored to a data-driven `_LAZY_IMPORTS` dict
+  in `hedge.transport.__init__` for easier extensibility.
+- `pyproject.toml` optional extras: `[niquests]`, `[tornado]` (also added
+  to `[all]` and `[dev]`).
+- Comprehensive unit tests for niquests and tornado adapters.
+- Import-error tests for `niquests`, `tornado`, and `grpc` modules.
+- Additional coverage tests: `TokenBucket.set_rps` truncation, `WindowedSketch`
+  double-start idempotency, `DDSketch` quantile edge cases, gRPC interceptor
+  `current_task()` None branch and `_PrependedStream` EOF.
+
+### Changed
+
+- `Makefile`: `test`, `test-unit`, `test-integration`, and `coverage` targets
+  now depend on `install` to ensure all extras are available before running.
+- `examples/README.md` updated with new framework entries.
+
+### Other
+
+- Test coverage: **97%** (150 tests).
+- Supports Python 3.9 → 3.14.
+
 ## [0.1.0] - 2026-04-23
 
 ### Added
@@ -61,5 +93,6 @@ _Initial release — nothing removed._
   `[grpc]`, `[all]`, `[dev]`.
 - Supports Python 3.9 → 3.14.
 
-[Unreleased]: https://github.com/sunhailin-Leo/hedge-python/compare/v0.1.0...HEAD
+[Unreleased]: https://github.com/sunhailin-Leo/hedge-python/compare/v0.2.0...HEAD
+[0.2.0]: https://github.com/sunhailin-Leo/hedge-python/compare/v0.1.0...v0.2.0
 [0.1.0]: https://github.com/sunhailin-Leo/hedge-python/releases/tag/v0.1.0

{hedge_python-0.1.0 → hedge_python-0.2.0}/Makefile

@@ -17,16 +17,16 @@ format:
 typecheck:
 	uv run mypy src/hedge/
 
-# Run all tests
-test:
-	uv run pytest tests/ -v --tb=short
+# Run all tests (unit + integration, excludes benchmarks)
+test: install
+	uv run pytest tests/ -v --tb=short --ignore=tests/benchmark
 
 # Unit tests only
-test-unit:
+test-unit: install
 	uv run pytest tests/unit/ -v --tb=short
 
 # Integration tests only
-test-integration:
+test-integration: install
 	uv run pytest tests/integration/ -v --tb=short -m integration
 
 # Benchmark tests
@@ -45,9 +45,9 @@ bench-multi:
 bench-plot:
 	uv run python benchmark/plot.py
 
-# Coverage report
-coverage:
-	uv run pytest tests/ --cov=src/hedge --cov-report=term-missing --cov-report=html
+# Coverage report (excludes benchmarks for speed)
+coverage: install
+	uv run pytest tests/ --cov=src/hedge --cov-report=term-missing --cov-report=html --ignore=tests/benchmark
 
 # Run full CI checks locally
 ci: lint typecheck test coverage

{hedge_python-0.1.0 → hedge_python-0.2.0}/PKG-INFO

@@ -1,11 +1,11 @@
 Metadata-Version: 2.4
 Name: hedge-python
-Version: 0.1.0
+Version: 0.2.0
 Summary: Adaptive hedged request library for Python. Learns per-host latency via DDSketch, fires backup requests at estimated p90, caps hedge rate with token bucket.
 Author-email: LeoSun <sunhailin.shl@antgroup.com>
 License: MIT
 License-File: LICENSE
-Keywords: aiohttp,ddsketch,grpc,hedge,httpx,latency,tail-latency
+Keywords: aiohttp,ddsketch,grpc,hedge,httpx,latency,niquests,tail-latency,tornado
 Classifier: Development Status :: 3 - Alpha
 Classifier: Framework :: AsyncIO
 Classifier: Intended Audience :: Developers
@@ -26,7 +26,9 @@ Provides-Extra: all
 Requires-Dist: aiohttp>=3.9.0; extra == 'all'
 Requires-Dist: grpcio>=1.50.0; extra == 'all'
 Requires-Dist: httpx>=0.24.0; extra == 'all'
+Requires-Dist: niquests>=3.0.0; extra == 'all'
 Requires-Dist: protobuf>=4.21.0; extra == 'all'
+Requires-Dist: tornado>=6.0.0; extra == 'all'
 Provides-Extra: dev
 Requires-Dist: aiohttp>=3.9.0; extra == 'dev'
 Requires-Dist: grpcio-tools>=1.50.0; extra == 'dev'
@@ -34,6 +36,7 @@ Requires-Dist: grpcio>=1.50.0; extra == 'dev'
 Requires-Dist: httpx>=0.24.0; extra == 'dev'
 Requires-Dist: matplotlib>=3.7.0; extra == 'dev'
 Requires-Dist: mypy>=1.0; extra == 'dev'
+Requires-Dist: niquests>=3.0.0; extra == 'dev'
 Requires-Dist: protobuf>=4.21.0; extra == 'dev'
 Requires-Dist: pytest-asyncio>=0.21.0; extra == 'dev'
 Requires-Dist: pytest-benchmark>=4.0; extra == 'dev'
@@ -41,11 +44,16 @@ Requires-Dist: pytest-cov>=4.0; extra == 'dev'
 Requires-Dist: pytest-timeout>=2.1.0; extra == 'dev'
 Requires-Dist: pytest>=7.0; extra == 'dev'
 Requires-Dist: ruff>=0.4.0; extra == 'dev'
+Requires-Dist: tornado>=6.0.0; extra == 'dev'
 Provides-Extra: grpc
 Requires-Dist: grpcio>=1.50.0; extra == 'grpc'
 Requires-Dist: protobuf>=4.21.0; extra == 'grpc'
 Provides-Extra: httpx
 Requires-Dist: httpx>=0.24.0; extra == 'httpx'
+Provides-Extra: niquests
+Requires-Dist: niquests>=3.0.0; extra == 'niquests'
+Provides-Extra: tornado
+Requires-Dist: tornado>=6.0.0; extra == 'tornado'
 Description-Content-Type: text/markdown
 
 # hedge-python
@@ -54,7 +62,7 @@ Description-Content-Type: text/markdown
 
 [![CI](https://github.com/sunhailin-Leo/hedge-python/actions/workflows/ci.yml/badge.svg)](https://github.com/sunhailin-Leo/hedge-python/actions)
 [![Coverage](https://img.shields.io/badge/coverage-97%25-brightgreen.svg)](#testing)
-[![Python](https://img.shields.io/badge/python-3.9%E2%80%933.13-blue.svg)](pyproject.toml)
+[![Python](https://img.shields.io/badge/python-3.9%E2%80%933.14-blue.svg)](pyproject.toml)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
 
 Python port of [bhope/hedge](https://github.com/bhope/hedge) — **adaptive hedged
@@ -64,8 +72,8 @@ requests for tail-latency optimisation**.
 [DDSketch](https://arxiv.org/abs/2004.08604), races a backup request when the
 primary exceeds its estimated p90, and caps the hedge rate with a token bucket
 to prevent load amplification during outages. Zero configuration required.
-First-class support for **httpx**, **aiohttp**, and **gRPC** (unary +
-server-streaming).
+First-class support for **httpx**, **aiohttp**, **niquests**, **tornado**, and **gRPC** (unary +
+server-streaming). Works out of the box with **OpenAI's Python SDK**.
 
 Inspired by Dean & Barroso, [_The Tail at Scale_](https://research.google/pubs/the-tail-at-scale/) (CACM 2013).
 
@@ -101,6 +109,8 @@ Across all three frameworks, p99 latency drops by **60–66%** at the cost of
 # Install with your preferred framework
 pip install hedge-python[httpx]
 pip install hedge-python[aiohttp]
+pip install hedge-python[niquests]
+pip install hedge-python[tornado]
 pip install hedge-python[grpc]
 pip install hedge-python[all]   # all frameworks
 ```
@@ -166,6 +176,59 @@ async def make_channel():
     )
 ```
 
+### niquests
+
+```python
+import asyncio
+from hedge import HedgeConfig
+from hedge.transport import HedgedNiquestsSession
+
+async def main():
+    async with HedgedNiquestsSession(config=HedgeConfig()) as session:
+        resp = await session.get("https://api.example.com/data")
+        print(resp.status_code)
+
+asyncio.run(main())
+```
+
+### tornado
+
+```python
+import asyncio
+from hedge import HedgeConfig
+from hedge.transport import HedgedTornadoClient
+
+async def main():
+    async with HedgedTornadoClient(config=HedgeConfig()) as client:
+        resp = await client.fetch("https://api.example.com/data")
+        print(resp.code)
+
+asyncio.run(main())
+```
+
+### OpenAI SDK
+
+Since the OpenAI Python SDK uses httpx under the hood, you can inject
+`HedgedHttpxTransport` directly via the `http_client` parameter:
+
+```python
+import httpx
+from openai import AsyncOpenAI
+from hedge import HedgeConfig
+from hedge.transport import HedgedHttpxTransport
+
+transport = HedgedHttpxTransport(config=HedgeConfig(percentile=0.95))
+client = AsyncOpenAI(
+    api_key="sk-...",
+    http_client=httpx.AsyncClient(transport=transport),
+)
+```
+
+> **Note**: OpenAI's core APIs (Chat Completions, Embeddings, etc.) use POST,
+> so they are **not** hedged by default — avoiding double billing. Only GET
+> endpoints (e.g. model listing) are hedged. See
+> [`examples/openai_hedged.py`](examples/openai_hedged.py) for a full example.
+
 For server streaming, the hedge signal is **time-to-first-message (TTFM)**: if
 the primary stream doesn't yield its first chunk within the estimated p90,
 a backup stream is started. Whichever yields first wins and continues
@@ -305,7 +368,7 @@ make ci                 # lint + typecheck + test + coverage
 * **Benchmarks** (`tests/benchmark/`): DDSketch microbench, token bucket
   microbench, four-config comparison, three-framework comparison.
 
-Current coverage: **97%** (122 tests, ~7 seconds).
+Current coverage: **97%** (150 tests, ~7 seconds).
 
 ---
 
@@ -325,7 +388,9 @@ hedge-python/
 │   ├── transport/
 │   │   ├── _base.py         # Shared HedgeScheduler logic
 │   │   ├── _httpx.py        # httpx AsyncBaseTransport adapter
-│   │   └── _aiohttp.py      # aiohttp session wrapper
+│   │   ├── _aiohttp.py      # aiohttp session wrapper
+│   │   ├── _niquests.py     # niquests session wrapper
+│   │   └── _tornado.py      # tornado AsyncHTTPClient wrapper
 │   └── interceptor/
 │       └── _grpc.py         # gRPC unary + server-stream interceptors
 ├── tests/

{hedge_python-0.1.0 → hedge_python-0.2.0}/README.ja.md

@@ -4,7 +4,7 @@
 
 [![CI](https://github.com/sunhailin-Leo/hedge-python/actions/workflows/ci.yml/badge.svg)](https://github.com/sunhailin-Leo/hedge-python/actions)
 [![Coverage](https://img.shields.io/badge/coverage-97%25-brightgreen.svg)](#テスト)
-[![Python](https://img.shields.io/badge/python-3.9%E2%80%933.13-blue.svg)](pyproject.toml)
+[![Python](https://img.shields.io/badge/python-3.9%E2%80%933.14-blue.svg)](pyproject.toml)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
 
 > 📘 公式ドキュメントは **[英語版](README.md)** が主です。本書は概要をすばやく把握するための日本語訳です。
@@ -15,7 +15,8 @@
 `hedge-python` は [DDSketch](https://arxiv.org/abs/2004.08604) を用いてホストごとのレイテンシ分布を学習し、
 プライマリリクエストが推定 p90 を超えた時点でバックアップリクエストを発射、
 さらにトークンバケットでヘッジレートを制限することで、障害時の負荷増幅を防ぎます。
-**設定不要** で、**httpx**、**aiohttp**、**gRPC**（unary + server-streaming）を第一級でサポートします。
+**設定不要** で、**httpx**、**aiohttp**、**niquests**、**tornado**、**gRPC**（unary + server-streaming）を第一級でサポートします。
+`http_client` パラメータ経由で **OpenAI Python SDK** とのシームレスな統合もサポートしています。
 
 Dean & Barroso の [_The Tail at Scale_](https://research.google/pubs/the-tail-at-scale/)（CACM 2013）に着想を得ています。
 
@@ -52,6 +53,8 @@ Dean & Barroso の [_The Tail at Scale_](https://research.google/pubs/the-tail-a
 # 必要なフレームワーク向けにインストール
 pip install hedge-python[httpx]
 pip install hedge-python[aiohttp]
+pip install hedge-python[niquests]
+pip install hedge-python[tornado]
 pip install hedge-python[grpc]
 pip install hedge-python[all]   # 全フレームワーク
 ```
@@ -117,6 +120,59 @@ async def make_channel():
     )
 ```
 
+### niquests
+
+```python
+import asyncio
+from hedge import HedgeConfig
+from hedge.transport import HedgedNiquestsSession
+
+async def main():
+    async with HedgedNiquestsSession(config=HedgeConfig()) as session:
+        resp = await session.get("https://api.example.com/data")
+        print(resp.status_code)
+
+asyncio.run(main())
+```
+
+### tornado
+
+```python
+import asyncio
+from hedge import HedgeConfig
+from hedge.transport import HedgedTornadoClient
+
+async def main():
+    async with HedgedTornadoClient(config=HedgeConfig()) as client:
+        resp = await client.fetch("https://api.example.com/data")
+        print(resp.code)
+
+asyncio.run(main())
+```
+
+### OpenAI SDK
+
+OpenAI Python SDK は内部で httpx を使用しているため、`http_client` パラメータ経由で
+`HedgedHttpxTransport` を直接注入できます：
+
+```python
+import httpx
+from openai import AsyncOpenAI
+from hedge import HedgeConfig
+from hedge.transport import HedgedHttpxTransport
+
+transport = HedgedHttpxTransport(config=HedgeConfig(percentile=0.95))
+client = AsyncOpenAI(
+    api_key="sk-...",
+    http_client=httpx.AsyncClient(transport=transport),
+)
+```
+
+> **注意**: OpenAI のコア API（Chat Completions、Embeddings など）は POST を使用するため、
+> デフォルトではヘッジ **されません** —— 二重課金を回避するためです。GET エンドポイント
+>（モデル一覧など）のみがヘッジされます。完全な例は
+> [`examples/openai_hedged.py`](examples/openai_hedged.py) を参照してください。
+
 server-streaming におけるヘッジ信号は **TTFM（Time To First Message）** です。
 プライマリストリームが推定 p90 までに最初の chunk を返さなければ、バックアップストリームを起動します。
 先に最初の chunk を返した側が勝ち、以降のストリーミングを引き継ぎます。
@@ -240,7 +296,7 @@ make ci                 # lint + typecheck + test + coverage
 * **結合テスト** (`tests/integration/`): 実 httpx transport、実 aiohttp session、**実ローカル gRPC サーバ**（`.proto` + 生成 pb2 込み）。
 * **ベンチマーク** (`tests/benchmark/`): DDSketch マイクロベンチ、トークンバケットマイクロベンチ、4 構成比較、3 フレームワーク比較。
 
-現在のカバレッジ: **97%**（122 テスト、約 7 秒）。
+現在のカバレッジ: **97%**（150 テスト、約 7 秒）。
 
 ---
 

{hedge_python-0.1.0 → hedge_python-0.2.0}/README.md

@@ -4,7 +4,7 @@
 
 [![CI](https://github.com/sunhailin-Leo/hedge-python/actions/workflows/ci.yml/badge.svg)](https://github.com/sunhailin-Leo/hedge-python/actions)
 [![Coverage](https://img.shields.io/badge/coverage-97%25-brightgreen.svg)](#testing)
-[![Python](https://img.shields.io/badge/python-3.9%E2%80%933.13-blue.svg)](pyproject.toml)
+[![Python](https://img.shields.io/badge/python-3.9%E2%80%933.14-blue.svg)](pyproject.toml)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
 
 Python port of [bhope/hedge](https://github.com/bhope/hedge) — **adaptive hedged
@@ -14,8 +14,8 @@ requests for tail-latency optimisation**.
 [DDSketch](https://arxiv.org/abs/2004.08604), races a backup request when the
 primary exceeds its estimated p90, and caps the hedge rate with a token bucket
 to prevent load amplification during outages. Zero configuration required.
-First-class support for **httpx**, **aiohttp**, and **gRPC** (unary +
-server-streaming).
+First-class support for **httpx**, **aiohttp**, **niquests**, **tornado**, and **gRPC** (unary +
+server-streaming). Works out of the box with **OpenAI's Python SDK**.
 
 Inspired by Dean & Barroso, [_The Tail at Scale_](https://research.google/pubs/the-tail-at-scale/) (CACM 2013).
 
@@ -51,6 +51,8 @@ Across all three frameworks, p99 latency drops by **60–66%** at the cost of
 # Install with your preferred framework
 pip install hedge-python[httpx]
 pip install hedge-python[aiohttp]
+pip install hedge-python[niquests]
+pip install hedge-python[tornado]
 pip install hedge-python[grpc]
 pip install hedge-python[all]   # all frameworks
 ```
@@ -116,6 +118,59 @@ async def make_channel():
     )
 ```
 
+### niquests
+
+```python
+import asyncio
+from hedge import HedgeConfig
+from hedge.transport import HedgedNiquestsSession
+
+async def main():
+    async with HedgedNiquestsSession(config=HedgeConfig()) as session:
+        resp = await session.get("https://api.example.com/data")
+        print(resp.status_code)
+
+asyncio.run(main())
+```
+
+### tornado
+
+```python
+import asyncio
+from hedge import HedgeConfig
+from hedge.transport import HedgedTornadoClient
+
+async def main():
+    async with HedgedTornadoClient(config=HedgeConfig()) as client:
+        resp = await client.fetch("https://api.example.com/data")
+        print(resp.code)
+
+asyncio.run(main())
+```
+
+### OpenAI SDK
+
+Since the OpenAI Python SDK uses httpx under the hood, you can inject
+`HedgedHttpxTransport` directly via the `http_client` parameter:
+
+```python
+import httpx
+from openai import AsyncOpenAI
+from hedge import HedgeConfig
+from hedge.transport import HedgedHttpxTransport
+
+transport = HedgedHttpxTransport(config=HedgeConfig(percentile=0.95))
+client = AsyncOpenAI(
+    api_key="sk-...",
+    http_client=httpx.AsyncClient(transport=transport),
+)
+```
+
+> **Note**: OpenAI's core APIs (Chat Completions, Embeddings, etc.) use POST,
+> so they are **not** hedged by default — avoiding double billing. Only GET
+> endpoints (e.g. model listing) are hedged. See
+> [`examples/openai_hedged.py`](examples/openai_hedged.py) for a full example.
+
 For server streaming, the hedge signal is **time-to-first-message (TTFM)**: if
 the primary stream doesn't yield its first chunk within the estimated p90,
 a backup stream is started. Whichever yields first wins and continues
@@ -255,7 +310,7 @@ make ci                 # lint + typecheck + test + coverage
 * **Benchmarks** (`tests/benchmark/`): DDSketch microbench, token bucket
   microbench, four-config comparison, three-framework comparison.
 
-Current coverage: **97%** (122 tests, ~7 seconds).
+Current coverage: **97%** (150 tests, ~7 seconds).
 
 ---
 
@@ -275,7 +330,9 @@ hedge-python/
 │   ├── transport/
 │   │   ├── _base.py         # Shared HedgeScheduler logic
 │   │   ├── _httpx.py        # httpx AsyncBaseTransport adapter
-│   │   └── _aiohttp.py      # aiohttp session wrapper
+│   │   ├── _aiohttp.py      # aiohttp session wrapper
+│   │   ├── _niquests.py     # niquests session wrapper
+│   │   └── _tornado.py      # tornado AsyncHTTPClient wrapper
 │   └── interceptor/
 │       └── _grpc.py         # gRPC unary + server-stream interceptors
 ├── tests/

{hedge_python-0.1.0 → hedge_python-0.2.0}/README.zh-CN.md

@@ -4,14 +4,14 @@
 
 [![CI](https://github.com/sunhailin-Leo/hedge-python/actions/workflows/ci.yml/badge.svg)](https://github.com/sunhailin-Leo/hedge-python/actions)
 [![Coverage](https://img.shields.io/badge/coverage-97%25-brightgreen.svg)](#测试)
-[![Python](https://img.shields.io/badge/python-3.9%E2%80%933.13-blue.svg)](pyproject.toml)
+[![Python](https://img.shields.io/badge/python-3.9%E2%80%933.14-blue.svg)](pyproject.toml)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
 
 > 📘 完整文档以 **[英文版](README.md)** 为主，本文为中文摘要，便于快速了解。
 
 [bhope/hedge](https://github.com/bhope/hedge) 的 Python 移植版本 —— **面向尾延迟优化的自适应对冲请求库**。
 
-`hedge-python` 使用 [DDSketch](https://arxiv.org/abs/2004.08604) 学习每个目标主机的延迟分布，当主请求超过估算的 p90 时立即发起备份请求，并通过令牌桶限制对冲速率，避免在故障期间放大流量。**零配置开箱即用**，原生支持 **httpx**、**aiohttp** 和 **gRPC**（unary + server-streaming）。
+`hedge-python` 使用 [DDSketch](https://arxiv.org/abs/2004.08604) 学习每个目标主机的延迟分布，当主请求超过估算的 p90 时立即发起备份请求，并通过令牌桶限制对冲速率，避免在故障期间放大流量。**零配置开箱即用**，原生支持 **httpx**、**aiohttp**、**niquests**、**tornado** 和 **gRPC**（unary + server-streaming）。同时支持通过 `http_client` 参数无缝集成 **OpenAI Python SDK**。
 
 灵感来自 Dean & Barroso 的 [_The Tail at Scale_](https://research.google/pubs/the-tail-at-scale/)（CACM 2013）。
 
@@ -44,6 +44,8 @@
 # 按需安装框架支持
 pip install hedge-python[httpx]
 pip install hedge-python[aiohttp]
+pip install hedge-python[niquests]
+pip install hedge-python[tornado]
 pip install hedge-python[grpc]
 pip install hedge-python[all]   # 全部框架
 ```
@@ -109,6 +111,55 @@ async def make_channel():
     )
 ```
 
+### niquests
+
+```python
+import asyncio
+from hedge import HedgeConfig
+from hedge.transport import HedgedNiquestsSession
+
+async def main():
+    async with HedgedNiquestsSession(config=HedgeConfig()) as session:
+        resp = await session.get("https://api.example.com/data")
+        print(resp.status_code)
+
+asyncio.run(main())
+```
+
+### tornado
+
+```python
+import asyncio
+from hedge import HedgeConfig
+from hedge.transport import HedgedTornadoClient
+
+async def main():
+    async with HedgedTornadoClient(config=HedgeConfig()) as client:
+        resp = await client.fetch("https://api.example.com/data")
+        print(resp.code)
+
+asyncio.run(main())
+```
+
+### OpenAI SDK
+
+OpenAI Python SDK 底层使用 httpx，可通过 `http_client` 参数直接注入 `HedgedHttpxTransport`：
+
+```python
+import httpx
+from openai import AsyncOpenAI
+from hedge import HedgeConfig
+from hedge.transport import HedgedHttpxTransport
+
+transport = HedgedHttpxTransport(config=HedgeConfig(percentile=0.95))
+client = AsyncOpenAI(
+    api_key="sk-...",
+    http_client=httpx.AsyncClient(transport=transport),
+)
+```
+
+> **注意**：OpenAI 核心 API（Chat Completions、Embeddings 等）使用 POST，默认**不会**被对冲——避免双倍计费。仅 GET 端点（如模型列表）会被对冲。完整示例见 [`examples/openai_hedged.py`](examples/openai_hedged.py)。
+
 对于 server-streaming，对冲信号是 **首消息到达时间（TTFM）**：若主流在估算的 p90 内仍未返回首个 chunk，则发起备份流。先返回首 chunk 的流胜出并继续接管，败者在传输层被取消。
 
 > 每个框架的可运行示例位于 [`examples/`](examples/) 目录 —— gRPC 示例**完全自包含**（启动本地 server + 注入 straggler，无需任何外部依赖即可看到对冲触发）。详见 [`examples/README.md`](examples/README.md)。
@@ -220,7 +271,7 @@ make ci                 # lint + typecheck + test + coverage
 * **集成测试** (`tests/integration/`)：真实 httpx transport、真实 aiohttp session、**真实本地 gRPC server**（含 `.proto` 与生成的 pb2）。
 * **基准测试** (`tests/benchmark/`)：DDSketch 微基准、令牌桶微基准、四配置对比、三框架对比。
 
-当前覆盖率：**97%**（122 个测试，约 7 秒）。
+当前覆盖率：**97%**（150 个测试，约 7 秒）。
 
 ---