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

edda/integrations/mirascope/__init__.py

@@ -0,0 +1,78 @@
+"""
+Edda + Mirascope V2 integration for durable LLM calls.
+
+This module provides utilities to make LLM calls durable through
+Edda's activity system, enabling automatic caching, retry, and
+crash recovery for LLM operations.
+
+Example:
+    Using the decorator::
+
+        from edda import workflow, WorkflowContext
+        from edda.integrations.mirascope import durable_call
+
+        @durable_call("anthropic/claude-sonnet-4-20250514")
+        async def summarize(text: str) -> str:
+            return f"Summarize: {text}"
+
+        @workflow
+        async def my_workflow(ctx: WorkflowContext, text: str) -> str:
+            response = await summarize(ctx, text)
+            return response["content"]
+
+    Using the call function::
+
+        from edda import workflow, WorkflowContext
+        from edda.integrations.mirascope import call
+
+        @workflow
+        async def my_workflow(ctx: WorkflowContext, question: str) -> str:
+            response = await call(
+                ctx,
+                model="anthropic/claude-sonnet-4-20250514",
+                prompt=question,
+            )
+            return response["content"]
+
+    Using DurableAgent for context-aware conversations::
+
+        from dataclasses import dataclass
+        from mirascope import llm
+        from edda import workflow, WorkflowContext
+        from edda.integrations.mirascope import DurableAgent, DurableDeps
+
+        @dataclass
+        class MyDeps:
+            documents: list[str]
+
+        class MyAgent(DurableAgent[MyDeps]):
+            model = "anthropic/claude-sonnet-4-20250514"
+
+            def build_prompt(self, ctx, message):
+                docs = "\\n".join(ctx.deps.documents)
+                return [
+                    llm.messages.system(f"Documents:\\n{docs}"),
+                    llm.messages.user(message),
+                ]
+
+        @workflow
+        async def my_workflow(ctx: WorkflowContext, query: str) -> str:
+            deps = MyDeps(documents=["Doc 1", "Doc 2"])
+            agent = MyAgent(ctx)
+            response = await agent.chat(deps, query)
+            return response["content"]
+"""
+
+from edda.integrations.mirascope.agent import DurableAgent, DurableDeps
+from edda.integrations.mirascope.call import call, call_with_messages
+from edda.integrations.mirascope.decorator import durable_call
+from edda.integrations.mirascope.types import DurableResponse
+
+__all__ = [
+    "durable_call",
+    "call",
+    "call_with_messages",
+    "DurableAgent",
+    "DurableDeps",
+    "DurableResponse",
+]

edda/integrations/mirascope/agent.py

