Metadata-Version: 2.5
Name: openai-fast-transform
Version: 0.1.0
Summary: An exact, compiled replacement for the openai SDK's request transform.
Project-URL: Repository, https://github.com/rasmusfaber/openai-fast-transform
Project-URL: Issues, https://github.com/rasmusfaber/openai-fast-transform/issues
Author: Rasmus Faber-Espensen
License-Expression: MIT
License-File: LICENSE
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Typing :: Typed
Requires-Python: >=3.12
Requires-Dist: openai>=1.108.1
Requires-Dist: typing-extensions>=4.11
Description-Content-Type: text/markdown

# openai-fast-transform

An exact, compiled replacement for the [openai](https://github.com/openai/openai-python)
SDK's request transform.

Before sending a request, openai-python passes the body through
`openai._utils._transform`, which walks it node by node and re-derives the parameter
type's structure with typing introspection for every value on every call. That costs about
0.25 ms per Responses input item, so an agent with a long transcript spends hundreds of
milliseconds of event-loop time on every model call before any I/O happens.
`openai_fast_transform.install()` swaps in a version that compiles each parameter type once
and gives the same result as stock: hundreds of times faster on Responses requests and over
100 times faster on Chat Completions requests (see the benchmarks below).

## Usage

```python
import openai_fast_transform

openai_fast_transform.install()  # once, before the first request
```

`install()` returns `True` when the compiled transform is in place. It does nothing until
you call it (no import-time side effects, no environment variables) and never raises. If the
installed openai is not a verified release, or anything goes wrong, it logs a WARNING on the
`openai_fast_transform` logger, keeps the stock transform and returns `False`. On success it
logs the openai version and profile at INFO. Only the first call checks openai and logs;
later calls return its result.

## Guarantees

For every value and every annotation the SDK passes, the patched functions return a value
strictly equal to stock's (same container classes, dict key order, key objects and leaf
objects), raise the same exception at the same point, and have the same side effects
(generator consumption, file reads and whether they are sync or async, `model_dump` calls
and arguments, `__api_exclude__` reads). They may copy more than stock, but never return a
caller-owned container where stock returns a fresh one. Carve-outs:

1. Union arm order that depends on the history of openai's equality-keyed `lru_cache`s
   (`Union[A, B] == Union[B, A]`). A test asserts that no order-sensitive pair is reachable
   from openai's own param types.
2. The depth at which `RecursionError` or `MemoryError` occurs.
3. Third parties re-patching openai helpers or mutating `PropertyInfo` objects after
   `install()`.
4. User dunders run by type checks (`__class__`, `__instancecheck__`, ABC hooks) may run a
   different number of times.

