Configuration — Python SDK

Client Constructor

Both InfiniumClient and AsyncInfiniumClient accept the same parameters:

from infinium import InfiniumClient

client = InfiniumClient(
    agent_id="your-agent-id",
    agent_secret="your-agent-secret",
    base_url="https://platform.i42m.ai/api/v1",
    timeout=30.0,
    max_retries=3,
    enable_rate_limiting=True,
    requests_per_second=10.0,
    user_agent="infinium-python/1.0.0",
    enable_logging=False,
    log_level="INFO",
    verify_ssl=True,
)

Parameters

Parameter	Type	Default	Description
`agent_id`	`str`	required	Your agent’s UUID from the Infinium platform
`agent_secret`	`str`	required	Your agent’s secret key
`base_url`	`str`	`"https://platform.i42m.ai/api/v1"`	API endpoint
`timeout`	`float`	`30.0`	Per-request timeout in seconds
`max_retries`	`int`	`3`	Number of retry attempts for retryable errors
`enable_rate_limiting`	`bool`	`True`	Enable client-side rate limiting
`requests_per_second`	`float`	`10.0`	Maximum requests per second (when rate limiting is enabled)
`user_agent`	`str`	`"infinium-python/1.0.0"`	User-Agent header value
`enable_logging`	`bool`	`False`	Enable SDK debug logging
`log_level`	`str`	`"INFO"`	Logging level (when logging is enabled)
`verify_ssl`	`bool`	`True`	Verify SSL certificates

Context Managers

Both clients implement context manager protocols for automatic cleanup:

# Sync
with InfiniumClient(agent_id="...", agent_secret="...") as client:
    client.send_task(...)
# client.close() called automatically

# Async
async with AsyncInfiniumClient(agent_id="...", agent_secret="...") as client:
    await client.send_task(...)
# client.close() called automatically

If you don’t use a context manager, call close() explicitly when done.

SSL Configuration

For local development with self-signed certificates:

client = InfiniumClient(
    agent_id="...",
    agent_secret="...",
    verify_ssl=False,  # Disable SSL verification
)

Warning: Never disable SSL verification in production.

Logging

Enable SDK logging for debugging:

client = InfiniumClient(
    agent_id="...",
    agent_secret="...",
    enable_logging=True,
    log_level="DEBUG",  # DEBUG, INFO, WARNING, ERROR
)

Or configure logging manually:

from infinium import setup_logging

setup_logging(level="DEBUG")

This configures Python’s logging module for the infinium logger.

Rate Limiting

The built-in rate limiter uses a token bucket algorithm:

client = InfiniumClient(
    agent_id="...",
    agent_secret="...",
    enable_rate_limiting=True,
    requests_per_second=10.0,  # 10 requests per second
)

Thread-safe for sync usage
Async-safe for async usage
Burst size: 20 (allows short bursts above the rate)
Automatically throttles when the limit is reached

To disable:

client = InfiniumClient(
    agent_id="...",
    agent_secret="...",
    enable_rate_limiting=False,
)

Retry Configuration

Retries use exponential backoff with jitter:

client = InfiniumClient(
    agent_id="...",
    agent_secret="...",
    max_retries=3,   # Retry up to 3 times
    timeout=30.0,    # 30 second timeout per request
)

Only retryable errors trigger retries (5xx, network errors, timeouts). See Error Handling for the full list.

API Endpoints

The SDK communicates with three endpoints:

Method	Path	Auth	Purpose
POST	`/agents/{agentId}/trace`	Agent credentials	Send a trace
GET	`/agents/{agentId}/interpreted-result/{traceId}`	Agent credentials	Get Maestro interpretation
GET	`/prompts/{promptId}/v/{version}`	Prompt credentials	Fetch Prompt Studio content

Agent credentials are sent as x-agent-id and x-agent-key headers. Prompt credentials use x-prompt-id and x-prompt-key.