Metadata-Version: 2.4
Name: aidial-sdk
Version: 0.37.0.dev7
Summary: Framework to create applications and model adapters for AI DIAL
License-Expression: Apache-2.0
License-File: LICENSE
Author: EPAM RAIL
Author-email: SpecialEPM-DIALDevTeam@epam.com
Requires-Python: >=3.10,<4.0
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Provides-Extra: httpx
Provides-Extra: telemetry
Requires-Dist: fastapi (>=0.51,<1.0)
Requires-Dist: httpx (>=0.25.0,<1.0) ; extra == "httpx"
Requires-Dist: opentelemetry-api (>=1.22.0,<2.0) ; extra == "telemetry"
Requires-Dist: opentelemetry-exporter-otlp-proto-grpc (>=1.22.0,<2.0) ; extra == "telemetry"
Requires-Dist: opentelemetry-exporter-prometheus (>=0.43b0) ; extra == "telemetry"
Requires-Dist: opentelemetry-instrumentation-aiohttp-client (>=0.43b0) ; extra == "telemetry"
Requires-Dist: opentelemetry-instrumentation-fastapi (>=0.43b0) ; extra == "telemetry"
Requires-Dist: opentelemetry-instrumentation-httpx (>=0.43b0) ; extra == "telemetry"
Requires-Dist: opentelemetry-instrumentation-logging (>=0.43b0) ; extra == "telemetry"
Requires-Dist: opentelemetry-instrumentation-requests (>=0.43b0) ; extra == "telemetry"
Requires-Dist: opentelemetry-instrumentation-system-metrics (>=0.43b0) ; extra == "telemetry"
Requires-Dist: opentelemetry-instrumentation-urllib (>=0.43b0) ; extra == "telemetry"
Requires-Dist: opentelemetry-sdk (>=1.22.0,<2.0) ; extra == "telemetry"
Requires-Dist: prometheus-client (>=0.17.1,<1.0) ; extra == "telemetry"
Requires-Dist: pydantic (>=1.10.17,<3)
Requires-Dist: uvicorn (>=0.19,<1.0)
Requires-Dist: wrapt (>=1.10,<2)
Project-URL: Documentation, https://epam-rail.com/dial_api
Project-URL: Homepage, https://epam-rail.com
Project-URL: Repository, https://github.com/epam/ai-dial-sdk
Description-Content-Type: text/markdown

<h1 align="center">
    AI DIAL Python SDK
</h1>
<p align="center">
    <p align="center">
    <a href="https://dialx.ai/">
        <img src="https://dialx.ai/logo/dialx_logo.svg" alt="About DIALX">
    </a>
</p>
<h4 align="center">
    <a href="https://pypi.org/project/aidial-sdk/">
        <img src="https://img.shields.io/pypi/v/aidial-sdk.svg" alt="PyPI version">
    </a>
    <a href="https://discord.gg/ukzj9U9tEe">
        <img src="https://img.shields.io/static/v1?label=DIALX%20Community%20on&message=Discord&color=blue&logo=Discord&style=flat-square" alt="Discord">
    </a>
</h4>

