Advanced Usage

Error Handling

The SDK uses custom exceptions to provide clear error messages:

from airia import AiriaAPIError, AiriaClient

# Works with both API keys and bearer tokens
client = AiriaClient(api_key="your_api_key")
# Or: client = AiriaClient.with_bearer_token(bearer_token="your_bearer_token")

try:
    response = client.execute_pipeline(
        pipeline_id="invalid_id",
        user_input="test"
    )
except AiriaAPIError as e:
    print(f"API error: {e.status_code} - {e.message}")

Configuring Logging

The SDK uses Python's standard logging module with colored output for console logging (using ANSI codes, no additional dependencies required).

Basic Logging Configuration

import sys
from airia import configure_logging

# Basic configuration (logs to stderr with colors)
logger = configure_logging()

# Disable colors if needed
logger = configure_logging(use_colors=False)

# Advanced configuration with custom format
file_logger = configure_logging(
    format_string="[%(correlation_id)s] %(asctime)s | %(levelname)s | %(message)s",
    level="DEBUG",
    sink="app.log",  # Colors automatically disabled for file output
    include_correlation_id=True
)

# Console output with custom format
console_logger = configure_logging(
    level="INFO",
    sink=sys.stdout,
    use_colors=True  # Enabled by default for console
)

Color Scheme:

• DEBUG: Cyan
• INFO: Green
• WARNING: Yellow
• ERROR: Red
• CRITICAL: Magenta
• Correlation ID: Magenta
• Timestamp: Grey

Correlation ID Tracking

The SDK includes built-in correlation ID tracking for request tracing:

from airia import set_correlation_id, get_correlation_id, clear_correlation_id

# Set a specific correlation ID
set_correlation_id("request-123")

# Get the current correlation ID
current_id = get_correlation_id()

# Use auto-generated correlation ID
auto_id = set_correlation_id()  # Generates a UUID

# Clear the correlation ID
clear_correlation_id()