Skip to content

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

to_response(raw: RawT, request: ReqT) -> RespT

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; None for the first page.

required

Returns:

Type Description
IAPIMethod[RawPageT]

The provider's method, ready to send.

to_page abstractmethod

to_page(
    raw: RawPageT,
) -> tuple[Sequence[RawFileT], str | None]

Take the files of a page and where the next one starts.

Parameters:

Name Type Description Default
raw RawPageT

The page the list method returned.

required

Returns:

Type Description
Sequence[RawFileT]

The page's files and the cursor of the next page, None

str | None

after the last one.

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, raw included.

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.

provider property

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

to_response(raw: RawT, request: ReqT) -> RespT

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.

provider property

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; None if the generation reached its end.

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 (WebSearch, CodeExecution).

required

Raises:

Type Description
RequestValidationError

A shared tool is not in shared, a ProviderTool belongs to another provider, or the files of a CodeExecution are another provider's or of a container; field is tools.

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

input breaks one of these rules.

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

checked_options(
    options: object, options_type: type, provider: Provider
) -> dict[str, Any]

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 provider_options of a call.

required
options_type type

The provider's TypedDict of its options.

required
provider Provider

The provider, for the error.

required

Returns:

Type Description
dict[str, Any]

A copy of the options as a plain dict.

Raises:

Type Description
TypeError

options_type is not a TypedDict.

RequestValidationError

options is not a mapping, or has a key that is not one of the provider's options; field is the first such key.

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; None for a stored file.

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; MISSING for a field it leaves out.

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; field is its dotted path.

request_errors

request_errors(
    provider: Provider,
    fields: Mapping[str, str] | None = None,
) -> Generator[None]

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 {"max_tokens": "max_output_tokens"}.

None

Yields:

Type Description
Generator[None]

Nothing; the method is built in the with block.

Raises:

Type Description
RequestValidationError

Building the method failed validation; the ValidationError is its __cause__.

Example

with request_errors(Provider("openai")): ... method = CreateResponse(**fields)