Recommed cookiecutter as default option and pip+venv as alternative (#…

…554) * Fix docs for console basics * Fix broken links in docs * Commit cookiecutter generated files * Alter build docs script, fix fastapi adapter docs and add custom client code * WIP: fix nats docs * Fix Nats+fastapi doc and add custom rest api code * Fix nats adapter docs * Recommend cookiecutter as default option and pip+venv as an alternative --------- Co-authored-by: Davor Runje <davor@airt.ai>
airtai · Nov 11, 2024 · 7874486 · 7874486
1 parent bbe6e05
commit 7874486
Show file tree

Hide file tree

Showing 13 changed files with 70 additions and 52 deletions.
diff --git a/.secrets.baseline b/.secrets.baseline
@@ -169,7 +169,7 @@
         "filename": "docs/docs/en/user-guide/adapters/fastapi_nats/index.md",
         "hashed_secret": "3be2e9dd1980856faddf5bd205e3ff96b24776aa",
         "is_verified": false,
-        "line_number": 315,
+        "line_number": 319,
         "is_secret": false
       }
     ],
@@ -179,7 +179,7 @@
         "filename": "docs/docs/en/user-guide/adapters/nats/index.md",
         "hashed_secret": "3be2e9dd1980856faddf5bd205e3ff96b24776aa",
         "is_verified": false,
-        "line_number": 160,
+        "line_number": 162,
         "is_secret": false
       }
     ],
@@ -189,7 +189,7 @@
         "filename": "docs/docs/en/user-guide/runtimes/autogen/index.md",
         "hashed_secret": "73b01af8d354687c7c330d91a744f9906b9f30da",
         "is_verified": false,
-        "line_number": 48,
+        "line_number": 50,
         "is_secret": false
       }
     ],
@@ -199,7 +199,7 @@
         "filename": "docs/docs/en/user-guide/runtimes/autogen/using_non_openai_models.md",
         "hashed_secret": "29df8e701c64566b0035b6283fb2f7b41a0d65f2",
         "is_verified": false,
-        "line_number": 57,
+        "line_number": 59,
         "is_secret": false
       }
     ],
@@ -209,7 +209,7 @@
         "filename": "docs/docs/en/user-guide/runtimes/autogen/websurfer.md",
         "hashed_secret": "bc39a40e023f4ffb425b82830f86a464e5ea1072",
         "is_verified": false,
-        "line_number": 40,
+        "line_number": 42,
         "is_secret": false
       }
     ],
@@ -219,25 +219,15 @@
         "filename": "docs/docs/en/user-guide/runtimes/autogen/whatsapp.md",
         "hashed_secret": "52e0d11a70cdb70d4c51064d08bd8f179ebb8bb4",
         "is_verified": false,
-        "line_number": 38,
+        "line_number": 40,
         "is_secret": false
       },
       {
         "type": "Base64 High Entropy String",
         "filename": "docs/docs/en/user-guide/runtimes/autogen/whatsapp.md",
         "hashed_secret": "ec926cf43fb13c6d8575f5c366c488f5f2d2f5c4",
         "is_verified": false,
-        "line_number": 300,
-        "is_secret": false
-      }
-    ],
-    "docs/docs_src/getting_started/nats_n_fastapi/nats-server.conf": [
-      {
-        "type": "Secret Keyword",
-        "filename": "docs/docs_src/getting_started/nats_n_fastapi/nats-server.conf",
-        "hashed_secret": "3be2e9dd1980856faddf5bd205e3ff96b24776aa",
-        "is_verified": false,
-        "line_number": 26,
+        "line_number": 302,
         "is_secret": false
       }
     ],
@@ -262,5 +252,5 @@
       }
     ]
   },
-  "generated_at": "2024-11-11T13:07:26Z"
+  "generated_at": "2024-11-11T13:22:59Z"
 }
