Metadata-Version: 2.5
Name: aiollm-core
Version: 0.17.0
Summary: Async-first toolkit for building typed HTTP API clients, the core of aiollm
Project-URL: Homepage, https://github.com/aiollm-org/aiollm
Project-URL: Documentation, https://aiollm-org.github.io/aiollm/
Project-URL: Repository, https://github.com/aiollm-org/aiollm
Project-URL: Issues, https://github.com/aiollm-org/aiollm/issues
Project-URL: Changelog, https://github.com/aiollm-org/aiollm/blob/master/CHANGELOG.md
Author-email: GrehBan <maximfeedback19@gmail.com>
Maintainer-email: GrehBan <maximfeedback19@gmail.com>
License-Expression: MIT
License-File: LICENSE
Keywords: ai,aiohttp,api-client,async,asyncio,http-client,llm,pydantic,sse,streaming,typed
Classifier: Development Status :: 2 - Pre-Alpha
Classifier: Framework :: AsyncIO
Classifier: Framework :: Pydantic :: 2
Classifier: Framework :: aiohttp
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: Programming Language :: Python :: 3.15
Classifier: Programming Language :: Python :: Implementation :: CPython
Classifier: Topic :: Internet :: WWW/HTTP
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Typing :: Typed
Requires-Python: >=3.13
Requires-Dist: aiodns>=4.0.4
Requires-Dist: aiohttp>=3.14.5
Requires-Dist: aiopulse-py>=0.0.5
Requires-Dist: brotli>=1.2.1
Requires-Dist: certifi>=2026.10.23
Requires-Dist: multidict>=7.2.1
Requires-Dist: orjson>=3.13.0
Requires-Dist: pydantic>=2.14.1
Requires-Dist: tenacity>=9.2.1
Requires-Dist: typing-extensions>=4.16.0
Requires-Dist: yarl>=1.25.1
Provides-Extra: testing
Requires-Dist: jsonschema>=4.25; extra == 'testing'
Requires-Dist: pytest-aiohttp>=1.1.1; extra == 'testing'
Requires-Dist: pytest-asyncio>=1.4.1; extra == 'testing'
Requires-Dist: pytest>=9.2.0; extra == 'testing'
Description-Content-Type: text/markdown

<h1 align="center">
  <picture>
    <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/aiollm-org/aiollm/master/docs/assets/aiollm_dark.png">
    <img alt="aiollm" src="https://raw.githubusercontent.com/aiollm-org/aiollm/master/docs/assets/aiollm.png" width="420">
  </picture>
</h1>

An async-first toolkit for building typed HTTP API clients, aimed at AI providers.

<!-- --8<-- [start:intro] -->
You describe each API call as a small declarative class: a Pydantic model whose generic argument is its result type. The library sends it over `aiohttp` and returns a validated, statically typed result. It also handles retries, errors, file uploads and streaming, and ships clients for OpenAI and Anthropic with one shared generation API, images, documents and tool calls included.

