TAI42 — the OS for AI tools

Pooled clients + the generic client facade. Each client subclasses PooledClient (per-loop pooling, satisfies the contract BaseClient Protocol) and is reached by class through client_ctx. The driver each impl needs is declared by an extra (tai42-kit[curl] / [postgres]); import a driver submodule only when its driver is installed.

ClientDisconnectedError

tai42_contract.errors.ClientDisconnectedError

class ClientDisconnectedError(Exception)

Raised when a client disconnects unexpectedly and is removed from the cache. This is not a permanent failure — retrying the operation will cause a fresh client to be created automatically.

ClientSettings

tai42_kit.clients.settings.ClientSettings

class ClientSettings(DefaultNamespaceMixin, TaiBaseSettings)

Base a client’s settings subclass extends to supply connection kwargs via client_kwargs(). Attributes

Attribute	Type
`registry_exclude`	`bool`

Members

client_kwargs

tai42_kit.clients.settings.ClientSettings.client_kwargs

client_kwargs(self) -> dict[str, Any]

Connection kwargs passed to the client’s _create / current.

PooledClient

tai42_kit.clients.base.PooledClient

class PooledClient

A per-event-loop, per-epoch pool for a single driver client of type T. Subclasses implement _create and _close; callers lease the shared client through current, which rebuilds it after a classified disconnection.

Members

current

tai42_kit.clients.base.PooledClient.current

async current(self, **kwargs) -> AsyncIterator[T]

Lease the pooled client for kwargs, creating it on first use. A disconnection inside the body evicts and closes the client and raises ClientDisconnectedError; retry to rebuild it. Parameters

Parameter	Type	Default	Description
`kwargs`	—	`{}`	—

close

tai42_kit.clients.base.PooledClient.close

async close(self, **kwargs) -> None

Close and drop the pooled client for kwargs in the current epoch, if one is pooled. Parameters

Parameter	Type	Default	Description
`kwargs`	—	`{}`	—

PostgresConnectionSettings

tai42_kit.clients.settings.PostgresConnectionSettings

class PostgresConnectionSettings(ClientSettings)

Base Postgres connection settings loaded under a database’s TAI_DATABASE_<NAME>_ prefix. Attributes

Attribute	Type
`registry_exclude`	`bool`
`pg_host`	`str \| None`
`pg_port`	`int`
`pg_db`	`str`
`pg_user`	`str`
`pg_password`	`SecretStr \| None`
`pg_min_connections`	`int`
`pg_max_connections`	`int`
`pg_connect_timeout`	`int`
`pg_statement_timeout_seconds`	`float`

Members

pg_dsn

tai42_kit.clients.settings.PostgresConnectionSettings.pg_dsn

pg_dsn: str

Build the libpq DSN from the connection fields; a missing host or password raises a named error.

client_kwargs

tai42_kit.clients.settings.PostgresConnectionSettings.client_kwargs

client_kwargs(self) -> dict[str, Any]

Connection identity for the pooled client — JSON-serializable only. Pools are keyed by DSN + min/max size; callers that disagree on pool bounds get separate pools.

RedisConnectionSettings

tai42_kit.clients.settings.RedisConnectionSettings

class RedisConnectionSettings(ClientSettings)

Base Redis connection settings with unprefixed field names for a store to subclass with its own prefix. Attributes

Attribute	Type
`registry_exclude`	`bool`
`tai_default_fields`	`Mapping[str, str]`
`redis_url`	`str \| None`
`redis_max_connections`	`int \| None`
`decode_responses`	`bool`
`socket_timeout`	`float \| None`
`socket_connect_timeout`	`float \| None`
`retry_on_timeout`	`bool`
`retry_attempts`	`int`

Members

client_kwargs

tai42_kit.clients.settings.RedisConnectionSettings.client_kwargs

client_kwargs(self) -> dict[str, Any]

Connection identity for the pooled client — JSON-serializable only. The facade keys its per-loop connection pool on these kwargs, so every value must be JSON-serializable. retry_attempts travels as an int; the redis client turns it into a Retry object at construction time — a Retry instance is not serializable and would break the pool key. env_prefix rides along so the client can name this store’s own env var when redis_url is unset; it is not connection identity, so the redis client drops it from the pool key.

advance_client_epoch

tai42_kit.clients.base.advance_client_epoch

advance_client_epoch() -> int

Advance the process-wide client epoch and return the epoch just retired. New current() leases pool under the new epoch; the retired epoch’s pools stay live until their last lease releases (or drain_epoch force-closes them at a deadline). The same counter stamps cached settings instances.

client_ctx

tai42_kit.clients.facade.client_ctx

client_ctx(
    client_cls: type[PooledClient[T]],
    settings: ClientSettings | None = None,
    *,
    fresh: bool = False,
    **kwargs: Any,
) -> AbstractAsyncContextManager[T]

Return an async context manager yielding a connected client for client_cls. Pass either settings (its client_kwargs() supplies the connection kwargs) or raw **kwargs, never both. fresh=True builds a one-shot client outside the pool and closes it on exit; otherwise the client is pooled and reused per event-loop + connection params. Parameters

Parameter	Type	Default	Description
`client_cls`	`type[PooledClient[T]]`	—	—
`settings`	`ClientSettings \| None`	`None`	—
`fresh`	`bool`	`False`	—
`kwargs`	`Any`	`{}`	—

current_client_epoch

tai42_kit.clients.base.current_client_epoch

current_client_epoch() -> int

The current client epoch — the value new leases and settings stamps carry.

drain_epoch

tai42_kit.clients.base.drain_epoch

async drain_epoch(epoch: int, deadline: float) -> None

Drain and close a retired epoch’s client pools for the running loop. Waits up to deadline seconds for every leased client of epoch to reach zero leases (each closes itself on its last release), then force-closes any that remain regardless of held leases, collecting failures into an ExceptionGroup so none is dropped. Must run on the loop that owns the pools; the current epoch cannot be drained. Parameters

Parameter	Type	Default	Description
`epoch`	`int`	—	—
`deadline`	`float`	—	—

shutdown_all_clients

tai42_kit.clients.base.shutdown_all_clients

async shutdown_all_clients() -> None

Close every live client pool for the running event loop. Sweeps every epoch of the per-loop class-keyed cache and closes each pooled client — process-teardown semantics, independent of leases. Closes are best-effort — failures are collected and raised together, never silently dropped.

HTTP API

CLI

Settings

Capability map

Conversation bridge

Python SDK

Studio SDK

Pooled clients (tai42_kit.clients)

ClientDisconnectedError

ClientSettings

Members

client_kwargs

PooledClient

Members

current

close

PostgresConnectionSettings

Members

pg_dsn

client_kwargs

RedisConnectionSettings

Members

client_kwargs

advance_client_epoch

client_ctx

current_client_epoch

drain_epoch

shutdown_all_clients

​ClientDisconnectedError

​ClientSettings

​Members

​client_kwargs

​PooledClient

​Members

​current

​close

​PostgresConnectionSettings

​Members

​pg_dsn

​client_kwargs

​RedisConnectionSettings

​Members

​client_kwargs

​advance_client_epoch

​client_ctx

​current_client_epoch

​drain_epoch

​shutdown_all_clients

ClientDisconnectedError

ClientSettings

Members

client_kwargs

PooledClient

Members

current

close

PostgresConnectionSettings

Members

pg_dsn

client_kwargs

RedisConnectionSettings

Members

client_kwargs

advance_client_epoch

client_ctx

current_client_epoch

drain_epoch

shutdown_all_clients