Типизированные async-клиенты для API нейросетей: каждый запрос — небольшой декларативный класс.

Вызов API описывается моделью Pydantic, а её generic-параметр задаёт тип результата. aiollm отправляет запрос через aiohttp, повторяет его, когда это безопасно, и возвращает проверенный результат, тип которого mypy и pyright уже знают.

pip install aiollm-openai

На PyPI: aiollm-core, aiollm-openai и aiollm-anthropic. Нужен Python 3.13 или новее.

pre-alpha 0.15.0Python 3.13 · 3.14 · 3.15mypy & pyright в строгом режимеMIT лицензия
import asyncio

from aiollm_openai import OpenAIClient


async def main() -> None:
    async with OpenAIClient() as client:  # OPENAI_API_KEY
        response = await client.generation.create(
            model="gpt-6-astra",
            input="Explain asyncio in one line",
            instructions="Be brief",
            max_output_tokens=64,
        )

    print(response.text)
    print(response.usage)  # shared TokenUsage
    print(response.raw)    # OpenAI's own Response


asyncio.run(main())
Поставьте AnthropicClient вместо OpenAIClient, остальной код не меняется.
Быстрый старт

Три шага до первого ответа

Нужен Python 3.13 или новее. Поставьте пакет нужного провайдера: ядро, aiollm-core, придёт вместе с ним.

  1. 1. Установка

    Поставьте провайдера

    1. pip install aiollm-openai
    2. pip install aiollm-anthropic

    Только своё API? pip install aiollm-core. С uv: uv add aiollm-openai.

  2. 2. Ключ

    Задайте ключ провайдера

    Положите ключ в переменную окружения. Клиент возьмёт его оттуда, если вы не передали ни токен, ни готовую сессию.

    OPENAI_API_KEYANTHROPIC_API_KEY
    Как настроить клиент
  3. 3. Запрос

    Выберите, как работать

    client.generation — общий API для любого провайдера. Собственные методы провайдера дают все его поля. Для любого другого API опишите свой эндпоинт.

Возможности

Всё, что нужно API-клиенту, сделано один раз и типизировано

aiollm — низкоуровневый инструмент. HTTP он не прячет: каждый запрос — проверяемый объект, а повторы, ошибки, загрузки и потоки библиотека берёт на себя.

Типизированные методы

send_request(method) возвращает тип результата метода, и mypy и pyright его выводят.

Целиком или потоком

Ответ целиком: модель JSON, текст, байты или пустой. Потоком: SSE и NDJSON с типизированными событиями и проверкой завершающего события.

Повторы только по разрешению

Метод сам решает, можно ли его повторять. Временные сбои повторяются с экспоненциальной задержкой и случайным разбросом, с учётом Retry-After. RetryPolicy настраивается для сессии или вызова.

Понятные ошибки

Свой класс для каждого частого HTTP-статуса, плюс ошибки сети и ответа. В каждой есть код провайдера, id запроса и флаг transient.

Загрузка файлов

Из байтов, по пути, из открытого файла или async-итератора. При повторе файл открывается заново, а одноразовый источник повтор запрещает.

Безопасно по умолчанию

Параметры пути экранируются, редиректы выключены, прокси из окружения не используются, токены не попадают в repr и логи.

Общий API генерации

Один запрос для всех провайдеров

create() и stream() принимают поля запроса как именованные аргументы или готовый GenerationRequest. Код, типизированный через IGenerationClient, работает с любым встроенным клиентом, инструменты тоже.

Turn

Диалог из реплик

Диалог передаётся списком реплик пользователя и ассистента. Прошлый ответ превращается в реплику через response.to_turn(). Системный промпт идёт в instructions, а не в список.

output_schema

Ответ в JSON по вашей схеме

Передайте JSON Schema, и модель ответит JSON по ней. Ответ приходит текстом: перед разбором проверьте incomplete_reason. Каждый провайдер понимает свою часть JSON Schema.

Effort

Сколько модели думать

Уровни LOW, MEDIUM, HIGH, XHIGH и MAX. Если не указать effort, модель работает со своим уровнем по умолчанию. Какие уровни принимает модель, решает провайдер.

