Merge pull request #672 from saimachi/skm-release-040-agent-docs-updates

deploy/starter/README.md

@@ -2,12 +2,14 @@
 
 ## Dependencies
 
-Mac and Linux users can install the following dependencies locally to run the deployment. Windows users should use Ubuntu on [WSL](https://learn.microsoft.com/en-us/windows/wsl/install) to run all deployment steps. Other WSL Linux distributions may work, but these instructions have been validated with Ubuntu 18.04, 20.04, and 22.04.
+Please install the following dependencies to deploy FLLM.
 
+- [PowerShell 7](https://learn.microsoft.com/en-us/powershell/scripting/install/installing-powershell?view=powershell-7.4) (required for `pwsh` to work in the AZD hooks as an alias to powershell)
 - [azd CLI](https://learn.microsoft.com/en-us/azure/developer/azure-developer-cli/install-azd)
 - [Azure CLI](https://learn.microsoft.com/en-us/cli/azure/install-azure-cli)
 - [jq](https://jqlang.github.io/jq/download/)
 - [Docker Desktop](https://www.docker.com/products/docker-desktop/)
+- [git](https://git-scm.com/downloads)
 
 ### azd CLI
 
@@ -24,7 +26,7 @@ Clone the FoundationaLLM repository
 git clone -b release/0.4.0 https://github.com/solliancenet/foundationallm
 ```
 
-Run the following commands to set the appropriate application registration settings for OIDC authentication. **Windows users should run them in WSL.**
+Run the following commands to set the appropriate application registration settings for OIDC authentication.
 
 ```bash
 cd foundationallm
@@ -59,12 +61,21 @@ azd env set ENTRA_VECTORIZATION_API_TENANT_ID <Vectorization API Tenant ID>
 azd env set FOUNDATIONALLM_INSTANCE_ID <guid>
 ```
 
->**Note:** You need to manually generate a GUID for your instance ID.
+>[!NOTE]
+> You need to manually generate a GUID for `FOUNDATIONALLM_INSTANCE_ID`.
+
+Bash:
 
 ```bash
 uuidgen
 ```
 
+PowerShell:
+
+```powershell
+[guid]::NewGuid().ToString()
+```
+
 After setting the OIDC-specific settings in the AZD environment above, run `azd up` in the same folder location to build the Docker images, provision the infrastructure, update the App Configuration entries, deploy the API and web app services, and import files into the storage account.
 
 ```bash

docs/deployment/deployment-starter.md

@@ -10,7 +10,7 @@ Foundationa**LLM** deploys into your own Azure Subscription. By default, it will
 - Docker Desktop.
 - Azure CLI ([v2.51.0 or greater](https://docs.microsoft.com/cli/azure/install-azure-cli)).
 - Azure Developer CLI ([v1.6.1 or greater](https://learn.microsoft.com/en-us/azure/developer/azure-developer-cli/install-azd))
-- Powershell 7 ([7.4.1 or greater](https://learn.microsoft.com/en-us/powershell/scripting/install/installing-powershell-on-windows?view=powershell-7.4))
+- PowerShell 7 ([7.4.1 or greater](https://learn.microsoft.com/en-us/powershell/scripting/install/installing-powershell-on-windows?view=powershell-7.4))
     > Note: Powershell 7 is required for `pwsh` to work in the AZD hooks as an alias to `powershell`
 - Visual Studio 2022 (only needed if you plan to run/debug the solution locally).
 - Minimum quota of 65 CPUs across all VM family types. Start here to [Manage VM Quotas](https://learn.microsoft.com/azure/quotas/per-vm-quota-requests).
@@ -35,9 +35,7 @@ Follow the steps below to deploy the solution to your Azure subscription. You wi
     git clone -b release/0.4.0 https://github.com/solliancenet/foundationallm.git 
     ```
 
-3. **Windows users should use Ubuntu in WSL, opened in the `foundationallm` directory, for the following steps; Mac and Linux users can follow them locally.**
-
-    Run the following commands to set the appropriate application registration settings for OIDC authentication. Please refer to the instructions on the [authentication setup page](authentication/index.md) to configure authentication for the solution and obtain the appropriate client Ids, scopes, and tenant Ids for the following steps.
+3. Run the following commands to set the appropriate application registration settings for OIDC authentication. Please refer to the instructions on the [authentication setup page](authentication/index.md) to configure authentication for the solution and obtain the appropriate client Ids, scopes, and tenant Ids for the following steps.
 
     ```bash
     cd deploy/starter
@@ -71,12 +69,21 @@ Follow the steps below to deploy the solution to your Azure subscription. You wi
     azd env set FOUNDATIONALLM_INSTANCE_ID <guid>
     ```
 
-    >**Note:** You need to manually generate a GUID for `FOUNDATIONALLM_INSTANCE_ID`.
+    >[!NOTE]
+    > You need to manually generate a GUID for `FOUNDATIONALLM_INSTANCE_ID`.
+
+    Bash:
 
     ```bash
     uuidgen
     ```
 
+    PowerShell:
+
+    ```powershell
+    [guid]::NewGuid().ToString()
+    ```
+
     After setting the OIDC-specific settings in the AZD environment above, run `azd up` in the same folder location to build the Docker images, provision the infrastructure, update the App Configuration entries, deploy the API and web app services, and import files into the storage account.
 
     ```bash
@@ -89,7 +96,7 @@ Follow the instructions on the [authentication setup page](authentication/index.
 
 ## Update APIs and portals from local code changes
 
-To update all APIs and portals from local code changes, run the following from the `./deploy/starter` folder in your locally cloned repository. Again, Windows users should use WSL.
+To update all APIs and portals from local code changes, run the following from the `./deploy/starter` folder in your locally cloned repository.
 
 ```bash
 azd deploy

docs/setup-guides/agents/internal-context-agent.md

@@ -8,8 +8,8 @@ The structure of an internal context agent is the following:
 
 ```json
 {
-  "name": "<name>",
   "type": "internal-context",
+  "name": "<name>",
   "object_id": "/instances/<instance_id>/providers/FoundationaLLM.Agent/agents/<name>",
   "description": "<description>",  
   "language_model": {
@@ -47,8 +47,8 @@ where:
 
 | Parameter | Description |
 | --- | --- |
+| `type` | The type of the agent - will always be `internal-context`. **`type` must be the first parameter in the request body.** |
 | `name` | The name of the agent. |
-| `type` | The type of the agent - will always be `internal-context`. |
 | `object_id` | The object ID of the agent. Remove this element when creating an agent as this is generated by the Management API. |
 | `description` | The description of the agent, ensure this description details the purpose of the agent. |
 | `language_model` | The language model configuration. This sample demonstrates the usage of the Azure OpenAI language model. |
@@ -98,6 +98,9 @@ where `<agent_configuration>` is the JSON agent configuration structure describe
 HTTP DELETE {{baseUrl}}/instances/{{instanceId}}/providers/FoundationaLLM.Agent/agents/<name>
 ```
 
+> [!NOTE]
+> FLLM currently implements logical deletes for Internal Context agents. This means that users cannot create an Internal Context agent with the same name as a deleted Internal Context agent. Support for purging Internal Context agents will be added in a future release.
+
 ## Validating an internal context agent
 
 Once configured, the internal context agent can be validated using an API call to the [Core API](../exposed-apis/core-api.md) or via the [User Portal](../quickstart.md).

docs/setup-guides/agents/knowledge-management-agent.md

@@ -24,8 +24,8 @@ The structure of a knowledge management agent is the following:
 
 ```json
 {
-  "name": "<name>",
   "type": "knowledge-management",
+  "name": "<name>",
   "object_id": "/instances/<instance_id>/providers/FoundationaLLM.Agent/agents/<name>",
   "description": "<description>",
   "indexing_profile_object_id": "<indexing_profile_resource_objectid>",
@@ -69,8 +69,8 @@ where:
 
 | Parameter | Description |
 | --- | --- |
+| `type` | The type of the agent - will always be `knowledge-management`. **`type` must be the first key in the request body.** |
 | `name` | The name of the agent. |
-| `type` | The type of the agent - will always be `knowledge-management`. |
 | `object_id` | The object ID of the agent. Remove this element when creating an agent as this is generated by the Management API. |
 | `description` | The description of the agent, ensure this description details the purpose of the agent. |
 | `indexing_profile_object_id` | The object ID of the indexing profile resource. |
@@ -123,6 +123,9 @@ where `<agent_configuration>` is the JSON agent configuration structure describe
 HTTP DELETE {{baseUrl}}/instances/{{instanceId}}/providers/FoundationaLLM.Agent/agents/<name>
 ```
 
+> [!NOTE]
+> FLLM currently implements logical deletes for Knowledge Management agents. This means that users cannot create a Knowledge Management agent with the same name as a deleted Knowledge Management agent. Support for purging Knowledge Management agents will be added in a future release.
+
 ## Validating a knowledge management agent
 
 Once configured, the knowledge management agent can be validated using an API call to the [Core API](../exposed-apis/core-api.md) or via the [User Portal](../quickstart.md).

docs/setup-guides/agents/prompt-resource.md

@@ -8,8 +8,8 @@ The structure of a prompt is the following:
 
 ```json
 {
+  "type": "multipart",
   "name": "<name>",
-  "type": "prompt",
   "object_id": "/instances/<instance_id>/providers/FoundationaLLM.Prompt/prompts/<name>",
   "description": "<description>",
   "prefix": "<prompt_prefix>",
@@ -27,8 +27,8 @@ where:
 
 | Parameter | Description |
 | --- | --- |
+| `type` | The type - will be `multipart`. `multipart` prompts have a prefix and suffix. Support for `basic` prompts, which have no suffix, will be added in a future release. **`type` must be the first parameter in the request body.** |
 | `name` | The name of the prompt. |
-| `type` | The type - will always be `prompt`. |
 | `object_id` | The object ID of the prompt. Remove this element when creating an prompt as this is generated by the Management API. |
 | `description` | The description of the prompt, ensure this description details the purpose or role of the prompt. |
 | `prompt_prefix` | The beginning of the prompt. |
@@ -61,3 +61,6 @@ where `<prompt_configuration>` is the prompt configuration structure described a
 ```http
 HTTP DELETE {{baseUrl}}/instances/{{instanceId}}/providers/FoundationaLLM.Prompt/prompts/<name>
 ```
+
+> [!NOTE]
+> FLLM currently implements logical deletes for Prompts. This means that users cannot create a Prompt with the same name as a deleted Prompt. Support for purging Prompts will be added in a future release.

docs/setup-guides/vectorization/vectorization-profiles.md

@@ -110,6 +110,9 @@ where `<content source profile>` is a JSON object with the structure described a
 HTTP DELETE {{baseUrl}}/instances/{{instanceId}}/providers/FoundationaLLM.Vectorization/contentsourceprofiles/<name>
 ```
 
+> [!NOTE]
+> FLLM implements a *logical delete* for Content Source profiles. This means that users cannot create a Content Source profile with the same name as a deleted profile. Support for purging Content Source profiles will be added in a future release.
+
 ## Text partitioning profiles
 
 The structure of a text partitioning profile is the following:
@@ -182,6 +185,9 @@ where `<text partitioning profile>` is a JSON object with the structure describe
 HTTP DELETE {{baseUrl}}/instances/{{instanceId}}/providers/FoundationaLLM.Vectorization/textpartitioningprofiles/<name>
 ```
 
+> [!NOTE]
+> FLLM implements a *logical delete* for Text Partitioning profiles. This means that users cannot create a Text Partitioning profile with the same name as a deleted profile. Support for purging Text Partitioning profiles will be added in a future release.
+
 ## Text embedding profiles
 
 The structure of a text embedding profile is the following:
@@ -254,6 +260,9 @@ where `<text embedding profile>` is a JSON object with the structure described a
 HTTP DELETE {{baseUrl}}/instances/{{instanceId}}/providers/FoundationaLLM.Vectorization/textembeddingprofiles/<name>
 ```
 
+> [!NOTE]
+> FLLM implements a *logical delete* for Text Embedding profiles. This means that users cannot create a Text Embedding profile with the same name as a deleted profile. Support for purging Text Embedding profiles will be added in a future release.
+
 ## Indexing profiles
 
 The structure of an indexing profile is the following:
@@ -327,6 +336,9 @@ where `<indexing profile>` is a JSON object with the structure described above.
 HTTP DELETE {{baseUrl}}/instances/{{instanceId}}/providers/FoundationaLLM.Vectorization/indexingprofiles/<name>
 ```
 
+> [!NOTE]
+> FLLM implements a *logical delete* for Text Indexing profiles. This means that users cannot create a Text Indexing profile with the same name as a deleted profile. Support for purging Text Indexing profiles will be added in a future release.
+
 ## Additional configuration steps
 
 ### Entra ID app registration for SharePoint Online content source