Skip to content

Changelog

All notable changes to this project will be documented in this file.

The format is based on Keep a Changelog, and this project adheres to Semantic Versioning.

Unreleased

0.17.0 - 2026-11-21

Added

  • Files of built-in tools: GenerationResponse.files and CompletedEvent.files list the files a built-in tool made (a chart the code drew) as ProducedFiles, a ProviderFile with its filename, the container_id of a code container and the source_call_id of the call that made it, as far as the provider tells them; client.files.download(file) streams one from wherever it lives, a container included. CodeExecution(files=[...]) puts stored files into the sandbox for the code to read. A file of a container is reached only by download: retrieve, delete, a part's file and CodeExecution.files refuse it with RequestValidationError, as they refuse another provider's file. aiollm.adapters.container_of(file) tells an adapter which container holds a file.

Changed

  • Breaking: for provider packages. IFilesAdapter.to_download_method (and BaseFilesAdapter's) takes the whole ProviderFile instead of its id, so that a provider downloads a ProducedFile from its container or refuses it where it has none: a provider changes the parameter and reads file.id, with container_of(file) for the container. In the test kit, BuiltinCase takes coded, coded_stream, produced and code_files (a code execution that made a file, and the files a CodeExecution reads), and FilesCase takes container_download (the path of a container file's download, None for a provider without containers): a provider adds them to its cases.
  • BuiltinCase.paused and BuiltinCase.continued of the test kit are optional: a provider whose API never pauses a turn (OpenAI's Responses API) leaves them out, and the scenario that continues a paused turn is skipped for it instead of failing. A provider that has them is checked as before.

0.16.0 - 2026-11-21

Added

  • Built-in tools, the ones a provider runs itself, in the shared request and response: WebSearch and CodeExecution (with UserLocation), the two both providers have, and ProviderTool for a provider's own, all in the tools= list beside the functions (request.tools keeps the functions, request.builtin_tools has the rest). A response has server_tool_calls (ServerToolCall: kind, status, queries, code, error, the provider's items in raw; a failed tool is a call with FAILED, not an exception) and citations (Citation), a stream has ServerToolCallEvent for the start and the end of a call, and CompletedEvent carries the same two fields. IncompleteReason.PAUSED is a turn the provider paused. A provider takes them from its own release: the 0.15 provider packages send no built-in tool yet. For providers and tests: check_builtin_tools in aiollm.adapters, BuiltinCase for the shared scenarios (a GenerationCase without one skips them) and a web search and a code execution in the echo provider, with the new names in the extension API.

Changed

  • An assistant Turn can carry native, and to_turn() of a response that called built-in tools, or paused (IncompleteReason.PAUSED), returns one: the provider needs its own record of the turn, such as Anthropic's encrypted search results, to go on with it. A paused response without text has a turn too, and a conversation may now end with an assistant turn that has native, to continue the pause; any other assistant turn still cannot end it, and an ordinary text answer still gives a plain turn. A provider adapter sends Turn.native when it is its own, as it does for a ToolCallTurn, and one that does not ignores it, so a provider package on this core changes nothing until it takes these.
  • The core and both providers are on PyPI: pip install aiollm-openai or pip install aiollm-anthropic installs a provider with the core it needs, and pip install aiollm-core the core alone. The README no longer installs from source.

0.15.0 - 2026-11-20

Added

  • The checks an adapter runs on a shared request, checked_options, merge_options, request_errors, check_conversation and check_files, are exported from aiollm.adapters, so a provider written outside the library takes them from a public package. The Extending guide lists the names of the core a provider package may build on.
  • aiollm.testing runs a provider of your own through the scenarios every library provider passes: subclass GenerationContract, FilesContract and ClientContract (aiollm.testing.contract) with a case of your wire format. aiollm.testing.extension.check_extension_api lists the imports of a package outside the extension API (now aiollm/testing/extension_api.json), aiollm.testing.wire compares generated models with a snapshot of the upstream schemas, and aiollm.testing.echo is a whole provider built from the extension API alone, for an API that exists only on the local server; its EchoClient types the arguments of its session, as a provider client does. The testing extra now installs jsonschema too.
  • aiollm.testing, the test kit the library's own tests use, for code built on aiollm, such as a provider of your own: FakeTransport replays queued responses through the real session, Recorder (in aiollm.testing.aiohttp) is a local server that answers only what a test scripted, and the pytest plugin aiollm.testing.plugin gives their fixtures and makes retries instant. Its dependencies come with the new testing extra.

Changed

  • Breaking: Provider is an open value instead of a closed enum, so a provider written outside the library names itself and its files and errors stay apart from another one's. It is a str made from the provider's name; the library declares only Provider.GENERIC, and each provider package its own PROVIDER. To migrate, write aiollm_openai.api.PROVIDER (or Provider("openai")) for Provider.OPENAI, aiollm_anthropic.api.PROVIDER (or Provider("anthropic")) for Provider.ANTHROPIC, and Provider("<name>") for the Provider.GENERIC an adapter or resolver of your own set; compare providers with ==, not is. ANTHROPIC_VERSION, the header name, moved from aiollm.http.headers to aiollm_anthropic.api.
  • The project moved to the aiollm-org GitHub organization: the repository is https://github.com/aiollm-org/aiollm and the documentation is at https://aiollm-org.github.io/aiollm/. The old GrehBan/aiollm addresses redirect, but the old documentation address no longer opens.

Removed

  • Breaking: the providers left the core for packages of their own, in repositories of their own, and the core's distribution is now named aiollm-core (was aiollm; import aiollm is unchanged). To migrate, install the provider you use and change its imports: aiollm.providers.openai → aiollm_openai (distribution aiollm-openai), aiollm.providers.anthropic → aiollm_anthropic (distribution aiollm-anthropic). The modules under them keep their names (aiollm.providers.openai.methods → aiollm_openai.methods), and a provider package installs the core it needs. ToolCall left the extension API as a name of aiollm.types.responses.generation: a provider takes it from aiollm.types.requests.generation, where it is defined.

0.14.0 - 2026-11-20

Added

  • OpenAI's Responses API follows openapi.yaml at commit 76a4810: the request takes background_options (BackgroundOptionsParam: completion_window and continuation_id) for a background: true call, and a response has input_transformations (ReasoningInputTransformation), the reasoning inputs withheld from the model.

Changed

  • Breaking: the Anthropic types and request parameters follow the anthropic 2.11.0 SDK, which renamed five error objects of the server tool results: BashCodeExecutionToolResultError, CodeExecutionToolResultError, TextEditorCodeExecutionToolResultError, ToolSearchToolResultError and WebSearchToolResultError are now named with an Object suffix (CodeExecutionToolResultErrorObject, ...), in providers.anthropic.types and providers.anthropic.methods.params, and WebSearchToolRequestErrorParam is now WebSearchToolRequestErrorObjectParam. Their fields are unchanged. The model literal lists claude-fable-5-2 and claude-mythos-5-2, and a skill id may be 128 characters long.

0.13.0 - 2026-11-19

