edda-framework 0.9.1__py3-none-any.whl → 0.11.0__py3-none-any.whl

edda/integrations/mirascope/decorator.py

@@ -0,0 +1,163 @@
+"""
+Durable LLM call decorator for Edda + Mirascope V2 integration.
+
+This module provides the @durable_call decorator that combines
+Mirascope's @llm.call with Edda's @activity for durable LLM calls.
+"""
+
+from __future__ import annotations
+
+import functools
+import inspect
+from collections.abc import Callable
+from typing import Any, TypeVar
+
+from edda.activity import activity
+from edda.context import WorkflowContext
+
+from .types import DurableResponse
+
+F = TypeVar("F", bound=Callable[..., Any])
+
+
+def _import_mirascope() -> Any:
+    """
+    Lazy import Mirascope components.
+
+    Raises:
+        ImportError: If mirascope is not installed.
+    """
+    try:
+        from mirascope import llm
+
+        return llm
+    except ImportError as e:
+        raise ImportError(
+            "Mirascope not installed. Install with: pip install 'mirascope[anthropic]' "
+            "or pip install 'edda-framework[mirascope]'"
+        ) from e
+
+
+def durable_call(
+    model: str,
+    *,
+    tools: list[Any] | None = None,
+    response_model: type | None = None,
+    json_mode: bool = False,
+    **call_params: Any,
+) -> Callable[[F], F]:
+    """
+    Decorator that makes an LLM call durable through Edda's activity system.
+
+    This decorator combines Mirascope V2's @llm.call with Edda's @activity,
+    providing automatic caching, retry, and crash recovery for LLM calls.
+
+    Args:
+        model: Model identifier in "provider/model" format
+            (e.g., "anthropic/claude-sonnet-4-20250514", "openai/gpt-4").
+        tools: Optional list of tool functions for function calling.
+        response_model: Optional Pydantic model for structured output.
+        json_mode: Whether to enable JSON mode.
+        **call_params: Additional parameters passed to the LLM provider.
+
+    Returns:
+        A decorator that transforms the function into a durable LLM call.
+
+    Example:
+        Basic usage::
+
+            @durable_call("anthropic/claude-sonnet-4-20250514")
+            async def summarize(text: str) -> str:
+                return f"Summarize this text: {text}"
+
+            @workflow
+            async def my_workflow(ctx: WorkflowContext, text: str) -> str:
+                response = await summarize(ctx, text)
+                return response["content"]
+
+        With tools::
+
+            def get_weather(city: str) -> str:
+                '''Get the weather for a city.'''
+                return f"Sunny in {city}"
+
+            @durable_call(
+                "anthropic/claude-sonnet-4-20250514",
+                tools=[get_weather],
+            )
+            async def weather_assistant(query: str) -> str:
+                return query
+
+        With structured output::
+
+            class BookInfo(BaseModel):
+                title: str
+                author: str
+                year: int
+
+            @durable_call(
+                "anthropic/claude-sonnet-4-20250514",
+                response_model=BookInfo,
+            )
+            async def extract_book_info(text: str) -> str:
+                return f"Extract book information from: {text}"
+
+    Note:
+        - The decorated function must return a string (the prompt).
+        - When called, the first argument must be the WorkflowContext.
+        - The response is returned as a dictionary (DurableResponse.to_dict()).
+    """
+    llm = _import_mirascope()
+
+    # Extract provider from model string (e.g., "anthropic/claude-..." -> "anthropic")
+    provider = model.split("/")[0] if "/" in model else "unknown"
+
+    def decorator(func: F) -> F:
+        # Apply Mirascope V2's @llm.call decorator with unified model string
+        mirascope_decorated = llm.call(
+            model,
+            tools=tools,
+            response_model=response_model,
+            json_mode=json_mode,
+            **call_params,
+        )(func)
+
+        # Determine if the original function is async
+        is_async = inspect.iscoroutinefunction(func)
+
+        @activity
+        @functools.wraps(func)
+        async def async_wrapper(
+            ctx: WorkflowContext,  # noqa: ARG001 - Required by @activity decorator
+            *args: Any,
+            **kwargs: Any,
+        ) -> dict[str, Any]:
+            # Call the Mirascope-decorated function
+            if is_async or inspect.iscoroutinefunction(mirascope_decorated):
+                response = await mirascope_decorated(*args, **kwargs)
+            else:
+                response = mirascope_decorated(*args, **kwargs)
+
+            # Handle structured output (response_model)
+            # For structured output, the response is the Pydantic model itself
+            if response_model is not None and hasattr(response, "model_dump"):
+                return {
+                    "content": "",
+                    "model": model,
+                    "provider": provider,
+                    "structured_output": response.model_dump(),
+                }
+
+            # Convert to serializable format
+            return DurableResponse.from_mirascope(response, provider).to_dict()
+
+        # Store metadata for introspection
+        async_wrapper._mirascope_func = mirascope_decorated  # type: ignore[union-attr]
+        async_wrapper._provider = provider  # type: ignore[union-attr]
+        async_wrapper._model = model  # type: ignore[union-attr]
+        async_wrapper._tools = tools  # type: ignore[union-attr]
+        async_wrapper._response_model = response_model  # type: ignore[union-attr]
+
+        return async_wrapper  # type: ignore[return-value]
+
+    return decorator

