Exceptions
==========

Custom exception classes for handling orchestration errors.

Exception Hierarchy
-------------------

All exceptions inherit from ``OrchestrationError``::

    OrchestrationError
    ├── PatternExecutionError
    ├── PatternConfigurationError
    ├── AgentError
    ├── ToolExecutionError
    ├── StateError
    └── ValidationError

Exception Classes
-----------------

.. automodule:: pygeai_orchestration.core.exceptions
   :members:
   :undoc-members:
   :show-inheritance:

Usage Examples
--------------

Basic Exception Handling
~~~~~~~~~~~~~~~~~~~~~~~~~

.. code-block:: python

    from pygeai_orchestration import ReflectionPattern, PatternExecutionError

    try:
        pattern = ReflectionPattern(agent=agent)
        result = await pattern.execute("Task description")
    except PatternExecutionError as e:
        print(f"Pattern failed: {e.message}")
        print(f"Error code: {e.code}")
        print(f"Context: {e.context}")

Using Error Handler
~~~~~~~~~~~~~~~~~~~

.. code-block:: python

    from pygeai_orchestration import ErrorHandler

    response = await agent.execute(task)

    if ErrorHandler.has_errors(response):
        error = ErrorHandler.extract_error(response)
        ErrorHandler.handle_error(error, context={"operation": "execute"})

Custom Error Context
~~~~~~~~~~~~~~~~~~~~

.. code-block:: python

    from pygeai_orchestration import AgentError

    raise AgentError(
        message="Agent execution timeout",
        code="AGENT_TIMEOUT",
        context={
            "agent": "assistant",
            "timeout": 300,
            "elapsed": 310
        }
    )
