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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: codex-backend-sdk
-Version: 0.3.0
+Version: 0.3.2
 Summary: Unofficial Python SDK for the ChatGPT Codex backend API
 License: MIT
 License-File: LICENSE
@@ -184,17 +184,20 @@ resources (`responses`, `models`, `realtime`) or Codex-only resources (`codex`).
 |---|---|---|
 | `POST /backend-api/codex/responses` | `client.responses.create(...)` | Stream-only backend; non-streaming SDK calls are collected from SSE events. |
 | `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. |
 | `wss://api.openai.com/v1/realtime?model=...` | `client.realtime_websocket_url(...)` / `client.realtime_websocket_headers(...)` | Helper surface used by codex-agent's realtime plugin. |
 | `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`. |
 | `GET /backend-api/wham/usage` | `client.codex.usage()` | Codex/ChatGPT quota and rate-limit status. |
+| `GET /backend-api/wham/config/requirements` | `client.codex.config.requirements()` | Raw managed requirements/config payload for the authenticated account. |
 | `GET /backend-api/wham/tasks/list` | `client.codex.tasks.list(...)` | Raw Codex cloud task listing. |
 | `GET /backend-api/wham/tasks/{task_id}` | `client.codex.tasks.retrieve(task_id)` | Raw Codex cloud task detail. |
 | `GET /backend-api/wham/tasks/{task_id}/turns` | `client.codex.tasks.turns.list(task_id)` | Raw task turn mapping. |
 | `GET /backend-api/wham/tasks/{task_id}/turns/{turn_id}/sibling_turns` | `client.codex.tasks.turns.sibling_turns(task_id, turn_id)` | Raw sibling turn list. |
 | `GET /backend-api/wham/environments` | `client.codex.environments.list()` | Raw Codex cloud environment list. |
+| `POST /backend-api/files` + signed upload | `client.files.upload(...)` | Uploads local files for Codex Apps/MCP file parameters and returns `sediment://...` metadata. |
 | `GET /backend-api/memories` | `client.codex.memories.list()` | Raw ChatGPT memory payload for the authenticated account. |
 | `GET /backend-api/user_system_messages` | `client.codex.user_system_messages.retrieve()` | Raw ChatGPT customization/system-message payload. |
 
@@ -267,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,
@@ -403,18 +407,52 @@ not part of the official OpenAI SDK.
 ```python
 memories = client.codex.memories.list()
 customization = client.codex.user_system_messages.retrieve()
+requirements = client.codex.config.requirements()
 ```
 
