codex-backend-sdk 0.5.8__tar.gz → 0.5.9__tar.gz

{codex_backend_sdk-0.5.8 → codex_backend_sdk-0.5.9}/CHANGELOG.md

@@ -2,6 +2,17 @@
 
 All notable changes to this project will be documented in this file.
 
+## [0.5.9] - 2026-10-24
+
+### Added
+- OAuth transcription-only primary Realtime WebSocket with JSON events,
+  context-managed cleanup, bounded socket timeout, and no automatic audio replay.
+  Verified with synthetic PCM16LE mono 24 kHz speech, no developer API key.
+
+### Documentation
+- Distinguish verified Realtime transcription from the legacy batch route's
+  current HTTP 403 responses; OAuth success does not establish quota coverage.
+
 ## [0.5.8] - 2026-10-22
 
 ### Added

{codex_backend_sdk-0.5.8 → codex_backend_sdk-0.5.9}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: codex-backend-sdk
-Version: 0.5.8
+Version: 0.5.9
 Summary: Unofficial Python SDK for the ChatGPT Codex backend API
 License: MIT
 License-File: LICENSE

{codex_backend_sdk-0.5.8 → codex_backend_sdk-0.5.9}/codex_backend_sdk/__init__.py

@@ -17,7 +17,7 @@ Quickstart:
     print(response.output_text)
 """
 
-__version__ = "0.5.8"
+__version__ = "0.5.9"
 
 from .oauth import (
     DeviceCode,

{codex_backend_sdk-0.5.8 → codex_backend_sdk-0.5.9}/codex_backend_sdk/resources/realtime.py

@@ -3,6 +3,7 @@
 from __future__ import annotations
 
 import json
+from contextlib import contextmanager
 import threading
 import urllib.parse
 import uuid
@@ -33,6 +34,38 @@ class Realtime:
         self.sideband = RealtimeSideband(client)
 
 
+    @contextmanager
+    def connect(self, *, intent: str, timeout: Optional[float] = None):
+        """Open a transcription-only primary WebSocket with ChatGPT OAuth.
+
+        Events are JSON dictionaries sent/received with ``send``/``recv``.
+        There is no automatic retry or audio replay. Availability and usage
+        attribution depend on the backend; subscription coverage is not implied.
+        """
+        if intent != "transcription":
+            raise CodexBackendUnsupportedParameterError(
+                "Only intent='transcription' is supported by the OAuth primary socket."
+            )
+        store = self._client._store
+        if store is None or not store.access_token:
+            raise RuntimeError("Realtime transcription requires ChatGPT OAuth authentication.")
+        headers = {
+            "Authorization": f"Bearer {store.access_token}",
+            "originator": "codex_cli_rs",
+            "x-session-id": str(uuid.uuid4()),
+        }
+        if store.account_id:
+            headers["ChatGPT-Account-ID"] = store.account_id
+        socket = websocket.create_connection(
+            "wss://api.openai.com/v1/realtime?intent=transcription",
+            header=headers,
+            timeout=self._client._timeout if timeout is None else timeout,
+            redirect_limit=0,
+        )
+        with RealtimeConnection(socket) as connection:
+            yield connection
+
+
 class Live:
     """OpenAI-compatible Live resource backed by ChatGPT OAuth.
 
@@ -114,8 +147,8 @@ class Live:
         )
 
 
-class RealtimeSidebandConnection:
-    """JSON transport joined to an existing Realtime v3 WebRTC call."""
+class RealtimeConnection:
+    """Synchronous JSON event transport with deterministic socket cleanup."""
 
     def __init__(self, socket: Any, *, graceful_close: bool = False) -> None:
         self._socket = socket
@@ -125,20 +158,20 @@ class RealtimeSidebandConnection:
 
     def send(self, event: Any) -> None:
         if self.closed:
-            raise RuntimeError("Realtime sideband connection is closed.")
+            raise RuntimeError("Realtime connection is closed.")
         payload = json.dumps(_jsonable(event), ensure_ascii=False)
         with self._send_lock:
             self._socket.send(payload)
 
     def recv(self) -> dict[str, Any]:
         if self.closed:
