openai-agents 0.2.6__py3-none-any.whl → 0.6.8__py3-none-any.whl

agents/extensions/experimental/codex/output_schema_file.py

@@ -0,0 +1,50 @@
+from __future__ import annotations
+
+import json
+import os
+import shutil
+import tempfile
+from dataclasses import dataclass
+from typing import Any, Callable
+
+from agents.exceptions import UserError
+
+
+@dataclass
+class OutputSchemaFile:
+    # Holds the on-disk schema path and cleanup callback.
+    schema_path: str | None
+    cleanup: Callable[[], None]
+
+
+def _is_plain_json_object(schema: Any) -> bool:
+    return isinstance(schema, dict)
+
+
+def create_output_schema_file(schema: dict[str, Any] | None) -> OutputSchemaFile:
+    """Materialize a JSON schema into a temp file for the Codex CLI."""
+    if schema is None:
+        # No schema means there is no temp file to manage.
+        return OutputSchemaFile(schema_path=None, cleanup=lambda: None)
+
+    if not _is_plain_json_object(schema):
+        raise UserError("output_schema must be a plain JSON object")
+
+    # The Codex CLI expects a schema file path, so write to a temp directory.
+    schema_dir = tempfile.mkdtemp(prefix="codex-output-schema-")
+    schema_path = os.path.join(schema_dir, "schema.json")
+
+    def cleanup() -> None:
+        # Best-effort cleanup since this runs in finally blocks.
+        try:
+            shutil.rmtree(schema_dir, ignore_errors=True)
+        except Exception:
+            pass
+
+    try:
+        with open(schema_path, "w", encoding="utf-8") as handle:
+            json.dump(schema, handle)
+        return OutputSchemaFile(schema_path=schema_path, cleanup=cleanup)
+    except Exception:
+        cleanup()
+        raise

agents/extensions/experimental/codex/payloads.py

@@ -0,0 +1,31 @@
+from __future__ import annotations
+
+import dataclasses
+from collections.abc import Iterable
+from typing import Any, cast
+
+
+class _DictLike:
+    def __getitem__(self, key: str) -> Any:
+        if key in self._field_names():
+            return getattr(self, key)
+        raise KeyError(key)
+
+    def get(self, key: str, default: Any = None) -> Any:
+        if key in self._field_names():
+            return getattr(self, key)
+        return default
+
+    def __contains__(self, key: object) -> bool:
+        if not isinstance(key, str):
+            return False
+        return key in self._field_names()
+
+    def keys(self) -> Iterable[str]:
+        return iter(self._field_names())
+
+    def as_dict(self) -> dict[str, Any]:
+        return dataclasses.asdict(cast(Any, self))
+
+    def _field_names(self) -> list[str]:
+        return [field.name for field in dataclasses.fields(cast(Any, self))]

agents/extensions/experimental/codex/thread.py

