Configuration Options

The options module provides configuration classes for customizing client behavior, connection settings, and processing options.

AthenaOptions

class AthenaOptions(host='localhost', resize_images=True, compress_images=True, deployment_id='default', affiliate='default', max_batch_size=10, correlation_provider=<class 'resolver_athena_client.client.correlation.HashCorrelationProvider'>, timeout=120.0, keepalive_interval=None)

Bases: object

Options for configuring the Athena client behavior.

This class provides configuration options for controlling how the client connects to and interacts with the Athena service.

Parameters:

• host (str)

• resize_images (bool)

• compress_images (bool)

• deployment_id (str)

• affiliate (str)

• max_batch_size (int)

• correlation_provider (type[CorrelationProvider])

• timeout (float | None)

• keepalive_interval (float | None)

host

The hostname of the Athena service to connect to. Defaults to “localhost”.

Type:

str

resize_images

Whether to automatically resize images before sending. When True, images will be resized to the optimal size for the model. Defaults to True.

Type:

bool

compress_images

Whether to compress images using Brotli compression. Enabling this reduces network bandwidth usage but adds slight CPU overhead. Defaults to True.

Type:

bool

deployment_id

The ID of the model deployment to use for inference. This identifies which model version to use on the server. Defaults to “default”.

Type:

str

affiliate

The affiliate ID to associate with requests. Used for tracking and billing purposes. Defaults to “default”.

Type:

str

max_batch_size

Maximum number of images to batch together in one request. Larger batches improve throughput but increase latency. Defaults to 100.

Type:

int

correlation_provider

Class that generates correlation IDs for requests. Used for request tracing and debugging. Defaults to HashCorrelationProvider.

Type:

type[resolver_athena_client.client.correlation.CorrelationProvider]

timeout

Optional timeout in seconds for receiving responses. When None, allows infinite streaming with no timeout. When set to a float value, stream will stop after that many seconds without receiving a response. Defaults to 120.0 seconds.

Type:

float | None

keepalive_interval

Optional interval in seconds for sending keepalive requests to maintain stream connection. When None, uses a sensible default based on server configuration. When set to a float value, sends empty requests at this interval to prevent stream timeouts. Defaults to None (auto-detect).

Type:

float | None

Main configuration class for the Athena client. Controls connection settings, processing options, and performance tuning.

Example:

>>> options = AthenaOptions(
...     host="athena.example.com",
...     deployment_id="prod-deployment",
...     resize_images=True,
...     compress_images=True,
...     timeout=120.0,
...     affiliate="my-service"
... )

host: str = 'localhost'

resize_images: bool = True

compress_images: bool = True

deployment_id: str = 'default'

affiliate: str = 'default'

max_batch_size: int = 10

correlation_provider

alias of HashCorrelationProvider

timeout: float | None = 120.0

keepalive_interval: float | None = None

__init__(host='localhost', resize_images=True, compress_images=True, deployment_id='default', affiliate='default', max_batch_size=10, correlation_provider=<class 'resolver_athena_client.client.correlation.HashCorrelationProvider'>, timeout=120.0, keepalive_interval=None)

Parameters:

• host (str)

• resize_images (bool)

• compress_images (bool)

• deployment_id (str)

• affiliate (str)

• max_batch_size (int)

• correlation_provider (type[CorrelationProvider])

• timeout (float | None)

• keepalive_interval (float | None)

Return type:

None

Configuration Parameters

Connection Settings

hoststr

The hostname or address of the Athena service.

Example: "athena.example.com" or "localhost:50051"

deployment_idstr

The deployment identifier for the specific model version to use.

Example: "prod-v1.2" or "dev-latest"

timeoutfloat, optional

Maximum time in seconds to wait for responses. Set to None for no timeout.

Default: 120.0

keepalive_intervalfloat, optional

Interval in seconds for sending keepalive messages to maintain connection.

Default: 30.0

max_message_sizeint, optional

Maximum size in bytes for gRPC messages.

Default: 100 * 1024 * 1024 (100MB)

Processing Options

resize_imagesbool, optional

Whether to automatically resize images for optimal processing.

Default: True

compress_imagesbool, optional

Whether to compress image data using Brotli compression.

Default: True

affiliatestr, optional

Affiliate identifier for tracking and billing purposes.

Example: "my-organization"

Configuration Examples

Development Configuration

from resolver_athena_client.client.athena_options import AthenaOptions

# Development setup
dev_options = AthenaOptions(
    host="localhost:50051",
    deployment_id="dev-latest",
    resize_images=True,
    compress_images=False,  # Disable for faster local testing
    timeout=60.0,
    affiliate="development"
)

Production Configuration

# Production setup
prod_options = AthenaOptions(
    host="athena.prod.example.com",
    deployment_id="prod-v1.2",
    resize_images=True,
    compress_images=True,  # Enable for bandwidth efficiency
    timeout=300.0,  # Longer timeout for production loads
    keepalive_interval=60.0,
    max_message_size=200 * 1024 * 1024,  # 200MB for large images
    affiliate="production-service"
)

High-Throughput Configuration

# High-throughput setup
high_throughput_options = AthenaOptions(
    host="athena.cluster.example.com",
    deployment_id="high-perf-v2.0",
    resize_images=True,
    compress_images=True,
    timeout=None,  # No timeout for long-running streams
    keepalive_interval=30.0,
    max_message_size=500 * 1024 * 1024,  # 500MB for batch processing
    affiliate="batch-processor"
)

