Configuration

This document provides comprehensive documentation for configuration classes in the ViewAI Python SDK.

Overview

The ViewAI SDK provides flexible configuration management through:

• ClientConfiguration: Main configuration class for client setup

• RetryStrategy: Configurable retry logic with exponential backoff

• Environment Variables: Load configuration from environment

---

ClientConfiguration

Enterprise client configuration with validation.

Overview

The ClientConfiguration dataclass holds all configuration parameters for the ViewAI client, providing validation, defaults, and environment variable support.

Initialization

@dataclass
class ClientConfiguration:
    """Enterprise client configuration with validation."""

Parameters:

• Required:

  • api_key (str): API authentication key

• API Configuration:

  • base_url (str): Base URL for API requests (default: "https://qi1gp3ed2m.execute-api.us-west-1.amazonaws.com")

• Timeout Configuration:

  • connection_timeout (int): Connection timeout in seconds (default: 10)

  • read_timeout (int): Read timeout in seconds (default: 30)

• Retry Configuration:

  • max_retries (int): Maximum number of retry attempts (default: 3)

  • retry_backoff_factor (float): Exponential backoff multiplier for retries (default: 2.0)

• Resource Limits:

  • max_upload_size_mb (int): Maximum file upload size in megabytes (default: 100)

  • max_batch_size (int): Maximum number of items in batch operations (default: 10000)

• Logging Configuration:

  • log_level (int): Logging level (default: logging.INFO)

  • log_file (str, optional): Optional log file path (default: None)

• Performance Configuration:

  • enable_caching (bool): Enable response caching (default: True)

  • cache_ttl_seconds (int): Cache time-to-live in seconds (default: 300)

  • connection_pool_size (int): HTTP connection pool size (default: 10)

• Feature Flags:

  • enable_telemetry (bool): Enable telemetry and metrics collection (default: False)

  • enable_compression (bool): Enable request/response compression (default: True)

• Context Defaults:

  • default_workspace (str, optional): Default workspace name or ID (default: None)

  • default_project (str, optional): Default project name or ID (default: None)

  • default_model_id (str, optional): Default model ID for predictions (default: None)

---

Basic Usage

from viewai_client.config import ClientConfiguration
from viewai_client import ViewAIClient

# Simple configuration
config = ClientConfiguration(api_key="your-api-key")

# With custom settings
config = ClientConfiguration(
    api_key="your-api-key",
    base_url="https://api.viewai.ca",
    connection_timeout=15,
    read_timeout=60,
    max_retries=5
)

# Use with client
client = ViewAIClient(config=config)

---

Advanced Configuration

import logging
from viewai_client.config import ClientConfiguration

config = ClientConfiguration(
    # Required
    api_key="your-api-key",

    # API
    base_url="https://api.viewai.ca",

    # Timeouts
    connection_timeout=15,
    read_timeout=60,

    # Retry
    max_retries=5,
    retry_backoff_factor=2.0,

    # Resource limits
    max_upload_size_mb=200,
    max_batch_size=20000,

    # Logging
    log_level=logging.DEBUG,
    log_file="/var/log/viewai.log",

    # Performance
    enable_caching=True,
    cache_ttl_seconds=600,
    connection_pool_size=20,

    # Features
    enable_telemetry=True,
    enable_compression=True,

    # Defaults
    default_workspace="production",
    default_project="ml-models",
    default_model_id="model-123"
)

# Validate configuration
try:
    config.validate()
    print("Configuration is valid")
except ValueError as e:
    print(f"Invalid configuration: {e}")

---

Methods

validate()

Validate configuration values.

Raises:

• ValueError: If any configuration value is invalid

Example:

config = ClientConfiguration(api_key="")

try:
    config.validate()
except ValueError as e:
    print(f"Validation error: {e}")
    # Output: Validation error: Configuration validation failed:
    #   - API key is required and cannot be empty

Validation Rules:

• API key must not be empty

• Base URL must start with http:// or https://

