AIR

Models

Import: from air import Message, Role, ChatRequest, ChatResponse (also available from air.models). Usage is available from air.models (not re-exported from the top level air package).

Role

python
class Role(str, Enum):
    SYSTEM = "system"
    USER = "user"
    ASSISTANT = "assistant"

Message

python
@dataclass
class Message:
    role: Role
    content: str

ChatRequest

python
@dataclass
class ChatRequest:
    messages: list[Message]
    model: str | None = None
    provider: str | None = None
    temperature: float | None = None
    max_tokens: int | None = None
    requires: set[str] | None = None
  • messages: the conversation, in order.
  • model: overrides the provider's configured default model for this request, if set.
  • provider: if set, forces explicit provider selection (see ../core/routing.md); bypasses routing and fallback.
  • temperature, max_tokens: passed through to the provider if set.
  • requires: a set of capability strings (for example {"vision"}) merged into intelligent routing's required capability set. Only used when routing="intelligent"; ignored otherwise.

air.chat("some text") is shorthand for air.chat(ChatRequest(messages=[Message(role=Role.USER, content="some text")])).

Usage

python
@dataclass
class Usage:
    prompt_tokens: int | None = None
    completion_tokens: int | None = None
    total_tokens: int | None = None

Populated from a provider's response only when that provider's API reports usage; fields are None otherwise. See ../features/capacity-tracking.md.

ChatResponse

python
@dataclass
class ChatResponse:
    content: str
    provider: str
    model: str
    raw: dict[str, Any] = field(default_factory=dict)
    events: list[str] = field(default_factory=list)
    structured_events: list[Event] = field(default_factory=list)
    usage: Usage | None = None
    selection_reason: str | None = None
    original_estimated_tokens: int | None = None
    optimized_estimated_tokens: int | None = None
    estimated_tokens_saved: int | None = None
    compression_applied: bool = False
  • content: the reply text.
  • provider: the name of the provider that actually answered (may differ from the first one tried, after fallback).
  • model: the model that actually answered, as reported by the provider (or the configured default if the provider does not echo it back).
  • raw: the provider's raw parsed JSON response body. Never includes request headers or your API key.
  • events: human readable strings (each prefixed "[AIR]: ") for every routing event that occurred during this call. See ../features/structured-events.md.
  • structured_events: the same events as structured Event objects.
  • usage: token usage for this specific response, if the provider reported it.
  • selection_reason: set only when routing="intelligent" picked the provider that ended up answering. See ../features/intelligent-routing.md.
  • original_estimated_tokens, optimized_estimated_tokens, estimated_tokens_saved, compression_applied: context optimization metadata for this call. See ../features/context-optimization.md.