Client Management

Client management helpers for persistent HTTP clients.

ClientManager()

Explicit, caller-owned tracker for clients created within one asyncio run.

Examples:

async with ClientManager() as manager:
    client_config = ClientConfig(http_client=http_client, manager=manager)
    invoker = AnthropicLMInvoker(..., client_config=client_config)
    ...

get_or_create() also works without the async with block -- construct a ClientManager() directly and call release_resources() explicitly when done:

manager = ClientManager()
client_config = ClientConfig(http_client=http_client, manager=manager)
invoker = AnthropicLMInvoker(..., client_config=client_config)
...
await manager.release_resources()

Every client returned by get_or_create() is closed by release_resources() regardless of whether the caller keeps its ClientConfig alive -- the manager tracks each client independent of that config's lifetime.

Initializes a new, empty ClientManager.

__aenter__() async

Enters the async context manager.

Returns:

Name	Type	Description
ClientManager	ClientManager	This manager instance.

__aexit__(*exc_info) async

Closes every tracked client.

Parameters:

Name	Type	Description	Default
*exc_info	object	Exception info passed by the async with protocol (unused).	()

get_or_create(config, factory, identity, model_id_log)

Return the tracked client for config's identity if one exists, else build and track one.

Parameters:

Name	Type	Description	Default
config	ClientConfig	The caller's client configuration.	required
factory	Callable[[], ManagedClient]	Builds a fresh client from config.http_client; called only on a cache miss.	required
identity	dict[str, Any]	The calling invoker's own connection parameters (api_key, base_url, organization, headers, timeout, ...).	required
model_id_log	str	Log identifier for the calling invoker.	required

Returns:

Type	Description
ManagedClient	tuple[ManagedClient, bool]: The live client and whether it is manager-tracked
bool	(False on the closed-manager fallback path).

Raises:

Type	Description
ValueError	If config was already used with a different identity.

release_resources() async

Closes every tracked client and marks this manager closed.

This includes clients built around a caller-supplied config.http_client: opting a ClientConfig into a manager transfers close-ownership of its client to that manager, even for an injected transport.

Concurrent calls are serialized so each tracked client is closed exactly once.

HookedClient(raw_client, teardown)

Bases: Generic[T]

Managed-client wrapper for SDK clients with custom async teardown.

The wrapper implements close() and synchronous is_closed() for the existing client manager protocol. It delegates SDK attributes and methods to raw_client and forwards async context management when available. Callers provide the teardown hook that matches their SDK's cleanup API.

Attributes:

Name	Type	Description
raw_client	T	The wrapped provider SDK client.

Wrap a provider client with its asynchronous teardown hook.

Parameters:

Name	Type	Description	Default
raw_client	T	SDK client to wrap.	required
teardown	TeardownHook	Async callback that closes raw_client.	required

__aenter__() async

Enter the wrapped SDK context when it provides one and return this wrapper.

Returns:

Type	Description
HookedClient[T]	HookedClient[T]: self.

__aexit__(exc_type, exc_val, exc_tb) async

Forward async context exit or use the configured teardown hook.

Parameters:

Name	Type	Description	Default
exc_type	type[BaseException] | None	Exception type from the managed block.	required
exc_val	BaseException | None	Exception raised by the managed block.	required
exc_tb	Any	Traceback for the managed-block exception.	required

Returns:

Type	Description
bool | None	bool | None: The raw client's exception-suppression result, or None when cleanup is performed through the teardown hook.

__getattr__(name)

Delegate public SDK attributes to the wrapped client.

Parameters:

Name	Type	Description	Default
name	str	Attribute or provider operation to retrieve.	required

Returns:

Name	Type	Description
Any	Any	The matching attribute on raw_client.

Raises:

Type	Description
AttributeError	If the attribute does not exist or is private.

close() async

Run the teardown hook once, serializing concurrent close requests.

is_closed()

Check whether the client is closed.

Returns:

Name	Type	Description
bool	bool	True if the client is closed, False otherwise.

ManagedClient

Bases: Protocol

Structural shape a client tracker needs: something it can close and check.

close() async

Closes the client and releases its connections.

is_closed()

Returns whether the client is closed.

PersistentClientMixin

Mixin for invokers that own a closable provider client, ephemeral or persistent.

Provides double-checked locking for safe client reacquisition after release_resources() in persistent mode. Subclasses must call _register_client() in __init__ and implement _create_client().

release_resources() async

Close the underlying persistent client, if any, and release its connections.

A safe no-op in ephemeral mode, since no ambient client is kept. In persistent mode, only closes a client this invoker actually owns: manager-tracked clients are left for the ClientManager to close, and caller-supplied client_config.http_client transports are left for the caller to close.

async_aclose_hook(client) async

Invoke the async SDK client's aclose() method.

Parameters:

Name	Type	Description	Default
client	Any	SDK client to close.	required