circle-codex 0.154.1__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -0,0 +1,148 @@
1
+ Metadata-Version: 2.4
2
+ Name: circle-codex
3
+ Version: 0.154.1
4
+ Summary: Unofficial Codex Python SDK fork with a built-in xAI provider
5
+ Keywords: codex,sdk,llm,ai,agents,xai,grok
6
+ Author: Ashish Verma
7
+ License-Expression: Apache-2.0
8
+ Classifier: Development Status :: 5 - Production/Stable
9
+ Classifier: Intended Audience :: Developers
10
+ Classifier: Topic :: Software Development :: Libraries :: Python Modules
11
+ Requires-Dist: pydantic>=2.12
12
+ Requires-Dist: packaging>=26.2
13
+ Requires-Dist: circle-codex-cli-bin==0.154.1
14
+ Requires-Python: >=3.10
15
+ Project-URL: Homepage, https://github.com/ashish447344/codex
16
+ Project-URL: Repository, https://github.com/ashish447344/codex
17
+ Project-URL: Issues, https://github.com/ashish447344/codex/issues
18
+ Project-URL: Documentation, https://github.com/ashish447344/codex/tree/main/sdk/python/docs
19
+ Description-Content-Type: text/markdown
20
+
21
+ # circle-codex
22
+
23
+ Unofficial fork of the OpenAI Codex Python SDK. It bundles a Codex CLI build
24
+ that adds a built-in xAI (Grok) model provider.
25
+
26
+ This project is not affiliated with, endorsed by, or supported by OpenAI or
27
+ xAI. It is built from <https://github.com/ashish447344/codex>, a fork of
28
+ <https://github.com/openai/codex>.
29
+
30
+ Build Python applications that start Codex threads, run turns, stream progress,
31
+ and control workspace access.
32
+
33
+ ## Install
34
+
35
+ Install the SDK:
36
+
37
+ ```bash
38
+ pip install circle-codex
39
+ ```
40
+
41
+ The SDK runs the Codex CLI through its runtime package, `circle-codex-cli-bin`,
42
+ which pip installs automatically. That package is small: the first time your
43
+ code starts Codex, it downloads the runtime for your platform (about 150-200 MB)
44
+ from the project's GitHub Release, checks its SHA-256 checksum and caches it in
45
+ `~/Library/Caches/circle-codex` (macOS) or `~/.cache/circle-codex` (Linux).
46
+ Later starts use the cached copy.
47
+
48
+ Supported platforms: macOS (Apple silicon and Intel) and Linux (x86_64 and
49
+ aarch64). Windows is not supported.
50
+
51
+ To download the runtime ahead of time, for example while building a Docker
52
+ image, run:
53
+
54
+ ```bash
55
+ python -m codex_cli_bin download
56
+ ```
57
+
58
+ Set `CIRCLE_CODEX_CACHE_DIR` to change the cache location, or
59
+ `CIRCLE_CODEX_DOWNLOAD_BASE_URL` to download from a mirror.
60
+
61
+ The import package keeps the upstream name `openai_codex`, so do not install
62
+ this package into the same environment as the official `openai-codex`.
63
+
64
+ ## Quickstart with xAI
65
+
66
+ Set `XAI_API_KEY` in your environment, then select the xAI provider:
67
+
68
+ ```python
69
+ from openai_codex import Codex, CodexConfig, Sandbox
70
+
71
+ config = CodexConfig(
72
+ config_overrides=('model_provider="xai"', 'model="grok-4.7"'),
73
+ )
74
+
75
+ with Codex(config) as codex:
76
+ thread = codex.thread_start(sandbox=Sandbox.workspace_write)
77
+ result = thread.run("Explain this repository in three bullets.")
78
+ print(result.final_response)
79
+ ```
80
+
81
+ ## Quickstart
82
+
83
+ The SDK reuses your existing Codex authentication when one is already
84
+ available:
85
+
86
+ ```python
87
+ from openai_codex import Codex
88
+
89
+ with Codex() as codex:
90
+ thread = codex.thread_start()
91
+ result = thread.run("Explain this repository in three bullets.")
92
+ print(result.final_response)
93
+ ```
94
+
95
+ `thread.run(...)` returns a `TurnResult` containing the final response,
96
+ collected items, and token usage.
97
+
98
+ ## Authentication
99
+
100
+ Existing Codex authentication is reused automatically. To start ChatGPT
101
+ browser login explicitly:
102
+
103
+ ```python
104
+ from openai_codex import Codex
105
+
106
+ with Codex() as codex:
107
+ login = codex.login_chatgpt()
108
+ print(login.auth_url)
109
+ print(login.wait().success)
110
+ ```
111
+
112
+ For device-code login:
113
+
114
+ ```python
115
+ with Codex() as codex:
116
+ login = codex.login_chatgpt_device_code()
117
+ print(login.verification_url, login.user_code)
118
+ login.wait()
119
+ ```
120
+
121
+ For API-key login:
122
+
123
+ ```python
124
+ with Codex() as codex:
125
+ codex.login_api_key("sk-...")
126
+ ```
127
+
128
+ ## Built-In Help
129
+
130
+ Use Python's standard `help(openai_codex)`, `help(Codex)`, or
131
+ `python -m pydoc openai_codex` documentation tools.
132
+
133
+ ## Documentation
134
+
135
+ The SDK API is the same as upstream, so the upstream guides apply:
136
+
137
+ - [Getting started](https://github.com/openai/codex/blob/main/sdk/python/docs/getting-started.md)
138
+ - [API reference](https://github.com/openai/codex/blob/main/sdk/python/docs/api-reference.md)
139
+ - [Untrusted external messages](https://github.com/openai/codex/blob/main/sdk/python/docs/api-reference.md#externalmessage)
140
+ - [FAQ](https://github.com/openai/codex/blob/main/sdk/python/docs/faq.md)
141
+ - [Examples](https://github.com/openai/codex/blob/main/sdk/python/examples/README.md)
142
+
143
+ Where those guides say `pip install openai-codex`, use `pip install circle-codex`.
144
+
145
+ The package is licensed under the
146
+ [Apache License 2.0](https://github.com/ashish447344/codex/blob/main/LICENSE),
147
+ the same license as upstream. See the repository
148
+ [NOTICE](https://github.com/ashish447344/codex/blob/main/NOTICE) for attribution.
@@ -0,0 +1,128 @@
1
+ # circle-codex
2
+
3
+ Unofficial fork of the OpenAI Codex Python SDK. It bundles a Codex CLI build
4
+ that adds a built-in xAI (Grok) model provider.
5
+
6
+ This project is not affiliated with, endorsed by, or supported by OpenAI or
7
+ xAI. It is built from <https://github.com/ashish447344/codex>, a fork of
8
+ <https://github.com/openai/codex>.
9
+
10
+ Build Python applications that start Codex threads, run turns, stream progress,
11
+ and control workspace access.
12
+
13
+ ## Install
14
+
15
+ Install the SDK:
16
+
17
+ ```bash
18
+ pip install circle-codex
19
+ ```
20
+
21
+ The SDK runs the Codex CLI through its runtime package, `circle-codex-cli-bin`,
22
+ which pip installs automatically. That package is small: the first time your
23
+ code starts Codex, it downloads the runtime for your platform (about 150-200 MB)
24
+ from the project's GitHub Release, checks its SHA-256 checksum and caches it in
25
+ `~/Library/Caches/circle-codex` (macOS) or `~/.cache/circle-codex` (Linux).
26
+ Later starts use the cached copy.
27
+
28
+ Supported platforms: macOS (Apple silicon and Intel) and Linux (x86_64 and
29
+ aarch64). Windows is not supported.
30
+
31
+ To download the runtime ahead of time, for example while building a Docker
32
+ image, run:
33
+
34
+ ```bash
35
+ python -m codex_cli_bin download
36
+ ```
37
+
38
+ Set `CIRCLE_CODEX_CACHE_DIR` to change the cache location, or
39
+ `CIRCLE_CODEX_DOWNLOAD_BASE_URL` to download from a mirror.
40
+
41
+ The import package keeps the upstream name `openai_codex`, so do not install
42
+ this package into the same environment as the official `openai-codex`.
43
+
44
+ ## Quickstart with xAI
45
+
46
+ Set `XAI_API_KEY` in your environment, then select the xAI provider:
47
+
48
+ ```python
49
+ from openai_codex import Codex, CodexConfig, Sandbox
50
+
51
+ config = CodexConfig(
52
+ config_overrides=('model_provider="xai"', 'model="grok-4.7"'),
53
+ )
54
+
55
+ with Codex(config) as codex:
56
+ thread = codex.thread_start(sandbox=Sandbox.workspace_write)
57
+ result = thread.run("Explain this repository in three bullets.")
58
+ print(result.final_response)
59
+ ```
60
+
61
+ ## Quickstart
62
+
63
+ The SDK reuses your existing Codex authentication when one is already
64
+ available:
65
+
66
+ ```python
67
+ from openai_codex import Codex
68
+
69
+ with Codex() as codex:
70
+ thread = codex.thread_start()
71
+ result = thread.run("Explain this repository in three bullets.")
72
+ print(result.final_response)
73
+ ```
74
+
75
+ `thread.run(...)` returns a `TurnResult` containing the final response,
76
+ collected items, and token usage.
77
+
78
+ ## Authentication
79
+
80
+ Existing Codex authentication is reused automatically. To start ChatGPT
81
+ browser login explicitly:
82
+
83
+ ```python
84
+ from openai_codex import Codex
85
+
86
+ with Codex() as codex:
87
+ login = codex.login_chatgpt()
88
+ print(login.auth_url)
89
+ print(login.wait().success)
90
+ ```
91
+
92
+ For device-code login:
93
+
94
+ ```python
95
+ with Codex() as codex:
96
+ login = codex.login_chatgpt_device_code()
97
+ print(login.verification_url, login.user_code)
98
+ login.wait()
99
+ ```
100
+
101
+ For API-key login:
102
+
103
+ ```python
104
+ with Codex() as codex:
105
+ codex.login_api_key("sk-...")
106
+ ```
107
+
108
+ ## Built-In Help
109
+
110
+ Use Python's standard `help(openai_codex)`, `help(Codex)`, or
111
+ `python -m pydoc openai_codex` documentation tools.
112
+
113
+ ## Documentation
114
+
115
+ The SDK API is the same as upstream, so the upstream guides apply:
116
+
117
+ - [Getting started](https://github.com/openai/codex/blob/main/sdk/python/docs/getting-started.md)
118
+ - [API reference](https://github.com/openai/codex/blob/main/sdk/python/docs/api-reference.md)
119
+ - [Untrusted external messages](https://github.com/openai/codex/blob/main/sdk/python/docs/api-reference.md#externalmessage)
120
+ - [FAQ](https://github.com/openai/codex/blob/main/sdk/python/docs/faq.md)
121
+ - [Examples](https://github.com/openai/codex/blob/main/sdk/python/examples/README.md)
122
+
123
+ Where those guides say `pip install openai-codex`, use `pip install circle-codex`.
124
+
125
+ The package is licensed under the
126
+ [Apache License 2.0](https://github.com/ashish447344/codex/blob/main/LICENSE),
127
+ the same license as upstream. See the repository
128
+ [NOTICE](https://github.com/ashish447344/codex/blob/main/NOTICE) for attribution.
@@ -0,0 +1,82 @@
1
+ [build-system]
2
+ requires = ["uv_build>=0.11.19,<0.12"]
3
+ build-backend = "uv_build"
4
+
5
+ [project]
6
+ name = "circle-codex"
7
+ version = "0.154.1"
8
+ description = "Unofficial Codex Python SDK fork with a built-in xAI provider"
9
+ readme = "README.md"
10
+ requires-python = ">=3.10"
11
+ license = "Apache-2.0"
12
+ authors = [{ name = "Ashish Verma" }]
13
+ keywords = ["codex", "sdk", "llm", "ai", "agents", "xai", "grok"]
14
+ classifiers = [
15
+ "Development Status :: 5 - Production/Stable",
16
+ "Intended Audience :: Developers",
17
+ "Topic :: Software Development :: Libraries :: Python Modules",
18
+ ]
19
+ dependencies = ["pydantic>=2.12", "packaging>=26.2", "circle-codex-cli-bin==0.154.1"]
20
+
21
+ [project.urls]
22
+ Homepage = "https://github.com/ashish447344/codex"
23
+ Repository = "https://github.com/ashish447344/codex"
24
+ Issues = "https://github.com/ashish447344/codex/issues"
25
+ Documentation = "https://github.com/ashish447344/codex/tree/main/sdk/python/docs"
26
+
27
+ [dependency-groups]
28
+ format = ["ruff>=0.15.8"]
29
+ test = [
30
+ "pytest>=8.0",
31
+ "datamodel-code-generator==0.64.0",
32
+ { include-group = "format" },
33
+ ]
34
+ dev = [
35
+ { include-group = "test" },
36
+ { include-group = "format" },
37
+ ]
38
+
39
+ [tool.codex.codegen]
40
+ schema-dir = "../../codex-rs/app-server-protocol/schema/json"
41
+
42
+ # The distribution is named circle-codex, but the import package keeps the
43
+ # upstream name so existing `from openai_codex import ...` code keeps working.
44
+ [tool.uv.build-backend]
45
+ module-name = "openai_codex"
46
+
47
+ [tool.pytest.ini_options]
48
+ addopts = "-q"
49
+ testpaths = ["tests"]
50
+
51
+ [tool.ruff]
52
+ target-version = "py310"
53
+ required-version = ">=0.15.8"
54
+ line-length = 100
55
+ extend-exclude = [
56
+ "notebooks/**",
57
+ "src/openai_codex/generated/**",
58
+ ]
59
+
60
+ [tool.ruff.lint]
61
+ select = ["E", "F", "I", "B", "C4"]
62
+ ignore = ["E501"]
63
+ preview = true
64
+ extend-safe-fixes = ["ALL"]
65
+ unfixable = ["F841"]
66
+
67
+ [tool.ruff.lint.per-file-ignores]
68
+ "examples/**/*.py" = ["E402"]
69
+ "tests/test_real_app_server_integration.py" = ["E402"]
70
+
71
+ [tool.ruff.lint.isort]
72
+ combine-as-imports = true
73
+
74
+ [tool.uv]
75
+ exclude-newer = "7 days"
76
+ exclude-newer-package = { circle-codex-cli-bin = "2100-01-01T00:00:00Z" }
77
+ index-strategy = "first-index"
78
+
79
+ [tool.uv.pip]
80
+ exclude-newer = "7 days"
81
+ exclude-newer-package = { circle-codex-cli-bin = "2100-01-01T00:00:00Z" }
82
+ index-strategy = "first-index"
@@ -0,0 +1,95 @@
1
+ """Python SDK for running Codex workflows.
2
+
3
+ Start with :class:`Codex` for synchronous applications or
4
+ :class:`AsyncCodex` for async applications. Most programs create a thread and
5
+ run a turn::
6
+
7
+ from openai_codex import Codex, Sandbox
8
+
9
+ with Codex() as codex:
10
+ thread = codex.thread_start(sandbox=Sandbox.workspace_write)
11
+ result = thread.run("Describe this project.")
12
+ print(result.final_response)
13
+ """
14
+
15
+ from ._version import __version__
16
+ from .api import (
17
+ ApprovalMode,
18
+ AsyncChatgptLoginHandle,
19
+ AsyncCodex,
20
+ AsyncDeviceCodeLoginHandle,
21
+ AsyncThread,
22
+ AsyncTurnHandle,
23
+ ChatgptLoginHandle,
24
+ Codex,
25
+ DeviceCodeLoginHandle,
26
+ ExternalMessage,
27
+ ImageInput,
28
+ Input,
29
+ InputItem,
30
+ LocalImageInput,
31
+ MentionInput,
32
+ RunInput,
33
+ Sandbox,
34
+ SkillInput,
35
+ TextInput,
36
+ Thread,
37
+ TurnHandle,
38
+ TurnResult,
39
+ )
40
+ from .client import CodexConfig
41
+ from .errors import (
42
+ CodexError,
43
+ CodexRpcError,
44
+ InternalRpcError,
45
+ InvalidParamsError,
46
+ InvalidRequestError,
47
+ JsonRpcError,
48
+ MethodNotFoundError,
49
+ ParseError,
50
+ RetryLimitExceededError,
51
+ ServerBusyError,
52
+ TransportClosedError,
53
+ is_retryable_error,
54
+ )
55
+ from .retry import retry_on_overload
56
+
57
+ __all__ = [
58
+ "__version__",
59
+ "CodexConfig",
60
+ "Codex",
61
+ "AsyncCodex",
62
+ "ApprovalMode",
63
+ "Sandbox",
64
+ "ChatgptLoginHandle",
65
+ "DeviceCodeLoginHandle",
66
+ "AsyncChatgptLoginHandle",
67
+ "AsyncDeviceCodeLoginHandle",
68
+ "Thread",
69
+ "AsyncThread",
70
+ "TurnHandle",
71
+ "AsyncTurnHandle",
72
+ "TurnResult",
73
+ "Input",
74
+ "InputItem",
75
+ "RunInput",
76
+ "ExternalMessage",
77
+ "TextInput",
78
+ "ImageInput",
79
+ "LocalImageInput",
80
+ "SkillInput",
81
+ "MentionInput",
82
+ "retry_on_overload",
83
+ "CodexError",
84
+ "TransportClosedError",
85
+ "JsonRpcError",
86
+ "CodexRpcError",
87
+ "ParseError",
88
+ "InvalidRequestError",
89
+ "MethodNotFoundError",
90
+ "InvalidParamsError",
91
+ "InternalRpcError",
92
+ "ServerBusyError",
93
+ "RetryLimitExceededError",
94
+ "is_retryable_error",
95
+ ]
@@ -0,0 +1,51 @@
1
+ from __future__ import annotations
2
+
3
+ from enum import Enum
4
+ from typing import NoReturn
5
+
6
+ from .generated.v2_all import (
7
+ ApprovalsReviewer,
8
+ AskForApproval,
9
+ AskForApprovalValue,
10
+ )
11
+
12
+
13
+ class ApprovalMode(str, Enum):
14
+ """High-level approval behavior for escalated permission requests."""
15
+
16
+ deny_all = "deny_all"
17
+ auto_review = "auto_review"
18
+
19
+
20
+ def _approval_mode_settings(
21
+ approval_mode: ApprovalMode,
22
+ ) -> tuple[AskForApproval, ApprovalsReviewer | None]:
23
+ """Map the public approval mode to generated app-server start params."""
24
+ if not isinstance(approval_mode, ApprovalMode):
25
+ supported = ", ".join(mode.value for mode in ApprovalMode)
26
+ raise ValueError(f"approval_mode must be one of: {supported}")
27
+
28
+ match approval_mode:
29
+ case ApprovalMode.auto_review:
30
+ return (
31
+ AskForApproval(root=AskForApprovalValue.on_request),
32
+ ApprovalsReviewer.auto_review,
33
+ )
34
+ case ApprovalMode.deny_all:
35
+ return AskForApproval(root=AskForApprovalValue.never), None
36
+ case _:
37
+ return _assert_never_approval_mode(approval_mode)
38
+
39
+
40
+ def _assert_never_approval_mode(approval_mode: NoReturn) -> NoReturn:
41
+ """Make approval mode mapping exhaustive for static type checkers."""
42
+ raise AssertionError(f"Unhandled approval mode: {approval_mode!r}")
43
+
44
+
45
+ def _approval_mode_override_settings(
46
+ approval_mode: ApprovalMode | None,
47
+ ) -> tuple[AskForApproval | None, ApprovalsReviewer | None]:
48
+ """Map an optional public approval mode to app-server override params."""
49
+ if approval_mode is None:
50
+ return None, None
51
+ return _approval_mode_settings(approval_mode)