codex-python 1.114.0__tar.gz → 1.114.2__tar.gz

{codex_python-1.114.0 → codex_python-1.114.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: codex-python
-Version: 1.114.0
+Version: 1.114.2
 Classifier: Programming Language :: Python :: 3
 Classifier: Programming Language :: Python :: 3 :: Only
 Classifier: Programming Language :: Python :: 3.12
@@ -66,13 +66,29 @@ Use `AppServerClient` when you want a deeper integration:
 ## Quickstart: `Codex`
 
 ```python
-from codex import Codex
+from codex import Codex, ThreadStartOptions
 
 client = Codex()
+
+# Simplest one-shot call.
 summary = client.run_text("Diagnose the failing tests and propose a fix")
 print(summary)
+
+# One-shot call with thread-scoped defaults for that run's fresh internal thread.
+summary = client.run_text(
+    "Diagnose the failing tests in this repo",
+    thread_options=ThreadStartOptions(
+        cwd="/repo",
+        model="gpt-5",
+    ),
+)
+print(summary)
 ```
 
+Use `thread_options=` on `run()`, `run_text()`, `run_json()`, and `run_model()` when you want to
+set defaults on the fresh internal thread created for that one-shot call. Use
+`start_thread()` / `resume_thread()` when later runs should share context.
+
 More `Codex` examples: [docs/exec_api.md](docs/exec_api.md)
 
 ## Quickstart: `AppServerClient`
@@ -97,6 +113,35 @@ with AppServerClient.connect_stdio(initialize_options=initialize_options) as cli
 More app-server examples: [docs/app_server.md](docs/app_server.md)
 For websocket transport, install the optional extra: `pip install "codex-python[websocket]"`.
 
+## Dynamic tools
+
+Decorator-driven dynamic tools are available on both SDK surfaces.
+
+### `Codex`
+
+```python
+from codex import Codex, dynamic_tool
+
+
+@dynamic_tool
+def lookup_ticket(id: str) -> str:
+    """Look up a support ticket by id."""
+    return f"Ticket {id}: Login requests time out in eu-west-1."
+
+
+client = Codex()
+summary = client.run_text(
+    "Use the lookup_ticket dynamic tool for ticket 123 and summarize the result.",
+    tools=[lookup_ticket],
+)
+print(summary)
+```
+
+### `AppServerClient`
+
+For a complete app-server example using the same decorator-driven flow, see
+[examples/app_server_dynamic_tool.py](examples/app_server_dynamic_tool.py).
+
 ## Structured output
 
 ### `Codex`
@@ -186,10 +231,12 @@ Advanced app-server usage, including typed stable RPC domains such as `client.mo
 ## Examples
 
 - [examples/basic_conversation.py](examples/basic_conversation.py): minimal `Codex` flow
+- [examples/basic_dynamic_tool.py](examples/basic_dynamic_tool.py): high-level `Codex` dynamic tool flow
 - [examples/app_server_conversation.py](examples/app_server_conversation.py): minimal app-server flow
 - [examples/app_server_websocket_conversation.py](examples/app_server_websocket_conversation.py): minimal websocket app-server flow
 - [examples/app_server_stream_events.py](examples/app_server_stream_events.py): protocol-native app-server streaming
 - [examples/app_server_tool_handler.py](examples/app_server_tool_handler.py): typed app-server request handling
+- [examples/app_server_dynamic_tool.py](examples/app_server_dynamic_tool.py): decorator-driven dynamic tool registration
 
 ## Bundled binary behavior
 

{codex_python-1.114.0 → codex_python-1.114.2}/README.md

@@ -44,13 +44,29 @@ Use `AppServerClient` when you want a deeper integration:
 ## Quickstart: `Codex`
 
 ```python
-from codex import Codex
+from codex import Codex, ThreadStartOptions
 
 client = Codex()
+
+# Simplest one-shot call.
 summary = client.run_text("Diagnose the failing tests and propose a fix")
 print(summary)
+
+# One-shot call with thread-scoped defaults for that run's fresh internal thread.
+summary = client.run_text(
+    "Diagnose the failing tests in this repo",
+    thread_options=ThreadStartOptions(
+        cwd="/repo",
+        model="gpt-5",
+    ),
+)
+print(summary)
 ```
 
+Use `thread_options=` on `run()`, `run_text()`, `run_json()`, and `run_model()` when you want to
+set defaults on the fresh internal thread created for that one-shot call. Use
+`start_thread()` / `resume_thread()` when later runs should share context.
+
 More `Codex` examples: [docs/exec_api.md](docs/exec_api.md)
 
 ## Quickstart: `AppServerClient`
@@ -75,6 +91,35 @@ with AppServerClient.connect_stdio(initialize_options=initialize_options) as cli
 More app-server examples: [docs/app_server.md](docs/app_server.md)
 For websocket transport, install the optional extra: `pip install "codex-python[websocket]"`.
 
+## Dynamic tools
+
+Decorator-driven dynamic tools are available on both SDK surfaces.
+
+### `Codex`
+
+```python
+from codex import Codex, dynamic_tool
+
+
+@dynamic_tool
+def lookup_ticket(id: str) -> str:
+    """Look up a support ticket by id."""
+    return f"Ticket {id}: Login requests time out in eu-west-1."
+
+
+client = Codex()
+summary = client.run_text(
+    "Use the lookup_ticket dynamic tool for ticket 123 and summarize the result.",
+    tools=[lookup_ticket],
+)
+print(summary)
+```
+
+### `AppServerClient`
+
+For a complete app-server example using the same decorator-driven flow, see
+[examples/app_server_dynamic_tool.py](examples/app_server_dynamic_tool.py).
+
 ## Structured output
 
 ### `Codex`
@@ -164,10 +209,12 @@ Advanced app-server usage, including typed stable RPC domains such as `client.mo
 ## Examples
 
 - [examples/basic_conversation.py](examples/basic_conversation.py): minimal `Codex` flow
+- [examples/basic_dynamic_tool.py](examples/basic_dynamic_tool.py): high-level `Codex` dynamic tool flow
 - [examples/app_server_conversation.py](examples/app_server_conversation.py): minimal app-server flow
 - [examples/app_server_websocket_conversation.py](examples/app_server_websocket_conversation.py): minimal websocket app-server flow
 - [examples/app_server_stream_events.py](examples/app_server_stream_events.py): protocol-native app-server streaming
 - [examples/app_server_tool_handler.py](examples/app_server_tool_handler.py): typed app-server request handling
+- [examples/app_server_dynamic_tool.py](examples/app_server_dynamic_tool.py): decorator-driven dynamic tool registration
 
 ## Bundled binary behavior
 

{codex_python-1.114.0 → codex_python-1.114.2}/codex/__init__.py

@@ -3,9 +3,11 @@
 from __future__ import annotations
 
 from codex.codex import Codex
+from codex.dynamic_tools import dynamic_tool
 from codex.errors import CodexError, CodexExecError, CodexParseError, ThreadRunError
 from codex.options import (
     CancelSignal,
+    CodexConfig,
     CodexConfigObject,
     CodexConfigValue,
     CodexOptions,
@@ -13,11 +15,16 @@ from codex.options import (
     ThreadStartOptions,
     TurnOptions,
 )
+from codex.thread import CodexTurnStream, Input, Thread
 
-__version__ = "1.114.0"
+__version__ = "1.114.2"
 
 __all__ = [
     "Codex",
+    "CodexTurnStream",
+    "Thread",
+    "Input",
+    "dynamic_tool",
     "CodexError",
     "CodexExecError",
     "CodexParseError",
@@ -26,6 +33,7 @@ __all__ = [
     "ThreadStartOptions",
     "ThreadResumeOptions",
     "TurnOptions",
+    "CodexConfig",
     "CodexConfigValue",
     "CodexConfigObject",
     "CancelSignal",

codex_python-1.114.2/codex/_config_types.py

@@ -0,0 +1,108 @@
+from __future__ import annotations
+
+from typing import Literal
+
+from pydantic import BaseModel, ConfigDict, Field
+
+from codex.protocol import types as protocol
+
+type CodexConfigValue = (
+    str | int | float | bool | list["CodexConfigValue"] | dict[str, "CodexConfigValue"]
+)
+type CodexConfigObject = dict[str, CodexConfigValue]
+
+
+class CodexConfig(BaseModel):
+    """Typed top-level Codex config shape with forward-compatible extra keys."""
+
+    model_config = ConfigDict(extra="allow")
+    __pydantic_extra__: dict[str, CodexConfigValue]
+
+    analytics: CodexConfigObject | None = Field(
+        default=None,
+        description="Open-ended analytics configuration subtree.",
+    )
+    approval_policy: protocol.AskForApproval | None = Field(
+        default=None,
+        description="Default approval policy for new turns and commands.",
+    )
+    compact_prompt: str | None = Field(
+        default=None,
+        description="Prompt text used when the app-server compacts thread history.",
+    )
+    developer_instructions: str | None = Field(
+        default=None,
+        description="Default developer instructions applied to new turns.",
+    )
+    forced_chatgpt_workspace_id: str | None = Field(
+        default=None,
+        description="Workspace identifier to force for ChatGPT-managed auth flows.",
+    )
+    forced_login_method: Literal["chatgpt", "api"] | None = Field(
+        default=None,
+        description="Force Codex auth to ChatGPT or API-key mode.",
+    )
+    instructions: str | None = Field(
+        default=None,
+        description="Default user-visible instructions prepended to new conversations.",
+    )
+    model: str | None = Field(
+        default=None,
+        description="Default model id used when threads or turns do not override it.",
+    )
+    model_auto_compact_token_limit: int | None = Field(
+        default=None,
+        description="Token threshold that triggers automatic thread compaction.",
+    )
+    model_context_window: int | None = Field(
+        default=None,
+        description="Context window size override for the configured model.",
+    )
+    model_provider: str | None = Field(
+        default=None,
+        description="Default model provider name.",
+    )
+    model_reasoning_effort: protocol.ReasoningEffort | None = Field(
+        default=None,
+        description="Default reasoning effort for turns that do not override it.",
+    )
+    model_reasoning_summary: protocol.ReasoningSummary | None = Field(
+        default=None,
+        description="Default reasoning-summary behavior for supported models.",
+    )
+    model_verbosity: Literal["low", "medium", "high"] | None = Field(
+        default=None,
+        description="Default verbosity for supported models.",
+    )
+    profile: str | None = Field(
+        default=None,
+        description="Name of the active Codex profile.",
+    )
+    profiles: CodexConfigObject | None = Field(
+        default_factory=dict,
+        description="Open-ended profile definitions keyed by profile name.",
+    )
+    review_model: str | None = Field(
+        default=None,
+        description="Model override used for review flows.",
+    )
+    sandbox_mode: protocol.SandboxMode | None = Field(
+        default=None,
+        description="Default sandbox mode for new threads and turns.",
+    )
+    sandbox_workspace_write: CodexConfigObject | None = Field(
+        default=None,
+        description="Open-ended workspace-write sandbox configuration subtree.",
+    )
+    service_tier: protocol.ServiceTier | None = Field(
+        default=None,
+        description="Default service tier for requests that do not override it.",
+    )
+    tools: CodexConfigObject | None = Field(
+        default=None,
+        description="Open-ended tool configuration subtree.",
+    )
+    web_search: Literal["disabled", "cached", "live"] | None = Field(
+        default=None,
+        description="Default web-search mode.",
+    )

{codex_python-1.114.0 → codex_python-1.114.2}/codex/_runtime.py

@@ -7,7 +7,7 @@ from collections.abc import Callable, Mapping
 from pathlib import Path
 
 from codex._binary import BundledCodexNotFoundError
-from codex._config_types import CodexConfigObject, CodexConfigValue
+from codex._config_types import CodexConfig, CodexConfigObject, CodexConfigValue
 
 INTERNAL_ORIGINATOR_ENV = "CODEX_INTERNAL_ORIGINATOR_OVERRIDE"
 PYTHON_SDK_ORIGINATOR = "codex_sdk_py"
@@ -50,9 +50,14 @@ def resolve_codex_path(
         return system_codex
 
 
-def serialize_config_overrides(config_overrides: CodexConfigObject) -> list[str]:
+def serialize_config_overrides(config_overrides: CodexConfig | CodexConfigObject) -> list[str]:
     overrides: list[str] = []
-    _flatten_config_overrides(config_overrides, "", overrides)
+    root = (
+        config_overrides.model_dump(mode="python", exclude_none=True, exclude_unset=True)
+        if isinstance(config_overrides, CodexConfig)
+        else config_overrides
+    )
+    _flatten_config_overrides(root, "", overrides)
     return overrides
 
 

{codex_python-1.114.0 → codex_python-1.114.2}/codex/app_server/__init__.py

@@ -1,5 +1,6 @@
 from __future__ import annotations
 
+from codex._config_types import CodexConfig
 from codex.app_server._async_client import AsyncAppServerClient, AsyncRpcClient
 from codex.app_server._async_threads import AsyncAppServerThread, AsyncTurnStream
 from codex.app_server._sync_client import AppServerClient, RpcClient
@@ -23,6 +24,7 @@ from codex.app_server.options import (
     AppServerTurnOptions,
     AppServerWebSocketOptions,
 )
+from codex.dynamic_tools import dynamic_tool
 
 __all__ = [
     "AsyncAppServerClient",
@@ -30,6 +32,7 @@ __all__ = [
     "AsyncRpcClient",
     "AsyncTurnStream",
     "AppServerClient",
+    "dynamic_tool",
     "AppServerThread",
     "RpcClient",
     "TurnStream",
@@ -40,6 +43,7 @@ __all__ = [
     "AppServerRpcError",
     "AppServerTurnError",
     "AppServerClientInfo",
+    "CodexConfig",
     "AppServerInitializeOptions",
     "AppServerProcessOptions",
     "AppServerWebSocketOptions",

{codex_python-1.114.0 → codex_python-1.114.2}/codex/app_server/_async_client.py

@@ -2,7 +2,7 @@
 
 from __future__ import annotations
 
-from collections.abc import Collection, Mapping
+from collections.abc import Callable, Collection, Mapping
 from typing import TypeVar, cast
 
 from pydantic import BaseModel
@@ -43,6 +43,7 @@ from codex.app_server.transports import (
     AsyncStdioTransport,
     AsyncWebSocketTransport,
 )
+from codex.dynamic_tools import _DynamicToolRuntime, merge_dynamic_tool_specs, resolve_dynamic_tools
 from codex.protocol import types as protocol
 
 _ModelT = TypeVar("_ModelT", bound=BaseModel)
@@ -60,8 +61,9 @@ __all__ = [
 class AsyncRpcClient:
     """Low-level async JSON-RPC access to app-server methods."""
 
-    def __init__(self, session: _AsyncSession) -> None:
+    def __init__(self, session: _AsyncSession, dynamic_tools: _DynamicToolRuntime) -> None:
         self._session = session
+        self._dynamic_tools = dynamic_tools
 
     async def request(
         self,
@@ -92,6 +94,7 @@ class AsyncRpcClient:
         *,
         request_model: type[_RequestT] | None = None,
     ) -> None:
+        self._dynamic_tools.check_manual_handler_registration(method)
         self._session.on_request(method, handler, request_model=request_model)
 
 
@@ -114,7 +117,8 @@ class AsyncAppServerClient:
         initialize_options: AppServerInitializeOptions | None = None,
     ) -> None:
         self._session = _AsyncSession(transport, initialize_options)
-        self.rpc = AsyncRpcClient(self._session)
+        self._dynamic_tools = _DynamicToolRuntime(self._session.on_request)
+        self.rpc = AsyncRpcClient(self._session, self._dynamic_tools)
         self.events = AsyncEventsClient(self._session)
         self.models = AsyncModelsClient(self.rpc)
         self.apps = AsyncAppsClient(self.rpc)
@@ -167,12 +171,19 @@ class AsyncAppServerClient:
     async def start_thread(
         self,
         options: AppServerThreadStartOptions | None = None,
+        *,
+        tools: Collection[Callable[..., object]] | None = None,
     ) -> AsyncAppServerThread:
+        start_options = options or AppServerThreadStartOptions()
+        resolved_tools = resolve_dynamic_tools(list(tools or ()))
+        dynamic_tools = merge_dynamic_tool_specs(start_options.dynamic_tools, resolved_tools)
+        self._dynamic_tools.prepare_activation(resolved_tools)
         result = await self.rpc.request_typed(
             "thread/start",
-            (options or AppServerThreadStartOptions()).to_params(),
+            start_options.model_copy(update={"dynamic_tools": dynamic_tools}).to_params(),
             ThreadResult,
         )
+        self._dynamic_tools.activate(result.thread.id, resolved_tools)
         return AsyncAppServerThread(cast(_ThreadClient, self), result.thread)
 
     async def resume_thread(

{codex_python-1.114.0 → codex_python-1.114.2}/codex/app_server/_session.py

@@ -31,6 +31,7 @@ from codex.protocol import types as protocol
 _ModelT = TypeVar("_ModelT", bound=BaseModel)
 _RequestT = TypeVar("_RequestT", bound=BaseModel)
 _NotificationPredicate = Callable[[Notification], bool]
+_SubscriptionMessage = Notification | Exception | None
 
 
 class _NotificationSink:
@@ -41,7 +42,7 @@ class _NotificationSink:
     ) -> None:
         self.methods = methods
         self.predicate = predicate
-        self.queue: asyncio.Queue[Notification | None] = asyncio.Queue()
+        self.queue: asyncio.Queue[_SubscriptionMessage] = asyncio.Queue()
 
     def matches(self, method: str, notification: Notification) -> bool:
         if self.methods is not None and method not in self.methods:
@@ -52,13 +53,15 @@ class _NotificationSink:
 @dataclass(slots=True)
 class _AsyncNotificationSubscription:
     sink: _NotificationSink
-    queue: asyncio.Queue[Notification | None]
+    queue: asyncio.Queue[_SubscriptionMessage]
     close_callback: Callable[[], None]
 
     async def next(self) -> Notification:
         message = await self.queue.get()
         if message is None:
             raise StopAsyncIteration
+        if isinstance(message, Exception):
+            raise message
         return message
 
     async def close(self) -> None:
@@ -253,7 +256,7 @@ class _AsyncSession:
             self._reader_error = exc
             self._fail_pending(exc)
             for sink in list(self._notification_sinks):
-                await sink.queue.put(None)
+                await sink.queue.put(exc)
 
     async def _await_future(self, future: asyncio.Future[object]) -> object:
         while True:

{codex_python-1.114.0 → codex_python-1.114.2}/codex/app_server/_sync_client.py

@@ -5,7 +5,7 @@ from __future__ import annotations
 import asyncio
 import concurrent.futures
 import time
-from collections.abc import Coroutine, Mapping
+from collections.abc import Callable, Collection, Coroutine, Mapping
 from contextlib import suppress
 from threading import Thread
 from typing import Any, TypeVar, cast
@@ -311,9 +311,13 @@ class AppServerClient(_SyncRunner):
     def start_thread(
         self,
         options: AppServerThreadStartOptions | None = None,
+        *,
+        tools: Collection[Callable[..., object]] | None = None,
     ) -> AppServerThread:
         return AppServerThread(
-            cast(_AsyncThreadLike, self._run(self._async_client.start_thread(options))),
+            cast(
+                _AsyncThreadLike, self._run(self._async_client.start_thread(options, tools=tools))
+            ),
             self._run,
         )
 

{codex_python-1.114.0 → codex_python-1.114.2}/codex/app_server/models.py

@@ -6,7 +6,7 @@ from pydantic import BaseModel, Field
 from pydantic import ConfigDict as PydanticConfigDict
 from pydantic.alias_generators import to_camel
 
-from codex._config_types import CodexConfigObject, CodexConfigValue
+from codex._config_types import CodexConfig, CodexConfigObject, CodexConfigValue
 from codex.protocol import types as protocol
 
 
@@ -144,31 +144,8 @@ class AccountRateLimitsResult(AppServerResultModel):
     rate_limits_by_limit_id: dict[str, protocol.RateLimitSnapshot] | None = None
 
 
-class AppServerConfig(BaseModel):
-    model_config = PydanticConfigDict(extra="allow")
-
-    analytics: CodexConfigObject | None = None
-    approval_policy: protocol.AskForApproval | None = None
-    compact_prompt: str | None = None
-    developer_instructions: str | None = None
-    forced_chatgpt_workspace_id: str | None = None
-    forced_login_method: Literal["chatgpt", "api"] | None = None
-    instructions: str | None = None
-    model: str | None = None
-    model_auto_compact_token_limit: int | None = None
-    model_context_window: int | None = None
-    model_provider: str | None = None
-    model_reasoning_effort: protocol.ReasoningEffort | None = None
-    model_reasoning_summary: protocol.ReasoningSummary | None = None
-    model_verbosity: Literal["low", "medium", "high"] | None = None
-    profile: str | None = None
-    profiles: CodexConfigObject | None = Field(default_factory=dict)
-    review_model: str | None = None
-    sandbox_mode: protocol.SandboxMode | None = None
-    sandbox_workspace_write: CodexConfigObject | None = None
-    service_tier: protocol.ServiceTier | None = None
-    tools: CodexConfigObject | None = None
-    web_search: Literal["disabled", "cached", "live"] | None = None
+class AppServerConfig(CodexConfig):
+    """Typed config payload returned by app-server config APIs."""
 
 
 class ConfigLayerMetadata(AppServerResultModel):