-            raise RuntimeError("Realtime sideband connection is closed.")
+            raise RuntimeError("Realtime connection is closed.")
         payload = self._socket.recv()
         if isinstance(payload, bytes):
             payload = payload.decode("utf-8")
         event = json.loads(payload)
         if not isinstance(event, dict):
-            raise TypeError("Expected a Realtime sideband event to be a JSON object.")
+            raise TypeError("Expected a Realtime event to be a JSON object.")
         return event
 
     def close(self) -> None:
@@ -159,13 +192,17 @@ class RealtimeSidebandConnection:
             except (IndexError, StopIteration):
                 return
 
-    def __enter__(self) -> "RealtimeSidebandConnection":
+    def __enter__(self) -> "RealtimeConnection":
         return self
 
     def __exit__(self, *_: Any) -> None:
         self.close()
 
 
+class RealtimeSidebandConnection(RealtimeConnection):
+    """JSON transport joined to an existing Realtime v3 WebRTC call."""
+
+
 class LiveSidebandConnection(RealtimeSidebandConnection):
     """Live-shaped event stream over the Codex OAuth sideband dialect."""
 

{codex_backend_sdk-0.5.8 → codex_backend_sdk-0.5.9}/docs/api-reference.md

@@ -250,7 +250,8 @@ content and a MIME type.
 Required: `file`, `model`. Supported optional backend parameters are `language`,
 `prompt`, `response_format` (`json` or `text`), `temperature`, `extra_headers`,
 `extra_query`, `extra_body`, and `timeout`. Returns typed `Transcription` for
-JSON or `str` for text.
+JSON or `str` for text. The legacy batch route returned HTTP 403 in live tests
+on October 24, 2026; prefer the verified transcription WebSocket below.
 
 The OpenAI-compatible signature rejects unsupported `chunking_strategy`,
 `include`, `known_speaker_names`, `known_speaker_references`, `stream`, and
@@ -271,6 +272,7 @@ Platform quota rather than the ChatGPT subscription.
 
 | Method | Parameters | Returns |
 | --- | --- | --- |
+| `client.realtime.connect(...)` | `intent="transcription"`, optional `timeout` | context manager yielding a JSON `RealtimeConnection` |
 | `client.live.create(...)` | official `session`, `transport`; standard request extensions | `LiveCreateResponse` with `session.id` and `transport.sdp` |
 | `client.live.sideband.connect(...)` | official sideband keywords including `session_id`, `graceful_close`, request/socket/retry options | lazy `LiveSidebandConnectionManager` context manager |
 | `client.realtime.calls.create_v3(...)` | `sdp`, `session`, optional `session_id`, `thread_id`, transport extensions | typed `RealtimeCallResponse` |
@@ -284,11 +286,11 @@ apply `response.transport.sdp`, then attach with
 adapter presents the backend call ID as the Live session ID. The connection is
 iterable and yields forward-compatible `LiveEvent` objects with attribute
 access. The public primary `client.live.connect()` transport raises an explicit
-unsupported error because ChatGPT OAuth currently exposes only WebRTC plus an
-attached sideband.
+unsupported error. This is distinct from the transcription-only primary
+`client.realtime.connect(intent="transcription")` socket, verified with OAuth
+on October 24, 2026. Its quota/billing attribution is not established.
 
-`create_v3()` requires the effective model to be `gpt-live-1-codex` or
-`gpt-live-1-boulder-alpha`, removes any caller-supplied session ID, generates
+`create_v3()` forwards the requested model and explicit correlation IDs, generates
 required backend correlation IDs when omitted, and applies the current Codex v3
 intent/architecture. The result exposes `answer_sdp`, `call_id`, raw `session`,
 and original response text. The sideband connection joins that call over
@@ -768,3 +770,25 @@ validation errors according to the boundary.
   mutations.
 - Commercial/admin, attestation, reporting, telemetry, analytics, beacon, and
   personal-access-token surfaces are outside the public SDK API.
