### Start NVIDIA ACE Deployment with Docker Compose

Source: https://github.com/nvidia/ace/blob/main/microservices/audio_2_face_microservice/1.0/quick-start/README.md

This command initiates the deployment of NVIDIA ACE components using Docker Compose. The initial run may take several minutes to generate TRT models for Audio2Emotion and Audio2Face. Subsequent starts will use cached models. Use Ctrl+C to interrupt.

```bash
docker compose up
```

--------------------------------

### Install Dependencies and Run Tests

Source: https://github.com/nvidia/ace/blob/main/microservices/ace_agent/4.1/webui/README.md

Install project dependencies using yarn and execute the test suite for the server. Tests use Node's native test runner with tsx for TypeScript support. If permission errors occur during installation, remove node_modules and retry with sudo.

```bash
cd ./server
yarn install
yarn test
```

--------------------------------

### Deploy Helm Chart (Shell)

Source: https://github.com/nvidia/ace/blob/main/microservices/ace_agent/4.1/deploy/ucs_apps/chat_bot/food_ordering_bot/README.md

Installs the ACE Agent Helm chart using `helm install`. The chart is assumed to be located at `ucf-app-chat-bot-4.1.0/`.

```shell
helm install ace-agent ucf-app-chat-bot-4.1.0/
```

--------------------------------

### Install Project Requirements

Source: https://github.com/nvidia/ace/blob/main/microservices/audio_2_face_microservice/1.2/scripts/audio2face_in_animation_pipeline_validation_app/README.md

Installs all necessary Python packages listed in the requirements.txt file for the project. This ensures all dependencies are met.

```bash
pip3 install -r requirements.txt
```

--------------------------------

### Install Local Path Provisioner using cURL and sed

Source: https://github.com/nvidia/ace/blob/main/microservices/ace_agent/4.0/deploy/ucs_apps/chat_bot/food_ordering_bot/README.md

This command installs the Local Path Provisioner, a Kubernetes storage solution. It fetches the YAML configuration from a raw GitHub URL, modifies a specific name field using `sed`, and applies it using `kubectl`.

```shell
curl https://raw.githubusercontent.com/rancher/local-path-provisioner/v0.0.23/deploy/local-path-storage.yaml | sed 's/^  name: local-path$/  name: mdx-local-path/g' | microk8s kubectl apply -f -
```

--------------------------------

### GET /list

Source: https://context7.com/nvidia/ace/llms.txt

Lists all available plugin endpoints and their basic information.

```APIDOC
## GET /list

### Description
Retrieves a list of all available plugin endpoints, including their names, descriptions, and expected parameters.

### Method
GET

### Endpoint
/list

### Parameters
None

### Request Example
```
GET /list
```

### Response
#### Success Response (200)
- **Array of Objects**: Each object represents an endpoint with the following fields:
  - **name** (str) - The name of the endpoint.
  - **description** (str) - A brief description of the endpoint's functionality.
  - **parameters** (List[str]) - A list of parameter names expected by the endpoint.

#### Response Example
```json
[
  {
    "name": "add_item_to_order",
    "description": "Add food item to order",
    "parameters": [
      "food_item",
      "quantity",
      "size"
    ]
  }
]
```
```

--------------------------------

### Install NVIDIA ACE Python Wheel Package

Source: https://github.com/nvidia/ace/blob/main/microservices/audio_2_face_microservice/1.2/scripts/audio2face_in_animation_pipeline_validation_app/README.md

Installs the NVIDIA ACE gRPC proto for Python using a pre-built wheel package. This command assumes the wheel file is located in the specified path.

```bash
pip3 install ../../proto/sample_wheel/nvidia_ace-1.0.0-py3-none-any.whl
```

--------------------------------

### Remove All Stale Docker Containers

Source: https://github.com/nvidia/ace/blob/main/microservices/audio_2_face_microservice/1.0/quick-start/README.md

This command forcefully removes all stopped Docker containers from the system. It's a comprehensive cleanup step for troubleshooting deployment issues.

```bash
docker container prune -f
```

--------------------------------

### Generate and Deploy Helm Chart

Source: https://github.com/nvidia/ace/blob/main/microservices/ace_agent/4.0/deploy/ucs_apps/speech_bot/ddg_langchain_bot/README.md