@@ -0,0 +1,214 @@
+from __future__ import annotations
+
+import asyncio
+import contextlib
+from collections.abc import AsyncGenerator
+from dataclasses import dataclass
+from typing import Any, Union, cast
+
+from typing_extensions import Literal, TypeAlias, TypedDict
+
+from .codex_options import CodexOptions
+from .events import (
+    ItemCompletedEvent,
+    ThreadError,
+    ThreadErrorEvent,
+    ThreadEvent,
+    ThreadStartedEvent,
+    TurnCompletedEvent,
+    TurnFailedEvent,
+    Usage,
+    coerce_thread_event,
+)
+from .exec import CodexExec, CodexExecArgs
+from .items import ThreadItem, is_agent_message_item
+from .output_schema_file import create_output_schema_file
+from .thread_options import ThreadOptions
+from .turn_options import TurnOptions
+
+
+@contextlib.asynccontextmanager
+async def _aclosing(
+    generator: AsyncGenerator[str, None],
+) -> AsyncGenerator[AsyncGenerator[str, None], None]:
+    try:
+        yield generator
+    finally:
+        await generator.aclose()
+
+
+class TextInput(TypedDict):
+    type: Literal["text"]
+    text: str
+
+
+class LocalImageInput(TypedDict):
+    type: Literal["local_image"]
+    path: str
+
+
+UserInput: TypeAlias = Union[TextInput, LocalImageInput]
+Input: TypeAlias = Union[str, list[UserInput]]
+
+
+@dataclass(frozen=True)
+class Turn:
+    items: list[ThreadItem]
+    final_response: str
+    usage: Usage | None
+
+
+RunResult = Turn
+
+
+@dataclass(frozen=True)
+class StreamedTurn:
+    events: AsyncGenerator[ThreadEvent, None]
+
+
+RunStreamedResult = StreamedTurn
+
+
+class Thread:
+    def __init__(
+        self,
+        *,
+        exec_client: CodexExec,
+        options: CodexOptions,
+        thread_options: ThreadOptions,
+        thread_id: str | None = None,
+    ) -> None:
+        self._exec = exec_client
+        self._options = options
+        self._id = thread_id
+        self._thread_options = thread_options
+
+    @property
+    def id(self) -> str | None:
+        return self._id
+
+    async def run_streamed(
+        self, input: Input, turn_options: TurnOptions | None = None
+    ) -> StreamedTurn:
+        options = turn_options or TurnOptions()
+        return StreamedTurn(events=self._run_streamed_internal(input, options))
+
+    async def _run_streamed_internal(
+        self, input: Input, turn_options: TurnOptions
+    ) -> AsyncGenerator[ThreadEvent, None]:
+        # The Codex CLI expects an output schema file path for structured output.
+        output_schema_file = create_output_schema_file(turn_options.output_schema)
+        options = self._thread_options
+        prompt, images = _normalize_input(input)
+        idle_timeout = turn_options.idle_timeout_seconds
+        signal = turn_options.signal
+        if idle_timeout is not None and signal is None:
+            signal = asyncio.Event()
+        generator = self._exec.run(
+            CodexExecArgs(
+                input=prompt,
+                base_url=self._options.base_url,
+                api_key=self._options.api_key,
+                thread_id=self._id,
+                images=images,
+                model=options.model,
+                sandbox_mode=options.sandbox_mode,
+                working_directory=options.working_directory,
+                skip_git_repo_check=options.skip_git_repo_check,
+                output_schema_file=output_schema_file.schema_path,
+                model_reasoning_effort=options.model_reasoning_effort,
+                signal=signal,
+                idle_timeout_seconds=idle_timeout,
+                network_access_enabled=options.network_access_enabled,
+                web_search_mode=options.web_search_mode,
+                web_search_enabled=options.web_search_enabled,
+                approval_policy=options.approval_policy,
+                additional_directories=list(options.additional_directories)
+                if options.additional_directories
+                else None,
+            )
+        )
+
+        try:
+            async with _aclosing(generator) as stream:
+                while True:
+                    try:
+                        if idle_timeout is None or isinstance(self._exec, CodexExec):
+                            item = await stream.__anext__()
+                        else:
+                            item = await asyncio.wait_for(
+                                stream.__anext__(),
+                                timeout=idle_timeout,
+                            )
+                    except StopAsyncIteration:
+                        break
+                    except asyncio.TimeoutError as exc:
+                        if signal is not None:
+                            signal.set()
+                        raise RuntimeError(
+                            f"Codex stream idle for {idle_timeout} seconds."
+                        ) from exc
+                    try:
+                        parsed = _parse_event(item)
+                    except Exception as exc:  # noqa: BLE001
+                        raise RuntimeError(f"Failed to parse event: {item}") from exc
+                    if isinstance(parsed, ThreadStartedEvent):
+                        # Capture the thread id so callers can resume later.
+                        self._id = parsed.thread_id
+                    yield parsed
+        finally:
+            output_schema_file.cleanup()
+
+    async def run(self, input: Input, turn_options: TurnOptions | None = None) -> Turn:
+        # Aggregate events into a single Turn result (matching the TS SDK behavior).
+        options = turn_options or TurnOptions()
+        generator = self._run_streamed_internal(input, options)
+        items: list[ThreadItem] = []
+        final_response = ""
+        usage: Usage | None = None
+        turn_failure: ThreadError | None = None
+
+        async for event in generator:
+            if isinstance(event, ItemCompletedEvent):
+                item = event.item
+                if is_agent_message_item(item):
+                    final_response = item.text
+                items.append(item)
+            elif isinstance(event, TurnCompletedEvent):
+                usage = event.usage
+            elif isinstance(event, TurnFailedEvent):
+                turn_failure = event.error
+                break
+            elif isinstance(event, ThreadErrorEvent):
+                raise RuntimeError(f"Codex stream error: {event.message}")
+
+        if turn_failure:
+            raise RuntimeError(turn_failure.message)
+
+        return Turn(items=items, final_response=final_response, usage=usage)
+
+
+def _normalize_input(input: Input) -> tuple[str, list[str]]:
+    # Merge text items into a single prompt and collect image paths.
+    if isinstance(input, str):
+        return input, []
+
+    prompt_parts: list[str] = []
+    images: list[str] = []
+    for item in input:
+        if item["type"] == "text":
+            text = item.get("text", "")
+            prompt_parts.append(text)
+        elif item["type"] == "local_image":
+            path = item.get("path", "")
+            if path:
+                images.append(path)
+
+    return "\n\n".join(prompt_parts), images
+
+
+def _parse_event(raw: str) -> ThreadEvent:
+    import json
+
+    parsed = json.loads(raw)
+    return coerce_thread_event(cast(dict[str, Any], parsed))

