Factor out documentation for execution environment configuration

- Create new `environment.md` page detailing Docker image options - Move execution environment details from `installation.md` to `environment.md`
gradion-ai · Jan 27, 2025 · c2c2817 · c2c2817
1 parent ec65a1b
commit c2c2817
Show file tree

Hide file tree

Showing 7 changed files with 82 additions and 65 deletions.
diff --git a/docs/cli.md b/docs/cli.md
@@ -21,7 +21,7 @@ To submit a multiline message, simply press `Enter`.
 
 ## Environment variables
 
-The CLI reads environment variables from a `.env` file in the current directory and passes them to the [execution environment](installation.md#execution-environment). API keys required for an agent's code action model must be either defined in the `.env` file, passed as command-line arguments, or directly set as variables in the shell.
+The CLI reads environment variables from a `.env` file in the current directory and passes them to the [execution environment](environment.md#execution-environment). API keys required for an agent's code action model must be either defined in the `.env` file, passed as command-line arguments, or directly set as variables in the shell.
 
 ### Example 1
 

diff --git a/docs/environment.md b/docs/environment.md
@@ -0,0 +1,72 @@
+# Execution environment
+
+`freeact` uses [`ipybox`](https://gradion-ai.github.io/ipybox/) as its code execution environment, providing a secure Docker-based IPython runtime. You can either create a [custom Docker image](#custom-docker-image) with your specific requirements or use [prebuilt Docker images](#prebuilt-docker-images).
+
+## Custom Docker image
+
+To build a custom `ipybox` Docker image with [`freeact-skills`](https://gradion-ai.github.io/freeact-skills/) pre-installed, create a `dependencies.txt` file:
+
+```toml title="dependencies.txt"
+freeact-skills = {version = "*", extras = ["all"]}
+# Add additional dependencies here if needed
+```
+
+!!! Note 
+
+    `dependencies.txt` must follow the [Poetry dependency specification format](https://python-poetry.org/docs/dependency-specification/).
+
+Then build the `ipybox` Docker image referencing the dependencies file:
+
+```bash
+python -m ipybox build -t gradion-ai/ipybox:custom -d dependencies.txt
+```
+
+To use the image, reference it in [`CodeExecutionContainer`][freeact.executor.CodeExecutionContainer] when creating an `ipybox` Docker container. Use the `env` argument to set any API keys required by the pre-installed skills. 
+
+## Prebuilt Docker images
+
+We provide [prebuilt Docker images](https://github.com/gradion-ai/ipybox/pkgs/container/ipybox) with variants `minimal`, `basic`, and `example`. These variants have the following dependencies installed:
+
+- `ghcr.io/gradion-ai/ipybox:minimal`: 
+
+    ```toml title="docker/dependencies-minimal.txt"
+    --8<-- "docker/dependencies-minimal.txt"
+    ```
+
+- `ghcr.io/gradion-ai/ipybox:basic`: 
+
+    ```toml title="docker/dependencies-basic.txt"
+    --8<-- "docker/dependencies-basic.txt"
+    ```
+
+- `ghcr.io/gradion-ai/ipybox:example`, used for the [tutorials](tutorials/index.md): 
+
+    ```toml title="docker/dependencies-example.txt"
+    --8<-- "docker/dependencies-example.txt"
+    ```
+
+!!! Note
+
+    Prebuilt images run with root privileges. For non-root execution, build a [custom Docker image](#custom-docker-image) (and find further details in the `ipybox` [installation guide](https://gradion-ai.github.io/ipybox/installation/)).
+
+## Installing dependencies at runtime
+
+In addition to letting an agent install required dependencies at runtime, you can install extra dependencies at runtime before launching an agent, which is useful for testing custom skills across agent sessions without rebuilding Docker images:
+
+```python
+from freeact import execution_environment
+
+async with execution_environment(ipybox_tag="ghcr.io/gradion-ai/ipybox:basic") as env:
+    # Install the serpapi package in the current environment
+    await env.executor.execute("!pip install serpapi")
+
+    # Import skill modules that depend on serpapi
+    skill_sources = await env.executor.get_module_sources(
+        module_names=["my_skill_module_1", "my_skill_module_2"],
+    )
+
+    # Initialize agent with the new skills
+    # ...
+```
+
+For production use, it's recommended to include frequently used dependencies in a custom Docker image instead.
diff --git a/docs/installation.md b/docs/installation.md
@@ -6,66 +6,10 @@
 pip install freeact
 ```
 
-## Execution environment
-
-`freeact` uses [`ipybox`](https://gradion-ai.github.io/ipybox/) as its code execution environment, providing a secure Docker-based IPython runtime. You can either use [pre-built Docker images](https://github.com/gradion-ai/ipybox/pkgs/container/ipybox) or create a [custom Docker image](#custom-docker-image) with your specific requirements.
-
-!!! Note
-
-    Pre-built images run with root privileges. For non-root execution, build a [custom Docker image](#custom-docker-image) (and find further details in the `ipybox` [installation guide](https://gradion-ai.github.io/ipybox/installation/)).
-
-### Custom Docker image
-
-To build a custom `ipybox` Docker image with [`freeact-skills`](https://gradion-ai.github.io/freeact-skills/) pre-installed, create a `dependencies.txt` file:
-
-```toml title="dependencies.txt"
-freeact-skills = {version = "*", extras = ["all"]}
-# Add additional dependencies here if needed
-```
-
-!!! Note 
-
-    `dependencies.txt` must follow the [Poetry dependency specification format](https://python-poetry.org/docs/dependency-specification/).
-
-Then build the `ipybox` Docker image referencing the dependencies file:
-
-```bash
-python -m ipybox build -t gradion-ai/ipybox:custom -d dependencies.txt
-```
+## Development installation
 
-To use the image, reference it in [`CodeExecutionContainer`][freeact.executor.CodeExecutionContainer] when creating an `ipybox` Docker container. Use the `env` argument to set any API keys required by the pre-installed skills. 
+The development installation is described in the [Development Guide](https://github.com/gradion-ai/freeact/blob/main/DEVELOPMENT.md).
 
+## Execution environment
 
-### Tutorial Docker image
-
-For running the [tutorials](tutorials/index.md), we provide a custom `ghcr.io/gradion-ai/ipybox:example` image with the following dependencies pre-installed:
-
-```toml title="dependencies.txt"
---8<-- "docker/dependencies-example.txt"
-```
-
-!!! Note
-
-    The tutorials run containers locally. Make sure you have [Docker](https://docs.docker.com/get-docker/) installed on your system.
-
-### Installing dependencies at runtime
-
-In addition to letting an agent install required dependencies at runtime, you can install extra dependencies at runtime before launching an agent, which is useful for testing custom skills across agent sessions without rebuilding Docker images:
-
-```python
-from freeact import execution_environment
-
-async with execution_environment(ipybox_tag="ghcr.io/gradion-ai/ipybox:basic") as env:
-    # Install the serpapi package in the current environment
-    await env.executor.execute("!pip install serpapi")
-
-    # Import skill modules that depend on serpapi
-    skill_sources = await env.executor.get_module_sources(
-        module_names=["my_skill_module_1", "my_skill_module_2"],
-    )
-
-    # Initialize agent with the new skills
-    # ...
-```
-
-For production use, it's recommended to include frequently used dependencies in a custom Docker image instead.
+For creating custom execution environments with your own dependency requirements, see [Execution environment](environment.md).
diff --git a/docs/tutorials/basics.md b/docs/tutorials/basics.md
@@ -2,7 +2,7 @@
 
 A `freeact` agent system consists of:
 
-- A code execution Docker container, managed by the [`CodeExecutionContainer`][freeact.executor.CodeExecutionContainer] context manager. This tutorial uses the `gradion-ai/ipybox-example` image.
+- A code execution Docker container, managed by the [`CodeExecutionContainer`][freeact.executor.CodeExecutionContainer] context manager. This tutorial uses the [prebuilt](../environment.md#prebuilt-docker-images) `ghcr.io/gradion-ai/ipybox:example` image.
 - A code executor, managed by the [`CodeExecutor`][freeact.executor.CodeExecutor] context manager. It manages an IPython kernel's lifecycle within the container and handles code execution.
 - A code action model that generates *code actions* to be executed by the executor. Models must implement the interfaces defined in the [`freeact.model`](../api/model.md) package. This tutorial uses [`Claude`][freeact.model.claude.model.Claude], configured with `claude-3-5-sonnet-20241022` as model name.
 - A [`CodeActAgent`][freeact.agent.CodeActAgent] configured with both the model and executor. It orchestrates their interaction until a final response is ready.
@@ -59,7 +59,7 @@ ANTHROPIC_API_KEY=...
 GOOGLE_API_KEY=...
 ```
 
-The tutorials use the pre-built [`ghcr.io/gradion-ai/ipybox:example`](../installation.md#tutorial-docker-image) Docker image for sandboxed code execution.
+The tutorials use the prebuilt [`ghcr.io/gradion-ai/ipybox:example`](../environment.md#prebuilt-docker-images) Docker image for sandboxed code execution.
 
 ## Running
 

diff --git a/docs/tutorials/index.md b/docs/tutorials/index.md
@@ -4,4 +4,4 @@
 2. [Skill development](skills.md) - Learn how to develop and improve custom skills in a conversation with the agent. The agent leverages its software engineering capabilities to support this process.
 3. [System extensions](extend.md) - Learn how to define custom agent behavior and constraints through system extensions in natural language. This enables human-in-the-loop workflows, proactive agents, and more.
 
-All tutorials use a pre-built [`ipybox`](https://gradion-ai.github.io/ipybox/) [tutorial Docker image](../installation.md#tutorial-docker-image) for sandboxed code execution and the `freeact` [CLI](../cli.md) for user-agent interactions. The [Basic usage](basics.md) tutorial additionally demonstrates the minimal Python code needed to implement a `freeact` agent.
+All tutorials use a [prebuilt Docker image](../environment.md#prebuilt-docker-images) for sandboxed code execution and the `freeact` [CLI](../cli.md) for user-agent interactions. The [Basic usage](basics.md) tutorial additionally demonstrates the minimal Python code needed to implement a `freeact` agent.
diff --git a/docs/tutorials/skills.md b/docs/tutorials/skills.md
@@ -68,7 +68,7 @@ The example conversation was initiated with the following `freeact.cli` command.
 ```
 
 !!! Note
-    If you've developed a custom skill that has external dependencies, you either need to build a [custom Docker image](../installation.md#custom-docker-image) with the required dependencies or need to [install them at runtime](../installation.md#installing-dependencies-at-runtime) prior to launching an agent.
+    If you've developed a custom skill that has external dependencies, you either need to build a [custom Docker image](../environment.md#custom-docker-image) with the required dependencies or need to [install them at runtime](../environment.md#installing-dependencies-at-runtime) prior to launching an agent.
 
 ### Example conversation
 

diff --git a/mkdocs.yml b/mkdocs.yml
@@ -88,6 +88,7 @@ nav:
       - Installation: installation.md
       - Building blocks: blocks.md
       - Supported models: models.md
+      - Execution environment: environment.md
       - CLI: cli.md
     - Tutorials:
       - Overview: tutorials/index.md