Generates the Helm Chart using UCF tools and then deploys the ACE agent using the generated chart. This involves running the `ucf_app_builder_cli` and `helm install` commands.

```bash
ucf_app_builder_cli app build app.yaml app-params.yaml

helm install ace-agent ucf-app-speech-bot-4.0.0/
```

--------------------------------

### Generate and Deploy Helm Chart for ACE Agent

Source: https://github.com/nvidia/ace/blob/main/microservices/ace_agent/4.0/deploy/ucs_apps/chat_bot/food_ordering_bot/README.md

This sequence of commands first generates a Helm chart for the ACE Agent using UCS tools with specified application and parameter files. It then installs the chart using `helm install`, deploying the food ordering bot.

```shell
ucf_app_builder_cli app build app.yaml app-params.yaml

helm install ace-agent ucf-app-chat-bot-4.0.0/
```

--------------------------------

### Deploy Helm Chart

Source: https://github.com/nvidia/ace/blob/main/microservices/ace_agent/4.0/deploy/ucs_apps/chat_bot/stock_bot/README.md

This command deploys the Stock Sample Bot using Helm. It installs the chart named `ace-agent` from the specified repository `ucf-app-chat-bot-4.0.0/`. Ensure the Helm chart repository is correctly configured.

```bash
helm install ace-agent ucf-app-chat-bot-4.0.0/
```

--------------------------------

### Example config.yaml for ACE Digital Human Customization

Source: https://github.com/nvidia/ace/blob/main/workflows/tokkio/5.0.0-ga/customization-notebooks/02_prompt_greeting.ipynb

This snippet shows an example structure of the `config.yaml` file used for customizing the ACE Digital Human. It includes settings for an OpenAI Large Language Model context, specifying the avatar's name and prompt, and a User Presence Processor for welcome and farewell messages.

```yaml
# Example snippet of `config.yaml`
OpenAILLMContext:
    name: "Benji"
    prompt: "You are {name}, a friendly mathematics teacher who enjoys telling math jokes.  
UserPresenceProcesssor:
    welcome_message: "Hello"
    farewell_message: "Bye"
```

--------------------------------

### Deploy Helm Chart - Shell

Source: https://github.com/nvidia/ace/blob/main/microservices/ace_agent/4.0/deploy/ucs_apps/speech_bot/npc_bots/README.md

Deploys the ACE Agent Helm chart. This command installs the chart with the release name 'ace-agent' using the specified chart path.

```shell
helm install ace-agent ucf-app-speech-bot-4.0.0/
```

--------------------------------

### Configure ACE Controller API URL (Bash)

Source: https://github.com/nvidia/ace/blob/main/workflows/tokkio/5.0.0-ga/customization-notebooks/00_setup_prerequisites.ipynb

This script extracts the server IP from the Kubernetes configuration and constructs the ACE Configurator API URL. It handles both HTTP and HTTPS based on the Kubernetes cluster setup (Baremetal vs. CSP). The output is the Configurator API URL, which is necessary for the ACE Configurator UI.

```bash
server_ip=$(kubectl config view --minify -o jsonpath='{.clusters[0].cluster.server}' | sed 's|http[s]*://||' | cut -d':' -f1)

if [[ -z "$server_ip" ]]; then
  echo "Error: Unable to extract server IP from Kubernetes config."
  exit 1
fi

configurator_url="${server_ip}:30180"

echo "Configurator API URL: $configurator_url. Use http:// or https:// prefix, depending on Baremetal or CSP installation respectively."
```

--------------------------------

### Check Client Availability and Get Instance

Source: https://github.com/nvidia/ace/blob/main/microservices/ace_agent/4.1/webui/README.md

Use the singleton pattern to check if a specific client is available and retrieve its instance. This example demonstrates checking for GRPCClient availability before using it to stream speech results.

```javascript
if (GRPCClient.isAvailable()) {
  const client = GRPCClient.get();
  const metaDataResponse = this.gRPCClient.streamSpeechResults(request);
}
```

--------------------------------

### Deploy Plugin Server (Bash)

Source: https://github.com/nvidia/ace/blob/main/microservices/ace_agent/4.1/samples/stock_bot/README.md

