# Raysurfer Python SDK

Drop-in replacement for Claude Agent SDK with automatic code caching.

## Quick Start

Simply swap your import:

```python
# Before
from claude_agent_sdk import ClaudeSDKClient, ClaudeAgentOptions

# After
from raysurfer import ClaudeSDKClient, ClaudeAgentOptions
```

Set the `RAYSURFER_API_KEY` environment variable to enable caching. Everything else works exactly the same.

## How It Works

1. **On query**: Automatically retrieves relevant cached code and injects it into the system prompt
2. **On success**: Automatically uploads generated code to the cache for future reuse
3. **No caching?**: If `RAYSURFER_API_KEY` isn't set, behaves exactly like the original SDK

## Example

```python
import os
from raysurfer import ClaudeSDKClient, ClaudeAgentOptions

os.environ["RAYSURFER_API_KEY"] = "rs_..."

options = ClaudeAgentOptions(
    allowed_tools=["Read", "Write", "Bash"],
    system_prompt="You are a helpful assistant.",
)

async with ClaudeSDKClient(options=options) as client:
    await client.query("Fetch data from GitHub API")
    async for msg in client.receive_response():
        print(msg)
```

## Direct API Access

For advanced use cases, you can use the low-level client directly:

```python
from raysurfer import AsyncRaySurfer

async with AsyncRaySurfer(api_key="rs_...") as client:
    # Store a code block
    await client.store_code_block(
        name="GitHub User Fetcher",
        source="def fetch_user(username): ...",
        entrypoint="fetch_user",
        language="python",
    )

    # Retrieve code blocks
    response = await client.retrieve(task="Fetch GitHub user data")
```

## Package Managers

Use `uv` for all Python operations.