Low-Latency Configuration

# Low-latency setup
low_latency_options = AthenaOptions(
    host="athena.edge.example.com",
    deployment_id="fast-inference",
    resize_images=False,  # Skip resizing for speed
    compress_images=False,  # Skip compression for speed
    timeout=10.0,  # Short timeout for real-time use
    keepalive_interval=5.0,  # Frequent keepalives
    affiliate="real-time-service"
)

Environment-Based Configuration

import os
from resolver_athena_client.client.athena_options import AthenaOptions

# Load from environment variables
options = AthenaOptions(
    host=os.getenv("ATHENA_HOST", "localhost:50051"),
    deployment_id=os.getenv("ATHENA_DEPLOYMENT_ID", "default"),
    resize_images=os.getenv("ATHENA_RESIZE_IMAGES", "true").lower() == "true",
    compress_images=os.getenv("ATHENA_COMPRESS_IMAGES", "true").lower() == "true",
    timeout=float(os.getenv("ATHENA_TIMEOUT", "120.0")),
    affiliate=os.getenv("ATHENA_AFFILIATE", "default")
)

Performance Tuning

Image Processing

resize_images=True:

• Automatically optimizes image dimensions for the model

• Reduces processing time and bandwidth

• Recommended for most use cases

resize_images=False:

• Uses original image dimensions

• Faster if images are already optimized

• May increase bandwidth usage

compress_images=True:

• Uses Brotli compression to reduce bandwidth

• Slight CPU overhead for compression/decompression

• Recommended for network-constrained environments

compress_images=False:

• No compression overhead

• Higher bandwidth usage

• Recommended for local or high-bandwidth connections

Connection Tuning

timeout:

• Set based on expected response times

• Use None for long-running streams

• Balance between responsiveness and reliability

keepalive_interval:

• Shorter intervals for unreliable networks

• Longer intervals for stable connections

• Affects resource usage on both client and server

max_message_size:

• Increase for large images or batch processing

• Balance with memory usage

• Consider network MTU and buffering

Best Practices

Environment-Specific Settings

def create_options_for_environment(env: str) -> AthenaOptions:
    """Create options appropriate for the deployment environment."""
    base_config = {
        "resize_images": True,
        "affiliate": f"service-{env}"
    }

    if env == "development":
        return AthenaOptions(
            host="localhost:50051",
            deployment_id="dev-latest",
            compress_images=False,
            timeout=60.0,
            **base_config
        )
    elif env == "staging":
        return AthenaOptions(
            host="athena.staging.example.com",
            deployment_id="staging-v1.0",
            compress_images=True,
            timeout=120.0,
            **base_config
        )
    elif env == "production":
        return AthenaOptions(
            host="athena.prod.example.com",
            deployment_id="prod-v1.2",
            compress_images=True,
            timeout=300.0,
            keepalive_interval=60.0,
            **base_config
        )
    else:
        raise ValueError(f"Unknown environment: {env}")

Configuration Validation

def validate_options(options: AthenaOptions) -> None:
    """Validate configuration options."""
    if not options.host:
        raise ValueError("Host must be specified")

    if not options.deployment_id:
        raise ValueError("Deployment ID must be specified")

    if options.timeout is not None and options.timeout <= 0:
        raise ValueError("Timeout must be positive or None")

    if options.keepalive_interval <= 0:
        raise ValueError("Keepalive interval must be positive")

    if options.max_message_size <= 0:
        raise ValueError("Max message size must be positive")

Configuration from Files

import json
from pathlib import Path
from resolver_athena_client.client.athena_options import AthenaOptions

def load_options_from_file(config_path: Path) -> AthenaOptions:
    """Load configuration from a JSON file."""
    with open(config_path) as f:
        config = json.load(f)

    return AthenaOptions(**config)

# Example config.json:
# {
#   "host": "athena.example.com",
#   "deployment_id": "prod-v1.2",
#   "resize_images": true,
#   "compress_images": true,
#   "timeout": 120.0,
#   "affiliate": "my-service"
# }

Migration Guide

From Version 0.1.x

If upgrading from earlier versions:

# Old approach (deprecated)
# client = AthenaClient(host="...", deployment_id="...")

# New approach
options = AthenaOptions(
    host="your-host",
    deployment_id="your-deployment-id"
)
client = AthenaClient(channel, options)

Common Issues

Invalid Host Format

# Incorrect - missing port for non-standard ports
# options = AthenaOptions(host="athena.example.com")

# Correct - include port if non-standard
options = AthenaOptions(host="athena.example.com:443")

Timeout Configuration

# For long-running operations
options = AthenaOptions(
    host="your-host",
    deployment_id="your-deployment",
    timeout=None  # No timeout
)

# For real-time applications
options = AthenaOptions(
    host="your-host",
    deployment_id="your-deployment",
    timeout=5.0  # 5 second timeout
)

Memory Usage

# For memory-constrained environments
options = AthenaOptions(
    host="your-host",
    deployment_id="your-deployment",
    max_message_size=10 * 1024 * 1024,  # 10MB limit
    compress_images=True  # Reduce bandwidth
)

See Also

• Client Interface - Client interface using these options

• Examples - Complete usage examples

• Authentication - Authentication configuration