Command to deploy the ACE Agent plugin server using a specified configuration file. Requires the 'aceagent' package to be installed.

```bash
aceagent plugin-server deploy --config bots/stock_bot/plugin_config.yaml
```

--------------------------------

### Set Up Virtual Environment (Bash)

Source: https://github.com/nvidia/ace/blob/main/microservices/ace_agent/4.1/samples/chitchat_bot/README.md

Creates and activates a Python virtual environment. This isolates project dependencies and ensures a clean development setup. It's a standard practice for Python projects.

```bash
python3 -m venv venv
source venv/bin/activate
```

--------------------------------

### Generate Helm Chart using UCS Tools (Shell)

Source: https://github.com/nvidia/ace/blob/main/microservices/ace_agent/4.1/deploy/ucs_apps/chat_bot/food_ordering_bot/README.md

Generates a Helm chart for the ACE Agent application using the `ucf_app_builder_cli`. Requires `app.yaml` and `app-params.yaml` configuration files.

```shell
ucf_app_builder_cli app build app.yaml app-params.yaml
```

--------------------------------

### Add ACE Controller Dependencies to pyproject.toml

Source: https://github.com/nvidia/ace/blob/main/workflows/tokkio/5.0.0-ga/customization-notebooks/09_create_frame_processor.ipynb

Example snippet from `pyproject.toml` showing how to add necessary project dependencies. The `nvidia-pipecat` library and other specified packages should be included in the `dependencies` list for the ACE controller frame processing.

```toml
[project]
name = "tokkio-llm-rag-example"
version = "0.1.0"
description = "Add your description here"
readme = "README.md"
requires-python = ">=3.12"
dependencies = [
    "nvidia-pipecat",
    "opentelemetry-sdk==1.31.1",
    "opentelemetry-exporter-otlp-proto-grpc==1.31.1",
    "opentelemetry-distro==0.52b1",
    "watchfiles==1.0.4",
    "watchdog==6.0.0",
    # <----- Add the dependencies here
]
```

--------------------------------

### Install LangChain Plugin Server Dependencies

Source: https://github.com/nvidia/ace/blob/main/microservices/ace_agent/4.0/deploy/ucs_apps/speech_bot/ddg_langchain_bot/README.md

Installs necessary Python packages for the LangChain plugin server. This Dockerfile snippet adds custom dependencies required for specific LangChain versions and the DuckDuckGo search integration.

```dockerfile
##############################
# Install custom dependencies 
##############################
RUN pip3 install \
    langchain==0.1.1 \
    langchain-community==0.0.13 \
    langchain-core==0.1.12 \
    duckduckgo-search==5.3.1b1
```

--------------------------------

### Launch all NPC bots with chat engine

Source: https://github.com/nvidia/ace/blob/main/microservices/ace_agent/4.1/samples/npc_bots/README.md

Starts the chat engine and auto-discovers all available bots in the specified directory. Each bot configuration is loaded from individual bot_config.yaml files for character backstory and LLM tuning.

```bash
aceagent chat web --config bots/npc_bots
```

--------------------------------

### Generate and Deploy Helm Chart (Bash)

Source: https://github.com/nvidia/ace/blob/main/microservices/ace_agent/4.1/deploy/ucs_apps/speech_bot/stock_bot/README.md

This sequence of commands first generates a Helm chart for the ACE agent application using the ucf_app_builder_cli tool and then deploys this chart to the Kubernetes cluster using helm install.

```Bash
ucf_app_builder_cli app build app.yaml app-params.yaml

helm install ace-agent ucf-app-speech-bot-4.1.0/
```

--------------------------------

### Deploy ACE Agent using Helm

Source: https://github.com/nvidia/ace/blob/main/microservices/ace_agent/4.1/deploy/ucs_apps/speech_bot/npc_bots/README.md

Installs the ACE Agent using Helm, deploying the necessary components into the Kubernetes cluster. This command assumes the Helm chart has been generated and is available.

```bash
helm install ace-agent ucf-app-speech-bot-4.1.0/
```

--------------------------------

### FastAPI Plugin Server: Custom Business Logic Integration

Source: https://context7.com/nvidia/ace/llms.txt

