claude-agent-sdk 0.0.23__py3-none-any.whl

claude_agent_sdk/__init__.py

@@ -0,0 +1,325 @@
+"""Claude SDK for Python."""
+
+from collections.abc import Awaitable, Callable
+from dataclasses import dataclass
+from typing import Any, Generic, TypeVar
+
+from ._errors import (
+    ClaudeSDKError,
+    CLIConnectionError,
+    CLIJSONDecodeError,
+    CLINotFoundError,
+    ProcessError,
+)
+from ._internal.transport import Transport
+from ._version import __version__
+from .client import ClaudeSDKClient
+from .query import query
+from .types import (
+    AgentDefinition,
+    AssistantMessage,
+    CanUseTool,
+    ClaudeAgentOptions,
+    ContentBlock,
+    HookCallback,
+    HookContext,
+    HookMatcher,
+    McpSdkServerConfig,
+    McpServerConfig,
+    Message,
+    PermissionMode,
+    PermissionResult,
+    PermissionResultAllow,
+    PermissionResultDeny,
+    PermissionUpdate,
+    ResultMessage,
+    SettingSource,
+    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. This is what Claude will use
+            to reference the tool in function calls.
+        description: Human-readable description of what the tool does.
+            This helps Claude understand when to use the tool.
+        input_schema: Schema defining the tool's input parameters.
+            Can be either:
+            - A dictionary mapping parameter names to types (e.g., {"text": str})
+            - A TypedDict class for more complex schemas
+            - A JSON Schema dictionary for full validation
+
+    Returns:
+        A decorator function that wraps the tool implementation and returns
+        an SdkMcpTool instance ready for use with create_sdk_mcp_server().
+
+    Example:
+        Basic tool with simple schema:
+        >>> @tool("greet", "Greet a user", {"name": str})
+        ... async def greet(args):
+        ...     return {"content": [{"type": "text", "text": f"Hello, {args['name']}!"}]}
+
+        Tool with multiple parameters:
+        >>> @tool("add", "Add two numbers", {"a": float, "b": float})
+        ... async def add_numbers(args):
+        ...     result = args["a"] + args["b"]
+        ...     return {"content": [{"type": "text", "text": f"Result: {result}"}]}
+
+        Tool with error handling:
+        >>> @tool("divide", "Divide two numbers", {"a": float, "b": float})
+        ... async def divide(args):
+        ...     if args["b"] == 0:
+        ...         return {"content": [{"type": "text", "text": "Error: Division by zero"}], "is_error": True}
+        ...     return {"content": [{"type": "text", "text": f"Result: {args['a'] / args['b']}"}]}
+
+    Notes:
+        - The tool function must be async (defined with async def)
+        - The function receives a single dict argument with the input parameters
+        - The function should return a dict with a "content" key containing the response
+        - Errors can be indicated by including "is_error": True in the response
+    """
+
+    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. This provides:
+    - Better performance (no IPC overhead)
+    - Simpler deployment (single process)
+    - Easier debugging (same process)
+    - Direct access to your application's state
+
+    Args:
+        name: Unique identifier for the server. This name is used to reference
+            the server in the mcp_servers configuration.
+        version: Server version string. Defaults to "1.0.0". This is for
+            informational purposes and doesn't affect functionality.
+        tools: List of SdkMcpTool instances created with the @tool decorator.
+            These are the functions that Claude can call through this server.
+            If None or empty, the server will have no tools (rarely useful).
+
+    Returns:
+        McpSdkServerConfig: A configuration object that can be passed to
+        ClaudeAgentOptions.mcp_servers. This config contains the server
+        instance and metadata needed for the SDK to route tool calls.
+
+    Example:
+        Simple calculator server:
+        >>> @tool("add", "Add numbers", {"a": float, "b": float})
+        ... async def add(args):
+        ...     return {"content": [{"type": "text", "text": f"Sum: {args['a'] + args['b']}"}]}
+        >>>
+        >>> @tool("multiply", "Multiply numbers", {"a": float, "b": float})
+        ... async def multiply(args):
+        ...     return {"content": [{"type": "text", "text": f"Product: {args['a'] * args['b']}"}]}
+        >>>
+        >>> calculator = create_sdk_mcp_server(
+        ...     name="calculator",
+        ...     version="2.0.0",
+        ...     tools=[add, multiply]
+        ... )
+        >>>
+        >>> # Use with Claude
+        >>> options = ClaudeAgentOptions(
+        ...     mcp_servers={"calc": calculator},
+        ...     allowed_tools=["add", "multiply"]
+        ... )
+
+        Server with application state access:
+        >>> class DataStore:
+        ...     def __init__(self):
+        ...         self.items = []
+        ...
+        >>> store = DataStore()
+        >>>
+        >>> @tool("add_item", "Add item to store", {"item": str})
+        ... async def add_item(args):
+        ...     store.items.append(args["item"])
+        ...     return {"content": [{"type": "text", "text": f"Added: {args['item']}"}]}
+        >>>
+        >>> server = create_sdk_mcp_server("store", tools=[add_item])
+
+    Notes:
+        - The server runs in the same process as your Python application
+        - Tools have direct access to your application's variables and state
+        - No subprocess or IPC overhead for tool calls
+        - Server lifecycle is managed automatically by the SDK
+
+    See Also:
+        - tool(): Decorator for creating tool functions
+        - ClaudeAgentOptions: Configuration for using servers with query()
+    """
+    from mcp.server import Server
+    from mcp.types import TextContent, Tool
+
+    # Create MCP server instance
+    server = Server(name, version=version)
+
+    # Register tools if provided
+    if tools:
+        # Store tools for access in handlers
+        tool_map = {tool_def.name: tool_def for tool_def in tools}
+
+        # Register list_tools handler to expose available tools
+        @server.list_tools()  # type: ignore[no-untyped-call,misc]
+        async def list_tools() -> list[Tool]:
+            """Return the list of available tools."""
+            tool_list = []
+            for tool_def in tools:
+                # Convert input_schema to JSON Schema format
+                if isinstance(tool_def.input_schema, dict):
+                    # Check if it's already a JSON schema
+                    if (
+                        "type" in tool_def.input_schema
+                        and "properties" in tool_def.input_schema
+                    ):
+                        schema = tool_def.input_schema
+                    else:
+                        # Simple dict mapping names to types - convert to JSON schema
+                        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"}  # Default
+                        schema = {
+                            "type": "object",
+                            "properties": properties,
+                            "required": list(properties.keys()),
+                        }
+                else:
+                    # For TypedDict or other types, create basic schema
+                    schema = {"type": "object", "properties": {}}
+
+                tool_list.append(
+                    Tool(
+                        name=tool_def.name,
+                        description=tool_def.description,
+                        inputSchema=schema,
+                    )
+                )
+            return tool_list
+
+        # Register call_tool handler to execute tools
+        @server.call_tool()  # type: ignore[misc]
+        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]
+            # Call the tool's handler with arguments
+            result = await tool_def.handler(arguments)
+
+            # Convert result to MCP format
+            # The decorator expects us to return the content, not a CallToolResult
+            # It will wrap our return value in CallToolResult
+            content = []
+            if "content" in result:
+                for item in result["content"]:
+                    if item.get("type") == "text":
+                        content.append(TextContent(type="text", text=item["text"]))
+
+            # Return just the content list - the decorator wraps it
+            return content
+
+    # Return SDK server configuration
+    return McpSdkServerConfig(type="sdk", name=name, instance=server)
+
+
+__all__ = [
+    # Main exports
+    "query",
+    "__version__",
+    # Transport
+    "Transport",
+    "ClaudeSDKClient",
+    # Types
+    "PermissionMode",
+    "McpServerConfig",
+    "McpSdkServerConfig",
+    "UserMessage",
+    "AssistantMessage",
+    "SystemMessage",
+    "ResultMessage",
+    "Message",
+    "ClaudeAgentOptions",
+    "TextBlock",
+    "ThinkingBlock",
+    "ToolUseBlock",
+    "ToolResultBlock",
+    "ContentBlock",
+    # Tool callbacks
+    "CanUseTool",
+    "ToolPermissionContext",
+    "PermissionResult",
+    "PermissionResultAllow",
+    "PermissionResultDeny",
+    "PermissionUpdate",
+    "HookCallback",
+    "HookContext",
+    "HookMatcher",
+    # Agent support
+    "AgentDefinition",
+    "SettingSource",
+    # MCP Server Support
+    "create_sdk_mcp_server",
+    "tool",
+    "SdkMcpTool",
+    # Errors
+    "ClaudeSDKError",
+    "CLIConnectionError",
+    "CLINotFoundError",
+    "ProcessError",
+    "CLIJSONDecodeError",
+]

