600 lines
21 KiB
Python
600 lines
21 KiB
Python
import asyncio
|
|
import json
|
|
import os
|
|
from pathlib import Path
|
|
from typing import Any, Optional
|
|
|
|
from modaic import PrecompiledProgram, PrecompiledConfig
|
|
from pydantic import BaseModel
|
|
|
|
import dspy
|
|
from dspy.primitives.prediction import Prediction
|
|
|
|
from claude_agent_sdk import (
|
|
ClaudeSDKClient,
|
|
ClaudeAgentOptions,
|
|
AssistantMessage,
|
|
ResultMessage,
|
|
SystemMessage,
|
|
TextBlock,
|
|
ThinkingBlock,
|
|
ToolUseBlock,
|
|
ToolResultBlock,
|
|
)
|
|
|
|
from .trace import (
|
|
TraceItem,
|
|
AgentMessageItem,
|
|
ThinkingItem,
|
|
ToolUseItem,
|
|
ToolResultItem,
|
|
ErrorItem,
|
|
)
|
|
from .utils import (
|
|
Usage,
|
|
is_pydantic_model,
|
|
get_json_schema,
|
|
parse_json_response,
|
|
extract_text_from_response,
|
|
)
|
|
|
|
|
|
class ClaudeCodeConfig(PrecompiledConfig):
|
|
"""Configuration for ClaudeCode agent."""
|
|
|
|
model: str = "claude-opus-4-5-20251101"
|
|
|
|
class ClaudeCodeKwargs(BaseModel):
|
|
"""Arguments for ClaudeCode initialization.
|
|
|
|
Matches ClaudeAgentOptions from the SDK with additional DSPy-specific fields.
|
|
See: https://platform.claude.com/docs/en/agent-sdk/python#claudeagentoptions
|
|
"""
|
|
|
|
# DSPy-specific (required)
|
|
signature: Any # str | dspy.Signature - validated manually in __init__
|
|
|
|
# Authentication
|
|
api_key: str | None = None
|
|
|
|
# Basic configuration
|
|
working_directory: str = "."
|
|
permission_mode: str | None = None
|
|
allowed_tools: list[str] | None = None # Any Claude Code tools
|
|
disallowed_tools: list[str] | None = None
|
|
sandbox: dict[str, Any] | None = None
|
|
system_prompt: str | dict[str, Any] | None = None
|
|
|
|
# MCP servers
|
|
mcp_servers: dict[str, Any] | str | Path | None = None
|
|
|
|
# Session management
|
|
continue_conversation: bool = False
|
|
resume: str | None = None
|
|
max_turns: int | None = None
|
|
fork_session: bool = False
|
|
|
|
# Advanced options
|
|
permission_prompt_tool_name: str | None = None
|
|
settings: str | None = None
|
|
add_dirs: list[str | Path] | None = None
|
|
env: dict[str, str] | None = None
|
|
extra_args: dict[str, str | None] | None = None
|
|
max_buffer_size: int | None = None
|
|
|
|
# Callbacks and hooks
|
|
stderr: Any | None = None # Callable[[str], None] - can't type check callables in Pydantic easily
|
|
can_use_tool: Any | None = None # CanUseTool callback
|
|
hooks: dict[str, list[dict[str, Any]]] | None = None
|
|
|
|
# User and settings
|
|
user: str | None = None
|
|
include_partial_messages: bool = False
|
|
setting_sources: list[str] | None = None # List of "user" | "project" | "local"
|
|
|
|
# Subagents and plugins
|
|
agents: dict[str, dict[str, Any]] | None = None
|
|
plugins: list[dict[str, Any]] | None = None
|
|
|
|
# CLI configuration
|
|
cli_path: str | Path | None = None
|
|
|
|
|
|
class ClaudeCode(PrecompiledProgram):
|
|
"""DSPy module that wraps Claude Code SDK.
|
|
|
|
Each agent instance maintains a stateful conversation session.
|
|
Perfect for multi-turn agentic workflows with context preservation.
|
|
|
|
Example:
|
|
>>> config = ClaudeCodeConfig()
|
|
>>> agent = ClaudeCode(
|
|
... config,
|
|
... signature='message:str -> answer:str',
|
|
... working_directory="."
|
|
... )
|
|
>>> result = agent(message="What files are in this directory?")
|
|
>>> print(result.answer) # Typed access
|
|
>>> print(result.trace) # Execution trace
|
|
>>> print(result.usage) # Token usage
|
|
"""
|
|
|
|
config: ClaudeCodeConfig
|
|
|
|
def __init__(
|
|
self,
|
|
config: ClaudeCodeConfig,
|
|
**kwargs: dict,
|
|
):
|
|
super().__init__(config=config)
|
|
|
|
args = ClaudeCodeKwargs(**kwargs)
|
|
|
|
# Parse and validate signature
|
|
signature = args.signature
|
|
if isinstance(signature, str):
|
|
self.signature = dspy.Signature(signature)
|
|
else:
|
|
self.signature = signature
|
|
|
|
# Validate signature has exactly 1 input and 1 output
|
|
input_fields = list(self.signature.input_fields.keys())
|
|
output_fields = list(self.signature.output_fields.keys())
|
|
|
|
if len(input_fields) != 1:
|
|
raise ValueError(
|
|
f"ClaudeCode requires exactly 1 input field, got {len(input_fields)}. "
|
|
f"Found: {input_fields}"
|
|
)
|
|
|
|
if len(output_fields) != 1:
|
|
raise ValueError(
|
|
f"ClaudeCode requires exactly 1 output field, got {len(output_fields)}. "
|
|
f"Found: {output_fields}"
|
|
)
|
|
|
|
self.input_field_name = input_fields[0]
|
|
self.output_field_name = output_fields[0]
|
|
self.input_field = self.signature.input_fields[self.input_field_name]
|
|
self.output_field = self.signature.output_fields[self.output_field_name]
|
|
|
|
# Store all configuration values
|
|
self.api_key = args.api_key or os.getenv("ANTHROPIC_API_KEY")
|
|
self.working_directory = Path(args.working_directory).resolve()
|
|
self.model = config.model
|
|
|
|
# Basic options
|
|
self.permission_mode = args.permission_mode
|
|
self.allowed_tools = args.allowed_tools
|
|
self.disallowed_tools = args.disallowed_tools
|
|
self.sandbox = args.sandbox
|
|
self.system_prompt = args.system_prompt
|
|
|
|
# MCP servers
|
|
self.mcp_servers = args.mcp_servers
|
|
|
|
# Session management
|
|
self.continue_conversation = args.continue_conversation
|
|
self.resume = args.resume
|
|
self.max_turns = args.max_turns
|
|
self.fork_session = args.fork_session
|
|
|
|
# Advanced options
|
|
self.permission_prompt_tool_name = args.permission_prompt_tool_name
|
|
self.settings = args.settings
|
|
self.add_dirs = args.add_dirs
|
|
self.env = args.env
|
|
self.extra_args = args.extra_args
|
|
self.max_buffer_size = args.max_buffer_size
|
|
|
|
# Callbacks and hooks
|
|
self.stderr = args.stderr
|
|
self.can_use_tool = args.can_use_tool
|
|
self.hooks = args.hooks
|
|
|
|
# User and settings
|
|
self.user = args.user
|
|
self.include_partial_messages = args.include_partial_messages
|
|
self.setting_sources = args.setting_sources
|
|
|
|
# Subagents and plugins
|
|
self.agents = args.agents
|
|
self.plugins = args.plugins
|
|
|
|
# CLI configuration
|
|
self.cli_path = args.cli_path
|
|
|
|
# determine output format upfront
|
|
self.output_format = self._get_output_format()
|
|
|
|
# session state
|
|
self._client: Optional[ClaudeSDKClient] = None
|
|
self._session_id: Optional[str] = None
|
|
self._is_connected = False
|
|
|
|
@property
|
|
def session_id(self) -> Optional[str]:
|
|
"""Get the session ID for this agent instance.
|
|
|
|
Returns None until first forward() call.
|
|
"""
|
|
return self._session_id
|
|
|
|
def _create_client(self) -> ClaudeSDKClient:
|
|
"""Create ClaudeSDKClient with configured options."""
|
|
# Build options dict, only including non-None values
|
|
options_dict = {
|
|
"cwd": str(self.working_directory),
|
|
"model": self.model,
|
|
"output_format": self.output_format,
|
|
}
|
|
|
|
# Add optional fields only if they're not None
|
|
if self.permission_mode is not None:
|
|
options_dict["permission_mode"] = self.permission_mode
|
|
if self.allowed_tools is not None:
|
|
options_dict["allowed_tools"] = self.allowed_tools
|
|
if self.disallowed_tools is not None:
|
|
options_dict["disallowed_tools"] = self.disallowed_tools
|
|
if self.sandbox is not None:
|
|
options_dict["sandbox"] = self.sandbox
|
|
if self.system_prompt is not None:
|
|
options_dict["system_prompt"] = self.system_prompt
|
|
if self.mcp_servers is not None:
|
|
options_dict["mcp_servers"] = self.mcp_servers
|
|
if self.continue_conversation:
|
|
options_dict["continue_conversation"] = self.continue_conversation
|
|
if self.resume is not None:
|
|
options_dict["resume"] = self.resume
|
|
if self.max_turns is not None:
|
|
options_dict["max_turns"] = self.max_turns
|
|
if self.fork_session:
|
|
options_dict["fork_session"] = self.fork_session
|
|
if self.permission_prompt_tool_name is not None:
|
|
options_dict["permission_prompt_tool_name"] = self.permission_prompt_tool_name
|
|
if self.settings is not None:
|
|
options_dict["settings"] = self.settings
|
|
if self.add_dirs is not None:
|
|
options_dict["add_dirs"] = self.add_dirs
|
|
if self.env is not None:
|
|
options_dict["env"] = self.env
|
|
if self.extra_args is not None:
|
|
options_dict["extra_args"] = self.extra_args
|
|
if self.max_buffer_size is not None:
|
|
options_dict["max_buffer_size"] = self.max_buffer_size
|
|
if self.stderr is not None:
|
|
options_dict["stderr"] = self.stderr
|
|
if self.can_use_tool is not None:
|
|
options_dict["can_use_tool"] = self.can_use_tool
|
|
if self.hooks is not None:
|
|
options_dict["hooks"] = self.hooks
|
|
if self.user is not None:
|
|
options_dict["user"] = self.user
|
|
if self.include_partial_messages:
|
|
options_dict["include_partial_messages"] = self.include_partial_messages
|
|
if self.setting_sources is not None:
|
|
options_dict["setting_sources"] = self.setting_sources
|
|
if self.agents is not None:
|
|
options_dict["agents"] = self.agents
|
|
if self.plugins is not None:
|
|
options_dict["plugins"] = self.plugins
|
|
if self.cli_path is not None:
|
|
options_dict["cli_path"] = self.cli_path
|
|
|
|
options = ClaudeAgentOptions(**options_dict)
|
|
|
|
# Set API key if provided
|
|
if self.api_key:
|
|
os.environ["ANTHROPIC_API_KEY"] = self.api_key
|
|
|
|
return ClaudeSDKClient(options=options)
|
|
|
|
def _build_prompt(self, input_value: str) -> str:
|
|
"""Build prompt from signature docstring, field descriptions, and input value."""
|
|
prompt_parts = []
|
|
|
|
# add signature docstring if present
|
|
if self.signature.__doc__:
|
|
doc = self.signature.__doc__.strip()
|
|
if doc:
|
|
prompt_parts.append(f"Task: {doc}")
|
|
|
|
# add input field description if present
|
|
# DSPy fields store desc in json_schema_extra
|
|
input_desc = None
|
|
if (
|
|
hasattr(self.input_field, "json_schema_extra")
|
|
and self.input_field.json_schema_extra
|
|
):
|
|
input_desc = self.input_field.json_schema_extra.get("desc")
|
|
|
|
if input_desc:
|
|
prompt_parts.append(f"Input context: {input_desc}")
|
|
|
|
# add the actual input value
|
|
prompt_parts.append(input_value)
|
|
|
|
# add output field description if present
|
|
output_desc = None
|
|
if (
|
|
hasattr(self.output_field, "json_schema_extra")
|
|
and self.output_field.json_schema_extra
|
|
):
|
|
output_desc = self.output_field.json_schema_extra.get("desc")
|
|
|
|
if output_desc:
|
|
prompt_parts.append(f"\nPlease produce the following output: {output_desc}")
|
|
|
|
# for Pydantic outputs, add explicit JSON instructions
|
|
if self.output_format:
|
|
schema = self.output_format["schema"]
|
|
prompt_parts.append(
|
|
f"\nYou MUST respond with ONLY valid JSON matching this schema:\n"
|
|
f"{json.dumps(schema, indent=2)}\n\n"
|
|
f"Do not include any explanatory text, markdown formatting, or code blocks. "
|
|
f"Return ONLY the raw JSON object."
|
|
)
|
|
|
|
return "\n\n".join(prompt_parts)
|
|
|
|
def _get_output_format(self) -> Optional[dict[str, Any]]:
|
|
"""Get output format configuration for structured outputs."""
|
|
output_type = self.output_field.annotation
|
|
|
|
if is_pydantic_model(output_type):
|
|
schema = get_json_schema(output_type)
|
|
return {
|
|
"type": "json_schema",
|
|
"schema": schema,
|
|
}
|
|
|
|
return None
|
|
|
|
async def _run_async(self, prompt: str) -> tuple[str, list[TraceItem], Usage]:
|
|
"""Run the agent asynchronously and collect results."""
|
|
# create client if needed
|
|
if self._client is None:
|
|
self._client = self._create_client()
|
|
|
|
# connect if not already connected
|
|
if not self._is_connected:
|
|
await self._client.connect()
|
|
self._is_connected = True
|
|
|
|
# send query (output_format already configured in options)
|
|
await self._client.query(prompt)
|
|
|
|
# collect messages and build trace
|
|
trace: list[TraceItem] = []
|
|
usage = Usage()
|
|
response_text = ""
|
|
|
|
async for message in self._client.receive_response():
|
|
# handle assistant messages
|
|
if isinstance(message, AssistantMessage):
|
|
for block in message.content:
|
|
if isinstance(block, TextBlock):
|
|
response_text += block.text
|
|
trace.append(
|
|
AgentMessageItem(text=block.text, model=message.model)
|
|
)
|
|
elif isinstance(block, ThinkingBlock):
|
|
trace.append(
|
|
ThinkingItem(text=block.thinking, model=message.model)
|
|
)
|
|
elif isinstance(block, ToolUseBlock):
|
|
# Handle StructuredOutput tool (contains JSON response)
|
|
if block.name == "StructuredOutput":
|
|
# The JSON is directly in the tool input (already a dict)
|
|
response_text = json.dumps(block.input)
|
|
|
|
trace.append(
|
|
ToolUseItem(
|
|
tool_name=block.name,
|
|
tool_input=block.input,
|
|
tool_use_id=block.id,
|
|
)
|
|
)
|
|
elif isinstance(block, ToolResultBlock):
|
|
content_str = ""
|
|
if isinstance(block.content, str):
|
|
content_str = block.content
|
|
elif isinstance(block.content, list):
|
|
# Extract text from content blocks
|
|
for item in block.content:
|
|
if (
|
|
isinstance(item, dict)
|
|
and item.get("type") == "text"
|
|
):
|
|
content_str += item.get("text", "")
|
|
|
|
trace.append(
|
|
ToolResultItem(
|
|
tool_name="", # Tool name not in ToolResultBlock
|
|
tool_use_id=block.tool_use_id,
|
|
content=content_str,
|
|
is_error=block.is_error or False,
|
|
)
|
|
)
|
|
|
|
# handle result messages (final message with usage info)
|
|
elif isinstance(message, ResultMessage):
|
|
# store session ID
|
|
if hasattr(message, "session_id"):
|
|
self._session_id = message.session_id
|
|
|
|
# extract usage
|
|
if hasattr(message, "usage") and message.usage:
|
|
usage_data = message.usage
|
|
usage = Usage(
|
|
input_tokens=usage_data.get("input_tokens", 0),
|
|
cached_input_tokens=usage_data.get(
|
|
"cache_read_input_tokens", 0
|
|
),
|
|
output_tokens=usage_data.get("output_tokens", 0),
|
|
)
|
|
|
|
# check for errors
|
|
if hasattr(message, "is_error") and message.is_error:
|
|
error_msg = (
|
|
message.result
|
|
if hasattr(message, "result")
|
|
else "Unknown error"
|
|
)
|
|
trace.append(
|
|
ErrorItem(message=error_msg, error_type="execution_error")
|
|
)
|
|
raise RuntimeError(f"Agent execution failed: {error_msg}")
|
|
|
|
# extract result if present (for structured outputs from result field)
|
|
# Note: structured outputs may come from StructuredOutput tool instead
|
|
if hasattr(message, "result") and message.result:
|
|
response_text = message.result
|
|
|
|
# handle system messages
|
|
elif isinstance(message, SystemMessage):
|
|
# log system messages to trace but don't error
|
|
if hasattr(message, "data") and message.data:
|
|
data_str = str(message.data)
|
|
trace.append(
|
|
AgentMessageItem(text=f"[System: {data_str}]", model="system")
|
|
)
|
|
|
|
return response_text, trace, usage
|
|
|
|
def forward(self, **kwargs: Any) -> Prediction:
|
|
"""Execute the agent with an input message.
|
|
|
|
Args:
|
|
**kwargs: Must contain the input field specified in signature
|
|
|
|
Returns:
|
|
Prediction with:
|
|
- Typed output field (named according to signature)
|
|
- trace: list[TraceItem] - Execution trace
|
|
- usage: Usage - Token usage statistics
|
|
|
|
Example:
|
|
>>> result = agent(message="Hello")
|
|
>>> print(result.answer) # Access typed output
|
|
>>> print(result.trace) # List of execution items
|
|
>>> print(result.usage) # Token usage stats
|
|
"""
|
|
# extract input value
|
|
if self.input_field_name not in kwargs:
|
|
raise ValueError(
|
|
f"Missing required input field: {self.input_field_name}. "
|
|
f"Received: {list(kwargs.keys())}"
|
|
)
|
|
|
|
input_value = kwargs[self.input_field_name]
|
|
|
|
# build prompt
|
|
prompt = self._build_prompt(input_value)
|
|
|
|
# run async execution in event loop
|
|
try:
|
|
loop = asyncio.get_event_loop()
|
|
if loop.is_running():
|
|
# If already in async context, create new loop
|
|
import nest_asyncio
|
|
|
|
nest_asyncio.apply()
|
|
response_text, trace, usage = loop.run_until_complete(
|
|
self._run_async(prompt)
|
|
)
|
|
else:
|
|
response_text, trace, usage = loop.run_until_complete(
|
|
self._run_async(prompt)
|
|
)
|
|
except RuntimeError:
|
|
# no event loop, create one
|
|
response_text, trace, usage = asyncio.run(self._run_async(prompt))
|
|
|
|
# parse response based on output type
|
|
output_type = self.output_field.annotation
|
|
if is_pydantic_model(output_type):
|
|
try:
|
|
parsed_output = parse_json_response(response_text, output_type)
|
|
except Exception as e:
|
|
raise ValueError(
|
|
f"Failed to parse Claude response as {output_type.__name__}: {e}\n"
|
|
f"Response: {response_text}"
|
|
)
|
|
else:
|
|
# string output - extract text
|
|
parsed_output = extract_text_from_response(response_text)
|
|
|
|
# return prediction with typed output, trace, and usage
|
|
return Prediction(
|
|
**{
|
|
self.output_field_name: parsed_output,
|
|
"trace": trace,
|
|
"usage": usage,
|
|
}
|
|
)
|
|
|
|
async def aforward(self, **kwargs: Any) -> Prediction:
|
|
"""Async version of forward().
|
|
|
|
Use this when already in an async context to avoid event loop issues.
|
|
|
|
Args:
|
|
**kwargs: Must contain the input field specified in signature
|
|
|
|
Returns:
|
|
Prediction with typed output, trace, and usage
|
|
"""
|
|
# extract input value
|
|
if self.input_field_name not in kwargs:
|
|
raise ValueError(
|
|
f"Missing required input field: {self.input_field_name}. "
|
|
f"Received: {list(kwargs.keys())}"
|
|
)
|
|
|
|
input_value = kwargs[self.input_field_name]
|
|
|
|
# build prompt
|
|
prompt = self._build_prompt(input_value)
|
|
|
|
# run async execution
|
|
response_text, trace, usage = await self._run_async(prompt)
|
|
|
|
# parse response based on output type
|
|
output_type = self.output_field.annotation
|
|
if is_pydantic_model(output_type):
|
|
try:
|
|
parsed_output = parse_json_response(response_text, output_type)
|
|
except Exception as e:
|
|
raise ValueError(
|
|
f"Failed to parse Claude response as {output_type.__name__}: {e}\n"
|
|
f"Response: {response_text}"
|
|
)
|
|
else:
|
|
# string output - extract text
|
|
parsed_output = extract_text_from_response(response_text)
|
|
|
|
# return prediction with typed output, trace, and usage
|
|
return Prediction(
|
|
**{
|
|
self.output_field_name: parsed_output,
|
|
"trace": trace,
|
|
"usage": usage,
|
|
}
|
|
)
|
|
|
|
async def disconnect(self) -> None:
|
|
"""Disconnect from Claude Code and clean up resources."""
|
|
if self._client and self._is_connected:
|
|
await self._client.disconnect()
|
|
self._is_connected = False
|
|
|
|
def __del__(self):
|
|
"""Cleanup on deletion."""
|
|
if self._client and self._is_connected:
|
|
try:
|
|
asyncio.run(self.disconnect())
|
|
except Exception:
|
|
# best effort cleanup
|
|
pass
|