This Python code snippet outlines the setup for a FastAPI-based Plugin Server. It initializes an APIRouter and a logger, providing a foundation for integrating custom business logic, external APIs, and domain-specific functionalities into ACE Agent bots. Dependencies include 'fastapi' and 'typing'.

```python
from fastapi import APIRouter, Body
from typing import Dict, List, Optional
import logging

router = APIRouter()
logger = logging.getLogger("plugin")


```

--------------------------------

### Check Kubernetes Pod Status (Bash)

Source: https://github.com/nvidia/ace/blob/main/workflows/tokkio/5.0.0-ga/customization-notebooks/00_setup_prerequisites.ipynb

This command checks if all pods within the 'app' namespace are in a running state. It's essential for verifying the Digital Human application is operational before proceeding with ACE customizations. No specific inputs are required, and the output lists pod names, readiness, status, restarts, and age.

```bash
!kubectl get po -n app
```

--------------------------------

### Check Server Readiness - Python

Source: https://context7.com/nvidia/ace/llms.txt

Verifies that the ACE Agent server is running and ready to accept requests by making a GET request to the /isReady endpoint. Uses async HTTP client with 15-second timeout and returns boolean indicating server availability.

```python
async def check_server_ready(host="localhost", port=9000):
    """Verify ACE Agent server is ready"""
    async with aiohttp.ClientSession(timeout=aiohttp.ClientTimeout(15)) as session:
        async with session.get(f"http://{host}:{port}/isReady") as resp:
            return resp.ok
```

--------------------------------

### Launch Chitchat Bot (Bash)

Source: https://github.com/nvidia/ace/blob/main/microservices/ace_agent/4.1/samples/chitchat_bot/README.md

Launches the chitchat bot using the aceagent CLI. This command starts the bot, making it ready to receive and process conversational queries based on the specified configuration file.

```bash
aceagent chat cli --config bots/chitchat_bot
```

--------------------------------

### Deploy Speech and NLP Models - Docker Compose

Source: https://github.com/nvidia/ace/blob/main/microservices/ace_agent/4.1/samples/colang_1.0/spanish_bot_nmt/README.md

Deploys the necessary speech and NLP models (Riva ASR, TTS, NMT) using Docker Compose. This command initiates the download and setup of models, which can take a significant amount of time on the first run.

```docker-compose
docker compose -f deploy/docker/docker-compose.yml up model-utils-speech
```

--------------------------------

### Configure ACE Agent Bot with YAML

Source: https://context7.com/nvidia/ace/llms.txt

Defines bot settings, including LLM models, dialogue flows, and plugins. Supports simple and advanced configurations with multiple models and custom plugin setups. Input is a YAML configuration file.

```yaml
bot: rag_assistant

plugins:
  - path: /path/to/rag_plugin
    config:
      rag:
        RAG_SERVER_URL: "http://localhost:8081"
        TEMPERATURE: 0.2
        MAX_TOKENS: 200

colang_flows:
  - |
            define flow answer_question
              user expressed question
              $answer = execute rag_query(question=$user_message)
              bot inform answer_from_knowledge_base(answer=$answer)
```

```yaml
# chitchat_bot_config.yml - Simple conversational bot
bot: chitchat

models:
  - type: main
    engine: openai
    model: gpt-3.5-turbo-instruct
    parameters:
      stop: ["\n"]
      temperature: 0.7
      max_tokens: 150

# Advanced configuration with multiple models
models:
  - type: main
    engine: nvidia_ai_endpoints
    model: mistralai/mixtral-8x7b-instruct-v0.1

  - type: embeddings
    engine: nvidia_ai_endpoints
    model: nvidia/nv-embed-qa-v1

# Plugin configuration
plugins:
  - name: food_ordering
    path: ./plugin/order_food.py

  - name: rag_system
    path: ./plugin/rag.py
    config:
      rag:
        RAG_SERVER_URL: "http://rag-server:8081"
        TEMPERATURE: 0.2

# Colang dialogue flows
colang_flows:
  - |
            define flow greeting
      user expressed greeting
      bot express greeting
      bot offer help

    define flow order_food
      user wants to order food
      $item = ask "What would you like to order?"
      $size = ask "What size?"
      $result = execute add_item_to_order(food_item=$item, size=$size)
      bot inform order_status(result=$result)
```

