AIR

Changelog: v0.1.0-beta.1

This is the initial released version of AIR. No prior published version exists. This version was released on 01 August 2026.

Contents of v0.1.0-beta.1

  • Core AIR client: provider registration (add_provider), provider lookup (get_provider), and chat(request) accepting either a plain string or a ChatRequest.
  • Provider abstraction (air.providers.base.Provider) with no provider specific logic in AIR core.
  • Four built in provider adapters: xAI (Grok), Google Gemini, Groq, and OpenRouter, each using httpx for async HTTP, with provider specific request/response conversion and error classification.
  • A structured exception hierarchy (AIRError and subclasses) distinguishing authentication failures, quota exhaustion, rate limits, timeouts, generic API errors, and malformed responses, each carrying provider name, error code, retryable flag, and HTTP status code where available.
  • Priority based automatic routing with fallback: providers are tried in configured priority order, and AIR automatically moves to the next provider on a fallback eligible error (quota exhaustion, rate limit, timeout, or generic API error), without retrying on authentication or malformed response errors.
  • Provider health tracking (available, rate_limited, exhausted, temporarily_unavailable, unknown) and usage tracking (prompt/completion/total tokens, when a provider reports them).
  • Optional per provider capacity limits (limits={"tokens": ..., "reserve": ...}) with a preflight capacity check that skips a provider before calling it if AIR estimates it cannot handle the request.
  • Optional intelligent routing (routing="intelligent"): deterministic, keyword based request classification and capability/health/capacity aware provider scoring, with no calls to an AI model to make the routing decision itself.
  • Manual provider override: explicit provider selection on a ChatRequest, on air.chat(...) via AIRConfig.default_provider, and per call on Session.chat(message, provider=...).
  • Local session storage: air.session(session_id) returning a Session with chat, history, clear, and delete. Backed by an in memory store by default, or a local SQLite file when AIR(persist=...) is used. Only role, content, provider name, model, and timestamp are stored; API keys and provider objects are never stored.
  • Context optimization: a configurable token budget (ContextBudget) that trims oversized individual messages and, for long conversations, replaces older messages with a summary (a local, no-API-call summary by default, or an AI assisted one if explicitly enabled) while always preserving the full original history in the session store. Optimization metadata (original_estimated_tokens, optimized_estimated_tokens, estimated_tokens_saved, compression_applied) is returned on every ChatResponse.
  • Structured events: a unified Event dataclass for provider switches, exhaustion, recovery, usage thresholds, and capacity based skips, deliverable to application code through air.on_event(callback)/air.off_event(callback) (sync or async callbacks, isolated from routing failures) and inspectable directly on ChatResponse.structured_events, with no dependency on console output or TTS.
  • An optional TTS announcer (air.announcer) that can speak selected structured events through a pluggable TTSBackend, with a free SystemTTSBackend convenience implementation for macOS, Linux, and Windows. TTS is off by default and failures never affect routing.
  • Configuration validation: invalid routing or context_optimization values raise ConfigurationError at AIR() construction time instead of being silently ignored.
  • AIR.close() for releasing the underlying SQLite connection when using persistent sessions.

Test coverage

127 tests, all passing as of this documentation pass, covering provider adapters, routing/fallback, health/capacity tracking, intelligent routing, sessions (in memory and SQLite), context optimization, the structured event system, TTS/announcer behavior (including Windows TTS input handling), and configuration validation.