@@ -0,0 +1,467 @@
+"""
+DurableAgent: llm.Context を活用した durable エージェント.
+
+Mirascope V2 の llm.Context を durable execution と統合:
+- llm.Context 経由の dependency injection
+- 会話履歴の自動管理
+- 各ターンは durable activity として実行
+
+Example:
+    Using DurableAgent with context::
+
+        from dataclasses import dataclass
+        from mirascope import llm
+        from edda import workflow, WorkflowContext
+        from edda.integrations.mirascope import DurableAgent, DurableDeps
+
+        @dataclass
+        class ResearchDeps:
+            documents: list[str]
+            search_index: dict[str, str]
+
+        class ResearchAgent(DurableAgent[ResearchDeps]):
+            model = "anthropic/claude-sonnet-4-20250514"
+
+            @staticmethod
+            @llm.tool()
+            def search(ctx: llm.Context[ResearchDeps], query: str) -> str:
+                '''Search through documents.'''
+                return ctx.deps.search_index.get(query, "No results")
+
+            def get_tools(self) -> list:
+                return [self.search]
+
+            def build_prompt(self, ctx: llm.Context[ResearchDeps], message: str) -> list:
+                docs = "\\n".join(ctx.deps.documents)
+                return [
+                    llm.messages.system(f"You are a research assistant.\\nDocs:\\n{docs}"),
+                    llm.messages.user(message),
+                ]
+
+        @workflow
+        async def research_workflow(ctx: WorkflowContext, topic: str) -> str:
+            deps = ResearchDeps(
+                documents=["Doc 1...", "Doc 2..."],
+                search_index={"key1": "value1"},
+            )
+            agent = ResearchAgent(ctx)
+            response = await agent.chat(deps, f"Research: {topic}")
+            return response["content"]
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import TYPE_CHECKING, Any, Generic, TypeVar
+
+from edda.activity import activity
+from edda.context import WorkflowContext
+
+from .types import DurableResponse
+
+if TYPE_CHECKING:
+    pass
+
+# Type variable for dependency data
+T = TypeVar("T")
+
+
+def _import_mirascope() -> Any:
+    """Import mirascope with helpful error message."""
+    try:
+        from mirascope import llm
+
+        return llm
+    except ImportError as e:
+        msg = (
+            "Mirascope is not installed. Install with:\n"
+            "  pip install 'mirascope[anthropic]'\n"
+            "or\n"
+            "  pip install 'edda-framework[mirascope]'"
+        )
+        raise ImportError(msg) from e
+
+
+@dataclass
+class DurableDeps(Generic[T]):
+    """
+    Serializable dependency container for DurableAgent.
+
+    Bridges llm.Context and Edda's durable activity system.
+    Manages both user-defined dependencies and conversation history.
+
+    Attributes:
+        data: User-defined dependency data (will be injected into llm.Context)
+        history: Conversation history (automatically managed)
+
+    Example:
+        >>> @dataclass
+        ... class MyDeps:
+        ...     api_key: str
+        ...     cache: dict[str, str]
+        ...
+        >>> deps = DurableDeps(data=MyDeps(api_key="xxx", cache={}))
+        >>> agent = MyAgent(ctx)
+        >>> await agent.chat(deps, "Hello")  # history auto-updated
+    """
+
+    data: T
+    history: list[dict[str, str]] = field(default_factory=list)
+
+    def to_dict(self) -> dict[str, Any]:
+        """Convert to JSON-serializable dictionary for activity caching."""
+        import dataclasses
+
+        # Handle dataclass or dict data
+        if dataclasses.is_dataclass(self.data) and not isinstance(self.data, type):
+            data_dict: dict[str, Any] = dataclasses.asdict(self.data)
+        elif hasattr(self.data, "model_dump"):
+            # Pydantic model
+            data_dict = self.data.model_dump()
+        elif isinstance(self.data, dict):
+            data_dict = self.data
+        else:
+            data_dict = {"value": self.data}
+
+        return {
+            "data": data_dict,
+            "history": self.history,
+        }
+
+    def add_user_message(self, content: str) -> None:
+        """Add a user message to history."""
+        self.history.append({"role": "user", "content": content})
+
+    def add_assistant_message(self, content: str) -> None:
+        """Add an assistant message to history."""
+        self.history.append({"role": "assistant", "content": content})
+
+    def add_system_message(self, content: str) -> None:
+        """Add a system message to history."""
+        self.history.append({"role": "system", "content": content})
+
+    def clear_history(self) -> None:
+        """Clear conversation history."""
+        self.history = []
+
+
+@activity
+async def _chat_activity(
+    ctx: WorkflowContext,  # noqa: ARG001
+    *,
+    model: str,
+    messages: list[dict[str, str]],
+    tools: list[Any] | None = None,
+    response_model: type | None = None,
+    deps_dict: dict[str, Any],  # noqa: ARG001 - for logging/debugging
+    turn: int,  # noqa: ARG001 - used in activity ID
+    **call_params: Any,
+) -> dict[str, Any]:
+    """Internal: Execute LLM call as durable activity."""
+    llm = _import_mirascope()
+    provider = model.split("/")[0] if "/" in model else "unknown"
+
+    def convert_messages(msgs: list[dict[str, str]]) -> list[Any]:
+        result: list[Any] = []
+        for msg in msgs:
+            role = msg.get("role", "user")
+            content = msg.get("content", "")
+            if role == "system":
+                result.append(llm.messages.system(content))
+            elif role == "assistant":
+                # Mirascope V2: assistant messages require model_id and provider_id
+                result.append(llm.messages.assistant(content, model_id=model, provider_id=provider))
+            else:
+                result.append(llm.messages.user(content))
+        return result
+
+    @llm.call(model, tools=tools, response_model=response_model, **call_params)  # type: ignore[misc]
+    async def _call() -> list[Any]:
+        return convert_messages(messages)
+
+    response = await _call()
+
+    # Handle structured output (response_model)
+    if response_model is not None and hasattr(response, "model_dump"):
+        return {
+            "content": "",
+            "model": model,
+            "provider": provider,
+            "structured_output": response.model_dump(),
+        }
+
+    return DurableResponse.from_mirascope(response, provider).to_dict()
+
+
+class DurableAgent(Generic[T]):
+    """
+    Base class for durable agents with llm.Context support.
+
+    Integrates Mirascope V2's llm.Context with Edda's durable execution:
+    - Each chat turn is a separate durable activity (cached & replayable)
+    - llm.Context provides dependency injection to prompts and tools
+    - Conversation history is automatically managed via DurableDeps
+
+    Subclass and override:
+    - `model`: The LLM model string (e.g., "anthropic/claude-sonnet-4-20250514")
+    - `build_prompt()`: Construct the prompt with access to ctx.deps
+    - `get_tools()`: Return list of @llm.tool() decorated functions
+
+    Attributes:
+        model: The model string in "provider/model" format
+        response_model: Optional Pydantic model for structured output
+
+    Example:
+        >>> class MyAgent(DurableAgent[MyDeps]):
+        ...     model = "anthropic/claude-sonnet-4-20250514"
+        ...
+        ...     def build_prompt(self, ctx, message):
+        ...         return [
+        ...             llm.messages.system(f"Context: {ctx.deps.some_data}"),
+        ...             llm.messages.user(message),
+        ...         ]
+        ...
+        >>> @workflow
+        ... async def my_workflow(ctx: WorkflowContext, query: str) -> str:
+        ...     deps = MyDeps(some_data="value")
+        ...     agent = MyAgent(ctx)
+        ...     response = await agent.chat(deps, query)
+        ...     return response["content"]
+    """
+
+    model: str = "anthropic/claude-sonnet-4-20250514"
+    response_model: type | None = None
+
+    def __init__(self, workflow_ctx: WorkflowContext) -> None:
+        """
+        Initialize the agent with a workflow context.
+
+        Args:
+            workflow_ctx: The Edda WorkflowContext for durable execution
+        """
+        self._workflow_ctx = workflow_ctx
+        self._turn_count = 0
+
+    def get_tools(self) -> list[Any] | None:
+        """
+        Override to provide tools for the agent.
+
+        Tools should be decorated with @llm.tool() and can access
+        ctx: llm.Context[T] as their first parameter.
+
+        Returns:
+            List of tool functions, or None if no tools
+        """
+        return None
+
+    def build_prompt(self, ctx: Any, message: str) -> list[Any]:
+        """
+        Override to build the prompt for each turn.
+
+        Access dependencies via ctx.deps. The returned messages
+        will be sent to the LLM.
+
+        Args:
+            ctx: llm.Context[T] with access to deps
+            message: The user message for this turn
+
+        Returns:
+            List of llm.messages (system, user, assistant)
+
+        Example:
+            >>> def build_prompt(self, ctx, message):
+            ...     llm = _import_mirascope()
+            ...     return [
+            ...         llm.messages.system(f"Data: {ctx.deps.my_data}"),
+            ...         llm.messages.user(message),
+            ...     ]
+        """
+        llm = _import_mirascope()
+        messages: list[Any] = []
+
+        # Extract provider from model string for assistant messages
+        provider = self.model.split("/")[0] if "/" in self.model else "unknown"
+
+        # Include history from DurableDeps if available
+        history = getattr(ctx.deps, "history", [])
+        for msg in history:
+            role = msg.get("role", "user")
+            content = msg.get("content", "")
+            if role == "system":
+                messages.append(llm.messages.system(content))
+            elif role == "assistant":
+                # Mirascope V2: assistant messages require model_id and provider_id
+                messages.append(
+                    llm.messages.assistant(content, model_id=self.model, provider_id=provider)
+                )
+            else:
+                messages.append(llm.messages.user(content))
+
+        # Add the new user message
+        messages.append(llm.messages.user(message))
+        return messages
+
+    async def chat(
+        self,
+        deps: T | DurableDeps[T],
+        message: str,
+        **call_params: Any,
+    ) -> dict[str, Any]:
+        """
+        Send a message and get a response.
+
+        Each call is a separate durable activity - results are cached
+        and replayed on workflow recovery.
+
+        Args:
+            deps: Dependency data (raw or wrapped in DurableDeps)
+            message: User message to send
+            **call_params: Additional LLM call parameters
+
+        Returns:
+            DurableResponse as dict with keys:
+            - content: Response text
+            - model: Model used
+            - provider: Provider name
+            - tool_calls: List of tool calls (if any)
+            - usage: Token usage stats
+        """
+        self._turn_count += 1
+        llm = _import_mirascope()
+
+        # Wrap in DurableDeps if needed
+        durable_deps = deps if isinstance(deps, DurableDeps) else DurableDeps(data=deps)
+
+        # Add user message to history
+        durable_deps.add_user_message(message)
+
+        # Build llm.Context with the actual data
+        llm_ctx = llm.Context(deps=durable_deps.data)
+
+        # Build prompt using the context
+        prompt_messages = self.build_prompt(llm_ctx, message)
+
+        # Convert to serializable format for activity
+        serializable_messages = self._messages_to_dict(prompt_messages)
+
+        # Execute as durable activity
+        # The @activity decorator transforms the function signature, but mypy doesn't understand it
+        response: dict[str, Any] = await _chat_activity(  # type: ignore[misc, call-arg]
+            self._workflow_ctx,  # type: ignore[arg-type]
+            model=self.model,
+            messages=serializable_messages,
+            tools=self.get_tools(),
+            response_model=self.response_model,
+            deps_dict=durable_deps.to_dict(),
+            turn=self._turn_count,
+            **call_params,
+        )
+
+        # Add assistant response to history
+        assistant_content = response.get("content", "")
+        if assistant_content:
+            durable_deps.add_assistant_message(assistant_content)
+
+        return response
+
+    def _messages_to_dict(self, messages: list[Any]) -> list[dict[str, str]]:
+        """Convert llm.messages to serializable dicts."""
+        result = []
+        for msg in messages:
+            if isinstance(msg, dict):
+                result.append(msg)
+            elif hasattr(msg, "role") and hasattr(msg, "content"):
+                content = self._extract_text_content(msg.content)
+                result.append({"role": msg.role, "content": content})
+            elif hasattr(msg, "content"):
+                content = self._extract_text_content(msg.content)
+                result.append({"role": "user", "content": content})
+            else:
+                result.append({"role": "user", "content": str(msg)})
+        return result
+
+    def _extract_text_content(self, content: Any) -> str:
+        """
+        Extract text from Mirascope V2 content format.
+
+        Mirascope V2 content can be:
+        - A plain string
+        - A list of Text/ContentBlock objects with .text attribute
+        - None
+
+        Args:
+            content: The content to extract text from.
+
+        Returns:
+            Extracted text as a string.
+        """
+        if content is None:
+            return ""
+        if isinstance(content, str):
+            return content
+        # Handle Mirascope V2's list of Text/ContentBlock objects
+        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)
+
+    async def chat_with_tool_loop(
+        self,
+        deps: T | DurableDeps[T],
+        message: str,
+        tool_executor: Any | None = None,
+        max_iterations: int = 10,
+        **call_params: Any,
+    ) -> dict[str, Any]:
+        """
+        Chat with automatic tool execution loop.
+
+        Continues calling tools until the model stops requesting them
+        or max_iterations is reached.
+
+        Args:
+            deps: Dependency data
+            message: Initial user message
+            tool_executor: Optional callable(tool_name, tool_args) -> result.
+                          If None, tools are not executed.
+            max_iterations: Maximum tool call iterations
+            **call_params: Additional LLM call parameters
+
+        Returns:
+            Final response after tool loop completes
+        """
+        response = await self.chat(deps, message, **call_params)
+
+        iteration = 0
+        while response.get("tool_calls") and iteration < max_iterations:
+            if tool_executor is None:
+                # No executor provided, return with tool_calls
+                break
+
+            # Execute tools
+            tool_outputs = []
+            for tc in response["tool_calls"]:
+                tool_name = tc.get("name")
+                tool_args = tc.get("args", {})
+                try:
+                    result = await tool_executor(tool_name, tool_args)
+                    tool_outputs.append({"tool": tool_name, "output": str(result)})
+                except Exception as e:
+                    tool_outputs.append({"tool": tool_name, "error": str(e)})
+
+            # Format tool results and continue conversation
+            tool_results_str = "\n".join(
+                f"Tool {to['tool']}: {to.get('output', to.get('error', 'Unknown'))}"
+                for to in tool_outputs
+            )
+            response = await self.chat(deps, f"Tool results:\n{tool_results_str}", **call_params)
+            iteration += 1
+
+        return response

edda/integrations/mirascope/call.py

@@ -0,0 +1,166 @@
+"""
+Simple durable LLM call function for Edda + Mirascope V2 integration.
+
+This module provides a straightforward way to make durable LLM calls
+without needing to define a separate function with @durable_call.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from edda.activity import activity
+from edda.context import WorkflowContext
+
+from .types import DurableResponse
+
+
+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
+
+
+@activity
+async def call(
+    ctx: WorkflowContext,  # noqa: ARG001 - Required by @activity decorator
+    *,
+    model: str,
+    prompt: str,
+    system: str | None = None,
+    tools: list[Any] | None = None,
+    response_model: type | None = None,
+    **call_params: Any,
+) -> dict[str, Any]:
+    """
+    Make a durable LLM call.
+
+    This is a simple, ad-hoc way to make LLM calls within workflows.
+    For more complex use cases, consider using the @durable_call decorator.
+
+    Args:
+        ctx: Workflow context (automatically provided by Edda).
+        model: Model identifier in "provider/model" format
+            (e.g., "anthropic/claude-sonnet-4-20250514", "openai/gpt-4").
+        prompt: The user prompt/message.
+        system: Optional system prompt.
+        tools: Optional list of tool functions for function calling.
+        response_model: Optional Pydantic model for structured output.
+        **call_params: Additional parameters passed to the LLM provider.
+
+    Returns:
+        Dictionary representation of DurableResponse.
+
+    Example:
+        >>> @workflow
+        ... async def my_workflow(ctx: WorkflowContext, question: str) -> str:
+        ...     response = await call(
+        ...         ctx,
+        ...         model="anthropic/claude-sonnet-4-20250514",
+        ...         prompt=question,
+        ...         system="You are a helpful assistant.",
+        ...     )
+        ...     return response["content"]
+    """
+    llm = _import_mirascope()
+
+    # Extract provider from model string (e.g., "anthropic/claude-..." -> "anthropic")
+    provider = model.split("/")[0] if "/" in model else "unknown"
+
+    # Build the call function dynamically using V2 API
+    @llm.call(model, tools=tools, response_model=response_model, **call_params)  # type: ignore[misc]
+    async def _call() -> list[Any]:
+        # V2: Use llm.messages.system/user and return list directly
+        messages = []
+        if system:
+            messages.append(llm.messages.system(system))
+        messages.append(llm.messages.user(prompt))
+        return messages
+
+    # Execute the call
+    response = await _call()
+
+    # Convert to serializable format
+    return DurableResponse.from_mirascope(response, provider).to_dict()
+
+
+@activity
+async def call_with_messages(
+    ctx: WorkflowContext,  # noqa: ARG001 - Required by @activity decorator
+    *,
+    model: str,
+    messages: list[dict[str, str]],
+    tools: list[Any] | None = None,
+    response_model: type | None = None,
+    **call_params: Any,
+) -> dict[str, Any]:
+    """
+    Make a durable LLM call with a full message history.
+
+    This is useful for multi-turn conversations where you need to pass
+    the full conversation history.
+
+    Args:
+        ctx: Workflow context (automatically provided by Edda).
+        model: Model identifier in "provider/model" format
+            (e.g., "anthropic/claude-sonnet-4-20250514", "openai/gpt-4").
+        messages: List of message dicts with "role" and "content" keys.
+        tools: Optional list of tool functions for function calling.
+        response_model: Optional Pydantic model for structured output.
+        **call_params: Additional parameters passed to the LLM provider.
+
+    Returns:
+        Dictionary representation of DurableResponse.
+
+    Example:
+        >>> @workflow
+        ... async def chat_workflow(ctx: WorkflowContext, history: list[dict]) -> str:
+        ...     response = await call_with_messages(
+        ...         ctx,
+        ...         model="anthropic/claude-sonnet-4-20250514",
+        ...         messages=history,
+        ...     )
+        ...     return response["content"]
+    """
+    llm = _import_mirascope()
+
+    # Extract provider and model_id from model string
+    # e.g., "anthropic/claude-sonnet-4-20250514" -> provider="anthropic", model_id="anthropic/claude-sonnet-4-20250514"
+    provider = model.split("/")[0] if "/" in model else "unknown"
+
+    # Convert message dicts to Mirascope V2 message objects
+    def convert_messages(msgs: list[dict[str, str]]) -> list[Any]:
+        result = []
+        for msg in msgs:
+            role = msg.get("role", "user")
+            content = msg.get("content", "")
+            if role == "system":
+                result.append(llm.messages.system(content))
+            elif role == "assistant":
+                # Mirascope V2: assistant messages require model_id and provider_id
+                result.append(llm.messages.assistant(content, model_id=model, provider_id=provider))
+            else:
+                result.append(llm.messages.user(content))
+        return result
+
+    @llm.call(model, tools=tools, response_model=response_model, **call_params)  # type: ignore[misc]
+    async def _call() -> list[Any]:
+        return convert_messages(messages)
+
+    # Execute the call
+    response = await _call()
+
+    # Convert to serializable format
+    return DurableResponse.from_mirascope(response, provider).to_dict()

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_framework-0.10.0.dist-info → edda_framework-0.11.0.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: edda-framework
-Version: 0.10.0
+Version: 0.11.0
 Summary: Lightweight Durable Execution Framework
 Project-URL: Homepage, https://github.com/i2y/edda
 Project-URL: Documentation, https://github.com/i2y/edda#readme
@@ -44,6 +44,9 @@ Requires-Dist: testcontainers[postgres]>=4.0.0; extra == 'dev'
 Requires-Dist: tsuno>=0.1.3; extra == 'dev'
 Provides-Extra: mcp
 Requires-Dist: mcp>=1.22.0; extra == 'mcp'
+Provides-Extra: mirascope
+Requires-Dist: mirascope[anthropic,google,openai]>=2.0.0a0; extra == 'mirascope'
+Requires-Dist: pydantic-settings>=2.0.0; extra == 'mirascope'
 Provides-Extra: mysql
 Requires-Dist: aiomysql>=0.2.0; extra == 'mysql'
 Provides-Extra: opentelemetry
@@ -93,6 +96,7 @@ For detailed documentation, visit [https://i2y.github.io/edda/](https://i2y.gith
 - 📬 **Channel-based Messaging**: Actor-model style communication with competing (job queue) and broadcast (fan-out) modes
 - ⚡ **Instant Notifications**: PostgreSQL LISTEN/NOTIFY for near-instant event delivery (optional)
 - 🤖 **MCP Integration**: Expose durable workflows as AI tools via Model Context Protocol
+- 🧠 **Mirascope Integration**: Durable LLM calls
 - 🌍 **ASGI/WSGI Support**: Deploy with your preferred server (uvicorn, gunicorn, uWSGI)
 
 ## Use Cases

{edda_framework-0.10.0.dist-info → edda_framework-0.11.0.dist-info}/RECORD

@@ -16,6 +16,11 @@ edda/integrations/__init__.py,sha256=F_CaTvlDEbldfOpPKq_U9ve1E573tS6XzqXnOtyHcXI
 edda/integrations/mcp/__init__.py,sha256=YK-8m0DIdP-RSqewlIX7xnWU7TD3NioCiW2_aZSgnn8,1232
 edda/integrations/mcp/decorators.py,sha256=31SmbDwmHEGvUNa3aaatW91hBkpnS5iN9uy47dID3J4,10037
 edda/integrations/mcp/server.py,sha256=Q5r4AbMn-9gBcy2CZocbgW7O0fn7Qb4e9CBJa1FEmzU,14507
+edda/integrations/mirascope/__init__.py,sha256=TKKIs1W2ef88qT1oNoNm0-DQZObOc7tiuw3ul38nc6U,2509
+edda/integrations/mirascope/agent.py,sha256=9y2HmyEDs5zREJgRuXI9EINjj09rWy991Khs7eDXfyY,16235
+edda/integrations/mirascope/call.py,sha256=2pSDrja8Zix6d3TM4VejLmp1DHxbUnSAdSBSg7CFC7k,5754
+edda/integrations/mirascope/decorator.py,sha256=TIK9qoR5ydaz-r33HAMuLrY4rsKJ5tsPlJJp5T_06B8,5488
+edda/integrations/mirascope/types.py,sha256=vgEAu8EFTLSd92XSAxtZpMoe5gv93fe4Rm0DaXaDlV8,9088
 edda/integrations/opentelemetry/__init__.py,sha256=x1_PyyygGDW-rxQTwoIrGzyjKErXHOOKdquFAMlCOAo,906
 edda/integrations/opentelemetry/hooks.py,sha256=rCb6K_gJJMxjQ-UoJnbIOWsafapipzu7w-YPROZKxDA,21330
 edda/outbox/__init__.py,sha256=azXG1rtheJEjOyoWmMsBeR2jp8Bz02R3wDEd5tQnaWA,424
@@ -38,8 +43,8 @@ edda/viewer_ui/theme.py,sha256=mrXoXLRzgSnvE2a58LuMcPJkhlvHEDMWVa8Smqtk4l0,8118
 edda/visualizer/__init__.py,sha256=DOpDstNhR0VcXAs_eMKxaL30p_0u4PKZ4o2ndnYhiRo,343
 edda/visualizer/ast_analyzer.py,sha256=plmx7C9X_X35xLY80jxOL3ljg3afXxBePRZubqUIkxY,13663
 edda/visualizer/mermaid_generator.py,sha256=XWa2egoOTNDfJEjPcwoxwQmblUqXf7YInWFjFRI1QGo,12457
-edda_framework-0.10.0.dist-info/METADATA,sha256=HGJf790N4Rh8EDGIC4e7lFhH8xV5kCQP_xNPTLK8kpE,36366
-edda_framework-0.10.0.dist-info/WHEEL,sha256=WLgqFyCfm_KASv4WHyYy0P3pM_m7J5L9k2skdKLirC8,87
-edda_framework-0.10.0.dist-info/entry_points.txt,sha256=dPH47s6UoJgUZxHoeSMqZsQkLaSE-SGLi-gh88k2WrU,48
-edda_framework-0.10.0.dist-info/licenses/LICENSE,sha256=udxb-V7_cYKTHqW7lNm48rxJ-Zpf0WAY_PyGDK9BPCo,1069
-edda_framework-0.10.0.dist-info/RECORD,,
+edda_framework-0.11.0.dist-info/METADATA,sha256=AkgFtGUJNfhOoHXzti_R7fLli1q45Bg5xO6TfpjvsO8,36587
+edda_framework-0.11.0.dist-info/WHEEL,sha256=WLgqFyCfm_KASv4WHyYy0P3pM_m7J5L9k2skdKLirC8,87
+edda_framework-0.11.0.dist-info/entry_points.txt,sha256=dPH47s6UoJgUZxHoeSMqZsQkLaSE-SGLi-gh88k2WrU,48
+edda_framework-0.11.0.dist-info/licenses/LICENSE,sha256=udxb-V7_cYKTHqW7lNm48rxJ-Zpf0WAY_PyGDK9BPCo,1069
+edda_framework-0.11.0.dist-info/RECORD,,