--------------------------------

### Create NGC API Key Secret (Shell)

Source: https://github.com/nvidia/ace/blob/main/microservices/ace_agent/4.1/deploy/ucs_apps/chat_bot/food_ordering_bot/README.md

Creates a generic Kubernetes secret named `ngc-api-key-secret` to store the NGC CLI API key. This is used for downloading models and resources from NGC.

```shell
kubectl create secret generic ngc-api-key-secret --from-literal=NGC_CLI_API_KEY="${NGC_CLI_API_KEY}"
```

--------------------------------

### Clean NVIDIA ACE Docker Cache and Models

Source: https://github.com/nvidia/ace/blob/main/microservices/audio_2_face_microservice/1.0/quick-start/README.md

This command removes the cached Audio2Emotion and Audio2Face TRT models, forcing regeneration on the next startup. This is useful for troubleshooting or when model updates are needed.

```bash
docker compose down -v
```

--------------------------------

### Get Service NodePort (Shell)

Source: https://github.com/nvidia/ace/blob/main/microservices/ace_agent/4.1/deploy/ucs_apps/chat_bot/food_ordering_bot/README.md

Retrieves the service details for `ace-agent-webapp-deployment-service`, specifically the NodePort. This is needed to access the web frontend application.

```shell
kubectl get svc
```

--------------------------------

### Implement Custom Task with AbortController Signal

Source: https://github.com/nvidia/ace/blob/main/microservices/ace_agent/4.1/webui/README.md

Create a new task by extending AbstractTask base class and implementing start(), interactionModes, and optional cleanup() methods. The task must support AbortController signal to enable proper interruption when stopped. This example shows how to pass the abort signal to gRPC client calls.

```javascript
const metaDataResponse = this.gRPCClient.streamSpeechResults(request, {
  signal: this.abortController.signal
});
```

--------------------------------

### Source Docker Initialization Script - Shell

Source: https://github.com/nvidia/ace/blob/main/microservices/ace_agent/4.1/samples/colang_1.0/spanish_bot_nmt/README.md

Sources the docker_init.sh script to load environment variables required for the docker-compose.yaml configuration. This ensures all necessary settings are in place before deploying services.

```shell
source deploy/docker/docker_init.sh
```

--------------------------------

### Install LangChain Custom Dependencies in Dockerfile

Source: https://github.com/nvidia/ace/blob/main/microservices/ace_agent/4.1/deploy/ucs_apps/speech_bot/ddg_langchain_bot/README.md

Adds LangChain and DuckDuckGo search dependencies to the plugin server Docker image by installing required Python packages. Should be added to the plugin_server.Dockerfile in the deploy/docker/dockerfiles directory. Versions specified are compatible with ACE 4.1.0.

```dockerfile
##############################
# Install custom dependencies
##############################
RUN pip3 install \
    langchain==0.1.1 \
    langchain-community==0.0.13 \
    langchain-core==0.1.12 \
    duckduckgo-search==5.3.1b1
```

--------------------------------

### Deploy plugin server for bot fulfillment module

Source: https://github.com/nvidia/ace/blob/main/microservices/ace_agent/4.1/samples/npc_bots/README.md

Launches the plugin server that hosts custom instruction generation logic. The fulfillment module processes game-stage context and injects custom instructions into LLM prompts for dynamic NPC behavior.

```bash
aceagent plugin-server deploy --config bots/npc_bots/plugin_config.yaml &
```

--------------------------------

### Execute Async Chat Workflow - Python

Source: https://context7.com/nvidia/ace/llms.txt

Main entry point demonstrating the complete async chat workflow: checks server readiness before sending multiple chat queries sequentially. Uses asyncio.run() to execute the async main coroutine and handles potential connection failures gracefully.

```python
async def main():
    if await check_server_ready():
        await chat_with_bot(query="What can you help me with?")
        await chat_with_bot(query="Tell me about the menu")

asyncio.run(main())
```

--------------------------------

### Get User Context

Source: https://github.com/nvidia/ace/blob/main/microservices/ace_agent/4.1/samples/npc_bots/README.md

