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-Afterup to a cap; aRetryPolicytunes 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
transientflag. - Provider clients.
OpenAIClient(Responses and Files APIs, packageaiollm-openai) andAnthropicClient(Messages and Files APIs, packageaiollm-anthropic), with types generated from the providers' schemas and the provider-neutralclient.generation(text with images and PDF documents, structured output, reasoning summaries and function tools, buffered or streamed) andclient.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:
- Methods: parameters, body, query and path, result types
- Uploads and streaming
- Errors and retries and sessions
- Provider clients and shared generation
- Reference, generated from the code
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)
| 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)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| 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 logRelease 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 logSecurity 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.
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 logA 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.