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.15.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. It is not on PyPI yet, so install it from source:

git clone https://github.com/aiollm-org/aiollm.git
cd aiollm
uv sync

Or with pip: pip install -e .

The provider clients are packages of their own, installed the same way from their repositories: aiollm-openai (import aiollm_openai) and aiollm-anthropic (import aiollm_anthropic).

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.15.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.15.0
File Size Uploaded Provenance Actions
aiollm_core-0.15.0.tar.gz 1.1 MB With provenance Details for aiollm_core-0.15.0.tar.gz

Built distribution (wheel)

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

Total release size: 1.3 MB

Release files / aiollm_core-0.15.0.tar.gz

Download URL aiollm_core-0.15.0.tar.gz
Size 1.1 MB
Tags Source
SHA-256 checksum
How to use checksums
d6a2a27c610a487b474daae0f9cfbefebc381c514418d3a6172f5232babbaaaf
BLAKE2b-256 checksum
How to use checksums
032b3143adc1433da31316562703571f02e8cffe03a6675cc65fc5a989bee6d6
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 20, 2026.

Transparency log

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

Download URL aiollm_core-0.15.0-py3-none-any.whl
Size 218.6 kB
Tags Python 3
SHA-256 checksum
How to use checksums
6a1147b9ef06936a56cf8c90b6cceaaba1cdfcf9e385f2555856dfa45d388285
BLAKE2b-256 checksum
How to use checksums
1135eeb852f00799022b6d8156264962768c95a118c708506acd36940cc68da3
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 20, 2026.

Transparency log

Security for aiollm-core 0.15.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.15.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 20, 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