Metadata-Version: 2.5
Name: piatra-ai
Version: 0.2.0
Summary: Thin wrapper over the OpenAI SDK, preset for the Piatra AI Gateway.
Project-URL: Homepage, https://ai.piatra.center
Author: Piatra Institute
License-Expression: MIT
License-File: LICENSE
Keywords: ai-gateway,llm,openai,piatra
Requires-Python: >=3.11
Requires-Dist: openai<3,>=2
Description-Content-Type: text/markdown

# piatra-ai

Thin wrapper over the official [`openai`](https://pypi.org/project/openai/) SDK,
preset for the [Piatra AI Gateway](../../../README.md). It does exactly three
things: presets the gateway base URL, reads the key from `PIATRA_AI_KEY`, and
exposes typed `piatra.*` model-id constants. Everything else — chat, streaming,
retries — is the OpenAI SDK's, unchanged.

## Install

```
pip install piatra-ai
```

Imported as `piatra_ai`.

## Usage

```python
from piatra_ai import PiatraAI, MODELS

client = PiatraAI()
# api_key  defaults to os.environ["PIATRA_AI_KEY"]
# base_url defaults to https://ai.piatra.center/v1

res = client.chat.completions.create(
    model=MODELS.GLM,  # "piatra.glm"
    messages=[{"role": "user", "content": "What is default logic?"}],
)
```

Streaming and multimodal input are the OpenAI SDK's, unchanged:

```python
stream = client.chat.completions.create(
    model=MODELS.GLM, messages=messages, stream=True,
)
for chunk in stream:
    ...

client.chat.completions.create(
    model=MODELS.MEDGEMMA,  # the vision-capable model
    messages=[{
        "role": "user",
        "content": [
            {"type": "text", "text": "describe this radiograph"},
            {"type": "image_url", "image_url": {"url": data_url}},
        ],
    }],
)
```

## Configuration

| Argument   | Default                            | Notes                                                       |
| ---------- | ---------------------------------- | ----------------------------------------------------------- |
| `api_key`  | `os.environ["PIATRA_AI_KEY"]`      | The `pi_live_*` key, issued and owned by `core`.            |
| `base_url` | `https://ai.piatra.center/v1`   | Or set `PIATRA_AI_BASE_URL`.                                |

Any other OpenAI client keyword argument is accepted and passed through
unchanged.