edda/integrations/mirascope/types.py

@@ -0,0 +1,268 @@
+"""
+Type definitions for Edda + Mirascope integration.
+
+This module provides serializable response types that bridge
+Mirascope's response objects with Edda's activity system.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any
+
+
+@dataclass
+class DurableResponse:
+    """
+    Serializable representation of a Mirascope LLM response.
+
+    This class captures the essential parts of an LLM response
+    in a JSON-serializable format for Edda's activity caching.
+
+    Attributes:
+        content: The text content of the response.
+        model: The model identifier used for the call.
+        provider: The provider name (e.g., "anthropic", "openai").
+        usage: Token usage statistics (input, output, total).
+        tool_calls: List of tool calls requested by the model.
+        stop_reason: The reason the model stopped generating.
+        raw: Raw response data for debugging/advanced use.
+    """
+
+    content: str
+    model: str
+    provider: str
+    usage: dict[str, int] | None = None
+    tool_calls: list[dict[str, Any]] | None = None
+    stop_reason: str | None = None
+    raw: dict[str, Any] = field(default_factory=dict)
+
+    def to_dict(self) -> dict[str, Any]:
+        """Convert to JSON-serializable dictionary."""
+        return {
+            "content": self.content,
+            "model": self.model,
+            "provider": self.provider,
+            "usage": self.usage,
+            "tool_calls": self.tool_calls,
+            "stop_reason": self.stop_reason,
+            "raw": self.raw,
+        }
+
+    @classmethod
+    def from_dict(cls, data: dict[str, Any]) -> DurableResponse:
+        """Create from dictionary (for replay)."""
+        return cls(
+            content=data.get("content", ""),
+            model=data.get("model", ""),
+            provider=data.get("provider", ""),
+            usage=data.get("usage"),
+            tool_calls=data.get("tool_calls"),
+            stop_reason=data.get("stop_reason"),
+            raw=data.get("raw", {}),
+        )
+
+    @classmethod
+    def _extract_content(cls, response: Any) -> str:
+        """
+        Extract text content from a Mirascope response.
+
+        Handles Mirascope V2's response format where content can be:
+        - A plain string
+        - A list of Text/ContentBlock objects with .text attribute
+        - None
+
+        Args:
+            response: The Mirascope CallResponse object.
+
+        Returns:
+            The extracted text content as a string.
+        """
+        if not hasattr(response, "content"):
+            return str(response)
+
+        content = response.content
+        if content is None:
+            return ""
+        if isinstance(content, str):
+            return content
+
+        # Handle Mirascope V2's list of Text/ContentBlock objects
+        # e.g., [Text(type='text', text='Hello!')]
+        if isinstance(content, list):
+            text_parts = []
+            for item in content:
+                if hasattr(item, "text"):
+                    text_parts.append(item.text)
+                elif isinstance(item, str):
+                    text_parts.append(item)
+                else:
+                    text_parts.append(str(item))
+            return "".join(text_parts)
+
+        return str(content)
+
+    @classmethod
+    def _extract_model(cls, response: Any) -> str:
+        """
+        Extract model string from a Mirascope response.
+
+        Handles Mirascope V2 where response.model is a Model object,
+        not a string. Use model_id for the string version.
+
+        Args:
+            response: The Mirascope CallResponse object.
+
+        Returns:
+            The model identifier as a string.
+        """
+        # Mirascope V2: use model_id (string) instead of model (Model object)
+        if hasattr(response, "model_id"):
+            return str(response.model_id)
+
+        # Fallback: try model attribute
+        model = getattr(response, "model", "")
+        if isinstance(model, str):
+            return model
+
+        # If model is an object, try to get a string representation
+        return str(model) if model else ""
+
+    @classmethod
+    def _extract_usage(cls, response: Any) -> dict[str, Any] | None:
+        """
+        Extract usage statistics from a Mirascope response.
+
+        Handles Mirascope V2 where usage may be in response.raw.usage
+        instead of response.usage.
+
+        Args:
+            response: The Mirascope CallResponse object.
+
+        Returns:
+            Usage statistics as a dict, or None if not available.
+        """
+        usage = None
+
+        # Try direct usage attribute first
+        if hasattr(response, "usage") and response.usage is not None:
+            if hasattr(response.usage, "model_dump"):
+                usage = response.usage.model_dump()
+            elif isinstance(response.usage, dict):
+                usage = response.usage
+
+        # Mirascope V2: try response.raw.usage
+        if usage is None and hasattr(response, "raw") and response.raw is not None:
+            raw = response.raw
+            if hasattr(raw, "usage") and raw.usage is not None:
+                if hasattr(raw.usage, "model_dump"):
+                    usage = raw.usage.model_dump()
+                elif isinstance(raw.usage, dict):
+                    usage = raw.usage
+
+        return usage
+
+    @classmethod
+    def _extract_stop_reason(cls, response: Any) -> str | None:
+        """
+        Extract stop reason from a Mirascope response.
+
+        Handles various attribute names across different providers
+        and Mirascope versions.
+
+        Args:
+            response: The Mirascope CallResponse object.
+
+        Returns:
+            The stop reason as a string, or None if not available.
+        """
+        # Try common attribute names
+        stop_reason = getattr(response, "stop_reason", None)
+        if stop_reason is None:
+            stop_reason = getattr(response, "finish_reason", None)
+
+        # Mirascope V2: try response.raw.stop_reason
+        if stop_reason is None and hasattr(response, "raw") and response.raw is not None:
+            stop_reason = getattr(response.raw, "stop_reason", None)
+            if stop_reason is None:
+                stop_reason = getattr(response.raw, "finish_reason", None)
+
+        return stop_reason
+
+    @classmethod
+    def _parse_tool_args(cls, args: Any) -> dict[str, Any]:
+        """
+        Parse tool arguments from various formats.
+
+        Mirascope V2 returns args as a JSON string (e.g., '{"city": "Tokyo"}'),
+        while we need a dict for execution.
+
+        Args:
+            args: Tool arguments (string, dict, or None).
+
+        Returns:
+            Parsed arguments as a dict.
+        """
+        import json
+
+        if args is None:
+            return {}
+        if isinstance(args, dict):
+            return args
+        if isinstance(args, str):
+            try:
+                parsed = json.loads(args)
+                return parsed if isinstance(parsed, dict) else {}
+            except json.JSONDecodeError:
+                return {}
+        return {}
+
+    @classmethod
+    def from_mirascope(cls, response: Any, provider: str) -> DurableResponse:
+        """
+        Convert a Mirascope response to DurableResponse.
+
+        Args:
+            response: The Mirascope CallResponse object.
+            provider: The provider name (e.g., "anthropic").
+
+        Returns:
+            A DurableResponse instance with serializable data.
+        """
+        # Extract tool calls if available
+        tool_calls = None
+        if hasattr(response, "tool_calls") and response.tool_calls:
+            tool_calls = []
+            for tc in response.tool_calls:
+                if hasattr(tc, "model_dump"):
+                    tc_dict = tc.model_dump()
+                    # Ensure args is a dict, not a JSON string
+                    tc_dict["args"] = cls._parse_tool_args(tc_dict.get("args"))
+                    tool_calls.append(tc_dict)
+                elif isinstance(tc, dict):
+                    tc["args"] = cls._parse_tool_args(tc.get("args"))
+                    tool_calls.append(tc)
+                else:
+                    # Fallback: extract common attributes
+                    raw_args = getattr(tc, "args", None) or getattr(tc, "arguments", {})
+                    tool_calls.append(
+                        {
+                            "name": getattr(tc, "name", None) or getattr(tc, "tool_name", None),
+                            "args": cls._parse_tool_args(raw_args),
+                            "id": getattr(tc, "id", None) or getattr(tc, "tool_call_id", None),
+                        }
+                    )
+
+        return cls(
+            content=cls._extract_content(response),
+            model=cls._extract_model(response),
+            provider=provider,
+            usage=cls._extract_usage(response),
+            tool_calls=tool_calls,
+            stop_reason=cls._extract_stop_reason(response),
+        )
+
+    @property
+    def has_tool_calls(self) -> bool:
+        """Check if the response contains tool calls."""
+        return bool(self.tool_calls)

edda/outbox/relayer.py

@@ -48,6 +48,7 @@ class OutboxRelayer:
         max_retries: int = 3,
         batch_size: int = 10,
         max_age_hours: float | None = None,
+        wake_event: asyncio.Event | None = None,
     ):
         """
         Initialize the Outbox Relayer.