The test suite checks this differentially against stock, sync and async: quirk cases,
synthetic fuzzing over aliases, formats, unions, recursive and unresolvable types, and
fuzzing over every TypedDict in `openai.types`. The full argument is in the header comment
of [`_transform.py`](https://github.com/rasmusfaber/openai-fast-transform/blob/main/src/openai_fast_transform/_transform.py).

## Supported openai releases

`install()` only patches an openai whose normalised `_utils/_transform.py` (docstrings,
annotations and `cast` calls dropped) and the `is_given` and `is_base64_file_input` helpers
have known fingerprints, and whose loaded functions are the ones compiled from that source.
Anything else keeps the stock transform, so the dependency has no upper bound.

| openai releases  | profile |
| ---------------- | ------- |
| 1.108.1 – 3.11.0 | A       |
| 3.12.0 – 3.18.0  | B       |
| 3.19.0 – 3.43.0  | C       |

The ranges come from fingerprinting every release from 1.0.0 to 3.43.0; the fingerprints
are identical on Python 3.12, 3.13 and 3.14. Releases before 1.108.1 are refused. CI tests
both ends of every range, and a weekly job tests the newest openai on PyPI.

`python -m openai_fast_transform` prints what the gate sees (it exits 1 if the release is
refused):

```
openai 3.43.0
_transform.py 972f4e003507b0ccfced9a9a08e4fafb55b55f6a28c5e14b8b14f75f75014412
is_given a5e2169fcf23b5b0e42ee616ee372dddb848f1f14db2a4706bed313e94caa62b
is_base64_file_input 7a7155747eff3c1445c585d97f6dbe7e83a72ac99ba3bfa870f72f3ab13c7be6
profile C
```

## Benchmarks

`openai._utils._transform.transform` / `async_transform` on two synthetic request bodies:

- Responses (`ResponseCreateParamsNonStreaming`): a developer and a user message, then
  repeated reasoning (6,000-character `encrypted_content`), `function_call` and
  `function_call_output` items up to the given number of input items, two function tools
  and the usual omitted fields.
- Chat Completions (`CompletionCreateParamsNonStreaming`), 1 MB of JSON: a system and a
  user message (2,000 characters each), then 311 assistant messages (300 characters of
  text and one function tool call) each followed by a tool message with a 2,700-character
  result, 624 messages in all, two function tools and the usual omitted fields.

These are medians of 21 runs on Python 3.13.12, openai 3.43.0 and an AMD Ryzen 7 9800X3D.

| request                | mode  | stock (ms) | patched (ms) | speed-up |
| ---------------------- | ----- | ---------: | -----------: | -------: |
| Responses, 50 items    | sync  |       13.9 |         0.02 |     601x |
| Responses, 50 items    | async |       14.2 |         0.03 |     444x |
| Responses, 300 items   | sync  |       84.8 |         0.13 |     666x |
| Responses, 300 items   | async |       84.1 |         0.16 |     536x |
| Responses, 1000 items  | sync  |      284.6 |         0.43 |     662x |
| Responses, 1000 items  | async |      299.3 |         0.45 |     661x |
| Chat Completions, 1 MB | sync  |       50.2 |         0.36 |     138x |
| Chat Completions, 1 MB | async |       54.6 |         0.37 |     147x |

`install()` takes about 10 ms. The first call for a parameter type compiles its plans, once
per process for sync and once for async: 14 ms and 8 ms for the Responses create params.

## Limitations

- Plans are compiled only for openai's own types. Anything else, such as a user-defined
  TypedDict or `Annotated` metadata that is not openai's `PropertyInfo`, runs the stock
  transform for that part of the request.
- openai only. anthropic 1.8 and later already replaced this transform upstream.
- After 20,000 compiled nodes (all of `openai.types` takes about 4,800), new annotations
  use the stock transform, so callers that build a new annotation per call cannot grow
  memory without bound.

## Maintenance

When a new openai release changes the transform, `install()` refuses it and the weekly
**Newest openai** workflow fails. GitHub disables scheduled workflows in a public repository
after 60 days without activity; if **Newest openai** is disabled, re-enable it under
Actions. To support the release:

1. Install it and run `python -m openai_fast_transform` to get its fingerprints.
2. Diff `src/openai/_utils/_transform.py`, `is_given` and `is_base64_file_input` against the
   last verified release in openai-python's git history. Decide whether the change only
   reaches helpers the plans call live (the same profile) or changes a branch the compiler
   mirrors (a new profile, with a matching change in `_Compiler` and `_Node.apply`).
3. Add the fingerprint and its release range to `_PROFILES` (or `_HELPERS`) in
   [`_transform.py`](https://github.com/rasmusfaber/openai-fast-transform/blob/main/src/openai_fast_transform/_transform.py).
   For a new profile, also add its first release to `_FIRST_RELEASES` in
   `tests/test_transform.py`.
4. Run the tests against the new release and add it to the `test-openai` matrix in
   `.github/workflows/pr-and-main.yaml`. Update the table above.

## Development

```bash
uv sync --all-groups
uv run pytest -n auto
uv run ruff check && uv run ruff format --check && uv run basedpyright

# Against another openai release (uv sync restores the locked one):
uv pip install openai==3.12.0 && uv run --no-sync pytest -n auto

# On another Python:
UV_PROJECT_ENVIRONMENT=.venv-3.12 uv run --python 3.12 --all-groups pytest -n auto
```

To release, publish a GitHub release tagged `vX.Y.Z`. The **Release** workflow builds the
sdist and wheel and uploads them with PyPI Trusted Publishing (the PyPI project trusts
`release.yaml` in the `pypi` environment).

## License

MIT. See [LICENSE](https://github.com/rasmusfaber/openai-fast-transform/blob/main/LICENSE).