• Timeouts must be positive

• Connection timeout cannot exceed read timeout

• Max retries must be between 0 and 10

• Retry backoff factor must be positive

• Resource limits must be positive

• Cache TTL cannot be negative

• Connection pool size must be positive

---

from_environment(api_key_env_var="VIEWAI_API_KEY", base_url_env_var="VIEWAI_API_BASE_URL")

Create configuration from environment variables.

Parameters:

• api_key_env_var (str): Environment variable name for API key (default: "VIEWAI_API_KEY")

• base_url_env_var (str): Environment variable name for base URL (default: "VIEWAI_API_BASE_URL")

Returns: ClientConfiguration instance populated from environment

Raises:

• ValueError: If required environment variables are missing

Environment Variables:

• VIEWAI_API_KEY: API authentication key (required)

• VIEWAI_API_BASE_URL: Base API URL (optional)

• VIEWAI_TIMEOUT: Request timeout in seconds (optional)

• VIEWAI_MAX_RETRIES: Max retry attempts (optional)

• VIEWAI_LOG_LEVEL: Logging level (optional)

• VIEWAI_DEFAULT_WORKSPACE: Default workspace (optional)

• VIEWAI_DEFAULT_PROJECT: Default project (optional)

• VIEWAI_DEFAULT_MODEL_ID: Default model ID (optional)

Example:

# Set environment variables
export VIEWAI_API_KEY="your-api-key"
export VIEWAI_API_BASE_URL="https://api.viewai.ca"
export VIEWAI_TIMEOUT="60"
export VIEWAI_MAX_RETRIES="5"
export VIEWAI_LOG_LEVEL="DEBUG"
export VIEWAI_DEFAULT_WORKSPACE="production"

from viewai_client.config import ClientConfiguration
from viewai_client import ViewAIClient

# Load from environment
config = ClientConfiguration.from_environment()

# Use with client
client = ViewAIClient(config=config)

Custom Environment Variable Names:

config = ClientConfiguration.from_environment(
    api_key_env_var="MY_API_KEY",
    base_url_env_var="MY_BASE_URL"
)

---

to_dict()

Convert configuration to dictionary.

Returns: Dictionary representation of configuration

Example:

config = ClientConfiguration(api_key="your-key")
config_dict = config.to_dict()

print(config_dict)

# {

#     'api_key': '***',  # Masked for security

#     'base_url': 'https://qi1gp3ed2m.execute-api.us-west-1.amazonaws.com',

#     'connection_timeout': 10,

#     'read_timeout': 30,

#     'max_retries': 3,

#     ...

# }

Note: API key is masked in the output for security.

---

Complete Configuration Example

import logging
from viewai_client import ViewAIClient
from viewai_client.config import ClientConfiguration

# Production configuration
production_config = ClientConfiguration(
    # Authentication
    api_key="prod-api-key",

    # API endpoint
    base_url="https://api.viewai.ca",

    # Aggressive timeouts for production
    connection_timeout=5,
    read_timeout=30,

    # Retry strategy
    max_retries=3,
    retry_backoff_factor=2.0,

    # Resource limits
    max_upload_size_mb=100,
    max_batch_size=10000,

    # Production logging
    log_level=logging.WARNING,
    log_file="/var/log/viewai/production.log",

    # Performance optimization
    enable_caching=True,
    cache_ttl_seconds=300,
    connection_pool_size=20,

    # Monitoring
    enable_telemetry=True,
    enable_compression=True,

    # Production defaults
    default_workspace="production",
    default_project="ml-models"
)

# Validate
production_config.validate()

# Use with client
with ViewAIClient(config=production_config) as client:
    # Check health
    diagnostics = client.execute_comprehensive_diagnostics()

    # Make predictions
    result = client.execute_prediction(data, model_id="model-123")

---

RetryStrategy

Configurable retry strategy with exponential backoff and jitter.

Overview