GenerationResponse

Ответ в общих полях

Текст, расход токенов, отказ модели и причина остановки лежат в одних и тех же полях для всех провайдеров. Исходный ответ провайдера доступен в raw.

structured_output.py
from typing import Any

from aiollm import Effort, GenerationResponse, IGenerationClient


async def extract_summary(
    client: IGenerationClient,
    model: str,
    text: str,
) -> GenerationResponse[Any]:
    return await client.generation.create(
        model=model,
        input=text,
        instructions="Summarize the supplied text.",
        effort=Effort.MEDIUM,
        output_schema={
            "type": "object",
            "properties": {
                "summary": {"type": "string"},
            },
            "required": ["summary"],
            "additionalProperties": False,
        },
        max_output_tokens=1024,
    )

JSON приходит текстом в text. Перед разбором проверьте incomplete_reason.

Во что общие поля превращаются у каждого провайдера
Общее полеOpenAIAnthropic
instructionsinstructionssystem
max_output_tokensmax_output_tokensmax_tokens
effortreasoning.effortoutput_config.effort
output_schematext.formatoutput_config.format
end_user_idsafety_identifiermetadata.user_id
toolstools (function tools)tools (custom tools)
tool_choicetool_choicetool_choice (REQUIRED as any)
parallel_tool_callsparallel_tool_callstool_choice.disable_parallel_tool_use

instructions

OpenAI
instructions
Anthropic
system

max_output_tokens

OpenAI
max_output_tokens
Anthropic
max_tokens

effort

OpenAI
reasoning.effort
Anthropic
output_config.effort

output_schema

OpenAI
text.format
Anthropic
output_config.format

end_user_id

OpenAI
safety_identifier
Anthropic
metadata.user_id

tools

OpenAI
tools (function tools)
Anthropic
tools (custom tools)

tool_choice

OpenAI
tool_choice
Anthropic
tool_choice (REQUIRED as any)

parallel_tool_calls

OpenAI
parallel_tool_calls
Anthropic
tool_choice.disable_parallel_tool_use

Сводку рассуждений можно запросить через типизированные опции провайдера. В потоке она приходит событиями ReasoningDeltaEvent, а events.text() отдаёт только текст ответа. Неверные опции вызывают RequestValidationError до отправки запроса.

Инструменты

Модель вызывает ваши функции, с любым провайдером

Опишите функции один раз как инструменты. Модель отвечает вызовами, ваш код их выполняет, а результаты уходят обратно в диалог, пока модель не ответит текстом.

tools.py Новое в 0.15.0
import json
from typing import Any

from aiollm import (
    GenerationResponse,
    IGenerationClient,
    InputItem,
    Tool,
    ToolResult,
    Turn,
)

WEATHER = Tool(
    name="get_weather",
    description="Current weather in a city.",
    parameters={
        "type": "object",
        "properties": {"city": {"type": "string"}},
        "required": ["city"],
        "additionalProperties": False,
    },
    strict=True,
)


def get_weather(city: str) -> str:
    return json.dumps({"city": city, "celsius": 15})


async def ask_with_tools(
    client: IGenerationClient,
    model: str,
    question: str,
) -> GenerationResponse[Any]:
    conversation: list[InputItem] = [Turn.user(question)]
    while True:
        response = await client.generation.create(
            model=model, input=conversation, tools=[WEATHER]
        )
        if not response.tool_calls:
            return response
        conversation.append(response.to_turn())
        for call in response.tool_calls:
            arguments = call.parse_arguments()
            output = get_weather(str(arguments["city"]))
            conversation.append(
                ToolResult(call_id=call.id, output=output)
            )

Цикл ваш: aiollm передаёт вызовы и результаты, но сам ваши функции не запускает.

Инструмент: имя, описание и схема

Tool хранит JSON Schema аргументов; с strict=True аргументы ей точно следуют. tool_choice выбирает AUTO, NONE, REQUIRED или один ForcedTool.

Вызовы и результаты в диалоге

