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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: codex-backend-sdk
-Version: 0.3.1
+Version: 0.3.3
 Summary: Unofficial Python SDK for the ChatGPT Codex backend API
 License: MIT
 License-File: LICENSE
@@ -240,6 +240,30 @@ response = client.responses.create(
 )
 ```
 
+For structured output, `client.responses.parse(...)` accepts a Pydantic model,
+sends it as a strict JSON schema, and returns `ParsedResponse`:
+
+```python
+from pydantic import BaseModel
+
+
+class Person(BaseModel):
+    name: str
+    age: int
+
+
+parsed = client.responses.parse(
+    model="gpt-5.4",
+    input="Extract: Ada is 37 years old.",
+    text_format=Person,
+)
+print(parsed.output_parsed.name)
+```
+
+Collected responses expose convenience properties for common output items:
+`response.output_text`, `response.reasoning_summary`, and
+`response.tool_calls`.
+
 Unsupported official Responses parameters are rejected explicitly with
 `CodexBackendUnsupportedParameterError`, including `temperature`, `top_p`,
 `max_output_tokens`, `metadata`, `user`, `safety_identifier`, `truncation`,
@@ -270,10 +294,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 +438,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.3}/README.md

@@ -214,6 +214,30 @@ response = client.responses.create(
 )
 ```
 
+For structured output, `client.responses.parse(...)` accepts a Pydantic model,
+sends it as a strict JSON schema, and returns `ParsedResponse`:
+
+```python
+from pydantic import BaseModel
+
+
+class Person(BaseModel):
+    name: str
+    age: int
+
+
+parsed = client.responses.parse(
+    model="gpt-5.4",
+    input="Extract: Ada is 37 years old.",
+    text_format=Person,
+)
+print(parsed.output_parsed.name)
+```
+
+Collected responses expose convenience properties for common output items:
+`response.output_text`, `response.reasoning_summary`, and
+`response.tool_calls`.
+
 Unsupported official Responses parameters are rejected explicitly with
 `CodexBackendUnsupportedParameterError`, including `temperature`, `top_p`,
 `max_output_tokens`, `metadata`, `user`, `safety_identifier`, `truncation`,
@@ -244,10 +268,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 +412,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.3}/codex_backend_sdk/__init__.py

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

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

@@ -7,6 +7,7 @@ from typing import Any, Optional
 
 import requests
 
+from ._transport import request_with_retries
 from ._utils import _UNSET, _is_given
 from .storage import TokenStore, load_tokens, save_tokens, token_needs_refresh
 
@@ -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,26 @@ 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:
+        use_session = kwargs.pop("_use_session", True)
+        return request_with_retries(
+            self._session,
+            method,
+            url,
+            max_retries=self._max_retries,
+            retry_base_delay=self._retry_base_delay,
+            use_session=use_session,
+            **kwargs,
+        )
+
     def realtime_websocket_url(self, *, model: str) -> str:
         """Return the official OpenAI Realtime WebSocket URL for Codex plugins."""
         if not model:

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

@@ -4,7 +4,7 @@ from __future__ import annotations
 
 import time
 from collections.abc import Iterator
-from typing import Any, Literal, Optional
+from typing import Any, Generic, Literal, Optional, TypeVar
 
 import requests
 from pydantic import BaseModel, ConfigDict, Field
@@ -13,6 +13,7 @@ ReasoningEffort = Literal["minimal", "low", "medium", "high", "xhigh"]
 ReasoningSummary = Literal["concise", "detailed", "auto"]
 Verbosity = Literal["low", "medium", "high"]
 ServiceTier = Literal["flex", "priority"]
+ParsedT = TypeVar("ParsedT")
 
 
 class CodexBaseModel(BaseModel):
@@ -73,6 +74,14 @@ class ResponseUsage(CodexBaseModel):
     output_tokens_details: TokenDetails = Field(default_factory=TokenDetails)
 
 
+class ResponseFormatJsonSchema(CodexBaseModel):
+    type: Literal["json_schema"] = "json_schema"
+    name: str
+    schema_: dict[str, Any] = Field(alias="schema")
+    strict: Optional[bool] = None
+    description: Optional[str] = None
+
+
 class Response(CodexBaseModel):
     id: str
     created_at: float = Field(default_factory=time.time)
@@ -117,6 +126,49 @@ class Response(CodexBaseModel):
                         texts.append(content.get("text", ""))
         return "".join(texts)
 
