Skip to main content

aiollm

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

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.16.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.

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) and AnthropicClient (Messages and Files APIs, package 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, with it:

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.

Quick start

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.

Documentation

The guide and the API reference are at aiollm-org.github.io/aiollm:

License

MIT. See LICENSE.

Metadata

Release files for aiollm-core 0.16.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for aiollm-core 0.16.0
File Size Uploaded Provenance Actions
aiollm_core-0.16.0.tar.gz 1.1 MB With provenance Details for aiollm_core-0.16.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for aiollm-core 0.16.0
File Interpreter ABI Platform Actions
aiollm_core-0.16.0-py3-none-any.whl Python 3 none any Details for aiollm_core-0.16.0-py3-none-any.whl

Total release size: 1.3 MB

Release files / aiollm_core-0.16.0.tar.gz

Download URL aiollm_core-0.16.0.tar.gz
Size 1.1 MB
Tags Source
SHA-256 checksum
How to use checksums
1169350ef2b94938cdc841e01e92dd632902f81f8680bc45dfeaf40df2315c8d
BLAKE2b-256 checksum
How to use checksums
e413e4d842d787f573468df3d01a7b0e2b93d275038826a76acba5bcab2cf262
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 21, 2026.

Transparency log

Release files / aiollm_core-0.16.0-py3-none-any.whl

Download URL aiollm_core-0.16.0-py3-none-any.whl
Size 228.4 kB
Tags Python 3
SHA-256 checksum
How to use checksums
3edc68b939ec1df75efa45ab25e3170bd27d6065cb4f7ff5782b661e35c3aead
BLAKE2b-256 checksum
How to use checksums
6d20af9e0cea99c8bc27e2c7ccb749d804305323d135f4ade8ddda9bcd51f5e1
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 21, 2026.

Transparency log

Security for aiollm-core 0.16.0

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Full provenance

Both files in this release have been uploaded with provenance metadata.

Select from 2 files

Attestation for aiollm_core-0.16.0.tar.gz

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 21, 2026.

Transparency log

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page