Ripperdoc Python SDK

Python SDK for Ripperdoc AI Agent.

Overview

This SDK is a fork of Anthropic's Claude Agent SDK Python and maintains full API compatibility with it. The Ripperdoc SDK extends the original SDK with support for multiple LLM providers (not just Claude) while keeping the same interface and usage patterns.

Compatibility: If you have code using claude_agent_sdk, you can easily migrate by simply changing the imports from claude_agent_sdk to ripperdoc_agent_sdk and using RipperdocAgentOptions instead of ClaudeAgentOptions. All other API calls remain the same.

Features

• Subprocess Architecture: Clean separation between SDK and CLI via JSON Control Protocol
• Async-First: Built with asyncio and anyio for efficient async operations
• Type Safety: Full type hints for better IDE support and type checking
• Comprehensive: Support for hooks, permissions, MCP servers, and custom tools

Installation

Install from PyPI:

pip install ripperdoc-agent-sdk

Install from GitHub:

pip install git+https://github.com/quantmew/ripperdoc-agent-sdk-python

For development:

pip install git+https://github.com/quantmew/ripperdoc-agent-sdk-python#egg=ripperdoc-agent-sdk[dev]

Quick Start

Simple Query

importasynciofromripperdoc_agent_sdkimportquery, RipperdocAgentOptionsasyncdefmain():
asyncformessageinquery(
prompt="What is the capital of France?",
options=RipperdocAgentOptions()
):
print(message)
asyncio.run(main())

Persistent Client

importasynciofromripperdoc_agent_sdkimportRipperdocSDKClient, RipperdocAgentOptionsasyncdefmain():
asyncwithRipperdocSDKClient(options=RipperdocAgentOptions()) asclient:
awaitclient.query("Help me understand this code")
asyncformessageinclient.receive_messages():
ifisinstance(message, AssistantMessage):
forblockinmessage.content:
ifisinstance(block, TextBlock):
print(block.text)
asyncio.run(main())

Configuration

RipperdocAgentOptions

fromripperdoc_agent_sdkimportRipperdocAgentOptionsoptions=RipperdocAgentOptions(
model="model-name",
permission_mode="default", # or "acceptEdits", "bypassPermissions", "plan"allowed_tools=["Bash", "Read", "Write"],
max_turns=10,
system_prompt="You are a helpful coding assistant",
cli_path="/path/to/ripperdoc", # Optional: path to Ripperdoc CLI
)

Permission Modes

• "default": Prompts for dangerous operations
• "acceptEdits": Auto-accept file edits
• "bypassPermissions": Allow all operations (use with caution)
• "plan": Planning mode with no execution

Advanced Usage

Custom Permission Checker

fromripperdoc_agent_sdkimport (
RipperdocSDKClient,
RipperdocAgentOptions,
PermissionResultAllow,
PermissionResultDeny,
)
asyncdefmy_permission_checker(tool_name, tool_input, context):
# Custom permission logiciftool_name=="Bash"and"rm -rf"intool_input.get("command", ""):
returnPermissionResultDeny(message="Dangerous command!")
returnPermissionResultAllow()
options=RipperdocAgentOptions(
permission_checker=my_permission_checker,
)

Programmatic Hooks

fromripperdoc_agent_sdkimportRipperdocAgentOptions, HookMatcherasyncdefmy_hook(event_type, data):
print(f"Hook event: {event_type}")
return {"continue_": True}
options=RipperdocAgentOptions(
hooks={
"PreToolUse": [
HookMatcher(
callback=my_hook,
tool_pattern="Bash*",
)
]
},
)

MCP Servers

fromripperdoc_agent_sdkimportRipperdocAgentOptions, McpServerConfigoptions=RipperdocAgentOptions(
mcp_servers={
"my-server": McpServerConfig(
type="stdio",
command="node",
args=["/path/to/server.js"],
)
},
)

Custom Agents

fromripperdoc_agent_sdkimportRipperdocAgentOptions, AgentConfigoptions=RipperdocAgentOptions(
agents={
"code-reviewer": AgentConfig(
description="Reviews code for bugs and style issues",
prompt="You are a code reviewer. Focus on bug detection and style.",
tools=["Read", "Grep"],
)
},
)

Message Types

The SDK provides the following message types:

• UserMessage: Messages from the user
• AssistantMessage: Responses from the AI
• SystemMessage: System-level events
• ResultMessage: Query completion with metadata
• StreamEvent: Raw stream events

Content Blocks

• TextBlock: Plain text content
• ThinkingBlock: Extended thinking output
• ToolUseBlock: Tool invocation
• ToolResultBlock: Tool execution result

Architecture

The SDK uses a subprocess architecture:

┌─────────────────────┐
│ Python SDK │
│ │
│ ┌───────────────┐ │
│ │ Ripperdoc │ │
│ │ SDK Client │ │
│ └───────┬───────┘ │
│ │ │
│ ┌───────▼───────┐ │
│ │ JSON Control │ │
│ │ Protocol │ │
│ └───────┬───────┘ │
└──────────┼──────────┘
│ stdio
┌──────▼─────────┐
│ Ripperdoc │
│ CLI Process │
└────────────────┘

Development

Running Tests

pytest tests/

Type Checking

mypy ripperdoc_agent_sdk

Code Formatting

black ripperdoc_agent_sdk
ruff check ripperdoc_agent_sdk

Requirements

• Python 3.10+
• anyio >= 4.0.0
• pydantic >= 2.0.0

License

Apache License 2.0

Contributing

Contributions are welcome! Please read our contributing guidelines before submitting PRs.

Related Projects

• Ripperdoc CLI - The main Ripperdoc CLI that works with multiple LLM providers
• Claude Agent SDK Python - The original Anthropic SDK that this project is based on
• Claude Code - Anthropic's official CLI tool

Migration from Claude Agent SDK

If you're already using the Claude Agent SDK, migrating is straightforward:

# Before (Claude Agent SDK)fromclaude_agent_sdkimportquery, ClaudeAgentOptionsoptions=ClaudeAgentOptions(
system_prompt="You are a helpful assistant",
permission_mode='acceptEdits',
)
# After (Ripperdoc SDK)fromripperdoc_agent_sdkimportquery, RipperdocAgentOptionsoptions=RipperdocAgentOptions(
system_prompt="You are a helpful assistant",
permission_mode='acceptEdits',
)

The rest of your code remains exactly the same. The Ripperdoc SDK provides the same API with the added benefit of supporting multiple LLM providers beyond just Claude.