+
+### Transcription-only OAuth WebSocket
+
+```python
+client.authenticate(interactive=False)
+with client.realtime.connect(intent="transcription", timeout=10) as connection:
+    connection.send({"type": "session.update", "session": {
+        "type": "transcription", "audio": {"input": {
+            "format": {"type": "audio/pcm", "rate": 24000},
+            "transcription": {"model": "gpt-4o-mini-transcribe", "language": "fr"},
+            "turn_detection": None,
+        }},
+    }})
+    # Wait for session.updated (handle error events), then send base64 PCM16LE
+    # mono chunks as input_audio_buffer.append and input_audio_buffer.commit.
+    # Receive conversation.item.input_audio_transcription.completed.
+```
+
+This synchronous raw-event surface has no automatic retry/replay, generated
+assistant response, tools, or output audio. Set a bounded socket timeout and an
+application-level total deadline. Context exit closes the socket even on failure.
+Only `intent="transcription"` is supported; model/session events remain caller-owned.

{codex_backend_sdk-0.5.8 → codex_backend_sdk-0.5.9}/docs/backend-api.md

@@ -402,7 +402,8 @@ low-level `client.realtime.sideband.connect(...)`) joins its
 JSON control/delegation channel at `/v1/live/{call_id}` with the current ChatGPT
 OAuth account. This transport is used for client-managed delegation events and
 context appends. The SDK intentionally does not expose the unrelated API-key
-Voice v2 WebSocket surface.
+Voice v2 conversation WebSocket surface. It separately exposes the verified
+transcription-only primary socket described below.
 
 ---
 
@@ -410,8 +411,10 @@ Voice v2 WebSocket surface.
 
 These OpenAI-shaped resources deliberately use different upstreams. Embeddings
 remain an OpenAI Platform call and consume the associated developer-account
-quota. Batch transcription uses the authenticated ChatGPT backend and does not
-require a developer API key.
+quota. Legacy batch transcription uses the authenticated ChatGPT backend but
+returned HTTP 403 in current live tests. The transcription-only Realtime socket
+accepts ChatGPT OAuth without a developer API key; its quota/billing attribution
+is not established.
 
 ### `POST /v1/embeddings`
 
@@ -437,13 +440,26 @@ subscription.
 
 **SDK method**: `client.audio.transcriptions.create(...)`
 
-**Status**: Supported for non-streaming ChatGPT batch transcription. The SDK
+**Status**: Legacy adapter present, but live tests with WebM and WAV returned
+HTTP 403 HTML on October 24, 2026. This is not proof of permanent removal. The SDK
 uploads multipart audio with the OAuth bearer and `ChatGPT-Account-ID`, and
 supports the `model`, `language`, `prompt`, `temperature`, and `json`/`text`
 response options used by Codex Agent. Streaming, timestamps, speaker references,
 chunking, SRT, and VTT are rejected locally rather than falling back to a
 billable Platform endpoint.
 
+### `WSS /v1/realtime?intent=transcription` (api.openai.com)
+
+**SDK method**: `client.realtime.connect(intent="transcription", timeout=...)`
+
+**Status**: Verified October 24, 2026 with a ChatGPT OAuth bearer, no API key.
+`session.update` with type `transcription`, PCM16LE mono 24 kHz,
+`gpt-4o-mini-transcribe`, and `turn_detection: null` accepted synthetic speech and
+returned the correct `conversation.item.input_audio_transcription.completed` text.
+The ChatGPT backend URL `/backend-api/codex/realtime?intent=transcription` instead
+returned HTTP 403. Subscription coverage and quota/billing attribution remain
+unverified; successful OAuth authentication alone does not establish either.
+
 ### `POST /backend-api/codex/images/generations`
 
 **SDK method**: `client.images.generate(...)`

{codex_backend_sdk-0.5.8 → codex_backend_sdk-0.5.9}/docs/openai-compatibility.md

@@ -20,7 +20,8 @@ parameter cannot disappear silently from the backend client surface.
 | `responses.compact` | Official parameters preserved; Codex tool/reasoning controls are additive | Supported request options and `extra_body` are forwarded | Stored-response continuation and explicit Platform prompt-cache controls are unavailable |
 | `models.list` / `retrieve` | Official parameters preserved; `force_refresh` is additive | Returns iterable OpenAI-shaped model pages | Catalog retrieval is a Codex endpoint and `retrieve` resolves from that catalog |
 | `embeddings.create` | Official signature preserved | Uses the OpenAI endpoint with the Codex OAuth bearer | Availability depends on OAuth scopes and account rollout |
