Metadata-Version: 2.4
Name: pydantic-ai-gigachat
Version: 0.1.0
Summary: PydanticAI integration for GigaChat
Project-URL: Homepage, https://github.com/ai-forever/pydantic-ai-gigachat
Project-URL: Repository, https://github.com/ai-forever/pydantic-ai-gigachat
Project-URL: Issues, https://github.com/ai-forever/pydantic-ai-gigachat/issues
Author: pydantic-ai-gigachat contributors
License: MIT
License-File: LICENSE
Keywords: gigachat,llm,pydantic-ai,sber
Classifier: Development Status :: 3 - Alpha
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Requires-Python: >=3.10
Requires-Dist: gigachat>=0.2.1
Requires-Dist: pydantic-ai-slim>=1.90
Requires-Dist: pydantic>=2.7
Provides-Extra: dev
Requires-Dist: mypy>=1.10; extra == 'dev'
Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
Requires-Dist: pytest>=8; extra == 'dev'
Requires-Dist: respx>=0.21; extra == 'dev'
Requires-Dist: ruff>=0.6; extra == 'dev'
Description-Content-Type: text/markdown

# pydantic-ai-gigachat

[![CI](https://github.com/ai-forever/pydantic-ai-gigachat/actions/workflows/ci.yml/badge.svg)](https://github.com/ai-forever/pydantic-ai-gigachat/actions/workflows/ci.yml)

[PydanticAI](https://github.com/pydantic/pydantic-ai) integration for **GigaChat**.

This package implements a native PydanticAI `Model` against GigaChat's own
`/chat/completions` API (not the OpenAI-compatibility shim), so all GigaChat
features — Russian profanity filter, repetition penalty, function calling,
streaming — are first-class.

## Install

```bash
pip install pydantic-ai-gigachat
```

Requires Python 3.10+ and `pydantic-ai-slim>=1.90`.

## Quick start

```python
import asyncio
from pydantic_ai import Agent
from pydantic_ai_gigachat import GigaChatModel, GigaChatProvider

async def main():
    provider = GigaChatProvider()  # reads GIGACHAT_CREDENTIALS env
    model = GigaChatModel("GigaChat", provider=provider)
    agent = Agent(model, system_prompt="Отвечай коротко.")

    result = await agent.run("Привет, как дела?")
    print(result.output)

    await provider.aclose()

asyncio.run(main())
```

## Configuration

### Credentials

Get your **Authorization key** from the
[Sber developer cabinet](https://developers.sber.ru/studio/workspaces) (it's the
base64-encoded `client_id:client_secret`). Pass it explicitly or via env:

```bash
export GIGACHAT_CREDENTIALS="<authorization key>"
```

```python
provider = GigaChatProvider(
    authorization_key="...",
    scope=GigaChatScope.PERS,        # PERS / B2B / CORP
)
```

### TLS certificates

GigaChat endpoints serve certificates signed by the **Russian Trusted Root CA**,
which is not in the standard `certifi` bundle. Three options:

1. **Production** — download the CA from
   [`gu-st.ru`](https://gu-st.ru/content/Other/doc/russian_trusted_root_ca.cer)
   and point the provider at it:

   ```bash
   export GIGACHAT_CA_BUNDLE_FILE=/path/to/russian_trusted_root_ca.cer
   ```

2. **Append to certifi** (one-shot, affects the whole venv):

   ```bash
   curl -k "https://gu-st.ru/content/Other/doc/russian_trusted_root_ca.cer" \
       >> $(python -m certifi)
   ```

3. **Dev only** — `GigaChatProvider(verify_ssl=False)`.

## Features

| Feature                                           | Status        |
| ------------------------------------------------- | ------------- |
| Chat completions                                  | ✅            |
| Streaming (SSE)                                   | ✅            |
| Function calling                                  | ✅            |
| OAuth2 token cache + refresh                      | ✅            |
| Custom CA bundle                                  | ✅            |
| Pre-flight token counting (`Model.count_tokens`)  | ✅            |
| Prompt cache reporting (`cache_read_tokens`)      | ✅            |
| Embeddings                                        | ⏭ planned     |
| `/files` (vision/RAG inputs)                      | ⏭ planned     |

## Available models

`GigaChat`, `GigaChat-Pro`, `GigaChat-Max`, `GigaChat-2`, `GigaChat-2-Pro`,
`GigaChat-2-Max` (and `-preview` early-access variants).

```python
model = GigaChatModel("GigaChat-Max", provider=provider)
```

## Settings passthrough

PydanticAI's `ModelSettings` map cleanly to GigaChat parameters:
`temperature`, `top_p`, `max_tokens`, `n`. GigaChat-specific knobs
(`repetition_penalty`, `update_interval`, `profanity_check`) work via
`extra_body`:

```python
result = await agent.run(
    "...",
    model_settings={
        "temperature": 0.3,
        "max_tokens": 256,
        "extra_body": {"profanity_check": True, "repetition_penalty": 1.1},
    },
)
```

## Examples

See `examples/`:

- `basic.py` — minimal agent
- `tools.py` — function calling
- `streaming.py` — streamed response

## Development

```bash
python -m venv .venv
.venv/bin/pip install -e ".[dev]"
.venv/bin/pytest
```

## License

MIT.
