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.filesandCompletedEvent.fileslist the files a built-in tool made (a chart the code drew) asProducedFiles, aProviderFilewith itsfilename, thecontainer_idof a code container and thesource_call_idof 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 bydownload:retrieve,delete, a part'sfileandCodeExecution.filesrefuse it withRequestValidationError, 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(andBaseFilesAdapter's) takes the wholeProviderFileinstead of its id, so that a provider downloads aProducedFilefrom its container or refuses it where it has none: a provider changes the parameter and readsfile.id, withcontainer_of(file)for the container. In the test kit,BuiltinCasetakescoded,coded_stream,producedandcode_files(a code execution that made a file, and the files aCodeExecutionreads), andFilesCasetakescontainer_download(the path of a container file's download,Nonefor a provider without containers): a provider adds them to its cases. BuiltinCase.pausedandBuiltinCase.continuedof 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:
WebSearchandCodeExecution(withUserLocation), the two both providers have, andProviderToolfor a provider's own, all in thetools=list beside the functions (request.toolskeeps the functions,request.builtin_toolshas the rest). A response hasserver_tool_calls(ServerToolCall:kind,status,queries,code,error, the provider's items inraw; a failed tool is a call withFAILED, not an exception) andcitations(Citation), a stream hasServerToolCallEventfor the start and the end of a call, andCompletedEventcarries the same two fields.IncompleteReason.PAUSEDis 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_toolsinaiollm.adapters,BuiltinCasefor the shared scenarios (aGenerationCasewithout 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
assistantTurncan carrynative, andto_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 anassistantturn that hasnative, to continue the pause; any otherassistantturn still cannot end it, and an ordinary text answer still gives a plain turn. A provider adapter sendsTurn.nativewhen it is its own, as it does for aToolCallTurn, 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-openaiorpip install aiollm-anthropicinstalls a provider with the core it needs, andpip install aiollm-corethe 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_conversationandcheck_files, are exported fromaiollm.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.testingruns a provider of your own through the scenarios every library provider passes: subclassGenerationContract,FilesContractandClientContract(aiollm.testing.contract) with a case of your wire format.aiollm.testing.extension.check_extension_apilists the imports of a package outside the extension API (nowaiollm/testing/extension_api.json),aiollm.testing.wirecompares generated models with a snapshot of the upstream schemas, andaiollm.testing.echois a whole provider built from the extension API alone, for an API that exists only on the local server; itsEchoClienttypes the arguments of its session, as a provider client does. Thetestingextra now installsjsonschematoo.aiollm.testing, the test kit the library's own tests use, for code built on aiollm, such as a provider of your own:FakeTransportreplays queued responses through the real session,Recorder(inaiollm.testing.aiohttp) is a local server that answers only what a test scripted, and the pytest pluginaiollm.testing.plugingives their fixtures and makes retries instant. Its dependencies come with the newtestingextra.
Changed¶
- Breaking:
Provideris 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 astrmade from the provider's name; the library declares onlyProvider.GENERIC, and each provider package its ownPROVIDER. To migrate, writeaiollm_openai.api.PROVIDER(orProvider("openai")) forProvider.OPENAI,aiollm_anthropic.api.PROVIDER(orProvider("anthropic")) forProvider.ANTHROPIC, andProvider("<name>")for theProvider.GENERICan adapter or resolver of your own set; compare providers with==, notis.ANTHROPIC_VERSION, the header name, moved fromaiollm.http.headerstoaiollm_anthropic.api. - The project moved to the
aiollm-orgGitHub organization: the repository is https://github.com/aiollm-org/aiollm and the documentation is at https://aiollm-org.github.io/aiollm/. The oldGrehBan/aiollmaddresses 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(wasaiollm;import aiollmis unchanged). To migrate, install the provider you use and change its imports:aiollm.providers.openai→aiollm_openai(distributionaiollm-openai),aiollm.providers.anthropic→aiollm_anthropic(distributionaiollm-anthropic). The modules under them keep their names (aiollm.providers.openai.methods→aiollm_openai.methods), and a provider package installs the core it needs.ToolCallleft the extension API as a name ofaiollm.types.responses.generation: a provider takes it fromaiollm.types.requests.generation, where it is defined.
0.14.0 - 2026-11-20¶
Added¶
- OpenAI's Responses API follows
openapi.yamlat commit 76a4810: the request takesbackground_options(BackgroundOptionsParam:completion_windowandcontinuation_id) for abackground: truecall, and a response hasinput_transformations(ReasoningInputTransformation), the reasoning inputs withheld from the model.
Changed¶
- Breaking: the Anthropic types and request parameters follow the
anthropic2.11.0 SDK, which renamed five error objects of the server tool results:BashCodeExecutionToolResultError,CodeExecutionToolResultError,TextEditorCodeExecutionToolResultError,ToolSearchToolResultErrorandWebSearchToolResultErrorare now named with anObjectsuffix (CodeExecutionToolResultErrorObject, ...), inproviders.anthropic.typesandproviders.anthropic.methods.params, andWebSearchToolRequestErrorParamis nowWebSearchToolRequestErrorObjectParam. Their fields are unchanged. Themodelliteral listsclaude-fable-5-2andclaude-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,DeleteFileandDownloadFilein each provider'smethods, 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, sincePOST /filesis not idempotent; listing returns one page per call;DownloadFilestreams the content (Stream.save(path)). See the new Provider files guide. client.filesonOpenAIClientandAnthropicClient: the sameupload,retrieve,list,deleteanddownloadfor every provider, in shared types. An upload returns aStoredFile(ref,filename,size,created_at,expires_atin UTC, the provider's metadata inraw), and itsref, aProviderFile, goes into the new third source ofImagePartandDocumentPart,file=, so a request carries the file's id instead of its base64. AProviderFileof another provider raisesRequestValidationErrorbefore anything is sent.list()goes through every page; OpenAI's uploads areuser_datafiles unlessprovider_options={"purpose": ...}(the newOpenAIFileOptions) says otherwise. New public names:FilesResource,IFilesResource,IFilesClient,IFilesAdapter,BaseFilesAdapter,OpenAIFilesAdapter,AnthropicFilesAdapter,FileUpload,ProviderFile,StoredFile.
Changed¶
- Breaking: a dict (or a model) in a
FORMorMULTIPARTbody 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'sjson_dumpsis no longer used for forms. To keep sending a JSON-encoded field, declare it asstrand passjson.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.runhad returned was dropped silently:asyncio.runcancelled 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 toconcurrency. Tool.from_callable()and@tooltake afunctools.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 withoutself); both raisedTypeErrorbefore. The generated schema now saysadditionalProperties: false, as the arguments were already validated that way, and a strict tool whose callable takes**kwargs, which no strict schema can describe, raisesTypeErrorinstead 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, astool_runner.stream()already did. tool_runner.create()andtool_runner.stream()takein_orderandbuffer_size.in_order=Falseyields eachToolResultas soon as its callback finishes instead of in tool-call order.buffer_sizelets that many finished but unread results wait beyondconcurrency, 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()andtool_runner.stream()takeon_error, which turns the exception of a failed callback (or of serializing its output) into that call'sToolResult.output, so the model reads the failure and the other callbacks go on, for exampleon_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-pyfrom PyPI (>=0.0.5), imported asaiopulse. A callback failure is raised as aCallbackExceptionGroupholding every failure observed before the callbacks stopped, even when there is only one, instead of the first failure alone; handle it withexcept*or read itsfailures.CallbackExceptionGroup,CallbackFailureandCallbackCancelledErrorare re-exported fromaiollm. An iteration oftool_runner.create()still waiting in another task when the iterator is closed ends withStopAsyncIterationinstead ofCancelledError. - 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
concurrencyabove1, synchronous callbacks run at the same time. A callback that must stay in the loop's thread (one that uses ansqlite3connection or other object bound to its thread, or that is not thread-safe) should be anasync 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 itsTaskGroup. It is now aCallbackCancelledErrorfailure in the raisedCallbackExceptionGroup, 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
userturn ofclient.generationcan hold images and PDF documents:Turn.user([...])takes a list ofTextPart,ImagePartandDocumentPart, each image or document given as bytes (sent inline in base64) or as a URL.await ImagePart.load(path)andawait DocumentPart.load(path)read a file in a worker thread. OpenAI getsinput_text,input_imageandinput_fileitems, Anthropictext,imageanddocumentblocks; parts in anassistantturn raiseValidationError. - Added
Tool.from_callableand the@tooldecorator 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 whoseparametersare a Pydantic model's JSON Schema, andToolCall.parse_arguments(Model)validates a call's arguments with the model and returns it, raising the model'sValidationError(aValueError) 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.contentis typedstr | list[ContentPart]instead ofstr, since auserturn can now hold parts. Turns built from a string are unchanged at run time, but code that readsturn.contentas a string no longer type-checks: narrow it first withisinstance(turn.content, str). Anassistantturn is always a string. - The provider types are reproducible:
scripts/generate_provider_types.pyruns aiollm-codegen from thecodegendependency 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_urlorimage_urlof OpenAI's generated parameters, failed with "Request body cannot be encoded as JSON". URLs are now sent as their text. - The documentation of
ToolCallDoneEventsaid 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 itsCompletedEvent. 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.inputtakesToolCallTurns (the model's calls, with its text) andToolResults (call_id,output) next toTurns, asInputItems.GenerationResponse.to_turn()gives aToolCallTurnfor a response with calls, holding the response's own output innative(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.mddescribe tools and the generated provider types. GenerationRequestandclient.generation.create()/stream()taketools(a list ofTool: name, description, JSON Schemaparameters,strict),tool_choice(aToolChoice:AUTO,NONE,REQUIRED, or aForcedToolnaming one tool) andparallel_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 withNONE) are refused before sending. OpenAI's provider options gainincludeandmax_tool_calls.GenerationResponse.tool_callsandCompletedEvent.tool_callslist the model's calls of the request's tools asToolCalls (id,name,argumentsas JSON text;parse_arguments()gives the object and raisesValueErrorfor text that is not one), from OpenAI'sfunction_callitems and Anthropic'stool_useblocks, buffered or streamed.output_text/reasoning_summary/tool_calls(OpenAI) andmessage_text/message_thinking/message_tool_calls(Anthropic) do the same for the providers' own responses.client.generation.stream()yieldsToolCallStartEvent(call_id,name),ToolCallDeltaEvent(a piece of the arguments) andToolCallDoneEvent(the wholeToolCall, before the response ends) for each tool call, from OpenAI's function call items and Anthropic'stool_useblocks.CompletedEventcarriesnative, the stream's own output put together from its events (Anthropic's thinking with its signature among it), andto_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.paramsandaiollm.providers.anthropic.methods.params. Names follow the schemas, so code that imports provider types migrates: OpenAIOutputText→OutputTextContent,OutputRefusal→RefusalContent,OutputTextDeltaEvent→ResponseTextDeltaEvent,ResponseStateEvent→ResponseCompletedEvent,ResponseIncompleteEventand the others of its kind,UnknownOutputItem,UnknownContentandUnknownEvent→UnknownVariant; AnthropicMessageStartEvent,ContentBlockDeltaEventand the other events →RawMessageStartEvent,RawContentBlockDeltaEvent, ...,MessageDelta→Delta,StopDetails→RefusalStopDetails,UnknownBlock,UnknownDeltaandUnknownEvent→UnknownVariant, and apingis anUnknownVariant;MessageParam,ResponseParams,Reasoning,TextConfigand the other requestTypedDicts give way to the generated models, which take dicts at run time and refuse unknown keys.Response.output_text,Response.reasoning_summary,Message.textandMessage.thinkingare gone: OpenAI'soutput_textis a schema field the API leaves out, so useoutput_text()andreasoning_summary()fromaiollm.providers.openai.adaptersandmessage_text()andmessage_thinking()fromaiollm.providers.anthropic.adapters. The types follow the schemas strictly: OpenAI'susageneeds itsinput_tokens_detailsandoutput_tokens_detailsand anoutput_textpart itsannotationsandlogprobs, Anthropic'smessage_deltaitsusage, and an Anthropic turn may be asystemone. The early checks the schemas do not state stay: OpenAI'smetadatalimits, and Anthropic's at least one turn,max_tokensfrom 0 andmetadata.user_idup to 512 characters. - Breaking:
Turnhas atypefield ("text"), which shows in itsreprandmodel_dump(); a dict withouttypestill reads as aTurn.GenerationResponse.to_turn()returnsTurn | ToolCallTurnand raisesValueErrorfor a response with calls that stopped early. The adapters'input_conversiontakes a list ofInputItems instead ofTurns, so a custom conversion handles the new items;GenerationRequest.inputand theinputofcreate()/stream()are typedstr | Sequence[InputItem], so alist[Turn]still type-checks.ToolCallmoved toaiollm.types.requests(it is still inaiollm). - An Anthropic message that stops with
stop_reason: "tool_use"now finishes normally:incomplete_reasonandraw_incomplete_reasonareNone, as for acompletedOpenAI response with function calls, since the model is waiting for the tool results.
0.9.0 - 2026-11-05¶
Added¶
GenerationRequestandclient.generation.create()/stream()takeeffort=, anEffort(low,medium,high,xhigh,max): how much work the model puts into the response, sent as OpenAI'sreasoning.effortand Anthropic'soutput_config.effort. Left out, nothing is sent and the model's default applies.CreateResponse/StreamResponsegainreasoning(Reasoning) andCreateMessage/StreamMessageoutput_config(OutputConfig), as the providers' schemas define them.GenerationRequestandclient.generationtakeoutput_schema=, a JSON Schema the responsetextthen follows as JSON: OpenAI'stext.format(json_schema,strict: true, named byOpenAIGenerationAdapter(schema_name=...),"output"by default) and Anthropic'soutput_config.format. The schema is sent as it is.CreateResponse/StreamResponsegaintext(TextConfig) and Anthropic'sOutputConfigitsformat;JSONSchemaandJSONValueare inaiollm.types.requests.GenerationResponse.reasoningandCompletedEvent.reasoninghold a summary of the model's reasoning, andstream()yields it asReasoningDeltaEvents, when the request asks for one throughprovider_options: OpenAI's{"reasoning": {"summary": "auto"}}(OpenAIReasoningOptions, merged with the sharedeffort) or Anthropic's{"thinking": {"type": "adaptive", "display": "summarized"}}(thinking, a new field ofCreateMessage). OpenAI'sReasoningItemandReasoningSummaryTextDeltaEventand Anthropic'sThinkingBlockandThinkingDeltaare modeled.
Changed¶
- Breaking:
GenerationRequest.metadatais replaced byend_user_id, an opaque id of the end user (a hash, never personal data) that both providers use to detect abuse: OpenAI'ssafety_identifier(up to 128 characters, now a field ofCreateResponse) and Anthropic'smetadata.user_id(up to 512). The sharedmetadatameant different things (free-form pairs stored by OpenAI, onlyuser_idat Anthropic). Passend_user_id=...where you passedmetadata={"user_id": ...}, and OpenAI's free-form pairs asprovider_options={"metadata": {...}}(OpenAIGenerationOptions). - Breaking: a stream's reasoning summary pieces (OpenAI's
response.reasoning_summary_text.delta, Anthropic's non-emptythinking_delta) come asReasoningDeltaEventinstead ofOtherEvent, andGenerationEventTypehasREASONING_DELTA; code that matched them asOtherEventmatchesReasoningDeltaEventnow. OpenAI'sreasoningoutput items and Anthropic'sthinkingblocks areReasoningItemandThinkingBlock, no longerUnknownOutputItemandUnknownBlock. client.generationofAnthropicClientsendsmax_tokens16000, not 1024, when a request has nomax_output_tokens: thinking is always on for the Claude 5.x models and counts towardmax_tokens, so 1024 could end a reply in its thinking, with little or no text. Passdefault_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,b1andrc1pre-releases may come before it. client.generation.create()andstream()takeprovider_options=, a provider's own fields of that call that the shared request does not hold:store,previous_response_id,temperatureandtop_pfor OpenAI (OpenAIGenerationOptions),stop_sequencesfor Anthropic (AnthropicGenerationOptions). The options are aTypedDictof the client's provider, so a wrong key or value is a type error; at run time an unknown key or an invalid value raisesRequestValidationErrorbefore anything is sent. Code typed asIGenerationClientcannot pass them.
Changed¶
- Breaking:
GenerationResourcetakes 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 anIGenerationAdapter, which addswith_options(options, /) -> SelftoICompositeAdapter: a generation adapter of your own without provider options adds awith_options(self, options: NoProviderOptions, /) -> Selfthat callschecked_options(options, NoProviderOptions, self.provider)(fromaiollm.adapters.validation), so no key is dropped silently, and returnsself.NoProviderOptionsis closed: only{}matches it.CallOptionsis now closed (PEP 728): a**options: Unpack[CallOptions]takes no other key, andtyping-extensionsis a direct dependency.
Fixed¶
- A retry policy's
retry_ifandbackoffare no longer called after the last attemptmax_attemptsallows, when no retry can follow: abackoffthat counts retries or aretry_ifthat logs counted one call too many. With adeadline,backoffis 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_optionsthat aGenerationResourceadapter now needs (type checkers refused the example without it), and the design guide's limitations say thatclient.generationis 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 longestRetry-Afterworth waiting for, the backoff (FullJitterBackoffby default, or any callable that takes aRetryState) andretry_if, which can refuse a transient error. Give one to a session or a client asretry_policy=, or to a singlesend_requestorstreamcall 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. Ifretry_iforbackofffails, its error keeps the request's error as its__cause__. client.generation.create()andstream()take the options of the call,headers=,timeout=andretry_policy=, assend_requestdoes, 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 ofaiollm.resourcespass them on too, andaiollm.session.CallOptionsnames them for**options.
Changed¶
- Breaking:
IUseCase.__call__andIStreamUseCase.stream, and the abstract methods ofBaseUseCase,BaseStreamUseCaseandBaseCompositeUseCase, take the options of the call as**options: Unpack[CallOptions]. A use case of your own adds that parameter and passes**optionstosession.send_requestorsession.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), withadapter_factory=for an adapter that takes options from the client.BaseProviderClientbuilds 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_typesandBaseProviderClient.adapter()are removed.
Removed¶
- Breaking: Sessions and provider clients no longer take
max_retry_afterandretry_deadline, and sessions no longer have attributes of those names; passretry_policy=RetryPolicy(max_retry_after=..., deadline=...)instead and readsession.retry_policy. The DEBUG record of aRetry-Afterabove the limit now comes from theaiollm.session.retry.runnerlogger instead ofaiollm.session.retry. - Breaking: The import package and distribution are now named
aiollm; change imports fromai_apitoaiollmand dependency declarations fromai-apitoaiollm.
Fixed¶
- The README's quick start and the methods guide still said that a field set to
Noneis not sent. Since 0.5.0 a field leftMISSINGis not sent, andNoneis sent asnull; 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_apiand 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_templateon 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, soIAPIMethodandIStreamMethod) require arequest_path_templateproperty, the path as declared with its placeholders kept. Methods derived fromBaseAPIMethodorBaseStreamMethodhave 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, andNoneis sent asnull. Until nowNonemeant both, so a request could not sendnull. A field is declared after the API's schema:x: int | MISSING = MISSING(left out until given),x: int | None | MISSING = MISSING(left out, ornull),x: int | None(required, may benull). - Breaking: a method field that defaults to
None, or holds a model with such a field anywhere in its type, raisesTypeErroronce 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 sendnullfor a value nobody set. Dataclasses (standard and Pydantic's),NamedTuples andNewTypes in a field's type are looked into as models are, and a default factory that givesNonecounts as aNonedefault. Recursive type aliases are walked once. - Breaking:
MISSINGgoes in a field's type only together with theMISSINGdefault, and the other way round; otherwise the class raisesTypeError, since a required field that takesMISSINGcould be left out.AnytakesMISSING. MISSINGas an item of a list or a value of a dict raisesValueErrorwhen the request is built, instead of an encoder error about an unknown type. Replacelimit: int | None = Nonewithlimit: int | MISSING = MISSING(from pydantic import MISSING), and describe nested request data with aTypedDict(NotRequiredkeys are left out). Fields withexclude=Trueare not checked.- Breaking:
Nonein a query parameter or a form field raisesValueErrorinstead of being skipped: neither has anull. - Breaking:
GenerationRequest.instructions,max_output_tokensandmetadatadefault toMISSINGand take noNone; leave a field out instead.generation.create()andstream()showT | MISSINGin their keyword arguments. - The OpenAI and Anthropic request fields follow the providers'
schemas: OpenAI's optional fields take
None(sent asnull), Anthropic'ssystem,metadataandstop_sequencesdo not. - Breaking: a model put into a request body at run time, such as
a response item sent back, sends its
Nonefields asnull; until now they were dropped. Dump it withmodel_dump(by_alias=True, exclude_unset=True)to send exactly the fields the response had. - Shared requests validate assignments:
request.instructions = NoneraisesValidationError, as the constructor does. - A type with a
PlainSerializeris not looked into forNonedefaults: the serializer decides what is sent.
Added¶
- A path parameter that defaults to
MISSINGraisesTypeErrorat class definition. - The wire-contract tests check every provider method field against
the request schema:
Nonewherenullis allowed,MISSINGonly where the field is optional.
Fixed¶
AnthropicGenerationAdaptergivenmetadata=None(throughmodel_copy, which validates nothing) raised a bareTypeError; it raisesRequestValidationError, as for the other fields.
0.4.4 - 2026-11-02¶
Added¶
- Logging through the standard
loggingmodule, underai_apiand one logger per module that logs, with only aNullHandleronai_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
GandLOGrules, 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 cancelledopen) 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
ThreadWorkfailure. - 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.streamcloses 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.finishis a coroutine and takesblocking=; both are internal helpers oftypes/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.ymlpublishes it frommaster. [project.urls]inpyproject.toml: documentation, repository and changelog.
Changed¶
README.mdis 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 whichtests/docs/test_examples.py(wastest_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
toolsor other parameters they do not list; a text stream in a method is aValidationErrorat creation;APIStatusErroralso covers in-band failures below 400.
0.4.1 - 2026-11-02¶
Changed¶
StreamFiletakes ownership of its source: the upload closes it, byaclose()elseclose(), 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 raisesRuntimeErroron a second call at once.- The body builder opens every upload while it builds the body, so an
open()that raises is anAPIRequestErrorbefore anything is sent.
Removed¶
- The
aiofilesdependency (and thetypes-aiofilesdev stub).PathFileandStream.saveopen, read, write and close files in a worker thread themselves.
Fixed¶
- A
PathFilewhose 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. StreamFiledid not close the source it was given.- A cancelled
IOFileread let go of the stream while itsread()still ran in the worker thread, so the retry seeked and read under it; the next read now waits for that call. Likewise a cancelledPathFileread orStream.savewrite 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 withextra="allow". The provider response types derive from it, so the fields the library does not model are kept inmodel_extra, reached throughraw(response.raw.model_extra["service_tier"]).ChunkedFile(ai_api,ai_api.types): the base ofPathFileandIOFile, for a source of your own read piece by piece.MAX_LINE_SIZEandMAX_EVENT_SIZE(ai_api.response.parse.stream): the default stream limits.
Changed¶
- Breaking:
StreamResponseParserlimits a line and the data of an SSE event to 32 Mi characters by default (MAX_LINE_SIZE,MAX_EVENT_SIZE); a longer one raisesAPIResponseError, andNonelifts 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
APIResponseErrortoo, where it raised theAPIStatusErrorof the error. - Breaking:
IBodyBuilder.build()takes a keyword-onlyuploads(contextlib.AsyncExitStack), the stack of the attempt, on which the upload readers are registered;AiohttpStreamResponsetakes it as well and closes it with the response. - Breaking:
MAX_DEPTHmoved fromai_api.serialization.normalizetoai_api.serialization.traversal, withguard_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, byaclose()if it has one, else byclose()(awaited when its result is awaitable). A source that fails to close raisesAPIRequestError.- 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 (
docsdependency group).
Fixed¶
- A method field holding a value that contains itself (through
Any, a list, a dict or a nested model) ended inRecursionErrorwhen the method was created; it is aValidationErrornow, as a field nested deeper thanMAX_DEPTHis. - A retryable method with a field nested exactly
MAX_DEPTHdeep raisedValueErrorfromretryable: 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 raisesAPIRequestErrornow. - A
chunk_sizebelow one sent an empty file (read(0)givesb""); it raisesValueErrornow. - An SSE
retryfield with more digits than Python turns into a number (4300 by default) raised a bareValueErrorfrom the stream; it is anAPIResponseErrornow.
0.3.0 - 2026-11-01¶
Added¶
IValueFormatterandBaseValueFormatter(ai_api,ai_api.serialization): a method's__value_formatter__(propertyvalue_formatter, also onIBaseMethod) 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'sPlainSerializer.BaseProviderClient(ai_api,ai_api.client): what a provider client shares, from itsprovider,session_factory,api_key_env,auth_headersandadapter_types(every adapter class it builds, one per shared resource);OpenAIClientandAnthropicClientare 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 inadapter_types.SessionMismatchWarning(ai_api), aUserWarning: 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, witherror_resolver, andSessionFactoryare exported fromai_api.session; breaking:SessionFactorymoved fromai_api.client.factorytoai_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 matches1), read a model's fields but not its properties (a property that raised broke the stream), andEventTypes("x")equalsFieldValues("type", "x");EventTypes.typesis a view ofvalues. A single matcher inAnyOfshows asAnyOf(x), and a protocol-only matcher may stand on the left of|. - Breaking: a
ServerSentEventitem whose data is JSON goes througherror_events, so an error in it raises instead of being yielded, andServerSentEvent.retrykeeps the last value the stream set, asiddoes (the HTML standard applies both at once). - Breaking:
GenerationRequestrefuses an emptymodelor textinputbefore anything is sent;BaseAPIrefuses credentials inbase_url; a payload model (BaseAPIType) with a field of a type Pydantic cannot validate fails at class definition (only therawof 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
dictsubclass, raisesTypeErrorinstead of being dumped lazily.Annotatedmembers of a union are unwrapped by the path and query checks, soAnnotated[dict, ...] | Noneis refused as a query field. - A path without placeholders unescapes
{{/}}as one with them does;APIKeyAuthdefaults to theX_API_KEYconstant; anInputFilefield explains that astris not taken, and a path-like thatPath()rejects is a validation error. typing-extensions,aresponsesandisortare no longer dependencies.- Ruff checks cyclomatic complexity (
C90,max-complexity = 10, the mccabe default; a lower limit would flag flatmatchdispatchers);BodyNormalizer._normalizehands streams and containers to helpers of their own to stay under it, with the same behaviour. - Tests: the local
Recorderfails 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_statusesandclassify_status: a provider sets its table of in-band codes and types and overrides the classification of a status;classifykeeps an in-band failure non-transient for every resolver.ContentTooLargeErrorfor HTTP 413 (Anthropic'srequest_too_largewas a plainAPIStatusError).CompletedEvent.provider, as onGenerationResponse; every adapter has aprovider(PROVIDERof its package,Provider.GENERICoutside the library).Stream.items_received: how many items a stream has given.transform_stream(..., stream_type=...)yields aStreamsubclass built on the transformed items, whichGenerationResourceuses for itsGenerationStream.- Conversions:
ai_api.adapters.IConversion[SourceT, TargetT](a protocol of__call__(source, /), so a plain function fits) and its ABCBaseConversion, for pure value conversions between a provider's types and the shared ones;ai_api.adapters.Stopholds what a stop conversion returns (incomplete_reason,raw_incomplete_reason,refusal). OpenAIGenerationAdapterandAnthropicGenerationAdaptertakeinput_conversion=,usage_conversion=andstop_conversion=keyword arguments (defaults: each provider'sInputConversion,UsageConversionandStopConversion), so one can be swapped without subclassing the adapter. A response and a stream go through the same conversions.tests/docs/test_unification.pychecks that every field ofdocs/unification.mdis filled by a conversion that every adapter has, or is listed as taken as is.generation.create(...)andgeneration.stream(...)take the fields ofGenerationRequestas keyword arguments, as the providers' SDKs do (create(model="...", input="Hi")), or a readyGenerationRequest; passing both raisesTypeError.IGenerationResourcehas the same overloads.GenerationStream(ai_api.resources):generation.stream(...)yields it. Besides iterating every event,events.text()gives the text deltas andawait events.final()reads to the end and returns theCompletedEvent; whatever read the stream, theCompletedEventis kept.CompletedEventcarries the response'sid,model(required) and wholetext, from OpenAI's terminal event and from Anthropic'smessage_startand text deltas.IGenerationClient[RawT = Any, RawItemT = Any](ai_api.resources): a client with a read-onlygeneration;OpenAIClientandAnthropicClientmatch it.OpenAIClient(token, **session_kwargs)andAnthropicClient(token, **session_kwargs)pass every keyword argument ofAiohttpSessionto the session built from the token, typed byai_api.session.aiohttp.AiohttpSessionOptions; withsession=they raiseValueError.BaseAPIType.__upstream_schema__: the name of the upstream schema definition a provider model mirrors (several names, or()for none).tests/providers/test_wire_contracts.pyrequires it on every provider model and checks each modeled field against that definition: it exists upstream, acceptsnullwhere 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,IGenerationResourceandIGenerationClient.
Changed¶
- Breaking: a concrete adapter must set
provider, andCompletedEventrequires it. - Breaking: OpenAI's
ERROR_EVENTSisRESPONSE_ERROR_EVENTS, so it is not mistaken for the parser's default of the same name; the module-levelwarn_about_sessionfunctions are now the classmethodBaseProviderClient.warn_about_session, whose second warning names the headers the provider takes. - Leaving a client's
async withcalls the session's__aexit__, as entering calls its__aenter__, instead ofclose(). - Breaking: 529 is no longer transient in
BaseErrorResolver: it is Anthropic's own status, andAnthropicErrorResolverkeeps classifying it as a transientServiceUnavailableError. - Breaking: only a certificate that fails verification
(
ClientConnectorCertificateError,ServerFingerprintMismatch) raisesAPITLSError; another SSL error, such as a handshake that breaks off, is a transientAPIConnectionError, retried as the official SDKs do. - Breaking:
Retry-Afteris read as RFC 9110 defines it, whole seconds in ASCII digits or an HTTP date.1.5,-5(which meant an immediate retry) or1e3count as no header. - Breaking:
APIStatusError.provideris aProvider,Provider.GENERICby default (it was typedstr | Nonewhile the resolvers passed the enum). - The session no longer turns a parser's
ValueErrorintoAPIResponseError: parsers raiseAPIResponseErrorthemselves, so a custom decoder's failure isFailed to decode JSON responseand other parser errors surface as they are. Invalid JSON isFailed to decode, a body that does not match the modelFailed to validate, in buffered and streamed responses alike. RequestValidationErrorlists every failing field of the provider's method under its shared name (max_output_tokens, notmax_tokens);fieldstays the first one.- When a stream use case's source method declares
__stream_terminal__and the adapter gives no final event, the error is aRuntimeErrornaming the adapter instead ofAPIStreamInterruptedError: the parser proved the stream complete, so it was not cut. APIRedirectError's default message isRedirect 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 aBaseValueFormattersubclass as__value_formatter__. - Breaking:
IBodyBuilder.buildandBodyNormalizer.normalize/normalize_mappingtake the method's formatter;AiohttpSessionpassesmethod.value_formatter. - Query, path and form values follow one rule (
scalar_text): enums as their values, booleans astrue/false, dates through the formatter. A naive datetime now raisesValueErrorin a query or path too, and a value with no text form (such as a class) raisesTypeError. BodyNormalizer.MAX_DEPTHis 253, orjson's limit for a body field: a field nested 254 to 256 levels deep raised the encoder'sTypeErrorinstead of the documentedValueError.- A method without a body (
BodyFormat.NONE, the default) whose field is neither a path nor a query parameter raisesTypeErrorat class definition, instead of dropping the field from every request; the aiohttp body builder refuses a non-empty body forNONEwithValueError. - OpenAI's
CreateResponseandStreamResponseand Anthropic'sCreateMessageandStreamMessageset__retryable__ = True: transient failures are retried (a stream only while it opens), as in the official SDKs. Before,client.generationnever retried. OpenAIErrorResolverandAnthropicErrorResolver: a failure reported after a 200 (OpenAI'sfailedresponse,response.failedorerrorstream event, Anthropic'serrorstream 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:
Nonein a query list (ValueError),Nonein 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 raisesTypeErrorat class definition, and such a value in anAnyfield when the request is built (it was sent as its Pythonrepr). - Checks moved to class definition: a buffered method whose generic
argument is not a class (
list[Model], a union) and aBYTES/TEXTstream with__stream_terminal__raiseTypeErrorunless the method sets its own parser. Before, the first failed after the request was sent and the second was ignored. ATEXTstream checks its charset when it opens, like theContent-Typeof SSE, instead of on the first item. IOFileover a non-blocking stream with no data ready raisesBlockingIOError(sent asAPIRequestError) instead of sending a truncated file.AiohttpSessionbuilds 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 aGenerationStream, aStreamsubclass, instead of a plainStream.CompletedEvent.modelis required: an adapter that builds the event passes the model.- An Anthropic stream builds a real
Usage(frommessage_startand the cumulativemessage_deltacounts) andMessageDeltafor the finalCompletedEvent. A stream withoutmessage_start, or with counts before it, now raisesAPIResponseErrorinstead of reporting partial counts.
Fixed¶
- An OpenAI quota error reported inside a stream (
insufficient_quotaand the other quota codes) is aQuotaExceededError, as over HTTP 429, instead of a plainAPIStatusError. OpenAIErrorResolverrecognizes a failedResponseby its status alone, as the parser does, so one withoutobjectkeeps its error.- After a failed read,
GenerationStream.final()raises the original error again instead ofAPIStreamInterruptedError: ended without a CompletedEvent; later reads andtext()do the same instead of ending quietly. - NaN and infinity raise
ValueErrorin every part of the request: afloatpath parameter was sent asnan, a NaN in anAnyquery field as the stringNone, and a form field asnan. - 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
TypeErrorin the normalizer instead of a message about binary data from the body builder. OutputText.logprobsacceptsnull, 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_reasonandto_event, Anthropic'sto_usage,message_usageandto_stop(itsStopmoved toai_api.adapters).
0.2.0 - 2026-10-31¶
Added¶
- Method headers:
__request_headers__(a mapping orHeaders,Noneby default) is sent with every request of the method; it is exposed as therequest_headersproperty, a newIHeaderscollection on every access. - Per-call options:
send_requestandstreamonISession,BaseSession,IClientandBaseClienttake keyword-onlyheaders=andtimeout=. 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.
timeoutis in seconds. For a buffered request it replaces the total of the session'stimeout; for a stream, the silence between chunks (sock_read) ofstream_timeout. Other limits are kept, and a stream still has no total limit.ai_api.http.HeadersType(a mapping or anIHeaders) andai_api.session.Timeout.Headers,Headers.addandHeaders.buildaccept anotherIHeaderscollection as well as a mapping.IHeadersisruntime_checkable.ai_api.adapters: adapters convert between shared types and a provider's methods and nothing else.IAdapter/BaseAdapterhaveto_method(request)andto_response(raw, request);IStreamAdapter/BaseStreamAdapterhaveto_stream_method(request)andto_events(items, request), which sees the whole stream;ICompositeAdapter/BaseCompositeAdapterhave all four.AdapterUseCase,AdapterStreamUseCaseandAdapterCompositeUseCaseinai_api.resources: use cases that only orchestrate a session and an adapter. The abstractBaseUseCaseclasses 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)inai_api.resources: the shared resource of text generation, one class for every provider, withcreate(request)andstream(request);IGenerationResourceis 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 fromOPENAI_API_KEY; an explicit token wins over it and an empty variable counts as unset.- OpenAI Responses API:
CreateResponseandStreamResponseinai_api.providers.openai.methods(POST /v1/responses, with OpenAI's limits onmax_output_tokens,temperature,top_pand metadata checked before sending), andResponse, its output items, usage and the stream events inai_api.providers.openai.types.Response.output_textjoins the text of the output messages. Items, content parts and events of a type the library does not model yet are kept whole asUnknownOutputItem,UnknownContentandUnknownEvent. OpenAIErrorResolverreads the flaterrorevent of a response stream, so its code and message reach the raisedAPIStatusError, and picks its class by its code or type (server_is_overloaded→ transientServiceUnavailableError,server_error→InternalServerError, ...), since it arrives after the stream's 200.OpenAIErrorResolvertreats every documented exhausted-limit 429 (credit_balance_exhausted, organization and project spend limits, the usage limit, and theinsufficient_quotatype) as a non-transientQuotaExceededError, not only theinsufficient_quotacode.- Cross-provider contract tests (
tests/providers/test_generation_contract.py): the same scenarios forOpenAIClient.generationandAnthropicClient.generation. OpenAIGenerationAdapterinai_api.providers.openai.adapters: shared generation over the Responses API, forGenerationResource; OpenAI's limits on the request raiseRequestValidationError. A buffered response that did not finish (cancelled,in_progress, ...) raisesAPIResponseError; a failed one is raised byCreateResponseandStreamResponsethemselves (see below).incomplete_reasononGenerationResponseandCompletedEvent: why the provider stopped early, anIncompleteReason(MAX_TOKENS,REFUSALorOTHER);Noneif it finished. The provider's own reason is inraw_incomplete_reason.- Anthropic provider (
ai_api.providers.anthropic):AnthropicClient(a token, a ready session orANTHROPIC_API_KEY;BearerAuth),ANTHROPIC_API,API_VERSION(2026-10-21) andAnthropicErrorResolver: spend caps and spend limits are non-transientQuotaExceededErrors, 529overloaded_erroris a transientServiceUnavailableError, and a stream'serrorevent is classified by its type. X_API_KEYandANTHROPIC_VERSIONheader names inai_api.http.headers.- Anthropic Messages API:
CreateMessageandStreamMessageinai_api.providers.anthropic.methods(POST /v1/messages; both sendanthropic-version: 2026-10-21throughVERSION_HEADERS;max_tokensis required, turns areMessageParamTypedDicts andmetadatatakes onlyuser_id, all checked before sending), andMessagewith its blocks, usage and the stream events inai_api.providers.anthropic.types.Message.textjoins the text blocks; unknown blocks, deltas and events are kept whole asUnknownBlock,UnknownDeltaandUnknownEvent. AnthropicGenerationAdapterinai_api.providers.anthropic.adaptersandAnthropicClient.generation(withdefault_max_tokens=1024for requests withoutmax_output_tokens): shared generation over the Messages API. Metadata other thanuser_idraisesRequestValidationError; astop_reasonother thanend_turnorstop_sequencesetsincomplete_reason; the stream'sCompletedEventcomes onmessage_stopwith the counts ofmessage_startand the cumulativemessage_delta; a message withoutstop_reasonraisesAPIResponseError.BaseUnknown,by_typeandUNKNOWNinai_api.types(moved from the OpenAI types, now shared by both providers): a pydantic discriminator that keeps a value of an unknowntypewhole instead of rejecting it.OpenAIClient.generation: aGenerationResourcewithOpenAIGenerationAdapter, soawait client.generation.create(request)andclient.generation.stream(request)work with shared types.- Wire-contract tests (
tests/providers/test_wire_contracts.py): requests ofCreateResponse/StreamResponseandCreateMessage/StreamMessageare 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 intests/providers/contracts/(OpenAI SDK 3.41.0, Anthropic SDK 2.3.0), rebuilt from the offline docs dump bypython -m tests.providers.contracts.update. New test dependencyjsonschema, new dev dependencytypes-jsonschema. - Event matchers in
ai_api.types: theIEventMatcherprotocol (matches(item) -> bool, for models and decoded JSON alike),BaseMatcher,EventTypes(*types),FieldValues(name, *values),TopLevelError(),DONE(matchesDONE_MARKER, thedata: [DONE]line) andAnyOf, built witha | b. Matchers compare by value and show what they match. - Stream terminals:
BaseStreamMethod.__stream_terminal__(anIEventMatcher,Noneby default; thestream_terminalproperty, also onIStreamMethod) 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 raisesAPIStreamInterruptedError, an item after it raisesAPIResponseError, and[DONE]is matched asDONE_MARKERinstead of ending the stream.StreamResponsedeclaresresponse.completed,response.incompleteandresponse.failed;StreamMessagedeclaresmessage_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 theerror_eventsproperty.BufferedResponseParser(error_responses=...): a matcher of parsed JSON results that are failures; a match is raised through the error resolver with the result inraw.APIStreamInterruptedError(anAPITransportError, not transient, withitems_received): an open stream broke or ended before its terminal.Streamwraps 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 failedResponse, or a stream's error event when it fits the item type;Noneotherwise.- Failed OpenAI responses are raised:
CreateResponseraises a response withstatus: "failed", andStreamResponsetheresponse.failedevent, as theAPIStatusErrorthatOpenAIErrorResolverbuilds fromresponse.error(with theResponseor the event inraw). This is stricter than the official SDK, which returns a failed response as a value. - The shared stream contract:
AdapterStreamUseCaseandAdapterCompositeUseCasetake keyword-onlyterminal=, and then require exactly one event that matches it, as the last one (none:APIStreamInterruptedError; an event after it:APIResponseError).GenerationResourcepassesGENERATION_TERMINAL(ai_api.types.responses), which matchesCompletedEvent, so every provider'sgeneration.streamends with exactly oneCompletedEvent. - 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 dependencyhypothesis. - Conversations in shared generation:
GenerationRequest.inputtakes a list ofTurns (ai_api.types.requests; frozen, unknown fields rejected,Turn.user(...)andTurn.assistant(...)) as well as a text, andGenerationResponse.to_turn()turns an answer into the next request'sassistantturn. The list must not be empty and must end with auserturn. OpenAI gets the turns asEasyInputMessageitems, Anthropic asmessages. Role,IncompleteReasonandGenerationEventType(StrEnums inai_api.enums, re-exported fromai_api).RequestValidationError(ai_api, aValueError, withproviderand the sharedfield): 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_reasonandrefusalonGenerationResponseandCompletedEvent. A refusal is an answer, as in both SDKs: it setsincomplete_reasontoIncompleteReason.REFUSALandrefusalto OpenAI's refusal text, or Anthropic'sstop_details.explanation(else itscategory).TokenUsage.cache_read_tokens,cache_write_tokensandreasoning_tokens(parts of the input and output counts;Noneif not reported), from OpenAI's token details and Anthropic's cache counts and thinking tokens.OutputTokensDetails(thinking_tokens) andoutput_tokens_detailson Anthropic'sUsageandMessageDeltaUsage.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.pychecks 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 givenIHeadersobject as it is instead of copying it into a newHeaders; a mapping is still copied.map_streamis built ontransform_streamand returns its context manager; its behavior is unchanged.require_token_or_sessioninai_api.client.validatorsis replaced byresolve_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_eventis replaced by theerror_eventsmatcher; the default accepts the same events as before.IResponseParser.parsetakeserror_resolverafterjson_loads, andBaseSessionpasses 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
terminaldo. - The
typeof the shared events is aGenerationEventType, andGENERATION_TERMINALmatchesGenerationEventType.COMPLETED; the values are the same strings as before.
Removed¶
GenerationRequest.temperature. Sampling parameters are not common to all providers: Anthropic removedtemperature,top_pandtop_kin API version2026-10-21. A provider's own method can still declare them.FailedEventfrom the shared events: a failure is an exception at every level, soGenerationEventisTextDeltaEvent | CompletedEvent | OtherEvent.
Fixed¶
LineDecoderno longer adds an empty line at the end of a body whose last\r\nis 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__.pyhas a sorted__all__, andai_apire-exports the names most code needs: method and type base classes, files, enums, auth,BaseAPI,Headers,Stream,ServerSentEvent,BaseSession,BaseClient,BaseErrorResolverand the whole error tree.import ai_apidoes not import aiohttp. ai_api.httppackage for the HTTP primitives:BaseAPI,BearerAuth,APIKeyAuth,Headers, theIAPI/IAuth/IHeadersprotocols andQuery.- 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 ofBaseErrorResolver.- 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. APIErroris renamed toAPIStatusError.- A response body cut off by a lost connection raises the transient
APIConnectionErrorinstead ofAPIResponseError, so buffered requests are retried. A stream cut off mid-way still reaches the caller. APIResponseErrormoved toai_api.http.exceptions.response.AiohttpSession(limit=...)is renamed tomax_connections=..., andcreate_session()toget_client().- Session arguments after
error_resolverare keyword-only, inBaseSessionandAiohttpSession. __path_safe__is renamed to__request_path_safe__.__request_query__defaults to an empty set and is stored as afrozenset.- The method property
body_formatis renamed torequest_body_format. StreamResponseParseroptions are keyword-only:StreamResponseParser(*, max_line_size, max_event_size, require_event_stream). It no longer takesjson_loadsorerror_resolver.BufferedResponseParsertakes no arguments.IResponseParser.parse(method, response, json_loads)andIStreamParser.parse(method, response, json_loads, error_resolver)take all their arguments as required. The response argument is namedresponse, notbuffered.Stream(events)is renamed toStream(items).SSEDecoder.feed()is renamed todecode(), andSSE_DONEmoved toai_api.response.parse.sse.get_headerandparse_retry_aftermoved from the error resolver toai_api.http.headers.ResponseEventis renamed toGenerationEvent.Provider.NONEis renamed toProvider.GENERIC.check_session_credsis renamed torequire_token_or_session, and the OpenAIvalidate_sessiontowarn_about_session.BodyFormatandResponseFormatmoved fromai_api.methods.enumstoai_api.enums.
Removed¶
ResponseModeand__response_mode__: buffered and stream methods are told apart by their base class.RETRY_CONDITION; useretry_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 |