Allows extraction of conversation history and user context for a specific user, which can then be saved on the application side.

```APIDOC
## POST /getUserContext

### Description
Extracts the conversation history and user context for a specific user. This data can be saved externally by the application.

### Method
POST

### Endpoint
/getUserContext

### Parameters
#### Request Body
- **UserId** (string) - Required - The unique identifier for the user whose context needs to be extracted. This ID can be found in the DM logs.

### Request Example
```json
{
  "UserId": "<Check the userid from the dm logs>"
}
```

### Response
#### Success Response (200)
Returns the conversation history and user context for the specified user.

#### Response Example
(The response structure would mirror the `Context` and `ChatHistory` fields from the `/setUserContext` request, but this specific example was not provided in the source text.)
```

--------------------------------

### Watch Pod Status (Shell)

Source: https://github.com/nvidia/ace/blob/main/microservices/ace_agent/4.1/deploy/ucs_apps/chat_bot/food_ordering_bot/README.md

Continuously monitors the status of Kubernetes pods. This command is used to verify that all deployment components are running correctly.

```shell
watch kubectl get pods
```

--------------------------------

### Build and Push Custom Plugin Server Docker Image

Source: https://github.com/nvidia/ace/blob/main/microservices/ace_agent/4.0/deploy/ucs_apps/speech_bot/ddg_langchain_bot/README.md

Builds a custom Docker image for the plugin server using Docker Compose, retags it for the NGC Docker registry, and pushes it. Requires environment variables set by `deploy/docker/docker_init.sh`.

```bash
# Set required environment variables for docker-compose.yaml
source deploy/docker/docker_init.sh

# Build custom plugin server docker image
docker compose -f deploy/docker/docker-compose.yml build plugin-server

# Retag docker image and push to NGC docker registry
docker tag docker.io/library/plugin-server:4.0.0-rc3 <CUSTOM_DOCKER_IMAGE_PATH>:<VERSION>

docker push <CUSTOM_DOCKER_IMAGE_PATH>:<VERSION>
```

--------------------------------

### Create Test File with Naming Convention

Source: https://github.com/nvidia/ace/blob/main/microservices/ace_agent/4.1/webui/README.md

Follow the standard naming convention for test files by creating a .test.ts file in the same directory as the file being tested with the same base name. This structure ensures tests are co-located with their source files for better maintainability.

```bash
server/emoji-finder/index.ts
server/emoji-finder/index.test.ts
```

--------------------------------

### Launch ACE Agent Chat CLI (Bash)

Source: https://github.com/nvidia/ace/blob/main/microservices/ace_agent/4.1/samples/stock_bot/README.md

Command to launch the ACE Agent chat interface in the command-line. Uses the specified bot configuration.

```bash
aceagent chat cli --config bots/stock_bot
```

--------------------------------

### Create NGC Docker Registry Secret (Shell)

Source: https://github.com/nvidia/ace/blob/main/microservices/ace_agent/4.1/deploy/ucs_apps/chat_bot/food_ordering_bot/README.md

Creates a Kubernetes secret named `ngc-docker-reg-secret` for authenticating with the NVIDIA Container Registry (nvcr.io). Requires the NGC_CLI_API_KEY environment variable to be set.

```shell
export NGC_CLI_API_KEY=...

kubectl create secret docker-registry ngc-docker-reg-secret --docker-server=nvcr.io --docker-username='$oauthtoken' --docker-password="${NGC_CLI_API_KEY}"
```

--------------------------------

### Create and Activate Python Virtual Environment

Source: https://github.com/nvidia/ace/blob/main/microservices/audio_2_face_microservice/1.2/scripts/audio2face_in_animation_pipeline_validation_app/README.md

Creates a Python virtual environment named '.venv' and activates it. This is a standard practice for managing project dependencies.

```bash
python3 -m venv .venv
source .venv/bin/activate
```

--------------------------------

### Deploy ACE Agent Plugin Server

Source: https://github.com/nvidia/ace/blob/main/microservices/ace_agent/4.1/samples/spanish_bot/README.md

Command to deploy the ACE agent plugin server. This command requires a configuration file specifying plugin details.

```bash
aceagent plugin-server deploy --config bots/spanish_bot/plugin_config.yaml
```