claude_agent_sdk/_errors.py

@@ -0,0 +1,56 @@
+"""Error types for Claude SDK."""
+
+from typing import Any
+
+
+class ClaudeSDKError(Exception):
+    """Base exception for all Claude SDK errors."""
+
+
+class CLIConnectionError(ClaudeSDKError):
+    """Raised when unable to connect to Claude Code."""
+
+
+class CLINotFoundError(CLIConnectionError):
+    """Raised when Claude Code is not found or not installed."""
+
+    def __init__(
+        self, message: str = "Claude Code not found", cli_path: str | None = None
+    ):
+        if cli_path:
+            message = f"{message}: {cli_path}"
+        super().__init__(message)
+
+
+class ProcessError(ClaudeSDKError):
+    """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(ClaudeSDKError):
+    """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(ClaudeSDKError):
+    """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)

claude_agent_sdk/_internal/__init__.py

@@ -0,0 +1 @@
+"""Internal implementation details."""

claude_agent_sdk/_internal/client.py

@@ -0,0 +1,121 @@
+"""Internal client implementation."""
+
+from collections.abc import AsyncIterable, AsyncIterator
+from dataclasses import replace
+from typing import Any
+
+from ..types import (
+    ClaudeAgentOptions,
+    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:
+                # Convert HookMatcher to internal dict format
+                internal_matcher = {
+                    "matcher": matcher.matcher if hasattr(matcher, "matcher") else None,
+                    "hooks": matcher.hooks if hasattr(matcher, "hooks") else [],
+                }
+                internal_hooks[event].append(internal_matcher)
+        return internal_hooks
+
+    async def process_query(
+        self,
+        prompt: str | AsyncIterable[dict[str, Any]],
+        options: ClaudeAgentOptions,
+        transport: Transport | None = None,
+    ) -> AsyncIterator[Message]:
+        """Process a query through transport and Query."""
+
+        # Validate and configure permission settings (matching TypeScript SDK logic)
+        configured_options = options
+        if options.can_use_tool:
+            # canUseTool callback requires streaming mode (AsyncIterable prompt)
+            if isinstance(prompt, str):
+                raise ValueError(
+                    "can_use_tool callback requires streaming mode. "
+                    "Please provide prompt as an AsyncIterable instead of a string."
+                )
+
+            # canUseTool and permission_prompt_tool_name are mutually exclusive
+            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."
+                )
+
+            # Automatically set permission_prompt_tool_name to "stdio" for control protocol
+            configured_options = replace(options, permission_prompt_tool_name="stdio")
+
+        # Use provided transport or create subprocess transport
+        if transport is not None:
+            chosen_transport = transport
+        else:
+            chosen_transport = SubprocessCLITransport(
+                prompt=prompt, options=configured_options
+            )
+
+        # Connect transport
+        await chosen_transport.connect()
+
+        # Extract SDK MCP servers from configured options
+        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]
+
+        # Create Query to handle control protocol
+        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:
+            # Start reading messages
+            await query.start()
+
+            # Initialize if streaming
+            if is_streaming:
+                await query.initialize()
+
+            # Stream input if it's an AsyncIterable
+            if isinstance(prompt, AsyncIterable) and query._tg:
+                # Start streaming in background
+                # Create a task that will run in the background
+                query._tg.start_soon(query.stream_input, prompt)
+            # For string prompts, the prompt is already passed via CLI args
+
+            # Yield parsed messages
+            async for data in query.receive_messages():
+                yield parse_message(data)
+
+        finally:
+            await query.close()

claude_agent_sdk/_internal/message_parser.py

@@ -0,0 +1,172 @@
+"""Message parser for Claude Code 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")
+                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,
+                        parent_tool_use_id=parent_tool_use_id,
+                    )
+                return UserMessage(
+                    content=data["message"]["content"],
+                    parent_tool_use_id=parent_tool_use_id,
+                )
+            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":
+                            content_blocks.append(
+                                ThinkingBlock(
+                                    thinking=block["thinking"],
+                                    signature=block["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"]["model"],
+                    parent_tool_use_id=data.get("parent_tool_use_id"),
+                )
+            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["duration_ms"],
+                    duration_api_ms=data["duration_api_ms"],
+                    is_error=data["is_error"],
+                    num_turns=data["num_turns"],
+                    session_id=data["session_id"],
+                    total_cost_usd=data.get("total_cost_usd"),
+                    usage=data.get("usage"),
+                    result=data.get("result"),
+                )
+            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)