codex-python-sdk 0.1.0__tar.gz

codex_python_sdk-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Henry_spdcoding
+
+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.

codex_python_sdk-0.1.0/PKG-INFO

@@ -0,0 +1,274 @@
+Metadata-Version: 2.4
+Name: codex-python-sdk
+Version: 0.1.0
+Summary: Python wrapper for Codex app-server JSON-RPC interface
+Author: Henry_spdcoding
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/spdcoding/codex-python-sdk
+Project-URL: Repository, https://github.com/spdcoding/codex-python-sdk
+Project-URL: Issues, https://github.com/spdcoding/codex-python-sdk/issues
+Project-URL: Documentation, https://github.com/spdcoding/codex-python-sdk/blob/HEAD/docs/tutorial.md
+Project-URL: Codex-App-Server, https://developers.openai.com/codex/app-server/
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Requires-Python: <4.0,>=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Provides-Extra: test
+Requires-Dist: pytest>=8.2; extra == "test"
+Requires-Dist: pytest-timeout; extra == "test"
+Requires-Dist: rich; extra == "test"
+Provides-Extra: build
+Requires-Dist: setuptools>=61; extra == "build"
+Requires-Dist: wheel; extra == "build"
+Requires-Dist: build; extra == "build"
+Requires-Dist: twine; extra == "build"
+Dynamic: license-file
+
+# codex-python-sdk
+
+[GitHub](https://github.com/spdcoding/codex-python-sdk) | [English](./README.md) | [简体中文](./README.zh-CN.md) | [Docs](./docs)
+
+Production-focused Python SDK for running Codex agents through `codex app-server`.
+
+`codex-python-sdk` gives you a stable Python interface over Codex JSON-RPC so you can automate agent workflows, stream structured runtime events, and enforce runtime policy from your own applications.
+
+## Why This SDK
+
+- Script-first API: built for automation pipelines, not only interactive CLI sessions.
+- Sync + async parity: same mental model and similar method names in both clients.
+- Structured streaming: consume normalized `ResponseEvent` objects for observability and UI.
+- Predictable failures: explicit error types such as `NotAuthenticatedError` and `SessionNotFoundError`.
+- Policy control: approval/file-change/tool-input/tool-call hooks and policy engine integration.
+- Thin protocol wrapper: close to `codex app-server` behavior, easier to reason about and debug.
+
+## 30-Second Quick Start
+
+```python
+from codex_python_sdk import create_client
+
+with create_client() as client:
+    result = client.responses_create(prompt="Reply with exactly: READY")
+    print(result.session_id)
+    print(result.text)
+```
+
+## Core Workflows
+
+### Stream events (for logs/UI)
+
+```python
+from codex_python_sdk import create_client, render_exec_style_events
+
+with create_client() as client:
+    events = client.responses_events(prompt="Summarize this repository")
+    render_exec_style_events(events)
+```
+
+### Async flow
+
+```python
+import asyncio
+from codex_python_sdk import create_async_client
+
+
+async def main() -> None:
+    async with create_async_client() as client:
+        result = await client.responses_create(prompt="Reply with exactly: ASYNC_READY")
+        print(result.text)
+
+
+asyncio.run(main())
+```
+
+### Smoke and demo runner
+
+```bash
+# Quick health check (default mode)
+codex-python-sdk-demo --mode smoke
+
+# Stable API showcase
+codex-python-sdk-demo --mode demo
+
+# Demo + unstable remote/interrupt/compact paths
+codex-python-sdk-demo --mode full
+```
+
+Note: the demo runner uses permissive hooks (`accept` for command/file approvals and empty tool-input answers) so it can run unattended.
+Use stricter hooks or policy engines in production.
+
+## Mental Model: How It Works
+
+`codex app-server` is Codex CLI's local JSON-RPC runtime over stdio.
+
+One `responses_create(prompt=...)` call is essentially:
+
+1. `create_client()` creates a sync facade (`CodexAgenticClient`).
+2. Sync call forwards to `AsyncCodexAgenticClient` via a dedicated event-loop thread.
+3. `connect()` starts `codex app-server` and performs `initialize/initialized`.
+4. `_request(method, params)` handles all JSON-RPC request/response plumbing.
+5. `responses_events()` streams notifications; `responses_create()` aggregates them into final text.
+
+For a deeper walkthrough, see `docs/core_mechanism.md`.
+
+## Safety Defaults (Important)
+
+Default behavior without hooks/policy:
+- Command approval: `accept`
+- File change approval: `accept`
+- Tool user input: empty answers
+- Tool call: failure response with explanatory text
+
+This is convenient for unattended demos, but not production-safe.
+
+Recommended safer setup: enable LLM-judge policy with strict fallback decisions.
+
+```python
+from codex_python_sdk import PolicyJudgeConfig, create_client
+
+rubric = {
+    "system_rubric": "Allow read-only operations. Decline unknown write operations.",
+    "use_llm_judge": True,
+}
+
+judge_cfg = PolicyJudgeConfig(
+    timeout_seconds=8.0,
+    model="gpt-5",
+    effort="low",
+    fallback_command_decision="decline",
+    fallback_file_change_decision="decline",
+)
+
+with create_client(
+    policy_rubric=rubric,
+    policy_judge_config=judge_cfg,
+) as client:
+    result = client.responses_create(prompt="Show git status.")
+    print(result.text)
+```
+
+Note: LLM-judge requires a real Codex runtime/account; for deterministic local tests, use `RuleBasedPolicyEngine`.
+
+## Install
+
+### Prerequisites
+
+- Python `3.9+` (recommended: `3.12`)
+- `uv` (recommended for development workflows)
+- `codex` CLI installed and runnable
+- Authentication completed via `codex login`
+
+### Install from PyPI
+
+```bash
+uv add codex-python-sdk
+uv run codex-python-sdk-demo --help
+```
+
+or
+
+```bash
+pip install codex-python-sdk
+codex-python-sdk-demo --help
+```
+
+### Developer setup (for contributors)
+
+```bash
+./uv-sync.sh
+```
+
+This bootstraps a local `.venv` and installs project/test/build dependencies.
+
+## API Snapshot
+
+Factory:
+- `create_client(**kwargs) -> CodexAgenticClient`
+- `create_async_client(**kwargs) -> AsyncCodexAgenticClient`
+
+High-frequency response APIs:
+- `responses_create(...) -> AgentResponse`
+- `responses_events(...) -> Iterator[ResponseEvent] / AsyncIterator[ResponseEvent]`
+- `responses_stream_text(...) -> Iterator[str] / AsyncIterator[str]`
+
+Thread basics:
+- `thread_start`, `thread_read`, `thread_list`, `thread_archive`
+
+Account basics:
+- `account_read`, `account_rate_limits_read`
+
+## Documentation Map
+
+English:
+- `docs/tutorial.md`: practical workflows and end-to-end usage
+- `docs/core_mechanism.md`: architecture-level core control flow
+- `docs/config.md`: server/thread/turn configuration model
+- `docs/api.md`: full API reference (sync + async)
+- `docs/policy.md`: hooks and policy engine integration
+- `docs/app_server.md`: app-server concepts and protocol mapping
+
+简体中文:
+- `docs/zh/tutorial.md`
+- `docs/zh/core_mechanism.md`
+- `docs/zh/config.md`
+- `docs/zh/api.md`
+- `docs/zh/policy.md`
+- `docs/zh/app_server.md`
+
+## Notes
+
+- After `AppServerConnectionError`, recreate the client instead of relying on implicit reconnect behavior.
+- Internal app-server `stderr` buffering keeps only the latest 500 lines in SDK-captured diagnostics.
+- When using low-level server request handlers, method names must be exactly `item`, `tool`, or `requestUserInput`.
+- Policy LLM-judge parsing is strict JSON-only: judge output must be a pure JSON object; embedded JSON snippets in free text are rejected.
+- Invalid command/file policy decision values (allowed: `accept`, `acceptForSession`, `decline`, `cancel`) raise `CodexAgenticError`.
+
+## Development
+
+```bash
+./uv-sync.sh
+uv run python3 -m pytest -q -m "not real"
+```
+
+## Release
+
+```bash
+# Default: test + build + twine check (no upload)
+./build.sh
+
+# Build only
+./build.sh build
+
+# Release to pypi (upload enabled explicitly)
+TWINE_UPLOAD=1 ./build.sh release --repo pypi
+
+# Release to testpypi
+TWINE_UPLOAD=1 ./build.sh release --repo testpypi
+
+# Upload existing artifacts only
+./build.sh upload --repo pypi
+
+# Help
+./build.sh help
+```
+
+Recommended upload auth: `~/.pypirc` with API token.
+
+## Project Layout
+
+- `codex_python_sdk/`: SDK source code
+- `codex_python_sdk/examples/`: runnable demo code
+- `tests/`: unit and real-runtime integration tests
+- `uv-sync.sh`: dev environment bootstrap
+- `build.sh`: build/release script
+
+## Error Types
+
+- `CodexAgenticError`: base SDK error
+- `AppServerConnectionError`: app-server transport/setup failure
+- `SessionNotFoundError`: unknown thread/session id
+- `NotAuthenticatedError`: auth unavailable or invalid

codex_python_sdk-0.1.0/README.md

@@ -0,0 +1,243 @@
+# codex-python-sdk
+
+[GitHub](https://github.com/spdcoding/codex-python-sdk) | [English](./README.md) | [简体中文](./README.zh-CN.md) | [Docs](./docs)
+
+Production-focused Python SDK for running Codex agents through `codex app-server`.
+
+`codex-python-sdk` gives you a stable Python interface over Codex JSON-RPC so you can automate agent workflows, stream structured runtime events, and enforce runtime policy from your own applications.
+
+## Why This SDK
+
+- Script-first API: built for automation pipelines, not only interactive CLI sessions.
+- Sync + async parity: same mental model and similar method names in both clients.
+- Structured streaming: consume normalized `ResponseEvent` objects for observability and UI.
+- Predictable failures: explicit error types such as `NotAuthenticatedError` and `SessionNotFoundError`.
+- Policy control: approval/file-change/tool-input/tool-call hooks and policy engine integration.
+- Thin protocol wrapper: close to `codex app-server` behavior, easier to reason about and debug.
+
+## 30-Second Quick Start
+
+```python
+from codex_python_sdk import create_client
+
+with create_client() as client:
+    result = client.responses_create(prompt="Reply with exactly: READY")
+    print(result.session_id)
+    print(result.text)
+```
+
+## Core Workflows
+
+### Stream events (for logs/UI)
+
+```python
+from codex_python_sdk import create_client, render_exec_style_events
+
+with create_client() as client:
+    events = client.responses_events(prompt="Summarize this repository")
+    render_exec_style_events(events)
+```
+
+### Async flow
+
+```python
+import asyncio
+from codex_python_sdk import create_async_client
+
+
+async def main() -> None:
+    async with create_async_client() as client:
+        result = await client.responses_create(prompt="Reply with exactly: ASYNC_READY")
+        print(result.text)
+
+
+asyncio.run(main())
+```
+
+### Smoke and demo runner
+
+```bash
+# Quick health check (default mode)
+codex-python-sdk-demo --mode smoke
+
+# Stable API showcase
+codex-python-sdk-demo --mode demo
+
+# Demo + unstable remote/interrupt/compact paths
+codex-python-sdk-demo --mode full
+```
+
+Note: the demo runner uses permissive hooks (`accept` for command/file approvals and empty tool-input answers) so it can run unattended.
+Use stricter hooks or policy engines in production.
+
+## Mental Model: How It Works
+
+`codex app-server` is Codex CLI's local JSON-RPC runtime over stdio.
+
+One `responses_create(prompt=...)` call is essentially:
+
+1. `create_client()` creates a sync facade (`CodexAgenticClient`).
+2. Sync call forwards to `AsyncCodexAgenticClient` via a dedicated event-loop thread.
+3. `connect()` starts `codex app-server` and performs `initialize/initialized`.
+4. `_request(method, params)` handles all JSON-RPC request/response plumbing.
+5. `responses_events()` streams notifications; `responses_create()` aggregates them into final text.
+
+For a deeper walkthrough, see `docs/core_mechanism.md`.
+
+## Safety Defaults (Important)
+
+Default behavior without hooks/policy:
+- Command approval: `accept`
+- File change approval: `accept`
+- Tool user input: empty answers
+- Tool call: failure response with explanatory text
+
+This is convenient for unattended demos, but not production-safe.
+
+Recommended safer setup: enable LLM-judge policy with strict fallback decisions.
+
+```python
+from codex_python_sdk import PolicyJudgeConfig, create_client
+
+rubric = {
+    "system_rubric": "Allow read-only operations. Decline unknown write operations.",
+    "use_llm_judge": True,
+}
+
+judge_cfg = PolicyJudgeConfig(
+    timeout_seconds=8.0,
+    model="gpt-5",
+    effort="low",
+    fallback_command_decision="decline",
+    fallback_file_change_decision="decline",
+)
+
+with create_client(
+    policy_rubric=rubric,
+    policy_judge_config=judge_cfg,
+) as client:
+    result = client.responses_create(prompt="Show git status.")
+    print(result.text)
+```
+
+Note: LLM-judge requires a real Codex runtime/account; for deterministic local tests, use `RuleBasedPolicyEngine`.
+
+## Install
+
+### Prerequisites
+
+- Python `3.9+` (recommended: `3.12`)
+- `uv` (recommended for development workflows)
+- `codex` CLI installed and runnable
+- Authentication completed via `codex login`
+
+### Install from PyPI
+
+```bash
+uv add codex-python-sdk
+uv run codex-python-sdk-demo --help
+```
+
+or
+
+```bash
+pip install codex-python-sdk
+codex-python-sdk-demo --help
+```
+
+### Developer setup (for contributors)
+
+```bash
+./uv-sync.sh
+```
+
+This bootstraps a local `.venv` and installs project/test/build dependencies.
+
+## API Snapshot
+
+Factory:
+- `create_client(**kwargs) -> CodexAgenticClient`
+- `create_async_client(**kwargs) -> AsyncCodexAgenticClient`
+
+High-frequency response APIs:
+- `responses_create(...) -> AgentResponse`
+- `responses_events(...) -> Iterator[ResponseEvent] / AsyncIterator[ResponseEvent]`
+- `responses_stream_text(...) -> Iterator[str] / AsyncIterator[str]`
+
+Thread basics:
+- `thread_start`, `thread_read`, `thread_list`, `thread_archive`
+
+Account basics:
+- `account_read`, `account_rate_limits_read`
+
+## Documentation Map
+
+English:
+- `docs/tutorial.md`: practical workflows and end-to-end usage
+- `docs/core_mechanism.md`: architecture-level core control flow
+- `docs/config.md`: server/thread/turn configuration model
+- `docs/api.md`: full API reference (sync + async)
+- `docs/policy.md`: hooks and policy engine integration
+- `docs/app_server.md`: app-server concepts and protocol mapping
+
+简体中文:
+- `docs/zh/tutorial.md`
+- `docs/zh/core_mechanism.md`
+- `docs/zh/config.md`
+- `docs/zh/api.md`
+- `docs/zh/policy.md`
+- `docs/zh/app_server.md`
+
+## Notes
+
+- After `AppServerConnectionError`, recreate the client instead of relying on implicit reconnect behavior.
+- Internal app-server `stderr` buffering keeps only the latest 500 lines in SDK-captured diagnostics.
+- When using low-level server request handlers, method names must be exactly `item`, `tool`, or `requestUserInput`.
+- Policy LLM-judge parsing is strict JSON-only: judge output must be a pure JSON object; embedded JSON snippets in free text are rejected.
+- Invalid command/file policy decision values (allowed: `accept`, `acceptForSession`, `decline`, `cancel`) raise `CodexAgenticError`.
+
+## Development
+
+```bash
+./uv-sync.sh
+uv run python3 -m pytest -q -m "not real"
+```
+
+## Release
+
+```bash
+# Default: test + build + twine check (no upload)
+./build.sh
+
+# Build only
+./build.sh build
+
+# Release to pypi (upload enabled explicitly)
+TWINE_UPLOAD=1 ./build.sh release --repo pypi
+
+# Release to testpypi
+TWINE_UPLOAD=1 ./build.sh release --repo testpypi
+
+# Upload existing artifacts only
+./build.sh upload --repo pypi
+
+# Help
+./build.sh help
+```
+
+Recommended upload auth: `~/.pypirc` with API token.
+
+## Project Layout
+
+- `codex_python_sdk/`: SDK source code
+- `codex_python_sdk/examples/`: runnable demo code
+- `tests/`: unit and real-runtime integration tests
+- `uv-sync.sh`: dev environment bootstrap
+- `build.sh`: build/release script
+
+## Error Types
+
+- `CodexAgenticError`: base SDK error
+- `AppServerConnectionError`: app-server transport/setup failure
+- `SessionNotFoundError`: unknown thread/session id
+- `NotAuthenticatedError`: auth unavailable or invalid

codex_python_sdk-0.1.0/codex_python_sdk/__init__.py

@@ -0,0 +1,57 @@
+from __future__ import annotations
+
+import asyncio as asyncio
+
+from .async_client import (
+    DEFAULT_APP_SERVER_ARGS,
+    DEFAULT_CLI_COMMAND,
+    AsyncCodexAgenticClient,
+)
+from .errors import (
+    AppServerConnectionError,
+    CodexAgenticError,
+    NotAuthenticatedError,
+    SessionNotFoundError,
+)
+from .factory import create_async_client, create_client
+from .policy import (
+    DEFAULT_POLICY_RUBRIC,
+    DefaultPolicyEngine,
+    LlmRubricPolicyEngine,
+    PolicyContext,
+    PolicyEngine,
+    PolicyJudgeConfig,
+    PolicyRubric,
+    RuleBasedPolicyEngine,
+    build_policy_engine_from_rubric,
+)
+from .renderer import ExecStyleRenderer, render_exec_style_events
+from .sync_client import CodexAgenticClient
+from .types import AgentResponse, ResponseEvent
+
+__all__ = [
+    "AgentResponse",
+    "AppServerConnectionError",
+    "AsyncCodexAgenticClient",
+    "CodexAgenticClient",
+    "CodexAgenticError",
+    "DEFAULT_APP_SERVER_ARGS",
+    "DEFAULT_CLI_COMMAND",
+    "ExecStyleRenderer",
+    "DEFAULT_POLICY_RUBRIC",
+    "DefaultPolicyEngine",
+    "LlmRubricPolicyEngine",
+    "NotAuthenticatedError",
+    "PolicyContext",
+    "PolicyEngine",
+    "PolicyJudgeConfig",
+    "PolicyRubric",
+    "ResponseEvent",
+    "RuleBasedPolicyEngine",
+    "SessionNotFoundError",
+    "asyncio",
+    "build_policy_engine_from_rubric",
+    "create_async_client",
+    "create_client",
+    "render_exec_style_events",
+]

codex_python_sdk-0.1.0/codex_python_sdk/_shared.py

@@ -0,0 +1,99 @@
+from __future__ import annotations
+
+from datetime import datetime, timezone
+from typing import Any
+
+
+def utc_now() -> str:
+    return datetime.now(tz=timezone.utc).isoformat()
+
+
+def first_nonempty_text(value: Any) -> str | None:
+    if isinstance(value, str):
+        text = value.strip()
+        return text or None
+    if isinstance(value, list):
+        out: list[str] = []
+        for item in value:
+            text = first_nonempty_text(item)
+            if text:
+                out.append(text)
+        if out:
+            return "\n".join(out)
+        return None
+    if isinstance(value, dict):
+        for key in ("message", "text", "delta", "error", "content"):
+            if key in value:
+                text = first_nonempty_text(value.get(key))
+                if text:
+                    return text
+        for nested in value.values():
+            if isinstance(nested, (dict, list)):
+                text = first_nonempty_text(nested)
+                if text:
+                    return text
+    return None
+
+
+def token_usage_total_tokens(value: Any) -> int | None:
+    if not isinstance(value, dict):
+        return None
+    total = value.get("totalTokens")
+    if isinstance(total, int):
+        return total
+    total = value.get("total_tokens")
+    if isinstance(total, int):
+        return total
+    return None
+
+
+def token_usage_summary(token_usage: dict[str, Any]) -> str | None:
+    last = token_usage.get("last")
+    total = token_usage.get("total")
+    last_total = token_usage_total_tokens(last)
+    total_total = token_usage_total_tokens(total)
+    if last_total is None and total_total is None:
+        return None
+    if last_total is None:
+        return f"total={total_total}"
+    if total_total is None:
+        return f"last={last_total}"
+    return f"last={last_total}, total={total_total}"
+
+
+def diff_change_counts(diff: str) -> tuple[int, int]:
+    added = 0
+    removed = 0
+    for line in diff.splitlines():
+        if line.startswith("+++") or line.startswith("---"):
+            continue
+        if line.startswith("+"):
+            added += 1
+        elif line.startswith("-"):
+            removed += 1
+    return added, removed
+
+
+def turn_plan_summary(params: dict[str, Any]) -> str | None:
+    plan = params.get("plan")
+    if not isinstance(plan, list):
+        return first_nonempty_text(params.get("explanation"))
+
+    status_counts: dict[str, int] = {}
+    for item in plan:
+        if not isinstance(item, dict):
+            continue
+        status = item.get("status")
+        if isinstance(status, str):
+            status_counts[status] = status_counts.get(status, 0) + 1
+
+    parts: list[str] = []
+    explanation = params.get("explanation")
+    if isinstance(explanation, str) and explanation.strip():
+        parts.append(explanation.strip())
+    parts.append(f"steps={len(plan)}")
+    for status in ("inProgress", "pending", "completed"):
+        if status in status_counts:
+            parts.append(f"{status}={status_counts[status]}")
+    return ", ".join(parts)
+