> **Status: pre-alpha (0.17.0).** The core abstractions are in place, but the public API may still change: before 1.0 a breaking change bumps the minor version (0.9 is followed by 0.10, not 1.0; 1.0 comes when the API is declared stable), see [Versioning](https://aiollm-org.github.io/aiollm/guide/design/#versioning).

## Features

- **Typed methods.** `send_request(method)` returns the method's result type, and mypy and pyright both infer it.
- **Buffered and streamed responses.** JSON models, text, bytes or nothing; streams of bytes, text, or typed events from server-sent events (SSE) and newline-delimited JSON (NDJSON).
- **Checked streams.** A method can declare the protocol's last event, so a stream cut between two events raises instead of looking complete.
- **File uploads.** From bytes, a path, an open binary stream or an async iterator; a retry resends the whole file.
- **Opt-in retries.** Transient failures are retried with exponential backoff and jitter, honouring `Retry-After` up to a cap; a `RetryPolicy` tunes them per session or per call.
- **Structured errors.** One exception class per common HTTP status, plus transport and response errors, each with the provider's code, the request id and a `transient` flag.
- **Provider clients.** `OpenAIClient` (Responses and Files APIs, package [`aiollm-openai`](https://github.com/aiollm-org/aiollm_openai)) and `AnthropicClient` (Messages and Files APIs, package [`aiollm-anthropic`](https://github.com/aiollm-org/aiollm_anthropic)), with types generated from the providers' schemas and the provider-neutral `client.generation` (text with images and PDF documents, structured output, reasoning summaries and function tools, buffered or streamed) and `client.files` (a file uploaded once and sent by its id).
- **Replaceable parts.** Sessions depend on protocols, so the API, authentication, error mapping, headers and JSON codec can each be swapped.
- **Safe defaults.** Path parameters are escaped, redirects are off, proxies from the environment are ignored, and tokens stay out of `repr`.

## Installation

The library requires Python 3.13 or newer. Install the provider you use; it brings the core, [`aiollm-core`](https://pypi.org/project/aiollm-core/), with it:

```bash
pip install aiollm-openai      # import aiollm_openai
pip install aiollm-anthropic   # import aiollm_anthropic
```

Or the core alone, for clients of your own: `pip install aiollm-core` (`import aiollm`). With uv, `uv add` takes the same names. The `testing` extra, `aiollm-core[testing]`, adds the test kit for a provider of your own. To work on the library itself, see [Contributing](https://aiollm-org.github.io/aiollm/contributing/).

## Quick start

```python title="quick_start.py"
import asyncio

from pydantic import MISSING

from aiollm import (
    BaseAPI,
    BaseAPIMethod,
    BaseAPIType,
    BaseErrorResolver,
    BearerAuth,
    BodyFormat,
)
from aiollm.session.aiohttp import AiohttpSession

API = BaseAPI("https://api.example.com", "v1")


class Message(BaseAPIType):
    role: str
    content: str


class Completion(BaseAPIType):
    id: str
    text: str


class CreateCompletion(BaseAPIMethod[Completion]):
    __request_path__ = "/completions"
    __request_method__ = "POST"
    __request_body_format__ = BodyFormat.JSON
    __retryable__ = True

    model: str
    messages: list[Message]
    temperature: float | MISSING = MISSING   # left out until given


async def main() -> None:
    session = AiohttpSession(
        api=API,
        auth=BearerAuth("sk-..."),
        error_resolver=BaseErrorResolver(),
    )

    async with session:
        completion = await session.send_request(
            CreateCompletion(
                model="example-1",
                messages=[Message(role="user", content="Hello!")],
            )
        )

    print(completion.text)  # completion: Completion


asyncio.run(main())
```

This sends `POST https://api.example.com/v1/completions` with the body `{"model": "example-1", "messages": [{"role": "user", "content": "Hello!"}]}`. `temperature` was not given, so it stays `MISSING` and is not sent at all (`None` would be sent as `null`). The response is validated into `Completion`, and type checkers know that `completion` is a `Completion`.
<!-- --8<-- [end:intro] -->

## Documentation

The guide and the API reference are at **[aiollm-org.github.io/aiollm](https://aiollm-org.github.io/aiollm/)**:

- [Methods](https://aiollm-org.github.io/aiollm/guide/methods/): parameters, body, query and path, result types
- [Uploads](https://aiollm-org.github.io/aiollm/guide/uploads/) and [streaming](https://aiollm-org.github.io/aiollm/guide/streaming/)
- [Errors and retries](https://aiollm-org.github.io/aiollm/guide/errors/) and [sessions](https://aiollm-org.github.io/aiollm/guide/sessions/)
- [Provider clients](https://aiollm-org.github.io/aiollm/guide/providers/) and [shared generation](https://aiollm-org.github.io/aiollm/guide/generation/)
- [Reference](https://aiollm-org.github.io/aiollm/reference/), generated from the code

## License

MIT. See [LICENSE](LICENSE).
