From ec65a1be0137bca64fafd7ae9e3d76d571d54c5d Mon Sep 17 00:00:00 2001 From: Martin Krasser Date: Sun, 26 Jan 2025 15:49:58 +0100 Subject: [PATCH 1/2] Add Docker build and push scripts for ipybox variants - Upgrade to latest freeact-skills version 0.0.7 - Create build script to generate Docker images for minimal, basic, example, and eval variants - Add dependency files for each Docker image variant - Implement push script to push Docker images with optional hex tagging - Update installation documentation to use latest freeact-skills version --- docker/build.sh | 4 ++ .../dependencies-basic.txt | 2 +- docker/dependencies-eval.txt | 6 +++ .../dependencies-example.txt | 2 +- docker/dependencies-minimal.txt | 1 + docker/push.sh | 44 +++++++++++++++++++ docs/installation.md | 4 +- 7 files changed, 59 insertions(+), 4 deletions(-) create mode 100755 docker/build.sh rename {freeact/examples => docker}/dependencies-basic.txt (58%) create mode 100644 docker/dependencies-eval.txt rename {freeact/examples => docker}/dependencies-example.txt (60%) create mode 100644 docker/dependencies-minimal.txt create mode 100755 docker/push.sh diff --git a/docker/build.sh b/docker/build.sh new file mode 100755 index 0000000..c933e75 --- /dev/null +++ b/docker/build.sh @@ -0,0 +1,4 @@ +python -m ipybox build -t ghcr.io/gradion-ai/ipybox:minimal -d docker/dependencies-minimal.txt -r +python -m ipybox build -t ghcr.io/gradion-ai/ipybox:basic -d docker/dependencies-basic.txt -r +python -m ipybox build -t ghcr.io/gradion-ai/ipybox:example -d docker/dependencies-example.txt -r +python -m ipybox build -t ghcr.io/gradion-ai/ipybox:eval -d docker/dependencies-eval.txt -r diff --git a/freeact/examples/dependencies-basic.txt b/docker/dependencies-basic.txt similarity index 58% rename from freeact/examples/dependencies-basic.txt rename to docker/dependencies-basic.txt index a930f9b..3613ab9 100644 --- a/freeact/examples/dependencies-basic.txt +++ b/docker/dependencies-basic.txt @@ -1,4 +1,4 @@ -freeact-skills = {version = "0.0.6", extras = ["search-google", "search-perplexity"]} +freeact-skills = {version = "0.0.7", extras = ["search-google", "search-perplexity"]} matplotlib = "^3.10" numpy = "^2.2" pandas = "^2.2" diff --git a/docker/dependencies-eval.txt b/docker/dependencies-eval.txt new file mode 100644 index 0000000..a8f6475 --- /dev/null +++ b/docker/dependencies-eval.txt @@ -0,0 +1,6 @@ +freeact-skills = {version = "^0.0.7", extras = ["all"]} +requests = "^2.32.0" +markdownify = "^0.14.1" +matplotlib = "^3.10.0" +numpy = "^2.2.1" +scipy = "^1.15.0" diff --git a/freeact/examples/dependencies-example.txt b/docker/dependencies-example.txt similarity index 60% rename from freeact/examples/dependencies-example.txt rename to docker/dependencies-example.txt index 8575e4d..2de54f2 100644 --- a/freeact/examples/dependencies-example.txt +++ b/docker/dependencies-example.txt @@ -1,4 +1,4 @@ -freeact-skills = {version = "0.0.6", extras = ["all"]} +freeact-skills = {version = "0.0.7", extras = ["all"]} matplotlib = "^3.10" numpy = "^2.2" pandas = "^2.2" diff --git a/docker/dependencies-minimal.txt b/docker/dependencies-minimal.txt new file mode 100644 index 0000000..0ffb1cf --- /dev/null +++ b/docker/dependencies-minimal.txt @@ -0,0 +1 @@ +freeact-skills = {version = "0.0.7", extras = ["search-google", "search-perplexity"]} diff --git a/docker/push.sh b/docker/push.sh new file mode 100755 index 0000000..2c8cab9 --- /dev/null +++ b/docker/push.sh @@ -0,0 +1,44 @@ +#!/bin/bash + +TAG_WITH_HEX=false + +# Parse command line arguments +while [[ "$#" -gt 0 ]]; do + case $1 in + --tag) TAG_WITH_HEX=true ;; + *) echo "Unknown parameter: $1"; exit 1 ;; + esac + shift +done + +# Generate random hex if tagging is enabled +if [ "$TAG_WITH_HEX" = true ]; then + RANDOM_HEX=$(openssl rand -hex 2) + echo "Generated random hex suffix: $RANDOM_HEX" +fi + +# Define image variants +VARIANTS=("minimal" "basic" "example" "eval") + +# Tag and push each variant +for variant in "${VARIANTS[@]}"; do + echo "Processing variant: $variant" + + # Push the main tag + echo "Pushing: ghcr.io/gradion-ai/ipybox:$variant" + docker push "ghcr.io/gradion-ai/ipybox:$variant" + + # Only tag and push with hex if --tag option was provided + if [ "$TAG_WITH_HEX" = true ]; then + echo "Tagging: ghcr.io/gradion-ai/ipybox:$variant-$RANDOM_HEX" + docker tag "ghcr.io/gradion-ai/ipybox:$variant" "ghcr.io/gradion-ai/ipybox:$variant-$RANDOM_HEX" + + echo "Pushing: ghcr.io/gradion-ai/ipybox:$variant-$RANDOM_HEX" + docker push "ghcr.io/gradion-ai/ipybox:$variant-$RANDOM_HEX" + fi + + echo "Completed processing $variant" + echo "-------------------" +done + +echo "All variants processed successfully" diff --git a/docs/installation.md b/docs/installation.md index e59db37..12b5c8c 100644 --- a/docs/installation.md +++ b/docs/installation.md @@ -19,7 +19,7 @@ pip install freeact 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 = "0.0.6", extras = ["all"]} +freeact-skills = {version = "*", extras = ["all"]} # Add additional dependencies here if needed ``` @@ -41,7 +41,7 @@ To use the image, reference it in [`CodeExecutionContainer`][freeact.executor.Co 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<-- "freeact/examples/dependencies-example.txt" +--8<-- "docker/dependencies-example.txt" ``` !!! Note From c2c2817d51055e253b3546432ff7e4b195e09da2 Mon Sep 17 00:00:00 2001 From: Martin Krasser Date: Mon, 27 Jan 2025 06:46:29 +0100 Subject: [PATCH 2/2] 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` --- docs/cli.md | 2 +- docs/environment.md | 72 ++++++++++++++++++++++++++++++++++++++++ docs/installation.md | 64 +++-------------------------------- docs/tutorials/basics.md | 4 +-- docs/tutorials/index.md | 2 +- docs/tutorials/skills.md | 2 +- mkdocs.yml | 1 + 7 files changed, 82 insertions(+), 65 deletions(-) create mode 100644 docs/environment.md diff --git a/docs/cli.md b/docs/cli.md index 934d966..6f74082 100644 --- 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 new file mode 100644 index 0000000..d82a763 --- /dev/null +++ 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 index 12b5c8c..c1f45d4 100644 --- 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 index 570ff53..f171c15 100644 --- 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 index 5a6d205..a5f7727 100644 --- 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 index cdce697..831128b 100644 --- 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 index 52fd9a9..c8ded24 100644 --- 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