orchestrata_ultimate.agents.constants

Reference › orchestrata_ultimate › agents › constants

constants holds the default configuration values of the Multi-Agent Runtime. It has no internal imports; PoolConfig and TaskDefinition in types, the pool and the hierarchy consume them, and each default can be overridden through the pool config, the task definition or dependency injection.

The values fall into groups. Pool defaults: zero minimum and five maximum instances, scale-up at 0.8 utilisation, scale-down at 0.2, and a 300 second idle timeout. Task defaults: a 300 second timeout and priority 5. Lifecycle defaults: a spawn timeout of 100 ms, a 30 second heartbeat interval, three recovery attempts and a 30 second graceful-shutdown timeout. The Redis key prefixes for instances, tasks, pools and coordination state all start with orchestrata:. PROLOG_MODULE names the multiagent Prolog module, MAX_HIERARCHY_DEPTH is 5, and the default resource budget is one CPU core, 512 MB of memory and 100 MB of storage. The PERF_* constants record the p95 latency targets for spawn, task assignment, Prolog queries, pool acquire, leader election and a five-way fan-out.

At a glance

Class diagram

No classes; see Functions.

Dependency diagram

API

Constants

Source

Permalink: https://gitlab.com/MSamy/orchestrata-ultimate-architecture/-/blob/a4cbc2bdf/src/orchestrata_ultimate/agents/constants.py

"""Multi-Agent Runtime configuration constants.

Centralizes default values for the runtime system. These can be
overridden via PoolConfig, TaskDefinition, or DI configuration.

Author: Mohamed
Spec: 005-multi-agent (amended)
"""

# Spec: 005 - Multi-Agent System

# ============================================================================
# Pool Defaults
# ============================================================================

DEFAULT_POOL_MIN: int = 0  # No pre-warmed instances; spawn on demand
DEFAULT_POOL_MAX: int = (
    5  # Caps concurrent Volk instances per type to bound resource usage
)
DEFAULT_SCALE_UP_THRESHOLD: float = 0.8  # Scale up when 80% of pool slots are occupied
DEFAULT_SCALE_DOWN_THRESHOLD: float = 0.2  # Scale down when utilisation drops below 20%
DEFAULT_IDLE_TIMEOUT_SECONDS: float = (
    300.0  # 5 minutes idle before a Volk instance is reaped
)

# ============================================================================
# Task Defaults
# ============================================================================

DEFAULT_TASK_TIMEOUT_SECONDS: float = 300.0
DEFAULT_TASK_PRIORITY: int = 5  # CXP scale 0-10, 5 = normal

# ============================================================================
# Runtime Defaults
# ============================================================================

DEFAULT_SPAWN_TIMEOUT_MS: int = 100
DEFAULT_HEARTBEAT_INTERVAL_SECONDS: float = 30.0
DEFAULT_MAX_RECOVERY_ATTEMPTS: int = 3
DEFAULT_GRACEFUL_SHUTDOWN_TIMEOUT_SECONDS: float = 30.0

# ============================================================================
# Redis Key Prefixes
# ============================================================================

REDIS_VOLK_INSTANCE_PREFIX: str = "orchestrata:volk:instance"
REDIS_TASK_PREFIX: str = "orchestrata:task"
REDIS_POOL_PREFIX: str = "orchestrata:pool"
REDIS_COORDINATION_PREFIX: str = "orchestrata:coordination"

# ============================================================================
# Prolog
# ============================================================================

PROLOG_MODULE: str = "multiagent"
MAX_HIERARCHY_DEPTH: int = (
    5  # Prolog hierarchy traversal depth; prevents infinite loops in circular delegation chains
)

# ============================================================================
# Prolog Resource Defaults (for can_register_volk/3)
# ============================================================================

DEFAULT_CPU_CORES: int = 1
DEFAULT_MEMORY_MB: int = 512
DEFAULT_STORAGE_MB: int = 100

# ============================================================================
# Performance Targets (for benchmark assertions in tests)
# ============================================================================

PERF_SPAWN_P95_MS: int = 100
PERF_TASK_ASSIGN_P95_MS: int = 50
PERF_PROLOG_QUERY_P95_MS: int = 5
PERF_POOL_ACQUIRE_P95_MS: int = 50
PERF_LEADER_ELECTION_P95_MS: int = 20
PERF_FAN_OUT_5_P95_MS: int = 200