From 135bca41de31b6e602897a694d7a08052c532f47 Mon Sep 17 00:00:00 2001 From: R3d91ll Date: Mon, 15 Jan 2024 11:15:59 -0600 Subject: [PATCH] Docker Documentation (#1251) * Updates to the Dockerfiles making them more secure. update to the installation.md file and a start.sh file for the Dockerfile.dev to start the document server. Not ready for pull request. * updates to the docker documentation * clean up before commit * added docker instructions on how to test documentation prior to commit. * fixed the title heading in the installation.md * removed alternate yarn install from Dockerfile.dev * Update sidebars.js removed un-related change from website/sidebars.js * cleaned up the lint errors from the pre-commit-check. * removed bad edit from sidebars.js * fixing git conflict with sidebars.js file * Update Installation.md added the missing sections back. However, do we still want the docker section under the Optional Dependencies? That looks like it would go better in the Dockerfiles.md file. * Update Installation.md Added mount your code back and added mount your directory for better clarity. * Update Installation.md Lint cleanup * Update Installation.md removed the relative path to samples/dockers/Dockerfiles.md with a proper URL to where it will exist * fixed bad link to Dockerfiles.md * Fix trailing whitespace and formatting issues * Update link to Dockerfiles.md * somtimes its really hard to find that lost i. * trailing whitespace and EOF issues resolved * fixed broken link * trailing space an broken link * removed broken links. will update one merged. * fixed glaring error about building an image from a particular branch Contribute.md * removed tic mark typo from contribute.md --------- Co-authored-by: Todd W Bucy --- samples/dockers/Dockerfile.base | 31 ++++--- samples/dockers/Dockerfile.dev | 41 +++++---- samples/dockers/Dockerfile.full | 34 +++++--- samples/dockers/Dockerfiles.md | 81 +++++++++++++++++ website/docs/Contribute.md | 149 ++++++++++++++++++++++---------- website/docs/Installation.md | 125 ++++++++++++++++++++------- 6 files changed, 340 insertions(+), 121 deletions(-) create mode 100644 samples/dockers/Dockerfiles.md diff --git a/samples/dockers/Dockerfile.base b/samples/dockers/Dockerfile.base index 4d08608ff290..9369df7ac93c 100644 --- a/samples/dockers/Dockerfile.base +++ b/samples/dockers/Dockerfile.base @@ -1,21 +1,26 @@ FROM python:3.11-slim-bookworm -RUN : \ - && apt-get update \ +RUN apt-get update \ && DEBIAN_FRONTEND=noninteractive apt-get install -y --no-install-recommends \ - software-properties-common \ - && DEBIAN_FRONTEND=noninteractive apt-get install -y --no-install-recommends \ - python3-venv \ + software-properties-common sudo\ && apt-get clean \ - && rm -rf /var/lib/apt/lists/* \ - && : + && rm -rf /var/lib/apt/lists/* + +# Setup a non-root user 'autogen' with sudo access +RUN adduser --disabled-password --gecos '' autogen +RUN adduser autogen sudo +RUN echo '%sudo ALL=(ALL) NOPASSWD:ALL' >> /etc/sudoers +USER autogen +WORKDIR /home/autogen -RUN python3 -m venv /venv -ENV PATH=/venv/bin:$PATH -EXPOSE 8081 +# Set environment variable if needed +# ENV OPENAI_API_KEY="{OpenAI-API-Key}" -RUN cd /venv; pip install pyautogen # Pre-load popular packages as per https://learnpython.com/blog/most-popular-python-packages/ -RUN pip install numpy pandas matplotlib seaborn scikit-learn requests urllib3 nltk pillow pytest beautifulsoup4 +RUN pip install pyautogen numpy pandas matplotlib seaborn scikit-learn requests urllib3 nltk pillow pytest beautifulsoup4 + +# Expose port +# EXPOSE 8081 -ENTRYPOINT [] +# Start Command +CMD [ "/bin/bash" ] diff --git a/samples/dockers/Dockerfile.dev b/samples/dockers/Dockerfile.dev index 07c0bb357396..62b18ade3a6c 100644 --- a/samples/dockers/Dockerfile.dev +++ b/samples/dockers/Dockerfile.dev @@ -1,33 +1,42 @@ -# basic setup +# Basic setup FROM python:3.11-slim-bookworm + +# Update and install necessary packages RUN apt-get update && apt-get -y update -RUN apt-get install -y sudo git npm +# added vim and nano for convenience +RUN apt-get install -y sudo git npm vim nano curl -# Setup user to not run as root -RUN adduser --disabled-password --gecos '' autogen-dev -RUN adduser autogen-dev sudo +# Setup a non-root user 'autogen' with sudo access +RUN adduser --disabled-password --gecos '' autogen +RUN adduser autogen sudo RUN echo '%sudo ALL=(ALL) NOPASSWD:ALL' >> /etc/sudoers -USER autogen-dev +USER autogen +WORKDIR /home/autogen + +# Set environment variable +# ENV OPENAI_API_KEY="{OpenAI-API-Key}" -# Pull repo -RUN cd /home/autogen-dev && git clone https://github.com/microsoft/autogen.git -WORKDIR /home/autogen-dev/autogen +# Clone the AutoGen repository +RUN git clone https://github.com/microsoft/autogen.git /home/autogen/autogen +WORKDIR /home/autogen/autogen -# Install autogen in editable mode (Note: extra components can be installed if needed) +# Install AutoGen in editable mode with extra components RUN sudo pip install -e .[test,teachable,lmm,retrievechat,mathchat,blendsearch] -# Install precommit hooks +# Install pre-commit hooks RUN pre-commit install -# For docs +# Setup Docusaurus and Yarn for the documentation website RUN sudo npm install --global yarn RUN sudo pip install pydoc-markdown RUN cd website RUN yarn install --frozen-lockfile --ignore-engines -# Pre-load popular packages as per https://learnpython.com/blog/most-popular-python-packages/ +# Exposes the Yarn port for Docusaurus +EXPOSE 3000 + +# Pre-load popular Python packages RUN pip install numpy pandas matplotlib seaborn scikit-learn requests urllib3 nltk pillow pytest beautifulsoup4 -# override default image starting point -CMD /bin/bash -ENTRYPOINT [] +# Set the default command to bash +CMD ["/bin/bash"] diff --git a/samples/dockers/Dockerfile.full b/samples/dockers/Dockerfile.full index 4307177d0dec..15122b2ac552 100644 --- a/samples/dockers/Dockerfile.full +++ b/samples/dockers/Dockerfile.full @@ -1,21 +1,29 @@ FROM python:3.11-slim-bookworm -RUN : \ - && apt-get update \ +# Update and install dependencies +RUN apt-get update \ && DEBIAN_FRONTEND=noninteractive apt-get install -y --no-install-recommends \ - software-properties-common \ - && DEBIAN_FRONTEND=noninteractive apt-get install -y --no-install-recommends \ - python3-venv \ + software-properties-common sudo\ && apt-get clean \ - && rm -rf /var/lib/apt/lists/* \ - && : + && rm -rf /var/lib/apt/lists/* -RUN python3 -m venv /venv -ENV PATH=/venv/bin:$PATH -EXPOSE 8081 +# Setup a non-root user 'autogen' with sudo access +RUN adduser --disabled-password --gecos '' autogen +RUN adduser autogen sudo +RUN echo '%sudo ALL=(ALL) NOPASSWD:ALL' >> /etc/sudoers +USER autogen +WORKDIR /home/autogen + +# Set environment variable if needed +# ENV OPENAI_API_KEY="{OpenAI-API-Key}" -RUN cd /venv; pip install pyautogen[teachable,lmm,retrievechat,mathchat,blendsearch] autogenra -# Pre-load popular packages as per https://learnpython.com/blog/most-popular-python-packages/ +# Install Python packages +RUN pip install --upgrade pip +RUN pip install pyautogen[teachable,lmm,retrievechat,mathchat,blendsearch] autogenra RUN pip install numpy pandas matplotlib seaborn scikit-learn requests urllib3 nltk pillow pytest beautifulsoup4 -ENTRYPOINT [] +# Expose port +EXPOSE 8081 + +# Start Command +CMD ["/bin/bash"] diff --git a/samples/dockers/Dockerfiles.md b/samples/dockers/Dockerfiles.md new file mode 100644 index 000000000000..8660364c91e6 --- /dev/null +++ b/samples/dockers/Dockerfiles.md @@ -0,0 +1,81 @@ +# README for AutoGen Docker Samples + +Welcome to the `autogen/samples/dockers` directory! Here you'll find Dockerfiles that are essential for setting up your AutoGen development environment. Each Dockerfile is tailored for different use cases and requirements. Below is a brief overview of each and how you can utilize them effectively. + +## Dockerfile Descriptions + +### Dockerfile.base + +- **Purpose**: This Dockerfile is designed for basic setups. It includes common Python libraries and essential dependencies required for general usage of AutoGen. +- **Usage**: Ideal for those just starting with AutoGen or for general-purpose applications. +- **Building the Image**: Run `docker build -f Dockerfile.base -t autogen_base_img .` in this directory. + +### Dockerfile.full + +- **Purpose**: This Dockerfile is for advanced features. It includes additional dependencies and is configured for more complex or feature-rich AutoGen applications. +- **Usage**: Suited for advanced users who need the full range of AutoGen's capabilities. +- **Building the Image**: Execute `docker build -f Dockerfile.full -t autogen_full_img .`. + +### Dockerfile.dev + +- **Purpose**: Tailored for AutoGen project developers, this Dockerfile includes tools and configurations aiding in development and contribution. +- **Usage**: Recommended for developers who are contributing to the AutoGen project. +- **Building the Image**: Run `docker build -f Dockerfile.dev -t autogen_dev_img .`. +- **Before using**: We highly encourage all potential contributors to read the [AutoGen Contributing](https://microsoft.github.io/autogen/docs/Contribute) page prior to submitting any pull requests. + +## Customizing Dockerfiles + +Feel free to modify these Dockerfiles for your specific project needs. Here are some common customizations: + +- **Adding New Dependencies**: If your project requires additional Python packages, you can add them using the `RUN pip install` command. +- **Changing the Base Image**: You may change the base image (e.g., from a Python image to an Ubuntu image) to suit your project's requirements. +- **Changing the Python version**: do you need a different version of python other than 3.11. Just update the first line of each of the Dockerfiles like so: + `FROM python:3.11-slim-bookworm` to `FROM python:3.10-slim-bookworm` +- **Setting Environment Variables**: Add environment variables using the `ENV` command for any application-specific configurations. We have prestaged the line needed to inject your OpenAI_key into the docker environment as a environmental variable. Others can be staged in the same way. Just uncomment the line. + `# ENV OPENAI_API_KEY="{OpenAI-API-Key}"` to `ENV OPENAI_API_KEY="{OpenAI-API-Key}"` +- **Need a less "Advanced" Autogen build**: If the Dockerfile.full is to much but you need more than advanced then update this line in the Dockerfile.full file. +`RUN pip install pyautogen[teachable,lmm,retrievechat,mathchat,blendsearch] autogenra` to install just what you need. `RUN pip install pyautogen[retrievechat,blendsearch] autogenra` +- **Can't Dev without your favorite CLI tool**: if you need particular OS tools to be installed in your Docker container you can add those packages here right after the sudo for the Dockerfile.base and Dockerfile.full files. In the example below we are installing net-tools and vim to the environment. + + ```code + RUN apt-get update \ + && DEBIAN_FRONTEND=noninteractive apt-get install -y --no-install-recommends \ + software-properties-common sudo net-tools vim\ + && apt-get clean \ + && rm -rf /var/lib/apt/lists/* + ``` + +### Managing Your Docker Environment + +After customizing your Dockerfile, build the Docker image using the `docker build` command as shown above. To run a container based on your new image, use: + +```bash +docker run -it -v $(pwd)/your_app:/app your_image_name +``` + +Replace `your_app` with your application directory and `your_image_name` with the name of the image you built. + +#### Closing for the Day + +- **Exit the container**: Type `exit`. +- **Stop the container**: Use `docker stop {application_project_name}`. + +#### Resuming Work + +- **Restart the container**: Use `docker start {application_project_name}`. +- **Access the container**: Execute `sudo docker exec -it {application_project_name} bash`. +- **Reactivate the environment**: Run `source /usr/src/app/autogen_env/bin/activate`. + +### Useful Docker Commands + +- **View running containers**: `docker ps -a`. +- **View Docker images**: `docker images`. +- **Restart container setup**: Stop (`docker stop my_container`), remove the container (`docker rm my_container`), and remove the image (`docker rmi my_image:latest`). + +#### Troubleshooting Common Issues + +- Check Docker daemon, port conflicts, and permissions issues. + +#### Additional Resources + +For more information on Docker usage and best practices, refer to the [official Docker documentation](https://docs.docker.com). diff --git a/website/docs/Contribute.md b/website/docs/Contribute.md index eb8305e7d91d..ab7ff96caa97 100644 --- a/website/docs/Contribute.md +++ b/website/docs/Contribute.md @@ -2,14 +2,13 @@ This project welcomes and encourages all forms of contributions, including but not limited to: -- Pushing patches. -- Code review of pull requests. -- Documentation, examples and test cases. -- Readability improvement, e.g., improvement on docstr and comments. -- Community participation in [issues](https://github.com/microsoft/autogen/issues), [discussions](https://github.com/microsoft/autogen/discussions), [discord](https://discord.gg/pAbnFJrkgZ), and [twitter](https://twitter.com/pyautogen). -- Tutorials, blog posts, talks that promote the project. -- Sharing application scenarios and/or related research. - +- Pushing patches. +- Code review of pull requests. +- Documentation, examples and test cases. +- Readability improvement, e.g., improvement on docstr and comments. +- Community participation in [issues](https://github.com/microsoft/autogen/issues), [discussions](https://github.com/microsoft/autogen/discussions), [discord](https://discord.gg/pAbnFJrkgZ), and [twitter](https://twitter.com/pyautogen). +- Tutorials, blog posts, talks that promote the project. +- Sharing application scenarios and/or related research. Most contributions require you to agree to a Contributor License Agreement (CLA) declaring that you have the right to, and actually do, grant us @@ -40,6 +39,7 @@ feedback: - Please include your **operating system type and version number**, as well as your **Python, autogen, scikit-learn versions**. The version of autogen can be found by running the following code snippet: + ```python import autogen print(autogen.__version__) @@ -49,7 +49,6 @@ print(autogen.__version__) appropriate code blocks**. See [Creating and highlighting code blocks](https://help.github.com/articles/creating-and-highlighting-code-blocks) for more details. - ## Becoming a Reviewer There is currently no formal reviewer solicitation process. Current reviewers identify reviewers from active contributors. If you are willing to become a reviewer, you are welcome to let us know on discord. @@ -58,57 +57,84 @@ There is currently no formal reviewer solicitation process. Current reviewers id ### General -* Be a member of the community and treat everyone as a member. Be inclusive. -* Help each other and encourage mutual help. -* Actively post and respond. -* Keep open communication. +- Be a member of the community and treat everyone as a member. Be inclusive. +- Help each other and encourage mutual help. +- Actively post and respond. +- Keep open communication. ### Pull Requests -* For new PR, decide whether to close without review. If not, find the right reviewers. The default reviewer is microsoft/autogen. Ask users who can benefit from the PR to review it. -* For old PR, check the blocker: reviewer or PR creator. Try to unblock. Get additional help when needed. -* When requesting changes, make sure you can check back in time because it blocks merging. -* Make sure all the checks are passed. -* For changes that require running OpenAI tests, make sure the OpenAI tests pass too. Running these tests requires approval. -* In general, suggest small PRs instead of a giant PR. -* For documentation change, request snapshot of the compiled website, or compile by yourself to verify the format. -* For new contributors who have not signed the contributing agreement, remind them to sign before reviewing. -* For multiple PRs which may have conflict, coordinate them to figure out the right order. -* Pay special attention to: - - Breaking changes. Don’t make breaking changes unless necessary. Don’t merge to main until enough headsup is provided and a new release is ready. - - Test coverage decrease. - - Changes that may cause performance degradation. Do regression test when test suites are available. - - Discourage **change to the core library** when there is an alternative. + +- For new PR, decide whether to close without review. If not, find the right reviewers. The default reviewer is microsoft/autogen. Ask users who can benefit from the PR to review it. + +- For old PR, check the blocker: reviewer or PR creator. Try to unblock. Get additional help when needed. +- When requesting changes, make sure you can check back in time because it blocks merging. +- Make sure all the checks are passed. +- For changes that require running OpenAI tests, make sure the OpenAI tests pass too. Running these tests requires approval. +- In general, suggest small PRs instead of a giant PR. +- For documentation change, request snapshot of the compiled website, or compile by yourself to verify the format. +- For new contributors who have not signed the contributing agreement, remind them to sign before reviewing. +- For multiple PRs which may have conflict, coordinate them to figure out the right order. +- Pay special attention to: + - Breaking changes. Don’t make breaking changes unless necessary. Don’t merge to main until enough headsup is provided and a new release is ready. + - Test coverage decrease. + - Changes that may cause performance degradation. Do regression test when test suites are available. + - Discourage **change to the core library** when there is an alternative. ### Issues and Discussions -* For new issues, write a reply, apply a label if relevant. Ask on discord when necessary. For roadmap issues, add to the roadmap project and encourage community discussion. Mention relevant experts when necessary. -* For old issues, provide an update or close. Ask on discord when necessary. Encourage PR creation when relevant. -* Use “good first issue” for easy fix suitable for first-time contributors. -* Use “task list” for issues that require multiple PRs. -* For discussions, create an issue when relevant. Discuss on discord when appropriate. -## Developing +- For new issues, write a reply, apply a label if relevant. Ask on discord when necessary. For roadmap issues, add to the roadmap project and encourage community discussion. Mention relevant experts when necessary. -### Setup +- For old issues, provide an update or close. Ask on discord when necessary. Encourage PR creation when relevant. +- Use “good first issue” for easy fix suitable for first-time contributors. +- Use “task list” for issues that require multiple PRs. +- For discussions, create an issue when relevant. Discuss on discord when appropriate. -```bash -git clone https://github.com/microsoft/autogen.git -pip install -e autogen -``` +## Docker for Development -### Docker +For developers contributing to the AutoGen project, we offer a specialized Docker environment. This setup is designed to streamline the development process, ensuring that all contributors work within a consistent and well-equipped environment. -We provide [Dockerfiles](https://github.com/microsoft/autogen/blob/main/samples/dockers/Dockerfile.dev) for developers to use. +### Autogen Developer Image (autogen_dev_img) -Use the following command line to build and run a docker image. +- **Purpose**: The `autogen_dev_img` is tailored for contributors to the AutoGen project. It includes a suite of tools and configurations that aid in the development and testing of new features or fixes. +- **Usage**: This image is recommended for developers who intend to contribute code or documentation to AutoGen. +- **Forking the Project**: It's advisable to fork the AutoGen GitHub project to your own repository. This allows you to make changes in a separate environment without affecting the main project. +- **Updating Dockerfile.dev**: Modify your copy of `Dockerfile.dev` as needed for your development work. +- **Submitting Pull Requests**: Once your changes are ready, submit a pull request from your branch to the upstream AutoGen GitHub project for review and integration. For more details on contributing, see the [AutoGen Contributing](https://microsoft.github.io/autogen/docs/Contribute) page. -``` -docker build -f samples/dockers/Dockerfile.dev -t autogen_dev_img https://github.com/microsoft/autogen.git#main +### Building the Developer Docker Image + +- To build the developer Docker image (`autogen_dev_img`), use the following commands: + + ```bash + docker build -f samples/dockers/Dockerfile.dev -t autogen_dev_img https://github.com/microsoft/autogen.git + ``` + +- For building the developer image built from a specific Dockerfile in a branch other than main/master + + ```bash + # clone the branch you want to work out of + git clone --branch {branch-name} https://github.com/microsoft/autogen.git -docker run -it autogen_dev_img + # cd to your new directory + cd autogen + + # build your Docker image + docker build -f samples/dockers/Dockerfile.dev -t autogen_dev-srv_img . + ``` + +### Using the Developer Docker Image + +Once you have built the `autogen_dev_img`, you can run it using the standard Docker commands. This will place you inside the containerized development environment where you can run tests, develop code, and ensure everything is functioning as expected before submitting your contributions. + +```bash +docker run -it -p 8081:3000 -v `pwd`/autogen-newcode:newstuff/ autogen_dev_img bash ``` -Detailed instructions can be found [here](Installation.md#option-1-install-and-run-autogen-in-docker). +- Note that the `pwd` is shorthand for present working directory. Thus, any path after the pwd is relative to that. If you want a more verbose method you could remove the "`pwd`/autogen-newcode" and replace it with the full path to your directory +```bash +docker run -it -p 8081:3000 -v /home/AutoGenDeveloper/autogen-newcode:newstuff/ autogen_dev_img bash +``` ### Develop in Remote Container @@ -123,6 +149,7 @@ Run `pre-commit install` to install pre-commit into your git hooks. Before you c ### Write tests Tests are automatically run via GitHub actions. There are two workflows: + 1. [build.yml](https://github.com/microsoft/autogen/blob/main/.github/workflows/build.yml) 1. [openai.yml](https://github.com/microsoft/autogen/blob/main/.github/workflows/openai.yml) @@ -131,14 +158,19 @@ The first workflow is required to pass for all PRs (and it doesn't do any OpenAI #### Run non-OpenAI tests To run the subset of the tests not depending on `openai` (and not calling LLMs)): + - Install pytest: -``` + +``` code pip install pytest ``` + - Run the tests from the `test` folder using the `--skip-openai` flag. -``` + +``` code pytest test --skip-openai ``` + - Make sure all tests pass, this is required for [build.yml](https://github.com/microsoft/autogen/blob/main/.github/workflows/build.yml) checks to pass ### Coverage @@ -175,5 +207,28 @@ yarn start The last command starts a local development server and opens up a browser window. Most changes are reflected live without having to restart the server. +To build and test documentation within a docker container. Use the Dockerfile.dev as described above to build your image + +```bash +docker build -f samples/dockers/Dockerfile.dev -t autogen_dev_img https://github.com/microsoft/autogen.git +``` + +Then start the container like so, this will log you in and ensure that Docker port 3000 is mapped to port 8081 on your local machine + +```bash +docker run -it -p 8081:3000 -v `pwd`/autogen-newcode:newstuff/ autogen_dev_img bash +``` + +Once at the CLI in Docker run the following commands: + +```bash +cd website +yarn install --frozen-lockfile --ignore-engines +pydoc-markdown +yarn start --host 0.0.0.0 --port 3000 +``` + +Once done you should be able to access the documentation at `http://127.0.0.1:8081/autogen` + Note: some tips in this guide are based off the contributor guide from [flaml](https://microsoft.github.io/FLAML/docs/Contribute). diff --git a/website/docs/Installation.md b/website/docs/Installation.md index 1c16141d8f3e..7360204692d5 100644 --- a/website/docs/Installation.md +++ b/website/docs/Installation.md @@ -1,44 +1,94 @@ # Installation +AutoGen is a versatile tool that can be installed and run in Docker or locally using a virtual environment. Below are detailed instructions for both methods. + ## Option 1: Install and Run AutoGen in Docker -[Docker](https://www.docker.com/) is a containerization platform that simplifies the setup and execution of your code. A properly built docker image could provide isolated and consistent environment to run your code securely across platforms. One option of using AutoGen is to install and run it in a docker container. You can do that in [Github codespace](https://codespaces.new/microsoft/autogen?quickstart=1) or follow the instructions below to do so. +Docker, an indispensable tool in modern software development, offers a compelling solution for AutoGen's setup. Docker allows you to create consistent environments that are portable and isolated from the host OS. With Docker, everything AutoGen needs to run, from the operating system to specific libraries, is encapsulated in a container, ensuring uniform functionality across different systems. The Dockerfiles necessary for AutoGen are conveniently located in the project's GitHub repository at [https://github.com/microsoft/autogen/tree/main/samples/dockers](https://github.com/microsoft/autogen/tree/main/samples/dockers). -#### Step 1. Install Docker. +**Pre-configured DockerFiles**: The AutoGen Project offers pre-configured Dockerfiles for your use. These Dockerfiles will run as is, however they can be modified to suit your development needs. Please see the README.md file in autogen/samples/dockers -Install docker following [this instruction](https://docs.docker.com/get-docker/). +- **autogen_base_img**: For a basic setup, you can use the `autogen_base_img` to run simple scripts or applications. This is ideal for general users or those new to AutoGen. +- **autogen_full_img**: Advanced users or those requiring more features can use `autogen_full_img`. Be aware that this version loads ALL THE THINGS and thus is very large. Take this into consideration if you build your application off of it. -For Mac users, alternatively you may choose to install [colima](https://smallsharpsoftwaretools.com/tutorials/use-colima-to-run-docker-containers-on-macos/) to run docker containers, if there is any issues with starting the docker daemon. +### Step 1: Install Docker -#### Step 2. Build a docker image +- **General Installation**: Follow the [official Docker installation instructions](https://docs.docker.com/get-docker/). This is your first step towards a containerized environment, ensuring a consistent and isolated workspace for AutoGen. -AutoGen provides [dockerfiles](https://github.com/microsoft/autogen/tree/main/samples/dockers/) that could be used to build docker images. Use the following command line to build a docker image named `autogen_img` (or other names you prefer) from one of the provided dockerfiles named `Dockerfile.base`: +- **For Mac Users**: If you encounter issues with the Docker daemon, consider using [colima](https://smallsharpsoftwaretools.com/tutorials/use-colima-to-run-docker-containers-on-macos/). Colima offers a lightweight alternative to manage Docker containers efficiently on macOS. -``` -docker build -f samples/dockers/Dockerfile.base -t autogen_img https://github.com/microsoft/autogen.git#main -``` -which includes some common python libraries and essential dependencies of AutoGen, or build from `Dockerfile.full` which include additional dependencies for more advanced features of AutoGen with the following command line: +### Step 2: Build a Docker Image -``` -docker build -f samples/dockers/Dockerfile.full -t autogen_full_img https://github.com/microsoft/autogen.git -``` -Once you build the docker image, you can use `docker images` to check whether it has been created successfully. +AutoGen now provides updated Dockerfiles tailored for different needs. Building a Docker image is akin to setting the foundation for your project's environment: -#### Step 3. Run applications built with AutoGen from a docker image. +- **Autogen Basic (dockerfile.base)**: Ideal for general use, this setup includes common Python libraries and essential dependencies. Perfect for those just starting with AutoGen. -**Mount your code to the docker image and run your application from there:** Now suppose you have your application built with AutoGen in a main script named `twoagent.py` ([example](https://github.com/microsoft/autogen/blob/main/test/twoagent.py)) in a folder named `myapp`. With the command line below, you can mount your folder and run the application in docker. + ```bash + docker build -f samples/dockers/Dockerfile.base -t autogen_base_img https://github.com/microsoft/autogen.git + ``` -```python -# Mount the local folder `myapp` into docker image and run the script named "twoagent.py" in the docker. -docker run -it -v `pwd`/myapp:/myapp autogen_img:latest python /myapp/main_twoagent.py -``` +- **Autogen Advanced (dockerfile.full)**: Advanced users or those requiring all the things that AutoGen has to offer `autogen_full_img` - + +- *Simple Script*: Run a Python script located in your local `myapp` directory. + + ```bash + docker run -it -v `pwd`/myapp:/myapp autogen_base_img:latest python /myapp/my_script.py + ``` + +- *Web Application*: If your application includes a web server running on port 5000. + + ```bash + docker run -it -p 8080:5000 -v $(pwd)/myapp:/myapp autogen_base_img:latest + ``` + +- *Data Processing*: For tasks that involve processing data stored in a local directory. + + ```bash + docker run -it -v $(pwd)/data:/data autogen_base_img:latest python /myapp/process_data.py + ``` + +#### Additional Resources + +- For more information on Docker usage and best practices, refer to the [official Docker documentation](https://docs.docker.com). + +- Details on how to use the Dockerfile.dev version can be found on the [Contributing](Contribute.md#docker) ## Option 2: Install AutoGen Locally Using Virtual Environment @@ -47,12 +97,14 @@ When installing AutoGen locally, we recommend using a virtual environment for th ### Option a: venv You can create a virtual environment with `venv` as below: + ```bash python3 -m venv pyautogen source pyautogen/bin/activate ``` The following command will deactivate the current `venv` environment: + ```bash deactivate ``` @@ -61,12 +113,14 @@ deactivate Another option is with `Conda`. You can install it by following [this doc](https://docs.conda.io/projects/conda/en/stable/user-guide/install/index.html), and then create a virtual environment as below: + ```bash conda create -n pyautogen python=3.10 # python 3.10 is recommended as it's stable and not too old conda activate pyautogen ``` The following command will deactivate the current `conda` environment: + ```bash conda deactivate ``` @@ -79,6 +133,7 @@ Another option is with `poetry`, which is a dependency manager for Python. You can install it by following [this doc](https://python-poetry.org/docs/#installation), and then create a virtual environment as below: + ```bash poetry init poetry shell @@ -87,6 +142,7 @@ poetry add pyautogen ``` The following command will deactivate the current `poetry` environment: + ```bash exit ``` @@ -117,30 +173,34 @@ Therefore, some changes are required for users of `pyautogen<0.2`. - `api_base` -> `base_url`, `request_timeout` -> `timeout` in `llm_config` and `config_list`. `max_retry_period` and `retry_wait_time` are deprecated. `max_retries` can be set for each client. - MathChat is unsupported until it is tested in future release. - `autogen.Completion` and `autogen.ChatCompletion` are deprecated. The essential functionalities are moved to `autogen.OpenAIWrapper`: + ```python from autogen import OpenAIWrapper client = OpenAIWrapper(config_list=config_list) response = client.create(messages=[{"role": "user", "content": "2+2="}]) print(client.extract_text_or_completion_object(response)) ``` + - Inference parameter tuning and inference logging features are currently unavailable in `OpenAIWrapper`. Logging will be added in a future release. Inference parameter tuning can be done via [`flaml.tune`](https://microsoft.github.io/FLAML/docs/Use-Cases/Tune-User-Defined-Function). - `seed` in autogen is renamed into `cache_seed` to accommodate the newly added `seed` param in openai chat completion api. `use_cache` is removed as a kwarg in `OpenAIWrapper.create()` for being automatically decided by `cache_seed`: int | None. The difference between autogen's `cache_seed` and openai's `seed` is that: - * autogen uses local disk cache to guarantee the exactly same output is produced for the same input and when cache is hit, no openai api call will be made. - * openai's `seed` is a best-effort deterministic sampling with no guarantee of determinism. When using openai's `seed` with `cache_seed` set to None, even for the same input, an openai api call will be made and there is no guarantee for getting exactly the same output. - + - autogen uses local disk cache to guarantee the exactly same output is produced for the same input and when cache is hit, no openai api call will be made. + - openai's `seed` is a best-effort deterministic sampling with no guarantee of determinism. When using openai's `seed` with `cache_seed` set to None, even for the same input, an openai api call will be made and there is no guarantee for getting exactly the same output. ### Optional Dependencies -- #### docker + +- #### Docker Even if you install AutoGen locally, we highly recommend using Docker for [code execution](FAQ.md#enable-python-3-docker-image). To use docker for code execution, you also need to install the python package `docker`: + ```bash pip install docker ``` You might want to override the default docker image used for code execution. To do that set `use_docker` key of `code_execution_config` property to the name of the image. E.g.: + ```python user_proxy = autogen.UserProxyAgent( name="agent", @@ -156,6 +216,7 @@ Otherwise, reply CONTINUE, or the reason why the task is not solved yet.""" - #### blendsearch `pyautogen<0.2` offers a cost-effective hyperparameter optimization technique [EcoOptiGen](https://arxiv.org/abs/2303.04673) for tuning Large Language Models. Please install with the [blendsearch] option to use it. + ```bash pip install "pyautogen[blendsearch]<0.2" ``` @@ -169,6 +230,7 @@ Example notebooks: - #### retrievechat `pyautogen` supports retrieval-augmented generation tasks such as question answering and code generation with RAG agents. Please install with the [retrievechat] option to use it. + ```bash pip install "pyautogen[retrievechat]" ``` @@ -190,21 +252,20 @@ Example notebooks: [Automated Code Generation and Question Answering with Qdrant based Retrieval Augmented Agents](https://github.com/microsoft/autogen/blob/main/notebook/agentchat_qdrant_RetrieveChat.ipynb) - - #### Teachability To use Teachability, please install AutoGen with the [teachable] option. + ```bash pip install "pyautogen[teachable]" ``` Example notebook: [Chatting with a teachable agent](https://github.com/microsoft/autogen/blob/main/notebook/agentchat_teachability.ipynb) - - - #### Large Multimodal Model (LMM) Agents We offered Multimodal Conversable Agent and LLaVA Agent. Please install with the [lmm] option to use it. + ```bash pip install "pyautogen[lmm]" ``` @@ -213,10 +274,10 @@ Example notebooks: [LLaVA Agent](https://github.com/microsoft/autogen/blob/main/notebook/agentchat_lmm_llava.ipynb) - - #### mathchat `pyautogen<0.2` offers an experimental agent for math problem solving. Please install with the [mathchat] option to use it. + ```bash pip install "pyautogen[mathchat]<0.2" ```