Restructure extensions, update corresponding docs (microsoft#3826)

jackgerrits · web-flow · commit b09e6777a462 · 2024-10-17T15:06:16.000-07:00
* Restructure extensions, update corresponding docs

* update tests, add deprecation messages

* fix tests

* update lockfile

---------
diff --git a/python/packages/autogen-core/docs/src/packages/index.md b/python/packages/autogen-core/docs/src/packages/index.md
@@ -33,7 +33,7 @@ pip install autogen-agentchat==0.4.0dev1
 ```
 
 
-[{fas}`file-code;pst-color-primary` API Reference](/reference/python/autogen_agentchat/autogen_agentchat.rst) | [{fab}`github;pst-color-primary` Source](https://github.com/microsoft/autogen/tree/main/python/packages/autogen-agentchat)
+[{fas}`circle-info;pst-color-primary` User Guide](/user-guide/agentchat-user-guide/index.md) | [{fas}`file-code;pst-color-primary` API Reference](/reference/python/autogen_agentchat/autogen_agentchat.rst) | [{fab}`python;pst-color-primary` PyPI](https://pypi.org/project/autogen-agentchat/0.4.0.dev1/) | [{fab}`github;pst-color-primary` Source](https://github.com/microsoft/autogen/tree/main/python/packages/autogen-agentchat)
 :::
 
 (pkg-info-autogen-core)=
@@ -48,7 +48,7 @@ Implements the core functionality of the AutoGen framework, providing basic buil
 pip install autogen-core==0.4.0dev1
 ```
 
-[{fas}`file-code;pst-color-primary` API Reference](/reference/python/autogen_core/autogen_core.rst) | [{fab}`github;pst-color-primary` Source](https://github.com/microsoft/autogen/tree/main/python/packages/autogen-core)
+[{fas}`circle-info;pst-color-primary` User Guide](/user-guide/core-user-guide/index.md) | [{fas}`file-code;pst-color-primary` API Reference](/reference/python/autogen_core/autogen_core.rst) | [{fab}`python;pst-color-primary` PyPI](https://pypi.org/project/autogen-core/0.4.0.dev1/) | [{fab}`github;pst-color-primary` Source](https://github.com/microsoft/autogen/tree/main/python/packages/autogen-core)
 :::
 
 (pkg-info-autogen-ext)=
@@ -63,7 +63,13 @@ Implementations of core components that interface with external services, or use
 pip install autogen-ext==0.4.0dev1
 ```
 
-[{fas}`file-code;pst-color-primary` API Reference](/reference/python/autogen_ext/autogen_ext.rst) | [{fab}`github;pst-color-primary` Source](https://github.com/microsoft/autogen/tree/main/python/packages/autogen-ext)
+Extras:
+
+- `langchain-tools` needed for {py:class}`~autogen_ext.tools.LangChainToolAdapter`
+- `azure-code-executor` needed for {py:class}`~autogen_ext.code_executors.ACADynamicSessionsCodeExecutor`
+- `docker-code-executor` needed for {py:class}`~autogen_ext.code_executors.DockerCommandLineCodeExecutor`
+
+[{fas}`circle-info;pst-color-primary` User Guide](/user-guide/extensions-user-guide/index.md) | [{fas}`file-code;pst-color-primary` API Reference](/reference/python/autogen_ext/autogen_ext.rst) | [{fab}`python;pst-color-primary` PyPI](https://pypi.org/project/autogen-ext/0.4.0.dev1/) | [{fab}`github;pst-color-primary` Source](https://github.com/microsoft/autogen/tree/main/python/packages/autogen-ext)
 :::
 
 (pkg-info-autogen-magentic-one)=
diff --git a/python/packages/autogen-core/docs/src/reference/index.md b/python/packages/autogen-core/docs/src/reference/index.md
@@ -26,8 +26,6 @@ python/autogen_core/autogen_core
 :caption: AutoGen Extensions
 
 python/autogen_ext/autogen_ext
-python/autogen_ext/autogen_ext.tools
-python/autogen_ext/autogen_ext.code_executor
 ```
 
 ::::{grid} 1 2 2 3
diff --git a/python/packages/autogen-core/docs/src/user-guide/agentchat-user-guide/guides/code-execution.ipynb b/python/packages/autogen-core/docs/src/user-guide/agentchat-user-guide/guides/code-execution.ipynb
@@ -316,7 +316,7 @@
     "from autogen_agentchat.agents import CodeExecutorAgent, CodingAssistantAgent\n",
     "from autogen_agentchat.teams import RoundRobinGroupChat, StopMessageTermination\n",
     "from autogen_core.components.models import OpenAIChatCompletionClient\n",
-    "from autogen_ext.code_executor.docker_executor import DockerCommandLineCodeExecutor\n",
+    "from autogen_ext.code_executors import DockerCommandLineCodeExecutor\n",
     "\n",
     "async with DockerCommandLineCodeExecutor(work_dir=\"coding\") as code_executor:  # type: ignore[syntax]\n",
     "    code_executor_agent = CodeExecutorAgent(\"code_executor\", code_executor=code_executor)\n",
diff --git a/python/packages/autogen-core/docs/src/user-guide/agentchat-user-guide/stocksnippet.md b/python/packages/autogen-core/docs/src/user-guide/agentchat-user-guide/stocksnippet.md
@@ -8,7 +8,7 @@ from autogen_agentchat import EVENT_LOGGER_NAME
 from autogen_agentchat.agents import CodeExecutorAgent, CodingAssistantAgent
 from autogen_agentchat.logging import ConsoleLogHandler
 from autogen_agentchat.teams import RoundRobinGroupChat, StopMessageTermination
-from autogen_ext.code_executor.docker_executor import DockerCommandLineCodeExecutor
+from autogen_ext.code_executors import DockerCommandLineCodeExecutor
 from autogen_core.components.models import OpenAIChatCompletionClient
 
 logger = logging.getLogger(EVENT_LOGGER_NAME)
diff --git a/python/packages/autogen-core/docs/src/user-guide/core-user-guide/cookbook/index.md b/python/packages/autogen-core/docs/src/user-guide/core-user-guide/cookbook/index.md
@@ -17,6 +17,5 @@ llamaindex-agent
 local-llms-ollama-litellm
 instrumenting
 topic-subscription-scenarios
-azure-container-code-executor
 structured-output-agent
 ```
diff --git a/python/packages/autogen-core/docs/src/user-guide/core-user-guide/cookbook/tool-use-with-intervention.ipynb b/python/packages/autogen-core/docs/src/user-guide/core-user-guide/cookbook/tool-use-with-intervention.ipynb
@@ -32,7 +32,7 @@
     ")\n",
     "from autogen_core.components.tool_agent import ToolAgent, ToolException, tool_agent_caller_loop\n",
     "from autogen_core.components.tools import PythonCodeExecutionTool, ToolSchema\n",
-    "from autogen_ext.code_executor.docker_executor import DockerCommandLineCodeExecutor"
+    "from autogen_ext.code_executors import DockerCommandLineCodeExecutor"
    ]
   },
   {
diff --git a/python/packages/autogen-core/docs/src/user-guide/core-user-guide/framework/command-line-code-executors.ipynb b/python/packages/autogen-core/docs/src/user-guide/core-user-guide/framework/command-line-code-executors.ipynb
@@ -51,7 +51,7 @@
     "\n",
     "from autogen_core.base import CancellationToken\n",
     "from autogen_core.components.code_executor import CodeBlock\n",
-    "from autogen_ext.code_executor.docker_executor import DockerCommandLineCodeExecutor\n",
+    "from autogen_ext.code_executors import DockerCommandLineCodeExecutor\n",
     "\n",
     "work_dir = Path(\"coding\")\n",
     "work_dir.mkdir(exist_ok=True)\n",
diff --git a/python/packages/autogen-core/docs/src/user-guide/core-user-guide/framework/tools.ipynb b/python/packages/autogen-core/docs/src/user-guide/core-user-guide/framework/tools.ipynb
@@ -45,7 +45,7 @@
    "source": [
     "from autogen_core.base import CancellationToken\n",
     "from autogen_core.components.tools import PythonCodeExecutionTool\n",
-    "from autogen_ext.code_executor.docker_executor import DockerCommandLineCodeExecutor\n",
+    "from autogen_ext.code_executors import DockerCommandLineCodeExecutor\n",
     "\n",
     "# Create the tool.\n",
     "code_executor = DockerCommandLineCodeExecutor()\n",
diff --git a/python/packages/autogen-core/docs/src/user-guide/core-user-guide/quickstart.ipynb b/python/packages/autogen-core/docs/src/user-guide/core-user-guide/quickstart.ipynb
@@ -313,7 +313,7 @@
     "\n",
     "from autogen_core.application import SingleThreadedAgentRuntime\n",
     "from autogen_core.components.models import OpenAIChatCompletionClient\n",
-    "from autogen_ext.code_executor.docker_executor import DockerCommandLineCodeExecutor\n",
+    "from autogen_ext.code_executors import DockerCommandLineCodeExecutor\n",
     "\n",
     "work_dir = tempfile.mkdtemp()\n",
     "\n",
diff --git a/python/packages/autogen-core/docs/src/user-guide/extensions-user-guide/azure-container-code-executor.ipynb b/python/packages/autogen-core/docs/src/user-guide/extensions-user-guide/azure-container-code-executor.ipynb
@@ -4,18 +4,15 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "# Azure Container Code Executor\n",
+    "# ACA Dynamic Sessions Code Executor\n",
     "\n",
     "This guide will explain the Azure Container Apps dynamic sessions in Azure Container Apps and show you how to use the Azure Container Code Executor class.\n",
     "\n",
-    "\n",
-    "## Azure Container Apps dynamic sessions\n",
-    "\n",
     "The [Azure Container Apps dynamic sessions](https://learn.microsoft.com/en-us/azure/container-apps/sessions) is a component in the Azure Container Apps service. The environment is hosted on remote Azure instances and will not execute any code locally. The interpreter is capable of executing python code in a jupyter environment with a pre-installed base of commonly used packages. [Custom environments](https://learn.microsoft.com/en-us/azure/container-apps/sessions-custom-container) can be created by users for their applications. Files can additionally be [uploaded to, or downloaded from](https://learn.microsoft.com/en-us/azure/container-apps/sessions-code-interpreter#upload-a-file-to-a-session) each session.\n",
     "\n",
     "The code interpreter can run multiple sessions of code, each of which are delineated by a session identifier string.\n",
     "\n",
-    "### Create a Container Apps Session Pool\n",
+    "## Create a Container Apps Session Pool\n",
     "\n",
     "In your Azure portal, create a new `Container App Session Pool` resource with the pool type set to `Python code interpreter` and note the `Pool management endpoint`. The format for the endpoint should be something like `https://{region}.dynamicsessions.io/subscriptions/{subscription_id}/resourceGroups/{resource_group_name}/sessionPools/{session_pool_name}`.\n",
     "\n",
diff --git a/python/packages/autogen-core/docs/src/user-guide/extensions-user-guide/index.md b/python/packages/autogen-core/docs/src/user-guide/extensions-user-guide/index.md
@@ -7,6 +7,14 @@ myst:
 
 # Extensions
 
+```{toctree}
+:maxdepth: 3
+:hidden:
+
+azure-container-code-executor
+```
+
+
 Discover community projects:
 
 ::::{grid} 1 2 2 2
diff --git a/python/packages/autogen-core/pyproject.toml b/python/packages/autogen-core/pyproject.toml
@@ -114,8 +114,7 @@ docs-clean = "rm -rf docs/build && rm -rf docs/src/reference/python/"
 
 docs-apidoc-core = "sphinx-apidoc --templatedir docs/src/_apidoc_templates --no-toc --separate --force -o docs/src/reference/python/autogen_core src/autogen_core src/autogen_core/application/protos/"
 docs-apidoc-agentchat = "sphinx-apidoc --templatedir docs/src/_apidoc_templates --no-toc --separate --force -o docs/src/reference/python/autogen_agentchat ../autogen-agentchat/src/autogen_agentchat"
-# Includes --implicit-namespaces as it is a namespace package
-docs-apidoc-ext = "sphinx-apidoc --implicit-namespaces --templatedir docs/src/_apidoc_templates --no-toc --separate --force -o docs/src/reference/python/autogen_ext ../autogen-ext/src/autogen_ext"
+docs-apidoc-ext = "sphinx-apidoc --templatedir docs/src/_apidoc_templates --no-toc --separate --force -o docs/src/reference/python/autogen_ext ../autogen-ext/src/autogen_ext ../autogen-ext/src/autogen_ext/code_executor ../autogen-ext/src/autogen_ext/tools/langchain"
 docs-apidoc-all = [
     "docs-apidoc-core",
     "docs-apidoc-agentchat",
diff --git a/python/packages/autogen-core/samples/coding_pub_sub.py b/python/packages/autogen-core/samples/coding_pub_sub.py
@@ -30,7 +30,7 @@
     UserMessage,
 )
 from autogen_core.components.tools import PythonCodeExecutionTool, Tool
-from autogen_ext.code_executor.docker_executor import DockerCommandLineCodeExecutor
+from autogen_ext.code_executors import DockerCommandLineCodeExecutor
 from common.utils import get_chat_completion_client_from_envs
 
 
diff --git a/python/packages/autogen-ext/pyproject.toml b/python/packages/autogen-ext/pyproject.toml
@@ -20,7 +20,7 @@ dependencies = [
 
 
 [project.optional-dependencies]
-langchain-tools = ["langchain >= 0.3.1"]
+langchain-tools = ["langchain_core~= 0.3.3"]
 azure-code-executor = ["azure-core"]
 docker-code-executor = ["docker~=7.0"]
 
diff --git a/python/packages/autogen-ext/src/autogen_ext/__init__.py b/python/packages/autogen-ext/src/autogen_ext/__init__.py
diff --git a/python/packages/autogen-ext/src/autogen_ext/code_executor/aca_dynamic_sessions/__init__.py b/python/packages/autogen-ext/src/autogen_ext/code_executor/aca_dynamic_sessions/__init__.py
@@ -1,4 +1,20 @@
-from ._azure_container_code_executor import AzureContainerCodeExecutor
+import warnings
+from typing import Any
+
+from ...code_executors import ACADynamicSessionsCodeExecutor
+
+
+class AzureContainerCodeExecutor(ACADynamicSessionsCodeExecutor):
+    """AzureContainerCodeExecutor has been renamed and moved to autogen_ext.code_executors.ACADynamicSessionsCodeExecutor"""
+
+    def __init__(self, *args: Any, **kwargs: Any) -> None:
+        warnings.warn(
+            "AzureContainerCodeExecutor has been renamed and moved to autogen_ext.code_executors.ACADynamicSessionsCodeExecutor",
+            DeprecationWarning,
+            stacklevel=2,
+        )
+        super().__init__(*args, **kwargs)
+
 
 __all__ = [
     "AzureContainerCodeExecutor",
diff --git a/python/packages/autogen-ext/src/autogen_ext/code_executor/docker_executor/__init__.py b/python/packages/autogen-ext/src/autogen_ext/code_executor/docker_executor/__init__.py
@@ -1,3 +1,11 @@
-from ._impl import DockerCommandLineCodeExecutor
+import warnings
+
+from ...code_executors import DockerCommandLineCodeExecutor
+
+warnings.warn(
+    "DockerCommandLineCodeExecutor moved to autogen_ext.code_executors.DockerCommandLineCodeExecutor",
+    DeprecationWarning,
+    stacklevel=2,
+)
 
 __all__ = ["DockerCommandLineCodeExecutor"]
diff --git a/python/packages/autogen-ext/src/autogen_ext/code_executors/__init__.py b/python/packages/autogen-ext/src/autogen_ext/code_executors/__init__.py
@@ -0,0 +1,4 @@
+from ._azure_container_code_executor import ACADynamicSessionsCodeExecutor, TokenProvider
+from ._docker_code_executor import DockerCommandLineCodeExecutor
+
+__all__ = ["DockerCommandLineCodeExecutor", "TokenProvider", "ACADynamicSessionsCodeExecutor"]
diff --git a/python/packages/autogen-ext/src/autogen_ext/code_executors/_azure_container_code_executor.py b/python/packages/autogen-ext/src/autogen_ext/code_executors/_azure_container_code_executor.py
@@ -1,10 +1,12 @@
 # Credit to original authors
 
+from __future__ import annotations
+
 import asyncio
 import os
 from pathlib import Path
 from string import Template
-from typing import Any, Callable, ClassVar, List, Optional, Protocol, Sequence, Union
+from typing import TYPE_CHECKING, Any, Callable, ClassVar, List, Optional, Protocol, Sequence, Union
 from uuid import uuid4
 
 import aiohttp
@@ -22,12 +24,14 @@
     get_required_packages,
     to_stub,
 )
-from azure.core.credentials import AccessToken
 from typing_extensions import ParamSpec
 
+if TYPE_CHECKING:
+    from azure.core.credentials import AccessToken
+
 PYTHON_VARIANTS = ["python", "Python", "py"]
 
-__all__ = ("AzureContainerCodeExecutor", "TokenProvider")
+__all__ = ("ACADynamicSessionsCodeExecutor", "TokenProvider")
 
 A = ParamSpec("A")
 
@@ -38,9 +42,14 @@ def get_token(
     ) -> AccessToken: ...
 
 
-class AzureContainerCodeExecutor(CodeExecutor):
+class ACADynamicSessionsCodeExecutor(CodeExecutor):
     """(Experimental) A code executor class that executes code through a an Azure
-    Container Apps instance.
+    Container Apps Dynamic Sessions instance.
+
+    .. note::
+
+        This class requires the :code:`azure-code-executor` extra for the :code:`autogen-ext` package.
+
 
     **This will execute LLM generated code on an Azure dynamic code container.**
 
diff --git a/python/packages/autogen-ext/src/autogen_ext/code_executors/_docker_code_executor.py b/python/packages/autogen-ext/src/autogen_ext/code_executors/_docker_code_executor.py
@@ -14,10 +14,6 @@
 from types import TracebackType
 from typing import Any, Callable, ClassVar, List, Optional, ParamSpec, Type, Union
 
-import asyncio_atexit
-import docker
-import docker.models
-import docker.models.containers
 from autogen_core.base import CancellationToken
 from autogen_core.components.code_executor import (
     CodeBlock,
@@ -30,7 +26,6 @@
     lang_to_cmd,
     silence_pip,
 )
-from docker.errors import ImageNotFound, NotFound
 
 if sys.version_info >= (3, 11):
     from typing import Self
@@ -55,6 +50,11 @@ async def _wait_for_ready(container: Any, timeout: int = 60, stop_time: float =
 class DockerCommandLineCodeExecutor(CodeExecutor):
     """Executes code through a command line environment in a Docker container.
 
+    .. note::
+
+        This class requires the :code:`docker-code-executor` extra for the :code:`autogen-ext` package.
+
+
     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.
@@ -156,7 +156,14 @@ def __init__(
         else:
             self._setup_functions_complete = True
 
-        self._container: docker.models.containers.Container | None = None
+        try:
+            from docker.models.containers import Container
+        except ImportError as e:
+            raise RuntimeError(
+                "Missing dependecies for DockerCommandLineCodeExecutor. Please ensure the autogen-ext package was installed with the 'docker-code-executor' extra."
+            ) from e
+
+        self._container: Container | None = None
         self._running = False
 
     @property
@@ -293,6 +300,14 @@ async def stop(self) -> None:
         if not self._running:
             return
 
+        try:
+            import docker
+            from docker.errors import NotFound
+        except ImportError as e:
+            raise RuntimeError(
+                "Missing dependecies for DockerCommandLineCodeExecutor. Please ensure the autogen-ext package was installed with the 'docker-code-executor' extra."
+            ) from e
+
         client = docker.from_env()
         try:
             container = await asyncio.to_thread(client.containers.get, self.container_name)
@@ -303,6 +318,15 @@ async def stop(self) -> None:
             self._running = False
 
     async def start(self) -> None:
+        try:
+            import asyncio_atexit
+            import docker
+            from docker.errors import ImageNotFound
+        except ImportError as e:
+            raise RuntimeError(
+                "Missing dependecies for DockerCommandLineCodeExecutor. Please ensure the autogen-ext package was installed with the 'docker-code-executor' extra."
+            ) from e
+
         # Start a container from the image, read to exec commands later
         client = docker.from_env()
 
diff --git a/python/packages/autogen-ext/src/autogen_ext/tools/__init__.py b/python/packages/autogen-ext/src/autogen_ext/tools/__init__.py
@@ -0,0 +1,3 @@
+from ._langchain_adapter import LangChainToolAdapter
+
+__all__ = ["LangChainToolAdapter"]
diff --git a/python/packages/autogen-ext/src/autogen_ext/tools/_langchain_adapter.py b/python/packages/autogen-ext/src/autogen_ext/tools/_langchain_adapter.py
diff --git a/python/packages/autogen-ext/src/autogen_ext/tools/langchain/__init__.py b/python/packages/autogen-ext/src/autogen_ext/tools/langchain/__init__.py
diff --git a/python/packages/autogen-ext/tests/code_executors/test_aca_dynamic_sessions.py b/python/packages/autogen-ext/tests/code_executors/test_aca_dynamic_sessions.py
diff --git a/python/packages/autogen-ext/tests/code_executors/test_aca_user_defined_functions.py b/python/packages/autogen-ext/tests/code_executors/test_aca_user_defined_functions.py
diff --git a/python/packages/autogen-ext/tests/code_executors/test_docker_commandline_code_executor.py b/python/packages/autogen-ext/tests/code_executors/test_docker_commandline_code_executor.py
diff --git a/python/packages/autogen-ext/tests/test_example.py b/python/packages/autogen-ext/tests/test_example.py
diff --git a/python/packages/autogen-ext/tests/test_tools.py b/python/packages/autogen-ext/tests/test_tools.py
diff --git a/python/packages/autogen-magentic-one/examples/example_coder.py b/python/packages/autogen-magentic-one/examples/example_coder.py
diff --git a/python/uv.lock b/python/uv.lock

Original file line number	Diff line number	Diff line change
`@@ -32,7 +32,7 @@`
`32`	`32`	`")\n",`
`33`	`33`	`"from autogen_core.components.tool_agent import ToolAgent, ToolException, tool_agent_caller_loop\n",`
`34`	`34`	`"from autogen_core.components.tools import PythonCodeExecutionTool, ToolSchema\n",`
`35`		`- "from autogen_ext.code_executor.docker_executor import DockerCommandLineCodeExecutor"`
	`35`	`+ "from autogen_ext.code_executors import DockerCommandLineCodeExecutor"`
`36`	`36`	`]`
`37`	`37`	`},`
`38`	`38`	`{`