From b56ac3dc1465aa42689152ce750597124de1debd Mon Sep 17 00:00:00 2001 From: Davor Runje Date: Tue, 5 Nov 2024 17:00:15 +0100 Subject: [PATCH] Polishing docs (#530) * polishing * Polish getting-started docs --------- Co-authored-by: Tvrtko Sternak --- .secrets.baseline | 12 +- docs/docs/en/user-guide/cookiecutter/index.md | 2 +- .../en/user-guide/getting-started/index.md | 312 ++++-------------- docs/docs/en/user-guide/index.md | 2 +- 4 files changed, 60 insertions(+), 268 deletions(-) diff --git a/.secrets.baseline b/.secrets.baseline index 74f7860c..a0afb276 100644 --- a/.secrets.baseline +++ b/.secrets.baseline @@ -173,16 +173,6 @@ "is_secret": false } ], - "docs/docs/en/user-guide/getting-started/index.md": [ - { - "type": "Secret Keyword", - "filename": "docs/docs/en/user-guide/getting-started/index.md", - "hashed_secret": "3be2e9dd1980856faddf5bd205e3ff96b24776aa", - "is_verified": false, - "line_number": 445, - "is_secret": false - } - ], "docs/docs/en/user-guide/runtimes/autogen/index.md": [ { "type": "Secret Keyword", @@ -234,5 +224,5 @@ } ] }, - "generated_at": "2024-11-05T11:49:46Z" + "generated_at": "2024-11-05T13:39:16Z" } diff --git a/docs/docs/en/user-guide/cookiecutter/index.md b/docs/docs/en/user-guide/cookiecutter/index.md index e3b2df2e..3a1789e6 100644 --- a/docs/docs/en/user-guide/cookiecutter/index.md +++ b/docs/docs/en/user-guide/cookiecutter/index.md @@ -204,7 +204,7 @@ Cookiecutter creates projects from cookiecutters (project templates), e.g. Pytho 8. After reopening the project in devcontainer, you can verify that the setup is correct by running the provided tests with the following command: ```console - pytest -s + pytest ``` You should get the following output if everything is correctly setup. diff --git a/docs/docs/en/user-guide/getting-started/index.md b/docs/docs/en/user-guide/getting-started/index.md index a4438e28..f87e89c6 100644 --- a/docs/docs/en/user-guide/getting-started/index.md +++ b/docs/docs/en/user-guide/getting-started/index.md @@ -16,51 +16,42 @@ search: ## Quick start -We will show you four different setups, two for development and two for production workloads: +You can use three different setups, depending on how scalable solution you need: -- Development setups - - **Console**: This setup uses console for interactively executing your workflow. - It is also very useful for automating testing and integration with CI/CD. +- **Mesop**: This setup uses [**Mesop**](https://google.github.io/mesop/){target="_blank"} + to build a web application for interacting with our workflow. It supports + a single-worker deployments only, limiting its scalability. However, it + is the fastest way to debug your application. +- **FastAPI + Mesop**: This is fairly scalable setup using [**FastAPI**](https://fastapi.tiangolo.com/){target="_blank"} to execute your workflows and [**Mesop**](https://google.github.io/mesop/){target="_blank"} for interactive web application. [**FastAPI**](https://fastapi.tiangolo.com/){target="_blank"} supports execution with multiple workers, with each workflow being executed in the context of a WebSocket connection. [**Mesop**](https://google.github.io/mesop/){target="_blank"} is still limited to a single worker, although there is much less load on it due to workflows being executed in the [**FastAPI**](https://fastapi.tiangolo.com/){target="_blank"} workers. - - **Mesop**: This setup uses [**Mesop**](https://google.github.io/mesop/){target="_blank"} - to build a web application for interacting with our workflow. It supports - a single-worker deployments only, limiting its scalability. However, it - is the fastest way to debug your application. - -- Production setups - - - **FastAPI + Mesop**: This is fairly scalable setup using [**FastAPI**](https://fastapi.tiangolo.com/){target="_blank"} to execute your workflows and [**Mesop**](https://google.github.io/mesop/){target="_blank"} for interactive web application. [**FastAPI**](https://fastapi.tiangolo.com/){target="_blank"} supports execution with multiple workers, with each workflow being executed in the context of a WebSocket connection. [**Mesop**](https://google.github.io/mesop/){target="_blank"} is still limited to a single worker, although there is much less load of it due to workflows being executed in the [**FastAPI**](https://fastapi.tiangolo.com/){target="_blank"} workers. - - - **NATS + FastAPI + Mesop**: This is the most scalable setup using a distributed message broker - [**NATS.io MQ**](https://nats.io/){target="_blank"}. Workflows are being executed with - multiple workers that attach to the MQ waiting for initiate workflow messages. Such workers - can be running on different machines or even different data centers/cloud providers. - Message queues are highly scalable, but more difficult to integrate with end-clients. - In order to make such integrations easier, we will connect our [**NATS**](https://nats.io/){target="_blank"}-based message queue with the [**FastAPI**](https://fastapi.tiangolo.com/){target="_blank"} application. +- **NATS + FastAPI + Mesop**: This is the most scalable setup using a distributed message broker + [**NATS.io MQ**](https://nats.io/){target="_blank"}. Workflows are being executed with + multiple workers that attach to the MQ waiting for initiate workflow messages. Such workers + can be running on different machines or even different data centers/cloud providers. + Message queues are highly scalable, but more difficult to integrate with end-clients. + In order to make such integrations easier, we will connect our [**NATS**](https://nats.io/){target="_blank"}-based message queue with the [**FastAPI**](https://fastapi.tiangolo.com/){target="_blank"} application. ### Project setup -There are two ways to setup you development environment and project: - -- [**Recommended**] Using [**Cookiecutter**](../cookiecutter/index.md): This creates the project folder structure, default workflow, automatically installs all the necessary requirements, and creates a [devcontainer](https://code.visualstudio.com/docs/devcontainers/containers){target="_blank"} that can be used with [Visual Studio Code](https://code.visualstudio.com/){target="_blank"}. +We **strongly recommend** using [**Cookiecutter**](../cookiecutter/index.md) for setting up the project. It creates the project folder structure, default workflow, automatically installs all the necessary requirements, and creates a [devcontainer](https://code.visualstudio.com/docs/devcontainers/containers){target="_blank"} that can be used with [Visual Studio Code](https://code.visualstudio.com/){target="_blank"}. -- Using virtual environment, such as [venv](https://docs.python.org/3/library/venv.html){target="_blank"}, and a Python package manager, such as [**pip**](https://en.wikipedia.org/wiki/Pip_(package_manager)). +You could also use virtual environment managers such as [venv](https://docs.python.org/3/library/venv.html){target="_blank"}, and a Python package manager, such as [pip](https://en.wikipedia.org/wiki/Pip_(package_manager)). -Let's see how to setup project using cookiecutter: - {! docs/en/user-guide/cookiecutter/index.md[ln:6-226] !} +!!! info + If you used a different `project_slug` than the default *my_fastagency_app* this will be reflected in the project module naming. Keep this in mind when running the commands further in this guide (in [Run Application](#run-application)), you will need to replace *my_fastagency_app* with your `project_slug` name. ----- ### Workflow Development #### Define the Workflow -You need to define the workflow that your application will use. This is where you specify how the agents interact and what they do. Here's a simple example of a workflow definition: +You need to define the workflow that your application will use. This is where you specify how the agents interact and what they do. Here's a simple example of a workflow definition as it is generated by the cookie cutter under `my_fastagency_app/workflow.py`: ```python {! docs_src/getting_started/workflow.py [ln:1-51] !} @@ -70,7 +61,7 @@ This code snippet sets up a simple learning chat between a student and a teacher #### Run and Debug the Workflow -To ensure that the workflow we have defined is working properly, we can test it locally using MesopUI. The code below imports the defined workflow and sets up MesopUI: +To ensure that the workflow we have defined is working properly, we can test it locally using MesopUI. The code below can be found under `my_fastagency_app/local/main_mesop.py` and imports the defined workflow and sets up MesopUI: ```python {! docs_src/getting_started/main_mesop.py [ln:1-8] !} @@ -81,20 +72,20 @@ Run MesopUI locally with the following command: === "Linux/MacOS" !!! note "Terminal" ```console - gunicorn main_mesop:app + gunicorn my_fastagency_app.local.main_mesop:app ``` === "Windows" !!! note "Terminal" ```console - waitress-serve --listen=0.0.0.0:8000 main_mesop:app + waitress-serve --listen=0.0.0.0:8000 my_fastagency_app.local.main_mesop:app ``` Open the MesopUI URL [http://localhost:8000](http://localhost:8000) in your browser. You can now use the graphical user interface to start, run, test and debug the autogen workflow manually. #### Run Workflow Tests -We can also use pytest to test the autogen workflow automatically, instead of manually testing it using MesopUI. +We can also use pytest to test the autogen workflow automatically, instead of manually testing it using MesopUI by using the generated `pytest` test found under `tests/test_workflow.py`. ```python {! docs_src/getting_started/test_workflow.py [ln:1-31] !} @@ -108,18 +99,13 @@ pytest Running the test could take up to 30 seconds, depending on latency and throughput of OpenAI (or other LLM providers). -### Workflow Deployment - -#### Imports +### Deployment files -Depending on the interface you choose, you'll need to import different modules. These imports set up the necessary components for your application: +Depending on the interface you choose, `cookiecutter` will generate appropriate files under `my_fastagency_app/deployment` folder. We'll quickly explain what they contain and how to use them. -=== "Console" - ```python hl_lines="2" - {!> docs_src/getting_started/main_console.py [ln:1-4] !} - ``` +#### Imports - For Console applications, import `ConsoleUI` to handle command-line input and output. +First, you'll need to import different modules. These imports set up the necessary components for your application: === "Mesop" ```python hl_lines="2" @@ -142,15 +128,6 @@ Depending on the interface you choose, you'll need to import different modules. #### Define FastAgency Application -=== "Console" - Next, define your FastAgency application. This ties together your workflow and the interface you chose: - - ```python hl_lines="1" - {!> docs_src/getting_started/main_console.py [ln:7] !} - ``` - - For Console applications, use `ConsoleUI` to handle user interaction via the command line. - === "Mesop" Next, define your FastAgency application. This ties together your workflow and the interface you chose: @@ -187,9 +164,6 @@ Depending on the interface you choose, you'll need to import different modules. #### Adapter Chaining -=== "Console" - Not applicable for this setup as there are no adapters used. - === "Mesop" Not applicable for this setup as there are no adapters used. @@ -225,22 +199,6 @@ Depending on the interface you choose, you'll need to import different modules. Please copy and paste the following code into the same folder, using the file names exactly as mentioned below. -=== "Console" - -
- workflow.py - ```python - {!> docs_src/getting_started/workflow.py !} - ``` -
- -
- main.py - ```python - {!> docs_src/getting_started/main_console.py !} - ``` -
- === "Mesop"
@@ -321,215 +279,59 @@ Please copy and paste the following code into the same folder, using the file na Once everything is set up, you can run your FastAgency application using the following command: -=== "Console" - - !!! note "Terminal" - ```console - fastagency run - ``` - === "Mesop" The preferred way to run the [**Mesop**](https://google.github.io/mesop/){target="_blank"} application is using a Python WSGI HTTP server like [**Gunicorn**](https://gunicorn.org/){target="_blank"} on Linux and Mac or [**Waitress**](https://docs.pylonsproject.org/projects/waitress/en/stable/){target="_blank"} on Windows. - === "Cookiecutter" - !!! note "Terminal" - ```console - gunicorn main:app - ``` - === "env + pip" - - First, install the package using package manager such as `pip` and then run it: - - === "Linux/MacOS" - !!! note "Terminal" - ```console - pip install gunicorn - gunicorn main:app - ``` - - === "Windows" - !!! note "Terminal" - ```console - pip install waitress - waitress-serve --listen=0.0.0.0:8000 main:app - ``` + - In the root of your project run: + !!! note "Terminal" + ```console + gunicorn my_fastagency_app.deployment.main:app + ``` === "FastAPI + Mesop" In this setup, we need to run **two** commands in **separate** terminal windows: - === "Cookiecutter" - - - Start **FastAPI** application using uvicorn: - !!! note "Terminal 1" - ``` - uvicorn main_1_fastapi:app --host 0.0.0.0 --port 8008 --reload - ``` - - - Start **Mesop** web interface using gunicorn: - !!! note "Terminal 2" - ``` - gunicorn main_2_mesop:app -b 0.0.0.0:8888 --reload - ``` - - === "env + pip" - - First, install the package using package manager such as `pip` and then run it: - - === "Linux/MacOS" + - Start **FastAPI** application using uvicorn, in the root of your project run: + !!! note "Terminal 1" + ``` + uvicorn my_fastagency_app.deployment.main_1_fastapi:app --host 0.0.0.0 --port 8008 --reload + ``` - - Start **FastAPI** application using uvicorn: - !!! note "Terminal 1" - ``` - pip install uvicorn - uvicorn main_1_fastapi:app --host 0.0.0.0 --port 8008 --reload - ``` + - Start **Mesop** web interface using gunicorn, in the root of your project run: + !!! note "Terminal 2" + ``` + gunicorn my_fastagency_app.deployment.main_2_mesop:app -b 0.0.0.0:8888 --reload + ``` - - Start **Mesop** web interface using gunicorn: - !!! note "Terminal 2" - ``` - pip install gunicorn - gunicorn main_2_mesop:app -b 0.0.0.0:8888 --reload - ``` +=== "NATS + FastAPI + Mesop" - === "Windows" + The **NATS** docker container is started automatically by Cookiecutter for this setup. In this setup, we need to run **three** commands in **separate** terminal windows: - - Start **FastAPI** application using uvicorn: - !!! note "Terminal 1" - ``` - pip install uvicorn - uvicorn main_1_fastapi:app --host 0.0.0.0 --port 8008 --reload - ``` + - Start **FastAPI** application that provides a conversational workflow, in the root of your project run:: + !!! note "Terminal 1" + ``` + uvicorn my_fastagency_app.deployment.main_1_nats:app --reload + ``` - - Start **Mesop** web interface using waitress: - !!! note "Terminal 2" - ``` - pip install waitress - waitress-serve --listen=0.0.0.0:8888 main_2_mesop:app - ``` + - Start **FastAPI** application integrated with a **NATS** messaging system, in the root of your project run:: + !!! note "Terminal 2" + ``` + uvicorn my_fastagency_app.deployment.main_2_fastapi:app --host 0.0.0.0 --port 8008 --reload + ``` -=== "NATS + FastAPI + Mesop" + - Start **Mesop** web interface using gunicorn, in the root of your project run:: + !!! note "Terminal 3" + ``` + gunicorn my_fastagency_app.deployment.main_3_mesop:app -b 0.0.0.0:8888 --reload + ``` - === "Cookiecutter" - - The **NATS** docker container is started automatically by Cookiecutter for this setup. In this setup, we need to run **three** commands in **separate** terminal windows: - - - Start **FastAPI** application that provides a conversational workflow: - !!! note "Terminal 1" - ``` - uvicorn main_1_nats:app --reload - ``` - - - Start **FastAPI** application integrated with a **NATS** messaging system: - !!! note "Terminal 2" - ``` - uvicorn main_2_fastapi:app --host 0.0.0.0 --port 8008 --reload - ``` - - - Start **Mesop** web interface using gunicorn: - !!! note "Terminal 3" - ``` - gunicorn main_3_mesop:app -b 0.0.0.0:8888 --reload - ``` - - === "env + pip" - - First, install the package using package manager such as `pip` and then run it. In this setup, we need to run **four** commands in **separate** terminal windows: - - === "Linux/MacOS" - - - Start **NATS** Docker container: - !!! note "Terminal 1" - ``` - docker run -d --name nats-fastagency --rm -p 4222:4222 -p 9222:9222 -p 8222:8222 -v $(pwd)/nats-server.conf:/etc/nats/nats-server.conf -e FASTAGENCY_NATS_PASSWORD='fastagency_nats_password' nats:latest -c /etc/nats/nats-server.conf - ``` - - - Start **FastAPI** application that provides a conversational workflow: - !!! note "Terminal 2" - ``` - pip install uvicorn - uvicorn main_1_nats:app --reload - ``` - - - Start **FastAPI** application integrated with a **NATS** messaging system: - !!! note "Terminal 3" - ``` - uvicorn main_2_fastapi:app --host 0.0.0.0 --port 8008 --reload - ``` - - - Start **Mesop** web interface using gunicorn: - !!! note "Terminal 4" - ``` - pip install gunicorn - gunicorn main_3_mesop:app -b 0.0.0.0:8888 --reload - ``` - - === "Windows" - - - Start **NATS** Docker container: - !!! note "Terminal 1" - ``` - docker run -d --name nats-fastagency --rm -p 4222:4222 -p 9222:9222 -p 8222:8222 -v $(pwd)/nats-server.conf:/etc/nats/nats-server.conf -e FASTAGENCY_NATS_PASSWORD='fastagency_nats_password' nats:latest -c /etc/nats/nats-server.conf - ``` - - - Start **FastAPI** application that provides a conversational workflow: - !!! note "Terminal 2" - ``` - pip install uvicorn - uvicorn main_1_nats:app --reload - ``` - - - Start **FastAPI** application integrated with a **NATS** messaging system: - !!! note "Terminal 3" - ``` - uvicorn main_2_fastapi:app --host 0.0.0.0 --port 8008 --reload - ``` - - - Start **Mesop** web interface using waitress: - !!! note "Terminal 4" - ``` - pip install waitress - waitress-serve --listen=0.0.0.0:8888 main_3_mesop:app - ``` ### Output The outputs will vary based on the interface, here is the output of the last terminal starting UI: -=== "Console" - ```console - ╭─ Python module file ─╮ - │ │ - │ 🐍 main.py │ - │ │ - ╰──────────────────────╯ - - ╭─ Importable FastAgency app ─╮ - │ │ - │ from main import app │ - │ │ - ╰─────────────────────────────╯ - - ╭─ FastAgency -> user [workflow_started] ──────────────────────────────────────╮ - │ │ - │ { │ - │ "name": "simple_learning", │ - │ "description": "Student and teacher │ - │ learning chat", │ - │ "params": {} │ - │ } │ - ╰──────────────────────────────────────────────────────────────────────────────╯ - - ╭─ Workflow -> User [text_input] ──────────────────────────────────────────────╮ - │ │ - │ I can help you learn about geometry. What subject you would like to │ - │ explore?: │ - ╰──────────────────────────────────────────────────────────────────────────────╯ - ``` - - For Console applications, you will see a command-line prompt where you can enter the initial message and interact with your workflow. - === "Mesop" ```console [2024-10-10 13:19:18 +0530] [23635] [INFO] Starting gunicorn 23.0.0 diff --git a/docs/docs/en/user-guide/index.md b/docs/docs/en/user-guide/index.md index 34d477cb..6a1c131b 100644 --- a/docs/docs/en/user-guide/index.md +++ b/docs/docs/en/user-guide/index.md @@ -13,6 +13,6 @@ search: # User Guide -Table of content: +Table of contents: - [Quick start](getting-started/index.md)