AIR

Events reference

Import: from air.events import Event, PROVIDER_SWITCH, PROVIDER_EXHAUSTED, PROVIDER_RECOVERED, USAGE_THRESHOLD, ALL_EXHAUSTED, CAPACITY_RESTORED, CAPACITY_SKIPPED.

See ../features/structured-events.md for the full narrative explanation, subscribing, and examples. This page is the field level reference.

Event

python
@dataclass
class Event:
    type: str
    message: str
    provider: str | None = None
    model: str | None = None
    reason: str | None = None
    previous_provider: str | None = None
    next_provider: str | None = None
    used_tokens: int | None = None
    limit_tokens: int | None = None
    threshold: float | None = None
    estimated_tokens: int | None = None
    remaining_tokens: int | None = None

model is present in the dataclass but is not populated by any of the builder functions in the current source; it is always None on every event AIR currently emits.

Event type constants and which fields they populate

| constant | value | populated fields (besides type, message) | |---|---|---| | PROVIDER_SWITCH | "provider_switch" | provider (= previous), previous_provider, next_provider, reason | | PROVIDER_EXHAUSTED | "provider_exhausted" | provider, reason (new status string) | | PROVIDER_RECOVERED | "provider_recovered" | provider, reason (new status string, "available") | | (unnamed constant, literal "health_change") | "health_change" | provider, reason (new status string) | | USAGE_THRESHOLD | "usage_threshold" | provider, used_tokens, limit_tokens, threshold | | CAPACITY_RESTORED | "capacity_restored" | provider | | CAPACITY_SKIPPED | "capacity_skipped" | provider, and either (estimated_tokens, remaining_tokens) for a capacity based skip, or reason="exhausted" with no token fields for an exhausted-provider skip | | ALL_EXHAUSTED | "all_exhausted" | none (message only) |

Builder functions

These construct Event instances and are used internally by AIR; they are documented here because they are the definitive source of each event's message text and field population. All are in air.events.

  • provider_switch_event(from_provider, to_provider, reason) -> Event
  • health_event(provider, previous_status, new_status, event_type) -> Event
  • capacity_skipped_event(provider, estimated_tokens, remaining_tokens) -> Event
  • usage_threshold_event(provider, used_tokens, limit_tokens, threshold) -> Event
  • capacity_restored_event(provider) -> Event
  • exhausted_skip_event(provider) -> Event
  • all_exhausted_event() -> Event

display_name

air.events.display_name(provider_name) -> str maps known provider names to a display form ("xai" to "xAI", "gemini" to "Gemini", "groq" to "Groq", "openrouter" to "OpenRouter"), falling back to provider_name.title() for anything else (including custom providers). Used only to build message text, not any structured field.