Update tutorials to use cookiecutter (#553)

* wip * wip * wip * wip * wip * wip * wip * wip * Update secrets.baseline * Update lines * Fix tests * Fix tests
airtai · Nov 11, 2024 · bbe6e05 · bbe6e05
1 parent 9502dd4
commit bbe6e05
Show file tree

Hide file tree

Showing 7 changed files with 222 additions and 143 deletions.
diff --git a/.secrets.baseline b/.secrets.baseline
@@ -133,15 +133,15 @@
         "filename": "docs/docs/en/tutorials/giphy/index.md",
         "hashed_secret": "63f8ff37d3848fcf04ef3afe45d0fc830678d1ce",
         "is_verified": false,
-        "line_number": 73,
+        "line_number": 64,
         "is_secret": false
       },
       {
         "type": "Secret Keyword",
         "filename": "docs/docs/en/tutorials/giphy/index.md",
         "hashed_secret": "bc39a40e023f4ffb425b82830f86a464e5ea1072",
         "is_verified": false,
-        "line_number": 74,
+        "line_number": 65,
         "is_secret": false
       }
     ],
@@ -151,15 +151,15 @@
         "filename": "docs/docs/en/tutorials/whatsapp/index.md",
         "hashed_secret": "52e0d11a70cdb70d4c51064d08bd8f179ebb8bb4",
         "is_verified": false,
-        "line_number": 85,
+        "line_number": 75,
         "is_secret": false
       },
       {
         "type": "Secret Keyword",
         "filename": "docs/docs/en/tutorials/whatsapp/index.md",
         "hashed_secret": "bc39a40e023f4ffb425b82830f86a464e5ea1072",
         "is_verified": false,
-        "line_number": 86,
+        "line_number": 76,
         "is_secret": false
       }
     ],
@@ -262,5 +262,5 @@
       }
     ]
   },
-  "generated_at": "2024-11-11T12:24:12Z"
+  "generated_at": "2024-11-11T13:07:26Z"
 }
diff --git a/docs/docs/en/tutorials/giphy/index.md b/docs/docs/en/tutorials/giphy/index.md
@@ -22,19 +22,10 @@ We will walk through setting up each agent, handling API security, and creating
 Let’s dive into creating a powerful interactive agent system with **FastAgency**!
 
 
-## Installation and API Key Setup
+## Project setup
 
-Before we dive into building our agents, let’s go over the necessary setup. We will guide you through installing the **FastAgency** framework and obtaining the API key needed for the Giphy integration.
+{! docs/en/tutorials/mesop_template.md[ln:3-105] !}
 
-### Installing FastAgency
-
-To get started, you need to install FastAgency with OpenAPI submodule. You can do this using `pip`, Python's package installer.
-
-```bash
-pip install "fastagency[autogen,mesop,openapi]"
-```
-
-Alternatively, you can use [**Cookiecutter**](../../user-guide/cookiecutter/index.md), which is the preferred method. Cookiecutter 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"}.
 
 ### API Key Setup
 [**`WebSurferAgent`**](../../api/fastagency/runtimes/autogen/agents/websurfer/WebSurferAgent.md) requires an **Bing Web Search** API key and **Giphy agent** requires an API key to interact with Giphy's service. Follow these steps to create your API keys:
@@ -81,13 +72,20 @@ You can set the API keys in your terminal as an environment variable:
 
 ## Complete Application Code
 
+### Workflow Code
+{! docs/en/tutorials/mesop_template.md[ln:108-112] !}
+
 <details>
-<summary>main.py</summary>
+<summary>workflow.py</summary>
 ```python
 {! docs_src/tutorials/giphy/main.py !}
 ```
 </details>
 
+### Deployment Code
+{! docs/en/tutorials/mesop_template.md[ln:116-127] !}
+
+
 
 ## Code Walkthrough
 
@@ -98,7 +96,7 @@ The following lines shows hot to initializes the Giphy API by loading the OpenAP
 
 Also, we configure the **Giphy API** with the __*GIPHY_API_KEY*__ using __*set_security_params*__ to authenticate our requests.
 ```python
-{! docs_src/tutorials/giphy/main.py [ln:25-29] !}
+{! docs_src/tutorials/giphy/main.py [ln:23-27] !}
 ```
 
 For more information, visit [**API Integration User Guide**](../../user-guide/api/index.md){target="_blank"}.
