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


Вызов API описывается моделью Pydantic, а её generic-параметр задаёт тип результата. aiollm отправляет запрос через aiohttp, повторяет его, когда это безопасно, и возвращает проверенный результат, тип которого mypy и pyright уже знают.
pip install aiollm-openaiНа PyPI: aiollm-core, aiollm-openai и aiollm-anthropic. Нужен Python 3.13 или новее.
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, придёт вместе с ним.
pip install aiollm-openaipip install aiollm-anthropicТолько своё API? pip install aiollm-core. С uv: uv add aiollm-openai.
Положите ключ в переменную окружения. Клиент возьмёт его оттуда, если вы не передали ни токен, ни готовую сессию.
OPENAI_API_KEYANTHROPIC_API_KEYclient.generation — общий API для любого провайдера. Собственные методы провайдера дают все его поля. Для любого другого API опишите свой эндпоинт.
aiollm — низкоуровневый инструмент. HTTP он не прячет: каждый запрос — проверяемый объект, а повторы, ошибки, загрузки и потоки библиотека берёт на себя.
send_request(method) возвращает тип результата метода, и mypy и pyright его выводят.
Ответ целиком: модель JSON, текст, байты или пустой. Потоком: SSE и NDJSON с типизированными событиями и проверкой завершающего события.
Метод сам решает, можно ли его повторять. Временные сбои повторяются с экспоненциальной задержкой и случайным разбросом, с учётом Retry-After. RetryPolicy настраивается для сессии или вызова.
Свой класс для каждого частого HTTP-статуса, плюс ошибки сети и ответа. В каждой есть код провайдера, id запроса и флаг transient.
Из байтов, по пути, из открытого файла или async-итератора. При повторе файл открывается заново, а одноразовый источник повтор запрещает.
Параметры пути экранируются, редиректы выключены, прокси из окружения не используются, токены не попадают в repr и логи.
create() и stream() принимают поля запроса как именованные аргументы или готовый GenerationRequest. Код, типизированный через IGenerationClient, работает с любым встроенным клиентом, инструменты тоже.
TurnДиалог передаётся списком реплик пользователя и ассистента. Прошлый ответ превращается в реплику через response.to_turn(). Системный промпт идёт в instructions, а не в список.
output_schemaПередайте JSON Schema, и модель ответит JSON по ней. Ответ приходит текстом: перед разбором проверьте incomplete_reason. Каждый провайдер понимает свою часть JSON Schema.
EffortУровни LOW, MEDIUM, HIGH, XHIGH и MAX. Если не указать effort, модель работает со своим уровнем по умолчанию. Какие уровни принимает модель, решает провайдер.
GenerationResponseТекст, расход токенов, отказ модели и причина остановки лежат в одних и тех же полях для всех провайдеров. Исходный ответ провайдера доступен в raw.
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.
| Общее поле | OpenAI | Anthropic |
|---|---|---|
| instructions | instructions | system |
| max_output_tokens | max_output_tokens | max_tokens |
| effort | reasoning.effort | output_config.effort |
| output_schema | text.format | output_config.format |
| end_user_id | safety_identifier | metadata.user_id |
| tools | tools (function tools) | tools (custom tools) |
| tool_choice | tool_choice | tool_choice (REQUIRED as any) |
| parallel_tool_calls | parallel_tool_calls | tool_choice.disable_parallel_tool_use |
Сводку рассуждений можно запросить через типизированные опции провайдера. В потоке она приходит событиями ReasoningDeltaEvent, а events.text() отдаёт только текст ответа. Неверные опции вызывают RequestValidationError до отправки запроса.
Опишите функции один раз как инструменты. Модель отвечает вызовами, ваш код их выполняет, а результаты уходят обратно в диалог, пока модель не ответит текстом.
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-кодек можно заменить по отдельности.
Модель Pydantic: путь, HTTP-метод, формат тела и тип результата.
Сессия собирает заголовки и авторизацию и пишет вызов в лог.
Его повторяет tenacity, если метод разрешает повторы.
aiohttp отправляет запрос и читает ответ целиком или потоком.
Резолвер превращает ошибочный статус в типизированную ошибку.
Тело ответа проверяется и превращается в тип результата.
3–5Голубые шаги выполняются в каждой попытке, поэтому повторять ли запрос, решает только флаг transient у ошибки.
client.generation принимает одинаковый запрос для любого провайдера и возвращает общие типы. Исходный ответ провайдера лежит в raw. Собственные типы каждого провайдера сгенерированы из его схемы.
Берёт ключ из OPENAI_API_KEY. Исчерпанная квота — отдельная ошибка, она не повторяется.
Берёт ключ из ANTHROPIC_API_KEY. Перегрузка (статус 529) считается временной ошибкой.
Нужны 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. В потоке событий объявленное завершающее событие отличает полный ответ от соединения, которое оборвалось раньше.
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 соединение освобождается, в том числе при break и исключении. Чтение потока после выхода вызывает RuntimeError.
Руководства объясняют, как всё устроено, а справочник, собранный из кода, описывает каждый публичный тип и метод. Документация пока только на английском.
0.15.0 — первая версия на PyPI: ядро называется aiollm-core, а провайдеры стали отдельными пакетами aiollm-openai и aiollm-anthropic, они импортируются как aiollm_openai и aiollm_anthropic. aiollm.testing прогоняет ваш собственный провайдер через те же сценарии, что и провайдеры библиотеки. До 1.0 ломающее изменение поднимает минорную версию: после 0.15 будет 0.16. Перед обновлением загляните в список изменений и правила версий.
Что умеет общий API, где начинается специфика провайдера и чего ждать до версии 1.0.
Нет. Встроенные клиенты работают с Responses API OpenAI и Messages API Anthropic, а поверх них есть общий API генерации текста. Он намеренно меньше, чем API провайдеров. Для остального есть собственные методы провайдера и типизированные provider_options.
Подробнее в руководстве ↗Нет. Повторить можно только открытие потока, и то если метод это разрешает. Ошибка во время чтения сразу приходит в ваш код. Поток не перезапускается и не проигрывается заново, поэтому дублей в выводе не будет.
Подробнее в руководстве ↗Нет. Модель возвращает вызовы, ваш код их выполняет и отправляет результаты обратно в диалог. Цикл остаётся вашим: сколько кругов, что делать с упавшим инструментом и запускать ли вызовы параллельно.
Подробнее в руководстве ↗Поле со значением MISSING вообще не попадает в запрос. None отправляется как null, и только там, где схема метода это разрешает. Необязательные поля общего API генерации по умолчанию MISSING и None не принимают.
Подробнее в руководстве ↗Да. Сессия зависит только от протоколов: API, авторизации, заголовков, парсеров и резолвера ошибок. Для нового провайдера нужны классы методов и адаптер. Чтобы сменить HTTP-клиент, реализуйте транспорт под BaseSession.
Подробнее в руководстве ↗Нет, библиотека только асинхронная. Открывайте клиент или сессию через async with: на выходе соединения закроются.
Подробнее в руководстве ↗Публичный API ещё меняется. До 1.0 ломающее изменение поднимает минорную версию, и в списке изменений написано, как перейти. После 0.9 выйдет 0.10, а 1.0 выйдет, когда API объявят стабильным.
Подробнее в руководстве ↗