response.tool_calls — список ToolCall, а parse_arguments() разбирает аргументы. Диалог продолжают to_turn() и ToolResult на каждый вызов; вызов без результата отклоняется ещё до отправки.

Рассуждения возвращаются вместе с вызовами

Реплика с вызовами хранит собственный вывод провайдера: reasoning-элементы OpenAI или подписанные рассуждения Anthropic. Тот же провайдер продолжит с того места, где остановился.

Вызовы приходят прямо в потоке

stream() отдаёт ToolCallStartEvent, ToolCallDeltaEvent и ToolCallDoneEvent на каждый вызов, так что инструмент можно запустить до конца ответа.

Руководство по инструментам ↗
Путь запроса

Один путь для любого вызова, и повтор ровно там, где нужно

Каждый этап описан протоколом, поэтому API, авторизацию, обработку ошибок, заголовки и JSON-кодек можно заменить по отдельности.

  1. 1

    BaseAPIMethod

    Модель Pydantic: путь, HTTP-метод, формат тела и тип результата.

  2. 2

    send_request

    Сессия собирает заголовки и авторизацию и пишет вызов в лог.

  3. 3

    _send_once

    Его повторяет tenacity, если метод разрешает повторы.

  4. 4

    транспорт

    aiohttp отправляет запрос и читает ответ целиком или потоком.

  5. 5

    проверка статуса

    Резолвер превращает ошибочный статус в типизированную ошибку.

  6. 6

    парсер

    Тело ответа проверяется и превращается в тип результата.

3–5Голубые шаги выполняются в каждой попытке, поэтому повторять ли запрос, решает только флаг transient у ошибки.

Провайдеры

Два провайдера, один API генерации

client.generation принимает одинаковый запрос для любого провайдера и возвращает общие типы. Исходный ответ провайдера лежит в raw. Собственные типы каждого провайдера сгенерированы из его схемы.

OpenAIClient

Responses API

Берёт ключ из OPENAI_API_KEY. Исчерпанная квота — отдельная ошибка, она не повторяется.

AnthropicClient

Messages API

Берёт ключ из ANTHROPIC_API_KEY. Перегрузка (статус 529) считается временной ошибкой.

BaseProviderClient

ваш провайдер

Нужны IAPI, резолвер ошибок и адаптеры. Общие контрактные тесты проверят их так же, как встроенных провайдеров.

Модель выбирайте под переданный клиент. Если лимит вывода не задан, для Anthropic берётся 16 000 токенов.

Собственные методы, сессии и опции провайдеров ↗
from typing import Any

from aiollm import GenerationResponse, IGenerationClient


async def summarize(
    client: IGenerationClient,  # OpenAI, Anthropic, yours
    model: str,  # choose a model for this provider
    text: str,
) -> GenerationResponse[Any]:
    return await client.generation.create(
        model=model,
        input=text,
        instructions="Summarize in two sentences",
        max_output_tokens=200,
        timeout=30,
    )
Стриминг и надёжность

Поток либо дошёл до конца, либо вы об этом узнаете

Байты, текст, SSE или NDJSON. В потоке событий объявленное завершающее событие отличает полный ответ от соединения, которое оборвалось раньше.

checked_stream.py
from typing import Any

from aiollm import CompletedEvent, IGenerationClient


async def stream_answer(
    client: IGenerationClient,
    model: str,
) -> CompletedEvent[Any]:
    async with client.generation.stream(
        model=model,
        input="Explain asynchronous iterators.",
    ) as events:
        async for delta in events.text():
            print(delta, end="", flush=True)

        # The final event includes usage and stop details.
        return await events.final()

Ровно одно событие завершения

Общий поток заканчивается одним CompletedEvent. Нет его — будет APIStreamInterruptedError. Пришло событие после него — APIResponseError.

Повторяется открытие, а не вывод

После начала чтения ошибки приходят в ваш код. Повтор возможен, только если метод его разрешает, ошибка временная, а тело запроса можно отправить заново. Исчерпанная квота и одноразовые загрузки не повторяются.

Соединение живёт внутри async with

На выходе из async with соединение освобождается, в том числе при break и исключении. Чтение потока после выхода вызывает RuntimeError.