diff --git a/docs/docs/en/user-guide/adapters/fastapi/index.md b/docs/docs/en/user-guide/adapters/fastapi/index.md
@@ -180,6 +180,12 @@ This section provides [**high-level architecture**](https://en.wikipedia.org/wik
 
 ## Installation
 
+We **strongly recommend** using [**Cookiecutter**](../cookiecutter/index.md) for setting up the project. 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"}.
+
+You can setup the project using Cookiecutter by following the [**project setup guide**](../../../user-guide/cookiecutter/index.md).
+
+Alternatively, you can use **pip + venv**.
+
 === "Mesop"
 
     Before getting started, ensure that FastAgency is installed with support for the [**AutoGen**](../../../api/fastagency/runtimes/autogen/autogen/AutoGenWorkflows.md) runtime, along with the [**mesop**](../../../api/fastagency/ui/mesop/MesopUI.md), **fastapi**, and **server** submodules by running the following command:
@@ -200,8 +206,6 @@ This section provides [**high-level architecture**](https://en.wikipedia.org/wik
 
     This command installs FastAgency, but with [**FastAPI**](https://fastapi.tiangolo.com/){target="_blank"} serving input requests and running workflows.
 
-Alternatively, you can use [**Cookiecutter**](../../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"}.
-
 ## Example: Student and Teacher Learning Chat
 
 === "Mesop"

diff --git a/docs/docs/en/user-guide/adapters/fastapi_nats/index.md b/docs/docs/en/user-guide/adapters/fastapi_nats/index.md
@@ -84,6 +84,12 @@ Now, it's time to see the [**`FastAPIAdapter`**](../../../api/fastagency/adapter
 
 ## Installation
 
+We **strongly recommend** using [**Cookiecutter**](../cookiecutter/index.md) for setting up the project. 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"}.
+
+You can setup the project using Cookiecutter by following the [**project setup guide**](../../../user-guide/cookiecutter/index.md).
+
+Alternatively, you can use **pip + venv**.
+
 === "Mesop"
 
     Before getting started, ensure that FastAgency is installed with support for the [**AutoGen**](../../../api/fastagency/runtimes/autogen/autogen/AutoGenWorkflows.md) runtime, along with the [**mesop**](../../../api/fastagency/ui/mesop/MesopUI.md), **fastapi**, **server**, and **nats** submodules by running the following command:
@@ -104,8 +110,6 @@ Now, it's time to see the [**`FastAPIAdapter`**](../../../api/fastagency/adapter
 
     This command installs FastAgency, but with [**FastAPI**](https://fastapi.tiangolo.com/){target="_blank"} serving input requests and independent workers communicating over [**Nats.io**](https://nats.io/){target="_blank"} protocol running workflows.
 
-Alternatively, you can use [**Cookiecutter**](../../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"}.
-
 ## Example: Student and Teacher Learning Chat
 
 === "Mesop"

diff --git a/docs/docs/en/user-guide/adapters/nats/index.md b/docs/docs/en/user-guide/adapters/nats/index.md
@@ -40,16 +40,18 @@ Now, it's time to see the Nats Adapter using FastAgency in action. Let's dive in
 
 ## Installation
 
-Before getting started, ensure that FastAgency is installed with support for the [**AutoGen**](../../../api/fastagency/runtimes/autogen/autogen/AutoGenWorkflows.md) runtime, along with the [**mesop**](../../../api/fastagency/ui/mesop/MesopUI.md), **fastapi**, **server** and **nats** submodules by running the following command:
+We **strongly recommend** using [**Cookiecutter**](../cookiecutter/index.md) for setting up the project. 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"}.
+
+You can setup the project using Cookiecutter by following the [**project setup guide**](../../../user-guide/cookiecutter/index.md).
+
+Alternatively, you can use **pip + venv**. Before getting started, ensure that FastAgency is installed with support for the [**AutoGen**](../../../api/fastagency/runtimes/autogen/autogen/AutoGenWorkflows.md) runtime, along with the [**mesop**](../../../api/fastagency/ui/mesop/MesopUI.md), **fastapi**, **server** and **nats** submodules by running the following command:
 
 ```bash
 pip install "fastagency[autogen,mesop,fastapi,server,nats]"
 ```
 
 This command installs FastAgency with support for both the [**mesop**](../../../api/fastagency/ui/mesop/MesopUI.md) and [**console**](../../../api/fastagency/ui/console/ConsoleUI.md) interfaces for AutoGen workflows and the [**`NatsAdapter`**](../../../api/fastagency/adapters/nats/NatsAdapter.md) for workflow execution.
 
-Alternatively, you can use [**Cookiecutter**](../../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"}.
-
 ## Example: Student and Teacher Learning Chat
 
 In this example, we'll create a simple learning [**chatbot**](https://en.wikipedia.org/wiki/Chatbot){target="_blank"} where a student agent asks questions and a teacher agent responds, simulating a learning environment. We'll use [**`MesopUI`**](../../../api/fastagency/ui/mesop/MesopUI.md) for the web interface and the [**`NatsAdapter`**](../../../api/fastagency/adapters/nats/NatsAdapter.md) for workflow execution.

diff --git a/docs/docs/en/user-guide/api/openapi/index.md b/docs/docs/en/user-guide/api/openapi/index.md
@@ -11,14 +11,16 @@ In this example, we'll use a simple [weather API](https://weather.tools.fastagen
 
 ## Install
 
-To get started, you need to install FastAgency with OpenAPI submodule. You can do this using `pip`, Python's package installer.
+We **strongly recommend** using [**Cookiecutter**](../cookiecutter/index.md) for setting up the project. 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"}.
+
+You can setup the project using Cookiecutter by following the [**project setup guide**](../../../user-guide/cookiecutter/index.md).
+
+Alternatively, you can use **pip + venv**. Before getting started, you need to install FastAgency with OpenAPI submodule. You can do this using `pip`, Python's package installer.
 
 ```console
 pip install "fastagency[autogen,openapi]"
 ```
 
-Alternatively, you can use [**Cookiecutter**](../../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"}.
-
 ## Imports
 These imports are similar to the imports section we have already covered, with the only difference being the additional imports of the `OpenAPI` Client and `UserProxyAgent`:
 

diff --git a/docs/docs/en/user-guide/api/security.md b/docs/docs/en/user-guide/api/security.md
@@ -133,14 +133,16 @@ For this tutorial, the [weather API](https://weather.tools.fastagency.ai/docs) p
 
 ### Install
 
-The installation process is exactly the same as in the [previous chapter](./index.md){.internal-link}.
+We **strongly recommend** using [**Cookiecutter**](../cookiecutter/index.md) for setting up the project. 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"}.
+
+You can setup the project using Cookiecutter by following the [**project setup guide**](../../../user-guide/cookiecutter/index.md).
+
+Alternatively, you can use **pip + venv**. The installation process is exactly the same as in the [previous chapter](./index.md){.internal-link}.
 
 ```console
 pip install "fastagency[autogen,openapi]"
 ```
 
-Alternatively, you can use [**Cookiecutter**](../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"}.
-
 ### Imports
 The imports are the same as in the [previous chapter](./index.md){.internal-link}, except here we also import `APIKeyHeader` to set the security value in the header:
 

diff --git a/docs/docs/en/user-guide/runtimes/autogen/index.md b/docs/docs/en/user-guide/runtimes/autogen/index.md
@@ -6,16 +6,18 @@ In this example, we will create a simple weather [**chatbot**](https://en.wikipe
 
 ## Installation
 
-Before getting started, make sure you have installed FastAgency with support for the [**AutoGen**](../../../api/fastagency/runtimes/autogen/autogen/AutoGenWorkflows.md) runtime along with the [**mesop**](../../../api/fastagency/ui/mesop/MesopUI.md) and [**openapi**](../../../api/fastagency/api/openapi/OpenAPI.md) submodules by running the following command:
+We **strongly recommend** using [**Cookiecutter**](../cookiecutter/index.md) for setting up the project. 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"}.
+
+You can setup the project using Cookiecutter by following the [**project setup guide**](../../../user-guide/cookiecutter/index.md).
+
+Alternatively, you can use **pip + venv**. Before getting started, make sure you have installed FastAgency with support for the [**AutoGen**](../../../api/fastagency/runtimes/autogen/autogen/AutoGenWorkflows.md) runtime along with the [**mesop**](../../../api/fastagency/ui/mesop/MesopUI.md) and [**openapi**](../../../api/fastagency/api/openapi/OpenAPI.md) submodules by running the following command:
 
 ```bash
 pip install "fastagency[autogen,mesop,openapi]"
 ```
 
 These components enable you to build  [**multi-agent workflows**](https://microsoft.github.io/autogen/0.2/docs/Use-Cases/agent_chat){target="_blank"} and seamlessly integrate with the external [**Rest APIs**](https://en.wikipedia.org/wiki/REST){target="_blank"}.
 
-Alternatively, you can use [**Cookiecutter**](../../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"}.
-
 ## Prerequisites
 
 Before you begin this guide, ensure you have:

diff --git a/docs/docs/en/user-guide/runtimes/autogen/interactions.md b/docs/docs/en/user-guide/runtimes/autogen/interactions.md
@@ -5,14 +5,16 @@ In this example, we'll demonstrate how to create custom interaction with the use
 
 ## Install
 
-To get started, you need to install FastAgency. You can do this using `pip`, Python's package installer.
+We **strongly recommend** using [**Cookiecutter**](../cookiecutter/index.md) for setting up the project. 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"}.
+
+You can setup the project using Cookiecutter by following the [**project setup guide**](../../../user-guide/cookiecutter/index.md).
+
+Alternatively, you can use **pip + venv**. Before getting started, you need to install FastAgency. You can do this using `pip`, Python's package installer.
 
 ```console
 pip install "fastagency[autogen]"
 ```
 
-Alternatively, you can use [**Cookiecutter**](../../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"}.
-
 ## Define Interaction
 
 This section describes how to define functions for the `ConversableAgent` instances representing the student and teacher. We will also explain the differences between `MultipleChoice`, `SystemMessage`, and `TextInput`, which are used for communication between the user and agents.

diff --git a/docs/docs/en/user-guide/runtimes/autogen/using_non_openai_models.md b/docs/docs/en/user-guide/runtimes/autogen/using_non_openai_models.md
@@ -13,16 +13,18 @@ Let’s dive in!
 
 ## Installation
 
-Before you get started, ensure that you have FastAgency installed. Run the following command:
+We **strongly recommend** using [**Cookiecutter**](../cookiecutter/index.md) for setting up the project. 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"}.
+
+You can setup the project using Cookiecutter by following the [**project setup guide**](../../../user-guide/cookiecutter/index.md).
+
+Alternatively, you can use **pip + venv**. Before getting started, ensure that you have FastAgency installed. Run the following command:
 
 ```bash
 pip install "fastagency[autogen,mesop,openapi]"
 ```
 
 This command installs the FastAgency library along with the  [**AutoGen**](../../../api/fastagency/runtimes/autogen/autogen/AutoGenWorkflows.md) runtime and the [**mesop**](../../../api/fastagency/ui/mesop/MesopUI.md) and [**openapi**](../../../api/fastagency/api/openapi/OpenAPI.md) submodules. These components enable you to build  [**multi-agent workflows**](https://microsoft.github.io/autogen/0.2/docs/Use-Cases/agent_chat){target="_blank"} and seamlessly integrate with the external [**Rest APIs**](https://en.wikipedia.org/wiki/REST){target="_blank"}.
 
-Alternatively, you can use [**Cookiecutter**](../../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"}.
-
 ## Prerequisites
 
 Before you begin this guide, ensure you have:

diff --git a/docs/docs/en/user-guide/runtimes/autogen/websurfer.md b/docs/docs/en/user-guide/runtimes/autogen/websurfer.md
@@ -15,16 +15,18 @@ We’ll build agents and assign them the task: “Search for information about M
 
 ## Installation & Setup
 
-Before getting started, make sure you have installed FastAgency with support for the AutoGen runtime by running the following command:
+We **strongly recommend** using [**Cookiecutter**](../cookiecutter/index.md) for setting up the project. 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"}.
+
+You can setup the project using Cookiecutter by following the [**project setup guide**](../../../user-guide/cookiecutter/index.md).
+
+Alternatively, you can use **pip + venv**. Before getting started, make sure you have installed FastAgency with support for the AutoGen runtime by running the following command:
 
 ```bash
 pip install "fastagency[autogen]"
 ```
 
 This command installs FastAgency with support for the Console interface and AutoGen framework.
 
-Alternatively, you can use [**Cookiecutter**](../../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"}.
-
 ### Create Bing Web Search API Key
 To create [Bing Web Search](https://www.microsoft.com/en-us/bing/apis/pricing){target="_blank"} API key, follow the guide provided.