codex-backend-sdk 0.5.6__tar.gz → 0.5.7__tar.gz

{codex_backend_sdk-0.5.6 → codex_backend_sdk-0.5.7}/CHANGELOG.md

@@ -2,6 +2,15 @@
 
 All notable changes to this project will be documented in this file.
 
+## [0.5.7] - 2026-10-22
+
+### Fixed
+- Discover the latest stable Codex CLI version over credential-free HTTPS for
+  model catalogs instead of sending a stale fixed version that can hide models.
+  Share a 24-hour process cache, retain a verified fallback on registry failure,
+  and allow an explicit `extra_query` version without registry access.
+- Keep catalogs fetched with custom request options out of the default cache.
+
 ## [0.5.6] - 2026-10-22
 
 ### Fixed

{codex_backend_sdk-0.5.6 → codex_backend_sdk-0.5.7}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: codex-backend-sdk
-Version: 0.5.6
+Version: 0.5.7
 Summary: Unofficial Python SDK for the ChatGPT Codex backend API
 License: MIT
 License-File: LICENSE
@@ -278,6 +278,24 @@ for model in client.models.list():
 model = client.models.retrieve("gpt-5.5")
 ```
 
+Model discovery obtains the latest stable Codex CLI version over HTTPS from the
+public npm registry; Node, npm and the Codex binary are not required. The version
+is cached for 24 hours per process, shared across clients. The lookup uses a
+separate request without backend credentials and a three-second timeout. On
+failure it keeps the last known version (or a bundled verified fallback) and
+retries no sooner than five minutes later. This only updates the advertised
+catalog version, not the SDK's implementation of backend features.
+
+To pin the catalog version and skip registry access entirely:
+
+```python
+models = client.models.list(extra_query={"client_version": "0.159.2"})
+```
+
+`force_refresh=True` bypasses the five-minute model catalog cache, not the
+24-hour version cache. Requests with explicit options do not replace the default
+catalog cache. Other protocol and application version fields are independent.
+
 ### Upload a file
 
 ```python

{codex_backend_sdk-0.5.6 → codex_backend_sdk-0.5.7}/README.md

@@ -249,6 +249,24 @@ for model in client.models.list():
 model = client.models.retrieve("gpt-5.5")
 ```
 
+Model discovery obtains the latest stable Codex CLI version over HTTPS from the
+public npm registry; Node, npm and the Codex binary are not required. The version
+is cached for 24 hours per process, shared across clients. The lookup uses a
+separate request without backend credentials and a three-second timeout. On
+failure it keeps the last known version (or a bundled verified fallback) and
+retries no sooner than five minutes later. This only updates the advertised
+catalog version, not the SDK's implementation of backend features.
+
+To pin the catalog version and skip registry access entirely:
+
+```python
+models = client.models.list(extra_query={"client_version": "0.159.2"})
+```
+
+`force_refresh=True` bypasses the five-minute model catalog cache, not the
+24-hour version cache. Requests with explicit options do not replace the default
+catalog cache. Other protocol and application version fields are independent.
+
 ### Upload a file
 
 ```python

{codex_backend_sdk-0.5.6 → codex_backend_sdk-0.5.7}/codex_backend_sdk/__init__.py

