codex-backend-sdk 0.3.6__tar.gz → 0.3.7__tar.gz

{codex_backend_sdk-0.3.6 → codex_backend_sdk-0.3.7}/CHANGELOG.md

@@ -2,6 +2,18 @@
 
 All notable changes to this project will be documented in this file.
 
+## [0.3.7] - 2026-07-17
+
+### Added
+- Added typed Realtime call results through `RealtimeCallResponse.answer_sdp` and `RealtimeCallResponse.call_id`.
+- Added Codex AVAS session payload support, including automatic removal of the server-generated session `id` and the required `quicksilver` query parameters.
+
+### Documentation
+- Documented that the ChatGPT-authenticated Codex WebRTC route is experimental and rollout-dependent, while the public Realtime WebSocket route still requires a developer API key.
+
+### Tests
+- Added coverage for SDP response parsing, call ID validation, AVAS payload construction, and invalid session payloads.
+
 ## [0.3.6] - 2026-07-11
 
 ### Added

{codex_backend_sdk-0.3.6 → codex_backend_sdk-0.3.7}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: codex-backend-sdk
-Version: 0.3.6
+Version: 0.3.7
 Summary: Unofficial Python SDK for the ChatGPT Codex backend API
 License: MIT
 License-File: LICENSE
@@ -186,7 +186,7 @@ resources (`responses`, `models`, `realtime`) or Codex-only resources (`codex`).
 | `POST /backend-api/codex/responses/compact` | `client.responses.compact(...)` | Codex-specific helper for encrypted context compaction. |
 | `POST /backend-api/codex/memories/trace_summarize` | `client.codex.memories.trace_summarize(...)` | Raw Codex memory trace summarization helper. |
 | `GET /backend-api/codex/models` | `client.models.list()` / `client.models.retrieve(...)` | OpenAI-shaped model objects with Codex metadata preserved as extra fields. |
-| `POST /backend-api/codex/realtime/calls` | `client.realtime.calls.create(...)` | OpenAI-shaped SDP call creation for realtime sessions. |
+| `POST /backend-api/codex/realtime/calls` | `client.realtime.calls.create(...)` | Experimental SDP call creation. The protocol is implemented by Codex, but ChatGPT routing is rollout-dependent and may return `404 Not Found`. |
 | `wss://api.openai.com/v1/realtime?model=...` | `client.realtime_websocket_url(...)` / `client.realtime.websocket_headers(...)` | Voice v2 helpers; requires a Realtime API key obtained during OAuth or supplied by the auth store. |
 | `POST /v1/embeddings` | `client.embeddings.create(...)` | Uses the Codex OAuth access token against `api.openai.com`; verified with `text-embedding-3-small`. |
 | `POST /v1/audio/transcriptions` | `client.audio.transcriptions.create(...)` | Uses the Codex OAuth access token against `api.openai.com`; verified with `gpt-4o-mini-transcribe`. |

{codex_backend_sdk-0.3.6 → codex_backend_sdk-0.3.7}/README.md

@@ -160,7 +160,7 @@ resources (`responses`, `models`, `realtime`) or Codex-only resources (`codex`).
 | `POST /backend-api/codex/responses/compact` | `client.responses.compact(...)` | Codex-specific helper for encrypted context compaction. |
 | `POST /backend-api/codex/memories/trace_summarize` | `client.codex.memories.trace_summarize(...)` | Raw Codex memory trace summarization helper. |
 | `GET /backend-api/codex/models` | `client.models.list()` / `client.models.retrieve(...)` | OpenAI-shaped model objects with Codex metadata preserved as extra fields. |