Added

  • OpenAI's and Anthropic's Files APIs: CreateFile, ListFiles, RetrieveFile, DeleteFile and DownloadFile in each provider's methods, with their generated types (OpenAIFile, FileMetadata, the list and deletion results) and request parameters. Upload a file once and refer to it by id in later requests instead of sending its base64 each time. An upload is never retried, since POST /files is not idempotent; listing returns one page per call; DownloadFile streams the content (Stream.save(path)). See the new Provider files guide.
  • client.files on OpenAIClient and AnthropicClient: the same upload, retrieve, list, delete and download for every provider, in shared types. An upload returns a StoredFile (ref, filename, size, created_at, expires_at in UTC, the provider's metadata in raw), and its ref, a ProviderFile, goes into the new third source of ImagePart and DocumentPart, file=, so a request carries the file's id instead of its base64. A ProviderFile of another provider raises RequestValidationError before anything is sent. list() goes through every page; OpenAI's uploads are user_data files unless provider_options={"purpose": ...} (the new OpenAIFileOptions) says otherwise. New public names: FilesResource, IFilesResource, IFilesClient, IFilesAdapter, BaseFilesAdapter, OpenAIFilesAdapter, AnthropicFilesAdapter, FileUpload, ProviderFile, StoredFile.

Changed

  • Breaking: a dict (or a model) in a FORM or MULTIPART body is now sent as one field per key with the key in brackets, expires_after[anchor]=created_at, nested dicts likewise, as OpenAI's upload reads it; it was sent as one JSON-encoded field, which OpenAI refuses with a
  • A list inside a dict, or a dict inside a list, now raises TypeError, since the form cannot keep its boundaries, and the session's json_dumps is no longer used for forms. To keep sending a JSON-encoded field, declare it as str and pass json.dumps(value).

0.12.1 - 2026-11-19

Fixed

  • A blocking call that ran on after its caller was cancelled (an upload's read or open, a synchronous tool callback) and failed after the coroutine given to asyncio.run had returned was dropped silently: asyncio.run cancelled the task that waited for it. The call is no longer a task, so the loop, which waits for its worker threads before closing, reports the failure through its exception handler as at any other time.
  • The tools guide said that the runner starts callbacks only while the consumer waits for a result; entering async with calls: (or the first read) already starts the first ones, up to concurrency.
  • Tool.from_callable() and @tool take a functools.partial (named after the function it wraps, its bound arguments left out of the schema) and an object with a __call__ method (named after its class, read without self); both raised TypeError before. The generated schema now says additionalProperties: false, as the arguments were already validated that way, and a strict tool whose callable takes **kwargs, which no strict schema can describe, raises TypeError instead of getting a 400 from the provider.

0.12.0 - 2026-11-19

Added

  • The iterator returned by tool_runner.create() is an async context manager: async with calls: cancels and awaits unfinished callbacks when the block is left early, as tool_runner.stream() already did.
  • tool_runner.create() and tool_runner.stream() take in_order and buffer_size. in_order=False yields each ToolResult as soon as its callback finishes instead of in tool-call order. buffer_size lets that many finished but unread results wait beyond concurrency, so a slow first callback holds back the ones after it only once those places are full. Further callbacks start while the consumer waits for a result, not between its reads.
  • tool_runner.create() and tool_runner.stream() take on_error, which turns the exception of a failed callback (or of serializing its output) into that call's ToolResult.output, so the model reads the failure and the other callbacks go on, for example on_error=lambda error: f"Error: {error}". Without it a failure is raised as before.

Changed

  • Breaking: the tool runner executes callbacks with aiopulse's CallbackExecutor, a new dependency: aiopulse-py from PyPI (>=0.0.5), imported as aiopulse. A callback failure is raised as a CallbackExceptionGroup holding every failure observed before the callbacks stopped, even when there is only one, instead of the first failure alone; handle it with except* or read its failures. CallbackExceptionGroup, CallbackFailure and CallbackCancelledError are re-exported from aiollm. An iteration of tool_runner.create() still waiting in another task when the iterator is closed ends with StopAsyncIteration instead of CancelledError.
  • Breaking: the tool runner runs a synchronous callback in a worker thread instead of in the event loop, so a blocking callback no longer stops the loop and, with concurrency above 1, synchronous callbacks run at the same time. A callback that must stay in the loop's thread (one that uses an sqlite3 connection or other object bound to its thread, or that is not thread-safe) should be an async def. A cancelled synchronous callback runs to its end, since a thread cannot be stopped; a failure it then ends with is reported through the event loop's exception handler.

Fixed

  • A tool callback that ended with a cancellation the runner did not request, such as awaiting a cancelled task, reached the consumer as CancelledError, which looks like a cancellation of the consumer and is swallowed by its TaskGroup. It is now a CallbackCancelledError failure in the raised CallbackExceptionGroup, with the original cancellation as its __cause__.

0.11.2 - 2026-11-17

Added

  • Allow limiting callback concurrency in buffered and streaming tool runners while preserving sequential execution by default.

0.11.1 - 2026-11-16

Added

  • Added callback execution for shared generation tools through buffered and streamed tool runners. Generation resource keyword arguments now accept callable tools directly, and the guide documents manual and runner-based workflows.

0.11.0 - 2026-11-16

Added

  • A user turn of client.generation can hold images and PDF documents: Turn.user([...]) takes a list of TextPart, ImagePart and DocumentPart, each image or document given as bytes (sent inline in base64) or as a URL. await ImagePart.load(path) and await DocumentPart.load(path) read a file in a worker thread. OpenAI gets input_text, input_image and input_file items, Anthropic text, image and document blocks; parts in an assistant turn raise ValidationError.
  • Added Tool.from_callable and the @tool decorator to derive a tool's name, description, and argument schema from a callable. Decorated functions remain directly callable and expose their cached definition as .tool.
  • Tool.from_model(name, Model, ...) makes a tool whose parameters are a Pydantic model's JSON Schema, and ToolCall.parse_arguments(Model) validates a call's arguments with the model and returns it, raising the model's ValidationError (a ValueError) for arguments the tool does not take. parse_arguments() without a model still checks only that the arguments are a JSON object.

Changed

  • Breaking: Turn.content is typed str | list[ContentPart] instead of str, since a user turn can now hold parts. Turns built from a string are unchanged at run time, but code that reads turn.content as a string no longer type-checks: narrow it first with isinstance(turn.content, str). An assistant turn is always a string.
  • The provider types are reproducible: scripts/generate_provider_types.py runs aiollm-codegen from the codegen dependency group, pinned to a commit of its public repository, and downloads OpenAI's OpenAPI file at a pinned commit, refusing a file whose SHA-256 is not the one of the contract snapshot. CI regenerates the types and fails when any file changes.

Fixed

  • A request body with a Pydantic URL in it, such as the file_url or image_url of OpenAI's generated parameters, failed with "Request body cannot be encoded as JSON". URLs are now sent as their text.
  • The documentation of ToolCallDoneEvent said a call "may be run" as soon as it arrives. It now says what the event guarantees: the arguments of that call are complete, not that the generation succeeded, since the stream can still fail before its CompletedEvent. The tools guide shows how to start only the tools that are safe to run early and run the ones with side effects after the stream has completed.
  • The generation guide gives the measured peak memory of a request with a loaded file: about 15 times the file's size with the default orjson encoder, which briefly holds a buffer far larger than its result for a long string, and about 5 times with json_dumps=json.dumps.

0.10.0 - 2026-11-07

Added

  • A conversation can carry a tool loop: GenerationRequest.input takes ToolCallTurns (the model's calls, with its text) and ToolResults (call_id, output) next to Turns, as InputItems. GenerationResponse.to_turn() gives a ToolCallTurn for a response with calls, holding the response's own output in native (GenerationResponse.native), so the provider gets its reasoning back (OpenAI's reasoning items, Anthropic's signed thinking); another provider gets the shared calls. Every adapter refuses a conversation out of order (a call without its result, a result without its call, text between them) before sending, and Anthropic's adapter calls whose arguments are not a JSON object.
  • The guide has a Tools page: a tool loop that works with any provider, how calls, results and reasoning travel, and streaming; the shared generation, design and providers pages and docs/unification.md describe tools and the generated provider types.
  • GenerationRequest and client.generation.create() / stream() take tools (a list of Tool: name, description, JSON Schema parameters, strict), tool_choice (a ToolChoice: AUTO, NONE, REQUIRED, or a ForcedTool naming one tool) and parallel_tool_calls, sent to OpenAI as function tools and to Anthropic as custom tools; settings no provider takes (a choice without tools, a forced tool that is not one of them, duplicate names, parallel calls with NONE) are refused before sending. OpenAI's provider options gain include and max_tool_calls.
  • GenerationResponse.tool_calls and CompletedEvent.tool_calls list the model's calls of the request's tools as ToolCalls (id, name, arguments as JSON text; parse_arguments() gives the object and raises ValueError for text that is not one), from OpenAI's function_call items and Anthropic's tool_use blocks, buffered or streamed. output_text/reasoning_summary/tool_calls (OpenAI) and message_text/message_thinking/message_tool_calls (Anthropic) do the same for the providers' own responses.
  • client.generation.stream() yields ToolCallStartEvent (call_id, name), ToolCallDeltaEvent (a piece of the arguments) and ToolCallDoneEvent (the whole ToolCall, before the response ends) for each tool call, from OpenAI's function call items and Anthropic's tool_use blocks. CompletedEvent carries native, the stream's own output put together from its events (Anthropic's thinking with its signature among it), and to_turn(), so a streamed tool loop continues as a buffered one does.

Changed

  • Breaking: OpenAI's and Anthropic's own types are now generated from their schemas (OpenAI's official OpenAPI file, Anthropic's documentation snapshot) and cover the whole of each endpoint: every output item, content block, tool and stream event the schema names, with request parameters in the new aiollm.providers.openai.methods.params and aiollm.providers.anthropic.methods.params. Names follow the schemas, so code that imports provider types migrates: OpenAI OutputText → OutputTextContent, OutputRefusal → RefusalContent, OutputTextDeltaEvent → ResponseTextDeltaEvent, ResponseStateEvent → ResponseCompletedEvent, ResponseIncompleteEvent and the others of its kind, UnknownOutputItem, UnknownContent and UnknownEvent → UnknownVariant; Anthropic MessageStartEvent, ContentBlockDeltaEvent and the other events → RawMessageStartEvent, RawContentBlockDeltaEvent, ..., MessageDelta → Delta, StopDetails → RefusalStopDetails, UnknownBlock, UnknownDelta and UnknownEvent → UnknownVariant, and a ping is an UnknownVariant; MessageParam, ResponseParams, Reasoning, TextConfig and the other request TypedDicts give way to the generated models, which take dicts at run time and refuse unknown keys. Response.output_text, Response.reasoning_summary, Message.text and Message.thinking are gone: OpenAI's output_text is a schema field the API leaves out, so use output_text() and reasoning_summary() from aiollm.providers.openai.adapters and message_text() and message_thinking() from aiollm.providers.anthropic.adapters. The types follow the schemas strictly: OpenAI's usage needs its input_tokens_details and output_tokens_details and an output_text part its annotations and logprobs, Anthropic's message_delta its usage, and an Anthropic turn may be a system one. The early checks the schemas do not state stay: OpenAI's metadata limits, and Anthropic's at least one turn, max_tokens from 0 and metadata.user_id up to 512 characters.
  • Breaking: Turn has a type field ("text"), which shows in its repr and model_dump(); a dict without type still reads as a Turn. GenerationResponse.to_turn() returns Turn | ToolCallTurn and raises ValueError for a response with calls that stopped early. The adapters' input_conversion takes a list of InputItems instead of Turns, so a custom conversion handles the new items; GenerationRequest.input and the input of create() / stream() are typed str | Sequence[InputItem], so a list[Turn] still type-checks. ToolCall moved to aiollm.types.requests (it is still in aiollm).
  • An Anthropic message that stops with stop_reason: "tool_use" now finishes normally: incomplete_reason and raw_incomplete_reason are None, as for a completed OpenAI response with function calls, since the model is waiting for the tool results.

0.9.0 - 2026-11-05

Added

  • GenerationRequest and client.generation.create()/stream() take effort=, an Effort (low, medium, high, xhigh, max): how much work the model puts into the response, sent as OpenAI's reasoning.effort and Anthropic's output_config.effort. Left out, nothing is sent and the model's default applies. CreateResponse/StreamResponse gain reasoning (Reasoning) and CreateMessage/StreamMessage output_config (OutputConfig), as the providers' schemas define them.
  • GenerationRequest and client.generation take output_schema=, a JSON Schema the response text then follows as JSON: OpenAI's text.format (json_schema, strict: true, named by OpenAIGenerationAdapter(schema_name=...), "output" by default) and Anthropic's output_config.format. The schema is sent as it is. CreateResponse/StreamResponse gain text (TextConfig) and Anthropic's OutputConfig its format; JSONSchema and JSONValue are in aiollm.types.requests.
  • GenerationResponse.reasoning and CompletedEvent.reasoning hold a summary of the model's reasoning, and stream() yields it as ReasoningDeltaEvents, when the request asks for one through provider_options: OpenAI's {"reasoning": {"summary": "auto"}} (OpenAIReasoningOptions, merged with the shared effort) or Anthropic's {"thinking": {"type": "adaptive", "display": "summarized"}} (thinking, a new field of CreateMessage). OpenAI's ReasoningItem and ReasoningSummaryTextDeltaEvent and Anthropic's ThinkingBlock and ThinkingDelta are modeled.

Changed

  • Breaking: GenerationRequest.metadata is replaced by end_user_id, an opaque id of the end user (a hash, never personal data) that both providers use to detect abuse: OpenAI's safety_identifier (up to 128 characters, now a field of CreateResponse) and Anthropic's metadata.user_id (up to 512). The shared metadata meant different things (free-form pairs stored by OpenAI, only user_id at Anthropic). Pass end_user_id=... where you passed metadata={"user_id": ...}, and OpenAI's free-form pairs as provider_options={"metadata": {...}} (OpenAIGenerationOptions).
  • Breaking: a stream's reasoning summary pieces (OpenAI's response.reasoning_summary_text.delta, Anthropic's non-empty thinking_delta) come as ReasoningDeltaEvent instead of OtherEvent, and GenerationEventType has REASONING_DELTA; code that matched them as OtherEvent matches ReasoningDeltaEvent now. OpenAI's reasoning output items and Anthropic's thinking blocks are ReasoningItem and ThinkingBlock, no longer UnknownOutputItem and UnknownBlock.
  • client.generation of AnthropicClient sends max_tokens 16000, not 1024, when a request has no max_output_tokens: thinking is always on for the Claude 5.x models and counts toward max_tokens, so 1024 could end a reply in its thinking, with little or no text. Pass default_max_tokens= to the client to keep another value.

0.8.0 - 2026-11-05

Added

  • The versioning guide says when 1.0 comes: not after 0.9 (0.10 follows it), but once two releases in a row have no breaking change, the core and the shared generation layer are declared stable and outside users have given feedback; 1.0.0a1, b1 and rc1 pre-releases may come before it.
  • client.generation.create() and stream() take provider_options=, a provider's own fields of that call that the shared request does not hold: store, previous_response_id, temperature and top_p for OpenAI (OpenAIGenerationOptions), stop_sequences for Anthropic (AnthropicGenerationOptions). The options are a TypedDict of the client's provider, so a wrong key or value is a type error; at run time an unknown key or an invalid value raises RequestValidationError before anything is sent. Code typed as IGenerationClient cannot pass them.

Changed

  • Breaking: GenerationResource takes the provider's options as its third type parameter, GenerationResource[RawT, RawItemT, OptionsT = NoProviderOptions, SessionT = ISession], so a session type given as the third argument moves to the fourth. Its adapter is an IGenerationAdapter, which adds with_options(options, /) -> Self to ICompositeAdapter: a generation adapter of your own without provider options adds a with_options(self, options: NoProviderOptions, /) -> Self that calls checked_options(options, NoProviderOptions, self.provider) (from aiollm.adapters.validation), so no key is dropped silently, and returns self. NoProviderOptions is closed: only {} matches it. CallOptions is now closed (PEP 728): a **options: Unpack[CallOptions] takes no other key, and typing-extensions is a direct dependency.

Fixed

  • A retry policy's retry_if and backoff are no longer called after the last attempt max_attempts allows, when no retry can follow: a backoff that counts retries or a retry_if that logs counted one call too many. With a deadline, backoff is still asked for the wait it would cut, since whether the deadline stops the retries depends on that wait.
  • The resources guide's custom adapter example has the with_options that a GenerationResource adapter now needs (type checkers refused the example without it), and the design guide's limitations say that client.generation is text only.

0.7.0 - 2026-11-05

Added

  • A contributing guide, CONTRIBUTING.md (also the site's Contributing page): setting up with pip or uv, the checks, the docs, changelog fragments, what CI requires, and directives for contributors who work with Claude.
  • Fuller package metadata on PyPI: maintainers, keywords, classifiers (pre-alpha, asyncio, aiohttp, Pydantic 2, CPython 3.13–3.15, typed) and links to the issue tracker and the home page; the author's address is now maximfeedback19@gmail.com.
  • Retries are configured with a RetryPolicy: the number of attempts (max_attempts, still 4 by default), the deadline, the longest Retry-After worth waiting for, the backoff (FullJitterBackoff by default, or any callable that takes a RetryState) and retry_if, which can refuse a transient error. Give one to a session or a client as retry_policy=, or to a single send_request or stream call to replace the session's for that call. A policy only narrows what is retried: methods still opt in with __retryable__, and only transient errors are retried. If retry_if or backoff fails, its error keeps the request's error as its __cause__.
  • client.generation.create() and stream() take the options of the call, headers=, timeout= and retry_policy=, as send_request does, and pass them to the session unchanged for every provider: an idempotency key, a longer limit for one generation or a single attempt no longer needs the provider's own methods. The use cases of aiollm.resources pass them on too, and aiollm.session.CallOptions names them for **options.

Changed

  • Breaking: IUseCase.__call__ and IStreamUseCase.stream, and the abstract methods of BaseUseCase, BaseStreamUseCase and BaseCompositeUseCase, take the options of the call as **options: Unpack[CallOptions]. A use case of your own adds that parameter and passes **options to session.send_request or session.stream; without it, type checkers report an incompatible override.
  • Breaking: a provider client declares its shared resources with bind_resource: generation = bind_resource(GenerationResource[Response, ResponseStreamEvent], MyGenerationAdapter), with adapter_factory= for an adapter that takes options from the client. BaseProviderClient builds every adapter before the session (a bad option still fails without one) and every resource after it, and checks each adapter's provider when the class is defined. adapter_types and BaseProviderClient.adapter() are removed.

Removed

  • Breaking: Sessions and provider clients no longer take max_retry_after and retry_deadline, and sessions no longer have attributes of those names; pass retry_policy=RetryPolicy(max_retry_after=..., deadline=...) instead and read session.retry_policy. The DEBUG record of a Retry-After above the limit now comes from the aiollm.session.retry.runner logger instead of aiollm.session.retry.
  • Breaking: The import package and distribution are now named aiollm; change imports from ai_api to aiollm and dependency declarations from ai-api to aiollm.

Fixed

  • The README's quick start and the methods guide still said that a field set to None is not sent. Since 0.5.0 a field left MISSING is not sent, and None is sent as null; both now say so.

0.6.0 - 2026-11-02

Added

  • A Versioning section in the design guide: before 1.0 a breaking change bumps the minor version and anything else the patch, and the public API is what ai_api and the __all__ of its packages export.
  • CI tests every supported CPython (3.13, 3.14 and 3.15) on Linux and Windows, builds the wheel and imports it in a clean environment, and audits the locked dependencies for known vulnerabilities.
  • request_path_template on every method: the path as declared, such as /files/{file_id}, which holds none of the request's values and so is safe to log.

Changed

  • Breaking: the method protocols (IBaseMethod, so IAPIMethod and IStreamMethod) require a request_path_template property, the path as declared with its placeholders kept. Methods derived from BaseAPIMethod or BaseStreamMethod have it; a class of your own that implements a protocol directly adds a property returning its path template.
  • The logs no longer carry anything that may name a user's data. The transport logs the path as declared (Sending GET /files/{file_id}), not the values of its parameters; a followed redirect is logged without the server's path; a retry names the failed attempt's error type and how many notes it has, not their text; the body writer's failure after the response came is logged by its type, without its message or traceback; the wait for a cancelled upload read no longer names the file.

Fixed

  • On Python 3.14 and newer, a blocking call of an upload or a download (a read, a write, a close) that failed after its caller was cancelled was reported twice to the event loop's exception handler, once by asyncio.shield; it is reported once.

0.5.0 - 2026-11-02

Changed

  • Breaking: a request field that is not given is left out with MISSING, and None is sent as null. Until now None meant both, so a request could not send null. A field is declared after the API's schema: x: int | MISSING = MISSING (left out until given), x: int | None | MISSING = MISSING (left out, or null), x: int | None (required, may be null).
  • Breaking: a method field that defaults to None, or holds a model with such a field anywhere in its type, raises TypeError once the class is complete (at definition; at the first use of a class that names a model declared further down, and then for every instance), since it would send null for a value nobody set. Dataclasses (standard and Pydantic's), NamedTuples and NewTypes in a field's type are looked into as models are, and a default factory that gives None counts as a None default. Recursive type aliases are walked once.
  • Breaking: MISSING goes in a field's type only together with the MISSING default, and the other way round; otherwise the class raises TypeError, since a required field that takes MISSING could be left out. Any takes MISSING.
  • MISSING as an item of a list or a value of a dict raises ValueError when the request is built, instead of an encoder error about an unknown type. Replace limit: int | None = None with limit: int | MISSING = MISSING (from pydantic import MISSING), and describe nested request data with a TypedDict (NotRequired keys are left out). Fields with exclude=True are not checked.
  • Breaking: None in a query parameter or a form field raises ValueError instead of being skipped: neither has a null.
  • Breaking: GenerationRequest.instructions, max_output_tokens and metadata default to MISSING and take no None; leave a field out instead. generation.create() and stream() show T | MISSING in their keyword arguments.
  • The OpenAI and Anthropic request fields follow the providers' schemas: OpenAI's optional fields take None (sent as null), Anthropic's system, metadata and stop_sequences do not.
  • Breaking: a model put into a request body at run time, such as a response item sent back, sends its None fields as null; until now they were dropped. Dump it with model_dump(by_alias=True, exclude_unset=True) to send exactly the fields the response had.
  • Shared requests validate assignments: request.instructions = None raises ValidationError, as the constructor does.
  • A type with a PlainSerializer is not looked into for None defaults: the serializer decides what is sent.

Added

  • A path parameter that defaults to MISSING raises TypeError at class definition.
  • The wire-contract tests check every provider method field against the request schema: None where null is allowed, MISSING only where the field is optional.

Fixed

  • AnthropicGenerationAdapter given metadata=None (through model_copy, which validates nothing) raised a bare TypeError; it raises RequestValidationError, as for the other fields.

0.4.4 - 2026-11-02

Added

  • Logging through the standard logging module, under ai_api and one logger per module that logs, with only a NullHandler on ai_api. An exception that reaches the caller is not logged; what the library handles or swallows is: a call's start and end and every attempt (sent; finished with status and duration) at DEBUG, every retry at WARNING (with the failed attempt's error and its notes, which are not raised), a suppressed error at DEBUG with its traceback. Tokens, keys, headers, bodies and query strings are never logged. See the Logging section of the sessions guide.
  • ruff's G and LOG rules, so log calls stay lazy.

Fixed

  • A stream refused with an error status while its upload was still open, whose source then failed to close, raised the close error instead of the status error; the status error is raised now, with the close error as a note.
  • The body writer's failure after the answer came was suppressed without a trace; it is logged at DEBUG, with its traceback.

0.4.3 - 2026-11-02

Fixed

  • A file closed after a cancelled read or write (PathFile, Stream.save, a cancelled open) was closed in the event loop, where a flush could block every other task; it is closed in the worker thread now.
  • A close put off until a cancelled call ended failed silently into the loop's handler, without the note on the error that ended the work; it now gets the note and is reported as a ThreadWork failure.
  • A call that failed after its caller was cancelled (a read() that raised later) was dropped without a trace; it is now reported through the loop's exception handler.
  • A stream that failed while its upload was still open, with a source that then failed to close, raised the close error instead of its own; the stream's error is raised now, with the close error as a note. BaseSession.stream closes the parser and the response the way an upload source is closed.

Changed

  • closing_source(resource, what=...) takes any closable resource and names it in the note. ThreadWork.finish is a coroutine and takes blocking=; both are internal helpers of types/files.py.

0.4.2 - 2026-11-02

Added

  • A documentation site, built with MkDocs and Material and published to GitHub Pages: https://grehban.github.io/ai_api/. The guide pages were checked against the code; the reference is generated from the docstrings. CI builds it with mkdocs build --strict, and .github/workflows/docs.yml publishes it from master.
  • [project.urls] in pyproject.toml: documentation, repository and changelog.

Changed

  • README.md is short: what the library is, features, installation and the quick start, with links to the site. The rest moved to the guide.
  • Every Python example has a title="name.py", by which tests/docs/test_examples.py (was test_readme.py) finds it in the README and every page; an example without a title or without a test fails.

Fixed

  • Documentation claims that no longer matched the code, among them: session headers are read on every request, not fixed when the pool is created; methods cannot send tools or other parameters they do not list; a text stream in a method is a ValidationError at creation; APIStatusError also covers in-band failures below 400.

0.4.1 - 2026-11-02

Changed

  • StreamFile takes ownership of its source: the upload closes it, by aclose() else close(), when it ends, however it ends (read to the end, cut short, cancelled, failed, or never sent because the request failed first). StreamFile.open() now returns an iterator that is not a generator and raises RuntimeError on a second call at once.
  • The body builder opens every upload while it builds the body, so an open() that raises is an APIRequestError before anything is sent.

Removed

  • The aiofiles dependency (and the types-aiofiles dev stub). PathFile and Stream.save open, read, write and close files in a worker thread themselves.

Fixed

  • A PathFile whose opening was cancelled (an answer that comes before the body is read cancels the upload) left the file the worker thread opened open; it is now closed as soon as it is open, and the retry after such an answer passes.
  • StreamFile did not close the source it was given.
  • A cancelled IOFile read let go of the stream while its read() still ran in the worker thread, so the retry seeked and read under it; the next read now waits for that call. Likewise a cancelled PathFile read or Stream.save write closes its file only after the call running in the thread is over.
  • A source that failed to close hid the error that ended the upload; the close error is now a note on that error.
  • A source that failed to close while the upload was cancelled turned the cancellation into APIRequestError; the cancellation now goes on, with the close error as a note. The same holds for the attempt: a failing close no longer replaces the error that ended it.

0.4.0 - 2026-11-02

Added

  • BaseAPITypeExtra (ai_api, ai_api.types): a payload base with extra="allow". The provider response types derive from it, so the fields the library does not model are kept in model_extra, reached through raw (response.raw.model_extra["service_tier"]).
  • ChunkedFile (ai_api, ai_api.types): the base of PathFile and IOFile, for a source of your own read piece by piece.
  • MAX_LINE_SIZE and MAX_EVENT_SIZE (ai_api.response.parse.stream): the default stream limits.

Changed

  • Breaking: StreamResponseParser limits a line and the data of an SSE event to 32 Mi characters by default (MAX_LINE_SIZE, MAX_EVENT_SIZE); a longer one raises APIResponseError, and None lifts a limit. They are large because a generated image comes as base64 in one line.
  • Breaking: nothing may follow a declared terminal: an error event after it raises APIResponseError too, where it raised the APIStatusError of the error.
  • Breaking: IBodyBuilder.build() takes a keyword-only uploads (contextlib.AsyncExitStack), the stack of the attempt, on which the upload readers are registered; AiohttpStreamResponse takes it as well and closes it with the response.
  • Breaking: MAX_DEPTH moved from ai_api.serialization.normalize to ai_api.serialization.traversal, with guard_traversal, the one cycle and depth guard of the body normalizer and of the file helpers of methods. A circular reference reads "Circular reference detected".
  • InputFile.open() may return any async iterator: it is closed when an attempt ends, by aclose() if it has one, else by close() (awaited when its result is awaitable). A source that fails to close raises APIRequestError.
  • Matchers read an object that is neither a mapping nor a model without running its code: slots and plain attributes are read, a property, a method or another descriptor counts as no field.
  • Markdown files are checked with rumdl (docs dependency group).

Fixed

  • A method field holding a value that contains itself (through Any, a list, a dict or a nested model) ended in RecursionError when the method was created; it is a ValidationError now, as a field nested deeper than MAX_DEPTH is.
  • A retryable method with a field nested exactly MAX_DEPTH deep raised ValueError from retryable: the method itself was counted as a level.
  • A retry after a connection that broke mid-upload, or after an answer that came before the body was read, sends the whole file again. The session now closes the readers of every attempt; aiohttp leaves them suspended.
  • Two uploads reading one stream at once (two requests in asyncio.gather, or one raw stream given to two methods) took chunks from under each other and sent mixed files without an error; the second one raises APIRequestError now.
  • A chunk_size below one sent an empty file (read(0) gives b""); it raises ValueError now.
  • An SSE retry field with more digits than Python turns into a number (4300 by default) raised a bare ValueError from the stream; it is an APIResponseError now.

0.3.0 - 2026-11-01

Added

  • IValueFormatter and BaseValueFormatter (ai_api, ai_api.serialization): a method's __value_formatter__ (property value_formatter, also on IBaseMethod) writes dates, times and durations in every part of the request. The default is ISO 8601; an API that wants another format overrides it on its base method, and one field can use Pydantic's PlainSerializer.
  • BaseProviderClient (ai_api, ai_api.client): what a provider client shares, from its provider, session_factory, api_key_env, auth_headers and adapter_types (every adapter class it builds, one per shared resource); OpenAIClient and AnthropicClient are built on it. The client, its resolver and every adapter must name one provider (check_same_provider), checked when the class is defined; client.adapter(AdapterClass, ...) builds an adapter, typed as a call of the class, and refuses a class not in adapter_types.
  • SessionMismatchWarning (ai_api), a UserWarning: a session given to a provider client whose error resolver is not the provider's (a subclass of it is fine; another provider's resolver was not warned about before) or whose key goes in a header the provider does not take. Turn it off with the standard warning filters.
  • ISessionFactory, with error_resolver, and SessionFactory are exported from ai_api.session; breaking: SessionFactory moved from ai_api.client.factory to ai_api.session.factory.
  • RETRY_ATTEMPT_LIMIT (ai_api.session.retry): the 4 attempts of a retried request, as a constant.
  • Breaking: matchers compare values as JSON tells them apart (FieldValues("done", True) no longer matches 1), read a model's fields but not its properties (a property that raised broke the stream), and EventTypes("x") equals FieldValues("type", "x"); EventTypes.types is a view of values. A single matcher in AnyOf shows as AnyOf(x), and a protocol-only matcher may stand on the left of |.
  • Breaking: a ServerSentEvent item whose data is JSON goes through error_events, so an error in it raises instead of being yielded, and ServerSentEvent.retry keeps the last value the stream set, as id does (the HTML standard applies both at once).
  • Breaking: GenerationRequest refuses an empty model or text input before anything is sent; BaseAPI refuses credentials in base_url; a payload model (BaseAPIType) with a field of a type Pydantic cannot validate fails at class definition (only the raw of shared results takes any type).
  • Raw binary streams nested in a model inside a method field are wrapped as well (the model is copied); a stream in a container that cannot be rebuilt, such as a dict subclass, raises TypeError instead of being dumped lazily. Annotated members of a union are unwrapped by the path and query checks, so Annotated[dict, ...] | None is refused as a query field.
  • A path without placeholders unescapes {{/}} as one with them does; APIKeyAuth defaults to the X_API_KEY constant; an InputFile field explains that a str is not taken, and a path-like that Path() rejects is a validation error.
  • typing-extensions, aresponses and isort are no longer dependencies.
  • Ruff checks cyclomatic complexity (C90, max-complexity = 10, the mccabe default; a lower limit would flag flat match dispatchers); BodyNormalizer._normalize hands streams and containers to helpers of their own to stay under it, with the same behaviour.
  • Tests: the local Recorder fails a test on any request it was not scripted for, mirrored provider client tests run once per provider (tests/providers/test_provider_clients.py), the backoff is checked by properties of the real jitter, and documented responses are compared field by field with their JSON. The retry loop awaits tenacity's call directly, without an unreachable guard.
  • BaseErrorResolver.error_statuses and classify_status: a provider sets its table of in-band codes and types and overrides the classification of a status; classify keeps an in-band failure non-transient for every resolver.
  • ContentTooLargeError for HTTP 413 (Anthropic's request_too_large was a plain APIStatusError).
  • CompletedEvent.provider, as on GenerationResponse; every adapter has a provider (PROVIDER of its package, Provider.GENERIC outside the library).
  • Stream.items_received: how many items a stream has given. transform_stream(..., stream_type=...) yields a Stream subclass built on the transformed items, which GenerationResource uses for its GenerationStream.
  • Conversions: ai_api.adapters.IConversion[SourceT, TargetT] (a protocol of __call__(source, /), so a plain function fits) and its ABC BaseConversion, for pure value conversions between a provider's types and the shared ones; ai_api.adapters.Stop holds what a stop conversion returns (incomplete_reason, raw_incomplete_reason, refusal).
  • OpenAIGenerationAdapter and AnthropicGenerationAdapter take input_conversion=, usage_conversion= and stop_conversion= keyword arguments (defaults: each provider's InputConversion, UsageConversion and StopConversion), so one can be swapped without subclassing the adapter. A response and a stream go through the same conversions.
  • tests/docs/test_unification.py checks that every field of docs/unification.md is filled by a conversion that every adapter has, or is listed as taken as is.
  • generation.create(...) and generation.stream(...) take the fields of GenerationRequest as keyword arguments, as the providers' SDKs do (create(model="...", input="Hi")), or a ready GenerationRequest; passing both raises TypeError. IGenerationResource has the same overloads.
  • GenerationStream (ai_api.resources): generation.stream(...) yields it. Besides iterating every event, events.text() gives the text deltas and await events.final() reads to the end and returns the CompletedEvent; whatever read the stream, the CompletedEvent is kept.
  • CompletedEvent carries the response's id, model (required) and whole text, from OpenAI's terminal event and from Anthropic's message_start and text deltas.
  • IGenerationClient[RawT = Any, RawItemT = Any] (ai_api.resources): a client with a read-only generation; OpenAIClient and AnthropicClient match it.
  • OpenAIClient(token, **session_kwargs) and AnthropicClient(token, **session_kwargs) pass every keyword argument of AiohttpSession to the session built from the token, typed by ai_api.session.aiohttp.AiohttpSessionOptions; with session= they raise ValueError.
  • BaseAPIType.__upstream_schema__: the name of the upstream schema definition a provider model mirrors (several names, or () for none). tests/providers/test_wire_contracts.py requires it on every provider model and checks each modeled field against that definition: it exists upstream, accepts null where upstream does and is optional where upstream is.
  • The root package re-exports the shared generation layer: GenerationRequest, Turn, GenerationResponse, TokenUsage, TextDeltaEvent, CompletedEvent, OtherEvent, GenerationEvent, GenerationStream, IGenerationResource and IGenerationClient.

Changed

  • Breaking: a concrete adapter must set provider, and CompletedEvent requires it.
  • Breaking: OpenAI's ERROR_EVENTS is RESPONSE_ERROR_EVENTS, so it is not mistaken for the parser's default of the same name; the module-level warn_about_session functions are now the classmethod BaseProviderClient.warn_about_session, whose second warning names the headers the provider takes.
  • Leaving a client's async with calls the session's __aexit__, as entering calls its __aenter__, instead of close().
  • Breaking: 529 is no longer transient in BaseErrorResolver: it is Anthropic's own status, and AnthropicErrorResolver keeps classifying it as a transient ServiceUnavailableError.
  • Breaking: only a certificate that fails verification (ClientConnectorCertificateError, ServerFingerprintMismatch) raises APITLSError; another SSL error, such as a handshake that breaks off, is a transient APIConnectionError, retried as the official SDKs do.
  • Breaking: Retry-After is read as RFC 9110 defines it, whole seconds in ASCII digits or an HTTP date. 1.5, -5 (which meant an immediate retry) or 1e3 count as no header.
  • Breaking: APIStatusError.provider is a Provider, Provider.GENERIC by default (it was typed str | None while the resolvers passed the enum).
  • The session no longer turns a parser's ValueError into APIResponseError: parsers raise APIResponseError themselves, so a custom decoder's failure is Failed to decode JSON response and other parser errors surface as they are. Invalid JSON is Failed to decode, a body that does not match the model Failed to validate, in buffered and streamed responses alike.
  • RequestValidationError lists every failing field of the provider's method under its shared name (max_output_tokens, not max_tokens); field stays the first one.
  • When a stream use case's source method declares __stream_terminal__ and the adapter gives no final event, the error is a RuntimeError naming the adapter instead of APIStreamInterruptedError: the parser proved the stream complete, so it was not cut.
  • APIRedirectError's default message is Redirect was not followed., since it is also raised when redirects are off or lead to another origin.
  • Breaking: a datetime in a JSON or form body is sent in ISO 8601 ("2026-01-02T03:04:05Z") instead of a Unix timestamp string, and a timedelta as an ISO 8601 duration ("PT30S") instead of the timestamp of now plus the delta. Query and path values were already ISO 8601; a date or time in the body goes through the same formatter. To keep Unix seconds, set a BaseValueFormatter subclass as __value_formatter__.
  • Breaking: IBodyBuilder.build and BodyNormalizer.normalize / normalize_mapping take the method's formatter; AiohttpSession passes method.value_formatter.
  • Query, path and form values follow one rule (scalar_text): enums as their values, booleans as true/false, dates through the formatter. A naive datetime now raises ValueError in a query or path too, and a value with no text form (such as a class) raises TypeError.
  • BodyNormalizer.MAX_DEPTH is 253, orjson's limit for a body field: a field nested 254 to 256 levels deep raised the encoder's TypeError instead of the documented ValueError.
  • A method without a body (BodyFormat.NONE, the default) whose field is neither a path nor a query parameter raises TypeError at class definition, instead of dropping the field from every request; the aiohttp body builder refuses a non-empty body for NONE with ValueError.
  • OpenAI's CreateResponse and StreamResponse and Anthropic's CreateMessage and StreamMessage set __retryable__ = True: transient failures are retried (a stream only while it opens), as in the official SDKs. Before, client.generation never retried.
  • OpenAIErrorResolver and AnthropicErrorResolver: a failure reported after a 200 (OpenAI's failed response, response.failed or error stream event, Anthropic's error stream event) is never transient; its class is still picked by its code or type.
  • Values the request cannot express raise instead of being dropped or mangled: None in a query list (ValueError), None in a form list (ValueError) and a list inside a form list (TypeError, it was flattened); a path parameter annotated as a list, set, dict or model raises TypeError at class definition, and such a value in an Any field when the request is built (it was sent as its Python repr).
  • Checks moved to class definition: a buffered method whose generic argument is not a class (list[Model], a union) and a BYTES/TEXT stream with __stream_terminal__ raise TypeError unless the method sets its own parser. Before, the first failed after the request was sent and the second was ignored. A TEXT stream checks its charset when it opens, like the Content-Type of SSE, instead of on the first item.
  • IOFile over a non-blocking stream with no data ready raises BlockingIOError (sent as APIRequestError) instead of sending a truncated file.
  • AiohttpSession builds the session's headers for every request instead of copying them into the connection pool once, so a header added after the first request is sent.
  • generation.stream(...) yields a GenerationStream, a Stream subclass, instead of a plain Stream.
  • CompletedEvent.model is required: an adapter that builds the event passes the model.
  • An Anthropic stream builds a real Usage (from message_start and the cumulative message_delta counts) and MessageDelta for the final CompletedEvent. A stream without message_start, or with counts before it, now raises APIResponseError instead of reporting partial counts.

Fixed

  • An OpenAI quota error reported inside a stream (insufficient_quota and the other quota codes) is a QuotaExceededError, as over HTTP 429, instead of a plain APIStatusError.
  • OpenAIErrorResolver recognizes a failed Response by its status alone, as the parser does, so one without object keeps its error.
  • After a failed read, GenerationStream.final() raises the original error again instead of APIStreamInterruptedError: ended without a CompletedEvent; later reads and text() do the same instead of ending quietly.
  • NaN and infinity raise ValueError in every part of the request: a float path parameter was sent as nan, a NaN in an Any query field as the string None, and a form field as nan.
  • A nested model passed to the normalizer is dumped by alias, so its wire names are kept, and enum dict keys are sent as their values (orjson rejected them). Keys that give the same value raise ValueError.
  • A text stream in a body raises a clear TypeError in the normalizer instead of a message about binary data from the body builder.
  • OutputText.logprobs accepts null, which OpenAI sends when log probabilities were not requested; such a response failed validation.

Removed

  • The internal conversion functions they replace: OpenAI's to_usage, refusal, incomplete_reason, raw_incomplete_reason and to_event, Anthropic's to_usage, message_usage and to_stop (its Stop moved to ai_api.adapters).

0.2.0 - 2026-10-31

Added

  • Method headers: __request_headers__ (a mapping or Headers, None by default) is sent with every request of the method; it is exposed as the request_headers property, a new IHeaders collection on every access.
  • Per-call options: send_request and stream on ISession, BaseSession, IClient and BaseClient take keyword-only headers= and timeout=. Both apply to every attempt of the call, retries included.
  • Headers are merged in the order session < method < call < authentication; a call cannot replace the authentication header.
  • timeout is in seconds. For a buffered request it replaces the total of the session's timeout; for a stream, the silence between chunks (sock_read) of stream_timeout. Other limits are kept, and a stream still has no total limit.
  • ai_api.http.HeadersType (a mapping or an IHeaders) and ai_api.session.Timeout.
  • Headers, Headers.add and Headers.build accept another IHeaders collection as well as a mapping. IHeaders is runtime_checkable.
  • ai_api.adapters: adapters convert between shared types and a provider's methods and nothing else. IAdapter / BaseAdapter have to_method(request) and to_response(raw, request); IStreamAdapter / BaseStreamAdapter have to_stream_method(request) and to_events(items, request), which sees the whole stream; ICompositeAdapter / BaseCompositeAdapter have all four.
  • AdapterUseCase, AdapterStreamUseCase and AdapterCompositeUseCase in ai_api.resources: use cases that only orchestrate a session and an adapter. The abstract BaseUseCase classes stay for calls that are not one request and one response.
  • ai_api.response.transform_stream(source, transform): opens a stream and passes its items through a function of the whole stream, closing the transformed stream before the source.
  • GenerationResource(session, adapter) in ai_api.resources: the shared resource of text generation, one class for every provider, with create(request) and stream(request); IGenerationResource is its protocol.
  • GenerationRequest.instructions: instructions given apart from the input, such as a system prompt.
  • OpenAIClient() without a token or a session reads the key from OPENAI_API_KEY; an explicit token wins over it and an empty variable counts as unset.
  • OpenAI Responses API: CreateResponse and StreamResponse in ai_api.providers.openai.methods (POST /v1/responses, with OpenAI's limits on max_output_tokens, temperature, top_p and metadata checked before sending), and Response, its output items, usage and the stream events in ai_api.providers.openai.types. Response.output_text joins the text of the output messages. Items, content parts and events of a type the library does not model yet are kept whole as UnknownOutputItem, UnknownContent and UnknownEvent.
  • OpenAIErrorResolver reads the flat error event of a response stream, so its code and message reach the raised APIStatusError, and picks its class by its code or type (server_is_overloaded → transient ServiceUnavailableError, server_error → InternalServerError, ...), since it arrives after the stream's 200.
  • OpenAIErrorResolver treats every documented exhausted-limit 429 (credit_balance_exhausted, organization and project spend limits, the usage limit, and the insufficient_quota type) as a non-transient QuotaExceededError, not only the insufficient_quota code.
  • Cross-provider contract tests (tests/providers/test_generation_contract.py): the same scenarios for OpenAIClient.generation and AnthropicClient.generation.
  • OpenAIGenerationAdapter in ai_api.providers.openai.adapters: shared generation over the Responses API, for GenerationResource; OpenAI's limits on the request raise RequestValidationError. A buffered response that did not finish (cancelled, in_progress, ...) raises APIResponseError; a failed one is raised by CreateResponse and StreamResponse themselves (see below).
  • incomplete_reason on GenerationResponse and CompletedEvent: why the provider stopped early, an IncompleteReason (MAX_TOKENS, REFUSAL or OTHER); None if it finished. The provider's own reason is in raw_incomplete_reason.
  • Anthropic provider (ai_api.providers.anthropic): AnthropicClient (a token, a ready session or ANTHROPIC_API_KEY; BearerAuth), ANTHROPIC_API, API_VERSION (2026-10-21) and AnthropicErrorResolver: spend caps and spend limits are non-transient QuotaExceededErrors, 529 overloaded_error is a transient ServiceUnavailableError, and a stream's error event is classified by its type.
  • X_API_KEY and ANTHROPIC_VERSION header names in ai_api.http.headers.
  • Anthropic Messages API: CreateMessage and StreamMessage in ai_api.providers.anthropic.methods (POST /v1/messages; both send anthropic-version: 2026-10-21 through VERSION_HEADERS; max_tokens is required, turns are MessageParam TypedDicts and metadata takes only user_id, all checked before sending), and Message with its blocks, usage and the stream events in ai_api.providers.anthropic.types. Message.text joins the text blocks; unknown blocks, deltas and events are kept whole as UnknownBlock, UnknownDelta and UnknownEvent.
  • AnthropicGenerationAdapter in ai_api.providers.anthropic.adapters and AnthropicClient.generation (with default_max_tokens=1024 for requests without max_output_tokens): shared generation over the Messages API. Metadata other than user_id raises RequestValidationError; a stop_reason other than end_turn or stop_sequence sets incomplete_reason; the stream's CompletedEvent comes on message_stop with the counts of message_start and the cumulative message_delta; a message without stop_reason raises APIResponseError.
  • BaseUnknown, by_type and UNKNOWN in ai_api.types (moved from the OpenAI types, now shared by both providers): a pydantic discriminator that keeps a value of an unknown type whole instead of rejecting it.
  • OpenAIClient.generation: a GenerationResource with OpenAIGenerationAdapter, so await client.generation.create(request) and client.generation.stream(request) work with shared types.
  • Wire-contract tests (tests/providers/test_wire_contracts.py): requests of CreateResponse/StreamResponse and CreateMessage/StreamMessage are validated against the providers' SDK-derived JSON schemas (closed, so an unknown field fails), and the documented response bodies and stream events are parsed by the library's types. The schemas and examples are a snapshot in tests/providers/contracts/ (OpenAI SDK 3.41.0, Anthropic SDK 2.3.0), rebuilt from the offline docs dump by python -m tests.providers.contracts.update. New test dependency jsonschema, new dev dependency types-jsonschema.
  • Event matchers in ai_api.types: the IEventMatcher protocol (matches(item) -> bool, for models and decoded JSON alike), BaseMatcher, EventTypes(*types), FieldValues(name, *values), TopLevelError(), DONE (matches DONE_MARKER, the data: [DONE] line) and AnyOf, built with a | b. Matchers compare by value and show what they match.
  • Stream terminals: BaseStreamMethod.__stream_terminal__ (an IEventMatcher, None by default; the stream_terminal property, also on IStreamMethod) names the protocol's last event. The SSE and NDJSON parsers then read the body to its end: a body that ends without the terminal raises APIStreamInterruptedError, an item after it raises APIResponseError, and [DONE] is matched as DONE_MARKER instead of ending the stream. StreamResponse declares response.completed, response.incomplete and response.failed; StreamMessage declares message_stop. Without a terminal nothing changes. A contract test checks that the declared terminal and error event types exist upstream.
  • StreamResponseParser(error_events=...): the matcher of decoded events that are raised through the error resolver, ERROR_EVENTS (EventTypes("error") | TopLevelError()) by default, and the error_events property.
  • BufferedResponseParser(error_responses=...): a matcher of parsed JSON results that are failures; a match is raised through the error resolver with the result in raw.
  • APIStreamInterruptedError (an APITransportError, not transient, with items_received): an open stream broke or ended before its terminal. Stream wraps every transport error raised while iterating in it, with the original as __cause__; nested streams pass it through unchanged.
  • APIStatusError.raw: the parsed object that reported the failure, such as OpenAI's failed Response, or a stream's error event when it fits the item type; None otherwise.
  • Failed OpenAI responses are raised: CreateResponse raises a response with status: "failed", and StreamResponse the response.failed event, as the APIStatusError that OpenAIErrorResolver builds from response.error (with the Response or the event in raw). This is stricter than the official SDK, which returns a failed response as a value.
  • The shared stream contract: AdapterStreamUseCase and AdapterCompositeUseCase take keyword-only terminal=, and then require exactly one event that matches it, as the last one (none: APIStreamInterruptedError; an event after it: APIResponseError). GenerationResource passes GENERATION_TERMINAL (ai_api.types.responses), which matches CompletedEvent, so every provider's generation.stream ends with exactly one CompletedEvent.
  • Tests: cancellation (task.cancel() while opening and while iterating releases the connection, for raw and shared streams of both providers), every two-chunk split of the documented provider streams, hypothesis property tests of the line and SSE decoders, cuts and silence mid-stream, and a close-delimited HTTP/1.1 body cut mid-event. New test dependency hypothesis.
  • Conversations in shared generation: GenerationRequest.input takes a list of Turns (ai_api.types.requests; frozen, unknown fields rejected, Turn.user(...) and Turn.assistant(...)) as well as a text, and GenerationResponse.to_turn() turns an answer into the next request's assistant turn. The list must not be empty and must end with a user turn. OpenAI gets the turns as EasyInputMessage items, Anthropic as messages.
  • Role, IncompleteReason and GenerationEventType (StrEnums in ai_api.enums, re-exported from ai_api).
  • RequestValidationError (ai_api, a ValueError, with provider and the shared field): the generation adapters raise it, before anything is sent, for a shared request that a provider cannot take; a pydantic error behind it is its __cause__.
  • raw_incomplete_reason and refusal on GenerationResponse and CompletedEvent. A refusal is an answer, as in both SDKs: it sets incomplete_reason to IncompleteReason.REFUSAL and refusal to OpenAI's refusal text, or Anthropic's stop_details.explanation (else its category).
  • TokenUsage.cache_read_tokens, cache_write_tokens and reasoning_tokens (parts of the input and output counts; None if not reported), from OpenAI's token details and Anthropic's cache counts and thinking tokens.
  • OutputTokensDetails (thinking_tokens) and output_tokens_details on Anthropic's Usage and MessageDeltaUsage.
  • docs/unification.md: what every shared field becomes for each provider, what is lost, when a request or response raises, and what is not unified; tests/docs/test_unification.py checks it against the shared types and raises every error it lists.

Changed

  • Transports implement _execute(method, *, headers=None, timeout=None) and _open_stream(method, *, headers=None, timeout=None).
  • BaseSession(headers=...) keeps a given IHeaders object as it is instead of copying it into a new Headers; a mapping is still copied.
  • map_stream is built on transform_stream and returns its context manager; its behavior is unchanged.
  • require_token_or_session in ai_api.client.validators is replaced by resolve_token(token, session, env), which also reads the environment. Without a token, a session and the variable, the error now names the variable.
  • A transport error while iterating a stream (a dropped connection, a read timeout) is raised as APIStreamInterruptedError, with the original error as its cause, instead of as that error.
  • StreamResponseParser.is_error_event is replaced by the error_events matcher; the default accepts the same events as before.
  • IResponseParser.parse takes error_resolver after json_loads, and BaseSession passes its own.
  • Shared streams report failures only as exceptions: the generation adapters no longer check the end of a stream themselves; the provider method's terminal and the use case's terminal do.
  • The type of the shared events is a GenerationEventType, and GENERATION_TERMINAL matches GenerationEventType.COMPLETED; the values are the same strings as before.

Removed

  • GenerationRequest.temperature. Sampling parameters are not common to all providers: Anthropic removed temperature, top_p and top_k in API version 2026-10-21. A provider's own method can still declare them.
  • FailedEvent from the shared events: a failure is an exception at every level, so GenerationEvent is TextDeltaEvent | CompletedEvent | OtherEvent.

Fixed

  • LineDecoder no longer adds an empty line at the end of a body whose last \r\n is split between two chunks, which could complete an unfinished server-sent event.

0.1.0 - 2026-10-30

This release reorganizes the package into layers and defines the public API. Almost every import path changes; see Migrating from 0.0.4.

Added

  • Public re-exports. Every package __init__.py has a sorted __all__, and ai_api re-exports the names most code needs: method and type base classes, files, enums, auth, BaseAPI, Headers, Stream, ServerSentEvent, BaseSession, BaseClient, BaseErrorResolver and the whole error tree. import ai_api does not import aiohttp.
  • ai_api.http package for the HTTP primitives: BaseAPI, BearerAuth, APIKeyAuth, Headers, the IAPI/IAuth/IHeaders protocols and Query.
  • Header and media type constants in ai_api.http.headers: RETRY_AFTER, REQUEST_ID, X_REQUEST_ID, JSON_CONTENT_TYPE, EVENT_STREAM_CONTENT_TYPE.
  • Provider.GENERIC, the provider of BaseErrorResolver.
  • This changelog.
  • README sections on the request flow, request body, response parsing, interrupted streams, sessions, adding a provider, resources, writing a transport, type safety, security and design decisions.

Changed

  • Python 3.13 or newer is required (was 3.15). Every module uses from __future__ import annotations.
  • APIError is renamed to APIStatusError.
  • A response body cut off by a lost connection raises the transient APIConnectionError instead of APIResponseError, so buffered requests are retried. A stream cut off mid-way still reaches the caller.
  • APIResponseError moved to ai_api.http.exceptions.response.
  • AiohttpSession(limit=...) is renamed to max_connections=..., and create_session() to get_client().
  • Session arguments after error_resolver are keyword-only, in BaseSession and AiohttpSession.
  • __path_safe__ is renamed to __request_path_safe__.
  • __request_query__ defaults to an empty set and is stored as a frozenset.
  • The method property body_format is renamed to request_body_format.
  • StreamResponseParser options are keyword-only: StreamResponseParser(*, max_line_size, max_event_size, require_event_stream). It no longer takes json_loads or error_resolver.
  • BufferedResponseParser takes no arguments.
  • IResponseParser.parse(method, response, json_loads) and IStreamParser.parse(method, response, json_loads, error_resolver) take all their arguments as required. The response argument is named response, not buffered.
  • Stream(events) is renamed to Stream(items).
  • SSEDecoder.feed() is renamed to decode(), and SSE_DONE moved to ai_api.response.parse.sse.
  • get_header and parse_retry_after moved from the error resolver to ai_api.http.headers.
  • ResponseEvent is renamed to GenerationEvent.
  • Provider.NONE is renamed to Provider.GENERIC.
  • check_session_creds is renamed to require_token_or_session, and the OpenAI validate_session to warn_about_session.
  • BodyFormat and ResponseFormat moved from ai_api.methods.enums to ai_api.enums.

Removed

  • ResponseMode and __response_mode__: buffered and stream methods are told apart by their base class.
  • RETRY_CONDITION; use retry_condition(max_retry_after).
  • The ai_api.client.* sub-packages; their modules moved to the layers below.

Migrating from 0.0.4

Most code only needs from ai_api import .... Old module paths and their new locations:

0.0.4 0.1.0
ai_api.client.api.base ai_api.http.api
ai_api.client.api.protocols, client.auth.protocols, client.headers.protocols ai_api.http.protocols
ai_api.client.api.url.parse ai_api.methods.path
ai_api.client.auth.bearer, client.auth.api_key ai_api.http.auth
ai_api.client.headers.headers, client.headers.names ai_api.http.headers
ai_api.client.exceptions.http ai_api.http.exceptions.status
ai_api.client.exceptions.transport ai_api.http.exceptions.transport (APIResponseError: ai_api.http.exceptions.response)
ai_api.client.exceptions.aiohttp ai_api.http.exceptions.aiohttp
ai_api.client.exceptions.error_resolver.base ai_api.http.exceptions.resolver
ai_api.client.exceptions.error_resolver.protocols ai_api.http.exceptions.protocols
ai_api.methods.enums ai_api.enums
ai_api.methods.resolve ai_api.methods.fields
ai_api.client.response.base ai_api.response.buffered
ai_api.client.response.{aiohttp,protocols,stream} ai_api.response.{aiohttp,protocols,stream}
ai_api.client.response.parse.* ai_api.response.parse.*
ai_api.client.serialization.json ai_api.serialization.json
ai_api.client.serialization.body ai_api.serialization.normalize
ai_api.client.session.{base,aiohttp,loop,protocols} ai_api.session.{base,aiohttp,loop,protocols}
ai_api.client.session.builders.* ai_api.session.body.*
ai_api.client.retry.startegy ai_api.session.retry
ai_api.client.factory.factory ai_api.client.factory
ai_api.client.resources.base ai_api.resources.base
ai_api.client.resources.usecases.base ai_api.resources.usecases
ai_api.client.resources.usecases.protocols ai_api.resources.protocols
ai_api.providers.openai.client.openai ai_api.providers.openai.client
ai_api.providers.openai.client.api.openai ai_api.providers.openai.api
ai_api.providers.openai.client.exceptions.error_resolver.openai ai_api.providers.openai.resolver