Documentation tweaks (#3705)

* Add extension to handle pydantic docs

* Docs tweaks

---------

Co-authored-by: Eric Zhu <ekzhu@users.noreply.github.com>

python/packages/autogen-agentchat/src/autogen_agentchat/agents/__init__.py

@@ -1,5 +1,6 @@
 from ._base_chat_agent import (
     BaseChatAgent,
+    BaseMessage,
     BaseToolUseChatAgent,
     ChatMessage,
     MultiModalMessage,
@@ -14,14 +15,15 @@ from ._tool_use_assistant_agent import ToolUseAssistantAgent
 
 __all__ = [
     "BaseChatAgent",
+    "BaseMessage",
     "BaseToolUseChatAgent",
     "ChatMessage",
-    "TextMessage",
-    "MultiModalMessage",
-    "ToolCallMessage",
-    "ToolCallResultMessage",
-    "StopMessage",
     "CodeExecutorAgent",
     "CodingAssistantAgent",
+    "MultiModalMessage",
+    "StopMessage",
+    "TextMessage",
+    "ToolCallMessage",
+    "ToolCallResultMessage",
     "ToolUseAssistantAgent",
 ]

python/packages/autogen-agentchat/src/autogen_agentchat/agents/_code_executor_agent.py

@@ -16,7 +16,6 @@ class CodeExecutorAgent(BaseChatAgent):
         *,
         description: str = "A computer terminal that performs no other action than running Python scripts (provided to it quoted in ```python code blocks), or sh shell scripts (provided to it quoted in ```sh code blocks).",
     ) -> None:
-        """Initialize the agent with a code executor."""
         super().__init__(name=name, description=description)
         self._code_executor = code_executor
 

python/packages/autogen-agentchat/src/autogen_agentchat/teams/__init__.py

@@ -1,7 +1,7 @@
 from ._logging import EVENT_LOGGER_NAME, TRACE_LOGGER_NAME, ConsoleLogHandler, FileLogHandler
 from ._termination import MaxMessageTermination, StopMessageTermination, TerminationCondition, TextMentionTermination
-from .group_chat._round_robin_group_chat import RoundRobinGroupChat
-from .group_chat._selector_group_chat import SelectorGroupChat
+from ._group_chat._round_robin_group_chat import RoundRobinGroupChat
+from ._group_chat._selector_group_chat import SelectorGroupChat
 
 __all__ = [
     "TRACE_LOGGER_NAME",

python/packages/autogen-agentchat/tests/test_sequential_routed_agent.py

@@ -4,7 +4,7 @@ from dataclasses import dataclass
 from typing import List
 
 import pytest
-from autogen_agentchat.teams.group_chat._sequential_routed_agent import SequentialRoutedAgent
+from autogen_agentchat.teams._group_chat._sequential_routed_agent import SequentialRoutedAgent
 from autogen_core.application import SingleThreadedAgentRuntime
 from autogen_core.base import AgentId, MessageContext
 from autogen_core.components import DefaultTopicId, default_subscription, message_handler

python/packages/autogen-core/docs/src/conf.py

@@ -35,6 +35,7 @@ extensions = [
     "sphinx_copybutton",
     "_extension.gallery_directive",
     "myst_nb",
+    "sphinxcontrib.autodoc_pydantic"
 ]
 suppress_warnings = ["myst.header"]
 
@@ -42,7 +43,7 @@ napoleon_custom_sections = [("Returns", "params_style")]
 
 templates_path = ["_templates"]
 
-autoclass_content = "init"
+autoclass_content = "class"
 
 # TODO: incldue all notebooks excluding those requiring remote API access.
 nb_execution_mode = "off"
@@ -128,6 +129,8 @@ autodoc_default_options = {
     "undoc-members": True,
 }
 
+autodoc_pydantic_model_show_config_summary = False
+
 intersphinx_mapping = {"python": ("https://docs.python.org/3", None)}
 
 

python/packages/autogen-core/pyproject.toml

@@ -66,6 +66,7 @@ dev-dependencies = [
     "sphinx-design",
     "sphinx",
     "sphinxcontrib-apidoc",
+    "autodoc_pydantic~=2.2",
 
     # Documentation tooling
     "sphinx-autobuild",

python/packages/autogen-core/src/autogen_core/components/_default_subscription.py

@@ -6,22 +6,22 @@ from ._type_subscription import TypeSubscription
 
 
 class DefaultSubscription(TypeSubscription):
+    """The default subscription is designed to be a sensible default for applications that only need global scope for agents.
+
+    This topic by default uses the "default" topic type and attempts to detect the agent type to use based on the instantiation context.
+
+    Example:
+
+        .. code-block:: python
+
+            await runtime.register("MyAgent", agent_factory, lambda: [DefaultSubscription()])
+
+    Args:
+        topic_type (str, optional): The topic type to subscribe to. Defaults to "default".
+        agent_type (str, optional): The agent type to use for the subscription. Defaults to None, in which case it will attempt to detect the agent type based on the instantiation context.
+    """
+
     def __init__(self, topic_type: str = "default", agent_type: str | None = None):
-        """The default subscription is designed to be a sensible default for applications that only need global scope for agents.
-
-        This topic by default uses the "default" topic type and attempts to detect the agent type to use based on the instantiation context.
-
-        Example:
-
-            .. code-block:: python
-
-                await runtime.register("MyAgent", agent_factory, lambda: [DefaultSubscription()])
-
-        Args:
-            topic_type (str, optional): The topic type to subscribe to. Defaults to "default".
-            agent_type (str, optional): The agent type to use for the subscription. Defaults to None, in which case it will attempt to detect the agent type based on the instantiation context.
-        """
-
         if agent_type is None:
             try:
                 agent_type = SubscriptionInstantiationContext.agent_type().type

python/packages/autogen-core/src/autogen_core/components/_default_topic.py

@@ -2,15 +2,16 @@ from ..base import MessageHandlerContext, TopicId
 
 
 class DefaultTopicId(TopicId):
+    """DefaultTopicId provides a sensible default for the topic_id and source fields of a TopicId.
+
+    If created in the context of a message handler, the source will be set to the agent_id of the message handler, otherwise it will be set to "default".
+
+    Args:
+        type (str, optional): Topic type to publish message to. Defaults to "default".
+        source (str | None, optional): Topic source to publish message to. If None, the source will be set to the agent_id of the message handler if in the context of a message handler, otherwise it will be set to "default". Defaults to None.
+    """
+
     def __init__(self, type: str = "default", source: str | None = None) -> None:
-        """DefaultTopicId provides a sensible default for the topic_id and source fields of a TopicId.
-
-        If created in the context of a message handler, the source will be set to the agent_id of the message handler, otherwise it will be set to "default".
-
-        Args:
-            type (str, optional): Topic type to publish message to. Defaults to "default".
-            source (str | None, optional): Topic source to publish message to. If None, the source will be set to the agent_id of the message handler if in the context of a message handler, otherwise it will be set to "default". Defaults to None.
-        """
         if source is None:
             try:
                 source = MessageHandlerContext.agent_id().key

python/packages/autogen-core/src/autogen_core/components/_type_subscription.py

@@ -6,27 +6,27 @@ from ..base.exceptions import CantHandleException
 
 
 class TypeSubscription(Subscription):
+    """This subscription matches on topics based on the type and maps to agents using the source of the topic as the agent key.
+
+    This subscription causes each source to have its own agent instance.
+
+    Example:
+
+        .. code-block:: python
+
+            subscription = TypeSubscription(topic_type="t1", agent_type="a1")
+
+        In this case:
+
+        - A topic_id with type `t1` and source `s1` will be handled by an agent of type `a1` with key `s1`
+        - A topic_id with type `t1` and source `s2` will be handled by an agent of type `a1` with key `s2`.
+
+    Args:
+        topic_type (str): Topic type to match against
+        agent_type (str): Agent type to handle this subscription
+    """
+
     def __init__(self, topic_type: str, agent_type: str):
-        """This subscription matches on topics based on the type and maps to agents using the source of the topic as the agent key.
-
-        This subscription causes each source to have its own agent instance.
-
-        Example:
-
-            .. code-block:: python
-
-                subscription = TypeSubscription(topic_type="t1", agent_type="a1")
-
-            In this case:
-
-            - A topic_id with type `t1` and source `s1` will be handled by an agent of type `a1` with key `s1`
-            - A topic_id with type `t1` and source `s2` will be handled by an agent of type `a1` with key `s2`.
-
-        Args:
-            topic_type (str): Topic type to match against
-            agent_type (str): Agent type to handle this subscription
-        """
-
         self._topic_type = topic_type
         self._agent_type = agent_type
         self._id = str(uuid.uuid4())

python/packages/autogen-core/src/autogen_core/components/code_executor/_impl/docker_command_line_code_executor.py

@@ -50,6 +50,36 @@ A = ParamSpec("A")
 
 
 class DockerCommandLineCodeExecutor(CodeExecutor):
+    """Executes code through a command line environment in a Docker container.
+
+    The executor first saves each code block in a file in the working
+    directory, and then executes the code file in the container.
+    The executor executes the code blocks in the order they are received.
+    Currently, the executor only supports Python and shell scripts.
+    For Python code, use the language "python" for the code block.
+    For shell scripts, use the language "bash", "shell", or "sh" for the code
+    block.
+
+    Args:
+        image (_type_, optional): Docker image to use for code execution.
+            Defaults to "python:3-slim".
+        container_name (Optional[str], optional): Name of the Docker container
+            which is created. If None, will autogenerate a name. Defaults to None.
+        timeout (int, optional): The timeout for code execution. Defaults to 60.
+        work_dir (Union[Path, str], optional): The working directory for the code
+            execution. Defaults to Path(".").
+        bind_dir (Union[Path, str], optional): The directory that will be bound
+        to the code executor container. Useful for cases where you want to spawn
+        the container from within a container. Defaults to work_dir.
+        auto_remove (bool, optional): If true, will automatically remove the Docker
+            container when it is stopped. Defaults to True.
+        stop_container (bool, optional): If true, will automatically stop the
+            container when stop is called, when the context manager exits or when
+            the Python process exits with atext. Defaults to True.
+        functions (List[Union[FunctionWithRequirements[Any, A], Callable[..., Any]]]): A list of functions that are available to the code executor. Default is an empty list.
+        functions_module (str, optional): The name of the module that will be created to store the functions. Defaults to "functions".
+    """
+
     SUPPORTED_LANGUAGES: ClassVar[List[str]] = [
         "bash",
         "shell",
@@ -87,35 +117,6 @@ $functions"""
         ] = [],
         functions_module: str = "functions",
     ):
-        """Executes code through a command line environment in a Docker container.
-
-        The executor first saves each code block in a file in the working
-        directory, and then executes the code file in the container.
-        The executor executes the code blocks in the order they are received.
-        Currently, the executor only supports Python and shell scripts.
-        For Python code, use the language "python" for the code block.
-        For shell scripts, use the language "bash", "shell", or "sh" for the code
-        block.
-
-        Args:
-            image (_type_, optional): Docker image to use for code execution.
-                Defaults to "python:3-slim".
-            container_name (Optional[str], optional): Name of the Docker container
-                which is created. If None, will autogenerate a name. Defaults to None.
-            timeout (int, optional): The timeout for code execution. Defaults to 60.
-            work_dir (Union[Path, str], optional): The working directory for the code
-                execution. Defaults to Path(".").
-            bind_dir (Union[Path, str], optional): The directory that will be bound
-            to the code executor container. Useful for cases where you want to spawn
-            the container from within a container. Defaults to work_dir.
-            auto_remove (bool, optional): If true, will automatically remove the Docker
-                container when it is stopped. Defaults to True.
-            stop_container (bool, optional): If true, will automatically stop the
-                container when stop is called, when the context manager exits or when
-                the Python process exits with atext. Defaults to True.
-            functions (List[Union[FunctionWithRequirements[Any, A], Callable[..., Any]]]): A list of functions that are available to the code executor. Default is an empty list.
-            functions_module (str, optional): The name of the module that will be created to store the functions. Defaults to "functions".
-        """
         if timeout < 1:
             raise ValueError("Timeout must be greater than or equal to 1.")
 

python/packages/autogen-core/src/autogen_core/components/code_executor/_impl/local_commandline_code_executor.py

@@ -29,6 +29,34 @@ A = ParamSpec("A")
 
 
 class LocalCommandLineCodeExecutor(CodeExecutor):
+    """A code executor class that executes code through a local command line
+    environment.
+
+    .. danger::
+
+        This will execute code on the local machine. If being used with LLM generated code, caution should be used.
+
+    Each code block is saved as a file and executed in a separate process in
+    the working directory, and a unique file is generated and saved in the
+    working directory for each code block.
+    The code blocks are executed in the order they are received.
+    Command line code is sanitized using regular expression match against a list of dangerous commands in order to prevent self-destructive
+    commands from being executed which may potentially affect the users environment.
+    Currently the only supported languages is Python and shell scripts.
+    For Python code, use the language "python" for the code block.
+    For shell scripts, use the language "bash", "shell", or "sh" for the code
+    block.
+
+    Args:
+        timeout (int): The timeout for the execution of any single code block. Default is 60.
+        work_dir (str): The working directory for the code execution. If None,
+            a default working directory will be used. The default working
+            directory is the current directory ".".
+        functions (List[Union[FunctionWithRequirements[Any, A], Callable[..., Any]]]): A list of functions that are available to the code executor. Default is an empty list.
+        functions_module (str, optional): The name of the module that will be created to store the functions. Defaults to "functions".
+
+    """
+
     SUPPORTED_LANGUAGES: ClassVar[List[str]] = [
         "bash",
         "shell",
@@ -59,34 +87,6 @@ $functions"""
         ] = [],
         functions_module: str = "functions",
     ):
-        """A code executor class that executes code through a local command line
-        environment.
-
-        .. danger::
-
-            This will execute code on the local machine. If being used with LLM generated code, caution should be used.
-
-        Each code block is saved as a file and executed in a separate process in
-        the working directory, and a unique file is generated and saved in the
-        working directory for each code block.
-        The code blocks are executed in the order they are received.
-        Command line code is sanitized using regular expression match against a list of dangerous commands in order to prevent self-destructive
-        commands from being executed which may potentially affect the users environment.
-        Currently the only supported languages is Python and shell scripts.
-        For Python code, use the language "python" for the code block.
-        For shell scripts, use the language "bash", "shell", or "sh" for the code
-        block.
-
-        Args:
-            timeout (int): The timeout for the execution of any single code block. Default is 60.
-            work_dir (str): The working directory for the code execution. If None,
-                a default working directory will be used. The default working
-                directory is the current directory ".".
-            functions (List[Union[FunctionWithRequirements[Any, A], Callable[..., Any]]]): A list of functions that are available to the code executor. Default is an empty list.
-            functions_module (str, optional): The name of the module that will be created to store the functions. Defaults to "functions".
-
-        """
-
         if timeout < 1:
             raise ValueError("Timeout must be greater than or equal to 1.")
 

python/packages/autogen-ext/src/autogen_ext/code_executor/aca_dynamic_sessions/_azure_container_code_executor.py

@@ -39,6 +39,26 @@ class TokenProvider(Protocol):
 
 
 class AzureContainerCodeExecutor(CodeExecutor):
+    """(Experimental) A code executor class that executes code through a an Azure
+    Container Apps instance.
+
+    **This will execute LLM generated code on an Azure dynamic code container.**
+
+    The execution environment is similar to that of a jupyter notebook which allows for incremental code execution. The parameter functions are executed in order once at the beginning of each session. Each code block is then executed serially and in the order they are received. Each environment has a statically defined set of available packages which cannot be changed.
+    Currently, attempting to use packages beyond what is available on the environment will result in an error. To get the list of supported packages, call the `get_available_packages` function.
+    Currently the only supported language is Python.
+    For Python code, use the language "python" for the code block.
+
+    Args:
+        pool_management_endpoint (str): The azure container apps dynamic sessions endpoint.
+        credential (TokenProvider): An object that implements the get_token function.
+        timeout (int): The timeout for the execution of any single code block. Default is 60.
+        work_dir (str): The working directory for the code execution. If None,
+            a default working directory will be used. The default working
+            directory is the current directory ".".
+        functions (List[Union[FunctionWithRequirements[Any, A], Callable[..., Any]]]): A list of functions that are available to the code executor. Default is an empty list.
+    """
+
     SUPPORTED_LANGUAGES: ClassVar[List[str]] = [
         "python",
     ]
@@ -63,26 +83,6 @@ $functions"""
         ] = [],
         functions_module: str = "functions",
     ):
-        """(Experimental) A code executor class that executes code through a an Azure
-        Container Apps instance.
-
-        **This will execute LLM generated code on an Azure dynamic code container.**
-
-        The execution environment is similar to that of a jupyter notebook which allows for incremental code execution. The parameter functions are executed in order once at the beginning of each session. Each code block is then executed serially and in the order they are received. Each environment has a statically defined set of available packages which cannot be changed.
-        Currently, attempting to use packages beyond what is available on the environment will result in an error. To get the list of supported packages, call the `get_available_packages` function.
-        Currently the only supported language is Python.
-        For Python code, use the language "python" for the code block.
-
-        Args:
-            pool_management_endpoint (str): The azure container apps dynamic sessions endpoint.
-            credential (TokenProvider): An object that implements the get_token function.
-            timeout (int): The timeout for the execution of any single code block. Default is 60.
-            work_dir (str): The working directory for the code execution. If None,
-                a default working directory will be used. The default working
-                directory is the current directory ".".
-            functions (List[Union[FunctionWithRequirements[Any, A], Callable[..., Any]]]): A list of functions that are available to the code executor. Default is an empty list.
-        """
-
         if timeout < 1:
             raise ValueError("Timeout must be greater than or equal to 1.")
 

python/uv.lock

@@ -342,6 +342,19 @@ wheels = [
     { url = "https://files.pythonhosted.org/packages/6a/21/5b6702a7f963e95456c0de2d495f67bf5fd62840ac655dc451586d23d39a/attrs-24.2.0-py3-none-any.whl", hash = "sha256:81921eb96de3191c8258c199618104dd27ac608d9366f5e35d011eae1867ede2", size = 63001 },
 ]
 
+[[package]]
+name = "autodoc-pydantic"
+version = "2.2.0"
+source = { registry = "https://pypi.org/simple" }
+dependencies = [
+    { name = "pydantic" },
+    { name = "pydantic-settings" },
+    { name = "sphinx" },
+]
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/7b/df/87120e2195f08d760bc5cf8a31cfa2381a6887517aa89453b23f1ae3354f/autodoc_pydantic-2.2.0-py3-none-any.whl", hash = "sha256:8c6a36fbf6ed2700ea9c6d21ea76ad541b621fbdf16b5a80ee04673548af4d95", size = 34001 },
+]
+
 [[package]]
 name = "autogen-agentchat"
 version = "0.4.0.dev0"
@@ -374,6 +387,7 @@ dependencies = [
 [package.dev-dependencies]
 dev = [
     { name = "aiofiles" },
+    { name = "autodoc-pydantic" },
     { name = "azure-identity" },
     { name = "chess" },
     { name = "colorama" },
@@ -429,6 +443,7 @@ requires-dist = [
 [package.metadata.requires-dev]
 dev = [
     { name = "aiofiles" },
+    { name = "autodoc-pydantic", specifier = "~=2.2" },
     { name = "azure-identity" },
     { name = "chess" },
     { name = "colorama" },
@@ -3628,6 +3643,19 @@ wheels = [
     { url = "https://files.pythonhosted.org/packages/af/93/06d44e08277b3b818b75bd5f25e879d7693e4b7dd3505fde89916fcc9ca2/pydantic_core-2.20.1-pp310-pypy310_pp73-win_amd64.whl", hash = "sha256:254ec27fdb5b1ee60684f91683be95e5133c994cc54e86a0b0963afa25c8f8a6", size = 1914966 },
 ]
 
+[[package]]
+name = "pydantic-settings"
+version = "2.5.2"
+source = { registry = "https://pypi.org/simple" }
+dependencies = [
+    { name = "pydantic" },
+    { name = "python-dotenv" },
+]
+sdist = { url = "https://files.pythonhosted.org/packages/68/27/0bed9dd26b93328b60a1402febc780e7be72b42847fa8b5c94b7d0aeb6d1/pydantic_settings-2.5.2.tar.gz", hash = "sha256:f90b139682bee4d2065273d5185d71d37ea46cfe57e1b5ae184fc6a0b2484ca0", size = 70938 }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/29/8d/29e82e333f32d9e2051c10764b906c2a6cd140992910b5f49762790911ba/pydantic_settings-2.5.2-py3-none-any.whl", hash = "sha256:2c912e55fd5794a59bf8c832b9de832dcfdf4778d79ff79b708744eed499a907", size = 26864 },
+]
+
 [[package]]
 name = "pydata-sphinx-theme"
 version = "0.15.4"