Metadata-Version: 2.4
Name: aidial-sdk
Version: 0.35.0rc0
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.|
|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
```

---

