Grafi 50/better exception propagation (#72)

* creates exceptions

* update exception propagation

* update unit test and lint

* address mypy errors, remove record decorator from mypy check

* update version

* update tracer and unit test

Author: GuanyiLi-Craig

grafi/common/decorators/record_base.py

@@ -1,3 +1,4 @@
+# mypy: ignore-errors
 """Base decorator utilities for recording component invoke events and tracing."""
 
 import functools

grafi/common/decorators/record_decorators.py

@@ -1,3 +1,4 @@
+# mypy: ignore-errors
 """
 Unified module for all record decorators.
 This replaces 8 separate files with a single, maintainable module.

grafi/common/exceptions/__init__.py

@@ -0,0 +1,50 @@
+"""
+Grafi exception hierarchy for comprehensive error handling.
+"""
+
+from grafi.common.exceptions.base import (
+    GrafiError,
+    ValidationError,
+)
+from grafi.common.exceptions.duplicate_node_error import DuplicateNodeError
+from grafi.common.exceptions.event_exceptions import (
+    EventPersistenceError,
+    EventSerializationError,
+    EventStoreError,
+    TopicError,
+    TopicPublicationError,
+    TopicSubscriptionError,
+)
+from grafi.common.exceptions.tool_exceptions import (
+    FunctionCallException,
+    FunctionToolException,
+    LLMToolException,
+    ToolInvocationError,
+)
+from grafi.common.exceptions.workflow_exceptions import (
+    NodeExecutionError,
+    WorkflowError,
+)
+
+__all__ = [
+    # Base errors
+    "GrafiError",
+    "ValidationError",
+    # Tool errors
+    "ToolInvocationError",
+    "LLMToolException",
+    "FunctionCallException",
+    "FunctionToolException",
+    # Workflow errors
+    "WorkflowError",
+    "NodeExecutionError",
+    # Event and topic errors
+    "EventStoreError",
+    "EventSerializationError",
+    "EventPersistenceError",
+    "TopicError",
+    "TopicSubscriptionError",
+    "TopicPublicationError",
+    # Domain-specific errors
+    "DuplicateNodeError",
+]

grafi/common/exceptions/base.py

@@ -0,0 +1,63 @@
+"""
+Base exception classes for the Grafi framework.
+"""
+
+import time
+from typing import Any
+from typing import Dict
+from typing import Optional
+
+from grafi.common.models.invoke_context import InvokeContext
+
+
+class GrafiError(Exception):
+    """Base exception for all Grafi framework errors.
+
+    Attributes:
+        message: Human-readable error message
+        context: Additional context information about the error
+        cause: The underlying exception that caused this error
+        timestamp: When the error occurred
+        severity: Error severity level
+    """
+
+    def __init__(
+        self,
+        message: str,
+        invoke_context: Optional[InvokeContext] = None,
+        cause: Optional[Exception] = None,
+        severity: str = "ERROR",
+    ):
+        super().__init__(message)
+        self.message = message
+        self.cause = cause
+        self.invoke_context = invoke_context
+        self.timestamp = time.time()
+        self.severity = severity
+
+    def __str__(self) -> str:
+        base_msg = f"[{self.severity}] {self.message}"
+        if self.invoke_context:
+            base_msg = f"{base_msg} [Invoke Context: {self.invoke_context}]"
+        if self.cause:
+            base_msg = f"{base_msg} [Caused by: {type(self.cause).__name__}: {str(self.cause)}]"
+        return base_msg
+
+    def to_dict(self) -> Dict[str, Any]:
+        """Convert error to dictionary for structured logging."""
+        return {
+            "error_type": type(self).__name__,
+            "message": self.message,
+            "timestamp": self.timestamp,
+            "severity": self.severity,
+            "cause": str(self.cause) if self.cause else None,
+            "invoke_context": (
+                self.invoke_context.model_dump() if self.invoke_context else None
+            ),
+        }
+
+
+class ValidationError(GrafiError):
+    """Raised when input validation fails."""
+
+    pass

grafi/common/exceptions/duplicate_node_error.py

@@ -1,11 +1,20 @@
 """Exception for handling duplicate nodes in the graph."""
 
-from grafi.nodes.node_base import NodeBase
+from typing import TYPE_CHECKING
 
+from grafi.common.exceptions.workflow_exceptions import WorkflowError
 
-class DuplicateNodeError(Exception):
+
+if TYPE_CHECKING:
+    from grafi.nodes.node_base import NodeBase
+
+
+class DuplicateNodeError(WorkflowError):
     """Exception raised when a duplicate node is detected in the graph."""
 
-    def __init__(self, node: NodeBase):
-        super().__init__(f"Duplicate element detected: {node.name}")
+    def __init__(self, node: "NodeBase") -> None:
+        super().__init__(
+            message=f"Duplicate node detected: {node.name}", severity="ERROR"
+        )
         self.node = node
+        self.node_name = node.name

grafi/common/exceptions/event_exceptions.py

@@ -0,0 +1,54 @@
+"""
+Event store and topic-related exception classes.
+"""
+
+from typing import Any
+from typing import Optional
+
+from grafi.common.exceptions.base import GrafiError
+from grafi.common.models.invoke_context import InvokeContext
+
+
+class EventStoreError(GrafiError):
+    """Raised when event store operations fail."""
+
+    pass
+
+
+class EventSerializationError(EventStoreError):
+    """Raised when event serialization/deserialization fails."""
+
+    pass
+
+
+class EventPersistenceError(EventStoreError):
+    """Raised when persisting events to storage fails."""
+
+    pass
+
+
+class TopicError(GrafiError):
+    """Raised when topic pub/sub operations fail."""
+
+    def __init__(
+        self,
+        topic_name: str,
+        message: str,
+        invoke_context: Optional[InvokeContext] = None,
+        cause: Optional[Exception] = None,
+        **kwargs: Any,
+    ) -> None:
+        super().__init__(message, invoke_context, cause, **kwargs)
+        self.topic_name = topic_name
+
+
+class TopicSubscriptionError(TopicError):
+    """Raised when topic subscription fails."""
+
+    pass
+
+
+class TopicPublicationError(TopicError):
+    """Raised when publishing to a topic fails."""
+
+    pass

grafi/common/exceptions/tool_exceptions.py

@@ -0,0 +1,75 @@
+"""
+Tool-related exception classes.
+"""
+
+from typing import Any
+from typing import Optional
+
+from grafi.common.exceptions.base import GrafiError
+from grafi.common.models.invoke_context import InvokeContext
+
+
+class ToolInvocationError(GrafiError):
+    """Base class for tool invocation failures."""
+
+    def __init__(
+        self,
+        tool_name: str,
+        message: str,
+        invoke_context: Optional[InvokeContext] = None,
+        cause: Optional[Exception] = None,
+        **kwargs: Any,
+    ) -> None:
+        super().__init__(message, invoke_context, cause, **kwargs)
+        self.tool_name = tool_name
+
+
+class LLMToolException(ToolInvocationError):
+    """Raised when LLM tool operations fail."""
+
+    def __init__(
+        self,
+        tool_name: str,
+        model: Optional[str] = None,
+        message: str = "LLM tool operation failed",
+        invoke_context: Optional[InvokeContext] = None,
+        cause: Optional[Exception] = None,
+        **kwargs: Any,
+    ) -> None:
+        super().__init__(tool_name, message, invoke_context, cause, **kwargs)
+        self.model = model
+        self.type = "LLM"
+
+
+class FunctionCallException(ToolInvocationError):
+    """Raised when function call tool operations fail."""
+
+    def __init__(
+        self,
+        tool_name: str,
+        function_name: Optional[str] = None,
+        message: str = "Function call operation failed",
+        invoke_context: Optional[InvokeContext] = None,
+        cause: Optional[Exception] = None,
+        **kwargs: Any,
+    ) -> None:
+        super().__init__(tool_name, message, invoke_context, cause, **kwargs)
+        self.function_name = function_name
+        self.type = "FunctionCall"
+
+
+class FunctionToolException(ToolInvocationError):
+    """Raised when generic function tool operations fail."""
+
+    def __init__(
+        self,
+        tool_name: str,
+        operation: Optional[str] = None,
+        message: str = "Function tool operation failed",
+        invoke_context: Optional[InvokeContext] = None,
+        cause: Optional[Exception] = None,
+        **kwargs: Any,
+    ) -> None:
+        super().__init__(tool_name, message, invoke_context, cause, **kwargs)
+        self.operation = operation
+        self.type = "Function"

grafi/common/exceptions/workflow_exceptions.py

@@ -0,0 +1,30 @@
+"""
+Workflow and node-related exception classes.
+"""
+
+from typing import Any
+from typing import Optional
+
+from grafi.common.exceptions.base import GrafiError
+from grafi.common.models.invoke_context import InvokeContext
+
+
+class WorkflowError(GrafiError):
+    """Raised when workflow execution encounters an error."""
+
+    pass
+
+
+class NodeExecutionError(WorkflowError):
+    """Raised when a node fails during execution."""
+
+    def __init__(
+        self,
+        node_name: str,
+        message: str,
+        invoke_context: Optional[InvokeContext] = None,
+        cause: Optional[Exception] = None,
+        **kwargs: Any,
+    ) -> None:
+        super().__init__(message, invoke_context, cause, **kwargs)
+        self.node_name = node_name