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

codex_backend_sdk-0.3.4/CHANGELOG.md

@@ -0,0 +1,13 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+## [0.3.4] - 2026-05-15
+
+### Added
+- Added `authenticate(interactive=False)` to allow non-interactive credential checks without triggering the browser OAuth flow.
+- Added `client.authenticated` for simple auth-state introspection.
+- Added `client.account_info()` to expose safe non-secret account metadata (`authenticated`, `account_id`, `email`, `plan_type`).
+
+### Documentation
+- Documented the non-interactive authentication helpers in `README.md`.

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: codex-backend-sdk
-Version: 0.3.2
+Version: 0.3.4
 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`,
@@ -331,6 +355,14 @@ headers = client.realtime_websocket_headers(session_id="voice-session")
 `openai_api_key`. The default `authenticate(request_api_key=True)` flow stores
 that key when available.
 
+For non-interactive checks, you can avoid triggering a browser login flow:
+
+```python
+client = OpenAI().authenticate(interactive=False)
+print(client.authenticated)
+print(client.account_info())
+```
+
 ### Embeddings
 
 `client.embeddings.create(...)` mirrors the official OpenAI embeddings resource

{codex_backend_sdk-0.3.2 → codex_backend_sdk-0.3.4}/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`,
@@ -305,6 +329,14 @@ headers = client.realtime_websocket_headers(session_id="voice-session")
 `openai_api_key`. The default `authenticate(request_api_key=True)` flow stores
 that key when available.
 
+For non-interactive checks, you can avoid triggering a browser login flow:
+
+```python
+client = OpenAI().authenticate(interactive=False)
+print(client.authenticated)
+print(client.account_info())
+```
+
 ### Embeddings
 
 `client.embeddings.create(...)` mirrors the official OpenAI embeddings resource

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

@@ -17,7 +17,7 @@ Quickstart:
     print(response.output_text)
 """
 
-__version__ = "0.3.2"
+__version__ = "0.3.4"
 
 from .oauth import run_oauth_flow, refresh_access_token, obtain_api_key
 from .storage import load_tokens, save_tokens, TokenStore
@@ -38,7 +38,9 @@ from .codex_client import (
     Model,
     RawMemory,
     RawMemoryMetadata,
+    ParsedResponse,
     Response,
+    ResponseFormatJsonSchema,
     ResponseStreamEvent,
     ResponseUsage,
     RealtimeCallResponse,
@@ -61,9 +63,11 @@ __all__ = [
     "MemorySummarizeOutput",
     "MemorySummarizeResponse",
     "Model",
+    "ParsedResponse",
     "RawMemory",
     "RawMemoryMetadata",
     "Response",
+    "ResponseFormatJsonSchema",
     "ResponseStreamEvent",
     "ResponseUsage",
     "RealtimeCallResponse",

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

@@ -3,11 +3,11 @@
 from __future__ import annotations
 
 import urllib.parse
-import time
 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
 
@@ -62,7 +62,12 @@ class CodexClient:
         self.files = Files(self)
         self.codex = CodexResources(self)
 
-    def authenticate(self, *, request_api_key: bool = True) -> "CodexClient":
+    def authenticate(
+        self,
+        *,
+        request_api_key: bool = True,
+        interactive: bool = True,
+    ) -> "CodexClient":
         from .oauth import refresh_access_token, run_oauth_flow
 
         def refresh(store: TokenStore) -> Optional[TokenStore]:
@@ -87,9 +92,28 @@ class CodexClient:
                 self._set_store(store)
                 return self
 
+        if not interactive:
+            raise RuntimeError("No usable stored Codex credentials; interactive login required.")
+
         self._set_store(run_oauth_flow(request_api_key=request_api_key))
         return self
 
+    @property
+    def authenticated(self) -> bool:
+        """Whether this client currently has OAuth credentials loaded."""
+        return bool(self._store and self._store.account_id)
+
+    def account_info(self) -> dict[str, Any]:
+        """Return safe non-secret account metadata decoded from stored tokens."""
+        store = self._store
+        authenticated = bool(store and store.account_id)
+        return {
+            "authenticated": authenticated,
+            "account_id": store.account_id if store else None,
+            "email": store.email if store else None,
+            "plan_type": store.plan_type if store else None,
+        }
+
     def _set_store(self, store: TokenStore) -> None:
         self._store = store
         self._session.headers.update(self._auth_headers())
@@ -271,37 +295,16 @@ class CodexClient:
         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)
+        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."""
@@ -324,12 +327,3 @@ 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.2 → codex_backend_sdk-0.3.4}/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

codex_backend_sdk-0.3.4/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.2 → codex_backend_sdk-0.3.4}/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.2 → codex_backend_sdk-0.3.4}/codex_backend_sdk/codex_client.py

@@ -16,12 +16,14 @@ from ._models import (
     Model,
     MemorySummarizeOutput,
     MemorySummarizeResponse,
+    ParsedResponse,
     RawMemory,
     RawMemoryMetadata,
     ReasoningEffort,
     ReasoningSummary,
     RealtimeCallResponse,
     Response,
+    ResponseFormatJsonSchema,
     ResponseStreamEvent,
     ResponseUsage,
     ServiceTier,
@@ -45,11 +47,13 @@ __all__ = [
     "MemorySummarizeResponse",
     "Model",
     "OpenAI",
+    "ParsedResponse",
     "RawMemory",
     "RawMemoryMetadata",
     "ReasoningEffort",
     "ReasoningSummary",
     "Response",
+    "ResponseFormatJsonSchema",
     "ResponseStreamEvent",
     "ResponseUsage",
     "RealtimeCallResponse",