- [Overview](#overview)
- [Environment Variables](#environment-variables)
- [Usage](#usage)
  - [Echo application example](#echo-application-example)
    - [Run](#run)
    - [Check](#check)
- [Development](#development)
  - [Development Environment](#development-environment)
  - [Setup](#setup)
  - [IDE configuration](#ide-configuration)
  - [Lint](#lint)
  - [Test](#test)
  - [Git hooks](#git-hooks)
  - [Clean](#clean)
  - [Build](#build)
  - [Publish](#publish)

---

## Overview

Framework to create applications and model adapters for [AI DIAL](https://epam-rail.com).

Applications and model adapters implemented using this framework will be compatible with [AI DIAL API](https://epam-rail.com/dial_api) that was designed based on [Azure OpenAI API](https://learn.microsoft.com/en-us/azure/ai-services/openai/reference).

---

## Environment Variables

|Variable|Default|Description|
|---|---|---|
|DIAL_SDK_LOG|WARNING|DIAL SDK log level|
|DIAL_SDK_HEADERS_TO_PROXY|``|A comma-separated list of headers that should be proxied from incoming requests to outgoing requests to the DIAL API. By default, no headers are proxied.|
|DIAL_SDK_SSE_HEARTBEAT_INTERVAL||When set, the SDK inserts ping comments into streaming chat completion responses after the response has been idle for the specified number of seconds, helping prevent read timeouts when the DIAL application isn't responsive.|
|PYDANTIC_V2|False|When `True` and Pydantic V2 is installed, DIAL SDK classes for requests/responses will be based on Pydantic V2 `BaseModel`. Otherwise, they will be based on Pydantic V1 `BaseModel`.|

---

## Usage

Install the library using [pip](https://pip.pypa.io/en/stable/getting-started):

```sh
pip install aidial-sdk
```

### Echo application example

The echo application example replies to the user by repeating their last message:

```python
# Save this as app.py
import uvicorn

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


# ChatCompletion is an abstract class for applications and model adapters
class EchoApplication(ChatCompletion):
    async def chat_completion(self, request: Request, response: Response) -> None:
        # Get last message (the newest) from the history
        last_user_message = request.messages[-1]

        # Generate response with a single choice
        with response.create_single_choice() as choice:
            # Fill the content of the response with the last user's content
            choice.append_content(last_user_message.text())


# DIALApp extends FastAPI to provide a user-friendly interface for routing requests to your applications
app = DIALApp()
app.add_chat_completion("echo", EchoApplication())

# Run built app
if __name__ == "__main__":
    uvicorn.run(app, port=5000)
```

#### Run

```sh
python3 app.py
```

#### Check

Send the next request:

```sh
curl http://127.0.0.1:5000/openai/deployments/echo/chat/completions \
  -H "Content-Type: application/json" \
  -H "Api-Key: DIAL_API_KEY" \
  -d '{
    "messages": [{"role": "user", "content": "Repeat me!"}]
  }'
```

You will see the JSON response as:

```json
{
    "choices":[
        {
            "index": 0,
            "finish_reason": "stop",
            "message": {
                "role": "assistant",
                "content": "Repeat me!"
            }
        }
    ],
    "usage": null,
    "id": "d08cfda2-d7c8-476f-8b95-424195fcdafe",
    "created": 1695298034,
    "object": "chat.completion"
}
```

---

## Development

### Development Environment

This project requires [Python ≥3.11](https://www.python.org/downloads/) and [Poetry ≥2.1.1](https://python-poetry.org/) for dependency management.

### Setup

1. Install Poetry. See the official [installation guide](https://python-poetry.org/docs/#installation).

2. *(Optional)* Specify custom Python or Poetry executables in `.env.dev`. This is useful if multiple versions are installed. By default, `python` and `poetry` are used.

   ```sh
   POETRY_PYTHON=path-to-python-exe
   POETRY=path-to-poetry-exe
   ```

3. Create and activate the virtual environment:

   ```sh
   make init_env
   source .venv/bin/activate
   ```

4. Install project dependencies (including linting, formatting, and test tools):

   ```sh
   make install
   ```

### IDE configuration

The recommended IDE is [VSCode](https://code.visualstudio.com/).
Open the project in VSCode and install the recommended extensions.
VS Code is configured to use the [Ruff formatter](https://docs.astral.sh/ruff/formatter/).

Alternatively you can use [PyCharm](https://www.jetbrains.com/pycharm/) that has built-in [Ruff support](https://www.jetbrains.com/help/pycharm/lsp-tools.html#ruff).

### Lint

Run the linting before committing:

```sh
make lint
```

To auto-fix formatting issues run:

```sh
make format
```

### Test

Run unit tests locally for available python versions:

```sh
make test
```

Run unit tests for the specific python version:

```sh
make test PYTHON=3.11
```

### Git hooks

You may optionally install Git hooks that will automatically run the linting step on Git push. You only need to do it once for the given repository.

```sh
make install_git_hooks
```

> [!IMPORTANT]
> This command doesn't work if you have already installed Git hooks locally or globally.

### Clean

To remove the virtual environment and build artifacts run:

```sh
make clean
```

### Build

To build the package run:

```sh
make build
```

### Publish

To publish the package to PyPI run:

```sh
make publish
```

---