@@ -60,6 +61,8 @@ class OutboxRelayer:
             batch_size: Number of events to process per batch (default: 10)
             max_age_hours: Maximum event age in hours before expiration (default: None, disabled)
                           Events older than this are marked as 'expired' and won't be retried.
+            wake_event: Optional asyncio.Event to wake the relayer immediately when new
+                       events are added. Used with PostgreSQL LISTEN/NOTIFY integration.
         """
         self.storage = storage
         self.broker_url = broker_url
@@ -67,6 +70,7 @@ class OutboxRelayer:
         self.max_retries = max_retries
         self.batch_size = batch_size
         self.max_age_hours = max_age_hours
+        self._wake_event = wake_event
 
         self._task: asyncio.Task[Any] | None = None
         self._running = False
@@ -120,6 +124,8 @@ class OutboxRelayer:
         Main polling loop.
 
         Continuously polls the database for pending events and publishes them.
+        When wake_event is provided (PostgreSQL NOTIFY integration), wakes up
+        immediately on notification, otherwise falls back to poll_interval.
         """
         while self._running:
             try:
@@ -127,8 +133,21 @@ class OutboxRelayer:
             except Exception as e:
                 logger.error(f"Error in outbox relayer poll loop: {e}")
 
-            # Wait before next poll
-            await asyncio.sleep(self.poll_interval)
+            # Wait before next poll (with optional NOTIFY wake)
+            if self._wake_event is not None:
+                try:
+                    await asyncio.wait_for(
+                        self._wake_event.wait(),
+                        timeout=self.poll_interval,
+                    )
+                    # Clear the event for next notification
+                    self._wake_event.clear()
+                    logger.debug("Outbox relayer woken by NOTIFY")
+                except TimeoutError:
+                    # Fallback polling timeout reached
+                    pass
+            else:
+                await asyncio.sleep(self.poll_interval)
 
     async def _poll_and_publish(self) -> None:
         """

edda/storage/__init__.py

@@ -1,9 +1,17 @@
 """Storage layer for Edda framework."""
 
+from edda.storage.notify_base import (
+    NoopNotifyListener,
+    NotifyProtocol,
+    create_notify_listener,
+)
 from edda.storage.protocol import StorageProtocol
 from edda.storage.sqlalchemy_storage import SQLAlchemyStorage
 
 __all__ = [
     "StorageProtocol",
     "SQLAlchemyStorage",
+    "NotifyProtocol",
+    "NoopNotifyListener",
+    "create_notify_listener",
 ]

edda/storage/notify_base.py

@@ -0,0 +1,162 @@
+"""Base classes and protocols for notification systems.
+
+This module defines the NotifyProtocol interface and provides a NoopNotifyListener
+implementation for databases that don't support LISTEN/NOTIFY (SQLite, MySQL).
+"""
+
+from __future__ import annotations
+
+import logging
+from collections.abc import Awaitable, Callable
+from typing import Protocol, runtime_checkable
+
+logger = logging.getLogger(__name__)
+
+
+NotifyCallback = Callable[[str], Awaitable[None]]
+"""Type alias for notification callback functions.
+
+The callback receives the payload string from the notification.
+"""
+
+
+@runtime_checkable
+class NotifyProtocol(Protocol):
+    """Protocol for notification systems.
+
+    This protocol defines the interface for LISTEN/NOTIFY style notification
+    systems. Implementations should handle:
+    - Connection management with automatic reconnection
+    - Channel subscription/unsubscription
+    - Callback dispatch on notification receipt
+    """
+
+    async def start(self) -> None:
+        """Start the notification listener.
+
+        Establishes the connection and begins listening for notifications.
+        Should be called before any subscribe() calls.
+        """
+        ...
+
+    async def stop(self) -> None:
+        """Stop the notification listener.
+
+        Closes the connection and cleans up resources.
+        All subscriptions are automatically removed.
+        """
+        ...
+
+    async def subscribe(self, channel: str, callback: NotifyCallback) -> None:
+        """Subscribe to notifications on a channel.
+
+        Args:
+            channel: The channel name to listen on.
+            callback: Async function called when a notification arrives.
+                     Receives the payload string as its argument.
+        """
+        ...
+
+    async def unsubscribe(self, channel: str) -> None:
+        """Unsubscribe from notifications on a channel.
+
+        Args:
+            channel: The channel name to stop listening on.
+        """
+        ...
+
+    async def notify(self, channel: str, payload: str) -> None:
+        """Send a notification on a channel.
+
+        Args:
+            channel: The channel name to send the notification on.
+            payload: The payload string (typically JSON, max ~7500 bytes for PostgreSQL).
+        """
+        ...
+
+    @property
+    def is_connected(self) -> bool:
+        """Check if the listener is currently connected."""
+        ...
+
+
+class NoopNotifyListener:
+    """No-op implementation of NotifyProtocol for SQLite/MySQL.
+
+    This implementation does nothing - all methods are no-ops.
+    When using SQLite or MySQL, the application falls back to polling-based
+    updates with the default intervals (no reduction in polling frequency).
+    """
+
+    def __init__(self) -> None:
+        """Initialize the no-op listener."""
+        self._connected = False
+
+    async def start(self) -> None:
+        """No-op start - does nothing."""
+        self._connected = True
+        logger.debug("NoopNotifyListener started (no-op)")
+
+    async def stop(self) -> None:
+        """No-op stop - does nothing."""
+        self._connected = False
+        logger.debug("NoopNotifyListener stopped (no-op)")
+
+    async def subscribe(self, channel: str, _callback: NotifyCallback) -> None:
+        """No-op subscribe - callbacks will never be called.
+
+        Args:
+            channel: Ignored.
+            _callback: Ignored - will never be called.
+        """
+        logger.debug(f"NoopNotifyListener: subscribe to '{channel}' (no-op)")
+
+    async def unsubscribe(self, channel: str) -> None:
+        """No-op unsubscribe.
+
+        Args:
+            channel: Ignored.
+        """
+        logger.debug(f"NoopNotifyListener: unsubscribe from '{channel}' (no-op)")
+
+    async def notify(self, channel: str, payload: str) -> None:
+        """No-op notify - does nothing.
+
+        Args:
+            channel: Ignored.
+            payload: Ignored.
+        """
+        # Intentionally silent - this is called frequently during normal operation
+        pass
+
+    @property
+    def is_connected(self) -> bool:
+        """Always returns the internal connected state."""
+        return self._connected
+
+
+def create_notify_listener(db_url: str) -> NotifyProtocol:
+    """Create appropriate notify listener based on database type.
+
+    Args:
+        db_url: Database connection URL.
+
+    Returns:
+        PostgresNotifyListener for PostgreSQL, NoopNotifyListener for others.
+
+    Example:
+        >>> listener = create_notify_listener("postgresql://localhost/db")
+        >>> await listener.start()
+        >>> await listener.subscribe("my_channel", handle_notification)
+    """
+    if db_url.startswith("postgresql"):
+        # Import here to avoid requiring asyncpg when not using PostgreSQL
+        from edda.storage.pg_notify import PostgresNotifyListener
+
+        return PostgresNotifyListener(dsn=db_url)
+    else:
+        logger.info(
+            "Database URL does not start with 'postgresql', "
+            "using NoopNotifyListener (polling-based updates)"
+        )
+        return NoopNotifyListener()