-| `audio.transcriptions.create` | Official signature preserved | File inputs, JSON/text output, language, prompt, and temperature are supported | Streaming, diarization, timestamps, `keywords`, and multi-language hints raise explicitly |
+| `realtime.connect` | Transcription-only OAuth subset | Context manager, raw JSON send/recv, deterministic close | Only `intent="transcription"`; no automatic replay; quota attribution unverified |
+| `audio.transcriptions.create` | Official signature preserved | Legacy batch adapter retains file inputs and options; live route returned HTTP 403 on October 24, 2026 | Streaming, diarization, timestamps, `keywords`, and multi-language hints raise explicitly |
 | `images.generate` | Official signature preserved | GPT Image generation returns OpenAI-shaped base64 results | Codex always returns non-streamed PNG/base64 output; format/compression and Platform user attribution are unavailable |
 | `images.edit` | Official signature preserved | Single/multiple file inputs, URLs, data URLs, reference objects, and masks are normalized to Codex JSON | A mask targets the first image; `file_id` is contract-derived but not live-verified; Codex returns non-streamed PNG/base64 output |
 | `files.create` | Official signature is present | Not callable with Codex OAuth | Live probe returned missing `api.files.write`; the method raises a scope-specific unsupported error |

{codex_backend_sdk-0.5.8 → codex_backend_sdk-0.5.9}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "codex-backend-sdk"
-version = "0.5.8"
+version = "0.5.9"
 description = "Unofficial Python SDK for the ChatGPT Codex backend API"
 readme = "README.md"
 license = { text = "MIT" }

{codex_backend_sdk-0.5.8 → codex_backend_sdk-0.5.9}/tests/test_realtime_resource.py

@@ -279,3 +279,37 @@ def test_realtime_call_response_requires_valid_location():
         assert "does not contain a valid call id" in str(exc)
     else:
         raise AssertionError("Expected invalid Location to fail")
+
+
+def test_primary_transcription_socket_uses_oauth_and_closes_on_failure(monkeypatch):
+    client = FakeRealtimeClient()
+    socket = FakeWebSocket([json.dumps({"type": "session.created"})])
+    captured = {}
+    def connect(url, **kwargs):
+        captured.update(url=url, **kwargs)
+        return socket
+    monkeypatch.setattr("codex_backend_sdk.resources.realtime.websocket.create_connection", connect)
+    with pytest.raises(ValueError, match="consumer"):
+        with client.realtime.connect(intent="transcription", timeout=12) as connection:
+            assert connection.recv() == {"type": "session.created"}
+            connection.send({"type": "input_audio_buffer.commit"})
+            raise ValueError("consumer")
+    assert captured["url"] == "wss://api.openai.com/v1/realtime?intent=transcription"
+    assert captured["header"]["Authorization"] == "Bearer chatgpt-token"
+    assert captured["header"]["ChatGPT-Account-ID"] == "account-id"
+    assert captured["header"]["x-session-id"]
+    assert captured["timeout"] == 12
+    assert captured["redirect_limit"] == 0
+    assert json.loads(socket.sent[0]) == {"type": "input_audio_buffer.commit"}
+    assert socket.closed
+
+
+def test_primary_socket_rejects_other_intents_and_missing_oauth():
+    client = FakeRealtimeClient()
+    with pytest.raises(NotImplementedError):
+        with client.realtime.connect(intent="realtime"):
+            pass
+    client._store = None
+    with pytest.raises(RuntimeError, match="ChatGPT OAuth"):
+        with client.realtime.connect(intent="transcription"):
+            pass

{codex_backend_sdk-0.5.8 → codex_backend_sdk-0.5.9}/uv.lock

@@ -162,7 +162,7 @@ wheels = [
 
 [[package]]
 name = "codex-backend-sdk"
-version = "0.5.8"
+version = "0.5.9"
 source = { editable = "." }
 dependencies = [
     { name = "pydantic" },