The RetryStrategy class implements retry logic with exponential backoff and jitter for resilient API communication.

Initialization

@dataclass
class RetryStrategy:
    """Configurable retry strategy with exponential backoff."""

Parameters:

• max_attempts (int): Maximum number of retry attempts (default: 3)

• initial_delay (float): Initial delay between retries in seconds (default: 1.0)

• max_delay (float): Maximum delay between retries in seconds (default: 60.0)

• exponential_base (float): Base for exponential backoff calculation (default: 2.0)

• jitter (bool): Whether to add random jitter to delays (default: True)

---

Basic Usage

from viewai_client.config import RetryStrategy

# Default strategy
strategy = RetryStrategy()

# Custom strategy
strategy = RetryStrategy(
    max_attempts=5,
    initial_delay=1.0,
    max_delay=60.0,
    exponential_base=2.0,
    jitter=True
)

---

Methods

calculate_delay(attempt)

Calculate delay for a given retry attempt with exponential backoff.

Parameters:

• attempt (int): The retry attempt number (1-indexed)

Returns: Delay in seconds before next retry (float)

Formula:

delay = min(initial_delay * (base ^ (attempt - 1)), max_delay)

If jitter enabled, delay is randomized between 50-100% of calculated value.

Example:

strategy = RetryStrategy()

for attempt in range(1, 4):
    delay = strategy.calculate_delay(attempt)
    print(f"Attempt {attempt}: wait {delay:.2f}s")

# Output:

# Attempt 1: wait 0.87s  (jitter applied)

# Attempt 2: wait 1.56s  (jitter applied)

# Attempt 3: wait 3.21s  (jitter applied)

Without Jitter:

strategy = RetryStrategy(jitter=False)

for attempt in range(1, 5):
    delay = strategy.calculate_delay(attempt)
    print(f"Attempt {attempt}: wait {delay:.2f}s")

# Output:

# Attempt 1: wait 1.00s  (1.0 * 2^0)

# Attempt 2: wait 2.00s  (1.0 * 2^1)

# Attempt 3: wait 4.00s  (1.0 * 2^2)

# Attempt 4: wait 8.00s  (1.0 * 2^3)

---

should_retry(attempt, exception)

Determine if operation should be retried.

Parameters:

• attempt (int): Current attempt number

• exception (Exception): Exception that occurred

Returns: True if should retry, False otherwise

Example:

strategy = RetryStrategy(max_attempts=3)

for attempt in range(1, 5):
    try:
        # Some operation that might fail
        risky_operation()
        break
    except Exception as e:
        if strategy.should_retry(attempt, e):
            delay = strategy.calculate_delay(attempt)
            print(f"Retrying in {delay:.2f}s (attempt {attempt})")
            time.sleep(delay)
        else:
            print("Max retries reached")
            raise

Note: Override this method in subclasses to implement custom retry logic based on exception type.

---

validate()

Validate retry strategy configuration.

Raises:

• ValueError: If configuration is invalid

Example:

strategy = RetryStrategy(
    max_attempts=-1,  # Invalid
    initial_delay=0,  # Invalid
)

try:
    strategy.validate()
except ValueError as e:
    print(f"Validation error: {e}")

Validation Rules:

• Max attempts must be positive

• Initial delay must be positive

• Max delay must be positive

• Initial delay cannot exceed max delay

• Exponential base must be greater than 1.0

---

Complete Retry Example

import time
from viewai_client.config import RetryStrategy
from viewai_client.exceptions import NetworkError, APIError

# Configure retry strategy
strategy = RetryStrategy(
    max_attempts=5,
    initial_delay=1.0,
    max_delay=30.0,
    exponential_base=2.0,
    jitter=True
)

# Validate
strategy.validate()