+    @property
+    def reasoning_summary(self) -> str | None:
+        texts: list[str] = []
+        for output in self.output:
+            if output.get("type") == "reasoning":
+                for summary in output.get("summary", []):
+                    if isinstance(summary, dict):
+                        texts.append(summary.get("text", ""))
+        return "\n".join(text for text in texts if text) or None
+
+    @property
+    def tool_calls(self) -> list[dict[str, Any]]:
+        return [output for output in self.output if output.get("type") == "function_call"]
+
+
+class ParsedResponse(CodexBaseModel, Generic[ParsedT]):
+    response: Response
+    output_parsed: ParsedT
+
+    @property
+    def id(self) -> str:
+        return self.response.id
+
+    @property
+    def model(self) -> Optional[str]:
+        return self.response.model
+
+    @property
+    def output(self) -> list[dict[str, Any]]:
+        return self.response.output
+
+    @property
+    def output_text(self) -> str:
+        return self.response.output_text
+
+    @property
+    def status(self) -> Optional[str]:
+        return self.response.status
+
+    @property
+    def usage(self) -> Optional[ResponseUsage]:
+        return self.response.usage
+
 
 class ResponseStreamEvent(CodexBaseModel):
     type: str
@@ -173,6 +225,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.3/codex_backend_sdk/_transport.py

@@ -0,0 +1,71 @@
+"""HTTP transport helpers shared by client resources."""
+
+from __future__ import annotations
+
+import time
+from typing import Any
+
+import requests
+
+
+def request_with_retries(
+    session: requests.Session,
+    method: str,
+    url: str,
+    *,
+    max_retries: int,
+    retry_base_delay: float,
+    use_session: bool = True,
+    **kwargs: Any,
+) -> requests.Response:
+    last_error: requests.RequestException | None = None
+    for attempt in range(max_retries + 1):
+        try:
+            request = session.request if use_session else requests.request
+            response = request(method, url, **kwargs)
+            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()
+            return response
+        except (requests.Timeout, requests.ConnectionError) as exc:
+            last_error = exc
+            if attempt >= max_retries:
+                raise
+            sleep_before_retry(None, attempt, retry_base_delay=retry_base_delay)
+    if last_error is not None:
+        raise last_error
+    raise RuntimeError("Request retry loop exhausted")
+
+
+def should_retry_response(
+    response: requests.Response,
+    attempt: int,
+    *,
+    max_retries: int,
+) -> bool:
+    if attempt >= max_retries:
+        return False
+    return response.status_code == 429 or 500 <= response.status_code < 600
+
+
+def sleep_before_retry(
+    response: requests.Response | None,
+    attempt: int,
+    *,
+    retry_base_delay: float,
+) -> 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 = retry_base_delay * (2 ** attempt)
+    time.sleep(delay)
+
+
+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.3}/codex_backend_sdk/_utils.py

@@ -4,6 +4,7 @@ from __future__ import annotations
 
 import base64
 import json
+from dataclasses import asdict, is_dataclass
 from typing import Any
 
 from pydantic import BaseModel
@@ -26,6 +27,8 @@ def image_b64(data: str, media_type: str = "image/jpeg") -> dict[str, str]:
 def _jsonable(value: Any) -> Any:
     if isinstance(value, BaseModel):
         return value.model_dump(mode="json", by_alias=True, exclude_unset=True)
+    if is_dataclass(value) and not isinstance(value, type):
+        return _jsonable(asdict(value))
     if isinstance(value, dict):
         return {key: _jsonable(item) for key, item in value.items()}
     if isinstance(value, list):

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

@@ -14,10 +14,16 @@ from ._models import (
     Embedding,
     EmbeddingUsage,
     Model,
+    MemorySummarizeOutput,
+    MemorySummarizeResponse,
+    ParsedResponse,
+    RawMemory,
+    RawMemoryMetadata,
     ReasoningEffort,
     ReasoningSummary,
     RealtimeCallResponse,
     Response,
+    ResponseFormatJsonSchema,
     ResponseStreamEvent,
     ResponseUsage,
     ServiceTier,
@@ -37,11 +43,17 @@ __all__ = [
     "Embedding",
     "EmbeddingUsage",
     "CompactedResponse",
+    "MemorySummarizeOutput",
+    "MemorySummarizeResponse",
     "Model",
     "OpenAI",
+    "ParsedResponse",
+    "RawMemory",
+    "RawMemoryMetadata",
     "ReasoningEffort",
     "ReasoningSummary",
     "Response",
+    "ResponseFormatJsonSchema",
     "ResponseStreamEvent",
     "ResponseUsage",
     "RealtimeCallResponse",