Skip to content

aiollm.client

client

Provider clients: the base client and session factories.

Modules:

Name Description
base

Base classes for clients and provider clients.

binding

Bindings of shared resources to the adapters of a provider client.

protocols

Interface of a client.

validators

Checks of the arguments shared by provider clients.

Classes:

Name Description
BaseClient

Sends methods through a session; a provider client subclasses it.

BaseProviderClient

What a provider's client shares: its session, from a token.

ResourceBinding

How a provider client builds one of its shared resources.

IClient

Sends methods through a session it owns.

Functions:

Name Description
bind_resource

Declare a shared resource of a provider client.

BaseClient

BaseClient(session: SessionT)

Sends methods through a session; a provider client subclasses it.

The client owns its session: close() and leaving async with close it. SessionT keeps the session's own type, so a client built on AiohttpSession exposes its settings, such as loop.

Attributes:

Name Type Description
session SessionT

The session that sends the requests.

Example

async with ExampleClient("sk-...") as client: ... models = await client.send_request(ListModels())

Wrap a session.

Parameters:

Name Type Description Default
session SessionT

The session that sends the requests.

required

Methods:

Name Description
close

Close the session and its connections.

send_request

Send a method and return its parsed response.

stream

Send a stream method; use the result with async with.

close async

close() -> None

Close the session and its connections.

send_request async

send_request(
    method: IAPIMethod[T],
    *,
    headers: HeadersType | None = None,
    timeout: Timeout | None = None,
    retry_policy: RetryPolicy | None = None,
) -> T

Send a method and return its parsed response.

Parameters:

Name Type Description Default
method IAPIMethod[T]

The method to send.

required
headers HeadersType | None

Headers for this request only.

None
timeout Timeout | None

Seconds the whole request may take; None for the session's timeout.

None
retry_policy RetryPolicy | None

Retry policy of this request; None for the session's.

None

Returns:

Type Description
T

The parsed response, typed by the method's generic argument.

stream

stream(
    method: IStreamMethod[T],
    *,
    headers: HeadersType | None = None,
    timeout: Timeout | None = None,
    retry_policy: RetryPolicy | None = None,
) -> AbstractAsyncContextManager[Stream[T]]

Send a stream method; use the result with async with.

Parameters:

Name Type Description Default
method IStreamMethod[T]

The stream method to send.

required
headers HeadersType | None

Headers for this request only.

None
timeout Timeout | None

Longest silence between two chunks, in seconds; None for the session's stream timeout.

None
retry_policy RetryPolicy | None

Retry policy of opening the stream; None for the session's.

None

Returns:

Type Description
AbstractAsyncContextManager[Stream[T]]

A context manager that yields the stream and closes it on

AbstractAsyncContextManager[Stream[T]]

exit.

BaseProviderClient

BaseProviderClient(
    token: str | None = None,
    *,
    session: ISession | None = None,
    **session_kwargs: Any,
)

Bases: BaseClient[ISession]

What a provider's client shares: its session, from a token.

A subclass declares its parts and its shared resources, each with bind_resource: the resource class and the adapter it runs on. The client builds every adapter before its session, so bad adapter options fail without one, and every resource right after it. The parts name one provider, checked when the subclass is defined, for every adapter it declares.

The bindings are found among the class attributes of the client and its bases, by MRO; a subclass replaces one under the same name or drops it with any other value. On an instance the attribute is the resource; on the class it stays the ResourceBinding, though type checkers see the resource (see bind_resource).

The client takes a token, a ready session= or, without either, the token in api_key_env; session_kwargs configure the session built from a token. A given session is checked by warn_about_session.

Attributes:

Name Type Description
provider Provider

The provider of the client.

session_factory ISessionFactory[ISession, Any, ...]

Builds the session from a token; its error resolver is the provider's.

api_key_env str

Environment variable read without a token or a session, such as EXAMPLE_API_KEY.

auth_headers frozenset[str]

Headers the provider takes the key in, such as Authorization.

Example

class ExampleClient(BaseProviderClient): ... provider = PROVIDER ... session_factory = session_factory ... api_key_env = "EXAMPLE_API_KEY" ... auth_headers = frozenset({AUTHORIZATION}) ... ... generation = bind_resource( ... GenerationResource[Response, ResponseStreamEvent], ... ExampleGenerationAdapter, ... )

Create the client from a token or a ready session.

A subclass types session_kwargs by its session's options and sets the options its adapter factories read before calling this. The adapters are built first, the resources once the session exists.

Parameters:

Name Type Description Default
token str | None

API key; the session is built from it by session_factory. Without a token and a session, the key in api_key_env is used.

None
session ISession | None

A ready session, for custom settings; it is checked with warn_about_session.

None
**session_kwargs Any

Further arguments of the session built from the token, such as timeout.

{}

Raises:

Type Description
ValueError

If both token and session are given, or neither is and api_key_env is unset or empty, or session_kwargs are given with a session.

TypeError

If an adapter factory returns another class than its binding declares.

Methods:

Name Description
warn_about_session

Warn about a given session that does not fit the provider.

warn_about_session classmethod

warn_about_session(session: ISession) -> None

Warn about a given session that does not fit the provider.

Only BaseSession subclasses are checked; other sessions are trusted as they are. The session's api is not checked: gateways, proxies and hosted deployments (such as Azure) serve a provider's API at another base_url on purpose.

