codex-backend-sdk 0.5.2__tar.gz → 0.5.4__tar.gz

{codex_backend_sdk-0.5.2 → codex_backend_sdk-0.5.4}/CHANGELOG.md

@@ -2,7 +2,31 @@
 
 All notable changes to this project will be documented in this file.
 
-## Unreleased
+## [0.5.4] - 2026-09-24
+
+### Fixed
+- Preserve a bounded backend response body in raised HTTP errors so callers can
+  diagnose rejected requests without reconstructing the transport call.
+
+## [0.5.3] - 2026-09-18
+
+### Added
+- Added the OpenAI-shaped `client.live.create(...)` and
+  `client.live.sideband.connect(...)` surfaces over the existing Codex OAuth
+  Realtime v3 transport, including the public response shape and lazy
+  sideband context-manager idiom.
+- Added current Codex workspace usage, task-usage, turn-estimate, plugin/skill
+  analytics, and reset-credit history resources discovered by the refreshed
+  source scan.
+- Added the current Desktop plugin home feed and explicit plugin/skill
+  enable-disable mutations.
+
+### Changed
+- Updated the compatibility baseline to `openai-python` 3.16.1 while retaining
+  the additive low-level `client.realtime` API.
+- Reconciled the endpoint inventory with the refreshed Codex and official
+  Desktop checkouts, and tightened validation of plugin catalog responses and
+  pagination state.
 
 ## [0.5.1] - 2026-08-14
 

