Execution API

from marsys.coordination.execution import BranchExecutor

BranchExecutor(
    validation_processor: ValidationProcessor,
    router: Router,
    step_executor: StepExecutor,
    context_manager: ContextManager,
    config: ExecutionConfig
)

async def execute_branch(
    branch: ExecutionBranch,
    initial_request: Any,
    context: Dict[str, Any],
    resume_with_results: Optional[Dict] = None
) -> BranchResult

executor = BranchExecutor(
    validation_processor=validator,
    router=router,
    step_executor=step_exec,
    context_manager=ctx_mgr,
    config=exec_config
)

result = await executor.execute_branch(
    branch=main_branch,
    initial_request="Analyze this data",
    context={"session_id": "123"}
)

from marsys.coordination.branches.types import ExecutionBranch, BranchType, BranchStatus

class BranchType(Enum):
    SIMPLE = "simple"                    # Sequential execution
    CONVERSATION = "conversation"        # Bidirectional dialogue
    NESTED = "nested"                    # Has child branches
    USER_INTERACTION = "user_interaction"  # Human-in-the-loop

class BranchStatus(Enum):
    PENDING = "pending"      # Not started
    RUNNING = "running"      # Currently executing
    WAITING = "waiting"      # Waiting for child branches
    COMPLETED = "completed"  # Successfully finished
    FAILED = "failed"        # Terminated with error

from marsys.coordination.execution import StepExecutor

async def execute_step(
    agent_name: str,
    request: Any,
    context: Dict[str, Any],
    branch: ExecutionBranch,
    memory: List[Message]
) -> StepResult

@dataclass
class StepResult:
    success: bool
    agent_name: str
    response: Any
    error: Optional[str] = None
    metadata: Dict[str, Any] = field(default_factory=dict)
    execution_time: float = 0.0
    memory_used: List[Message] = field(default_factory=list)

from marsys.coordination.execution import DynamicBranchSpawner

async def handle_parallel_invocation(
    agents: List[str],
    requests: Dict[str, Any],
    parent_branch: ExecutionBranch,
    context: Dict[str, Any]
) -> List[asyncio.Task]

spawner = DynamicBranchSpawner(
    branch_executor=branch_exec,
    context_manager=ctx_mgr,
    config=exec_config
)

# Spawn parallel branches
tasks = await spawner.handle_parallel_invocation(
    agents=["Worker1", "Worker2", "Worker3"],
    requests={
        "Worker1": "Task 1",
        "Worker2": "Task 2",
        "Worker3": "Task 3"
    },
    parent_branch=main_branch,
    context={"parallel": True}
)

# Wait for completion
results = await asyncio.gather(*tasks)

# Simple sequential branch
branch = ExecutionBranch(
    branch_type=BranchType.SIMPLE,
    agent_sequence=["Agent1", "Agent2", "Agent3"]
)

result = await executor.execute_branch(
    branch=branch,
    initial_request="Process this",
    context={}
)

# Bidirectional conversation
branch = ExecutionBranch(
    branch_type=BranchType.CONVERSATION,
    agent_sequence=["Agent1", "Agent2"],
    metadata={"max_turns": 5}
)

result = await executor.execute_branch(
    branch=branch,
    initial_request="Let's discuss",
    context={}
)

# Response that triggers parallel execution
response = {
    "next_action": "parallel_invoke",
    "agents": ["Worker1", "Worker2", "Worker3"],
    "agent_requests": {
        "Worker1": "Analyze segment A",
        "Worker2": "Analyze segment B",
        "Worker3": "Analyze segment C"
    }
}

# DynamicBranchSpawner handles this automatically