Skip to main content

Getting started with DIAL SDK

In this tutorial, you will build, run, and test your first Custom App using DIAL SDK. You will create a simple echo application that repeats the user's message, deploy it locally with Docker Compose, and verify it works in DIAL Chat. No prior DIAL experience is required — only basic Python and Docker knowledge.

Prerequisites​

  • Python 3.11 or later installed
  • Docker and Docker Compose (V2) installed
  • A terminal and a text editor

What you will build​

An echo application that receives a message through the DIAL Unified API and responds with the same text. You will run it alongside DIAL Core and DIAL Chat, then interact with it in the browser.

User → DIAL Chat → DIAL Core → Your Echo App → DIAL Core → DIAL Chat → User

Step 1: Create the project directory​

Create a fresh directory structure for the tutorial:

mkdir -p dial-echo-app/echo
mkdir -p dial-echo-app/core
cd dial-echo-app

Your project will have this layout when complete:

dial-echo-app/
├── docker-compose.yml
├── core/
│   └── config.json
└── echo/
    ├── app.py
    ├── requirements.txt
    └── Dockerfile

Step 2: Implement the application​

Create the file echo/app.py with the following content:

import uvicorn

from aidial_sdk import DIALApp
from aidial_sdk.chat_completion import ChatCompletion, Request, Response


class EchoApplication(ChatCompletion):
    async def chat_completion(
        self, request: Request, response: Response
    ) -> None:
        last_user_message = request.messages[-1]

        with response.create_single_choice() as choice:
            choice.append_content(last_user_message.content or "")


app = DIALApp()
app.add_chat_completion("echo", EchoApplication())

To run locally with uvicorn:

uvicorn app:app --host 0.0.0.0 --port 5000

Key concepts in this code:

  • ChatCompletion is the base class for all DIAL applications. You implement one method: chat_completion.
  • Request contains the conversation history. request.messages[-1] is the most recent user message.
  • Response is the object you write your output to. create_single_choice() opens a response stream with one choice.
  • DIALApp is a FastAPI-based application router. add_chat_completion("echo", ...) registers your handler under the deployment name echo.

Step 3: Add dependencies​

Create the file echo/requirements.txt:

aidial-sdk==0.27.0
uvicorn==0.34.0

Step 4: Create the Dockerfile​

Create the file echo/Dockerfile:

FROM python:3.11-alpine

WORKDIR /app
COPY . /app
RUN pip install --no-cache-dir -r requirements.txt

EXPOSE 5000
CMD ["python", "app.py"]

Verify: Run ls echo/ and confirm you have following:

dial-echo-app/
└── echo/
    ├── app.py
    ├── Dockerfile
    └── requirements.txt

Step 5: Configure DIAL Core​

DIAL Core needs to know about your application. Create the file core/config.json:

{
  "applications": {
    "echo": {
      "displayName": "My Echo App",
      "description": "Simple application that repeats the user's message",
      "endpoint": "http://echo:5000/openai/deployments/echo/chat/completions"
    }
  },
  "keys": {
    "dial_api_key": {
      "project": "TEST-PROJECT",
      "role": "default"
    }
  },
  "roles": {
    "default": {
      "limits": {
        "echo": {}
      }
    }
  }
}

This configuration does three things:

  1. Registers your app under the deployment name echo with its internal Docker network endpoint.
  2. Creates an API key (dial_api_key) that DIAL Chat uses to authenticate with DIAL Core.
  3. Grants the default role permission to use the echo application.

Step 6: Write the Docker Compose file​

Create docker-compose.yml in the project root:

services:
  echo:
    build: echo
    depends_on:
      - core
  
  # ========= DIAL =========
  core:
    image: epam/ai-dial-core:0.25.1
    platform: linux/amd64
    environment:
      aidial.config.files: '["/opt/config/config.json"]'
      aidial.storage.overrides: '{ "jclouds.filesystem.basedir": "data" }'
      aidial.redis.singleServerConfig.address: "redis://redis:6379"
      aidial.identityProviders.test.rolePath: 'roles'
      aidial.identityProviders.test.disableJwtVerification: 'true'
      aidial.encryption.secret: 'salt'
      aidial.encryption.key: 'password'
    ports:
      - "8080:8080"
    volumes:
      - ./core:/opt/config 
    depends_on:
      - redis

  themes:
    image: epam/ai-dial-chat-themes:0.10.0
    platform: linux/amd64

  chat:
    image: epam/ai-dial-chat:0.26.0
    platform: linux/amd64
    ports:
      - "3000:3000"
    depends_on:
      - themes
      - core
    environment:
      NEXTAUTH_SECRET: "secret"
      THEMES_CONFIG_HOST: "http://themes:8080"
      DIAL_API_HOST: "http://core:8080"
      DIAL_API_KEY: "dial_api_key"
      ENABLED_FEATURES: "conversations-section,prompts-section,top-settings,top-clear-conversation,top-chat-info,top-chat-model-settings,empty-chat-settings,header,footer,request-api-key,report-an-issue,likes,conversations-sharing,input-files,attachments-manager,custom-applications,marketplace"

  redis:
    image: redis:7.2.4-alpine3.19
    command: >
      redis-server
      --maxmemory 256mb
      --maxmemory-policy volatile-lfu
      --save ""
      --appendonly no

Step 7: Start the stack​

From the dial-echo-app/ directory, run:

docker compose up --build

Wait until you see log output from all services. DIAL Chat logs ready and DIAL Core logs Server started when they are ready.

Verify: Open http://localhost:3000 in your browser. You should see the DIAL Chat interface.

Step 8: Test in DIAL Chat​

  1. In DIAL Chat, open the Catalog (the grid icon or "Talk to" selector).
  2. Find My Echo App in the list of available applications.
  3. Select it to start a new conversation.
  4. Type any message — for example, Hello, DIAL! — and send it.

Verify: The app responds with the exact text you sent: Hello, DIAL!.

Step 9: Test via the API​

You can also call your app directly using the Unified API. Open a new terminal and run:

curl http://localhost:8080/openai/deployments/echo/chat/completions \
  -H "Content-Type: application/json" \
  -H "api-key: dial_api_key" \
  -d '{
    "messages": [
      {"role": "user", "content": "Testing the API"}
    ]
  }'

Verify: The response JSON contains your message in choices[0].message.content:

{
  "choices": [
    {
      "index": 0,
      "finish_reason": "stop",
      "message": {
        "role": "assistant",
        "content": "Testing the API"
      }
    }
  ]
}

Step 10: Stop the stack​

Press Ctrl+C in the terminal running Docker Compose, then clean up:

docker compose down

What you learned​

  • How to create a Custom App by subclassing ChatCompletion from the DIAL SDK.
  • How to register an application in DIAL Core via config.json.
  • How to run the full DIAL stack (Core, Chat, Redis, Themes) alongside your app using Docker Compose.
  • How to test your app both through the DIAL Chat UI and the Unified API directly.

Companion code​

The complete source code for this tutorial is available at https://github.com/epam/ai-dial/tree/main/dial-docker-compose/application.

Further reading​