evolv-agent-sdk 0.2.0__py3-none-any.whl

evolv_agent_sdk/__init__.py

@@ -0,0 +1,285 @@
+"""evolv Agent SDK for Python."""
+
+from collections.abc import Awaitable, Callable
+from dataclasses import dataclass
+from typing import Any, Generic, TypeVar
+
+from ._errors import (
+    CLIConnectionError,
+    CLIJSONDecodeError,
+    CLINotFoundError,
+    EvolvSDKError,
+    ProcessError,
+)
+from ._internal.transport import Transport
+from ._version import __version__
+from .client import EvolvSDKClient
+from .query import query
+from .types import (
+    AgentDefinition,
+    AssistantMessage,
+    CanUseTool,
+    ContentBlock,
+    EvolvAgentOptions,
+    HookCallback,
+    HookContext,
+    HookEvent,
+    HookInput,
+    HookJSONOutput,
+    HookMatcher,
+    McpSdkServerConfig,
+    McpServerConfig,
+    Message,
+    PermissionMode,
+    PermissionResult,
+    PermissionResultAllow,
+    PermissionResultDeny,
+    PermissionUpdate,
+    PostToolUseHookInput,
+    PreToolUseHookInput,
+    ResultMessage,
+    SdkBeta,
+    SettingSource,
+    SyncHookJSONOutput,
+    SystemMessage,
+    TextBlock,
+    ThinkingBlock,
+    ToolPermissionContext,
+    ToolResultBlock,
+    ToolUseBlock,
+    UserMessage,
+)
+
+# MCP Server Support
+
+T = TypeVar("T")
+
+
+@dataclass
+class SdkMcpTool(Generic[T]):
+    """Definition for an SDK MCP tool."""
+
+    name: str
+    description: str
+    input_schema: type[T] | dict[str, Any]
+    handler: Callable[[T], Awaitable[dict[str, Any]]]
+
+
+def tool(
+    name: str, description: str, input_schema: type | dict[str, Any]
+) -> Callable[[Callable[[Any], Awaitable[dict[str, Any]]]], SdkMcpTool[Any]]:
+    """Decorator for defining MCP tools with type safety.
+
+    Creates a tool that can be used with SDK MCP servers. The tool runs
+    in-process within your Python application, providing better performance
+    than external MCP servers.
+
+    Args:
+        name: Unique identifier for the tool.
+        description: Human-readable description of what the tool does.
+        input_schema: Schema defining the tool's input parameters.
+
+    Returns:
+        A decorator function that wraps the tool implementation.
+
+    Example:
+        ```python
+        @tool("greet", "Greet a user", {"name": str})
+        async def greet(args):
+            return {"content": [{"type": "text", "text": f"Hello, {args['name']}!"}]}
+        ```
+    """
+
+    def decorator(
+        handler: Callable[[Any], Awaitable[dict[str, Any]]],
+    ) -> SdkMcpTool[Any]:
+        return SdkMcpTool(
+            name=name,
+            description=description,
+            input_schema=input_schema,
+            handler=handler,
+        )
+
+    return decorator
+
+
+def create_sdk_mcp_server(
+    name: str, version: str = "1.0.0", tools: list[SdkMcpTool[Any]] | None = None
+) -> McpSdkServerConfig:
+    """Create an in-process MCP server that runs within your Python application.
+
+    Unlike external MCP servers that run as separate processes, SDK MCP servers
+    run directly in your application's process.
+
+    Args:
+        name: Unique identifier for the server.
+        version: Server version string. Defaults to "1.0.0".
+        tools: List of SdkMcpTool instances created with the @tool decorator.
+
+    Returns:
+        McpSdkServerConfig: A configuration object for use with EvolvAgentOptions.
+
+    Example:
+        ```python
+        @tool("add", "Add numbers", {"a": float, "b": float})
+        async def add(args):
+            return {"content": [{"type": "text", "text": f"Sum: {args['a'] + args['b']}"}]}
+
+        calculator = create_sdk_mcp_server(
+            name="calculator",
+            tools=[add]
+        )
+
+        options = EvolvAgentOptions(
+            mcp_servers={"calc": calculator},
+        )
+        ```
+    """
+    from mcp.server import Server
+    from mcp.types import ImageContent, TextContent, Tool
+
+    server = Server(name, version=version)
+
+    if tools:
+        tool_map = {tool_def.name: tool_def for tool_def in tools}
+
+        @server.list_tools()  # type: ignore[no-untyped-call,untyped-decorator]
+        async def list_tools() -> list[Tool]:
+            """Return the list of available tools."""
+            tool_list = []
+            for tool_def in tools:
+                if isinstance(tool_def.input_schema, dict):
+                    if (
+                        "type" in tool_def.input_schema
+                        and "properties" in tool_def.input_schema
+                    ):
+                        schema = tool_def.input_schema
+                    else:
+                        properties = {}
+                        for param_name, param_type in tool_def.input_schema.items():
+                            if param_type is str:
+                                properties[param_name] = {"type": "string"}
+                            elif param_type is int:
+                                properties[param_name] = {"type": "integer"}
+                            elif param_type is float:
+                                properties[param_name] = {"type": "number"}
+                            elif param_type is bool:
+                                properties[param_name] = {"type": "boolean"}
+                            else:
+                                properties[param_name] = {"type": "string"}
+                        schema = {
+                            "type": "object",
+                            "properties": properties,
+                            "required": list(properties.keys()),
+                        }
+                else:
+                    schema = {"type": "object", "properties": {}}
+
+                tool_list.append(
+                    Tool(
+                        name=tool_def.name,
+                        description=tool_def.description,
+                        inputSchema=schema,
+                    )
+                )
+            return tool_list
+
+        @server.call_tool()  # type: ignore[untyped-decorator]
+        async def call_tool(name: str, arguments: dict[str, Any]) -> Any:
+            """Execute a tool by name with given arguments."""
+            if name not in tool_map:
+                raise ValueError(f"Tool '{name}' not found")
+
+            tool_def = tool_map[name]
+            result = await tool_def.handler(arguments)
+
+            content: list[TextContent | ImageContent] = []
+            if "content" in result:
+                for item in result["content"]:
+                    if item.get("type") == "text":
+                        content.append(TextContent(type="text", text=item["text"]))
+                    if item.get("type") == "image":
+                        content.append(
+                            ImageContent(
+                                type="image",
+                                data=item["data"],
+                                mimeType=item["mimeType"],
+                            )
+                        )
+
+            return content
+
+    return McpSdkServerConfig(type="sdk", name=name, instance=server)
+
+
+# Backward compatibility aliases
+CortexSDKClient = EvolvSDKClient
+CortexAgentOptions = EvolvAgentOptions
+CortexSDKError = EvolvSDKError
+ClaudeSDKClient = EvolvSDKClient
+ClaudeAgentOptions = EvolvAgentOptions
+ClaudeSDKError = EvolvSDKError
+
+
+__all__ = [
+    # Main exports
+    "query",
+    "__version__",
+    # Transport
+    "Transport",
+    "EvolvSDKClient",
+    # Types
+    "PermissionMode",
+    "McpServerConfig",
+    "McpSdkServerConfig",
+    "UserMessage",
+    "AssistantMessage",
+    "SystemMessage",
+    "ResultMessage",
+    "Message",
+    "EvolvAgentOptions",
+    "TextBlock",
+    "ThinkingBlock",
+    "ToolUseBlock",
+    "ToolResultBlock",
+    "ContentBlock",
+    # Tool callbacks
+    "CanUseTool",
+    "ToolPermissionContext",
+    "PermissionResult",
+    "PermissionResultAllow",
+    "PermissionResultDeny",
+    "PermissionUpdate",
+    # Hooks
+    "HookCallback",
+    "HookContext",
+    "HookEvent",
+    "HookInput",
+    "HookJSONOutput",
+    "HookMatcher",
+    "PreToolUseHookInput",
+    "PostToolUseHookInput",
+    "SyncHookJSONOutput",
+    # Agent support
+    "AgentDefinition",
+    "SettingSource",
+    # Beta support
+    "SdkBeta",
+    # MCP Server Support
+    "create_sdk_mcp_server",
+    "tool",
+    "SdkMcpTool",
+    # Errors
+    "EvolvSDKError",
+    "CLIConnectionError",
+    "CLINotFoundError",
+    "ProcessError",
+    "CLIJSONDecodeError",
+    # Backward compatibility aliases
+    "CortexSDKClient",
+    "CortexAgentOptions",
+    "CortexSDKError",
+    "ClaudeSDKClient",
+    "ClaudeAgentOptions",
+    "ClaudeSDKError",
+]