-| `POST /backend-api/codex/realtime/calls` | `client.realtime.calls.create(...)` | OpenAI-shaped SDP call creation for realtime sessions. |
+| `POST /backend-api/codex/realtime/calls` | `client.realtime.calls.create(...)` | Experimental SDP call creation. The protocol is implemented by Codex, but ChatGPT routing is rollout-dependent and may return `404 Not Found`. |
 | `wss://api.openai.com/v1/realtime?model=...` | `client.realtime_websocket_url(...)` / `client.realtime.websocket_headers(...)` | Voice v2 helpers; requires a Realtime API key obtained during OAuth or supplied by the auth store. |
 | `POST /v1/embeddings` | `client.embeddings.create(...)` | Uses the Codex OAuth access token against `api.openai.com`; verified with `text-embedding-3-small`. |
 | `POST /v1/audio/transcriptions` | `client.audio.transcriptions.create(...)` | Uses the Codex OAuth access token against `api.openai.com`; verified with `gpt-4o-mini-transcribe`. |

{codex_backend_sdk-0.3.6 → codex_backend_sdk-0.3.7}/codex_backend_sdk/__init__.py

@@ -17,7 +17,7 @@ Quickstart:
     print(response.output_text)
 """
 
-__version__ = "0.3.6"
+__version__ = "0.3.7"
 
 from .oauth import run_oauth_flow, refresh_access_token
 from .storage import load_tokens, save_tokens, TokenStore

{codex_backend_sdk-0.3.6 → codex_backend_sdk-0.3.7}/codex_backend_sdk/_models.py

@@ -304,4 +304,30 @@ class BinaryResponseContent:
 
 
 class RealtimeCallResponse(BinaryResponseContent):
-    """Binary SDP response returned by ``client.realtime.calls.create``."""
+    """SDP answer and call identifier returned by Realtime call creation."""
+
+    @property
+    def answer_sdp(self) -> str:
+        return self.text
+
+    @property
+    def call_id(self) -> str:
+        location = self.response.headers.get("Location")
+        if not location:
+            raise RuntimeError("Realtime call response is missing the Location header.")
+        path = location.split("?", 1)[0].rstrip("/")
+        call_id = path.rsplit("/", 1)[-1]
+        if call_id.startswith("rtc_") or _is_uuid(call_id):
+            return call_id
+        raise RuntimeError(
+            f"Realtime call Location does not contain a valid call id: {location}"
+        )
+
+
+def _is_uuid(value: str) -> bool:
+    if len(value) != 36:
+        return False
+    return all(
+        char == "-" if index in {8, 13, 18, 23} else char in "0123456789abcdefABCDEF"
+        for index, char in enumerate(value)
+    )

{codex_backend_sdk-0.3.6 → codex_backend_sdk-0.3.7}/codex_backend_sdk/resources/realtime.py

@@ -35,6 +35,12 @@ class Realtime:
 
 
 class RealtimeCalls:
+    """Experimental Codex WebRTC call creation.
+
+    Availability depends on the Realtime call route enabled for the authenticated
+    ChatGPT account. A correctly authenticated request may still return 404 while
+    the backend is not rolled out.
+    """
     def __init__(self, client: CodexClient) -> None:
         self._client = client
 
@@ -65,15 +71,23 @@ class RealtimeCalls:
             )
             return RealtimeCallResponse(response)
 
+        session_payload = _jsonable(session)
+        if not isinstance(session_payload, dict):
+            raise TypeError("Expected `session` to serialize to a JSON object.")
+        session_payload.pop("id", None)
+        body = {
+            "sdp": sdp,
+            "session": session_payload,
+            **(_jsonable(extra_body) if extra_body else {}),
+        }
+        query = {"intent": "quicksilver", "architecture": "avas"}
+        if extra_query:
+            query.update(extra_query)
         response = self._client._post_raw(
             "/realtime/calls",
-            body={
-                "sdp": sdp,
-                "session": _jsonable(session),
-                **(_jsonable(extra_body) if extra_body else {}),
-            },
+            body=body,
             headers={"Accept": "application/sdp", **(extra_headers or {})},
-            params=extra_query,
+            params=query,
             timeout=timeout,
         )
         return RealtimeCallResponse(response)

{codex_backend_sdk-0.3.6 → codex_backend_sdk-0.3.7}/docs/backend-api.md

@@ -264,14 +264,21 @@ Realtime audio/video call initiation.
 
 **SDK method**: `client.realtime.calls.create(...)`
 
-**Status**: Supported. The SDK follows the official OpenAI SDK shape:
+**Status**: Experimental and rollout-dependent. The SDK follows the Codex
+client protocol:
 
 - plain SDP offer: `client.realtime.calls.create(sdp=offer_sdp)`
-- SDP offer plus session payload:
+- AVAS SDP offer plus session payload:
   `client.realtime.calls.create(sdp=offer_sdp, session={...})`
 
-The response is returned as binary SDP content with `.content`, `.text`,
-`.read()`, `.iter_bytes()`, and `.write_to_file(...)` helpers.
+The OAuth-authenticated ChatGPT route is not enabled for every account and may
+return `404 Not Found` until Codex supplies an experimental WebRTC call base URL.
+This is distinct from the public Realtime WebSocket route, which currently
+requires a developer API key.
+
+The response exposes `.answer_sdp` and `.call_id`, while preserving the binary
+helpers `.content`, `.text`, `.read()`, `.iter_bytes()`, and
+`.write_to_file(...)`.
 
 ---
 

{codex_backend_sdk-0.3.6 → codex_backend_sdk-0.3.7}/pyproject.toml

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

{codex_backend_sdk-0.3.6 → codex_backend_sdk-0.3.7}/tests/test_realtime_resource.py

@@ -6,6 +6,7 @@ class FakeResponse:
     content = b"answer-sdp"
     text = "answer-sdp"
     encoding = "utf-8"
+    headers = {"Location": "/v1/realtime/calls/calls/rtc_test"}
 
     def json(self, **kwargs):
         return {"ok": True}
@@ -43,6 +44,8 @@ def test_realtime_calls_create_posts_plain_sdp_like_official_sdk():
 
     assert isinstance(response, RealtimeCallResponse)
     assert response.read() == b"answer-sdp"
+    assert response.answer_sdp == "answer-sdp"
+    assert response.call_id == "rtc_test"
     path, kwargs = client.raw_posts[0]
     assert path == "/realtime/calls"
     assert kwargs["content"] == b"offer-sdp"
@@ -55,7 +58,7 @@ def test_realtime_calls_create_posts_session_as_backend_json():
 
     client.realtime.calls.create(
         sdp="offer-sdp",
-        session={"type": "realtime", "model": "gpt-realtime-1.5"},
+        session={"id": "session-id", "type": "realtime", "model": "gpt-realtime-1.5"},
     )
 
     path, kwargs = client.raw_posts[0]
@@ -64,9 +67,33 @@ def test_realtime_calls_create_posts_session_as_backend_json():
         "sdp": "offer-sdp",
         "session": {"type": "realtime", "model": "gpt-realtime-1.5"},
     }
+    assert kwargs["params"] == {"intent": "quicksilver", "architecture": "avas"}
     assert kwargs["headers"]["Accept"] == "application/sdp"
 
 
+def test_realtime_calls_create_rejects_non_object_session():
+    client = FakeRealtimeClient()
+
+    try:
+        client.realtime.calls.create(sdp="offer-sdp", session=["invalid"])
+    except TypeError as exc:
+        assert str(exc) == "Expected `session` to serialize to a JSON object."
+    else:
+        raise AssertionError("Expected non-object session to fail")
+
+
+def test_realtime_call_response_requires_valid_location():
+    response = FakeResponse()
+    response.headers = {"Location": "/v1/realtime/calls/not-a-call"}
+
+    try:
+        RealtimeCallResponse(response).call_id
+    except RuntimeError as exc:
+        assert "does not contain a valid call id" in str(exc)
+    else:
+        raise AssertionError("Expected invalid Location to fail")
+
+
 def test_realtime_websocket_uses_api_key_exchanged_during_oauth():
     client = FakeRealtimeClient()