Configuration API

from marsys.coordination.config import ExecutionConfig, StatusConfig, ErrorHandlingConfig

ExecutionConfig(
    # Timeouts
    convergence_timeout: float = 300.0,
    branch_timeout: float = 600.0,
    agent_acquisition_timeout: float = 240.0,
    step_timeout: float = 600.0,
    tool_execution_timeout: float = 120.0,
    user_interaction_timeout: float = 300.0,

    # Convergence behavior
    dynamic_convergence_enabled: bool = True,
    parent_completes_on_spawn: bool = True,
    auto_detect_convergence: bool = True,

    # Steering
    steering_mode: Literal["auto", "always", "error"] = "error",

    # User interaction
    user_first: bool = False,
    initial_user_msg: Optional[str] = None,
    user_interaction: str = "terminal",

    # Agent lifecycle management
    auto_cleanup_agents: bool = True,
    cleanup_scope: Literal["topology_nodes", "used_agents"] = "topology_nodes",

    # Response format
    response_format: str = "json",

    # Sub-configurations
    status: StatusConfig = field(default_factory=StatusConfig),
    error_handling: Optional[ErrorHandlingConfig] = None
)

# Production configuration
config = ExecutionConfig(
    convergence_timeout=600.0,
    step_timeout=300.0,
    steering_mode="auto",
    status=StatusConfig.from_verbosity(1)
)

# Development configuration
dev_config = ExecutionConfig(
    step_timeout=30.0,
    steering_mode="always",
    status=StatusConfig.from_verbosity(2)
)

# Interactive configuration
interactive_config = ExecutionConfig(
    user_first=True,
    initial_user_msg="Hello! How can I help?",
    user_interaction_timeout=300.0
)

# Long-running workflow (disable auto-cleanup)
long_running_config = ExecutionConfig(
    auto_cleanup_agents=False,  # Keep agents alive between runs
    convergence_timeout=3600.0
)

from marsys.coordination.config import StatusConfig, VerbosityLevel

StatusConfig(
    enabled: bool = False,
    verbosity: Optional[VerbosityLevel] = None,
    cli_output: bool = True,
    cli_colors: bool = True,
    show_thoughts: bool = True,
    show_tool_calls: bool = True,
    show_timings: bool = True,
    aggregation_window_ms: int = 500,
    aggregate_parallel: bool = True,
    max_events_per_session: int = 10000,
    session_cleanup_after_s: int = 3600,
    channels: List[str] = field(default_factory=lambda: ["cli"]),
    show_agent_prefixes: bool = True,
    prefix_width: int = 20,
    prefix_alignment: str = "left",
    follow_up_timeout: float = 30.0
)

class VerbosityLevel(IntEnum):
    QUIET = 0     # Minimal output (no thinking, no tool calls)
    NORMAL = 1    # Standard output (agent thinking, tool calls with reasoning)
    VERBOSE = 2   # Detailed output (all of above + tool arguments, completion timings)

# Create from verbosity level
status = StatusConfig.from_verbosity(1)

# Custom configuration
custom_status = StatusConfig(
    enabled=True,
    verbosity=VerbosityLevel.NORMAL,
    show_thoughts=True,
    show_tool_calls=True,
    cli_colors=False  # Disable colors for logs
)

# Quiet mode with timing
timing_only = StatusConfig(
    enabled=True,
    verbosity=VerbosityLevel.QUIET,
    show_timings=True
)

from marsys.coordination.config import CommunicationConfig

CommunicationConfig(
    use_rich_formatting: bool = True,
    theme_name: str = "modern",
    prefix_width: int = 20,
    show_timestamps: bool = True,
    enable_history: bool = True,
    history_size: int = 1000,
    enable_tab_completion: bool = True,
    use_colors: bool = True,
    color_depth: str = "truecolor",
    input_timeout: Optional[float] = None,
    show_typing_indicator: bool = False,
    use_enhanced_terminal: bool = True,
    fallback_on_error: bool = True
)

# Rich terminal configuration
rich_config = CommunicationConfig(
    use_rich_formatting=True,
    theme_name="modern",
    use_colors=True,
    color_depth="truecolor"
)

# Basic terminal configuration
basic_config = CommunicationConfig(
    use_rich_formatting=False,
    use_colors=False,
    use_enhanced_terminal=False
)

# Web interface configuration
web_config = CommunicationConfig(
    use_rich_formatting=False,  # Web handles formatting
    use_colors=False,            # Web handles colors
    input_timeout=0              # Non-blocking
)

from marsys.coordination.config import ErrorHandlingConfig

ErrorHandlingConfig(
    use_error_classification: bool = True,
    notify_on_critical_errors: bool = True,
    enable_error_routing: bool = True,
    preserve_error_context: bool = True,
    auto_retry_on_rate_limits: bool = True,
    max_rate_limit_retries: int = 3,
    pool_retry_attempts: int = 2,
    pool_retry_delay: float = 5.0,
    timeout_seconds: float = 300.0,
    timeout_retry_enabled: bool = False,
    provider_settings: Dict[str, Dict[str, Any]] = field(default_factory=dict)
)

provider_settings = {
    "openai": {
        "max_retries": 3,
        "base_retry_delay": 60,
        "insufficient_quota_action": "raise"  # "raise", "notify", "fallback"
    },
    "anthropic": {
        "max_retries": 3,
        "base_retry_delay": 30,
        "insufficient_quota_action": "raise"
    }
}

