From 95dfe7bf2225b1c6e968cdcd163b8f2ec321921b Mon Sep 17 00:00:00 2001 From: Jack Gerrits Date: Mon, 2 Dec 2024 17:36:00 -0500 Subject: [PATCH] Core doc edits, mostly visibility of private methods (#4457) --- python/packages/autogen-core/docs/src/conf.py | 1 + .../src/autogen_core/base/_agent_instantiation.py | 13 +++++++------ .../src/autogen_core/base/_agent_runtime.py | 3 +++ .../src/autogen_core/base/_base_agent.py | 4 ++++ .../autogen_core/base/_message_handler_context.py | 9 +++++---- .../src/autogen_core/base/_serialization.py | 4 ++++ .../src/autogen_core/base/_subscription_context.py | 9 +++++---- .../components/code_executor/_func_with_reqs.py | 1 + 8 files changed, 30 insertions(+), 14 deletions(-) diff --git a/python/packages/autogen-core/docs/src/conf.py b/python/packages/autogen-core/docs/src/conf.py index bdd4579c3..a723decc5 100644 --- a/python/packages/autogen-core/docs/src/conf.py +++ b/python/packages/autogen-core/docs/src/conf.py @@ -149,6 +149,7 @@ autodoc_default_options = { } autodoc_pydantic_model_show_config_summary = False +python_use_unqualified_type_names = True intersphinx_mapping = {"python": ("https://docs.python.org/3", None)} diff --git a/python/packages/autogen-core/src/autogen_core/base/_agent_instantiation.py b/python/packages/autogen-core/src/autogen_core/base/_agent_instantiation.py index e38f94a52..06364381d 100644 --- a/python/packages/autogen-core/src/autogen_core/base/_agent_instantiation.py +++ b/python/packages/autogen-core/src/autogen_core/base/_agent_instantiation.py @@ -12,23 +12,24 @@ class AgentInstantiationContext: "AgentInstantiationContext cannot be instantiated. It is a static class that provides context management for agent instantiation." ) - AGENT_INSTANTIATION_CONTEXT_VAR: ClassVar[ContextVar[tuple[AgentRuntime, AgentId]]] = ContextVar( - "AGENT_INSTANTIATION_CONTEXT_VAR" + _AGENT_INSTANTIATION_CONTEXT_VAR: ClassVar[ContextVar[tuple[AgentRuntime, AgentId]]] = ContextVar( + "_AGENT_INSTANTIATION_CONTEXT_VAR" ) @classmethod @contextmanager def populate_context(cls, ctx: tuple[AgentRuntime, AgentId]) -> Generator[None, Any, None]: - token = AgentInstantiationContext.AGENT_INSTANTIATION_CONTEXT_VAR.set(ctx) + """:meta private:""" + token = AgentInstantiationContext._AGENT_INSTANTIATION_CONTEXT_VAR.set(ctx) try: yield finally: - AgentInstantiationContext.AGENT_INSTANTIATION_CONTEXT_VAR.reset(token) + AgentInstantiationContext._AGENT_INSTANTIATION_CONTEXT_VAR.reset(token) @classmethod def current_runtime(cls) -> AgentRuntime: try: - return cls.AGENT_INSTANTIATION_CONTEXT_VAR.get()[0] + return cls._AGENT_INSTANTIATION_CONTEXT_VAR.get()[0] except LookupError as e: raise RuntimeError( "AgentInstantiationContext.runtime() must be called within an instantiation context such as when the AgentRuntime is instantiating an agent. Mostly likely this was caused by directly instantiating an agent instead of using the AgentRuntime to do so." @@ -37,7 +38,7 @@ class AgentInstantiationContext: @classmethod def current_agent_id(cls) -> AgentId: try: - return cls.AGENT_INSTANTIATION_CONTEXT_VAR.get()[1] + return cls._AGENT_INSTANTIATION_CONTEXT_VAR.get()[1] except LookupError as e: raise RuntimeError( "AgentInstantiationContext.agent_id() must be called within an instantiation context such as when the AgentRuntime is instantiating an agent. Mostly likely this was caused by directly instantiating an agent instead of using the AgentRuntime to do so." diff --git a/python/packages/autogen-core/src/autogen_core/base/_agent_runtime.py b/python/packages/autogen-core/src/autogen_core/base/_agent_runtime.py index 27c37ad9f..c4025ce23 100644 --- a/python/packages/autogen-core/src/autogen_core/base/_agent_runtime.py +++ b/python/packages/autogen-core/src/autogen_core/base/_agent_runtime.py @@ -86,6 +86,9 @@ class AgentRuntime(Protocol): ) -> AgentType: """Register an agent factory with the runtime associated with a specific type. The type must be unique. + .. deprecated:: 0.4.0.dev1 + Use a specific agent's `register` method directly instead of this method. For example: :meth:`BaseAgent.register` + Args: type (str): The type of agent this factory creates. It is not the same as agent class name. The `type` parameter is used to differentiate between different factory functions rather than agent classes. agent_factory (Callable[[], T]): The factory that creates the agent, where T is a concrete Agent type. Inside the factory, use `autogen_core.base.AgentInstantiationContext` to access variables like the current runtime and agent ID. diff --git a/python/packages/autogen-core/src/autogen_core/base/_base_agent.py b/python/packages/autogen-core/src/autogen_core/base/_base_agent.py index 70481705c..1b7a98d51 100644 --- a/python/packages/autogen-core/src/autogen_core/base/_base_agent.py +++ b/python/packages/autogen-core/src/autogen_core/base/_base_agent.py @@ -29,6 +29,8 @@ BaseAgentType = TypeVar("BaseAgentType", bound="BaseAgent") # Decorator for adding an unbound subscription to an agent def subscription_factory(subscription: UnboundSubscription) -> Callable[[Type[BaseAgentType]], Type[BaseAgentType]]: + """:meta private:""" + def decorator(cls: Type[BaseAgentType]) -> Type[BaseAgentType]: cls.internal_unbound_subscriptions_list.append(subscription) return cls @@ -56,7 +58,9 @@ def handles( class BaseAgent(ABC, Agent): internal_unbound_subscriptions_list: ClassVar[List[UnboundSubscription]] = [] + """:meta private:""" internal_extra_handles_types: ClassVar[List[Tuple[Type[Any], List[MessageSerializer[Any]]]]] = [] + """:meta private:""" def __init_subclass__(cls, **kwargs: Any) -> None: super().__init_subclass__(**kwargs) diff --git a/python/packages/autogen-core/src/autogen_core/base/_message_handler_context.py b/python/packages/autogen-core/src/autogen_core/base/_message_handler_context.py index f4707ff0f..b0f08ac8c 100644 --- a/python/packages/autogen-core/src/autogen_core/base/_message_handler_context.py +++ b/python/packages/autogen-core/src/autogen_core/base/_message_handler_context.py @@ -11,20 +11,21 @@ class MessageHandlerContext: "MessageHandlerContext cannot be instantiated. It is a static class that provides context management for agent instantiation." ) - MESSAGE_HANDLER_CONTEXT: ClassVar[ContextVar[AgentId]] = ContextVar("MESSAGE_HANDLER_CONTEXT") + _MESSAGE_HANDLER_CONTEXT: ClassVar[ContextVar[AgentId]] = ContextVar("_MESSAGE_HANDLER_CONTEXT") @classmethod @contextmanager def populate_context(cls, ctx: AgentId) -> Generator[None, Any, None]: - token = MessageHandlerContext.MESSAGE_HANDLER_CONTEXT.set(ctx) + """:meta private:""" + token = MessageHandlerContext._MESSAGE_HANDLER_CONTEXT.set(ctx) try: yield finally: - MessageHandlerContext.MESSAGE_HANDLER_CONTEXT.reset(token) + MessageHandlerContext._MESSAGE_HANDLER_CONTEXT.reset(token) @classmethod def agent_id(cls) -> AgentId: try: - return cls.MESSAGE_HANDLER_CONTEXT.get() + return cls._MESSAGE_HANDLER_CONTEXT.get() except LookupError as e: raise RuntimeError("MessageHandlerContext.agent_id() must be called within a message handler.") from e diff --git a/python/packages/autogen-core/src/autogen_core/base/_serialization.py b/python/packages/autogen-core/src/autogen_core/base/_serialization.py index 74e028641..608fe9180 100644 --- a/python/packages/autogen-core/src/autogen_core/base/_serialization.py +++ b/python/packages/autogen-core/src/autogen_core/base/_serialization.py @@ -199,6 +199,8 @@ V = TypeVar("V") def try_get_known_serializers_for_type(cls: type[Any]) -> list[MessageSerializer[Any]]: + """:meta private:""" + serializers: List[MessageSerializer[Any]] = [] if issubclass(cls, BaseModel): serializers.append(PydanticJsonMessageSerializer(cls)) @@ -211,6 +213,8 @@ def try_get_known_serializers_for_type(cls: type[Any]) -> list[MessageSerializer class SerializationRegistry: + """:meta private:""" + def __init__(self) -> None: # type_name, data_content_type -> serializer self._serializers: dict[tuple[str, str], MessageSerializer[Any]] = {} diff --git a/python/packages/autogen-core/src/autogen_core/base/_subscription_context.py b/python/packages/autogen-core/src/autogen_core/base/_subscription_context.py index 1e7e563a5..e67bcfc9b 100644 --- a/python/packages/autogen-core/src/autogen_core/base/_subscription_context.py +++ b/python/packages/autogen-core/src/autogen_core/base/_subscription_context.py @@ -11,21 +11,22 @@ class SubscriptionInstantiationContext: "SubscriptionInstantiationContext cannot be instantiated. It is a static class that provides context management for subscription instantiation." ) - SUBSCRIPTION_CONTEXT_VAR: ClassVar[ContextVar[AgentType]] = ContextVar("SUBSCRIPTION_CONTEXT_VAR") + _SUBSCRIPTION_CONTEXT_VAR: ClassVar[ContextVar[AgentType]] = ContextVar("_SUBSCRIPTION_CONTEXT_VAR") @classmethod @contextmanager def populate_context(cls, ctx: AgentType) -> Generator[None, Any, None]: - token = SubscriptionInstantiationContext.SUBSCRIPTION_CONTEXT_VAR.set(ctx) + """:meta private:""" + token = SubscriptionInstantiationContext._SUBSCRIPTION_CONTEXT_VAR.set(ctx) try: yield finally: - SubscriptionInstantiationContext.SUBSCRIPTION_CONTEXT_VAR.reset(token) + SubscriptionInstantiationContext._SUBSCRIPTION_CONTEXT_VAR.reset(token) @classmethod def agent_type(cls) -> AgentType: try: - return cls.SUBSCRIPTION_CONTEXT_VAR.get() + return cls._SUBSCRIPTION_CONTEXT_VAR.get() except LookupError as e: raise RuntimeError( "SubscriptionInstantiationContext.runtime() must be called within an instantiation context such as when the AgentRuntime is instantiating an agent. Mostly likely this was caused by directly instantiating an agent instead of using the AgentRuntime to do so." diff --git a/python/packages/autogen-core/src/autogen_core/components/code_executor/_func_with_reqs.py b/python/packages/autogen-core/src/autogen_core/components/code_executor/_func_with_reqs.py index 1ef01cedd..b7f4fcaef 100644 --- a/python/packages/autogen-core/src/autogen_core/components/code_executor/_func_with_reqs.py +++ b/python/packages/autogen-core/src/autogen_core/components/code_executor/_func_with_reqs.py @@ -161,6 +161,7 @@ def with_requirements( def build_python_functions_file( funcs: Sequence[Union[FunctionWithRequirements[Any, P], Callable[..., Any], FunctionWithRequirementsStr]], ) -> str: + """:meta private:""" # First collect all global imports global_imports: Set[Import] = set() for func in funcs: