edda-framework 0.10.0__py3-none-any.whl → 0.12.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)