Add documentation for jupyter code executor (#1809)

* Add documentation for jupyter code executor

* formatting

* move to notebooks

* formatting

* update docs, fix badge bug

* fix lints

* pprint

* stop server

autogen/coding/jupyter/base.py

@@ -7,9 +7,13 @@ class JupyterConnectionInfo:
     """(Experimental)"""
 
     host: str
+    """`str` - Host of the Jupyter gateway server"""
     use_https: bool
+    """`bool` - Whether to use HTTPS"""
     port: int
+    """`int` - Port of the Jupyter gateway server"""
     token: Optional[str]
+    """`Optional[str]` - Token for authentication. If None, no token is used"""
 
 
 @runtime_checkable
@@ -18,4 +22,5 @@ class JupyterConnectable(Protocol):
 
     @property
     def connection_info(self) -> JupyterConnectionInfo:
+        """Return the connection information for this connectable."""
         pass

autogen/coding/jupyter/jupyter_client.py

@@ -23,9 +23,12 @@
 
 
 class JupyterClient:
-    """(Experimental) A client for communicating with a Jupyter gateway server."""
-
     def __init__(self, connection_info: JupyterConnectionInfo):
+        """(Experimental) A client for communicating with a Jupyter gateway server.
+
+        Args:
+            connection_info (JupyterConnectionInfo): Connection information
+        """
         self._connection_info = connection_info
         self._session = requests.Session()
         retries = Retry(total=5, backoff_factor=0.1)

autogen/coding/jupyter/jupyter_code_executor.py

@@ -22,27 +22,6 @@
 
 
 class JupyterCodeExecutor(CodeExecutor):
-    """(Experimental) A code executor class that executes code statefully using an embedded
-    IPython kernel managed by this class.
-
-    **This will execute LLM generated code on the local machine.**
-
-    Each execution is stateful and can access variables created from previous
-    executions in the same session. The kernel must be installed before using
-    this class. The kernel can be installed using the following command:
-    `python -m ipykernel install --user --name {kernel_name}`
-    where `kernel_name` is the name of the kernel to install.
-
-    Args:
-        timeout (int): The timeout for code execution, by default 60.
-        kernel_name (str): The kernel name to use. Make sure it is installed.
-            By default, it is "python3".
-        output_dir (str): The directory to save output files, by default ".".
-        system_message_update (str): The system message update to add to the
-            agent that produces code. By default it is
-            `JupyterCodeExecutor.DEFAULT_SYSTEM_MESSAGE_UPDATE`.
-    """
-
     DEFAULT_SYSTEM_MESSAGE_UPDATE: ClassVar[
         str
     ] = """
@@ -72,24 +51,10 @@ class JupyterCodeExecutor(CodeExecutor):
 """
 
     class UserCapability:
-        """(Experimental) An AgentCapability class that gives agent ability use a stateful
-        IPython code executor. This capability can be added to an agent using
-        the `add_to_agent` method which append a system message update to the
-        agent's system message."""
-
         def __init__(self, system_message_update: str):
             self._system_message_update = system_message_update
 
         def add_to_agent(self, agent: LLMAgent) -> None:
-            """Add this capability to an agent by appending a system message
-            update to the agent's system message.
-
-            **Currently we do not check for conflicts with existing content in
-            the agent's system message.**
-
-            Args:
-                agent (LLMAgent): The agent to add the capability to.
-            """
             agent.update_system_message(agent.system_message + self._system_message_update)
 
     def __init__(
@@ -100,6 +65,19 @@ def __init__(
         output_dir: Union[Path, str] = Path("."),
         system_message_update: str = DEFAULT_SYSTEM_MESSAGE_UPDATE,
     ):
+        """(Experimental) A code executor class that executes code statefully using
+        a Jupyter server supplied to this class.
+
+        Each execution is stateful and can access variables created from previous
+        executions in the same session.
+
+        Args:
+            jupyter_server (Union[JupyterConnectable, JupyterConnectionInfo]): The Jupyter server to use.
+            timeout (int): The timeout for code execution, by default 60.
+            kernel_name (str): The kernel name to use. Make sure it is installed.
+                By default, it is "python3".
+            output_dir (str): The directory to save output files, by default ".".
+        """
         if timeout < 1:
             raise ValueError("Timeout must be greater than or equal to 1.")
 
@@ -130,8 +108,6 @@ def __init__(
 
     @property
     def user_capability(self) -> "JupyterCodeExecutor.UserCapability":
-        """(Experimental) Export a user capability for this executor that can be added to
-        an agent using the `add_to_agent` method."""
         return JupyterCodeExecutor.UserCapability(self._system_message_update)
 
     @property
@@ -142,8 +118,7 @@ def code_extractor(self) -> CodeExtractor:
     def execute_code_blocks(self, code_blocks: List[CodeBlock]) -> IPythonCodeResult:
         """(Experimental) Execute a list of code blocks and return the result.
 
-        This method executes a list of code blocks as cells in an IPython kernel
-        managed by this class.
+        This method executes a list of code blocks as cells in the Jupyter kernel.
         See: https://jupyter-client.readthedocs.io/en/stable/messaging.html
         for the message protocol.
 

autogen/coding/jupyter/local_jupyter_server.py

@@ -39,6 +39,17 @@ def __init__(
         log_max_bytes: int = 1048576,
         log_backup_count: int = 3,
     ):
+        """Runs a Jupyter Kernel Gateway server locally.
+
+        Args:
+            ip (str, optional): IP address to bind to. Defaults to "127.0.0.1".
+            port (Optional[int], optional): Port to use, if None it automatically selects a port. Defaults to None.
+            token (Union[str, GenerateToken], optional): Token to use for Jupyter server. By default will generate a token. Using None will use no token for authentication. Defaults to GenerateToken().
+            log_file (str, optional): File for Jupyter Kernel Gateway logs. Defaults to "jupyter_gateway.log".
+            log_level (str, optional): Level for Jupyter Kernel Gateway logs. Defaults to "INFO".
+            log_max_bytes (int, optional): Max logfile size. Defaults to 1048576.
+            log_backup_count (int, optional): Number of backups for rotating log. Defaults to 3.
+        """
         # Remove as soon as https://github.com/jupyter-server/kernel_gateway/issues/398 is fixed
         if sys.platform == "win32":
             raise ValueError("LocalJupyterServer is not supported on Windows due to kernelgateway bug.")

website/.gitignore

@@ -12,6 +12,7 @@ docs/reference
 /docs/notebooks
 
 docs/topics/llm_configuration.mdx
+docs/topics/code-execution/jupyter-code-executor.mdx
 
 # Misc
 .DS_Store

website/docs/topics/code-execution/_category_.json

@@ -0,0 +1,5 @@
+{
+    "position": 2,
+    "label": "Code Execution",
+    "collapsible": true
+}