# Use in retry loop
def make_request_with_retry():
    for attempt in range(1, strategy.max_attempts + 1):
        try:
            # Make API request
            response = api_client.make_request()
            return response

        except (NetworkError, APIError) as e:
            if strategy.should_retry(attempt, e):
                delay = strategy.calculate_delay(attempt)
                print(f"Request failed, retrying in {delay:.2f}s...")
                time.sleep(delay)
            else:
                print(f"Max retries ({strategy.max_attempts}) exceeded")
                raise

    raise RuntimeError("Request failed after all retries")

# Execute with retry
result = make_request_with_retry()

---

Custom Retry Strategy

Create a custom retry strategy by subclassing:

from viewai_client.config import RetryStrategy
from viewai_client.exceptions import NetworkError, TimeoutError

class CustomRetryStrategy(RetryStrategy):
    """Custom retry strategy that only retries on specific exceptions."""

    def should_retry(self, attempt, exception):
        # Don't retry if max attempts reached
        if not super().should_retry(attempt, exception):
            return False

        # Only retry on network and timeout errors
        if isinstance(exception, (NetworkError, TimeoutError)):
            return True

        # Don't retry other exceptions
        return False

# Use custom strategy
strategy = CustomRetryStrategy(max_attempts=5)

try:
    # Operation with custom retry logic
    result = make_request()
except Exception as e:
    if strategy.should_retry(1, e):
        print("Will retry")
    else:
        print("Won't retry")

---

Configuration Best Practices

Development Configuration

from viewai_client.config import ClientConfiguration
import logging

dev_config = ClientConfiguration(
    api_key="dev-api-key",
    base_url="https://dev-api.viewai.ca",

    # Longer timeouts for debugging
    connection_timeout=30,
    read_timeout=120,

    # More retries for unstable dev environment
    max_retries=5,

    # Debug logging
    log_level=logging.DEBUG,
    log_file="viewai_dev.log",

    # Disable caching for fresh results
    enable_caching=False,

    # Enable telemetry for debugging
    enable_telemetry=True,

    # Dev workspace
    default_workspace="development"
)

---

Production Configuration

from viewai_client.config import ClientConfiguration
import logging

prod_config = ClientConfiguration(
    api_key="prod-api-key",
    base_url="https://api.viewai.ca",

    # Aggressive timeouts
    connection_timeout=5,
    read_timeout=30,

    # Conservative retries
    max_retries=3,

    # Warning level logging
    log_level=logging.WARNING,
    log_file="/var/log/viewai/production.log",

    # Enable caching for performance
    enable_caching=True,
    cache_ttl_seconds=300,

    # Large connection pool for concurrency
    connection_pool_size=50,

    # Production optimization
    enable_compression=True,

    # Production workspace
    default_workspace="production"
)

---

Testing Configuration

from viewai_client.config import ClientConfiguration

test_config = ClientConfiguration(
    api_key="test-api-key",
    base_url="https://test-api.viewai.ca",

    # Fast timeouts for quick test feedback
    connection_timeout=5,
    read_timeout=10,

    # No retries in tests
    max_retries=0,

    # No caching in tests
    enable_caching=False,

    # Test workspace
    default_workspace="testing"
)

---

Environment-Based Configuration

Use environment variables for different deployment environments:

import os
from viewai_client import ViewAIClient
from viewai_client.config import ClientConfiguration

# Determine environment
env = os.getenv("ENVIRONMENT", "development")

if env == "production":
    # Load production config from environment
    config = ClientConfiguration.from_environment()

elif env == "staging":
    # Load staging config
    config = ClientConfiguration(
        api_key=os.getenv("STAGING_API_KEY"),
        base_url="https://staging-api.viewai.ca",
        default_workspace="staging"
    )

else:
    # Development config
    config = ClientConfiguration(
        api_key=os.getenv("DEV_API_KEY", "dev-key"),
        base_url="https://dev-api.viewai.ca",
        log_level=logging.DEBUG,
        default_workspace="development"
    )

# Validate and create client
config.validate()
client = ViewAIClient(config=config)

---

See Also

• ViewAIClient - Main client class

• Exceptions - Exception handling

• Service Classes - Service documentation