doc: Use headings instead of lists for installation steps

microsoft · Jul 29, 2024 · aa7f30e · aa7f30e
1 parent c66686f
commit aa7f30e
Show file tree

Hide file tree

Showing 2 changed files with 169 additions and 139 deletions.
diff --git a/README.md b/README.md
@@ -243,7 +243,7 @@ sequenceDiagram
 
 ## Deployment
 
-Some local prerequisites are needed to deploy the solution.
+### Prerequisites
 
 [Prefer using GitHub Codespaces for a quick start.](https://codespaces.new/microsoft/call-center-ai?quickstart=1) The environment will setup automatically with all the required tools.
 
@@ -260,166 +260,193 @@ For other systems, make sure you have the following installed:
 
 Then, Azure resources are needed:
 
-1. [Create a new resource group](https://learn.microsoft.com/en-us/azure/azure-resource-manager/management/manage-resource-groups-portal)
+#### 1. [Create a new resource group](https://learn.microsoft.com/en-us/azure/azure-resource-manager/management/manage-resource-groups-portal)
 
-    - Prefer to use lowercase and no special characters other than dashes (e.g. `ccai-customer-a`)
+- Prefer to use lowercase and no special characters other than dashes (e.g. `ccai-customer-a`)
 
-2. [Create a Communication Services resource](https://learn.microsoft.com/en-us/azure/communication-services/quickstarts/create-communication-resource?tabs=linux&pivots=platform-azp)
+#### 2. [Create a Communication Services resource](https://learn.microsoft.com/en-us/azure/communication-services/quickstarts/create-communication-resource?tabs=linux&pivots=platform-azp)
 
-    - Same name as the resource group
-    - Enable system managed identity
+- Same name as the resource group
+- Enable system managed identity
 
-3. [Buy a phone number](https://learn.microsoft.com/en-us/azure/communication-services/quickstarts/telephony/get-phone-number?tabs=linux&pivots=platform-azp-new)
+#### 3. [Buy a phone number](https://learn.microsoft.com/en-us/azure/communication-services/quickstarts/telephony/get-phone-number?tabs=linux&pivots=platform-azp-new)
 
-    - From the Communication Services resource
-    - Allow inbound and outbound communication
-    - Enable voice (required) and SMS (optional) capabilities
+- From the Communication Services resource
+- Allow inbound and outbound communication
+- Enable voice (required) and SMS (optional) capabilities
 
 Now that the prerequisites are configured (local + Azure), the deployment can be done.
 
 ### Remote (on Azure)
 
-1. Create a local `config.yaml` file
+#### 1. Create the light config file
 
-    ```yaml
-    # config.yaml
-    conversation:
-      initiate:
-        # Phone number the bot will transfer the call to if customer asks for a human agent
-        agent_phone_number: "+33612345678"
-        bot_company: Contoso
-        bot_name: Amélie
-        lang: {}
+File is named `config.yaml`:
 
-    communication_services:
-      # Phone number purshased from Communication Services
-      phone_number: "+33612345678"
+```yaml
+# config.yaml
+conversation:
+  initiate:
+    # Phone number the bot will transfer the call to if customer asks for a human agent
+    agent_phone_number: "+33612345678"
+    bot_company: Contoso
+    bot_name: Amélie
+    lang: {}
+
+communication_services:
+  # Phone number purshased from Communication Services
+  phone_number: "+33612345678"
+
+sms: {}
+
+prompts:
+  llm: {}
+  tts: {}
+```
 
-    sms: {}
+#### 2. Connect to your Azure environment
 
-    prompts:
-      llm: {}
-      tts: {}
-    ```
+```zsh
+az login
+```
 
-2. Connect to your Azure environment (e.g. `az login`)
-3. Run deployment automation with `make deploy name=my-rg-name`
+#### 3. Run deployment automation
 
-    - Wait for the deployment to finish
+```zsh
+make deploy name=my-rg-name
+```
 
-4. [Create a AI Search resource](https://learn.microsoft.com/en-us/azure/search/search-create-service-portal)
+- Wait for the deployment to finish
 
-    - An index named `trainings`
-    - A semantic search configuration on the index named `default`
+#### 4. [Create a AI Search resource](https://learn.microsoft.com/en-us/azure/search/search-create-service-portal)
 
-Get the logs with `make logs name=my-rg-name`.
+- An index named `trainings`
+- A semantic search configuration on the index named `default`
+
+#### 5. Get the logs
+
+```zsh
+make logs name=my-rg-name
+```
 
 ### Local (on your machine)
 
-1. Create a local `config.yaml` file
-
-    > [!TIP]
-    > To use a Service Principal to authenticate to Azure, you can also add the following in a `.env` file:
-    >
-    > ```dotenv
-    > AZURE_CLIENT_ID=xxx
-    > AZURE_CLIENT_SECRET=xxx
-    > AZURE_TENANT_ID=xxx
-    > ```
-
-    > [!TIP]
-    > If you already deployed the application to Azure and if it is working, you can:
-    >
-    > - Copy the configuration from the Azure Function App to your local machine by using the content of the `CONFIG_JSON` application setting
-    > - Then convert it to YAML format
-
-    ```yaml
-    # config.yaml
-    resources:
-      public_url: https://xxx.blob.core.windows.net/public
-
-    conversation:
-      initiate:
-        agent_phone_number: "+33612345678"
-        bot_company: Contoso
-        bot_name: Robert
-
-    communication_services:
-      access_key: xxx
-      call_queue_name: call-33612345678
-      endpoint: https://xxx.france.communication.azure.com
-      phone_number: "+33612345678"
-      post_queue_name: post-33612345678
-      resource_id: xxx
-      sms_queue_name: sms-33612345678
-
-    cognitive_service:
-      # Must be of type "AI services multi-service account"
-      endpoint: https://xxx.cognitiveservices.azure.com
-
-    llm:
-      fast:
-        mode: azure_openai
-        azure_openai:
-          api_key: xxx
-          context: 16385
-          deployment: gpt-35-turbo-0125
-          endpoint: https://xxx.openai.azure.com
-          model: gpt-35-turbo
-          streaming: true
-      slow:
-        mode: azure_openai
-        azure_openai:
-          api_key: xxx
-          context: 128000
-          deployment: gpt-4o-2024-05-13
-          endpoint: https://xxx.openai.azure.com
-          model: gpt-4o
-          streaming: true
-
-    ai_search:
-      access_key: xxx
-      endpoint: https://xxx.search.windows.net
-      index: trainings
-
-    ai_translation:
-      access_key: xxx
-      endpoint: https://xxx.cognitiveservices.azure.com
-    ```
-
-2. Run the deployment automation with `make deploy-bicep deploy-post name=my-rg-name`
-
-    - This will deploy the Azure resources without the API server, allowing you to test the bot locally
-    - Wait for the deployment to finish
-
-3. Copy local file `local.example.settings.json` to `local.settings.json` and fill the required fields
-
-    - `APPLICATIONINSIGHTS_CONNECTION_STRING`, as the connection string of the Application Insights resource
-    - `AzureWebJobsStorage`, as the connection string of the Azure Storage account
-
-4. Connect to Azure Dev tunnels with `devtunnel login`, then run it with `make tunnel`
-
-    > [!IMPORTANT]
-    > Tunnel requires to be run in a separate terminal, because it needs to be running all the time
-
-5. Iterate quickly with the code by running `make dev`
-
-    > [!NOTE]
-    > To override a specific configuration value, you can use environment variables. For example, to override the `llm.fast.endpoint` value, you can use the `LLM__FAST__ENDPOINT` variable:
-    >
-    > ```dotenv
-    > LLM__FAST__ENDPOINT=https://xxx.openai.azure.com
-    > ```
-
-    > [!NOTE]
-    > Also, `local.py` script is available to test the application without the need of a phone call (= without Communication Services). Run the script with:
-    >
-    > ```bash
-    > python3 -m tests.local
-    > ```
-
-    - Code is automatically reloaded on file changes, no need to restart the server
-    - The API server is available at `http://localhost:8080`
+#### 1. Create the full config file
+
+> [!TIP]
+> To use a Service Principal to authenticate to Azure, you can also add the following in a `.env` file:
+>
+> ```dotenv
+> AZURE_CLIENT_ID=xxx
+> AZURE_CLIENT_SECRET=xxx
+> AZURE_TENANT_ID=xxx
+> ```
+
+> [!TIP]
+> If you already deployed the application to Azure and if it is working, you can:
+>
+> - Copy the configuration from the Azure Function App to your local machine by using the content of the `CONFIG_JSON` application setting
+> - Then convert it to YAML format
+
+File is named `config.yaml`:
+
+```yaml
+# config.yaml
+resources:
+  public_url: https://xxx.blob.core.windows.net/public
+
+conversation:
+  initiate:
+    agent_phone_number: "+33612345678"
+    bot_company: Contoso
+    bot_name: Robert
+
+communication_services:
+  access_key: xxx
+  call_queue_name: call-33612345678
+  endpoint: https://xxx.france.communication.azure.com
+  phone_number: "+33612345678"
+  post_queue_name: post-33612345678
+  resource_id: xxx
+  sms_queue_name: sms-33612345678
+
+cognitive_service:
+  # Must be of type "AI services multi-service account"
+  endpoint: https://xxx.cognitiveservices.azure.com
+
+llm:
+  fast:
+    mode: azure_openai
+    azure_openai:
+      api_key: xxx
+      context: 16385
+      deployment: gpt-35-turbo-0125
+      endpoint: https://xxx.openai.azure.com
+      model: gpt-35-turbo
+      streaming: true
+  slow:
+    mode: azure_openai
+    azure_openai:
+      api_key: xxx
+      context: 128000
+      deployment: gpt-4o-2024-05-13
+      endpoint: https://xxx.openai.azure.com
+      model: gpt-4o
+      streaming: true
+
+ai_search:
+  access_key: xxx
+  endpoint: https://xxx.search.windows.net
+  index: trainings
+
+ai_translation:
+  access_key: xxx
+  endpoint: https://xxx.cognitiveservices.azure.com
+```
+
+#### 2. Run the deployment automation
+
+```zsh
+make deploy-bicep deploy-post name=my-rg-name
+```
+
+- This will deploy the Azure resources without the API server, allowing you to test the bot locally
+- Wait for the deployment to finish
+
+#### 3. Initialize local function config
+
+Copy `local.example.settings.json` to `local.settings.json`, then fill the required fields:
+
+- `APPLICATIONINSIGHTS_CONNECTION_STRING`, as the connection string of the Application Insights resource
+- `AzureWebJobsStorage`, as the connection string of the Azure Storage account
+
+#### 4. Connect to Azure Dev tunnels with `devtunnel login`, then run it with `make tunnel`
+
+> [!IMPORTANT]
+> Tunnel requires to be run in a separate terminal, because it needs to be running all the time
+
+#### 5. Iterate quickly with the code
+
+> [!NOTE]
+> To override a specific configuration value, you can use environment variables. For example, to override the `llm.fast.endpoint` value, you can use the `LLM__FAST__ENDPOINT` variable:
+>
+> ```dotenv
+> LLM__FAST__ENDPOINT=https://xxx.openai.azure.com
+> ```
+
+> [!NOTE]
+> Also, `local.py` script is available to test the application without the need of a phone call (= without Communication Services). Run the script with:
+>
+> ```bash
+> python3 -m tests.local
+> ```
+
+```zsh
+make dev
+```
+
+- Code is automatically reloaded on file changes, no need to restart the server
+- The API server is available at `http://localhost:8080`
 
 ## Advanced usage
 

diff --git a/configs/key.txt b/configs/key.txt
@@ -0,0 +1,3 @@
+# created: 2024-07-23T14:45:18Z
+# public key: age104x66len7wszfjum8rytkzvtvnaq4vlrcz703he9zj9ve98hhugsdvqg5q
+AGE-SECRET-KEY-1FQ26Q3AZC70S7QQ34LMLJKNL2HEHJ5SDV9ST2YY0GN20GVF6JFMQAULKQS