From 5155213101c74b06c11576ae208214f9165bb071 Mon Sep 17 00:00:00 2001 From: Todd W Bucy Date: Sat, 13 Jan 2024 22:10:10 -0600 Subject: [PATCH 01/24] 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. --- samples/dockers/Dockerfile.base | 31 ++-- samples/dockers/Dockerfile.dev | 65 ++++++--- samples/dockers/Dockerfile.full | 34 +++-- website/docs/Installation.md | 243 ++++++++------------------------ website/sidebars.js | 6 +- website/start.sh | 3 + 6 files changed, 154 insertions(+), 228 deletions(-) create mode 100644 website/start.sh diff --git a/samples/dockers/Dockerfile.base b/samples/dockers/Dockerfile.base index 4d08608ff290..314a852167d6 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" ] \ No newline at end of file diff --git a/samples/dockers/Dockerfile.dev b/samples/dockers/Dockerfile.dev index 07c0bb357396..10f09b19abf9 100644 --- a/samples/dockers/Dockerfile.dev +++ b/samples/dockers/Dockerfile.dev @@ -1,33 +1,60 @@ -# 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 +RUN git clone https://github.com/r3d91ll/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 -RUN sudo npm install --global yarn -RUN sudo pip install pydoc-markdown -RUN cd website +# Install tools for documentation +# Using the Debian package for Yarn is a more reliable way to install it +RUN curl -sS https://dl.yarnpkg.com/debian/pubkey.gpg | sudo apt-key add - +RUN echo "deb https://dl.yarnpkg.com/debian/ stable main" | sudo tee /etc/apt/sources.list.d/yarn.list +RUN sudo apt-get update && sudo apt-get install -y yarn +RUN sudo pip install pydoc-markdown + +# Set up the documentation environment +WORKDIR /home/autogen/autogen/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 + +# Assuming your Docker build context is the root of the 'autogen' project +# and 'start.sh' is located in the 'autogen/website' directory +# Copy the start script from the autogen/website directory to the current working directory +# and change its ownership to 'autogen' +COPY --chown=autogen:autogen website/start.sh . +# Make the start script executable +RUN chmod +x start.sh +# Set the default command to execute the start script +#CMD ["./start.sh"] +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/website/docs/Installation.md b/website/docs/Installation.md index 647986e9f37d..83d72be2b31e 100644 --- a/website/docs/Installation.md +++ b/website/docs/Installation.md @@ -1,226 +1,105 @@ -# Installation +# AutoGen Installation Guide + +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. +### Step 1: Install Docker -#### Step 1. Install Docker. +- Follow the [official Docker installation instructions](https://docs.docker.com/get-docker/). +- For Mac users: Consider using [colima](https://smallsharpsoftwaretools.com/tutorials/use-colima-to-run-docker-containers-on-macos/) as an alternative if you encounter issues with the Docker daemon. -Install docker following [this instruction](https://docs.docker.com/get-docker/). +### Step 2: Build a Docker Image -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. +AutoGen provides Dockerfiles for building docker images. Choose one based on your needs: -#### Step 2. Build a docker image +- For a basic setup (includes common Python libraries and essential dependencies): -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`: + ```bash + docker build -f samples/dockers/Dockerfile.base -t autogen_img https://github.com/microsoft/autogen.git#main + ``` + +- For advanced features (includes additional dependencies): -``` -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: + ```bash + docker build -f samples/dockers/Dockerfile.full -t autogen_full_img https://github.com/microsoft/autogen.git + ``` -``` -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. + To check if the image is created successfully, use `docker images`. -#### Step 3. Run applications built with AutoGen from a docker image. +### Step 3: Run AutoGen Applications from Docker Image -**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 mont your folder and run the application in docker. +To run an application built with AutoGen (e.g., a script named `twoagent.py`), mount your code and execute it in Docker: -```python -# Mount the local folder `myapp` into docker image and run the script named "twoagent.py" in the docker. +```bash docker run -it -v `pwd`/myapp:/myapp autogen_img:latest python /myapp/main_twoagent.py ``` - - ## Option 2: Install AutoGen Locally Using Virtual Environment -When installing AutoGen locally, we recommend using a virtual environment for the installation. This will ensure that the dependencies for AutoGen are isolated from the rest of your system. - ### Option a: venv -You can create a virtual environment with `venv` as below: -```bash -python3 -m venv pyautogen -source pyautogen/bin/activate -``` +1. Create and activate a virtual environment: -The following command will deactivate the current `venv` environment: -```bash -deactivate -``` + ```bash + python3 -m venv pyautogen + source pyautogen/bin/activate + ``` + +2. To exit the virtual environment: + + ```bash + deactivate + ``` ### Option b: conda -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 -``` +1. Create and activate a Conda environment: -The following command will deactivate the current `conda` environment: -```bash -conda deactivate -``` + ```bash + conda create -n pyautogen python=3.10 + conda activate pyautogen + ``` -### Option c: poetry +2. To exit Conda environment: -Another option is with `poetry`, which is a dependency manager for Python. + ```bash + conda deactivate + ``` -[Poetry](https://python-poetry.org/docs/) is a tool for dependency management and packaging in Python. It allows you to declare the libraries your project depends on and it will manage (install/update) them for you. Poetry offers a lockfile to ensure repeatable installs, and can build your project for distribution. +### Option c: poetry -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 +1. Initialize and activate a Poetry environment: -poetry add pyautogen -``` + ```bash + poetry init + poetry shell + poetry add pyautogen + ``` -The following command will deactivate the current `poetry` environment: -```bash -exit -``` +2. To exit the Poetry environment: -Now, you're ready to install AutoGen in the virtual environment you've just created. + ```bash + exit + ``` -## Python +## Python Version Compatibility -AutoGen requires **Python version >= 3.8, < 3.12**. It can be installed from pip: +AutoGen requires **Python version >= 3.8, < 3.12**. Install it using pip: ```bash pip install pyautogen ``` -`pyautogen<0.2` requires `openai<1`. Starting from pyautogen v0.2, `openai>=1` is required. - - - -### Migration guide to v0.2 - -openai v1 is a total rewrite of the library with many breaking changes. For example, the inference requires instantiating a client, instead of using a global class method. -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. - +Refer to the [Migration guide to v0.2](/autogen/docs/Installation#migration-guide-to-v0.2) for updates and changes. ### Optional Dependencies -- #### 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", - human_input_mode="TERMINATE", - max_consecutive_auto_reply=10, - code_execution_config={"work_dir":"_output", "use_docker":"python:3"}, - llm_config=llm_config, - system_message=""""Reply TERMINATE if the task has been solved at full satisfaction. -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" -``` - -Example notebooks: - -[Optimize for Code Generation](https://github.com/microsoft/autogen/blob/main/notebook/oai_completion.ipynb) - -[Optimize for Math](https://github.com/microsoft/autogen/blob/main/notebook/oai_chatgpt_gpt4.ipynb) - -- #### 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]" -``` - -RetrieveChat can handle various types of documents. By default, it can process -plain text and PDF files, including formats such as 'txt', 'json', 'csv', 'tsv', -'md', 'html', 'htm', 'rtf', 'rst', 'jsonl', 'log', 'xml', 'yaml', 'yml' and 'pdf'. -If you install [unstructured](https://unstructured-io.github.io/unstructured/installation/full_installation.html) -(`pip install "unstructured[all-docs]"`), additional document types such as 'docx', -'doc', 'odt', 'pptx', 'ppt', 'xlsx', 'eml', 'msg', 'epub' will also be supported. - -You can find a list of all supported document types by using `autogen.retrieve_utils.TEXT_FORMATS`. - -Example notebooks: - -[Automated Code Generation and Question Answering with Retrieval Augmented Agents](https://github.com/microsoft/autogen/blob/main/notebook/agentchat_RetrieveChat.ipynb) - -[Group Chat with Retrieval Augmented Generation (with 5 group member agents and 1 manager agent)](https://github.com/microsoft/autogen/blob/main/notebook/agentchat_groupchat_RAG.ipynb) - -[Automated Code Generation and Question Answering with Qdrant based Retrieval Augmented Agents](https://github.com/microsoft/autogen/blob/main/notebook/agentchat_qdrant_RetrieveChat.ipynb) +- **Docker**: Highly recommended for code execution. Install with `pip install docker`. +- **Blendsearch**: For hyperparameter optimization. Install with `pip install "pyautogen[blendsearch]<0.2"`. +- **Retrievechat**: For retrieval-augmented tasks. Install with `pip install "pyautogen[retrievechat]"`. +- **Teachability**: For teachable agents. Install with `pip install "pyautogen[teachable]"`. +- **LMM Agents**: For multimodal conversable agents. Install with `pip install "pyautogen[lmm]"`. +- **Mathchat**: For math problem-solving agents. Install with `pip install "pyautogen[mathchat]<0.2"`. -- #### 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]" -``` - -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" -``` - -Example notebooks: -[Using MathChat to Solve Math Problems](https://github.com/microsoft/autogen/blob/main/notebook/agentchat_MathChat.ipynb) diff --git a/website/sidebars.js b/website/sidebars.js index 98b6c26d2803..f604704a8de8 100644 --- a/website/sidebars.js +++ b/website/sidebars.js @@ -18,5 +18,9 @@ 'Research', ], // pydoc-markdown auto-generated markdowns from docstrings - referenceSideBar: [require("./docs/reference/sidebar.json")] + + // commenting out the reference sidebar allows the docs to be built + // the reference sidebar is not found in the docs folder + // referenceSideBar: [require("./docs/reference/sidebar.json")] + }; diff --git a/website/start.sh b/website/start.sh new file mode 100644 index 000000000000..395cf1301377 --- /dev/null +++ b/website/start.sh @@ -0,0 +1,3 @@ +#!/bin/bash +yarn start --host 0.0.0.0 # Start Yarn in the background +/bin/bash # Keep the shell open From 87b5a8e81d59a136c85b574e05920cee6688e4f0 Mon Sep 17 00:00:00 2001 From: Todd W Bucy Date: Sun, 14 Jan 2024 11:35:03 -0600 Subject: [PATCH 02/24] updates to the docker documentation --- samples/dockers/Dockerfile.dev | 38 +++++------ samples/dockers/Dockerfiles.md | 81 +++++++++++++++++++++++ website/docs/Contribute.md | 114 ++++++++++++++++++++++----------- website/docs/Installation.md | 79 ++++++++++++++++++----- 4 files changed, 235 insertions(+), 77 deletions(-) create mode 100644 samples/dockers/Dockerfiles.md diff --git a/samples/dockers/Dockerfile.dev b/samples/dockers/Dockerfile.dev index 10f09b19abf9..95e03f986b7e 100644 --- a/samples/dockers/Dockerfile.dev +++ b/samples/dockers/Dockerfile.dev @@ -17,8 +17,7 @@ WORKDIR /home/autogen # ENV OPENAI_API_KEY="{OpenAI-API-Key}" # Clone the AutoGen repository -# RUN git clone https://github.com/microsoft/autogen.git /home/autogen/autogen -RUN git clone https://github.com/r3d91ll/autogen.git /home/autogen/autogen +RUN git clone https://github.com/microsoft/autogen.git /home/autogen/autogen WORKDIR /home/autogen/autogen # Install AutoGen in editable mode with extra components @@ -27,17 +26,24 @@ RUN sudo pip install -e .[test,teachable,lmm,retrievechat,mathchat,blendsearch] # Install pre-commit hooks RUN pre-commit install -# Install tools for documentation -# Using the Debian package for Yarn is a more reliable way to install it -RUN curl -sS https://dl.yarnpkg.com/debian/pubkey.gpg | sudo apt-key add - -RUN echo "deb https://dl.yarnpkg.com/debian/ stable main" | sudo tee /etc/apt/sources.list.d/yarn.list -RUN sudo apt-get update && sudo apt-get install -y yarn -RUN sudo pip install pydoc-markdown - -# Set up the documentation environment -WORKDIR /home/autogen/autogen/website/ +# 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 +# Alternate method for installing tools for documentation +# The Debian package for Yarn is stable and is not as likely to have breaking changes +# However, it is not the latest version of Yarn and so may not be compatible with +# the latest version of Docusaurus installed on the website. +# your mileage may vary +# RUN curl -sS https://dl.yarnpkg.com/debian/pubkey.gpg | sudo apt-key add - +# RUN echo "deb https://dl.yarnpkg.com/debian/ stable main" | sudo tee /etc/apt/sources.list.d/yarn.list +# RUN sudo apt-get update && sudo apt-get install -y yarn +# RUN sudo pip install pydoc-markdown +# RUN cd /home/autogen/autogen/website/ +# RUN yarn install --frozen-lockfile --ignore-engines + # Exposes the Yarn port for Docusaurus EXPOSE 3000 @@ -45,16 +51,6 @@ EXPOSE 3000 RUN pip install numpy pandas matplotlib seaborn scikit-learn requests urllib3 nltk pillow pytest beautifulsoup4 # Set the default command to bash - -# Assuming your Docker build context is the root of the 'autogen' project -# and 'start.sh' is located in the 'autogen/website' directory -# Copy the start script from the autogen/website directory to the current working directory -# and change its ownership to 'autogen' -COPY --chown=autogen:autogen website/start.sh . -# Make the start script executable -RUN chmod +x start.sh -# Set the default command to execute the start script -#CMD ["./start.sh"] CMD ["/bin/bash"] diff --git a/samples/dockers/Dockerfiles.md b/samples/dockers/Dockerfiles.md new file mode 100644 index 000000000000..070f587e9fd0 --- /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 advaned 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). \ No newline at end of file diff --git a/website/docs/Contribute.md b/website/docs/Contribute.md index eb8305e7d91d..ed4f0e978614 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,33 +57,35 @@ 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 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. +- 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 @@ -95,20 +96,49 @@ git clone https://github.com/microsoft/autogen.git pip install -e autogen ``` -### Docker +## Docker for Development -We provide [Dockerfiles](https://github.com/microsoft/autogen/blob/main/samples/dockers/Dockerfile.dev) for developers to use. +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. -Use the following command line to build and run a docker image. +### Autogen Developer Image (`autogen_dev_img`) -``` -docker build -f samples/dockers/Dockerfile.dev -t autogen_dev_img https://github.com/microsoft/autogen.git#main +- **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. +- **Setup**: + - **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. + +### Building the Developer Docker Image + +- To build the developer Docker image (`autogen_dev_img`), use the following commands: + + ```bash + # Building the dev image for general development + 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 just append a `#{branch-name}` as shown below + + ```bash + docker build -f samples/dockers/Dockerfile.dev -t autogen_dev_img 'https://github.com/microsoft/autogen.git#dockerDocs' + ``` + +### 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. -docker run -it autogen_dev_img +- This will start your Docker container and allow Dockers port 3000 to be mapped to your workstation on port 8081. It wll also mount the local directory of autogen-newcode to the docker directory of /home/autogen/newstuff. And once running it will put you at the CLI in the /home/autogen/ directory. + +```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. 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 +153,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 +162,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 diff --git a/website/docs/Installation.md b/website/docs/Installation.md index 83d72be2b31e..620af4ee0f31 100644 --- a/website/docs/Installation.md +++ b/website/docs/Installation.md @@ -4,36 +4,83 @@ AutoGen is a versatile tool that can be installed and run in Docker or locally u ## Option 1: Install and Run AutoGen in Docker +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). For more details on customizing the Dockerfiles, see the [Docker Samples README](../samples/dockers/Dockerfiles.md). + +**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 + +- **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. + ### Step 1: Install Docker -- Follow the [official Docker installation instructions](https://docs.docker.com/get-docker/). -- For Mac users: Consider using [colima](https://smallsharpsoftwaretools.com/tutorials/use-colima-to-run-docker-containers-on-macos/) as an alternative if you encounter issues with the Docker daemon. +- **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. + +- **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. ### Step 2: Build a Docker Image -AutoGen provides Dockerfiles for building docker images. Choose one based on your needs: +AutoGen now provides updated Dockerfiles tailored for different needs. Building a Docker image is akin to setting the foundation for your project's environment: -- For a basic setup (includes common Python libraries and essential dependencies): +- **Autogen Basic (dockerfile.base)**: Ideal for general use, this setup includes common Python libraries and essential dependencies. Perfect for those just starting with AutoGen. ```bash - docker build -f samples/dockers/Dockerfile.base -t autogen_img https://github.com/microsoft/autogen.git#main + docker build -f samples/dockers/Dockerfile.base -t autogen_base_img https://github.com/microsoft/autogen.git ``` - -- For advanced features (includes additional dependencies): - ```bash - docker build -f samples/dockers/Dockerfile.full -t autogen_full_img https://github.com/microsoft/autogen.git - ``` +- **Autogen Advanced (dockerfile.full)**: Advanced users or those requiring all the things that AutoGen has to offer `autogen_full_img` - To check if the image is created successfully, use `docker images`. + ```bash + docker build -f samples/dockers/Dockerfile.full -t autogen_full_img https://github.com/microsoft/autogen.git + ``` ### Step 3: Run AutoGen Applications from Docker Image -To run an application built with AutoGen (e.g., a script named `twoagent.py`), mount your code and execute it in Docker: +Here's how you can run an application built with AutoGen, using the Docker image: -```bash -docker run -it -v `pwd`/myapp:/myapp autogen_img:latest python /myapp/main_twoagent.py -``` +1. **Mount Your Code**: Use the Docker `-v` flag to mount your local application directory to the Docker container. This allows you to develop on your local machine while running the code in a consistent Docker environment. For example: + + ```bash + docker run -it -v $(pwd)/myapp:/home/autogen/autogen/myapp autogen_base_img:latest python /home/autogen/autogen/myapp/main.py + ``` + + Here, `$(pwd)/myapp` is your local directory, and `/home/autogen/autogen/myapp` is the path in the Docker container where your code will be located. + +2. **Port Mapping**: If your application requires a specific port, use the `-p` flag to map the container's port to your host. For instance, if your app runs on port 3000 inside Docker and you want it accessible on port 8080 on your host machine: + + ```bash + docker run -it -p 8080:3000 -v $(pwd)/myapp:/myapp autogen_base_img:latest python /myapp + ``` + + In this command, `-p 8080:3000` maps port 3000 from the container to port 8080 on your local machine. + +3. **Examples of Running Different Applications**: +`docker run -it -p {WorkstationPortNum}:{DockerPortNum} -v {WorkStation_Dir}:{Docker_DIR} {name_of_the_image}:latest` + +- *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 for managing and interacting with your AutoGen Docker containers can be found in the [Docker Samples README](../samples/dockers/Dockerfiles.md). + +- 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 @@ -101,5 +148,3 @@ Refer to the [Migration guide to v0.2](/autogen/docs/Installation#migration-guid - **Teachability**: For teachable agents. Install with `pip install "pyautogen[teachable]"`. - **LMM Agents**: For multimodal conversable agents. Install with `pip install "pyautogen[lmm]"`. - **Mathchat**: For math problem-solving agents. Install with `pip install "pyautogen[mathchat]<0.2"`. - - From 0919fb20ab6bc31aaf38ed97c7a14079bc83fc03 Mon Sep 17 00:00:00 2001 From: Todd W Bucy Date: Sun, 14 Jan 2024 11:58:46 -0600 Subject: [PATCH 03/24] clean up before commit --- website/docs/Contribute.md | 17 +++++------------ website/start.sh | 3 --- 2 files changed, 5 insertions(+), 15 deletions(-) delete mode 100644 website/start.sh diff --git a/website/docs/Contribute.md b/website/docs/Contribute.md index ed4f0e978614..3ff33b8f552a 100644 --- a/website/docs/Contribute.md +++ b/website/docs/Contribute.md @@ -64,7 +64,8 @@ There is currently no formal reviewer solicitation process. Current reviewers id ### 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 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. @@ -81,21 +82,13 @@ There is currently no formal reviewer solicitation process. Current reviewers id ### 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 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 - -### Setup - -```bash -git clone https://github.com/microsoft/autogen.git -pip install -e autogen -``` - ## Docker for Development 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. @@ -134,7 +127,7 @@ Once you have built the `autogen_dev_img`, you can run it using the standard Doc docker run -it -p 8081:3000 -v `pwd`/autogen-newcode:newstuff/ autogen_dev_img bash ``` -- Note that the `pwd` is shorthand for present working directory. If you want a more verbose method you could remove the "`pwd`/autogen-newcode" and replace it with the full path to your directory +- 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 diff --git a/website/start.sh b/website/start.sh deleted file mode 100644 index 395cf1301377..000000000000 --- a/website/start.sh +++ /dev/null @@ -1,3 +0,0 @@ -#!/bin/bash -yarn start --host 0.0.0.0 # Start Yarn in the background -/bin/bash # Keep the shell open From 98491b05a1a976edfab3166e4434cd87b918a055 Mon Sep 17 00:00:00 2001 From: Todd W Bucy Date: Sun, 14 Jan 2024 12:55:21 -0600 Subject: [PATCH 04/24] added docker instructions on how to test documentation prior to commit. --- website/docs/Contribute.md | 24 ++++++++++++++++++++++++ 1 file changed, 24 insertions(+) diff --git a/website/docs/Contribute.md b/website/docs/Contribute.md index 3ff33b8f552a..bef64d1cabcf 100644 --- a/website/docs/Contribute.md +++ b/website/docs/Contribute.md @@ -204,5 +204,29 @@ 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 containter. 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 documentaion 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). From a93d12f72fff182db1fefef44910a9389ab81a46 Mon Sep 17 00:00:00 2001 From: Todd W Bucy Date: Sun, 14 Jan 2024 13:28:54 -0600 Subject: [PATCH 05/24] fixed the title heading in the installation.md --- website/docs/Installation.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/website/docs/Installation.md b/website/docs/Installation.md index 620af4ee0f31..85f357607066 100644 --- a/website/docs/Installation.md +++ b/website/docs/Installation.md @@ -1,4 +1,4 @@ -# AutoGen Installation Guide +# 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. From 351e050bbe07cf18dcf6ff63984924ada4a1f8bc Mon Sep 17 00:00:00 2001 From: Todd W Bucy Date: Sun, 14 Jan 2024 13:42:48 -0600 Subject: [PATCH 06/24] removed alternate yarn install from Dockerfile.dev --- samples/dockers/Dockerfile.dev | 12 ------------ 1 file changed, 12 deletions(-) diff --git a/samples/dockers/Dockerfile.dev b/samples/dockers/Dockerfile.dev index 95e03f986b7e..9b610a47a87f 100644 --- a/samples/dockers/Dockerfile.dev +++ b/samples/dockers/Dockerfile.dev @@ -32,18 +32,6 @@ RUN sudo pip install pydoc-markdown RUN cd website RUN yarn install --frozen-lockfile --ignore-engines -# Alternate method for installing tools for documentation -# The Debian package for Yarn is stable and is not as likely to have breaking changes -# However, it is not the latest version of Yarn and so may not be compatible with -# the latest version of Docusaurus installed on the website. -# your mileage may vary -# RUN curl -sS https://dl.yarnpkg.com/debian/pubkey.gpg | sudo apt-key add - -# RUN echo "deb https://dl.yarnpkg.com/debian/ stable main" | sudo tee /etc/apt/sources.list.d/yarn.list -# RUN sudo apt-get update && sudo apt-get install -y yarn -# RUN sudo pip install pydoc-markdown -# RUN cd /home/autogen/autogen/website/ -# RUN yarn install --frozen-lockfile --ignore-engines - # Exposes the Yarn port for Docusaurus EXPOSE 3000 From 3acdc7e138eb2053146ed6054bc69b4d790dceb5 Mon Sep 17 00:00:00 2001 From: R3d91ll Date: Sun, 14 Jan 2024 14:14:07 -0600 Subject: [PATCH 07/24] Update sidebars.js removed un-related change from website/sidebars.js --- website/sidebars.js | 6 +----- 1 file changed, 1 insertion(+), 5 deletions(-) diff --git a/website/sidebars.js b/website/sidebars.js index f604704a8de8..98b6c26d2803 100644 --- a/website/sidebars.js +++ b/website/sidebars.js @@ -18,9 +18,5 @@ 'Research', ], // pydoc-markdown auto-generated markdowns from docstrings - - // commenting out the reference sidebar allows the docs to be built - // the reference sidebar is not found in the docs folder - // referenceSideBar: [require("./docs/reference/sidebar.json")] - + referenceSideBar: [require("./docs/reference/sidebar.json")] }; From 1c863c3babd5379d7f343c2bf5ae24a1c06dff06 Mon Sep 17 00:00:00 2001 From: Todd W Bucy Date: Sun, 14 Jan 2024 14:27:14 -0600 Subject: [PATCH 08/24] cleaned up the lint errors from the pre-commit-check. --- samples/dockers/Dockerfile.base | 2 +- samples/dockers/Dockerfiles.md | 2 +- website/docs/Installation.md | 4 ++-- 3 files changed, 4 insertions(+), 4 deletions(-) diff --git a/samples/dockers/Dockerfile.base b/samples/dockers/Dockerfile.base index 314a852167d6..9369df7ac93c 100644 --- a/samples/dockers/Dockerfile.base +++ b/samples/dockers/Dockerfile.base @@ -23,4 +23,4 @@ RUN pip install pyautogen numpy pandas matplotlib seaborn scikit-learn requests # EXPOSE 8081 # Start Command -CMD [ "/bin/bash" ] \ No newline at end of file +CMD [ "/bin/bash" ] diff --git a/samples/dockers/Dockerfiles.md b/samples/dockers/Dockerfiles.md index 070f587e9fd0..926f5d863097 100644 --- a/samples/dockers/Dockerfiles.md +++ b/samples/dockers/Dockerfiles.md @@ -78,4 +78,4 @@ Replace `your_app` with your application directory and `your_image_name` with th #### Additional Resources -For more information on Docker usage and best practices, refer to the [official Docker documentation](https://docs.docker.com). \ No newline at end of file +For more information on Docker usage and best practices, refer to the [official Docker documentation](https://docs.docker.com). diff --git a/website/docs/Installation.md b/website/docs/Installation.md index 85f357607066..3ceb84ef538f 100644 --- a/website/docs/Installation.md +++ b/website/docs/Installation.md @@ -30,7 +30,7 @@ AutoGen now provides updated Dockerfiles tailored for different needs. Building - **Autogen Advanced (dockerfile.full)**: Advanced users or those requiring all the things that AutoGen has to offer `autogen_full_img` ```bash - docker build -f samples/dockers/Dockerfile.full -t autogen_full_img https://github.com/microsoft/autogen.git + docker build -f samples/dockers/Dockerfile.full -t autogen_full_img https://github.com/microsoft/autogen.git ``` ### Step 3: Run AutoGen Applications from Docker Image @@ -43,7 +43,7 @@ Here's how you can run an application built with AutoGen, using the Docker image docker run -it -v $(pwd)/myapp:/home/autogen/autogen/myapp autogen_base_img:latest python /home/autogen/autogen/myapp/main.py ``` - Here, `$(pwd)/myapp` is your local directory, and `/home/autogen/autogen/myapp` is the path in the Docker container where your code will be located. + Here, `$(pwd)/myapp` is your local directory, and `/home/autogen/autogen/myapp` is the path in the Docker container where your code will be located. 2. **Port Mapping**: If your application requires a specific port, use the `-p` flag to map the container's port to your host. For instance, if your app runs on port 3000 inside Docker and you want it accessible on port 8080 on your host machine: From 2180c03238e8f197fc4391866e2a60bd828190b3 Mon Sep 17 00:00:00 2001 From: Todd W Bucy Date: Sun, 14 Jan 2024 14:34:42 -0600 Subject: [PATCH 09/24] removed bad edit from sidebars.js --- website/sidebars.js | 22 ---------------------- 1 file changed, 22 deletions(-) delete mode 100644 website/sidebars.js diff --git a/website/sidebars.js b/website/sidebars.js deleted file mode 100644 index 98b6c26d2803..000000000000 --- a/website/sidebars.js +++ /dev/null @@ -1,22 +0,0 @@ -/** - * Creating a sidebar enables you to: - - create an ordered group of docs - - render a sidebar for each doc of that group - - provide next/previous navigation - - The sidebars can be generated from the filesystem, or explicitly defined here. - - Create as many sidebars as you want. - */ - - module.exports = { - docsSidebar: [ - 'Getting-Started', - 'Installation', - {'Use Cases': [{type: 'autogenerated', dirName: 'Use-Cases'}]}, - 'Contribute', - 'Research', - ], - // pydoc-markdown auto-generated markdowns from docstrings - referenceSideBar: [require("./docs/reference/sidebar.json")] -}; From 8d89e27212c8e92532761137a00e8d923e59aa02 Mon Sep 17 00:00:00 2001 From: Todd W Bucy Date: Sun, 14 Jan 2024 14:44:18 -0600 Subject: [PATCH 10/24] fixing git conflict with sidebars.js file --- website/sidebars.js | 22 ++++++++++++++++++++++ 1 file changed, 22 insertions(+) create mode 100644 website/sidebars.js diff --git a/website/sidebars.js b/website/sidebars.js new file mode 100644 index 000000000000..98b6c26d2803 --- /dev/null +++ b/website/sidebars.js @@ -0,0 +1,22 @@ +/** + * Creating a sidebar enables you to: + - create an ordered group of docs + - render a sidebar for each doc of that group + - provide next/previous navigation + + The sidebars can be generated from the filesystem, or explicitly defined here. + + Create as many sidebars as you want. + */ + + module.exports = { + docsSidebar: [ + 'Getting-Started', + 'Installation', + {'Use Cases': [{type: 'autogenerated', dirName: 'Use-Cases'}]}, + 'Contribute', + 'Research', + ], + // pydoc-markdown auto-generated markdowns from docstrings + referenceSideBar: [require("./docs/reference/sidebar.json")] +}; From 71d94be71555348a756c36d2c45c5a2406eeba81 Mon Sep 17 00:00:00 2001 From: R3d91ll Date: Sun, 14 Jan 2024 15:00:49 -0600 Subject: [PATCH 11/24] 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. --- website/docs/Installation.md | 198 ++++++++++++++++++++++++++++------- 1 file changed, 158 insertions(+), 40 deletions(-) diff --git a/website/docs/Installation.md b/website/docs/Installation.md index 3ceb84ef538f..850daab7912a 100644 --- a/website/docs/Installation.md +++ b/website/docs/Installation.md @@ -84,67 +84,185 @@ Here's how you can run an application built with AutoGen, using the Docker image ## Option 2: Install AutoGen Locally Using Virtual Environment -### Option a: venv - -1. Create and activate a virtual environment: +When installing AutoGen locally, we recommend using a virtual environment for the installation. This will ensure that the dependencies for AutoGen are isolated from the rest of your system. - ```bash - python3 -m venv pyautogen - source pyautogen/bin/activate - ``` +### Option a: venv -2. To exit the virtual environment: +You can create a virtual environment with `venv` as below: +```bash +python3 -m venv pyautogen +source pyautogen/bin/activate +``` - ```bash - deactivate - ``` +The following command will deactivate the current `venv` environment: +```bash +deactivate +``` ### Option b: conda -1. Create and activate a Conda environment: +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 +``` - ```bash - conda create -n pyautogen python=3.10 - conda activate pyautogen - ``` +The following command will deactivate the current `conda` environment: +```bash +conda deactivate +``` -2. To exit Conda environment: +### Option c: poetry - ```bash - conda deactivate - ``` +Another option is with `poetry`, which is a dependency manager for Python. -### Option c: poetry +[Poetry](https://python-poetry.org/docs/) is a tool for dependency management and packaging in Python. It allows you to declare the libraries your project depends on and it will manage (install/update) them for you. Poetry offers a lockfile to ensure repeatable installs, and can build your project for distribution. -1. Initialize and activate a Poetry environment: +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 - ```bash - poetry init - poetry shell - poetry add pyautogen - ``` +poetry add pyautogen +``` -2. To exit the Poetry environment: +The following command will deactivate the current `poetry` environment: +```bash +exit +``` - ```bash - exit - ``` +Now, you're ready to install AutoGen in the virtual environment you've just created. -## Python Version Compatibility +## Python -AutoGen requires **Python version >= 3.8, < 3.12**. Install it using pip: +AutoGen requires **Python version >= 3.8, < 3.12**. It can be installed from pip: ```bash pip install pyautogen ``` -Refer to the [Migration guide to v0.2](/autogen/docs/Installation#migration-guide-to-v0.2) for updates and changes. +`pyautogen<0.2` requires `openai<1`. Starting from pyautogen v0.2, `openai>=1` is required. + + + +### Migration guide to v0.2 + +openai v1 is a total rewrite of the library with many breaking changes. For example, the inference requires instantiating a client, instead of using a global class method. +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. + ### Optional Dependencies +- #### 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", + human_input_mode="TERMINATE", + max_consecutive_auto_reply=10, + code_execution_config={"work_dir":"_output", "use_docker":"python:3"}, + llm_config=llm_config, + system_message=""""Reply TERMINATE if the task has been solved at full satisfaction. +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" +``` + +Example notebooks: + +[Optimize for Code Generation](https://github.com/microsoft/autogen/blob/main/notebook/oai_completion.ipynb) + +[Optimize for Math](https://github.com/microsoft/autogen/blob/main/notebook/oai_chatgpt_gpt4.ipynb) + +- #### 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]" +``` + +RetrieveChat can handle various types of documents. By default, it can process +plain text and PDF files, including formats such as 'txt', 'json', 'csv', 'tsv', +'md', 'html', 'htm', 'rtf', 'rst', 'jsonl', 'log', 'xml', 'yaml', 'yml' and 'pdf'. +If you install [unstructured](https://unstructured-io.github.io/unstructured/installation/full_installation.html) +(`pip install "unstructured[all-docs]"`), additional document types such as 'docx', +'doc', 'odt', 'pptx', 'ppt', 'xlsx', 'eml', 'msg', 'epub' will also be supported. + +You can find a list of all supported document types by using `autogen.retrieve_utils.TEXT_FORMATS`. + +Example notebooks: + +[Automated Code Generation and Question Answering with Retrieval Augmented Agents](https://github.com/microsoft/autogen/blob/main/notebook/agentchat_RetrieveChat.ipynb) + +[Group Chat with Retrieval Augmented Generation (with 5 group member agents and 1 manager agent)](https://github.com/microsoft/autogen/blob/main/notebook/agentchat_groupchat_RAG.ipynb) + +[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]" +``` + +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" +``` + +Example notebooks: -- **Docker**: Highly recommended for code execution. Install with `pip install docker`. -- **Blendsearch**: For hyperparameter optimization. Install with `pip install "pyautogen[blendsearch]<0.2"`. -- **Retrievechat**: For retrieval-augmented tasks. Install with `pip install "pyautogen[retrievechat]"`. -- **Teachability**: For teachable agents. Install with `pip install "pyautogen[teachable]"`. -- **LMM Agents**: For multimodal conversable agents. Install with `pip install "pyautogen[lmm]"`. -- **Mathchat**: For math problem-solving agents. Install with `pip install "pyautogen[mathchat]<0.2"`. +[Using MathChat to Solve Math Problems](https://github.com/microsoft/autogen/blob/main/notebook/agentchat_MathChat.ipynb) From 784df4880d865ba7ecc56da673115bcf786c72a2 Mon Sep 17 00:00:00 2001 From: R3d91ll Date: Sun, 14 Jan 2024 15:24:50 -0600 Subject: [PATCH 12/24] Update Installation.md Added mount your code back and added mount your directory for better clarity. --- website/docs/Installation.md | 13 ++++++++++--- 1 file changed, 10 insertions(+), 3 deletions(-) diff --git a/website/docs/Installation.md b/website/docs/Installation.md index 850daab7912a..963714fdb920 100644 --- a/website/docs/Installation.md +++ b/website/docs/Installation.md @@ -37,7 +37,7 @@ AutoGen now provides updated Dockerfiles tailored for different needs. Building Here's how you can run an application built with AutoGen, using the Docker image: -1. **Mount Your Code**: Use the Docker `-v` flag to mount your local application directory to the Docker container. This allows you to develop on your local machine while running the code in a consistent Docker environment. For example: +1. **Mount Your Directory**: Use the Docker `-v` flag to mount your local application directory to the Docker container. This allows you to develop on your local machine while running the code in a consistent Docker environment. For example: ```bash docker run -it -v $(pwd)/myapp:/home/autogen/autogen/myapp autogen_base_img:latest python /home/autogen/autogen/myapp/main.py @@ -45,7 +45,14 @@ Here's how you can run an application built with AutoGen, using the Docker image Here, `$(pwd)/myapp` is your local directory, and `/home/autogen/autogen/myapp` is the path in the Docker container where your code will be located. -2. **Port Mapping**: If your application requires a specific port, use the `-p` flag to map the container's port to your host. For instance, if your app runs on port 3000 inside Docker and you want it accessible on port 8080 on your host machine: +2. **Mount your code:** 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. + +```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 +``` + +3. **Port Mapping**: If your application requires a specific port, use the `-p` flag to map the container's port to your host. For instance, if your app runs on port 3000 inside Docker and you want it accessible on port 8080 on your host machine: ```bash docker run -it -p 8080:3000 -v $(pwd)/myapp:/myapp autogen_base_img:latest python /myapp @@ -53,7 +60,7 @@ Here's how you can run an application built with AutoGen, using the Docker image In this command, `-p 8080:3000` maps port 3000 from the container to port 8080 on your local machine. -3. **Examples of Running Different Applications**: +4. **Examples of Running Different Applications**: `docker run -it -p {WorkstationPortNum}:{DockerPortNum} -v {WorkStation_Dir}:{Docker_DIR} {name_of_the_image}:latest` - *Simple Script*: Run a Python script located in your local `myapp` directory. From 8a7d6e63c163015fba2fba6c486fcb0f2c108554 Mon Sep 17 00:00:00 2001 From: R3d91ll Date: Sun, 14 Jan 2024 15:56:06 -0600 Subject: [PATCH 13/24] Update Installation.md Lint cleanup --- website/docs/Installation.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/website/docs/Installation.md b/website/docs/Installation.md index b267442e7739..a28b906cffb5 100644 --- a/website/docs/Installation.md +++ b/website/docs/Installation.md @@ -46,7 +46,7 @@ To run an application built with AutoGen using the Docker image: Here, `$(pwd)/myapp` is your local directory, and `/home/autogen/autogen/myapp` is the path in the Docker container where your code will be located. -2. **Execute your code:** 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. +2. **Execute your code:** 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. **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. From 78689514a4ec5540b090b9d36e848384dbdd23b3 Mon Sep 17 00:00:00 2001 From: R3d91ll Date: Sun, 14 Jan 2024 16:05:44 -0600 Subject: [PATCH 14/24] Update Installation.md removed the relative path to samples/dockers/Dockerfiles.md with a proper URL to where it will exist --- website/docs/Installation.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/website/docs/Installation.md b/website/docs/Installation.md index a28b906cffb5..196c48d0036e 100644 --- a/website/docs/Installation.md +++ b/website/docs/Installation.md @@ -4,9 +4,9 @@ AutoGen is a versatile tool that can be installed and run in Docker or locally u ## Option 1: Install and Run AutoGen in Docker -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). For more details on customizing the Dockerfiles, see the [Docker Samples README](../samples/dockers/Dockerfiles.md). +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). For more details on customizing the Dockerfiles, see the [Docker Samples README](https://github.com/microsoft/autogen/tree/main/samples/dockers/Dockerfiles.md). -**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 +**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. - **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. From 403fbad18526622411ccc338618156cea70ae796 Mon Sep 17 00:00:00 2001 From: Todd W Bucy Date: Sun, 14 Jan 2024 16:18:36 -0600 Subject: [PATCH 15/24] fixed bad link to Dockerfiles.md --- website/docs/Installation.md | 52 ++++++++++++++++++++++-------------- 1 file changed, 32 insertions(+), 20 deletions(-) diff --git a/website/docs/Installation.md b/website/docs/Installation.md index 196c48d0036e..86c3ae6dd3cb 100644 --- a/website/docs/Installation.md +++ b/website/docs/Installation.md @@ -4,9 +4,9 @@ AutoGen is a versatile tool that can be installed and run in Docker or locally u ## Option 1: Install and Run AutoGen in Docker -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). For more details on customizing the Dockerfiles, see the [Docker Samples README](https://github.com/microsoft/autogen/tree/main/samples/dockers/Dockerfiles.md). +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). For more details on customizing the Dockerfiles, see the [Docker Samples README](../../samples/dockers/Dockerfiles.md). -**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. +**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 - **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. @@ -29,28 +29,26 @@ AutoGen now provides updated Dockerfiles tailored for different needs. Building - **Autogen Advanced (dockerfile.full)**: Advanced users or those requiring all the things that AutoGen has to offer `autogen_full_img` - ```bash docker build -f samples/dockers/Dockerfile.full -t autogen_full_img https://github.com/microsoft/autogen.git ``` ### Step 3: Run AutoGen Applications from Docker Image -To run an application built with AutoGen using the Docker image: +Here's how you can run an application built with AutoGen, using the Docker image: -1. **Mount Your Directory**: Use the Docker `-v` flag to mount your local application directory to the Docker container. This allows you to develop on your local machine while running the code in a consistent Docker environment. For example, to run a Python script located in your local `myapp` directory: +1. **Mount Your Directory**: Use the Docker `-v` flag to mount your local application directory to the Docker container. This allows you to develop on your local machine while running the code in a consistent Docker environment. For example: ```bash docker run -it -v $(pwd)/myapp:/home/autogen/autogen/myapp autogen_base_img:latest python /home/autogen/autogen/myapp/main.py ``` - - Here, `$(pwd)/myapp` is your local directory, and `/home/autogen/autogen/myapp` is the path in the Docker container where your code will be located. -2. **Execute your code:** 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. + Here, `$(pwd)/myapp` is your local directory, and `/home/autogen/autogen/myapp` is the path in the Docker container where your code will be located. -**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. +2. **Mount your code:** 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 +```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 ``` @@ -62,8 +60,11 @@ docker run -it -v `pwd`/myapp:/myapp autogen_img:latest python /myapp/main_twoag In this command, `-p 8080:3000` maps port 3000 from the container to port 8080 on your local machine. -4. **Examples of Running Different Applications**: -`docker run -it -p {WorkstationPortNum}:{DockerPortNum} -v {WorkStation_Dir}:{Docker_DIR} {name_of_the_image}:latest` +4. **Examples of Running Different Applications**: Here is the basic format of the docker run command. + +```bash +docker run -it -p {WorkstationPortNum}:{DockerPortNum} -v {WorkStation_Dir}:{Docker_DIR} {name_of_the_image} {bash/python} {Docker_path_to_script_to_execute} +``` - *Simple Script*: Run a Python script located in your local `myapp` directory. @@ -87,7 +88,7 @@ docker run -it -v `pwd`/myapp:/myapp autogen_img:latest python /myapp/main_twoag - For more information on Docker usage and best practices, refer to the [official Docker documentation](https://docs.docker.com). -- Details for managing and interacting with your AutoGen Docker containers can be found in the [Docker Samples README](../samples/dockers/Dockerfiles.md). +- Details for managing and interacting with your AutoGen Docker containers can be found in the [Docker Samples README](../../samples/dockers/Dockerfiles.md). - Details on how to use the Dockerfile.dev version can be found on the [Contributing](Contribute.md#docker) @@ -98,12 +99,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 ``` @@ -112,12 +115,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 ``` @@ -130,6 +135,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 @@ -138,6 +144,7 @@ poetry add pyautogen ``` The following command will deactivate the current `poetry` environment: + ```bash exit ``` @@ -168,30 +175,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 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", @@ -207,6 +218,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" ``` @@ -220,6 +232,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]" ``` @@ -241,21 +254,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]" ``` @@ -264,10 +276,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" ``` From bbd996e57eadc46a3d4799807f054a251143c206 Mon Sep 17 00:00:00 2001 From: Todd W Bucy Date: Sun, 14 Jan 2024 16:26:03 -0600 Subject: [PATCH 16/24] Fix trailing whitespace and formatting issues --- website/docs/Contribute.md | 1 - website/docs/Installation.md | 8 ++++---- 2 files changed, 4 insertions(+), 5 deletions(-) diff --git a/website/docs/Contribute.md b/website/docs/Contribute.md index bef64d1cabcf..4fe32dff6bb3 100644 --- a/website/docs/Contribute.md +++ b/website/docs/Contribute.md @@ -227,6 +227,5 @@ yarn start --host 0.0.0.0 --port 3000 Once done you should be able to access the documentaion 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 86c3ae6dd3cb..2063a6d8b571 100644 --- a/website/docs/Installation.md +++ b/website/docs/Installation.md @@ -47,10 +47,10 @@ Here's how you can run an application built with AutoGen, using the Docker image 2. **Mount your code:** 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. -```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 -``` + ```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 + ``` 3. **Port Mapping**: If your application requires a specific port, use the `-p` flag to map the container's port to your host. For instance, if your app runs on port 3000 inside Docker and you want it accessible on port 8080 on your host machine: From 3ee5b9a8f4a73daffa8b3867593e588991814309 Mon Sep 17 00:00:00 2001 From: Todd W Bucy Date: Sun, 14 Jan 2024 16:40:21 -0600 Subject: [PATCH 17/24] Update link to Dockerfiles.md --- samples/dockers/Dockerfiles.md | 2 +- website/docs/Contribute.md | 4 ++-- website/docs/Installation.md | 4 ++-- 3 files changed, 5 insertions(+), 5 deletions(-) diff --git a/samples/dockers/Dockerfiles.md b/samples/dockers/Dockerfiles.md index 926f5d863097..8660364c91e6 100644 --- a/samples/dockers/Dockerfiles.md +++ b/samples/dockers/Dockerfiles.md @@ -33,7 +33,7 @@ Feel free to modify these Dockerfiles for your specific project needs. Here are `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 advaned then update this line in the Dockerfile.full file. +- **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. diff --git a/website/docs/Contribute.md b/website/docs/Contribute.md index 4fe32dff6bb3..c3103aeb6c4b 100644 --- a/website/docs/Contribute.md +++ b/website/docs/Contribute.md @@ -204,7 +204,7 @@ 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 containter. Use the Dockerfile.dev as described above to build your image +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 @@ -225,7 +225,7 @@ pydoc-markdown yarn start --host 0.0.0.0 --port 3000 ``` -Once done you should be able to access the documentaion at `http://127.0.0.1:8081/autogen` +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 2063a6d8b571..05503d16d91a 100644 --- a/website/docs/Installation.md +++ b/website/docs/Installation.md @@ -4,7 +4,7 @@ AutoGen is a versatile tool that can be installed and run in Docker or locally u ## Option 1: Install and Run AutoGen in Docker -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). For more details on customizing the Dockerfiles, see the [Docker Samples README](../../samples/dockers/Dockerfiles.md). +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). For more details on customizing the Dockerfiles, see the [Docker Samples README](autogen/samples/dockers/Dockerfiles.md). **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 @@ -88,7 +88,7 @@ docker run -it -p {WorkstationPortNum}:{DockerPortNum} -v {WorkStation_Dir}:{Doc - For more information on Docker usage and best practices, refer to the [official Docker documentation](https://docs.docker.com). -- Details for managing and interacting with your AutoGen Docker containers can be found in the [Docker Samples README](../../samples/dockers/Dockerfiles.md). +- Details for managing and interacting with your AutoGen Docker containers can be found in the [Docker Samples README](autogen/samples/dockers/Dockerfiles.md). - Details on how to use the Dockerfile.dev version can be found on the [Contributing](Contribute.md#docker) From 59248aa5ecdac5c2a219fdadde664f8bb95e2be1 Mon Sep 17 00:00:00 2001 From: Todd W Bucy Date: Sun, 14 Jan 2024 17:34:26 -0600 Subject: [PATCH 18/24] somtimes its really hard to find that lost i. --- website/docs/Contribute.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/website/docs/Contribute.md b/website/docs/Contribute.md index c3103aeb6c4b..4d989b1b56f0 100644 --- a/website/docs/Contribute.md +++ b/website/docs/Contribute.md @@ -121,7 +121,7 @@ For developers contributing to the AutoGen project, we offer a specialized Docke 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. -- This will start your Docker container and allow Dockers port 3000 to be mapped to your workstation on port 8081. It wll also mount the local directory of autogen-newcode to the docker directory of /home/autogen/newstuff. And once running it will put you at the CLI in the /home/autogen/ directory. +- This will start your Docker container and allow Dockers port 3000 to be mapped to your workstation on port 8081. It will also mount the local directory of autogen-newcode to the docker directory of /home/autogen/newstuff. And once running it will put you at the CLI in the /home/autogen/ directory. ```bash docker run -it -p 8081:3000 -v `pwd`/autogen-newcode:newstuff/ autogen_dev_img bash From bd80955d2a855a9c8fa4dcf30d1adc1a7b583b6b Mon Sep 17 00:00:00 2001 From: Todd W Bucy Date: Sun, 14 Jan 2024 17:48:19 -0600 Subject: [PATCH 19/24] trailing whitespace and EOF issues resolved --- samples/dockers/Dockerfile.dev | 2 -- website/docs/Contribute.md | 3 --- 2 files changed, 5 deletions(-) diff --git a/samples/dockers/Dockerfile.dev b/samples/dockers/Dockerfile.dev index 9b610a47a87f..62b18ade3a6c 100644 --- a/samples/dockers/Dockerfile.dev +++ b/samples/dockers/Dockerfile.dev @@ -40,5 +40,3 @@ RUN pip install numpy pandas matplotlib seaborn scikit-learn requests urllib3 nl # Set the default command to bash CMD ["/bin/bash"] - - diff --git a/website/docs/Contribute.md b/website/docs/Contribute.md index 4d989b1b56f0..8bccc1b555f7 100644 --- a/website/docs/Contribute.md +++ b/website/docs/Contribute.md @@ -107,7 +107,6 @@ For developers contributing to the AutoGen project, we offer a specialized Docke - To build the developer Docker image (`autogen_dev_img`), use the following commands: ```bash - # Building the dev image for general development docker build -f samples/dockers/Dockerfile.dev -t autogen_dev_img https://github.com/microsoft/autogen.git ``` @@ -121,8 +120,6 @@ For developers contributing to the AutoGen project, we offer a specialized Docke 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. -- This will start your Docker container and allow Dockers port 3000 to be mapped to your workstation on port 8081. It will also mount the local directory of autogen-newcode to the docker directory of /home/autogen/newstuff. And once running it will put you at the CLI in the /home/autogen/ directory. - ```bash docker run -it -p 8081:3000 -v `pwd`/autogen-newcode:newstuff/ autogen_dev_img bash ``` From ce334667f1bbd3050dfaacd1fc643adf892e1f7f Mon Sep 17 00:00:00 2001 From: Todd W Bucy Date: Sun, 14 Jan 2024 17:59:37 -0600 Subject: [PATCH 20/24] fixed broken link --- website/docs/Installation.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/website/docs/Installation.md b/website/docs/Installation.md index 05503d16d91a..2063a6d8b571 100644 --- a/website/docs/Installation.md +++ b/website/docs/Installation.md @@ -4,7 +4,7 @@ AutoGen is a versatile tool that can be installed and run in Docker or locally u ## Option 1: Install and Run AutoGen in Docker -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). For more details on customizing the Dockerfiles, see the [Docker Samples README](autogen/samples/dockers/Dockerfiles.md). +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). For more details on customizing the Dockerfiles, see the [Docker Samples README](../../samples/dockers/Dockerfiles.md). **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 @@ -88,7 +88,7 @@ docker run -it -p {WorkstationPortNum}:{DockerPortNum} -v {WorkStation_Dir}:{Doc - For more information on Docker usage and best practices, refer to the [official Docker documentation](https://docs.docker.com). -- Details for managing and interacting with your AutoGen Docker containers can be found in the [Docker Samples README](autogen/samples/dockers/Dockerfiles.md). +- Details for managing and interacting with your AutoGen Docker containers can be found in the [Docker Samples README](../../samples/dockers/Dockerfiles.md). - Details on how to use the Dockerfile.dev version can be found on the [Contributing](Contribute.md#docker) From ed2904ed39036fceeecd8499669cc7cb512a072a Mon Sep 17 00:00:00 2001 From: Todd W Bucy Date: Sun, 14 Jan 2024 18:10:11 -0600 Subject: [PATCH 21/24] trailing space an broken link --- website/docs/Contribute.md | 9 ++++----- website/docs/Installation.md | 4 ++-- 2 files changed, 6 insertions(+), 7 deletions(-) diff --git a/website/docs/Contribute.md b/website/docs/Contribute.md index 8bccc1b555f7..a29987434ee1 100644 --- a/website/docs/Contribute.md +++ b/website/docs/Contribute.md @@ -97,10 +97,9 @@ For developers contributing to the AutoGen project, we offer a specialized Docke - **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. -- **Setup**: - - **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. +- **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. ### Building the Developer Docker Image @@ -109,7 +108,7 @@ For developers contributing to the AutoGen project, we offer a specialized Docke ```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 just append a `#{branch-name}` as shown below ```bash diff --git a/website/docs/Installation.md b/website/docs/Installation.md index 2063a6d8b571..08d99b001387 100644 --- a/website/docs/Installation.md +++ b/website/docs/Installation.md @@ -4,7 +4,7 @@ AutoGen is a versatile tool that can be installed and run in Docker or locally u ## Option 1: Install and Run AutoGen in Docker -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). For more details on customizing the Dockerfiles, see the [Docker Samples README](../../samples/dockers/Dockerfiles.md). +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). For more details on customizing the Dockerfiles, see the [Docker Samples README](/home/autogen/autogen/samples/dockers/Dockerfiles.md). **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 @@ -88,7 +88,7 @@ docker run -it -p {WorkstationPortNum}:{DockerPortNum} -v {WorkStation_Dir}:{Doc - For more information on Docker usage and best practices, refer to the [official Docker documentation](https://docs.docker.com). -- Details for managing and interacting with your AutoGen Docker containers can be found in the [Docker Samples README](../../samples/dockers/Dockerfiles.md). +- Details for managing and interacting with your AutoGen Docker containers can be found in the [Docker Samples README](/home/autogen/autogen/samples/dockers/Dockerfiles.md). - Details on how to use the Dockerfile.dev version can be found on the [Contributing](Contribute.md#docker) From f95c5ebabe89d5b8f923f021b194bc8a92b62854 Mon Sep 17 00:00:00 2001 From: Todd W Bucy Date: Sun, 14 Jan 2024 18:13:50 -0600 Subject: [PATCH 22/24] removed broken links. will update one merged. --- website/docs/Installation.md | 4 +--- 1 file changed, 1 insertion(+), 3 deletions(-) diff --git a/website/docs/Installation.md b/website/docs/Installation.md index 08d99b001387..b0404cab69d2 100644 --- a/website/docs/Installation.md +++ b/website/docs/Installation.md @@ -4,7 +4,7 @@ AutoGen is a versatile tool that can be installed and run in Docker or locally u ## Option 1: Install and Run AutoGen in Docker -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). For more details on customizing the Dockerfiles, see the [Docker Samples README](/home/autogen/autogen/samples/dockers/Dockerfiles.md). +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). **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 @@ -88,8 +88,6 @@ docker run -it -p {WorkstationPortNum}:{DockerPortNum} -v {WorkStation_Dir}:{Doc - For more information on Docker usage and best practices, refer to the [official Docker documentation](https://docs.docker.com). -- Details for managing and interacting with your AutoGen Docker containers can be found in the [Docker Samples README](/home/autogen/autogen/samples/dockers/Dockerfiles.md). - - 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 From 41f9bd696cfa2480805c39814111b977baf35d7f Mon Sep 17 00:00:00 2001 From: Todd W Bucy Date: Sun, 14 Jan 2024 21:27:42 -0600 Subject: [PATCH 23/24] fixed glaring error about building an image from a particular branch Contribute.md --- website/docs/Contribute.md | 11 +++++++++-- website/docs/Installation.md | 2 +- 2 files changed, 10 insertions(+), 3 deletions(-) diff --git a/website/docs/Contribute.md b/website/docs/Contribute.md index a29987434ee1..946c88067962 100644 --- a/website/docs/Contribute.md +++ b/website/docs/Contribute.md @@ -109,10 +109,17 @@ For developers contributing to the AutoGen project, we offer a specialized Docke 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 just append a `#{branch-name}` as shown below +- For building the developer image built from a specific Dockerfile in a branch other than main/master ```bash - docker build -f samples/dockers/Dockerfile.dev -t autogen_dev_img 'https://github.com/microsoft/autogen.git#dockerDocs' + # clone the branch you want to work out of + git clone --branch {branch-name} https://github.com/microsoft/autogen.git + + # 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 diff --git a/website/docs/Installation.md b/website/docs/Installation.md index b0404cab69d2..7360204692d5 100644 --- a/website/docs/Installation.md +++ b/website/docs/Installation.md @@ -189,7 +189,7 @@ Inference parameter tuning can be done via [`flaml.tune`](https://microsoft.gith ### 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). From fa0c96d8af75bde0002fa2f44d3df85db2adb16c Mon Sep 17 00:00:00 2001 From: Todd W Bucy Date: Mon, 15 Jan 2024 01:09:52 -0600 Subject: [PATCH 24/24] removed tic mark typo from contribute.md --- website/docs/Contribute.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/website/docs/Contribute.md b/website/docs/Contribute.md index 946c88067962..ab7ff96caa97 100644 --- a/website/docs/Contribute.md +++ b/website/docs/Contribute.md @@ -93,7 +93,7 @@ There is currently no formal reviewer solicitation process. Current reviewers id 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. -### Autogen Developer Image (`autogen_dev_img`) +### Autogen Developer Image (autogen_dev_img) - **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. @@ -133,7 +133,7 @@ docker run -it -p 8081:3000 -v `pwd`/autogen-newcode:newstuff/ autogen_dev_img b - 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 +docker run -it -p 8081:3000 -v /home/AutoGenDeveloper/autogen-newcode:newstuff/ autogen_dev_img bash ``` ### Develop in Remote Container