Parameters:

Name Type Description Default
session ISession

The session given to the client.

required

Warns:

Type Description
SessionMismatchWarning

If the session's error resolver is not the provider's (a subclass of it is), or the session sends the key in a header the provider does not take. The warning points at the code that built the client.

ResourceBinding

ResourceBinding(
    resource_type: Callable[
        [ISession, AdapterT], ResourceT
    ],
    adapter_type: type[AdapterT],
    *,
    adapter_factory: Callable[[Any], AdapterT]
    | None = None,
)

How a provider client builds one of its shared resources.

bind_resource makes it; BaseProviderClient finds it among the class attributes, checks the adapter's provider when the class is defined, builds the adapter before the session and the resource after it.

Attributes:

Name Type Description
resource_type

Builds the resource from a session and an adapter, such as GenerationResource[Response, Event].

adapter_type

The adapter class; its provider is checked.

adapter_factory

Builds the adapter from the client, or None to call adapter_type() without arguments.

Keep the parts of the binding.

Parameters:

Name Type Description Default
resource_type Callable[[ISession, AdapterT], ResourceT]

Builds the resource from a session and an adapter.

required
adapter_type type[AdapterT]

The adapter class.

required
adapter_factory Callable[[Any], AdapterT] | None

Builds the adapter from the client; without it, adapter_type() is called.

None

Methods:

Name Description
build_adapter

Build the adapter for a client whose session is not made yet.

build_resource

Build the resource on the client's session.

build_adapter

build_adapter(client: object) -> AdapterT

Build the adapter for a client whose session is not made yet.

Parameters:

Name Type Description Default
client object

The provider client being created.

required

Returns:

Type Description
AdapterT

The adapter.

Raises:

Type Description
TypeError

If the factory returns something other than an adapter_type of its provider: only that class had its provider checked, and a subclass may name another.

build_resource

build_resource(
    session: ISession, adapter: AdapterT
) -> ResourceT

Build the resource on the client's session.

Parameters:

Name Type Description Default
session ISession

The client's session.

required
adapter AdapterT

The adapter from build_adapter.

required

Returns:

Type Description
ResourceT

The resource.

IClient

Bases: Protocol

Sends methods through a session it owns.

Methods:

Name Description
close

Close the session and its connections.

send_request

Send a method and return its parsed response.

stream

Send a stream method; use the result with async with.

Attributes:

Name Type Description
session ISession

The session that sends the requests.

session property

session: ISession

The session that sends the requests.

close async

close() -> None

Close the session and its connections.

send_request async

send_request(
    method: IAPIMethod[T],
    *,
    headers: HeadersType | None = None,
    timeout: Timeout | None = None,
    retry_policy: RetryPolicy | None = None,
) -> T

Send a method and return its parsed response.

Parameters:

Name Type Description Default
method IAPIMethod[T]

The method to send.

required
headers HeadersType | None

Headers for this request only.

None
timeout Timeout | None

Seconds the whole request may take; None for the session's timeout.

None
retry_policy RetryPolicy | None

Retry policy of this request; None for the session's.

None

Returns:

Type Description
T

The parsed response.

stream

stream(
    method: IStreamMethod[T],
    *,
    headers: HeadersType | None = None,
    timeout: Timeout | None = None,
    retry_policy: RetryPolicy | None = None,
) -> AbstractAsyncContextManager[Stream[T]]

Send a stream method; use the result with async with.

Parameters:

Name Type Description Default
method IStreamMethod[T]

The stream method to send.

required
headers HeadersType | None

Headers for this request only.

None
timeout Timeout | None

Longest silence between two chunks, in seconds; None for the session's stream timeout.

None
retry_policy RetryPolicy | None

Retry policy of opening the stream; None for the session's.

None

Returns:

Type Description
AbstractAsyncContextManager[Stream[T]]

A context manager that yields the stream and closes it on

AbstractAsyncContextManager[Stream[T]]

exit.

bind_resource

bind_resource(
    resource_type: Callable[
        [ISession, AdapterT], ResourceT
    ],
    adapter_type: type[AdapterT],
    *,
    adapter_factory: Callable[[Any], AdapterT]
    | None = None,
) -> ResourceT

Declare a shared resource of a provider client.

Assigned to a class attribute of a BaseProviderClient subclass, it makes that attribute of every client the resource, built on the client's session. Like dataclasses.field, it returns a ResourceBinding typed as the resource, so type checkers see the attribute as the resource; on the class itself it stays the binding.

Parameters:

Name Type Description Default
resource_type Callable[[ISession, AdapterT], ResourceT]

Builds the resource from a session and an adapter, such as GenerationResource[Response, Event].

required
adapter_type type[AdapterT]

The adapter class; its provider must be the client's, checked when the client class is defined.

required
adapter_factory Callable[[Any], AdapterT] | None

Builds the adapter from the client, before the session exists (so bad options fail without one), such as a method of the client that reads its own options; without it, adapter_type() is called.

None

Returns:

Type Description
ResourceT

The binding, typed as the resource.

Example

class ExampleClient(BaseProviderClient): ... generation = bind_resource( ... GenerationResource[Response, ResponseStreamEvent], ... ExampleGenerationAdapter, ... )