evolv_agent_sdk/_bundled/.gitkeep

@@ -0,0 +1 @@
+# Placeholder for bundled CLI binary

evolv_agent_sdk/_cli_version.py

@@ -0,0 +1,3 @@
+"""evolv CLI version tracking."""
+
+CLI_VERSION = "1.0.5"

evolv_agent_sdk/_errors.py

@@ -0,0 +1,61 @@
+"""Error types for evolv Agent SDK."""
+
+from typing import Any
+
+
+class EvolvSDKError(Exception):
+    """Base exception for all evolv Agent SDK errors."""
+
+
+class CLIConnectionError(EvolvSDKError):
+    """Raised when unable to connect to evolv Code."""
+
+
+class CLINotFoundError(CLIConnectionError):
+    """Raised when evolv Code is not found or not installed."""
+
+    def __init__(
+        self, message: str = "evolv Code not found", cli_path: str | None = None
+    ):
+        if cli_path:
+            message = f"{message}: {cli_path}"
+        super().__init__(message)
+
+
+class ProcessError(EvolvSDKError):
+    """Raised when the CLI process fails."""
+
+    def __init__(
+        self, message: str, exit_code: int | None = None, stderr: str | None = None
+    ):
+        self.exit_code = exit_code
+        self.stderr = stderr
+
+        if exit_code is not None:
+            message = f"{message} (exit code: {exit_code})"
+        if stderr:
+            message = f"{message}\nError output: {stderr}"
+
+        super().__init__(message)
+
+
+class CLIJSONDecodeError(EvolvSDKError):
+    """Raised when unable to decode JSON from CLI output."""
+
+    def __init__(self, line: str, original_error: Exception):
+        self.line = line
+        self.original_error = original_error
+        super().__init__(f"Failed to decode JSON: {line[:100]}...")
+
+
+class MessageParseError(EvolvSDKError):
+    """Raised when unable to parse a message from CLI output."""
+
+    def __init__(self, message: str, data: dict[str, Any] | None = None):
+        self.data = data
+        super().__init__(message)
+
+
+# Backward compatibility aliases
+CortexSDKError = EvolvSDKError
+ClaudeSDKError = EvolvSDKError

