diff --git a/docs/ref/sandbox/entries/mounts/providers/box.md b/docs/ref/sandbox/entries/mounts/providers/box.md new file mode 100644 index 00000000..3cc22369 --- /dev/null +++ b/docs/ref/sandbox/entries/mounts/providers/box.md @@ -0,0 +1,3 @@ +# `Box` + +::: agents.sandbox.entries.mounts.providers.box diff --git a/docs/ref/sandbox/session/archive_ops.md b/docs/ref/sandbox/session/archive_ops.md new file mode 100644 index 00000000..79a6b2dc --- /dev/null +++ b/docs/ref/sandbox/session/archive_ops.md @@ -0,0 +1,3 @@ +# `Archive Ops` + +::: agents.sandbox.session.archive_ops diff --git a/docs/ref/sandbox/session/manifest_ops.md b/docs/ref/sandbox/session/manifest_ops.md new file mode 100644 index 00000000..2524c66f --- /dev/null +++ b/docs/ref/sandbox/session/manifest_ops.md @@ -0,0 +1,3 @@ +# `Manifest Ops` + +::: agents.sandbox.session.manifest_ops diff --git a/docs/ref/sandbox/session/mount_lifecycle.md b/docs/ref/sandbox/session/mount_lifecycle.md new file mode 100644 index 00000000..364e4a46 --- /dev/null +++ b/docs/ref/sandbox/session/mount_lifecycle.md @@ -0,0 +1,3 @@ +# `Mount Lifecycle` + +::: agents.sandbox.session.mount_lifecycle diff --git a/docs/ref/sandbox/session/snapshot_lifecycle.md b/docs/ref/sandbox/session/snapshot_lifecycle.md new file mode 100644 index 00000000..1e714cfb --- /dev/null +++ b/docs/ref/sandbox/session/snapshot_lifecycle.md @@ -0,0 +1,3 @@ +# `Snapshot Lifecycle` + +::: agents.sandbox.session.snapshot_lifecycle diff --git a/docs/ref/sandbox/session/tar_workspace.md b/docs/ref/sandbox/session/tar_workspace.md new file mode 100644 index 00000000..d765c8d6 --- /dev/null +++ b/docs/ref/sandbox/session/tar_workspace.md @@ -0,0 +1,3 @@ +# `Tar Workspace` + +::: agents.sandbox.session.tar_workspace diff --git a/src/agents/extensions/memory/__init__.py b/src/agents/extensions/memory/__init__.py index 7d0437fa..3b0c74da 100644 --- a/src/agents/extensions/memory/__init__.py +++ b/src/agents/extensions/memory/__init__.py @@ -1,133 +1,133 @@ -"""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 .mongodb_session import MongoDBSession - from .redis_session import RedisSession - from .sqlalchemy_session import SQLAlchemySession - -__all__: list[str] = [ - "AdvancedSQLiteSession", - "AsyncSQLiteSession", - "DAPR_CONSISTENCY_EVENTUAL", - "DAPR_CONSISTENCY_STRONG", - "DaprSession", - "EncryptedSession", - "MongoDBSession", - "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 - - if name == "MongoDBSession": - try: - from .mongodb_session import MongoDBSession # noqa: F401 - - return MongoDBSession - except ModuleNotFoundError as e: - raise ImportError( - "MongoDBSession requires the 'mongodb' extra. " - "Install it with: pip install openai-agents[mongodb]" - ) from e - - raise AttributeError(f"module {__name__} has no attribute {name}") +"""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 [`Session`][agents.memory.session.Session] protocol so they can be +used as a drop-in replacement for [`SQLiteSession`][agents.memory.sqlite_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 .mongodb_session import MongoDBSession + from .redis_session import RedisSession + from .sqlalchemy_session import SQLAlchemySession + +__all__: list[str] = [ + "AdvancedSQLiteSession", + "AsyncSQLiteSession", + "DAPR_CONSISTENCY_EVENTUAL", + "DAPR_CONSISTENCY_STRONG", + "DaprSession", + "EncryptedSession", + "MongoDBSession", + "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 + + if name == "MongoDBSession": + try: + from .mongodb_session import MongoDBSession # noqa: F401 + + return MongoDBSession + except ModuleNotFoundError as e: + raise ImportError( + "MongoDBSession requires the 'mongodb' extra. " + "Install it with: pip install openai-agents[mongodb]" + ) from e + + raise AttributeError(f"module {__name__} has no attribute {name}") diff --git a/src/agents/extensions/memory/dapr_session.py b/src/agents/extensions/memory/dapr_session.py index ebb47198..8d928724 100644 --- a/src/agents/extensions/memory/dapr_session.py +++ b/src/agents/extensions/memory/dapr_session.py @@ -55,7 +55,7 @@ _RETRY_MAX_DELAY_SECONDS: Final[float] = 1.0 class DaprSession(SessionABC): - """Dapr State Store implementation of :pyclass:`agents.memory.session.Session`.""" + """Dapr State Store implementation of [`Session`][agents.memory.session.Session].""" session_settings: SessionSettings | None = None diff --git a/src/agents/extensions/memory/mongodb_session.py b/src/agents/extensions/memory/mongodb_session.py index 2bfccb6d..0abaa2bf 100644 --- a/src/agents/extensions/memory/mongodb_session.py +++ b/src/agents/extensions/memory/mongodb_session.py @@ -63,7 +63,7 @@ _DRIVER_INFO = DriverInfo(name="openai-agents", version=_VERSION) class MongoDBSession(SessionABC): - """MongoDB implementation of :pyclass:`agents.memory.session.Session`. + """MongoDB implementation of [`Session`][agents.memory.session.Session]. Conversation items are stored as individual documents in a ``messages`` collection. A lightweight ``sessions`` collection tracks metadata @@ -120,7 +120,7 @@ class MongoDBSession(SessionABC): messages_collection: Name of the collection that stores individual conversation items. Defaults to ``"agent_messages"``. session_settings: Optional session configuration. When ``None`` a - default :class:`~agents.memory.session_settings.SessionSettings` + default [`SessionSettings`][agents.memory.session_settings.SessionSettings] is used (no item limit). """ self.session_id = session_id @@ -161,14 +161,15 @@ class MongoDBSession(SessionABC): ``"mongodb+srv://user:pass@cluster.example.com"``. database: Name of the MongoDB database to use. client_kwargs: Additional keyword arguments forwarded to - :class:`pymongo.asynchronous.mongo_client.AsyncMongoClient`. + `pymongo.asynchronous.mongo_client.AsyncMongoClient`. session_settings: Optional session configuration settings. **kwargs: Additional keyword arguments forwarded to the main constructor (e.g. ``sessions_collection``, ``messages_collection``). Returns: - A :class:`MongoDBSession` connected to the specified MongoDB server. + A [`MongoDBSession`][agents.extensions.memory.mongodb_session.MongoDBSession] + connected to the specified MongoDB server. """ client_kwargs = client_kwargs or {} client_kwargs.setdefault("driver", _DRIVER_INFO) diff --git a/src/agents/extensions/memory/redis_session.py b/src/agents/extensions/memory/redis_session.py index 2dd3d716..60e86342 100644 --- a/src/agents/extensions/memory/redis_session.py +++ b/src/agents/extensions/memory/redis_session.py @@ -40,7 +40,7 @@ from ...memory.session_settings import SessionSettings, resolve_session_limit class RedisSession(SessionABC): - """Redis implementation of :pyclass:`agents.memory.session.Session`.""" + """Redis implementation of [`Session`][agents.memory.session.Session].""" session_settings: SessionSettings | None = None diff --git a/src/agents/extensions/memory/sqlalchemy_session.py b/src/agents/extensions/memory/sqlalchemy_session.py index ff411b7c..fd2502e2 100644 --- a/src/agents/extensions/memory/sqlalchemy_session.py +++ b/src/agents/extensions/memory/sqlalchemy_session.py @@ -54,7 +54,7 @@ from ...memory.session_settings import SessionSettings, resolve_session_limit class SQLAlchemySession(SessionABC): - """SQLAlchemy implementation of :pyclass:`agents.memory.session.Session`.""" + """SQLAlchemy implementation of [`Session`][agents.memory.session.Session].""" _table_init_locks: ClassVar[dict[tuple[str, str, str], threading.Lock]] = {} _table_init_locks_guard: ClassVar[threading.Lock] = threading.Lock()