{codex_backend_sdk-0.5.2 → codex_backend_sdk-0.5.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: codex-backend-sdk
-Version: 0.5.2
+Version: 0.5.4
 Summary: Unofficial Python SDK for the ChatGPT Codex backend API
 License: MIT
 License-File: LICENSE
@@ -19,12 +19,12 @@ Requires-Dist: pydantic>=2.0
 Requires-Dist: requests>=2.28
 Requires-Dist: websocket-client>=1.8
 Provides-Extra: dev
-Requires-Dist: openai<2.53.0,>=1.0; (python_version < '3.10') and extra == 'dev'
-Requires-Dist: openai>=2.53.0; (python_version >= '3.10') and extra == 'dev'
+Requires-Dist: openai<3.0,>=1.0; (python_version < '3.10') and extra == 'dev'
+Requires-Dist: openai>=3.16.1; (python_version >= '3.10') and extra == 'dev'
 Requires-Dist: pytest>=7.0; extra == 'dev'
 Provides-Extra: openai
-Requires-Dist: openai<2.53.0,>=1.0; (python_version < '3.10') and extra == 'openai'
-Requires-Dist: openai>=2.53.0; (python_version >= '3.10') and extra == 'openai'
+Requires-Dist: openai<3.0,>=1.0; (python_version < '3.10') and extra == 'openai'
+Requires-Dist: openai>=3.16.1; (python_version >= '3.10') and extra == 'openai'
 Description-Content-Type: text/markdown
 
 # codex-backend-sdk
@@ -65,7 +65,7 @@ from codex_backend_sdk import OpenAI
 client = OpenAI().authenticate()
 
 response = client.responses.create(
-    model="gpt-5.4",
+    model="gpt-5.5",
     input="Explain quicksort in one paragraph.",
 )
 
@@ -89,7 +89,8 @@ client.files           # upload files for Apps/MCP parameters
 client.images          # Codex-backed image generation and editing
 client.audio           # ChatGPT-backed transcription
 client.embeddings      # OpenAI embeddings endpoint through OAuth
-client.realtime        # WebRTC call creation and Realtime connection headers
+client.live            # OpenAI-shaped GPT-Live creation and sideband attachment
+client.realtime        # additive low-level Codex Realtime v3 transport
 ```
 
 These resources follow `openai-python` conventions where the backend overlaps
@@ -142,7 +143,7 @@ dictionaries or raw streams when imposing a stable model would be misleading.
 
 ```python
 response = client.responses.create(
-    model="gpt-5.4",
+    model="gpt-5.5",
     instructions="Be concise.",
     input="Summarize the CAP theorem.",
     reasoning={"effort": "medium", "summary": "auto"},
@@ -173,7 +174,7 @@ connection reusable across sequential turns:
 
 ```python
 with client.responses.websocket.connect() as ws:
-    for event in ws.create({"model": "gpt-5.4", "input": "Say hello."}):
+    for event in ws.create({"model": "gpt-5.5", "input": "Say hello."}):
         if event.get("type") == "response.output_text.delta":
             print(event.get("delta", ""), end="")
 ```
@@ -197,7 +198,7 @@ print(client.responses.create(input=history).output_text)
 
 ```python
 compacted = client.responses.compact(
-    model="gpt-5.4",
+    model="gpt-5.5",
     instructions="Preserve task-critical decisions and unresolved work.",
     input=history,
 )
@@ -268,7 +269,7 @@ print(result.output_parsed)
 for model in client.models.list():
     print(model.id, model.context_window, model.supported_reasoning_levels)
 
-model = client.models.retrieve("gpt-5.4")
+model = client.models.retrieve("gpt-5.5")
 ```
 
 ### Upload a file
@@ -340,6 +341,10 @@ sports, and time commands. See the API reference for command validation.
 quota = client.codex.usage()
 daily = client.codex.usage_details.daily_token_breakdown()
 credits = client.codex.usage_details.credit_events()
+plugin_metrics = client.codex.usage_details.plugin_usage_metrics(
+    start_date="2026-09-01",
+    end_date="2026-09-18",
+)
 
 print(quota.get("rate_limit", {}).get("primary_window"))
 ```
@@ -443,6 +448,7 @@ tool annotations and own user confirmation; the SDK never auto-invokes tools.
 plugins = client.chatgpt.plugins.list_all(scope="GLOBAL")
 installed = client.chatgpt.plugins.installed_all()
 suggested = client.chatgpt.plugins.suggested()
+home = client.chatgpt.plugins.home()
 skill = client.chatgpt.plugins.skill("plugins~...", "skill-name")
 
 checkout = client.chatgpt.plugins.bundles.extract_plugin(
@@ -491,33 +497,42 @@ return a typed in-memory object, bytes, `BytesIO`, a data URI, or a file path.
 ### Realtime voice
 
 ```python
-answer = client.realtime.calls.create_v3(
-    sdp=offer_sdp,
+live = client.live.create(
     session={
         "model": "gpt-live-1-codex",
         "instructions": "Speak naturally and stay concise.",
+        "delegation": {"type": "client"},
     },
+    transport={"type": "webrtc", "sdp": offer_sdp},
 )
-print(answer.answer_sdp)
+apply_remote_sdp(live.transport.sdp)
+
+with client.live.sideband.connect(session_id=live.session.id) as sideband:
+    for event in sideband:
+        print(event.type)
 ```
 
 Live probes confirmed `gpt-live-1-codex` and
 `gpt-live-1-boulder-alpha`. They are Codex Realtime v3 snapshots, not aliases
-for the public `gpt-realtime` family. The call response exposes `call_id`; join
-its OAuth-authenticated control and delegation channel with:
+for the public `gpt-live-1` model. `client.live` follows the current
+`openai-python` creation, response, and sideband idioms while adapting them to
+the ChatGPT OAuth call transport.
+
+The earlier low-level surface remains available for backend-specific code:
 
 ```python
-sideband = client.realtime.sideband.connect(
-    call_id=answer.call_id,
-    session_id="voice-session",
+answer = client.realtime.calls.create_v3(
+    sdp=offer_sdp,
+    session={"model": "gpt-live-1-codex"},
 )
-sideband.send({"type": "delegation.context.append", "content": []})
-event = sideband.recv()
-sideband.close()
+with client.realtime.sideband.connect(call_id=answer.call_id) as sideband:
+    sideband.send({"type": "session.close"})
 ```
 
-The SDK intentionally exposes only the ChatGPT-authenticated v3 transport. It
-does not retain the separately billed API-key Voice v2 WebSocket helpers.
+The OAuth backend's event dialect is still experimental and is exposed
+forward-compatibly through `LiveEvent` rather than rewritten into invented
+public fields. The public primary `client.live.connect()` WebSocket is not
+available through ChatGPT OAuth; use WebRTC plus the attached sideband.
 
 ### Embeddings
 

{codex_backend_sdk-0.5.2 → codex_backend_sdk-0.5.4}/README.md

@@ -36,7 +36,7 @@ from codex_backend_sdk import OpenAI
 client = OpenAI().authenticate()
 
 response = client.responses.create(
-    model="gpt-5.4",
+    model="gpt-5.5",
     input="Explain quicksort in one paragraph.",
 )
 
@@ -60,7 +60,8 @@ client.files           # upload files for Apps/MCP parameters
 client.images          # Codex-backed image generation and editing
 client.audio           # ChatGPT-backed transcription
 client.embeddings      # OpenAI embeddings endpoint through OAuth
-client.realtime        # WebRTC call creation and Realtime connection headers
+client.live            # OpenAI-shaped GPT-Live creation and sideband attachment
+client.realtime        # additive low-level Codex Realtime v3 transport
 ```
 
 These resources follow `openai-python` conventions where the backend overlaps
@@ -113,7 +114,7 @@ dictionaries or raw streams when imposing a stable model would be misleading.
 
 ```python
 response = client.responses.create(
-    model="gpt-5.4",
+    model="gpt-5.5",
     instructions="Be concise.",
     input="Summarize the CAP theorem.",
     reasoning={"effort": "medium", "summary": "auto"},
@@ -144,7 +145,7 @@ connection reusable across sequential turns:
 
 ```python
 with client.responses.websocket.connect() as ws:
-    for event in ws.create({"model": "gpt-5.4", "input": "Say hello."}):
+    for event in ws.create({"model": "gpt-5.5", "input": "Say hello."}):
         if event.get("type") == "response.output_text.delta":
             print(event.get("delta", ""), end="")
 ```
@@ -168,7 +169,7 @@ print(client.responses.create(input=history).output_text)
 
 ```python
 compacted = client.responses.compact(
-    model="gpt-5.4",
+    model="gpt-5.5",
     instructions="Preserve task-critical decisions and unresolved work.",
     input=history,
 )
@@ -239,7 +240,7 @@ print(result.output_parsed)
 for model in client.models.list():
     print(model.id, model.context_window, model.supported_reasoning_levels)
 
-model = client.models.retrieve("gpt-5.4")
+model = client.models.retrieve("gpt-5.5")
 ```
 
 ### Upload a file
@@ -311,6 +312,10 @@ sports, and time commands. See the API reference for command validation.
 quota = client.codex.usage()
 daily = client.codex.usage_details.daily_token_breakdown()
 credits = client.codex.usage_details.credit_events()
+plugin_metrics = client.codex.usage_details.plugin_usage_metrics(
+    start_date="2026-09-01",
+    end_date="2026-09-18",
+)
 
 print(quota.get("rate_limit", {}).get("primary_window"))
 ```
@@ -414,6 +419,7 @@ tool annotations and own user confirmation; the SDK never auto-invokes tools.
 plugins = client.chatgpt.plugins.list_all(scope="GLOBAL")
 installed = client.chatgpt.plugins.installed_all()
 suggested = client.chatgpt.plugins.suggested()
+home = client.chatgpt.plugins.home()
 skill = client.chatgpt.plugins.skill("plugins~...", "skill-name")
 
 checkout = client.chatgpt.plugins.bundles.extract_plugin(
@@ -462,33 +468,42 @@ return a typed in-memory object, bytes, `BytesIO`, a data URI, or a file path.
 ### Realtime voice
 
 ```python
-answer = client.realtime.calls.create_v3(
-    sdp=offer_sdp,
+live = client.live.create(
     session={
         "model": "gpt-live-1-codex",
         "instructions": "Speak naturally and stay concise.",
+        "delegation": {"type": "client"},
     },
+    transport={"type": "webrtc", "sdp": offer_sdp},
 )
-print(answer.answer_sdp)
+apply_remote_sdp(live.transport.sdp)
+
+with client.live.sideband.connect(session_id=live.session.id) as sideband:
+    for event in sideband:
+        print(event.type)
 ```
 
 Live probes confirmed `gpt-live-1-codex` and
 `gpt-live-1-boulder-alpha`. They are Codex Realtime v3 snapshots, not aliases
-for the public `gpt-realtime` family. The call response exposes `call_id`; join
-its OAuth-authenticated control and delegation channel with:
+for the public `gpt-live-1` model. `client.live` follows the current
+`openai-python` creation, response, and sideband idioms while adapting them to
+the ChatGPT OAuth call transport.
+
+The earlier low-level surface remains available for backend-specific code:
 
 ```python
-sideband = client.realtime.sideband.connect(
-    call_id=answer.call_id,
-    session_id="voice-session",
+answer = client.realtime.calls.create_v3(
+    sdp=offer_sdp,
+    session={"model": "gpt-live-1-codex"},
 )
-sideband.send({"type": "delegation.context.append", "content": []})
-event = sideband.recv()
-sideband.close()
+with client.realtime.sideband.connect(call_id=answer.call_id) as sideband:
+    sideband.send({"type": "session.close"})
 ```
 
-The SDK intentionally exposes only the ChatGPT-authenticated v3 transport. It
-does not retain the separately billed API-key Voice v2 WebSocket helpers.
+The OAuth backend's event dialect is still experimental and is exposed
+forward-compatibly through `LiveEvent` rather than rewritten into invented
+public fields. The public primary `client.live.connect()` WebSocket is not
+available through ChatGPT OAuth; use WebRTC plus the attached sideband.
 
 ### Embeddings
 

{codex_backend_sdk-0.5.2 → codex_backend_sdk-0.5.4}/codex_backend_sdk/__init__.py

@@ -17,7 +17,7 @@ Quickstart:
     print(response.output_text)
 """
 
-__version__ = "0.5.2"
+__version__ = "0.5.3"
 
 from .oauth import (
     DeviceCode,
@@ -57,6 +57,10 @@ from .codex_client import (
     Image,
     ImageResponse,
     ImagesResponse,
+    LiveCreateResponse,
+    LiveEvent,
+    LiveSession,
+    LiveTransport,
     RateLimitResetCredit,
     RateLimitResetCredits,
     ConsumeRateLimitResetCreditResponse,
@@ -102,6 +106,10 @@ __all__ = [
     "Image",
     "ImageResponse",
     "ImagesResponse",
+    "LiveCreateResponse",
+    "LiveEvent",
+    "LiveSession",
+    "LiveTransport",
     "RateLimitResetCredit",
     "RateLimitResetCredits",
     "ConsumeRateLimitResetCreditResponse",

{codex_backend_sdk-0.5.2 → codex_backend_sdk-0.5.4}/codex_backend_sdk/_client.py

@@ -30,7 +30,7 @@ class CodexClient:
         self,
         *,
         store: Optional[TokenStore] = None,
-        model: str = "gpt-5.4",
+        model: str = "gpt-5.5",
         instructions: Optional[str] = None,
         timeout: float = 120,
         max_retries: int = 2,
@@ -44,7 +44,7 @@ class CodexClient:
         from .resources.openai_oauth import Audio, Embeddings
         from .resources.files import Files
         from .resources.images import Images
-        from .resources.realtime import Realtime
+        from .resources.realtime import Live, Realtime
         from .resources.responses import Responses
 
         self._store = store
@@ -66,6 +66,7 @@ class CodexClient:
         self.responses = Responses(self)
         self.models = Models(self)
         self.realtime = Realtime(self)
+        self.live = Live(self)
         self.embeddings = Embeddings(self)
         self.audio = Audio(self)
         self.images = Images(self)

{codex_backend_sdk-0.5.2 → codex_backend_sdk-0.5.4}/codex_backend_sdk/_models.py

@@ -435,6 +435,32 @@ class RealtimeCallResponse(BinaryResponseContent):
         )
 
 
+class LiveSession(CodexBaseModel):
+    """Resolved Live session identity returned by the OAuth adapter."""
+
+    id: str
+
+
+class LiveTransport(CodexBaseModel):
+    """WebRTC answer using the public OpenAI Live response shape."""
+
+    type: Literal["webrtc"] = "webrtc"
+    sdp: str
+
+
+class LiveCreateResponse(CodexBaseModel):
+    """OpenAI-compatible view of a Codex OAuth Realtime call response."""
+
+    session: LiveSession
+    transport: LiveTransport
+
+
+class LiveEvent(CodexBaseModel):
+    """Forward-compatible Live sideband event with attribute access."""
+
+    type: str
+
+
 def _is_uuid(value: str) -> bool:
     if len(value) != 36:
         return False

{codex_backend_sdk-0.5.2 → codex_backend_sdk-0.5.4}/codex_backend_sdk/_transport.py

@@ -8,6 +8,26 @@ from typing import Any
 import requests
 
 
+_MAX_ERROR_DETAIL_CHARS = 4_000
+
+
+def raise_for_status_with_detail(response: requests.Response) -> None:
+    """Raise the usual HTTPError while retaining a bounded backend error body."""
+    try:
+        response.raise_for_status()
+    except requests.HTTPError as error:
+        detail = response.text.strip()
+        if not detail:
+            raise
+        if len(detail) > _MAX_ERROR_DETAIL_CHARS:
+            detail = detail[:_MAX_ERROR_DETAIL_CHARS] + "..."
+        raise requests.HTTPError(
+            f"{error}. Backend response: {detail}",
+            response=response,
+            request=error.request,
+        ) from error
+
+
 def request_with_retries(
     session: requests.Session,
     method: str,
@@ -26,7 +46,7 @@ def request_with_retries(
             if should_retry_response(response, attempt, max_retries=max_retries):
                 sleep_before_retry(response, attempt, retry_base_delay=retry_base_delay)
                 continue
-            response.raise_for_status()
+            raise_for_status_with_detail(response)
             return response
         except (requests.Timeout, requests.ConnectionError) as exc:
             last_error = exc

{codex_backend_sdk-0.5.2 → codex_backend_sdk-0.5.4}/codex_backend_sdk/codex_client.py

@@ -18,6 +18,10 @@ from ._models import (
     ImageData,
     ImageResponse,
     ImagesResponse,
+    LiveCreateResponse,
+    LiveEvent,
+    LiveSession,
+    LiveTransport,
     Model,
     MemorySummarizeOutput,
     MemorySummarizeResponse,
@@ -55,6 +59,10 @@ __all__ = [
     "ImageData",
     "ImageResponse",
     "ImagesResponse",
+    "LiveCreateResponse",
+    "LiveEvent",
+    "LiveSession",
+    "LiveTransport",
     "CompactedResponse",
     "MemorySummarizeOutput",
     "MemorySummarizeResponse",