# Aggressive retry strategy
aggressive = ErrorHandlingConfig(
    auto_retry_on_rate_limits=True,
    max_rate_limit_retries=10,
    timeout_retry_enabled=True,
    pool_retry_attempts=5
)

# Conservative strategy
conservative = ErrorHandlingConfig(
    auto_retry_on_rate_limits=False,
    max_rate_limit_retries=0,
    timeout_retry_enabled=False,
    enable_error_routing=True  # Route to user
)

# Custom provider settings
custom = ErrorHandlingConfig(
    provider_settings={
        "openai": {"max_retries": 5, "base_retry_delay": 30},
        "anthropic": {"max_retries": 3, "base_retry_delay": 60}
    }
)

def create_dev_config() -> ExecutionConfig:
    """Development configuration with verbose output."""
    return ExecutionConfig(
        status=StatusConfig(
            enabled=True,
            verbosity=VerbosityLevel.VERBOSE,
            show_thoughts=True,
            show_tool_calls=True
        ),
        step_timeout=30.0,
        steering_mode="always"
    )

def create_prod_config() -> ExecutionConfig:
    """Production configuration with minimal output."""
    return ExecutionConfig(
        status=StatusConfig.from_verbosity(0),
        step_timeout=600.0,
        convergence_timeout=1200.0,
        steering_mode="auto",
        error_handling=ErrorHandlingConfig(
            auto_retry_on_rate_limits=True,
            max_rate_limit_retries=5
        )
    )

def create_test_config() -> ExecutionConfig:
    """Testing configuration with fast failure."""
    return ExecutionConfig(
        status=StatusConfig.from_verbosity(1),
        step_timeout=5.0,
        convergence_timeout=10.0,
        steering_mode="error"
    )

def create_interactive_config() -> ExecutionConfig:
    """User-interactive configuration."""
    return ExecutionConfig(
        user_first=True,
        initial_user_msg="Hello! How can I help?",
        user_interaction_timeout=300.0,
        status=StatusConfig(
            enabled=True,
            cli_colors=True,
            show_agent_prefixes=True
        )
    )

# Default behavior - auto-cleanup enabled
result = await Orchestra.run(
    task="Analyze data",
    topology=topology,
    execution_config=ExecutionConfig(
        auto_cleanup_agents=True  # Default
    )
)
# After run completes:
# 1. Closes model resources (aiohttp sessions, etc.)
# 2. Closes agent-specific resources (browsers, playwright, etc.)
# 3. Unregisters agents from registry (frees names for reuse)

# Scenario 1: Multiple runs with same agents
config = ExecutionConfig(auto_cleanup_agents=False)

for task in tasks:
    result = await Orchestra.run(task, topology, execution_config=config)
    # Agents stay alive, registry intact

# Scenario 2: Long-lived agent pools
pool = await create_browser_agent_pool(num_instances=3, register=False)
AgentRegistry.register_pool(pool)

# Pool manages its own lifecycle
result = await Orchestra.run(
    task="Scrape websites",
    topology=topology,
    execution_config=ExecutionConfig(auto_cleanup_agents=False)
)

await pool.cleanup()  # Manual cleanup when done

from marsys.agents.registry import AgentRegistry

# Manual cleanup for specific agent
agent = AgentRegistry.get("my_agent")
if agent:
    await agent.cleanup()  # Close resources
    AgentRegistry.unregister_if_same("my_agent", agent)  # Identity-safe unregister

# Default JSON format (recommended)
config = ExecutionConfig(response_format="json")

# The JSON format produces system prompts with instructions like:
# --- STRICT JSON OUTPUT FORMAT ---
# Your response MUST be a single, valid JSON object...
# ```json
# {
#   "thought": "reasoning...",
#   "next_action": "invoke_agent",
#   "action_input": [...]
# }
# ```

from marsys.coordination.formats import BaseResponseFormat, register_format

class XMLResponseFormat(BaseResponseFormat):
    def get_format_name(self) -> str:
        return "xml"

    def build_format_instructions(self, actions, descriptions) -> str:
        # Build XML-specific instructions
        ...

    def get_parallel_invocation_examples(self, context) -> str:
        # Provide XML examples for parallel invocation
        ...

    def create_processor(self):
        return XMLProcessor()

# Register and use
register_format("xml", XMLResponseFormat)
config = ExecutionConfig(response_format="xml")

from dataclasses import replace

# Base configuration
base_config = ExecutionConfig(
    step_timeout=300.0,
    status=StatusConfig.from_verbosity(1)
)

# Override specific settings
custom_config = replace(
    base_config,
    step_timeout=60.0,
    steering_mode="always"
)

def get_config_for_task(task_type: str) -> ExecutionConfig:
    """Get configuration based on task type."""
    configs = {
        "research": ExecutionConfig(
            convergence_timeout=600.0,
            max_steps=200
        ),
        "quick_query": ExecutionConfig(
            step_timeout=30.0,
            max_steps=10
        )
    }
    return configs.get(task_type, ExecutionConfig())

import os
from dotenv import load_dotenv

load_dotenv()

config = ExecutionConfig(
    step_timeout=float(os.getenv("MARSYS_TIMEOUT", "300")),
    status=StatusConfig(
        verbosity=int(os.getenv("MARSYS_VERBOSITY", "1"))
    )
)

# Start with base config
orchestra = Orchestra(execution_config=base_config)

# Override for specific run
result = await orchestra.execute(
    task=task,
    topology=topology,
    execution_config=ExecutionConfig(
        step_timeout=60.0  # Override just this setting
    )
)