orchestrata_ultimate.agents.exceptions

Reference › orchestrata_ultimate › agents › exceptions

exceptions defines the error vocabulary of the Multi-Agent Runtime in the agents package (specification 005; the curated narrative is agents). Every runtime failure derives from VolkRuntimeError, so callers can catch the whole family with one clause. The base class and its subclasses carry the identifiers that matter for diagnosis: instance_id on the base, alias on VolkSpawnError and the pool errors, task_id on the task errors, group_id on the coordination errors, and predicate on PrologBridgeError.

The tree has three branches. Instance lifecycle failures are VolkSpawnError and VolkTerminateError. Task failures are TaskExecutionError, TaskAssignmentError (no suitable volk found) and TaskCancellationError. Pool failures are PoolExhaustedError and PoolScaleError. Coordination failures share the intermediate CoordinationError, which has LeaderElectionError and ConsensusError below it. PrologBridgeError reports a failed query against the governance rules in prolog_bridge. The runtime, pool, coordinator and task executor modules raise these types and the package __init__ re-exports them.

At a glance

Class diagram

Dependency diagram

API

Classes

VolkRuntimeError

Bases: Exception · Line 15

Base exception for all Volk runtime errors.

VolkSpawnError

Bases: VolkRuntimeError · Decorators: traces(spec='005', story='US-001', reqs=['REQ-005-US-001-001']) · Line 33

Failed to spawn a Volk instance.

VolkTerminateError

Bases: VolkRuntimeError · Line 50

Failed to terminate a Volk instance.

TaskExecutionError

Bases: VolkRuntimeError · Line 63

Task execution failed.

TaskAssignmentError

Bases: VolkRuntimeError · Line 80

No suitable Volk found for task assignment.

TaskCancellationError

Bases: VolkRuntimeError · Line 92

Task cannot be cancelled.

PoolExhaustedError

Bases: VolkRuntimeError · Line 109

Pool has no available capacity.

PoolScaleError

Bases: VolkRuntimeError · Line 121

Pool scaling operation failed.

CoordinationError

Bases: VolkRuntimeError · Line 137

Base exception for coordination failures.

LeaderElectionError

Bases: CoordinationError · Line 145

Leader election failed.

ConsensusError

Bases: CoordinationError · Line 153

Consensus process failed.

PrologBridgeError

Bases: VolkRuntimeError · Line 166

Prolog bridge operation failed.

Source

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

"""Multi-Agent Runtime exception hierarchy.

All exceptions inherit from VolkRuntimeError for consistent
error handling across the runtime system.

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

# Spec: 005 - Multi-Agent System

from orchestrata_ultimate.core.base.traces import traces


class VolkRuntimeError(Exception):
    """Base exception for all Volk runtime errors."""

    def __init__(self, message: str, instance_id: str | None = None) -> None:
        self.instance_id = instance_id
        super().__init__(message)


# ============================================================================
# Lifecycle Errors
# ============================================================================


@traces(
    spec="005",
    story="US-001",
    reqs=["REQ-005-US-001-001"],
)
class VolkSpawnError(VolkRuntimeError):
    """Failed to spawn a Volk instance.

    Raised when governance denies spawn, registration is not found,
    or resource allocation fails.
    """

    def __init__(
        self,
        message: str,
        alias: str | None = None,
        instance_id: str | None = None,
    ) -> None:
        self.alias = alias
        super().__init__(message, instance_id=instance_id)


class VolkTerminateError(VolkRuntimeError):
    """Failed to terminate a Volk instance.

    Raised when governance denies termination or the instance
    is in a state that prevents shutdown.
    """


# ============================================================================
# Task Errors
# ============================================================================


class TaskExecutionError(VolkRuntimeError):
    """Task execution failed.

    Raised when the task itself fails during execution,
    times out, or produces an invalid result.
    """

    def __init__(
        self,
        message: str,
        task_id: str | None = None,
        instance_id: str | None = None,
    ) -> None:
        self.task_id = task_id
        super().__init__(message, instance_id=instance_id)


class TaskAssignmentError(VolkRuntimeError):
    """No suitable Volk found for task assignment.

    Raised when Prolog find_best_volk_for_task returns no candidates
    or governance denies assignment.
    """

    def __init__(self, message: str, task_id: str | None = None) -> None:
        self.task_id = task_id
        super().__init__(message)


class TaskCancellationError(VolkRuntimeError):
    """Task cannot be cancelled.

    Raised when the task is already completed, already failed,
    or in a state that prevents cancellation.
    """

    def __init__(self, message: str, task_id: str | None = None) -> None:
        self.task_id = task_id
        super().__init__(message)


# ============================================================================
# Pool Errors
# ============================================================================


class PoolExhaustedError(VolkRuntimeError):
    """Pool has no available capacity.

    Raised when all instances are busy and the pool is at
    its maximum configured size.
    """

    def __init__(self, message: str, alias: str | None = None) -> None:
        self.alias = alias
        super().__init__(message)


class PoolScaleError(VolkRuntimeError):
    """Pool scaling operation failed.

    Raised when auto-scaling up or down encounters an error.
    """

    def __init__(self, message: str, alias: str | None = None) -> None:
        self.alias = alias
        super().__init__(message)


# ============================================================================
# Coordination Errors
# ============================================================================


class CoordinationError(VolkRuntimeError):
    """Base exception for coordination failures."""

    def __init__(self, message: str, group_id: str | None = None) -> None:
        self.group_id = group_id
        super().__init__(message)


class LeaderElectionError(CoordinationError):
    """Leader election failed.

    Raised when no candidate meets Prolog eligibility requirements
    or the election process encounters an error.
    """


class ConsensusError(CoordinationError):
    """Consensus process failed.

    Raised when quorum is not met, voting fails, or the
    consensus process times out.
    """


# ============================================================================
# Bridge Errors
# ============================================================================


class PrologBridgeError(VolkRuntimeError):
    """Prolog bridge operation failed.

    Raised when a Prolog query fails, returns unexpected results,
    or the bridge cannot communicate with SWI-Prolog.
    """

    def __init__(self, message: str, predicate: str | None = None) -> None:
        self.predicate = predicate
        super().__init__(message)