evolv_agent_sdk/_internal/__init__.py

@@ -0,0 +1 @@
+"""Internal modules for evolv Agent SDK."""

evolv_agent_sdk/_internal/client.py

@@ -0,0 +1,108 @@
+"""Internal client implementation."""
+
+from collections.abc import AsyncIterable, AsyncIterator
+from dataclasses import replace
+from typing import Any
+
+from ..types import (
+    EvolvAgentOptions,
+    HookEvent,
+    HookMatcher,
+    Message,
+)
+from .message_parser import parse_message
+from .query import Query
+from .transport import Transport
+from .transport.subprocess_cli import SubprocessCLITransport
+
+
+class InternalClient:
+    """Internal client implementation."""
+
+    def __init__(self) -> None:
+        """Initialize the internal client."""
+
+    def _convert_hooks_to_internal_format(
+        self, hooks: dict[HookEvent, list[HookMatcher]]
+    ) -> dict[str, list[dict[str, Any]]]:
+        """Convert HookMatcher format to internal Query format."""
+        internal_hooks: dict[str, list[dict[str, Any]]] = {}
+        for event, matchers in hooks.items():
+            internal_hooks[event] = []
+            for matcher in matchers:
+                internal_matcher: dict[str, Any] = {
+                    "matcher": matcher.matcher if hasattr(matcher, "matcher") else None,
+                    "hooks": matcher.hooks if hasattr(matcher, "hooks") else [],
+                }
+                if hasattr(matcher, "timeout") and matcher.timeout is not None:
+                    internal_matcher["timeout"] = matcher.timeout
+                internal_hooks[event].append(internal_matcher)
+        return internal_hooks
+
+    async def process_query(
+        self,
+        prompt: str | AsyncIterable[dict[str, Any]],
+        options: EvolvAgentOptions,
+        transport: Transport | None = None,
+    ) -> AsyncIterator[Message]:
+        """Process a query through transport and Query."""
+
+        configured_options = options
+        if options.can_use_tool:
+            if isinstance(prompt, str):
+                raise ValueError(
+                    "can_use_tool callback requires streaming mode. "
+                    "Please provide prompt as an AsyncIterable instead of a string."
+                )
+
+            if options.permission_prompt_tool_name:
+                raise ValueError(
+                    "can_use_tool callback cannot be used with permission_prompt_tool_name. "
+                    "Please use one or the other."
+                )
+
+            configured_options = replace(options, permission_prompt_tool_name="stdio")
+
+        if transport is not None:
+            chosen_transport = transport
+        else:
+            chosen_transport = SubprocessCLITransport(
+                prompt=prompt,
+                options=configured_options,
+            )
+
+        await chosen_transport.connect()
+
+        sdk_mcp_servers = {}
+        if configured_options.mcp_servers and isinstance(
+            configured_options.mcp_servers, dict
+        ):
+            for name, config in configured_options.mcp_servers.items():
+                if isinstance(config, dict) and config.get("type") == "sdk":
+                    sdk_mcp_servers[name] = config["instance"]  # type: ignore[typeddict-item]
+
+        is_streaming = not isinstance(prompt, str)
+        query = Query(
+            transport=chosen_transport,
+            is_streaming_mode=is_streaming,
+            can_use_tool=configured_options.can_use_tool,
+            hooks=self._convert_hooks_to_internal_format(configured_options.hooks)
+            if configured_options.hooks
+            else None,
+            sdk_mcp_servers=sdk_mcp_servers,
+        )
+
+        try:
+            await query.start()
+
+            if is_streaming:
+                await query.initialize()
+
+            if isinstance(prompt, AsyncIterable) and query._tg:
+                query._tg.start_soon(query.stream_input, prompt)
+
+            async for data in query.receive_messages():
+                yield parse_message(data)
+
+        finally:
+            await query.close()

