microsoft · marktayl1 · Apr 22, 2025 · Apr 22, 2025 · Apr 22, 2025 · Apr 22, 2025
diff --git a/README.md b/README.md
diff --git a/documentation/AzureGPTQuotaSettings.md b/documentation/AzureGPTQuotaSettings.md
@@ -0,0 +1,10 @@
+## How to Check & Update Quota
+
+1. **Navigate** to the [Azure AI Foundry portal](https://ai.azure.com/).  
+2. **Select** the AI Project associated with this accelerator.  
+3. **Go to** the `Management Center` from the bottom-left navigation menu.  
+4. Select `Quota`  
+   - Click on the `GlobalStandard` dropdown.  
+   - Select the required **GPT model** (`GPT-4o`)
+   - Choose the **region** where the deployment is hosted.  
+5. Request More Quota or delete any unused model deployments as needed.  
diff --git a/documentation/CustomizingAzdParameters.md b/documentation/CustomizingAzdParameters.md
@@ -0,0 +1,43 @@
+## [Optional]: Customizing resource names 
+
+By default this template will use the environment name as the prefix to prevent naming collisions within Azure. The parameters below show the default values. You only need to run the statements below if you need to change the values. 
+
+
+> To override any of the parameters, run `azd env set <key> <value>` before running `azd up`. On the first azd command, it will prompt you for the environment name. Be sure to choose 3-20 charaters alphanumeric unique name. 
+
+
+Change the Secondary Location (example: eastus2, westus2, etc.)
+
+```shell
+azd env set AZURE_ENV_COSMOS_LOCATION eastus2
+```
+
+Change the Model Deployment Type (allowed values: Standard, GlobalStandard)
+
+```shell
+azd env set AZURE_ENV_MODEL_DEPLOYMENT_TYPE Standard
+```
+
+Set the Model Name (allowed values: gpt-4, gpt-4o)
+
+```shell
+azd env set AZURE_ENV_MODEL_NAME gpt-4o
+```
+
+Change the Model Capacity (choose a number based on available GPT model capacity in your subscription)
+
+```shell
+azd env set AZURE_ENV_MODEL_CAPACITY 30
+```
+
+Change the Embedding Model 
+
+```shell
+azd env set AZURE_ENV_EMBEDDING_MODEL_NAME text-embedding-ada-002
+```
+
+Change the Embedding Deployment Capacity (choose a number based on available embedding model capacity in your subscription)
+
+```shell
+azd env set AZURE_ENV_EMBEDDING_MODEL_CAPACITY 80
+```
diff --git a/documentation/DeleteResourceGroup.md b/documentation/DeleteResourceGroup.md
@@ -0,0 +1,53 @@
+# Deleting Resources After a Failed Deployment in Azure Portal
+
+If your deployment fails and you need to clean up the resources manually, follow these steps in the Azure Portal.
+
+---
+
+## **1. Navigate to the Azure Portal**
+1. Open [Azure Portal](https://portal.azure.com/).
+2. Sign in with your Azure account.
+
+---
+
+## **2. Find the Resource Group**
+1. In the search bar at the top, type **"Resource groups"** and select it.
+2. Locate the **resource group** associated with the failed deployment.
+
+![Resource Groups](images/resourcegroup.png)
+
+![Resource Groups](images/resource-groups.png)
+
+---
+
+## **3. Delete the Resource Group**
+1. Click on the **resource group name** to open it.
+2. Click the **Delete resource group** button at the top.
+
+![Delete Resource Group](images/DeleteRG.png)
+
+3. Type the resource group name in the confirmation box and click **Delete**.
+
+📌 **Note:** Deleting a resource group will remove all resources inside it.
+
+---
+
+## **4. Delete Individual Resources (If Needed)**
+If you don’t want to delete the entire resource group, follow these steps:
+
+1. Open **Azure Portal** and go to the **Resource groups** section.
+2. Click on the specific **resource group**.
+3. Select the **resource** you want to delete (e.g., App Service, Storage Account).
+4. Click **Delete** at the top.
+
+![Delete Individual Resource](images/deleteservices.png)
+
+---
+
+## **5. Verify Deletion**
+- After a few minutes, refresh the **Resource groups** page.
+- Ensure the deleted resource or group no longer appears.
+
+📌 **Tip:** If a resource fails to delete, check if it's **locked** under the **Locks** section and remove the lock.
+
+
diff --git a/documentation/ManualAzureDeployment.md b/documentation/ManualAzureDeployment.md
@@ -0,0 +1,109 @@
+# Manual Azure Deployment
+Manual Deployment differs from the ‘Quick Deploy’ option in that it will install an Azure Container Registry (ACR) service, and relies on the installer to build and push the necessary containers to this ACR.  This allows you to build and push your own code changes and provides a sample solution you can customize based on your requirements.
+
+## Prerequisites
+
+- Current Azure CLI installed
+  You can update to the latest version using ```az upgrade```
+- Azure account with appropriate permissions
+- Docker installed
+
+## Deploy the Azure Services
+All of the necessary Azure services can be deployed using the /deploy/macae.bicep script.  This script will require the following parameters:
+
+```
+az login
+az account set --subscription <SUBSCRIPTION_ID>
+az group create --name <RG_NAME> --location <RG_LOCATION>
+```
+To deploy the script you can use the Azure CLI.
+```
+az deployment group create \
+  --resource-group <RG_NAME> \
+  --template-file <BICEP_FILE> \
+  --name <DEPLOYMENT_NAME>
+```
+
+Note: if you are using windows with PowerShell, the continuation character (currently ‘\’) should change to the tick mark (‘`’).
+
+The template will require you fill in locations for Cosmos and OpenAI services.  This is to avoid the possibility of regional quota errors for either of these resources.
+
+## Create the Containers
+- Get admin credentials from ACR
+
+Retrieve the admin credentials for your Azure Container Registry (ACR):
+
+```sh
+az acr credential show \
+--name <e.g. macaeacr2t62qyozi76bs> \
+--resource-group <rg-name>
+```
+
+## Login to ACR
+
+Login to your Azure Container Registry:
+
+```sh
+az acr login --name <e.g. macaeacr2t62qyozi76bs>
+```
+
+## Build and push the image
+
+Build the frontend and backend Docker images and push them  to your Azure Container Registry. Run the following from the src/backend and the src/frontend directory contexts:
+
+```sh
+az acr build \
+--registry <e.g. macaeacr2t62qyozi76bs> \
+--resource-group <rg-name> \
+--image <e.g. backendmacae:latest> .
+```
+
+## Add images to the Container APP and Web App services
+
+To add your newly created backend image: 
+- Navigate to the Container App Service in the Azure portal
+- Click on Application/Containers in the left pane
+- Click on the "Edit and deploy" button in the upper left of the containers pane
+- In the "Create and deploy new revision" page, click on your container image 'backend'.  This will give you the option of reconfiguring the container image, and also has an Environment variables tab
+- Change the properties page to 
+  - point to your Azure Container registry with a private image type and your image name (e.g. backendmacae:latest)
+  - under "Authentication type" select "Managed Identity" and choose the 'mace-containerapp-pull'... identity setup in the bicep template
+- In the environment variables section add the following (each with a 'Manual entry' source):
+
+        name: 'COSMOSDB_ENDPOINT'
+        value: \<Cosmos endpoint>
+
+        name: 'COSMOSDB_DATABASE'
+        value: 'autogen'
+	    Note: To change the default, you will need to create the database in Cosmos
+
+        name: 'COSMOSDB_CONTAINER'
+        value: 'memory'
+
+        name: 'AZURE_OPENAI_ENDPOINT'
+        value: <Azure OpenAI endpoint>
+
+        name: 'AZURE_OPENAI_DEPLOYMENT_NAME'
+        value: 'gpt-4o'
+
+        name: 'AZURE_OPENAI_API_VERSION'
+        value: '2024-08-01-preview'
+		Note: Version should be updated based on latest available
+
+        name: 'FRONTEND_SITE_NAME'
+        value: 'https://<website Name>.azurewebsites.net'
+
+        name: 'APPLICATIONINSIGHTS_CONNECTION_STRING'
+        value: <Application Insights Connection String>
+
+- Click 'Save' and deploy your new revision
+
+To add the new container to your website run the following:
+
+```
+az webapp config container set --resource-group <resource_group_name> \
+--name <container_name> \
+--container-image-name <e.g. macaeacr2t62qyozi76bs.azurecr.io/frontendmacae:latest>  \
+--container-registry-url <e.g. https://macaeacr2t62qyozi76bs.azurecr.io>
+```
+
diff --git a/documentation/SampleQuestions.md b/documentation/SampleQuestions.md
@@ -0,0 +1,25 @@
+# Sample Questions
+
+To help you get started, here are some **Sample Prompts** you can ask in the app:
+
+1. Run each of the following sample prompts and verify that a plan is generated:
+   - Launch a new marketing campaign
+   - Procure new office equipment
+   - Initiate a new product launch
+
+2. Run the **Onboard employee** prompt:
+   - Remove the employee name from the prompt to test how the solution handles missing information.
+   - The solution should ask for the missing detail before proceeding.
+
+3. Try running known **RAI test prompts** to confirm safeguard behavior:
+   - You should see a toast message indicating that a plan could not be generated due to policy restrictions.
+
+
+**Home Page**
+![HomePage](images/MACAE-GP1.png)
+
+**Task Page**
+![GeneratedPlan](images/MACAE-GP2.png)  
+
+
+_This structured approach helps ensure the system handles prompts gracefully, verifies plan generation flows, and confirms RAI protections are working as intended._
diff --git a/documentation/TRANSPARENCY_FAQ.md b/documentation/TRANSPARENCY_FAQ.md
@@ -0,0 +1,17 @@
+## Document Generation Solution Accelerator: Responsible AI FAQ
+- ### What is Build your own copilot - Generic Solution Accelerator?
+    This solution accelerator is an open-source GitHub Repository to help create AI assistants using Azure OpenAI Service and Azure AI Search. This can be used by anyone looking for reusable architecture and code snippets to build AI assistants with their own enterprise data. The repository showcases a generic scenario of a user who wants to generate a document template based on a sample set of data.
+
+- ### What can Document Generation Solution Accelerator do? 
+    The sample solution included focuses on a generic use case - chat with your own data, generate a document template using your own data, and exporting the document in a docx format. The sample data is sourced from generic AI-generated promissory notes. The documents are intended for use as sample data only. The sample solution takes user input in text format and returns LLM responses in text format up to 800 tokens. It uses prompt flow to search data from AI search vector store, summarize the retrieved documents with Azure OpenAI.
+
+- ### What is/are Document Generation Solution Accelerator’s intended use(s)?  
+    This repository is to be used only as a solution accelerator following the open-source license terms listed in the GitHub repository. The example scenario’s intended purpose is to help users generate a document template to perform their work more efficiently.
+
+- ### How was Document Generation Solution Accelerator evaluated? What metrics are used to measure performance?
+    We have used AI Foundry Prompt flow evaluation SDK to test for harmful content, groundedness, and potential security risks. 
+
+- ### What are the limitations of Document Generation Solution Accelerator? How can users minimize the impact of Document Generation Solution Accelerator’s limitations when using the system?
+    This solution accelerator can only be used as a sample to accelerate the creation of AI assistants. The repository showcases a sample scenario of a user generating a document template. Users should review the system prompts provided and update as per their organizational guidance. Users should run their own evaluation flow either using the guidance provided in the GitHub repository or their choice of evaluation methods. AI-generated content may be inaccurate and should be manually reviewed. Currently, the sample repo is available in English only.  
+- ### What operational factors and settings allow for effective and responsible use of Document Generation Solution Accelerator?
+    Users can try different values for some parameters like system prompt, temperature, max tokens etc. shared as configurable environment variables while running run evaluations for AI assistants. Please note that these parameters are only provided as guidance to start the configuration but not as a complete available list to adjust the system behavior. Please always refer to the latest product documentation for these details or reach out to your Microsoft account team if you need assistance.
diff --git a/documentation/images/MACAE-GP1.png b/documentation/images/MACAE-GP1.png
diff --git a/documentation/images/MACAE-GP2.png b/documentation/images/MACAE-GP2.png
diff --git a/documentation/images/git_bash.png b/documentation/images/git_bash.png
diff --git a/documentation/images/quota-check-output.png b/documentation/images/quota-check-output.png
diff --git a/documentation/quota_check.md b/documentation/quota_check.md
@@ -0,0 +1,100 @@
+## Check Quota Availability Before Deployment
+
+Before deploying the accelerator, **ensure sufficient quota availability** for the required model.
+> **For Global Standard | GPT-4o - the capacity to at least 50k tokens for optimal performance.**
+
+### Login if you have not done so already
+```
+azd auth login
+```
+
+
+### 📌 Default Models & Capacities:
+```
+gpt-4o:50
+```
+### 📌 Default Regions:
+```
+eastus, uksouth, eastus2, northcentralus, swedencentral, westus, westus2, southcentralus, canadacentral
+```
+### Usage Scenarios:
+- No parameters passed → Default models and capacities will be checked in default regions.
+- Only model(s) provided → The script will check for those models in the default regions.
+- Only region(s) provided → The script will check default models in the specified regions.
+- Both models and regions provided → The script will check those models in the specified regions.
+- `--verbose` passed → Enables detailed logging output for debugging and traceability.
+
+### **Input Formats**
+> Use the --models, --regions, and --verbose options for parameter handling:
+
+✔️ Run without parameters to check default models & regions without verbose logging:
+   ```
+  ./quota_check_params.sh
+   ```
+✔️ Enable verbose logging:
+   ```
+  ./quota_check_params.sh --verbose
+   ```
+✔️ Check specific model(s) in default regions:
+  ```
+  ./quota_check_params.sh --models gpt-4o:50
+  ```
+✔️ Check default models in specific region(s):
+  ```
+./quota_check_params.sh --regions eastus,westus
+  ```
+✔️ Passing Both models and regions:  
+  ```
+  ./quota_check_params.sh --models gpt-4o:50 --regions eastus,westus2
+  ```
+✔️ All parameters combined:
+  ```
+ ./quota_check_params.sh --models gpt-4o:50 --regions eastus,westus --verbose
+  ```
+
+### **Sample Output**
+The final table lists regions with available quota. You can select any of these regions for deployment.
+
+![quota-check-ouput](images/quota-check-output.png)
+
+---
+### **If using Azure Portal and Cloud Shell**
+
+1. Navigate to the [Azure Portal](https://portal.azure.com).
+2. Click on **Azure Cloud Shell** in the top right navigation menu.
+3. Run the appropriate command based on your requirement:  
+
+   **To check quota for the deployment**  
+
+    ```sh
+    curl -L -o quota_check_params.sh "https://raw.githubusercontent.com/microsoft/document-generation-solution-accelerator/main/scripts/quota_check_params.sh"
+    chmod +x quota_check_params.sh
+    ./quota_check_params.sh
+    ```
+    - Refer to [Input Formats](#input-formats) for detailed commands.
+
+### **If using VS Code or Codespaces**
+1. Open the terminal in VS Code or Codespaces.
+2. If you're using VS Code, click the dropdown on the right side of the terminal window, and select `Git Bash`.
+   ![git_bash](images/git_bash.png)
+3. Navigate to the `scripts` folder where the script files are located and make the script as executable:
+   ```sh
+    cd scripts
+    chmod +x quota_check_params.sh
+    ```
+4. Run the appropriate script based on your requirement:  
+
+   **To check quota for the deployment**  
+
+    ```sh
+    ./quota_check_params.sh
+    ```
+   - Refer to [Input Formats](#input-formats) for detailed commands.
+
+5. If you see the error `_bash: az: command not found_`, install Azure CLI:  
+
+    ```sh
+    curl -sL https://aka.ms/InstallAzureCLIDeb | sudo bash
+    az login
+    ```
+6. Rerun the script after installing Azure CLI.