-Both methods return raw backend dictionaries because these payloads can contain
+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 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=[
+        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
+file parameters: create file metadata under ChatGPT, upload bytes to the signed
+URL, then finalize the upload.
+
+```python
+uploaded = client.files.upload("report.csv")
+print(uploaded.uri)  # sediment://file_...
+```
+
 ### Observed But Not Exposed
 
 The reverse-engineering notes in `docs/backend-api.md` include additional
 observed endpoints. They are not exposed as SDK resources yet because they are
 plan-gated, unavailable on `chatgpt.com`, or not stable enough:
 
-- `POST /backend-api/codex/memories/trace_summarize`
-- `GET /backend-api/wham/config/requirements`
 - `POST /v1/audio/speech` (auth reaches the endpoint, but Pro OAuth lacks
   `api.model.audio.request` in current tests)

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

@@ -158,17 +158,20 @@ resources (`responses`, `models`, `realtime`) or Codex-only resources (`codex`).
 |---|---|---|
 | `POST /backend-api/codex/responses` | `client.responses.create(...)` | Stream-only backend; non-streaming SDK calls are collected from SSE events. |
 | `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. |
 | `wss://api.openai.com/v1/realtime?model=...` | `client.realtime_websocket_url(...)` / `client.realtime_websocket_headers(...)` | Helper surface used by codex-agent's realtime plugin. |
 | `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`. |
 | `GET /backend-api/wham/usage` | `client.codex.usage()` | Codex/ChatGPT quota and rate-limit status. |
+| `GET /backend-api/wham/config/requirements` | `client.codex.config.requirements()` | Raw managed requirements/config payload for the authenticated account. |
 | `GET /backend-api/wham/tasks/list` | `client.codex.tasks.list(...)` | Raw Codex cloud task listing. |
 | `GET /backend-api/wham/tasks/{task_id}` | `client.codex.tasks.retrieve(task_id)` | Raw Codex cloud task detail. |
 | `GET /backend-api/wham/tasks/{task_id}/turns` | `client.codex.tasks.turns.list(task_id)` | Raw task turn mapping. |
 | `GET /backend-api/wham/tasks/{task_id}/turns/{turn_id}/sibling_turns` | `client.codex.tasks.turns.sibling_turns(task_id, turn_id)` | Raw sibling turn list. |
 | `GET /backend-api/wham/environments` | `client.codex.environments.list()` | Raw Codex cloud environment list. |
+| `POST /backend-api/files` + signed upload | `client.files.upload(...)` | Uploads local files for Codex Apps/MCP file parameters and returns `sediment://...` metadata. |
 | `GET /backend-api/memories` | `client.codex.memories.list()` | Raw ChatGPT memory payload for the authenticated account. |
 | `GET /backend-api/user_system_messages` | `client.codex.user_system_messages.retrieve()` | Raw ChatGPT customization/system-message payload. |
 
@@ -241,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,
@@ -377,18 +381,52 @@ not part of the official OpenAI SDK.
 ```python
 memories = client.codex.memories.list()
 customization = client.codex.user_system_messages.retrieve()
+requirements = client.codex.config.requirements()
 ```
 
-Both methods return raw backend dictionaries because these payloads can contain
+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 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=[
+        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
+file parameters: create file metadata under ChatGPT, upload bytes to the signed
+URL, then finalize the upload.
+
+```python
+uploaded = client.files.upload("report.csv")
+print(uploaded.uri)  # sediment://file_...
+```
+
 ### Observed But Not Exposed
 
 The reverse-engineering notes in `docs/backend-api.md` include additional
 observed endpoints. They are not exposed as SDK resources yet because they are
 plan-gated, unavailable on `chatgpt.com`, or not stable enough:
 
-- `POST /backend-api/codex/memories/trace_summarize`
-- `GET /backend-api/wham/config/requirements`
 - `POST /v1/audio/speech` (auth reaches the endpoint, but Pro OAuth lacks
   `api.model.audio.request` in current tests)

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

@@ -17,7 +17,7 @@ Quickstart:
     print(response.output_text)
 """
 
-__version__ = "0.3.0"
+__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,
@@ -41,6 +45,7 @@ from .codex_client import (
     SyncPage,
     CompactedResponse,
     Transcription,
+    UploadedFile,
     image_url,
     image_b64,
 )
@@ -53,7 +58,11 @@ __all__ = [
     "CreateEmbeddingResponse",
     "Embedding",
     "EmbeddingUsage",
+    "MemorySummarizeOutput",
+    "MemorySummarizeResponse",
     "Model",
+    "RawMemory",
+    "RawMemoryMetadata",
     "Response",
     "ResponseStreamEvent",
     "ResponseUsage",
@@ -61,6 +70,7 @@ __all__ = [
     "SyncPage",
     "CompactedResponse",
     "Transcription",
+    "UploadedFile",
     "ReasoningEffort",
     "ReasoningSummary",
     "ServiceTier",

{codex_backend_sdk-0.3.0 → 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,15 +33,20 @@ 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
         from .resources.openai_oauth import Audio, Embeddings
+        from .resources.files import Files
         from .resources.realtime import Realtime
         from .resources.responses import Responses
 
         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,
@@ -53,6 +59,7 @@ class CodexClient:
         self.realtime = Realtime(self)
         self.embeddings = Embeddings(self)
         self.audio = Audio(self)
+        self.files = Files(self)
         self.codex = CodexResources(self)
 
     def authenticate(self, *, request_api_key: bool = True) -> "CodexClient":
@@ -119,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,
@@ -140,6 +163,7 @@ class CodexClient:
         self,
         path: str,
         *,
+        body: Optional[dict[str, Any]] = None,
         content: Optional[bytes] = None,
         files: Any = None,
         data: Any = None,
@@ -148,9 +172,11 @@ class CodexClient:
         timeout: Any = _UNSET,
     ) -> requests.Response:
         self._ensure_auth()
-        response = self._session.post(
+        response = self._request_with_retries(
+            "POST",
             f"{BASE_URL}{path}",
-            data=content if files is None else data,
+            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,
             files=files,
             headers=headers,
             params=params,
@@ -174,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()
@@ -196,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,
@@ -205,22 +234,75 @@ 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(
+        self,
+        path: str,
+        *,
+        body: dict[str, Any],
+        timeout: Any = _UNSET,
+    ) -> dict[str, Any]:
+        self._ensure_auth()
+        response = self._request_with_retries(
+            "POST",
+            f"{CHATGPT_BASE_URL}{path}",
+            json=body,
+            timeout=self._timeout if not _is_given(timeout) else timeout,
+        )
         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:
@@ -242,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.0 → codex_backend_sdk-0.3.2}/codex_backend_sdk/_models.py

@@ -173,6 +173,35 @@ 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
+    download_url: str
+    file_name: str
+    file_size_bytes: int
+    mime_type: Optional[str] = None
+    path: str
+
+
 class CompactedResponse(CodexBaseModel):
     id: str
     object: str = "response.compacted"

{codex_backend_sdk-0.3.0 → 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,
@@ -24,6 +28,7 @@ from ._models import (
     SyncPage,
     TokenDetails,
     Transcription,
+    UploadedFile,
     Verbosity,
 )
 from ._utils import CodexBackendUnsupportedParameterError, image_b64, image_url
@@ -36,8 +41,12 @@ __all__ = [
     "Embedding",
     "EmbeddingUsage",
     "CompactedResponse",
+    "MemorySummarizeOutput",
+    "MemorySummarizeResponse",
     "Model",
     "OpenAI",
+    "RawMemory",
+    "RawMemoryMetadata",
     "ReasoningEffort",
     "ReasoningSummary",
     "Response",
@@ -48,6 +57,7 @@ __all__ = [
     "SyncPage",
     "TokenDetails",
     "Transcription",
+    "UploadedFile",
     "Verbosity",
     "image_b64",
     "image_url",

{codex_backend_sdk-0.3.0 → 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
 
@@ -16,6 +19,7 @@ class CodexResources:
         self.memories = CodexMemories(client)
         self.tasks = CodexTasks(client)
         self.environments = CodexEnvironments(client)
+        self.config = CodexConfig(client)
         self.user_system_messages = CodexUserSystemMessages(client)
 
     def usage(self) -> dict[str, Any]:
@@ -31,6 +35,32 @@ class CodexMemories:
     def list(self) -> dict[str, Any]:
         return self._client._get_chatgpt("/memories")
 
+    def trace_summarize(
+        self,
+        *,
+        model: str,
+        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": _jsonable(traces)}
+        if reasoning is not None:
+            payload["reasoning"] = _jsonable(reasoning)
+        return MemorySummarizeResponse.model_validate(
+            self._client._post("/memories/trace_summarize", body=payload).json()
+        )
+
+
+class CodexConfig:
+    """Codex WHAM account configuration resources."""
+
+    def __init__(self, client: CodexClient) -> None:
+        self._client = client
+
+    def requirements(self) -> dict[str, Any]:
+        return self._client._get_wham("/wham/config/requirements")
+
 
 class CodexTasks:
     """Codex cloud task data for the authenticated account."""