aiollm.adapters¶
adapters
¶
Adapters between shared request and response types and provider methods.
Modules:
| Name | Description |
|---|---|
base |
Base classes of adapters. |
protocols |
Interfaces of adapters between shared types and provider methods. |
stop |
How a generation stopped, as the shared types tell it. |
validation |
Checks adapters run on a shared request before building a method. |
Classes:
| Name | Description |
|---|---|
BaseAdapter |
Base class of adapters of requests answered at once. |
BaseCompositeAdapter |
Base class of adapters of endpoints that respond and stream. |
BaseConversion |
Base class of conversions between provider and shared values. |
BaseFilesAdapter |
Base class of adapters of a provider's Files API. |
BaseStreamAdapter |
Base class of adapters of streamed requests. |
IAdapter |
Converts one shared request and its provider's response. |
ICompositeAdapter |
An adapter for an endpoint that can both respond and stream. |
IConversion |
Converts one provider value into a shared one, or back. |
IStreamAdapter |
Converts one shared request and its provider's stream. |
Stop |
How a generation stopped, in shared terms. |
Functions:
| Name | Description |
|---|---|
check_builtin_tools |
Check that the provider can run the built-in tools of a request. |
check_conversation |
Check the order of a conversation that every provider requires. |
check_files |
Check that every stored file a request names is the provider's. |
checked_options |
Check the keys of a call's provider options at run time. |
container_of |
Tell which container of a built-in tool holds a file. |
merge_options |
Merge a call's provider options into the fields of a method. |
request_errors |
Report a method the provider's limits reject as the request's fault. |
BaseAdapter
¶
Bases: _ProviderAdapter
Base class of adapters of requests answered at once.
Example
class ChatAdapter(BaseAdapter[GenerationRequest, Chat, Reply]): ... provider = Provider("chat") ... ... def to_method(self, request): ... return CreateChat(model=request.model, ...) ... ... def to_response(self, raw, request): ... return Reply(text=raw.choices[0].text, raw=raw)
Methods:
| Name | Description |
|---|---|
to_method |
Build the provider's method for a shared request. |
to_response |
Convert the provider's response into a shared response. |
to_method
abstractmethod
¶
to_method(request: ReqT) -> IAPIMethod[RawT]
Build the provider's method for a shared request.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
request
|
ReqT
|
The request in shared types. |
required |
Returns:
| Type | Description |
|---|---|
IAPIMethod[RawT]
|
The provider's method, ready to send. |
to_response
abstractmethod
¶
Convert the provider's response into a shared response.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
raw
|
RawT
|
The parsed result of the provider's method. |
required |
request
|
ReqT
|
The request the response answers. |
required |
Returns:
| Type | Description |
|---|---|
RespT
|
The response in shared types. |
BaseCompositeAdapter
¶
Bases: BaseAdapter[ReqT, RawT, RespT], BaseStreamAdapter[ReqT, RawItemT, EventT]
Base class of adapters of endpoints that respond and stream.
A subclass usually builds both methods from one private helper, since a provider's buffered and streamed requests mostly differ by one flag.
BaseConversion
¶
Bases: ABC
Base class of conversions between provider and shared values.
A conversion is pure: it converts one value and does no I/O. It
names what it converts in its type, source → target, and an
adapter takes it as a keyword argument, so a caller can swap it.
Example
class UsageConversion(BaseConversion[Usage, TokenUsage]): ... def call(self, source): ... return TokenUsage(input_tokens=source.input_tokens)
BaseFilesAdapter
¶
Bases: _ProviderAdapter
Base class of adapters of a provider's Files API.
A subclass builds the provider's five methods and converts its file
type and list page; it adds with_options for its upload options
(IFilesAdapter).
Example
class ExampleFilesAdapter(BaseFilesAdapter[File, FilePage]): ... provider = Provider("example") ... ... def to_retrieve_method(self, file_id): ... return RetrieveFile(file_id=file_id)
Methods:
| Name | Description |
|---|---|
to_upload_method |
Build the method that stores a file. |
to_retrieve_method |
Build the method that reads a file's metadata. |
to_list_method |
Build the method that reads one page of the stored files. |
to_page |
Take the files of a page and where the next one starts. |
to_delete_method |
Build the method that deletes a file. |
to_download_method |
Build the method that streams a file's content. |
to_stored_file |
Convert the provider's file into the shared metadata. |
to_upload_method
abstractmethod
¶
to_upload_method(
request: FileUpload,
) -> IAPIMethod[RawFileT]
Build the method that stores a file.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
request
|
FileUpload
|
The shared upload. |
required |
Returns:
| Type | Description |
|---|---|
IAPIMethod[RawFileT]
|
The provider's upload method, ready to send. |
to_retrieve_method
abstractmethod
¶
to_retrieve_method(file_id: str) -> IAPIMethod[RawFileT]
Build the method that reads a file's metadata.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
file_id
|
str
|
The provider's id of the file. |
required |
Returns:
| Type | Description |
|---|---|
IAPIMethod[RawFileT]
|
The provider's method, ready to send. |
to_list_method
abstractmethod
¶
to_list_method(cursor: str | None) -> IAPIMethod[RawPageT]
Build the method that reads one page of the stored files.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
cursor
|
str | None
|
Where the page starts; |
required |
Returns:
| Type | Description |
|---|---|
IAPIMethod[RawPageT]
|
The provider's method, ready to send. |
to_page
abstractmethod
¶
to_delete_method
abstractmethod
¶
to_delete_method(file_id: str) -> IAPIMethod[Any]
Build the method that deletes a file.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
file_id
|
str
|
The provider's id of the file. |
required |
Returns:
| Type | Description |
|---|---|
IAPIMethod[Any]
|
The provider's method, ready to send. |
to_download_method
abstractmethod
¶
to_download_method(
file: ProviderFile,
) -> IStreamMethod[bytes]
Build the method that streams a file's content.
The whole file, not its id: a ProducedFile of a container
(container_id) is downloaded from that container where the
provider has one, and refused where it has none.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
file
|
ProviderFile
|
The file, already known to be the provider's. |
required |
Returns:
| Type | Description |
|---|---|
IStreamMethod[bytes]
|
The provider's stream method, ready to open. |
Raises:
| Type | Description |
|---|---|
RequestValidationError
|
The provider cannot download the file, such as a file of a container where it has none. |
to_stored_file
abstractmethod
¶
to_stored_file(raw: RawFileT) -> StoredFile[RawFileT]
Convert the provider's file into the shared metadata.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
raw
|
RawFileT
|
The provider's file. |
required |
Returns:
| Type | Description |
|---|---|
StoredFile[RawFileT]
|
The shared metadata, |
BaseStreamAdapter
¶
Bases: _ProviderAdapter
Base class of adapters of streamed requests.
to_events is usually written as an async generator.
Methods:
| Name | Description |
|---|---|
to_stream_method |
Build the provider's stream method for a shared request. |
to_events |
Convert the provider's stream items into shared events. |
to_stream_method
abstractmethod
¶
to_stream_method(request: ReqT) -> IStreamMethod[RawItemT]
Build the provider's stream method for a shared request.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
request
|
ReqT
|
The request in shared types. |
required |
Returns:
| Type | Description |
|---|---|
IStreamMethod[RawItemT]
|
The provider's stream method, ready to send. |
to_events
abstractmethod
¶
to_events(
items: AsyncIterator[RawItemT], request: ReqT
) -> AsyncIterator[EventT]
Convert the provider's stream items into shared events.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
items
|
AsyncIterator[RawItemT]
|
The items of the provider's stream. |
required |
request
|
ReqT
|
The request the stream answers. |
required |
Returns:
| Type | Description |
|---|---|
AsyncIterator[EventT]
|
The events in shared types. |
IAdapter
¶
Bases: Protocol
Converts one shared request and its provider's response.
Both halves name the same RawT, so a type checker sees at the
adapter itself whether the method it builds returns what its response
conversion expects. An adapter only converts models: it sends nothing
and holds no session.
Methods:
| Name | Description |
|---|---|
to_method |
Build the provider's method for a shared request. |
to_response |
Convert the provider's response into a shared response. |
Attributes:
| Name | Type | Description |
|---|---|---|
provider |
Provider
|
The provider whose methods the adapter builds. |
to_method
¶
to_method(request: ReqT) -> IAPIMethod[RawT]
Build the provider's method for a shared request.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
request
|
ReqT
|
The request in shared types. |
required |
Returns:
| Type | Description |
|---|---|
IAPIMethod[RawT]
|
The provider's method, ready to send. |
to_response
¶
Convert the provider's response into a shared response.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
raw
|
RawT
|
The parsed result of the provider's method. |
required |
request
|
ReqT
|
The request the response answers, for what the provider does not send back, e.g. an output schema. |
required |
Returns:
| Type | Description |
|---|---|
RespT
|
The response in shared types. |
ICompositeAdapter
¶
Bases: IAdapter[ReqT, RawT, RespT], IStreamAdapter[ReqT, RawItemT, EventT], Protocol
An adapter for an endpoint that can both respond and stream.
IConversion
¶
Bases: Protocol
Converts one provider value into a shared one, or back.
An adapter takes its conversions as keyword arguments, so one can be swapped without subclassing the adapter. A plain function matches too: the source is positional-only, so its name does not matter.
IStreamAdapter
¶
Bases: Protocol
Converts one shared request and its provider's stream.
Methods:
| Name | Description |
|---|---|
to_stream_method |
Build the provider's stream method for a shared request. |
to_events |
Convert the provider's stream items into shared events. |
Attributes:
| Name | Type | Description |
|---|---|---|
provider |
Provider
|
The provider whose methods the adapter builds. |
to_stream_method
¶
to_stream_method(request: ReqT) -> IStreamMethod[RawItemT]
Build the provider's stream method for a shared request.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
request
|
ReqT
|
The request in shared types. |
required |
Returns:
| Type | Description |
|---|---|
IStreamMethod[RawItemT]
|
The provider's stream method, ready to send. |
to_events
¶
to_events(
items: AsyncIterator[RawItemT], request: ReqT
) -> AsyncIterator[EventT]
Convert the provider's stream items into shared events.
It sees the whole stream, so it may keep state, skip items and turn one item into several events.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
items
|
AsyncIterator[RawItemT]
|
The items of the provider's stream. |
required |
request
|
ReqT
|
The request the stream answers. |
required |
Returns:
| Type | Description |
|---|---|
AsyncIterator[EventT]
|
The events in shared types; usually an async generator. |
Stop
dataclass
¶
Stop(
incomplete_reason: IncompleteReason | None = None,
raw_incomplete_reason: str | None = None,
refusal: str | None = None,
)
How a generation stopped, in shared terms.
What a provider's stop conversion returns: the three stop fields of
GenerationResponse and CompletedEvent.
Attributes:
| Name | Type | Description |
|---|---|---|
incomplete_reason |
IncompleteReason | None
|
Shared reason of an early stop; |
raw_incomplete_reason |
str | None
|
The provider's own reason, if it gives one. |
refusal |
str | None
|
What the provider says about a refusal, if anything. |
check_builtin_tools
¶
check_builtin_tools(
request: GenerationRequest,
provider: Provider,
shared: Collection[type],
) -> None
Check that the provider can run the built-in tools of a request.
A provider takes some of the shared built-in tools (WebSearch,
CodeExecution) and only its own ProviderTools; a tool it
cannot take is refused before anything is sent, since leaving it out
would give an answer the caller did not ask for.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
request
|
GenerationRequest
|
The shared request. |
required |
provider
|
Provider
|
Provider the request is for. |
required |
shared
|
Collection[type]
|
The classes of the shared built-in tools the provider
takes, such as |
required |
Raises:
| Type | Description |
|---|---|
RequestValidationError
|
A shared tool is not in |
check_conversation
¶
check_conversation(
request: GenerationRequest, provider: Provider
) -> None
Check the order of a conversation that every provider requires.
Anthropic rejects a last assistant turn (prefill) on current
models, and OpenAI gives it a meaning of its own, so a conversation
ends with a user turn or a tool result; the one exception is an
assistant turn with native output, the turn of a paused
generation, which goes back to be continued. Both answer 400 to a call
without its result and to a result without its call (seen in a live
check, 2026-11-06), and Anthropic to results that do not follow
their call at once, so the results of a turn of calls come right
after it, one per call.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
request
|
GenerationRequest
|
The shared request. |
required |
provider
|
Provider
|
Provider the request is for. |
required |
Raises:
| Type | Description |
|---|---|
RequestValidationError
|
|
check_files
¶
check_files(
request: GenerationRequest, provider: Provider
) -> None
Check that every stored file a request names is the provider's.
A file id means nothing to another provider, which would answer 404
or, worse, find a file of its own by that id; so a part whose
file another provider stores is refused before anything is sent.
A file of a container is refused too, since a part names a stored
file.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
request
|
GenerationRequest
|
The shared request. |
required |
provider
|
Provider
|
Provider the request is for. |
required |
Raises:
| Type | Description |
|---|---|
RequestValidationError
|
A part names another provider's file, or a file of a container. |
checked_options
¶
Check the keys of a call's provider options at run time.
A type checker sees them only in typed code; a dict built at run
time reaches the adapter unchecked. The values are checked later by
the method the options go into.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
options
|
object
|
The |
required |
options_type
|
type
|
The provider's |
required |
provider
|
Provider
|
The provider, for the error. |
required |
Returns:
| Type | Description |
|---|---|
dict[str, Any]
|
A copy of the options as a plain |
Raises:
| Type | Description |
|---|---|
TypeError
|
|
RequestValidationError
|
|
container_of
¶
container_of(file: ProviderFile) -> str | None
Tell which container of a built-in tool holds a file.
Such a file (a ProducedFile with a container_id, as OpenAI's
code interpreter makes) is not among the stored files: only a
download reaches it.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
file
|
ProviderFile
|
The file. |
required |
Returns:
| Type | Description |
|---|---|
str | None
|
The container's id; |
Example
if (container := container_of(file)) is not None: ... return DownloadContainerFile(container, file.id)
merge_options
¶
merge_options(
fields: Mapping[str, Any],
options: Mapping[str, Any],
provider: Provider,
) -> dict[str, Any]
Merge a call's provider options into the fields of a method.
A shared field may fill part of an object, such as OpenAI's
reasoning.effort, while the options fill the rest of it
(reasoning.summary): such objects are merged one level deep.
A key both sides set is refused, so the two never disagree.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
fields
|
Mapping[str, Any]
|
The method fields the shared request gives; |
required |
options
|
Mapping[str, Any]
|
The checked provider options. |
required |
provider
|
Provider
|
The provider, for the error. |
required |
Returns:
| Type | Description |
|---|---|
dict[str, Any]
|
The merged fields. |
Raises:
| Type | Description |
|---|---|
RequestValidationError
|
The options set a key of an object that
a shared field sets too; |
request_errors
¶
Report a method the provider's limits reject as the request's fault.
A provider method checks the provider's limits when it is built, and
raises pydantic's ValidationError. The caller gave a shared
request, so the error speaks of the shared fields: field is the
shared name of the first failing field, and the message lists every
error, each under its shared name.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
provider
|
Provider
|
Provider of the method built inside. |
required |
fields
|
Mapping[str, str] | None
|
Shared field name of each method field whose name
differs, such as |
None
|
Yields:
| Type | Description |
|---|---|
Generator[None]
|
Nothing; the method is built in the |
Raises:
| Type | Description |
|---|---|
RequestValidationError
|
Building the method failed validation;
the |
Example
with request_errors(Provider("openai")): ... method = CreateResponse(**fields)