@@ -17,7 +17,7 @@ Quickstart:
     print(response.output_text)
 """
 
-__version__ = "0.5.6"
+__version__ = "0.5.7"
 
 from .oauth import (
     DeviceCode,

codex_backend_sdk-0.5.7/codex_backend_sdk/_codex_version.py

@@ -0,0 +1,45 @@
+"""Shared discovery of the upstream Codex CLI version (not the SDK version)."""
+
+import re
+import threading
+import time
+
+import requests
+
+
+# Last verified upstream protocol version, used when discovery is unavailable.
+CLIENT_VERSION = "0.163.0"
+_RETRY_TTL = 300
+_VERSION_TTL = 24 * 60 * 60
+_VERSION_URL = "https://registry.npmjs.org/@openai/codex/latest"
+_version = CLIENT_VERSION
+_version_refresh_at = 0.0
+_version_lock = threading.Lock()
+
+
+def codex_client_version() -> str:
+    """Discover the stable CLI version without sharing backend credentials.
+
+    Cache across clients in this process. Failed refreshes retain the last known
+    version and wait five minutes before retrying, including on first use.
+    """
+    global _version, _version_refresh_at
+    with _version_lock:
+        if time.monotonic() < _version_refresh_at:
+            return _version
+        ttl = _VERSION_TTL
+        try:
+            with requests.get(_VERSION_URL, timeout=3) as response:
+                response.raise_for_status()
+                payload = response.json()
+            candidate = payload.get("version") if isinstance(payload, dict) else None
+            if not isinstance(candidate, str) or not re.fullmatch(
+                r"[0-9]+\.[0-9]+\.[0-9]+", candidate
+            ):
+                raise ValueError("Invalid stable Codex version")
+            _version = candidate
+        except (requests.RequestException, ValueError):
+            ttl = _RETRY_TTL
+        _version_refresh_at = time.monotonic() + ttl
+        return _version
+

{codex_backend_sdk-0.5.6 → codex_backend_sdk-0.5.7}/codex_backend_sdk/resources/models.py

@@ -5,18 +5,15 @@ from __future__ import annotations
 import time
 from typing import Any, TYPE_CHECKING
 
+from .._codex_version import codex_client_version
 from .._models import Model, SyncPage
 from .._utils import _UNSET, CodexBackendUnsupportedParameterError, _is_given
 
 if TYPE_CHECKING:
     from .._client import CodexClient
 
-# This is the upstream Codex CLI protocol/client version expected by the
-# ChatGPT backend, not the PyPI package version.
-CLIENT_VERSION = "0.130.0"
 _CACHE_TTL = 300
 
-
 class Models:
     def __init__(self, client: CodexClient) -> None:
         self._client = client
@@ -41,7 +38,9 @@ class Models:
             if time.time() - self._cache_fetched_at <= _CACHE_TTL:
                 return self._cache
 
-        params = {"client_version": CLIENT_VERSION, **(extra_query or {})}
+        params = dict(extra_query or {})
+        if "client_version" not in params:
+            params["client_version"] = codex_client_version()
         response = self._client._get_raw(
             "/models", params=params, headers=extra_headers, timeout=timeout
         )
@@ -49,8 +48,9 @@ class Models:
         models = [_model_from_backend(item) for item in data.get("models", [])]
         models.sort(key=lambda model: getattr(model, "priority", 0))
         page = SyncPage(data=models, etag=response.headers.get("ETag"))
-        self._cache = page
-        self._cache_fetched_at = time.time()
+        if not has_request_options:
+            self._cache = page
+            self._cache_fetched_at = time.time()
         return page
 
     def retrieve(

{codex_backend_sdk-0.5.6 → codex_backend_sdk-0.5.7}/docs/api-reference.md

@@ -175,7 +175,7 @@ concurrent, turns. Backend error envelopes raise `ResponsesWebSocketError` with
 
 | Method | Parameters | Returns |
 | --- | --- | --- |
-| `client.models.list(...)` | `force_refresh=False`, `extra_headers=None`, `extra_query=None`, `extra_body=None`, `timeout=UNSET` | iterable `SyncPage` with optional `etag`; cached for 5 minutes |
+| `client.models.list(...)` | `force_refresh=False`, `extra_headers=None`, `extra_query=None`, `extra_body=None`, `timeout=UNSET` | iterable `SyncPage` with optional `etag`; default catalog cached for 5 minutes; Codex version auto-discovered over HTTPS (24-hour process cache), or pinned via `extra_query["client_version"]` |
 | `client.models.retrieve(...)` | `model`, plus the same transport controls | one typed `Model`; raises `LookupError` if absent |
 
 `Model` preserves Codex fields including display metadata, context window,

{codex_backend_sdk-0.5.6 → codex_backend_sdk-0.5.7}/docs/backend-api.md

@@ -78,7 +78,11 @@ List models available to this account.
 **SDK method**: `client.models.list()` / `client.models.retrieve(model)`
 
 **Query params**
-- `client_version` — Codex CLI protocol/client version string (e.g. `"0.130.0"`).
+- `client_version` — Codex CLI version string. The SDK discovers the latest stable
+  version from the public npm registry over HTTPS (24-hour in-process cache;
+  three-second timeout; last-known/bundled fallback with five-minute retry
+  backoff). Override with `extra_query={"client_version": "0.159.2"}` to skip
+  discovery. No Node/npm installation is required.
 
 **Response** — JSON `{ "models": [ ModelObject, … ] }`
 

{codex_backend_sdk-0.5.6 → codex_backend_sdk-0.5.7}/pyproject.toml

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

codex_backend_sdk-0.5.7/tests/test_codex_version.py

@@ -0,0 +1,88 @@
+"""Offline tests for upstream version discovery; no OAuth or npm binary."""
+
+from concurrent.futures import ThreadPoolExecutor
+from unittest.mock import MagicMock
+
+import pytest
+import requests
+
+from codex_backend_sdk import _codex_version as version
+
+
+@pytest.fixture
+def registry(monkeypatch):
+    clock = [100.0]
+    monkeypatch.setattr(version.time, "monotonic", lambda: clock[0])
+    monkeypatch.setattr(version, "_version", version.CLIENT_VERSION)
+    monkeypatch.setattr(version, "_version_refresh_at", 0.0)
+    response = MagicMock()
+    response.__enter__.return_value = response
+    response.json.return_value = {"version": "0.170.0"}
+    get = MagicMock(return_value=response)
+    monkeypatch.setattr(version.requests, "get", get)
+    return clock, get, response
+
+
+def test_version_uses_standalone_https_and_caches_for_24_hours(registry):
+    clock, get, response = registry
+    assert version.codex_client_version() == "0.170.0"
+    get.assert_called_once_with(version._VERSION_URL, timeout=3)
+    response.raise_for_status.assert_called_once()
+    response.__exit__.assert_called_once()
+    clock[0] += 86400 - 1
+    assert version.codex_client_version() == "0.170.0"
+    assert get.call_count == 1
+    clock[0] += 1
+    response.json.return_value = {"version": "0.171.0"}
+    assert version.codex_client_version() == "0.171.0"
+    assert get.call_count == 2
+
+
+@pytest.mark.parametrize("error", [requests.Timeout(), requests.HTTPError(), ValueError()])
+def test_first_failure_uses_verified_fallback_and_backs_off(registry, error):
+    clock, get, _ = registry
+    get.side_effect = error
+    assert version.codex_client_version() == version.CLIENT_VERSION
+    assert version.codex_client_version() == version.CLIENT_VERSION
+    assert get.call_count == 1
+    clock[0] += 300
+    get.side_effect = None
+    assert version.codex_client_version() == "0.170.0"
+    assert get.call_count == 2
+
+
+
+@pytest.mark.parametrize("stage", ["raise_for_status", "json"])
+def test_response_errors_close_request_and_use_fallback(registry, stage):
+    _, _, response = registry
+    error = requests.HTTPError() if stage == "raise_for_status" else ValueError()
+    getattr(response, stage).side_effect = error
+    assert version.codex_client_version() == version.CLIENT_VERSION
+    response.__exit__.assert_called_once()
+
+
+def test_refresh_failure_keeps_last_success(registry):
+    clock, get, _ = registry
+    assert version.codex_client_version() == "0.170.0"
+    clock[0] += 86400
+    get.side_effect = requests.ConnectionError()
+    assert version.codex_client_version() == "0.170.0"
+    assert version.codex_client_version() == "0.170.0"
+    assert get.call_count == 2
+
+
+@pytest.mark.parametrize("payload", [
+    None, [], {}, {"version": 123}, {"version": "0.170.0-beta.1"},
+    {"version": "garbage"}, {"version": "0.170.0\n"},
+])
+def test_invalid_registry_metadata_uses_fallback(registry, payload):
+    _, _, response = registry
+    response.json.return_value = payload
+    assert version.codex_client_version() == version.CLIENT_VERSION
+
+
+def test_concurrent_clients_share_one_lookup(registry):
+    _, get, _ = registry
+    with ThreadPoolExecutor(max_workers=8) as pool:
+        assert list(pool.map(lambda _: version.codex_client_version(), range(16))) == ["0.170.0"] * 16
+    assert get.call_count == 1

{codex_backend_sdk-0.5.6 → codex_backend_sdk-0.5.7}/tests/test_responses_resource.py

@@ -5,6 +5,12 @@ import pytest
 from pydantic import BaseModel
 
 from codex_backend_sdk import OpenAI, ParsedResponse, Response
+from codex_backend_sdk.resources import models as models_resource
+
+
+@pytest.fixture(autouse=True)
+def stable_catalog_version(monkeypatch):
+    monkeypatch.setattr(models_resource, "codex_client_version", lambda: "0.163.0")
 
 
 class FakeSSE:
@@ -363,12 +369,33 @@ def test_models_resource_forwards_official_request_options():
 
     assert client.gets[1] == (
         "/models",
-        {"client_version": "0.130.0", "preview": "1"},
+        {"client_version": "0.163.0", "preview": "1"},
         {"x-test": "header"},
         19,
     )
 
 
+
+def test_explicit_catalog_version_skips_discovery_and_does_not_replace_default_cache(monkeypatch):
+    client = FakeClient()
+    default = client.models.list()
+    def unexpected_lookup():
+        raise AssertionError("Explicit version must not contact registry")
+    monkeypatch.setattr(models_resource, "codex_client_version", unexpected_lookup)
+    custom = client.models.list(extra_query={"client_version": "0.159.2"})
+    assert custom is not default
+    assert client.gets[-1][1] == {"client_version": "0.159.2"}
+    assert client.models.list() is default
+
+
+def test_forced_catalog_refresh_resolves_version_again(monkeypatch):
+    client = FakeClient()
+    client.models.list()
+    monkeypatch.setattr(models_resource, "codex_client_version", lambda: "0.171.0")
+    client.models.list(force_refresh=True)
+    assert client.gets[-1][1] == {"client_version": "0.171.0"}
+
+
 def test_responses_compact_sends_shared_request_fields():
     client = FakeClient()
 

{codex_backend_sdk-0.5.6 → codex_backend_sdk-0.5.7}/uv.lock

@@ -162,7 +162,7 @@ wheels = [
 
 [[package]]
 name = "codex-backend-sdk"
-version = "0.5.6"
+version = "0.5.7"
 source = { editable = "." }
 dependencies = [
     { name = "pydantic" },