evolv_agent_sdk/_internal/message_parser.py

@@ -0,0 +1,181 @@
+"""Message parser for evolv Agent SDK responses."""
+
+import logging
+from typing import Any
+
+from .._errors import MessageParseError
+from ..types import (
+    AssistantMessage,
+    ContentBlock,
+    Message,
+    ResultMessage,
+    StreamEvent,
+    SystemMessage,
+    TextBlock,
+    ThinkingBlock,
+    ToolResultBlock,
+    ToolUseBlock,
+    UserMessage,
+)
+
+logger = logging.getLogger(__name__)
+
+
+def parse_message(data: dict[str, Any]) -> Message:
+    """
+    Parse message from CLI output into typed Message objects.
+
+    Args:
+        data: Raw message dictionary from CLI output
+
+    Returns:
+        Parsed Message object
+
+    Raises:
+        MessageParseError: If parsing fails or message type is unrecognized
+    """
+    if not isinstance(data, dict):
+        raise MessageParseError(
+            f"Invalid message data type (expected dict, got {type(data).__name__})",
+            data,
+        )
+
+    message_type = data.get("type")
+    if not message_type:
+        raise MessageParseError("Message missing 'type' field", data)
+
+    match message_type:
+        case "user":
+            try:
+                parent_tool_use_id = data.get("parent_tool_use_id")
+                tool_use_result = data.get("tool_use_result")
+                uuid = data.get("uuid")
+                if isinstance(data["message"]["content"], list):
+                    user_content_blocks: list[ContentBlock] = []
+                    for block in data["message"]["content"]:
+                        match block["type"]:
+                            case "text":
+                                user_content_blocks.append(
+                                    TextBlock(text=block["text"])
+                                )
+                            case "tool_use":
+                                user_content_blocks.append(
+                                    ToolUseBlock(
+                                        id=block["id"],
+                                        name=block["name"],
+                                        input=block["input"],
+                                    )
+                                )
+                            case "tool_result":
+                                user_content_blocks.append(
+                                    ToolResultBlock(
+                                        tool_use_id=block["tool_use_id"],
+                                        content=block.get("content"),
+                                        is_error=block.get("is_error"),
+                                    )
+                                )
+                    return UserMessage(
+                        content=user_content_blocks,
+                        uuid=uuid,
+                        parent_tool_use_id=parent_tool_use_id,
+                        tool_use_result=tool_use_result,
+                    )
+                return UserMessage(
+                    content=data["message"]["content"],
+                    uuid=uuid,
+                    parent_tool_use_id=parent_tool_use_id,
+                    tool_use_result=tool_use_result,
+                )
+            except KeyError as e:
+                raise MessageParseError(
+                    f"Missing required field in user message: {e}", data
+                ) from e
+
+        case "assistant":
+            try:
+                content_blocks: list[ContentBlock] = []
+                for block in data["message"]["content"]:
+                    match block["type"]:
+                        case "text":
+                            content_blocks.append(TextBlock(text=block["text"]))
+                        case "thinking":
+                            # evolv might not provide signature, use empty string
+                            content_blocks.append(
+                                ThinkingBlock(
+                                    thinking=block["thinking"],
+                                    signature=block.get("signature", ""),
+                                )
+                            )
+                        case "tool_use":
+                            content_blocks.append(
+                                ToolUseBlock(
+                                    id=block["id"],
+                                    name=block["name"],
+                                    input=block["input"],
+                                )
+                            )
+                        case "tool_result":
+                            content_blocks.append(
+                                ToolResultBlock(
+                                    tool_use_id=block["tool_use_id"],
+                                    content=block.get("content"),
+                                    is_error=block.get("is_error"),
+                                )
+                            )
+
+                return AssistantMessage(
+                    content=content_blocks,
+                    model=data["message"].get("model", "evolv"),
+                    parent_tool_use_id=data.get("parent_tool_use_id"),
+                    error=data.get("error"),
+                )
+            except KeyError as e:
+                raise MessageParseError(
+                    f"Missing required field in assistant message: {e}", data
+                ) from e
+
+        case "system":
+            try:
+                return SystemMessage(
+                    subtype=data["subtype"],
+                    data=data,
+                )
+            except KeyError as e:
+                raise MessageParseError(
+                    f"Missing required field in system message: {e}", data
+                ) from e
+
+        case "result":
+            try:
+                return ResultMessage(
+                    subtype=data["subtype"],
+                    duration_ms=data.get("duration_ms", 0),
+                    duration_api_ms=data.get("duration_api_ms", 0),
+                    is_error=data.get("is_error", data.get("subtype") != "success"),
+                    num_turns=data.get("num_turns", 1),
+                    session_id=data.get("session_id", "evolv-session"),
+                    total_cost_usd=data.get("total_cost_usd", 0),
+                    usage=data.get("usage"),
+                    result=data.get("result"),
+                    structured_output=data.get("structured_output"),
+                )
+            except KeyError as e:
+                raise MessageParseError(
+                    f"Missing required field in result message: {e}", data
+                ) from e
+
+        case "stream_event":
+            try:
+                return StreamEvent(
+                    uuid=data["uuid"],
+                    session_id=data["session_id"],
+                    event=data["event"],
+                    parent_tool_use_id=data.get("parent_tool_use_id"),
+                )
+            except KeyError as e:
+                raise MessageParseError(
+                    f"Missing required field in stream_event message: {e}", data
+                ) from e
+
+        case _:
+            raise MessageParseError(f"Unknown message type: {message_type}", data)