agents/extensions/experimental/codex/thread_options.py

@@ -0,0 +1,54 @@
+from __future__ import annotations
+
+from collections.abc import Mapping, Sequence
+from dataclasses import dataclass, fields
+from typing import Any
+
+from typing_extensions import Literal
+
+from agents.exceptions import UserError
+
+ApprovalMode = Literal["never", "on-request", "on-failure", "untrusted"]
+SandboxMode = Literal["read-only", "workspace-write", "danger-full-access"]
+ModelReasoningEffort = Literal["minimal", "low", "medium", "high", "xhigh"]
+WebSearchMode = Literal["disabled", "cached", "live"]
+
+
+@dataclass(frozen=True)
+class ThreadOptions:
+    # Model identifier passed to the Codex CLI (--model).
+    model: str | None = None
+    # Sandbox permissions for filesystem/network access.
+    sandbox_mode: SandboxMode | None = None
+    # Working directory for the Codex CLI process.
+    working_directory: str | None = None
+    # Allow running outside a Git repository.
+    skip_git_repo_check: bool | None = None
+    # Configure model reasoning effort.
+    model_reasoning_effort: ModelReasoningEffort | None = None
+    # Toggle network access in sandboxed workspace writes.
+    network_access_enabled: bool | None = None
+    # Configure web search mode via codex config.
+    web_search_mode: WebSearchMode | None = None
+    # Legacy toggle for web search behavior.
+    web_search_enabled: bool | None = None
+    # Approval policy for tool invocations within Codex.
+    approval_policy: ApprovalMode | None = None
+    # Additional filesystem roots available to Codex.
+    additional_directories: Sequence[str] | None = None
+
+
+def coerce_thread_options(
+    options: ThreadOptions | Mapping[str, Any] | None,
+) -> ThreadOptions | None:
+    if options is None or isinstance(options, ThreadOptions):
+        return options
+    if not isinstance(options, Mapping):
+        raise UserError("ThreadOptions must be a ThreadOptions or a mapping.")
+
+    allowed = {field.name for field in fields(ThreadOptions)}
+    unknown = set(options.keys()) - allowed
+    if unknown:
+        raise UserError(f"Unknown ThreadOptions field(s): {sorted(unknown)}")
+
+    return ThreadOptions(**dict(options))

agents/extensions/experimental/codex/turn_options.py

@@ -0,0 +1,36 @@
+from __future__ import annotations
+
+import asyncio
+from collections.abc import Mapping
+from dataclasses import dataclass, fields
+from typing import Any
+
+from agents.exceptions import UserError
+
+AbortSignal = asyncio.Event
+
+
+@dataclass(frozen=True)
+class TurnOptions:
+    # JSON schema used by Codex for structured output.
+    output_schema: dict[str, Any] | None = None
+    # Cancellation signal for the Codex CLI subprocess.
+    signal: AbortSignal | None = None
+    # Abort the Codex CLI if no events arrive within this many seconds.
+    idle_timeout_seconds: float | None = None
+
+
+def coerce_turn_options(
+    options: TurnOptions | Mapping[str, Any] | None,
+) -> TurnOptions | None:
+    if options is None or isinstance(options, TurnOptions):
+        return options
+    if not isinstance(options, Mapping):
+        raise UserError("TurnOptions must be a TurnOptions or a mapping.")
+
+    allowed = {field.name for field in fields(TurnOptions)}
+    unknown = set(options.keys()) - allowed
+    if unknown:
+        raise UserError(f"Unknown TurnOptions field(s): {sorted(unknown)}")
+
+    return TurnOptions(**dict(options))

agents/extensions/handoff_filters.py

@@ -1,9 +1,14 @@
 from __future__ import annotations
 
