gpt-codex-client 0.1.0__tar.gz

gpt_codex_client-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,27 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.10", "3.11", "3.12", "3.13", "3.14"]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v5
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+      - run: uv sync --all-extras --dev
+      - run: uv run ruff format --check
+      - run: uv run ruff check src tests
+      - run: uv run mypy src/gpt_codex_client tests --strict
+      - run: uv run pytest -q
+      - run: uv build
+

gpt_codex_client-0.1.0/.github/workflows/release.yml

@@ -0,0 +1,38 @@
+name: Release
+
+on:
+  push:
+    tags:
+      - "v*"
+
+permissions:
+  contents: write
+  id-token: write
+  pages: write
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v5
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.13"
+      - run: uv sync --all-extras --dev
+      - run: uv run ruff format --check
+      - run: uv run ruff check src tests
+      - run: uv run mypy src/gpt_codex_client tests --strict
+      - run: uv run pytest -q
+      - name: Check tag matches package version
+        run: |
+          VERSION=$(uv run python -c "import gpt_codex_client; print(gpt_codex_client.__version__)")
+          test "v${VERSION}" = "${GITHUB_REF_NAME}"
+      - run: uv build
+      - uses: pypa/gh-action-pypi-publish@release/v1
+      - uses: softprops/action-gh-release@v2
+        with:
+          files: dist/*
+          generate_release_notes: true
+      - run: uv run mkdocs gh-deploy --force
+

gpt_codex_client-0.1.0/.gitignore

@@ -0,0 +1,14 @@
+.DS_Store
+.idea/
+.ruff_cache/
+.mypy_cache/
+.pytest_cache/
+.venv/
+dist/
+build/
+*.egg-info/
+__pycache__/
+*.py[cod]
+site/
+.coverage
+htmlcov/

gpt_codex_client-0.1.0/AGENTS.md

@@ -0,0 +1,18 @@
+# AGENTS.md
+
+This repository is a typed Python package using a `src/` layout and `uv`.
+
+## Local Checks
+
+Run these before publishing:
+
+```bash
+uv run ruff format --check
+uv run ruff check src tests
+uv run mypy src/gpt_codex_client tests --strict
+uv run pytest -q
+uv build
+```
+
+Default tests must not call live OAuth or ChatGPT/Codex endpoints. Use `httpx.MockTransport` for integration-style coverage.
+

gpt_codex_client-0.1.0/CHANGELOG.md

@@ -0,0 +1,8 @@
+# Changelog
+
+## 0.1.0
+
+- Initial package scaffold.
+- Added OAuth PKCE token lifecycle helpers.
+- Added sync and async Codex clients with Responses, chat compatibility, models, and SSE streaming.
+

gpt_codex_client-0.1.0/LICENSE

@@ -0,0 +1,22 @@
+MIT License
+
+Copyright (c) 2026 gpt-codex-client contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+

gpt_codex_client-0.1.0/PKG-INFO

@@ -0,0 +1,164 @@
+Metadata-Version: 2.4
+Name: gpt-codex-client
+Version: 0.1.0
+Summary: OpenAI SDK-style Python client for ChatGPT/Codex OAuth-backed Responses workflows.
+Project-URL: Homepage, https://github.com/HC-Zhou/gpt-codex-client
+Project-URL: Documentation, https://hc-zhou.github.io/gpt-codex-client/
+Project-URL: Issues, https://github.com/HC-Zhou/gpt-codex-client/issues
+Author: gpt-codex-client contributors
+License-Expression: MIT
+License-File: LICENSE
+Keywords: chatgpt,codex,openai,responses,sdk
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Requires-Dist: httpx<1,>=0.27
+Provides-Extra: pydantic
+Requires-Dist: pydantic>=2; extra == 'pydantic'
+Description-Content-Type: text/markdown
+
+# gpt-codex-client
+
+English | [简体中文](README.zh-CN.md)
+
+`gpt-codex-client` is an OpenAI SDK-style Python client for ChatGPT/Codex
+OAuth-backed workflows. It is intentionally not an API-key client for
+`api.openai.com`; it uses a local token cache compatible with
+`~/.codex/auth.json` and requires an account that can access the relevant
+ChatGPT/Codex backend.
+
+```bash
+uv add gpt-codex-client
+```
+
+```python
+from gpt_codex_client import CodexClient
+
+with CodexClient(no_browser=True) as client:
+    response = client.responses.create(
+        model="gpt-5.5",
+        input="Write a short Python function that reverses a string.",
+    )
+    print(response.output_text)
+```
+
+## List Models
+
+`client.models.list()` reads the public OpenAI Codex model registry from the
+`openai/codex` GitHub repository instead of the ChatGPT/Codex backend `/models`
+endpoint.
+
+```python
+from gpt_codex_client import CodexClient
+
+with CodexClient() as client:
+    models = client.models.list()
+    for model in models:
+        print(model.id)
+```
+
+The registry source is:
+
+```text
+https://raw.githubusercontent.com/openai/codex/main/codex-rs/models-manager/models.json
+```
+
+Set `GPT_CODEX_CLIENT_MODELS_MANIFEST_URL` or pass `models_manifest_url=` to
+use another compatible registry.
+
+## Authentication
+
+The client lazily authenticates on the first request. By default it reads and
+writes `~/.codex/auth.json` with `0600` permissions.
+
+```python
+from gpt_codex_client import login
+
+login(no_browser=True)
+```
+
+The default OAuth client id follows the ChatGPT/Codex sign-in flow used by the
+official Codex clients. If OpenAI issues a different client id for your app, set
+`GPT_CODEX_CLIENT_OAUTH_CLIENT_ID` or pass `auth_client_id=` to `CodexClient`.
+
+For automation, pass a `login_handler` that receives the authorization URL and
+returns the final redirect URL:
+
+```python
+from gpt_codex_client import login
+
+token = login(login_handler=lambda url: input(f"Open {url}\nRedirect URL: "))
+```
+
+## Responses
+
+```python
+with CodexClient() as client:
+    response = client.responses.create(
+        model="gpt-5.5",
+        input="Summarize this repository.",
+        reasoning={"effort": "medium"},
+        text={"verbosity": "low"},
+    )
+```
+
+Streaming returns a context manager and iterator:
+
+```python
+with CodexClient() as client:
+    with client.responses.create(model="gpt-5.5", input="Say hi", stream=True) as stream:
+        for event in stream:
+            if event.type == "response.output_text.delta":
+                print(event.data.get("delta"), end="")
+```
+
+## Structured Output
+
+Install the optional extra when using Pydantic models:
+
+```bash
+uv add "gpt-codex-client[pydantic]"
+```
+
+```python
+from pydantic import BaseModel
+from gpt_codex_client import CodexClient
+
+class Result(BaseModel):
+    title: str
+
+parsed = CodexClient().responses.parse(
+    model="gpt-5.5",
+    input="Return JSON with a title.",
+    text_format=Result,
+)
+print(parsed.parsed.title)
+```
+
+## Chat Compatibility
+
+The chat compatibility layer converts Chat Completions-style messages and
+function tools into Responses requests:
+
+```python
+completion = CodexClient().chat.completions.create(
+    model="gpt-5.5",
+    messages=[{"role": "user", "content": "Hello"}],
+)
+print(completion.choices[0].message.content)
+```
+
+## Development
+
+```bash
+uv sync --all-extras --dev
+uv run pytest -q
+```

gpt_codex_client-0.1.0/README.md

@@ -0,0 +1,137 @@
+# gpt-codex-client
+
+English | [简体中文](README.zh-CN.md)
+
+`gpt-codex-client` is an OpenAI SDK-style Python client for ChatGPT/Codex
+OAuth-backed workflows. It is intentionally not an API-key client for
+`api.openai.com`; it uses a local token cache compatible with
+`~/.codex/auth.json` and requires an account that can access the relevant
+ChatGPT/Codex backend.
+
+```bash
+uv add gpt-codex-client
+```
+
+```python
+from gpt_codex_client import CodexClient
+
+with CodexClient(no_browser=True) as client:
+    response = client.responses.create(
+        model="gpt-5.5",
+        input="Write a short Python function that reverses a string.",
+    )
+    print(response.output_text)
+```
+
+## List Models
+
+`client.models.list()` reads the public OpenAI Codex model registry from the
+`openai/codex` GitHub repository instead of the ChatGPT/Codex backend `/models`
+endpoint.
+
+```python
+from gpt_codex_client import CodexClient
+
+with CodexClient() as client:
+    models = client.models.list()
+    for model in models:
+        print(model.id)
+```
+
+The registry source is:
+
+```text
+https://raw.githubusercontent.com/openai/codex/main/codex-rs/models-manager/models.json
+```
+
+Set `GPT_CODEX_CLIENT_MODELS_MANIFEST_URL` or pass `models_manifest_url=` to
+use another compatible registry.
+
+## Authentication
+
+The client lazily authenticates on the first request. By default it reads and
+writes `~/.codex/auth.json` with `0600` permissions.
+
+```python
+from gpt_codex_client import login
+
+login(no_browser=True)
+```
+
+The default OAuth client id follows the ChatGPT/Codex sign-in flow used by the
+official Codex clients. If OpenAI issues a different client id for your app, set
+`GPT_CODEX_CLIENT_OAUTH_CLIENT_ID` or pass `auth_client_id=` to `CodexClient`.
+
+For automation, pass a `login_handler` that receives the authorization URL and
+returns the final redirect URL:
+
+```python
+from gpt_codex_client import login
+
+token = login(login_handler=lambda url: input(f"Open {url}\nRedirect URL: "))
+```
+
+## Responses
+
+```python
+with CodexClient() as client:
+    response = client.responses.create(
+        model="gpt-5.5",
+        input="Summarize this repository.",
+        reasoning={"effort": "medium"},
+        text={"verbosity": "low"},
+    )
+```
+
+Streaming returns a context manager and iterator:
+
+```python
+with CodexClient() as client:
+    with client.responses.create(model="gpt-5.5", input="Say hi", stream=True) as stream:
+        for event in stream:
+            if event.type == "response.output_text.delta":
+                print(event.data.get("delta"), end="")
+```
+
+## Structured Output
+
+Install the optional extra when using Pydantic models:
+
+```bash
+uv add "gpt-codex-client[pydantic]"
+```
+
+```python
+from pydantic import BaseModel
+from gpt_codex_client import CodexClient
+
+class Result(BaseModel):
+    title: str
+
+parsed = CodexClient().responses.parse(
+    model="gpt-5.5",
+    input="Return JSON with a title.",
+    text_format=Result,
+)
+print(parsed.parsed.title)
+```
+
+## Chat Compatibility
+
+The chat compatibility layer converts Chat Completions-style messages and
+function tools into Responses requests:
+
+```python
+completion = CodexClient().chat.completions.create(
+    model="gpt-5.5",
+    messages=[{"role": "user", "content": "Hello"}],
+)
+print(completion.choices[0].message.content)
+```
+
+## Development
+
+```bash
+uv sync --all-extras --dev
+uv run pytest -q
+```

gpt_codex_client-0.1.0/README.zh-CN.md

@@ -0,0 +1,135 @@
+# gpt-codex-client
+
+[English](README.md) | 简体中文
+
+`gpt-codex-client` 是一个 OpenAI SDK 风格的 Python 客户端，用于
+ChatGPT/Codex OAuth 登录支持的工作流。它不是面向 `api.openai.com` 的
+API Key 客户端；它读取和写入兼容 `~/.codex/auth.json` 的本地 token 缓存，
+并要求账号具备对应 ChatGPT/Codex 后端访问权限。
+
+```bash
+uv add gpt-codex-client
+```
+
+```python
+from gpt_codex_client import CodexClient
+
+with CodexClient(no_browser=True) as client:
+    response = client.responses.create(
+        model="gpt-5.5",
+        input="Write a short Python function that reverses a string.",
+    )
+    print(response.output_text)
+```
+
+## 获取模型列表
+
+`client.models.list()` 会读取 OpenAI Codex 仓库中的公开模型注册表，
+而不是调用 ChatGPT/Codex 后端的 `/models` 接口。
+
+```python
+from gpt_codex_client import CodexClient
+
+with CodexClient() as client:
+    models = client.models.list()
+    for model in models:
+        print(model.id)
+```
+
+模型注册表来源：
+
+```text
+https://raw.githubusercontent.com/openai/codex/main/codex-rs/models-manager/models.json
+```
+
+如果需要使用其他兼容的注册表，可以设置
+`GPT_CODEX_CLIENT_MODELS_MANIFEST_URL`，或在构造客户端时传入
+`models_manifest_url=`。
+
+## 认证
+
+客户端会在首次请求时懒加载认证。默认读取并写入 `~/.codex/auth.json`，
+保存权限为 `0600`。
+
+```python
+from gpt_codex_client import login
+
+login(no_browser=True)
+```
+
+默认 OAuth client id 与官方 Codex 客户端使用的 ChatGPT/Codex 登录流程一致。
+如果你有自己的已注册 client id，可以设置 `GPT_CODEX_CLIENT_OAUTH_CLIENT_ID`，
+或在构造 `CodexClient` 时传入 `auth_client_id=`。
+
+自动化场景可以传入 `login_handler`，它会收到授权 URL，并返回最终 redirect URL：
+
+```python
+from gpt_codex_client import login
+
+token = login(login_handler=lambda url: input(f"Open {url}\nRedirect URL: "))
+```
+
+## Responses
+
+```python
+with CodexClient() as client:
+    response = client.responses.create(
+        model="gpt-5.5",
+        input="Summarize this repository.",
+        reasoning={"effort": "medium"},
+        text={"verbosity": "low"},
+    )
+```
+
+流式调用会返回 context manager 和 iterator：
+
+```python
+with CodexClient() as client:
+    with client.responses.create(model="gpt-5.5", input="Say hi", stream=True) as stream:
+        for event in stream:
+            if event.type == "response.output_text.delta":
+                print(event.data.get("delta"), end="")
+```
+
+## 结构化输出
+
+使用 Pydantic 模型时安装可选 extra：
+
+```bash
+uv add "gpt-codex-client[pydantic]"
+```
+
+```python
+from pydantic import BaseModel
+from gpt_codex_client import CodexClient
+
+class Result(BaseModel):
+    title: str
+
+parsed = CodexClient().responses.parse(
+    model="gpt-5.5",
+    input="Return JSON with a title.",
+    text_format=Result,
+)
+print(parsed.parsed.title)
+```
+
+## Chat 兼容层
+
+Chat 兼容层会把 Chat Completions 风格的 messages 和 function tools
+转换为 Responses 请求：
+
+```python
+completion = CodexClient().chat.completions.create(
+    model="gpt-5.5",
+    messages=[{"role": "user", "content": "Hello"}],
+)
+print(completion.choices[0].message.content)
+```
+
+## 开发
+
+```bash
+uv sync --all-extras --dev
+uv run pytest -q
+```

gpt_codex_client-0.1.0/docs/authentication.md

@@ -0,0 +1,31 @@
+# Authentication
+
+The default token cache is `~/.codex/auth.json`. Tokens are saved with `0600`
+permissions.
+
+```python
+from gpt_codex_client import login
+
+login(no_browser=True)
+```
+
+Automation can provide a handler:
+
+```python
+login(login_handler=lambda url: input(f"Open {url}\nRedirect URL: "))
+```
+
+`finish_login()` validates OAuth `state` before exchanging an authorization
+code. `get_token()` returns a cached token, refreshes expired tokens when a
+refresh token exists, and falls back to login if refresh fails.
+
+The default OAuth client id follows the ChatGPT/Codex sign-in flow used by the
+official Codex clients. Override it only when you have a registered client id:
+
+```bash
+export GPT_CODEX_CLIENT_OAUTH_CLIENT_ID="app_..."
+```
+
+```python
+client = CodexClient(auth_client_id="app_...")
+```

gpt_codex_client-0.1.0/docs/chat-compatibility.md

@@ -0,0 +1,18 @@
+# Chat Compatibility
+
+The chat layer accepts Chat Completions-style messages and function tools and
+converts them into a Responses request.
+
+```python
+completion = client.chat.completions.create(
+    model="model",
+    messages=[
+        {"role": "system", "content": "Be concise."},
+        {"role": "user", "content": "Hello"},
+    ],
+)
+print(completion.choices[0].message.content)
+```
+
+System and developer messages are folded into `instructions`.
+

gpt_codex_client-0.1.0/docs/errors.md

@@ -0,0 +1,15 @@
+# Errors
+
+All package exceptions derive from `CodexError`.
+
+- `AuthError`: OAuth, token cache, 401, or 403 failures.
+- `InvalidRequestError`: non-retryable 4xx request failures.
+- `RateLimitError`: 429 responses, including `retry_after`.
+- `ServerError`: 5xx responses.
+- `APITimeoutError`: request timeout.
+- `APIConnectionError`: transport-level failures.
+- `StreamError`: stream lifecycle failures.
+
+429 and 5xx responses are retried with exponential backoff up to
+`max_retries`.
+

gpt_codex_client-0.1.0/docs/index.md

@@ -0,0 +1,18 @@
+# Getting Started
+
+`gpt-codex-client` provides a typed Python client with an OpenAI SDK-style
+surface:
+
+```python
+from gpt_codex_client import CodexClient
+
+client = CodexClient()
+response = client.responses.create(
+    model="gpt-5.5",
+    input="Write a compact project summary.",
+)
+print(response.output_text)
+```
+
+This package targets ChatGPT/Codex OAuth-backed backend behavior, not standard
+API-key access to `api.openai.com`.

gpt_codex_client-0.1.0/docs/models.md

@@ -0,0 +1,22 @@
+# Models
+
+```python
+models = client.models.list()
+for model in models:
+    print(model.id)
+```
+
+The list is read from the OpenAI Codex model registry:
+
+```text
+https://raw.githubusercontent.com/openai/codex/main/codex-rs/models-manager/models.json
+```
+
+The result is cached in memory for five minutes. Pass `force_refresh=True` to
+fetch it again. Set `GPT_CODEX_CLIENT_MODELS_MANIFEST_URL` to point at another
+compatible registry during tests or if the upstream location changes. You can
+also pass `models_manifest_url=` when constructing a client:
+
+```python
+client = CodexClient(models_manifest_url="https://example.test/models.json")
+```

gpt_codex_client-0.1.0/docs/release.md

@@ -0,0 +1,16 @@
+# Release
+
+1. Update `CHANGELOG.md`.
+2. Ensure `src/gpt_codex_client/__init__.py` and `pyproject.toml` versions match.
+3. Run:
+
+```bash
+uv run ruff format --check
+uv run ruff check src tests
+uv run mypy src/gpt_codex_client tests --strict
+uv run pytest -q
+uv build
+```
+
+4. Tag `vX.Y.Z` and push the tag.
+