AIR

AIR

Import: from air import AIR

Constructor

python
AIR(
    config: AIRConfig | None = None,
    routing: str | None = None,
    persist: str | None = None,
)
  • config: an AIRConfig instance. If omitted, a default AIRConfig() is used. See configuration.md.
  • routing: convenience override for config.routing ("priority" or "intelligent"). If given, it overwrites config.routing after config is resolved.
  • persist: a file path. If given, sessions are stored in a SQLite database at this path (SQLiteContextStore). If omitted, sessions are stored in memory for the life of the process (InMemoryContextStore), and no file is created.

Raises ConfigurationError immediately if the resolved config.routing is not "priority" or "intelligent", or if config.context_optimization is not "off" or "auto".

Attributes

  • config: AIRConfig - the resolved configuration.
  • announcer: Announcer - the optional TTS announcer. See ../features/tts.md.

Methods

add_provider(provider, priority=None, limits=None, capabilities=None) -> None

Registers a provider under provider.name.

  • provider: Provider - must implement air.providers.base.Provider.
  • priority: int | None - lower runs first. If omitted, the next unused integer priority (in registration order) is assigned.
  • limits: dict | None - {"tokens": int, "reserve": int}, see ../features/capacity-tracking.md.
  • capabilities: dict | None - keyword arguments for ProviderCapabilities, see ../features/intelligent-routing.md.

Raises ProviderAlreadyRegisteredError if provider.name is already registered.

get_provider(name: str) -> Provider

Returns the registered provider instance. Raises ProviderNotFoundError if name is not registered.

health_of(name: str) -> ProviderHealth

Returns the current tracked health for a registered provider name. See ../core/fallback.md.

usage_of(name: str) -> UsageTotals

Returns tracked cumulative usage totals for a registered provider name. See ../features/capacity-tracking.md.

async chat(request: ChatRequest | str) -> ChatResponse

Sends a request through routing/fallback and returns the response. See ../core/routing.md and models.md.

Can raise: ProviderNotFoundError (explicit provider name not registered), NoProviderAvailableError (no providers registered and none named), ProvidersExhaustedError (all candidates failed or were skipped), or any provider exception not eligible for fallback (AuthenticationError, ProviderResponseError, or an arbitrary exception from a custom provider). See exceptions.md.

session(session_id: str) -> Session

Returns a Session bound to this id and to this AIR instance's context store. See session.md.

async list_sessions() -> list[str]

Returns known session ids from the configured context store.

on_event(callback) -> None

Registers an event callback (sync or async). See ../features/structured-events.md.

off_event(callback) -> None

Removes a previously registered event callback.

close() -> None

Closes the underlying SQLite connection if persist=... was used. Safe to call (no-op) when using the default in memory store.

Minimal example

python
import asyncio
from air import AIR
from air.providers.groq import GroqProvider
 
async def main():
    air = AIR()
    air.add_provider(GroqProvider(api_key="...", model="llama-3.3-70b-versatile"))
    response = await air.chat("Hello")
    print(response.content)
 
asyncio.run(main())