-from ..handoffs import HandoffInputData
+from ..handoffs import (
+    HandoffInputData,
+    default_handoff_history_mapper,
+    nest_handoff_history,
+)
 from ..items import (
     HandoffCallItem,
     HandoffOutputItem,
+    ReasoningItem,
     RunItem,
     ToolCallItem,
     ToolCallOutputItem,
@@ -12,6 +17,12 @@ from ..items import (
 
 """Contains common handoff input filters, for convenience. """
 
+__all__ = [
+    "remove_all_tools",
+    "nest_handoff_history",
+    "default_handoff_history_mapper",
+]
+
 
 def remove_all_tools(handoff_input_data: HandoffInputData) -> HandoffInputData:
     """Filters out all tool items: file search, web search and function calls+output."""
@@ -41,6 +52,7 @@ def _remove_tools_from_items(items: tuple[RunItem, ...]) -> tuple[RunItem, ...]:
             or isinstance(item, HandoffOutputItem)
             or isinstance(item, ToolCallItem)
             or isinstance(item, ToolCallOutputItem)
+            or isinstance(item, ReasoningItem)
         ):
             continue
         filtered_items.append(item)

agents/extensions/memory/__init__.py

@@ -0,0 +1,120 @@
+"""Session memory backends living in the extensions namespace.
+
+This package contains optional, production-grade session implementations that
+introduce extra third-party dependencies (database drivers, ORMs, etc.). They
+conform to the :class:`agents.memory.session.Session` protocol so they can be
+used as a drop-in replacement for :class:`agents.memory.session.SQLiteSession`.
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any
+
+if TYPE_CHECKING:
+    from .advanced_sqlite_session import AdvancedSQLiteSession
+    from .async_sqlite_session import AsyncSQLiteSession
+    from .dapr_session import (
+        DAPR_CONSISTENCY_EVENTUAL,
+        DAPR_CONSISTENCY_STRONG,
+        DaprSession,
+    )
+    from .encrypt_session import EncryptedSession
+    from .redis_session import RedisSession
+    from .sqlalchemy_session import SQLAlchemySession
+
+__all__: list[str] = [
+    "AdvancedSQLiteSession",
+    "AsyncSQLiteSession",
+    "DAPR_CONSISTENCY_EVENTUAL",
+    "DAPR_CONSISTENCY_STRONG",
+    "DaprSession",
+    "EncryptedSession",
+    "RedisSession",
+    "SQLAlchemySession",
+]
+
+
+def __getattr__(name: str) -> Any:
+    if name == "EncryptedSession":
+        try:
+            from .encrypt_session import EncryptedSession  # noqa: F401
+
+            return EncryptedSession
+        except ModuleNotFoundError as e:
+            raise ImportError(
+                "EncryptedSession requires the 'cryptography' extra. "
+                "Install it with: pip install openai-agents[encrypt]"
+            ) from e
+
+    if name == "RedisSession":
+        try:
+            from .redis_session import RedisSession  # noqa: F401
+
+            return RedisSession
+        except ModuleNotFoundError as e:
+            raise ImportError(
+                "RedisSession requires the 'redis' extra. "
+                "Install it with: pip install openai-agents[redis]"
+            ) from e
+
+    if name == "SQLAlchemySession":
+        try:
+            from .sqlalchemy_session import SQLAlchemySession  # noqa: F401
+
+            return SQLAlchemySession
+        except ModuleNotFoundError as e:
+            raise ImportError(
+                "SQLAlchemySession requires the 'sqlalchemy' extra. "
+                "Install it with: pip install openai-agents[sqlalchemy]"
+            ) from e
+
+    if name == "AdvancedSQLiteSession":
+        try:
+            from .advanced_sqlite_session import AdvancedSQLiteSession  # noqa: F401
+
+            return AdvancedSQLiteSession
+        except ModuleNotFoundError as e:
+            raise ImportError(f"Failed to import AdvancedSQLiteSession: {e}") from e
+
+    if name == "AsyncSQLiteSession":
+        try:
+            from .async_sqlite_session import AsyncSQLiteSession  # noqa: F401
+
+            return AsyncSQLiteSession
+        except ModuleNotFoundError as e:
+            raise ImportError(f"Failed to import AsyncSQLiteSession: {e}") from e
+
+    if name == "DaprSession":
+        try:
+            from .dapr_session import DaprSession  # noqa: F401
+
+            return DaprSession
+        except ModuleNotFoundError as e:
+            raise ImportError(
+                "DaprSession requires the 'dapr' extra. "
+                "Install it with: pip install openai-agents[dapr]"
+            ) from e
+
+    if name == "DAPR_CONSISTENCY_EVENTUAL":
+        try:
+            from .dapr_session import DAPR_CONSISTENCY_EVENTUAL  # noqa: F401
+
+            return DAPR_CONSISTENCY_EVENTUAL
+        except ModuleNotFoundError as e:
+            raise ImportError(
+                "DAPR_CONSISTENCY_EVENTUAL requires the 'dapr' extra. "
+                "Install it with: pip install openai-agents[dapr]"
+            ) from e
+
+    if name == "DAPR_CONSISTENCY_STRONG":
+        try:
+            from .dapr_session import DAPR_CONSISTENCY_STRONG  # noqa: F401
+
+            return DAPR_CONSISTENCY_STRONG
+        except ModuleNotFoundError as e:
+            raise ImportError(
+                "DAPR_CONSISTENCY_STRONG requires the 'dapr' extra. "
+                "Install it with: pip install openai-agents[dapr]"
+            ) from e
+
+    raise AttributeError(f"module {__name__} has no attribute {name}")