Provider clients¶
OpenAIClient builds an AiohttpSession for OpenAI from a token: the https://api.openai.com/v1 URL, BearerAuth and OpenAIErrorResolver, which turns a 429 for exhausted credits or a reached spend or usage limit (insufficient_quota, credit_balance_exhausted, organization_spend_limit_exceeded, ...) into a QuotaExceededError that is not retried, also when a stream's error event reports it. A stream's error event and a failed response come after a 200, so their class is picked by the code or type, such as ServiceUnavailableError for server_is_overloaded and QuotaExceededError for insufficient_quota. Such a failure is never transient: the generation ran and failed, and running it again is your choice, as in the official SDK, which retries by the HTTP status only. The client owns its session, so close it, ideally with async with:
from aiollm_openai import OpenAIClient
async def list_models() -> ModelList:
async with OpenAIClient("sk-...") as client:
return await client.send_request(ListModels())
- Key from the environment.
OpenAIClient()without a token or a session reads the key fromOPENAI_API_KEY. An explicit token always wins over the variable, a session is never combined with it, and an empty variable counts as unset. - Custom session settings. Pass a ready session with
OpenAIClient(session=...)instead of a token. ABaseSessionwhose error resolver is not anOpenAIErrorResolver(a subclass of it is fine), or with authentication outside theAuthorizationheader, gets aSessionMismatchWarning(aUserWarning), since both are almost certainly mistakes for OpenAI. When the session is deliberate, turn the warning off with the standard filters:warnings.filterwarnings("ignore", category=SessionMismatchWarning). To change only some options of the session built from a token, pass them to the client:OpenAIClient(token, max_body_size=..., timeout=...)takes every keyword argument ofAiohttpSession(AiohttpSessionOptions), and type checkers check them; with a readysession=they raiseValueError, since they would be ignored.session_factory(token, max_body_size=...)fromaiollm_openai.clientbuilds such a session on its own. - Ownership. A client closes its session when it is closed, also a session you passed in. One owner per session means no connection pool is left open by accident; create one session per client.
- Anthropic.
AnthropicClient(aiollm_anthropic) works the same way: a token, a readysession=orANTHROPIC_API_KEY, with thehttps://api.anthropic.com/v1URL,BearerAuth(Anthropic also acceptsx-api-key, soAPIKeyAuthin a given session gets no warning) andAnthropicErrorResolver. The resolver reads Anthropic'serror.typeaserror_typeanddetails.error_codeascode; a reached spend cap (429enforced_spend_limit_reached) or a spend limit you set (400) is aQuotaExceededErrorthat is not retried, and the 529overloaded_erroris a transientServiceUnavailableError, like OpenAI's 503. A stream'serrorevent comes after a 200, so its class is picked by its type, and it is never transient, as for OpenAI. Anthropic also requires ananthropic-versionheader;API_VERSION(2026-10-21) is the version the library's Anthropic types follow. - Other providers. Subclass
BaseClient, which delegatessend_request,stream,closeandasync withto its session, and build the session with aSessionFactory(aiollm.session).BaseClientis generic in the session type:BaseClient(AiohttpSession(...)).sessionis typed asAiohttpSession, whileOpenAIClient, which accepts any session, is aBaseClient[ISession].
OpenAI Responses API¶
aiollm_openai.methods has CreateResponse and StreamResponse for POST /v1/responses. Their request fields come from aiollm_openai.methods.params and OpenAI's response and event types from aiollm_openai.types; both are generated from OpenAI's official OpenAPI file (see Provider types):
from aiollm_openai.adapters import output_text
from aiollm_openai.methods import CreateResponse, StreamResponse
from aiollm_openai.types import ResponseTextDeltaEvent
async def ask(client: OpenAIClient) -> str | None:
response = await client.send_request(
CreateResponse(model="gpt-6-astra", input="Hi", instructions="Be brief")
)
return output_text(response)
async def ask_streamed(client: OpenAIClient) -> str:
text = ""
method = StreamResponse(model="gpt-6-astra", input="Hi")
async with client.stream(method) as events:
async for event in events:
if isinstance(event, ResponseTextDeltaEvent):
text += event.delta
return text
- Text is joined by
output_text. The API sends no text field: OpenAI's schema namesResponse.output_textas a property the SDKs compute, so it reads asNone.output_text(response)(aiollm_openai.adapters) joins theoutput_textparts of themessageitems, as the SDKs do, andreasoning_summary(response)the reasoning summaries. - Nothing unknown is dropped or rejected. An output item, content part or stream event of a type the schema does not name yet arrives as
UnknownVariant(aiollm_openai.types.shared), with every field the provider sent kept. - Failures are raised. A
failedresponse, buffered (CreateResponse) or as the stream'sresponse.failedevent, raises theAPIStatusErrorthatOpenAIErrorResolverbuilds fromresponse.error, with theResponseor the event inraw; so does the separateerrorevent.server_erroris anInternalServerError,rate_limit_exceededaRateLimitError; a code without its own class, such asinvalid_prompt, gives a plainAPIStatusError. None of them is transient (see Provider clients). This is stricter than the official SDK, which returns a failed response as a value. - Retried like the SDK.
CreateResponseandStreamResponseset__retryable__ = True: a lost connection, a timeout, a 5xx or a 429 withRetry-Afteris retried, a stream only while it opens.response.incompletestays a regularResponseIncompleteEventwithresponse.incomplete_details. - Checked before sending. Every field follows the schema, and nested data is a model that refuses unknown keys. Dicts are taken and checked too, though type checkers want the models. On top of the schema,
metadatatakes up to 16 pairs with keys up to 64 and values up to 512 characters, limits OpenAI writes only in its description. - Only what is given is sent. Every optional field is left out until it is given (it defaults to
MISSING), and takesNone, sent asnull, where OpenAI's schema allowsnull. See Optional fields.
Anthropic Messages API¶
aiollm_anthropic.methods has CreateMessage and StreamMessage for POST /v1/messages, with request fields in aiollm_anthropic.methods.params and Anthropic's own types in aiollm_anthropic.types, generated from the schemas of the offline documentation snapshot:
from aiollm_anthropic import AnthropicClient
from aiollm_anthropic.adapters import message_text
from aiollm_anthropic.methods import CreateMessage, StreamMessage
from aiollm_anthropic.methods.params import UserMessageParam
from aiollm_anthropic.types import RawContentBlockDeltaEvent, TextDelta
async def ask_claude(client: AnthropicClient) -> str | None:
message = await client.send_request(
CreateMessage(
model="claude-opus-5-5",
max_tokens=1024,
system="Be brief",
messages=[UserMessageParam(role="user", content="Hi")],
)
)
return message_text(message)
async def ask_claude_streamed(client: AnthropicClient) -> str:
text = ""
method = StreamMessage(
model="claude-opus-5-5",
max_tokens=1024,
messages=[UserMessageParam(role="user", content="Hi")],
)
async with client.stream(method) as events:
async for event in events:
if isinstance(event, RawContentBlockDeltaEvent) and isinstance(
event.delta, TextDelta
):
text += event.delta.text
return text
- Retried like the SDK.
CreateMessageandStreamMessageset__retryable__ = True: a lost connection, a timeout, a 5xx, the 529overloaded_erroror a 429 withRetry-Afteris retried, a stream only while it opens. - The version is part of the method. Both methods send
anthropic-version: 2026-10-21(VERSION_HEADERS), the version their types follow, whatever session sends them. A method of your own for Anthropic sets__request_headers__ = VERSION_HEADERStoo. - Text is joined by
message_text.message_text(message)(aiollm_anthropic.adapters) joins thetextblocks of the content and isNonewithout them;message_thinking(message)joins the thinking. - Nothing unknown is dropped or rejected. Content blocks, deltas and stream events of a type the schema does not name (such as
ping) arrive asUnknownVariant(aiollm_anthropic.types.shared), with every field kept. Theerrorevent is raised as anAPIStatusErrorchosen by its type, such asServiceUnavailableErrorforoverloaded_error; like OpenAI's in-band failures, it is never transient. - Checked before sending. Every field follows the schema, and nested data is a model that refuses unknown keys. Beyond the schema, which names no limits here,
messagesneeds at least one turn,max_tokensat least 0 andmetadata.user_idat most 512 characters (MessageLimits). There are notemperature,top_pandtop_k: API version 2026-10-21 rejects them. - Only what is given is sent. An optional field is left out until it is given; it takes
Noneonly where Anthropic's schema allowsnull.
Provider types¶
The provider types and request parameters are generated with aiollm-codegen by each provider's scripts/generate_types.py, in its own repository (aiollm_openai, aiollm_anthropic): OpenAI's from its official OpenAPI file, Anthropic's from the types of its official Python SDK and a transcription of its Files reference. Every class names the upstream schema it mirrors in __upstream_schema__, and the provider's test_wire_contracts.py checks each field against it. The method classes in methods/ stay hand-written: they add what the schema does not say, such as retries, the parsing of a failed response and the limits above.