codex-backend-sdk 0.3.1__tar.gz → 0.3.2__tar.gz

{codex_backend_sdk-0.3.1 → codex_backend_sdk-0.3.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: codex-backend-sdk
-Version: 0.3.1
+Version: 0.3.2
 Summary: Unofficial Python SDK for the ChatGPT Codex backend API
 License: MIT
 License-File: LICENSE
@@ -270,10 +270,11 @@ as opaque backend state.
 
 `client.models.list()` and `client.models.retrieve(model)` mirror the official
 OpenAI models resource, while preserving Codex-specific metadata as extra
-Pydantic fields.
+Pydantic fields. The returned page also exposes the backend `ETag` when present.
 
 ```python
 models = client.models.list()
+print(models.etag)
 for model in models:
     print(
         model.id,
@@ -413,23 +414,29 @@ These methods return raw backend dictionaries because these payloads can contain
 personal account-specific fields and may change without notice.
 
 `client.codex.memories.trace_summarize(...)` exposes the Codex memory
-summarization endpoint used by the official client. It returns the raw backend
-dictionary:
+summarization endpoint used by the official client. It accepts dictionaries or
+`RawMemory` objects and returns a typed `MemorySummarizeResponse`:
 
 ```python
+from codex_backend_sdk import RawMemory
+
 summary = client.codex.memories.trace_summarize(
     model="gpt-5.4",
     traces=[
-        {
-            "id": "trace_1",
-            "metadata": {"source_path": "memory.jsonl"},
-            "items": [{"type": "message", "content": "Remember this"}],
-        }
+        RawMemory(
+            id="trace_1",
+            metadata={"source_path": "memory.jsonl"},
+            items=[{"type": "message", "content": "Remember this"}],
+        )
     ],
     reasoning={"effort": "low"},
 )
+print(summary.output[0].memory_summary)
 ```
 
+Transient HTTP failures (`429`, `5xx`, timeouts, and connection errors) are
+retried by default. Configure this with `OpenAI(max_retries=..., retry_base_delay=...)`.
+
 ### File Uploads
 
 `client.files.upload(...)` follows the official Codex file flow for Apps/MCP

{codex_backend_sdk-0.3.1 → codex_backend_sdk-0.3.2}/README.md

@@ -244,10 +244,11 @@ as opaque backend state.
 
 `client.models.list()` and `client.models.retrieve(model)` mirror the official
 OpenAI models resource, while preserving Codex-specific metadata as extra
-Pydantic fields.
+Pydantic fields. The returned page also exposes the backend `ETag` when present.
 
 ```python
 models = client.models.list()
+print(models.etag)
 for model in models:
     print(
         model.id,
@@ -387,23 +388,29 @@ These methods return raw backend dictionaries because these payloads can contain
 personal account-specific fields and may change without notice.
 
 `client.codex.memories.trace_summarize(...)` exposes the Codex memory
-summarization endpoint used by the official client. It returns the raw backend
-dictionary:
+summarization endpoint used by the official client. It accepts dictionaries or
+`RawMemory` objects and returns a typed `MemorySummarizeResponse`:
 
 ```python
+from codex_backend_sdk import RawMemory
+
 summary = client.codex.memories.trace_summarize(
     model="gpt-5.4",
     traces=[
-        {
-            "id": "trace_1",
-            "metadata": {"source_path": "memory.jsonl"},
-            "items": [{"type": "message", "content": "Remember this"}],
-        }
+        RawMemory(
+            id="trace_1",
+            metadata={"source_path": "memory.jsonl"},
+            items=[{"type": "message", "content": "Remember this"}],
+        )
     ],
     reasoning={"effort": "low"},
 )
+print(summary.output[0].memory_summary)
 ```
 
+Transient HTTP failures (`429`, `5xx`, timeouts, and connection errors) are
+retried by default. Configure this with `OpenAI(max_retries=..., retry_base_delay=...)`.
+
 ### File Uploads
 
 `client.files.upload(...)` follows the official Codex file flow for Apps/MCP

{codex_backend_sdk-0.3.1 → codex_backend_sdk-0.3.2}/codex_backend_sdk/__init__.py

@@ -17,7 +17,7 @@ Quickstart:
     print(response.output_text)
 """
 
-__version__ = "0.3.1"
+__version__ = "0.3.2"
 
 from .oauth import run_oauth_flow, refresh_access_token, obtain_api_key
 from .storage import load_tokens, save_tokens, TokenStore
@@ -33,7 +33,11 @@ from .codex_client import (
     Verbosity,
     CodexClient,
     OpenAI,
+    MemorySummarizeOutput,
+    MemorySummarizeResponse,
     Model,
+    RawMemory,
+    RawMemoryMetadata,
     Response,
     ResponseStreamEvent,
     ResponseUsage,
@@ -54,7 +58,11 @@ __all__ = [
     "CreateEmbeddingResponse",
     "Embedding",
     "EmbeddingUsage",
+    "MemorySummarizeOutput",
+    "MemorySummarizeResponse",
     "Model",
+    "RawMemory",
+    "RawMemoryMetadata",
     "Response",
     "ResponseStreamEvent",
     "ResponseUsage",

{codex_backend_sdk-0.3.1 → codex_backend_sdk-0.3.2}/codex_backend_sdk/_client.py

@@ -3,6 +3,7 @@
 from __future__ import annotations
 
 import urllib.parse
+import time
 from typing import Any, Optional
 
 import requests
@@ -32,6 +33,8 @@ class CodexClient:
         model: str = "gpt-5.4",
         instructions: Optional[str] = None,
         timeout: float = 120,
+        max_retries: int = 2,
+        retry_base_delay: float = 0.25,
     ) -> None:
         from .resources.codex import CodexResources
         from .resources.models import Models
@@ -42,6 +45,8 @@ class CodexClient:
 
         self._store = store
         self._timeout = timeout
+        self._max_retries = max_retries
+        self._retry_base_delay = retry_base_delay
         self._session = requests.Session()
         self._defaults = {
             "model": model,
@@ -121,14 +126,30 @@ class CodexClient:
             return False
 
     def _get(self, path: str, *, params: Optional[dict[str, Any]] = None) -> dict[str, Any]:
+        return self._get_raw(path, params=params).json()
+
+    def _get_raw(
+        self,
+        path: str,
+        *,
+        params: Optional[dict[str, Any]] = None,
+        headers: Optional[dict[str, str]] = None,
+        timeout: Any = _UNSET,
+    ) -> requests.Response:
         self._ensure_auth()
-        response = self._session.get(f"{BASE_URL}{path}", params=params, timeout=self._timeout)
-        response.raise_for_status()
-        return response.json()
+        response = self._request_with_retries(
+            "GET",
+            f"{BASE_URL}{path}",
+            params=params,
+            headers=headers,
+            timeout=self._timeout if not _is_given(timeout) else timeout,
+        )
+        return response
 
     def _post(self, path: str, *, body: dict[str, Any], stream: bool = False) -> requests.Response:
         self._ensure_auth()
-        response = self._session.post(
+        response = self._request_with_retries(
+            "POST",
             f"{BASE_URL}{path}",
             json=body,
             headers={"Accept": "text/event-stream"} if stream else None,
@@ -151,7 +172,8 @@ class CodexClient:
         timeout: Any = _UNSET,
     ) -> requests.Response:
         self._ensure_auth()
-        response = self._session.post(
+        response = self._request_with_retries(
+            "POST",
             f"{BASE_URL}{path}",
             json=body if files is None and data is None and content is None else None,
             data=content if content is not None else data,
@@ -178,12 +200,14 @@ class CodexClient:
         params: Optional[dict[str, Any]] = None,
         timeout: Any = _UNSET,
     ) -> dict[str, Any]:
-        response = requests.post(
+        response = self._request_with_retries(
+            "POST",
             f"{OPENAI_BASE_URL}{path}",
             json=body,
             headers=self._openai_headers(headers),
             params=params,
             timeout=self._timeout if not _is_given(timeout) else timeout,
+            _use_session=False,
         )
         response.raise_for_status()
         return response.json()
@@ -200,7 +224,8 @@ class CodexClient:
         timeout: Any = _UNSET,
         stream: bool = False,
     ) -> requests.Response:
-        response = requests.post(
+        response = self._request_with_retries(
+            "POST",
             f"{OPENAI_BASE_URL}{path}",
             json=body if files is None and data is None else None,
             data=data,
@@ -209,20 +234,24 @@ class CodexClient:
             params=params,
             stream=stream,
             timeout=self._timeout if not _is_given(timeout) else timeout,
+            _use_session=False,
         )
         response.raise_for_status()
         return response
 
     def _get_wham(self, path: str, *, params: Optional[dict[str, Any]] = None) -> dict[str, Any]:
         self._ensure_auth()
-        response = self._session.get(f"{WHAM_BASE_URL}{path}", params=params, timeout=30)
-        response.raise_for_status()
+        response = self._request_with_retries(
+            "GET",
+            f"{WHAM_BASE_URL}{path}",
+            params=params,
+            timeout=30,
+        )
         return response.json()
 
     def _get_chatgpt(self, path: str) -> dict[str, Any]:
         self._ensure_auth()
-        response = self._session.get(f"{CHATGPT_BASE_URL}{path}", timeout=30)
-        response.raise_for_status()
+        response = self._request_with_retries("GET", f"{CHATGPT_BASE_URL}{path}", timeout=30)
         return response.json()
 
     def _post_chatgpt(
@@ -233,14 +262,47 @@ class CodexClient:
         timeout: Any = _UNSET,
     ) -> dict[str, Any]:
         self._ensure_auth()
-        response = self._session.post(
+        response = self._request_with_retries(
+            "POST",
             f"{CHATGPT_BASE_URL}{path}",
             json=body,
             timeout=self._timeout if not _is_given(timeout) else timeout,
         )
-        response.raise_for_status()
         return response.json()
 
+    def _request_with_retries(self, method: str, url: str, **kwargs: Any) -> requests.Response:
+        last_error: requests.RequestException | None = None
+        use_session = kwargs.pop("_use_session", True)
+        for attempt in range(self._max_retries + 1):
+            try:
+                request = self._session.request if use_session else requests.request
+                response = request(method, url, **kwargs)
+                if self._should_retry_response(response, attempt):
+                    self._sleep_before_retry(response, attempt)
+                    continue
+                response.raise_for_status()
+                return response
+            except (requests.Timeout, requests.ConnectionError) as exc:
+                last_error = exc
+                if attempt >= self._max_retries:
+                    raise
+                self._sleep_before_retry(None, attempt)
+        if last_error is not None:
+            raise last_error
+        raise RuntimeError("Request retry loop exhausted")
+
+    def _should_retry_response(self, response: requests.Response, attempt: int) -> bool:
+        if attempt >= self._max_retries:
+            return False
+        return response.status_code == 429 or 500 <= response.status_code < 600
+
+    def _sleep_before_retry(self, response: requests.Response | None, attempt: int) -> None:
+        retry_after = response.headers.get("Retry-After") if response is not None else None
+        delay = _parse_retry_after(retry_after)
+        if delay is None:
+            delay = self._retry_base_delay * (2 ** attempt)
+        time.sleep(delay)
+
     def realtime_websocket_url(self, *, model: str) -> str:
         """Return the official OpenAI Realtime WebSocket URL for Codex plugins."""
         if not model:
@@ -262,3 +324,12 @@ class CodexClient:
 
 
 OpenAI = CodexClient
+
+
+def _parse_retry_after(value: str | None) -> float | None:
+    if not value:
+        return None
+    try:
+        return max(0.0, float(value))
+    except ValueError:
+        return None

{codex_backend_sdk-0.3.1 → codex_backend_sdk-0.3.2}/codex_backend_sdk/_models.py

@@ -173,6 +173,25 @@ class Transcription(CodexBaseModel):
     text: str = ""
 
 
+class RawMemoryMetadata(CodexBaseModel):
+    source_path: str
+
+
+class RawMemory(CodexBaseModel):
+    id: str
+    metadata: RawMemoryMetadata
+    items: list[Any] = Field(default_factory=list)
+
+
+class MemorySummarizeOutput(CodexBaseModel):
+    raw_memory: str = Field(default="", alias="trace_summary")
+    memory_summary: str = ""
+
+
+class MemorySummarizeResponse(CodexBaseModel):
+    output: list[MemorySummarizeOutput] = Field(default_factory=list)
+
+
 class UploadedFile(CodexBaseModel):
     file_id: str
     uri: str

{codex_backend_sdk-0.3.1 → codex_backend_sdk-0.3.2}/codex_backend_sdk/codex_client.py

@@ -14,6 +14,10 @@ from ._models import (
     Embedding,
     EmbeddingUsage,
     Model,
+    MemorySummarizeOutput,
+    MemorySummarizeResponse,
+    RawMemory,
+    RawMemoryMetadata,
     ReasoningEffort,
     ReasoningSummary,
     RealtimeCallResponse,
@@ -37,8 +41,12 @@ __all__ = [
     "Embedding",
     "EmbeddingUsage",
     "CompactedResponse",
+    "MemorySummarizeOutput",
+    "MemorySummarizeResponse",
     "Model",
     "OpenAI",
+    "RawMemory",
+    "RawMemoryMetadata",
     "ReasoningEffort",
     "ReasoningSummary",
     "Response",

{codex_backend_sdk-0.3.1 → codex_backend_sdk-0.3.2}/codex_backend_sdk/resources/codex.py

@@ -4,6 +4,9 @@ from __future__ import annotations
 
 from typing import Any, TYPE_CHECKING
 
+from .._models import MemorySummarizeResponse
+from .._utils import _jsonable
+
 if TYPE_CHECKING:
     from .._client import CodexClient
 
@@ -36,15 +39,17 @@ class CodexMemories:
         self,
         *,
         model: str,
-        traces: list[dict[str, Any]],
-        reasoning: dict[str, Any] | None = None,
-    ) -> dict[str, Any]:
+        traces: list[Any],
+        reasoning: Any = None,
+    ) -> MemorySummarizeResponse:
         if not model:
             raise ValueError(f"Expected a non-empty value for `model` but received {model!r}")
-        payload: dict[str, Any] = {"model": model, "traces": traces}
+        payload: dict[str, Any] = {"model": model, "traces": _jsonable(traces)}
         if reasoning is not None:
-            payload["reasoning"] = reasoning
-        return self._client._post("/memories/trace_summarize", body=payload).json()
+            payload["reasoning"] = _jsonable(reasoning)
+        return MemorySummarizeResponse.model_validate(
+            self._client._post("/memories/trace_summarize", body=payload).json()
+        )
 
 
 class CodexConfig:

{codex_backend_sdk-0.3.1 → codex_backend_sdk-0.3.2}/codex_backend_sdk/resources/models.py

@@ -36,10 +36,11 @@ class Models:
             if time.time() - self._cache_fetched_at <= _CACHE_TTL:
                 return self._cache
 
-        data = self._client._get("/models", params={"client_version": CLIENT_VERSION})
+        response = self._client._get_raw("/models", params={"client_version": CLIENT_VERSION})
+        data = response.json()
         models = [_model_from_backend(item) for item in data.get("models", [])]
         models.sort(key=lambda model: getattr(model, "priority", 0))
-        page = SyncPage(data=models)
+        page = SyncPage(data=models, etag=response.headers.get("ETag"))
         self._cache = page
         self._cache_fetched_at = time.time()
         return page

{codex_backend_sdk-0.3.1 → codex_backend_sdk-0.3.2}/docs/backend-api.md

@@ -47,6 +47,9 @@ List models available to this account.
 
 **Response** — JSON `{ "models": [ ModelObject, … ] }`
 
+The backend may include an `ETag` header. The SDK preserves it as
+`client.models.list().etag`.
+
 Key fields per model:
 | Field | Type | Notes |
 |---|---|---|
@@ -228,8 +231,8 @@ Summarize traces into persistent memories.
 
 **SDK method**: `client.codex.memories.trace_summarize(...)`
 
-**Status**: Supported as a raw helper. May return `403 Forbidden` depending on
-plan/account capabilities.
+**Status**: Supported as a typed helper. May return `403 Forbidden` depending
+on plan/account capabilities.
 
 **Request body**:
 ```json
@@ -246,7 +249,8 @@ plan/account capabilities.
 }
 ```
 
-**Response** — raw JSON, typically `{ "output": [...] }`.
+**Response** — JSON `{ "output": [...] }`, exposed by the SDK as
+`MemorySummarizeResponse`.
 
 ---
 

{codex_backend_sdk-0.3.1 → codex_backend_sdk-0.3.2}/pyproject.toml

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

codex_backend_sdk-0.3.2/tests/test_client_retry.py

@@ -0,0 +1,97 @@
+import requests
+
+import codex_backend_sdk._client as client_module
+from codex_backend_sdk import OpenAI
+
+
+class DummySession:
+    def __init__(self, outcomes):
+        self.outcomes = list(outcomes)
+        self.calls = []
+
+    def request(self, method, url, **kwargs):
+        self.calls.append((method, url, kwargs))
+        outcome = self.outcomes.pop(0)
+        if isinstance(outcome, Exception):
+            raise outcome
+        return outcome
+
+
+class RetryClient(OpenAI):
+    def __init__(self, outcomes, **kwargs):
+        super().__init__(max_retries=kwargs.pop("max_retries", 2), retry_base_delay=0, **kwargs)
+        self._session = DummySession(outcomes)
+
+    def _ensure_auth(self):
+        return None
+
+
+def _response(status_code, *, body=b"{}", headers=None):
+    response = requests.Response()
+    response.status_code = status_code
+    response._content = body
+    response.headers.update(headers or {})
+    response.url = "https://example.test"
+    return response
+
+
+def test_retry_retries_5xx_then_returns_success(monkeypatch):
+    sleeps = []
+    monkeypatch.setattr(client_module.time, "sleep", sleeps.append)
+    client = RetryClient([
+        _response(503),
+        _response(200, body=b'{"ok": true}'),
+    ])
+
+    response = client._get_raw("/models")
+
+    assert response.json() == {"ok": True}
+    assert len(client._session.calls) == 2
+    assert sleeps == [0]
+
+
+def test_retry_honors_retry_after_header(monkeypatch):
+    sleeps = []
+    monkeypatch.setattr(client_module.time, "sleep", sleeps.append)
+    client = RetryClient([
+        _response(429, headers={"Retry-After": "1.5"}),
+        _response(200),
+    ])
+
+    client._get_raw("/models")
+
+    assert len(client._session.calls) == 2
+    assert sleeps == [1.5]
+
+
+def test_retry_does_not_retry_client_errors(monkeypatch):
+    sleeps = []
+    monkeypatch.setattr(client_module.time, "sleep", sleeps.append)
+    client = RetryClient([
+        _response(400, body=b'{"error": "bad request"}'),
+    ])
+
+    try:
+        client._get_raw("/models")
+    except requests.HTTPError:
+        pass
+    else:
+        raise AssertionError("Expected HTTPError")
+
+    assert len(client._session.calls) == 1
+    assert sleeps == []
+
+
+def test_retry_retries_transport_timeout(monkeypatch):
+    sleeps = []
+    monkeypatch.setattr(client_module.time, "sleep", sleeps.append)
+    client = RetryClient([
+        requests.Timeout("temporary timeout"),
+        _response(200, body=b'{"ok": true}'),
+    ])
+
+    response = client._get_raw("/models")
+
+    assert response.json() == {"ok": True}
+    assert len(client._session.calls) == 2
+    assert sleeps == [0]

{codex_backend_sdk-0.3.1 → codex_backend_sdk-0.3.2}/tests/test_codex_resources.py

@@ -1,4 +1,4 @@
-from codex_backend_sdk import OpenAI
+from codex_backend_sdk import MemorySummarizeResponse, OpenAI, RawMemory
 
 
 class FakeCodexClient(OpenAI):
@@ -41,7 +41,9 @@ class FakeCodexClient(OpenAI):
     def _post(self, path, *, body, stream=False):
         self.posts.append((path, body, stream))
         if path == "/memories/trace_summarize":
-            return FakeJSONResponse({"output": [{"memory_summary": "summary"}]})
+            return FakeJSONResponse({
+                "output": [{"trace_summary": "raw", "memory_summary": "summary"}]
+            })
         raise AssertionError(f"Unexpected Codex post path: {path}")
 
 
@@ -77,16 +79,18 @@ def test_codex_memories_trace_summarize_posts_codex_payload():
     response = client.codex.memories.trace_summarize(
         model="gpt-test",
         traces=[
-            {
-                "id": "trace_1",
-                "metadata": {"source_path": "/tmp/memory.jsonl"},
-                "items": [{"type": "message", "content": "remember me"}],
-            }
+            RawMemory(
+                id="trace_1",
+                metadata={"source_path": "/tmp/memory.jsonl"},
+                items=[{"type": "message", "content": "remember me"}],
+            )
         ],
         reasoning={"effort": "low"},
     )
 
-    assert response == {"output": [{"memory_summary": "summary"}]}
+    assert isinstance(response, MemorySummarizeResponse)
+    assert response.output[0].raw_memory == "raw"
+    assert response.output[0].memory_summary == "summary"
     assert client.posts == [
         (
             "/memories/trace_summarize",

{codex_backend_sdk-0.3.1 → codex_backend_sdk-0.3.2}/tests/test_responses_resource.py

@@ -15,8 +15,9 @@ class FakeSSE:
 
 
 class FakeJSONResponse:
-    def __init__(self, payload):
+    def __init__(self, payload, headers=None):
         self._payload = payload
+        self.headers = headers or {}
 
     def json(self):
         return self._payload
@@ -47,28 +48,31 @@ class FakeClient(OpenAI):
             ),
         ])
 
-    def _get(self, path, *, params=None):
+    def _get_raw(self, path, *, params=None, headers=None, timeout=None):
         self.gets.append((path, params))
-        return {
-            "models": [
-                {
-                    "slug": "gpt-lower-priority",
-                    "display_name": "GPT Lower Priority",
-                    "description": "Test model",
-                    "context_window": 123,
-                    "supported_in_api": True,
-                    "priority": 7,
-                },
-                {
-                    "slug": "gpt-test",
-                    "display_name": "GPT Test",
-                    "description": "Test model",
-                    "context_window": 456,
-                    "supported_in_api": True,
-                    "priority": 1,
-                }
-            ]
-        }
+        return FakeJSONResponse(
+            {
+                "models": [
+                    {
+                        "slug": "gpt-lower-priority",
+                        "display_name": "GPT Lower Priority",
+                        "description": "Test model",
+                        "context_window": 123,
+                        "supported_in_api": True,
+                        "priority": 7,
+                    },
+                    {
+                        "slug": "gpt-test",
+                        "display_name": "GPT Test",
+                        "description": "Test model",
+                        "context_window": 456,
+                        "supported_in_api": True,
+                        "priority": 1,
+                    },
+                ]
+            },
+            headers={"ETag": "models-etag"},
+        )
 
 
 def test_responses_create_collects_to_pydantic_response():
@@ -147,6 +151,7 @@ def test_models_resource_returns_iterable_page():
     assert len(page) == 2
     assert model.id == "gpt-test"
     assert model.context_window == 456
+    assert page.etag == "models-etag"
     assert client.models.retrieve("gpt-test").id == "gpt-test"
     assert len(client.gets) == 1