Подробно о стриминге ↗
Документация

Руководства по темам

Руководства объясняют, как всё устроено, а справочник, собранный из кода, описывает каждый публичный тип и метод. Документация пока только на английском.

0.15.0

Pre-alpha: API ещё меняется

0.15.0 — первая версия на PyPI: ядро называется aiollm-core, а провайдеры стали отдельными пакетами aiollm-openai и aiollm-anthropic, они импортируются как aiollm_openai и aiollm_anthropic. aiollm.testing прогоняет ваш собственный провайдер через те же сценарии, что и провайдеры библиотеки. До 1.0 ломающее изменение поднимает минорную версию: после 0.15 будет 0.16. Перед обновлением загляните в список изменений и правила версий.

руководствоМетодыКак описать эндпоинт: путь, тело, query-параметры и тип результата.руководствоЗагрузка файловБайты, пути, открытые файлы и одноразовые источники; кто и когда их закрывает.руководствоСтримингБайты, текст, SSE и NDJSON; проверка того, что поток дошёл до конца.руководствоОшибки и повторыКакие бывают ошибки и какие из них повторяются; настройка RetryPolicy.руководствоСессииПул соединений, авторизация, заголовки и тайм-аут отдельного вызова.руководствоПровайдерыOpenAI Responses API и Anthropic Messages API: клиенты и их собственные методы.руководствоОбщий API генерацииДиалоги, JSON по схеме, effort и события потока, одинаковые для всех провайдеров.руководствоИнструментыФункции-инструменты для любого провайдера: вызовы, результаты, рассуждения и стриминг.руководствоРесурсы и сценарииКак собрать операцию, не привязанную к провайдеру, поверх методов и сессий.руководствоРасширениеСвой адаптер, свой ресурс в клиенте или другой HTTP-транспорт.руководствоУстройство библиотекиТипизация, сетевые настройки по умолчанию, ограничения и версии.
Частые вопросы

Что стоит знать заранее

Что умеет общий API, где начинается специфика провайдера и чего ждать до версии 1.0.

aiollm заменяет официальные SDK целиком?

Нет. Встроенные клиенты работают с Responses API OpenAI и Messages API Anthropic, а поверх них есть общий API генерации текста. Он намеренно меньше, чем API провайдеров. Для остального есть собственные методы провайдера и типизированные provider_options.

Подробнее в руководстве ↗
Оборвавшийся поток перезапустится сам?

Нет. Повторить можно только открытие потока, и то если метод это разрешает. Ошибка во время чтения сразу приходит в ваш код. Поток не перезапускается и не проигрывается заново, поэтому дублей в выводе не будет.

Подробнее в руководстве ↗
aiollm сам вызывает мои инструменты?

Нет. Модель возвращает вызовы, ваш код их выполняет и отправляет результаты обратно в диалог. Цикл остаётся вашим: сколько кругов, что делать с упавшим инструментом и запускать ли вызовы параллельно.

Подробнее в руководстве ↗
Чем «не передано» отличается от null?

Поле со значением MISSING вообще не попадает в запрос. None отправляется как null, и только там, где схема метода это разрешает. Необязательные поля общего API генерации по умолчанию MISSING и None не принимают.

Подробнее в руководстве ↗
Можно подключить своего провайдера или другой HTTP-клиент?

Да. Сессия зависит только от протоколов: API, авторизации, заголовков, парсеров и резолвера ошибок. Для нового провайдера нужны классы методов и адаптер. Чтобы сменить HTTP-клиент, реализуйте транспорт под BaseSession.

Подробнее в руководстве ↗
Есть синхронный API?

Нет, библиотека только асинхронная. Открывайте клиент или сессию через async with: на выходе соединения закроются.

Подробнее в руководстве ↗
Что значит pre-alpha для обновлений?

Публичный API ещё меняется. До 1.0 ломающее изменение поднимает минорную версию, и в списке изменений написано, как перейти. После 0.9 выйдет 0.10, а 1.0 выйдет, когда API объявят стабильным.

Подробнее в руководстве ↗