@@ -108,14 +106,14 @@ For more information, visit [**API Integration User Guide**](../../user-guide/ap
 Here, we initialize a new workflow using ***AutoGenWorkflows()*** and register it under the name ***"giphy_and_websurfer"***. The ***@wf.register*** decorator registers the function to handle chat flow with security enabled, combining both Giphy agent and WebSurferAgent.
 
 ```python
-{! docs_src/tutorials/giphy/main.py [ln:58-61] !}
+{! docs_src/tutorials/giphy/main.py [ln:56-59] !}
 ```
 
 ### Interaction with the user
 This is a core function used by the **Giphy agent** to either present the task result or ask a follow-up question to the user. The message is wrapped in a ***TextInput*** object, and then ***ui.process_message()*** sends it for user interaction.
 
 ```python
-{! docs_src/tutorials/giphy/main.py [ln:65-76] !}
+{! docs_src/tutorials/giphy/main.py [ln:63-73] !}
 ```
 
 ### Creating the Giphy and WebSurfer Agents
@@ -124,20 +122,20 @@ This is a core function used by the **Giphy agent** to either present the task r
 - **WebSurferAgent**: The *[**`WebSurferAgent`**](../../api/fastagency/runtimes/autogen/agents/websurfer/WebSurferAgent.md)* is responsible for scraping web content and passes the retrieved data to the **Giphy agent**. It’s configured with a summarizer to condense web content, which is useful when presenting concise data to the user. For more information, visit [**WebSurfer User Guide**](../../user-guide/runtimes/autogen/websurfer.md){target="_blank"}.
 
 ```python
-{! docs_src/tutorials/giphy/main.py [ln:77-92] !}
+{! docs_src/tutorials/giphy/main.py [ln:75-90] !}
 ```
 
 ### Registering Functions
 
 The function ***present_completed_task_or_ask_question*** is registered to allow the **Giphy agent** to ask questions or present completed tasks after receiving data from the [**`WebSurferAgent`**](../../api/fastagency/runtimes/autogen/agents/websurfer/WebSurferAgent.md).
 
 ```python
-{! docs_src/tutorials/giphy/main.py [ln:94-101] !}
+{! docs_src/tutorials/giphy/main.py [ln:92-99] !}
 ```
 
 We specify which Giphy API functions can be used by the **Giphy agent**: *random_gif*, *search_gifs*, and *trending_gifs*. These functions allow the agent to generate GIFs based on user input or trending content.
 ```python
-{! docs_src/tutorials/giphy/main.py [ln:103-109] !}
+{! docs_src/tutorials/giphy/main.py [ln:101-107] !}
 ```
 
 ### Initiating the Chat
@@ -147,57 +145,17 @@ We initiate the conversation between the user, [**`WebSurferAgent`**](../../api/
 Once the conversation ends, the summary is returned to the user, wrapping up the session.
 
 ```python
-{! docs_src/tutorials/giphy/main.py [ln:117-124] !}
+{! docs_src/tutorials/giphy/main.py [ln:115-122] !}
 ```
 
 ### Starting the Application
 
-The FastAgency app is created, using the registered workflows (***wf***) and web-based user interface (***MesopUI***). This makes the conversation between agents and the user interactive.
-
-```python
-{! docs_src/tutorials/giphy/main.py [ln:127] !}
-```
-
-For more information, visit [**Mesop User Guide**](../../user-guide/ui/mesop/basics.md){target="_blank"}.
+{! docs/en/tutorials/mesop_template.md[ln:132-138] !}
 
 ## Running the Application
 
-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
-            ```
-
-```console
-[2024-10-10 13:19:18 +0530] [23635] [INFO] Starting gunicorn 23.0.0
-[2024-10-10 13:19:18 +0530] [23635] [INFO] Listening at: http://127.0.0.1:8000 (23635)
-[2024-10-10 13:19:18 +0530] [23635] [INFO] Using worker: sync
-[2024-10-10 13:19:18 +0530] [23645] [INFO] Booting worker with pid: 23645
-```
-
-The command will launch a web interface where users can input their requests and interact with the agents (in this case ***http://localhost:8000***)
+{! docs/en/tutorials/mesop_template.md[ln:143-178] !}
 
-!!! note
-    Ensure that your OpenAI API key is set in the environment, as the agents rely on it to interact using GPT-4o. If the API key is not correctly configured, the application may fail to retrieve LLM-powered responses.
 
 ## Chat Example
 In this scenario, the user instructs the agents to scrape [BBC Sport](https://www.bbc.com/sport) for the latest sports news.

diff --git a/docs/docs/en/tutorials/mesop_template.md b/docs/docs/en/tutorials/mesop_template.md
@@ -0,0 +1,178 @@
+## Project setup
+
+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"} for development.
+
+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)).
+
+
+=== "Cookiecutter"
+
+    1. Install Cookiecutter with the following command:
+        ```console
+        pip install cookiecutter
+        ```
+
+    2. Run the `cookiecutter` command:
+        ```console
+        cookiecutter https://github.com/airtai/cookiecutter-fastagency.git
+        ```
+
+    3. Depending on the type of the project, choose the appropriate option in step 3:
+
+        ```console
+        [1/4] project_name (My FastAgency App):
+        [2/4] project_slug (my_fastagency_app):
+        [3/4] Select app_type
+            1 - fastapi+mesop
+            2 - mesop
+            3 - nats+fastapi+mesop
+            Choose from [1/2/3] (1): 2
+        [4/4] Select python_version
+            1 - 3.12
+            2 - 3.11
+            3 - 3.10
+            Choose from [1/2/3] (1):
+        ```
+
+        This command installs FastAgency with support for both the Console and Mesop interfaces for AutoGen workflows.
+
+
+    4. Executing the `cookiecutter` command will create the following file structure:
+
+        ```console
+        {!> docs_src/getting_started/mesop/folder_structure.txt !}
+        ```
+
+    5. To run LLM-based applications, you need an API key for the LLM used. The most commonly used LLM is [OpenAI](https://platform.openai.com/docs/models). To use it, create an [OpenAI API Key](https://openai.com/index/openai-api/) and set it as an environment variable in the terminal using the following command:
+
+        ```console
+        export OPENAI_API_KEY=openai_api_key_here
+        ```
+
+        If you want to use a different LLM provider, follow [this guide](https://fastagency.ai/latest/user-guide/runtimes/autogen/using_non_openai_models/).
+
+        Alternatively, you can skip this step and set the LLM API key as an environment variable later in the devcontainer's terminal. If you open the project in [Visual Studio Code](https://code.visualstudio.com/){target="_blank"} using GUI, you will need to manually set the environment variable in the devcontainer's terminal.
+
+    6. Open the generated project in [Visual Studio Code](https://code.visualstudio.com/){target="_blank"} with the following command:
+        ```console
+        code my_fastagency_app
+        ```
+
+    7. Once the project is opened, you will get the following option to reopen it in a devcontainer:
+
+        <img src="../getting-started/images/reopen-in-container.png" width="600" class="center">
+
+    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
+        ```
+
+        You should get the following output if everything is correctly setup.
+        ```console
+        =================================== test session starts ===================================
+        platform linux -- Python 3.12.7, pytest-8.3.3, pluggy-1.5.0
+        rootdir: /workspaces/my_fastagency_app
+        configfile: pyproject.toml
+        plugins: asyncio-0.24.0, anyio-4.6.2.post1
+        asyncio: mode=Mode.STRICT, default_loop_scope=None
+        collected 1 item
+
+        tests/test_workflow.py .                                                            [100%]
+
+        ==================================== 1 passed in 1.02s ====================================
+        ```
+
+        Running the test could take up to 30 seconds, depending on latency and throughput of OpenAI (or other LLM providers).
+
+
+    9. Install additional dependencies which will be needed for this tutorial:
+        ```bash
+        pip install "fastagency[openapi]"
+        ```
+
+
+    !!! 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.
+
+
+=== "env + pip"
+
+    To get started, you need to install FastAgency with OpenAPI submodule. You can do this using `pip`, Python's package installer.
+
+    ```bash
+    pip install "fastagency[autogen,mesop,openapi]"
+    ```
+
+## Workflow Code
+You need to define the workflow that your application will use. This is where you specify how the agents interact and what they do.
+=== "Cookiecutter"
+    Workflow will be generated within the `my_fastagency_app/workflow.py` folder. You will need to replace the existing `workflow.py` with the code below.
+=== "env + pip"
+    Create `workflow.py` and paste the code below inside.
+
+
+## Deployment Code
+=== "Cookiecutter"
+    Deployment files will be generated under `my_fastagency_app/deployment` folder. Generated `main.py` should be the same as the code below. You don't need change anything.
+=== "env + pip"
+    Create `deployment/main.py` and paste the code below inside.
+
+<details>
+<summary>main.py</summary>
+```python
+{! docs_src/getting_started/mesop/my_fastagency_app/my_fastagency_app/deployment/main.py [ln:1-10] !}
+```
+
+</details>
+
+
+## Starting the Application
+
+The FastAgency app is created, using the registered workflows (**`wf`**) and web-based user interface ([**`MesopUI`**](../../api/fastagency/ui/mesop/MesopUI.md)). This makes the conversation between agents and the user interactive.
+
+```python
+{! docs_src/getting_started/mesop/my_fastagency_app/my_fastagency_app/deployment/main.py [ln:6-10] !}
+```
+
+For more information, visit [**Mesop User Guide**](../../user-guide/ui/mesop/basics.md){target="_blank"}.
+
+
+## Running the Application
+
+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 my_fastagency_app.deployment.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 deployment.main:app
+            ```
+
+    === "Windows"
+        !!! note "Terminal"
+            ```console
+            pip install waitress
+            waitress-serve --listen=0.0.0.0:8000 deployment.main:app
+            ```
+
+```console
+[2024-10-10 13:19:18 +0530] [23635] [INFO] Starting gunicorn 23.0.0
+[2024-10-10 13:19:18 +0530] [23635] [INFO] Listening at: http://127.0.0.1:8000 (23635)
+[2024-10-10 13:19:18 +0530] [23635] [INFO] Using worker: sync
+[2024-10-10 13:19:18 +0530] [23645] [INFO] Booting worker with pid: 23645
+```
+
+The command will launch a web interface where users can input their requests and interact with the agents (in this case ***http://localhost:8000***)
+
+!!! note
+    Ensure that your OpenAI API key is set in the environment, as the agents rely on it to interact using GPT-4o. If the API key is not correctly configured, the application may fail to retrieve LLM-powered responses.