Metadata-Version: 2.4
Name: patera-aiinterface
Version: 0.11.0
Summary: Experimental LLM interface for Patera: prompts, chat history and retrieval augmentation
Keywords: patera,llm,ai,openai
Author: Marko Šterk
Author-email: Marko Šterk <marko_sterk@hotmail.com>
License-Expression: MIT
License-File: LICENSE
Classifier: Development Status :: 3 - Alpha
Classifier: Framework :: AsyncIO
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Typing :: Typed
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Requires-Dist: httpx>=0.28.1
Requires-Dist: patera>=0.121
Requires-Dist: patera-database>=0.11
Requires-Dist: numpy>=2.4.4 ; extra == 'augmentation'
Requires-Dist: pgvector>=0.4.2 ; extra == 'augmentation'
Requires-Dist: sentence-transformers>=5.4.1 ; extra == 'augmentation'
Requires-Python: >=3.13
Project-URL: Homepage, https://github.com/MarkoSterk/Patera
Project-URL: Documentation, https://github.com/MarkoSterk/Patera#readme
Project-URL: Repository, https://github.com/MarkoSterk/Patera
Project-URL: Issues, https://github.com/MarkoSterk/Patera/issues
Project-URL: Changelog, https://github.com/MarkoSterk/Patera/blob/main/CHANGELOG.md
Provides-Extra: augmentation
Description-Content-Type: text/markdown

# patera-aiinterface

Experimental LLM interface for Patera: prompts, chat history and retrieval augmentation. Part of [Patera](https://github.com/MarkoSterk/Patera), a modular async-first Python web framework.

> **Experimental.** This package is not yet ready for production use; its API may change in any release.

## Installation

```sh
pip install patera-aiinterface
# with retrieval augmentation (sentence-transformers, PyTorch, pgvector)
pip install "patera-aiinterface[augmentation]"
```

Requires Python 3.13 or newer and `patera>=0.121`.

## Usage

`patera-aiinterface` connects to chat completion APIs (OpenAI-compatible and Ollama). Retrieval
augmentation needs the `augmentation` extra; everything else works without it.

```python
from typing import AsyncIterator, Optional

from patera.aiinterface import (
    AiService, AiServiceConfig, ChatResponse, SqlHistoryProvider, history, system_prompt, user_prompt,
)
from patera.aiinterface.service_provider.openai import OpenAIServiceProvider


class ChatHistory(SqlHistoryProvider[ChatMessageRow]):   # a model with session_id, role,
    model = ChatMessageRow                               # content and order_number columns


class Assistant(AiService):
    service_provider = OpenAIServiceProvider()           # or OllamaServiceProvider()
    history_provider = ChatHistory()

    @system_prompt("You are a helpful translator.")
    @user_prompt("Translate '<:text>' to <:language>.")
    async def translate(self, text: str, language: str = "German") -> ChatResponse: ...

    @history
    @system_prompt("You are a friendly assistant.")
    @user_prompt("<:message>")
    async def chat(self, session_id: Optional[str], message: str) -> AsyncIterator[ChatResponse]: ...


class Config(BaseConfig):
    ...
    ASSISTANT: AiServiceConfig = AiServiceConfig(
        BASE_URL="https://api.openai.com/v1", API_KEY="...", MODEL="gpt-4o-mini", HISTORY_LIMIT=10,
    )
```

See the [AI interface (experimental) section of the Patera documentation](https://github.com/MarkoSterk/Patera#ai-interface-experimental) for the full guide.

## License

MIT. See [LICENSE](https://github.com/MarkoSterk/Patera/blob/main/LICENSE).
