raysurfer 0.2.2__tar.gz

raysurfer-0.2.2/.github/workflows/ci.yml

@@ -0,0 +1,38 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+jobs:
+  test:
+    name: Test
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ['3.10', '3.11', '3.12']
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+
+      - name: Setup Python ${{ matrix.python-version }}
+        uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v4
+        with:
+          version: latest
+
+      - name: Install dependencies
+        run: uv pip install -e ".[dev]" --system
+
+      - name: Run linter
+        run: uv run ruff check .
+
+      - name: Run tests
+        run: uv run pytest tests/ -v --tb=short

raysurfer-0.2.2/.gitignore

@@ -0,0 +1,27 @@
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+.env
+.venv
+env/
+venv/
+.pytest_cache/
+.ruff_cache/
+.mypy_cache/

raysurfer-0.2.2/CLAUDE.md

@@ -0,0 +1,217 @@
+# Raysurfer Python SDK
+
+Python SDK for Raysurfer - code block caching and retrieval for AI agents with Claude Agent SDK integration.
+
+## Project Goal
+
+**Make AI agents 20-30x faster by reusing cached code instead of regenerating it every time.**
+
+The problem: When an AI agent encounters a task like "fetch GitHub user data", it typically:
+1. Thinks about the approach (2-5s)
+2. Generates code from scratch (5-15s)
+3. Writes the file (0.5s)
+4. Runs and iterates (variable)
+
+This happens **every single time**, even for identical or similar tasks.
+
+The solution: RaySurfer caches proven code blocks and retrieves them via semantic search:
+1. Check cache for matching code (50-200ms)
+2. If hit: return ready-to-run code instantly
+3. If miss: generate with agent, then cache for next time
+
+**Measured Results:**
+- Without RaySurfer: 34.2s, 11 iterations, 2 tool calls
+- With RaySurfer: 1.4s, 1 iteration, 0 tool calls
+- **Speedup: 24x faster**
+
+## Architecture
+
+- **Backend**: FastAPI on Railway, uses Pinecone for vector storage, Fireworks for embeddings
+- **SDK**: This Python package - async/sync clients for store/retrieve operations
+- **Integration**: Drop-in enhancement for Claude Agent SDK workflows
+
+## Installation
+
+```bash
+pip install raysurfer
+```
+
+## Quick Start
+
+### Basic Client (Store/Retrieve Code Blocks)
+
+```python
+from raysurfer import AsyncRaySurfer
+
+async with AsyncRaySurfer(api_key="rs_...") as client:
+    # Store a code block
+    result = await client.store_code_block(
+        name="GitHub User Fetcher",
+        source="def fetch_user(username): ...",
+        entrypoint="fetch_user",
+        language="python",
+    )
+
+    # Retrieve code blocks for a task
+    response = await client.retrieve(task="Fetch GitHub user data")
+    for match in response.code_blocks:
+        print(match.code_block.name, match.verdict_score)
+```
+
+### Claude Agent SDK Integration
+
+```python
+from raysurfer import RaysurferClient, RaysurferAgentOptions
+
+options = RaysurferAgentOptions(
+    raysurfer_api_key="rs_...",
+    allowed_tools=["Read", "Write", "Bash"],
+    system_prompt="You are a helpful assistant.",
+    model="claude-opus-4-5",  # Default
+)
+
+async with RaysurferClient(options=options) as client:
+    # Pre-fetches code files, downloads to sandbox, injects into prompt
+    await client.query("Fetch user data from GitHub API")
+
+    # Agent sees code files in system prompt and can execute with Bash
+    async for msg in client.receive_response():
+        print(msg)
+```
+
+## RaysurferAgentOptions
+
+Drop-in replacement options for `ClaudeAgentOptions` with Raysurfer-specific settings:
+
+```python
+@dataclass
+class RaysurferAgentOptions:
+    # Raysurfer-specific
+    raysurfer_api_key: str | None = None
+    raysurfer_base_url: str = "https://api.raysurfer.com"
+    prefetch_count: int = 5
+    min_verdict_score: float = 0.3
+    prefer_complete: bool = True
+    sandbox_dir: Path = ~/.raysurfer/sandbox
+
+    # Standard ClaudeAgentOptions (all passed through)
+    allowed_tools: list[str] | None = None
+    model: str = "claude-opus-4-5"
+    system_prompt: str | dict | None = None
+    sandbox: dict | None = None
+    # ... all other ClaudeAgentOptions fields
+```
+
+## How It Works
+
+1. **On `query()`**: RaysurferClient calls the backend to get relevant code files
+2. **Downloads to sandbox**: Files are written to `~/.raysurfer/sandbox/`
+3. **Injects into prompt**: Code snippets are added to the system prompt
+4. **Agent executes**: Agent can run the code using the Bash tool within the sandbox
+
+---
+
+# Claude Agent SDK Python Reference
+
+## Core Classes
+
+### `ClaudeSDKClient`
+
+```python
+async with ClaudeSDKClient(options=options) as client:
+    await client.query("Hello Claude")
+    async for message in client.receive_response():
+        print(message)
+```
+
+### `ClaudeAgentOptions`
+
+```python
+ClaudeAgentOptions(
+    allowed_tools=["Read", "Write", "Bash"],
+    disallowed_tools=[],
+    permission_mode="acceptEdits",  # or "default", "plan", "bypassPermissions"
+    system_prompt="You are helpful.",
+    model="claude-opus-4-5",
+    cwd="/path/to/project",
+    sandbox={"enabled": True},
+    max_turns=10,
+    # ... more options
+)
+```
+
+Key parameters:
+- `allowed_tools`: Tools the agent can use
+- `permission_mode`: How permissions are handled
+- `model`: Claude model to use
+- `sandbox`: Enable sandboxed execution
+- `setting_sources`: `["user", "project", "local"]` to load CLAUDE.md files
+
+### `SandboxSettings`
+
+```python
+sandbox={
+    "enabled": True,
+    "autoAllowBashIfSandboxed": True,
+    "excludedCommands": ["docker"],
+    "network": {
+        "allowLocalBinding": True,
+    }
+}
+```
+
+## Message Types
+
+```python
+from claude_agent_sdk import (
+    AssistantMessage,
+    TextBlock,
+    ToolUseBlock,
+    ResultMessage,
+)
+
+async for message in client.receive_response():
+    if isinstance(message, AssistantMessage):
+        for block in message.content:
+            if isinstance(block, TextBlock):
+                print(block.text)
+            elif isinstance(block, ToolUseBlock):
+                print(f"Using tool: {block.name}")
+    elif isinstance(message, ResultMessage):
+        print(f"Done! Cost: ${message.total_cost_usd}")
+```
+
+## Custom Tools
+
+```python
+from claude_agent_sdk import tool, create_sdk_mcp_server
+
+@tool("greet", "Greet a user", {"name": str})
+async def greet(args):
+    return {"content": [{"type": "text", "text": f"Hello, {args['name']}!"}]}
+
+server = create_sdk_mcp_server("my-tools", tools=[greet])
+
+options = ClaudeAgentOptions(
+    mcp_servers={"tools": server},
+    allowed_tools=["mcp__tools__greet"],
+)
+```
+
+## Error Handling
+
+```python
+from claude_agent_sdk import (
+    CLINotFoundError,
+    ProcessError,
+    CLIConnectionError,
+)
+
+try:
+    async for message in query(prompt="Hello"):
+        print(message)
+except CLINotFoundError:
+    print("Install Claude Code: npm install -g @anthropic-ai/claude-code")
+except ProcessError as e:
+    print(f"Process failed: {e.exit_code}")
+```

raysurfer-0.2.2/PKG-INFO

@@ -0,0 +1,130 @@
+Metadata-Version: 2.4
+Name: raysurfer
+Version: 0.2.2
+Summary: Python SDK for RaySurfer - code block caching and retrieval for AI agents with Claude Agent SDK integration
+Project-URL: Homepage, https://raysurfer.com
+Project-URL: Repository, https://github.com/raymondxu/raysurfer-python
+Author: Raymond Xu
+License-Expression: MIT
+Keywords: agents,ai,anthropic,claude,code-blocks,embeddings,retrieval
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.10
+Requires-Dist: claude-agent-sdk>=0.1.0
+Requires-Dist: httpx>=0.25.0
+Requires-Dist: pydantic>=2.0.0
+Provides-Extra: dev
+Requires-Dist: pytest-asyncio>=0.21.0; extra == 'dev'
+Requires-Dist: pytest-httpx>=0.30.0; extra == 'dev'
+Requires-Dist: pytest>=7.0.0; extra == 'dev'
+Requires-Dist: ruff>=0.1.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# RaySurfer Python SDK
+
+Drop-in replacement for Claude Agent SDK with automatic code caching. Same API, 20-30x faster.
+
+## Install
+
+```bash
+pip install raysurfer
+```
+
+## Quick Start
+
+Swap `ClaudeSDKClient` for `RaysurferClient` - everything else stays the same:
+
+```python
+# from claude_agent_sdk import ClaudeSDKClient, ClaudeAgentOptions
+from raysurfer import RaysurferClient, RaysurferAgentOptions
+
+options = RaysurferAgentOptions(
+    raysurfer_api_key="your-api-key",
+    allowed_tools=["Read", "Write", "Bash"],
+    model="claude-sonnet-4-20250514",
+)
+
+# async with ClaudeSDKClient(options) as client:
+async with RaysurferClient(options) as client:
+    await client.query("Generate quarterly sales report")
+    async for msg in client.receive_response():
+        print(msg)
+```
+
+That's it. Your agent now automatically:
+- Pre-fetches relevant cached code before each task
+- Injects proven code snippets into the system prompt
+- Stores successful outputs for future reuse
+
+## How It Works
+
+1. **On `query()`**: Retrieves cached code blocks matching your task
+2. **Downloads to sandbox**: Files ready for the agent to execute
+3. **Injects into prompt**: Agent sees proven code snippets
+4. **After success**: New code is cached for next time
+
+**Measured Results:**
+- Without RaySurfer: 34.2s, 11 iterations, 2 tool calls
+- With RaySurfer: 1.4s, 1 iteration, 0 tool calls
+- **Speedup: 24x faster**
+
+## RaysurferAgentOptions
+
+All `ClaudeAgentOptions` fields are supported, plus:
+
+```python
+RaysurferAgentOptions(
+    # Raysurfer-specific
+    raysurfer_api_key="your-api-key",
+    prefetch_count=5,           # Code files to pre-fetch
+    min_verdict_score=0.3,      # Quality threshold
+
+    # Standard Claude Agent SDK options
+    allowed_tools=["Read", "Write", "Bash"],
+    model="claude-sonnet-4-20250514",
+    system_prompt="You are helpful.",
+    permission_mode="acceptEdits",
+    # ... all other ClaudeAgentOptions
+)
+```
+
+## Low-Level API
+
+For direct code block storage and retrieval:
+
+```python
+from raysurfer import RaySurfer
+
+rs = RaySurfer(api_key="your-api-key")
+
+# Store a code block
+rs.store_code_block(
+    name="fetch_weather",
+    source="def fetch_weather(city): ...",
+    entrypoint="fetch_weather",
+    language="python",
+)
+
+# Retrieve by task
+results = rs.retrieve("get weather data")
+for match in results.code_blocks:
+    print(f"{match.code_block.name}: {match.score}")
+```
+
+## Verdict System
+
+RaySurfer learns which code actually works through thumbs up/down verdicts:
+- A technical error can be thumbs up (correct validation)
+- A successful run can be thumbs down (useless output)
+
+The system learns usefulness, not just whether code runs.
+
+## Examples
+
+See [examples/](./examples) for complete demos.

raysurfer-0.2.2/README.md

@@ -0,0 +1,102 @@
+# RaySurfer Python SDK
+
+Drop-in replacement for Claude Agent SDK with automatic code caching. Same API, 20-30x faster.
+
+## Install
+
+```bash
+pip install raysurfer
+```
+
+## Quick Start
+
+Swap `ClaudeSDKClient` for `RaysurferClient` - everything else stays the same:
+
+```python
+# from claude_agent_sdk import ClaudeSDKClient, ClaudeAgentOptions
+from raysurfer import RaysurferClient, RaysurferAgentOptions
+
+options = RaysurferAgentOptions(
+    raysurfer_api_key="your-api-key",
+    allowed_tools=["Read", "Write", "Bash"],
+    model="claude-sonnet-4-20250514",
+)
+
+# async with ClaudeSDKClient(options) as client:
+async with RaysurferClient(options) as client:
+    await client.query("Generate quarterly sales report")
+    async for msg in client.receive_response():
+        print(msg)
+```
+
+That's it. Your agent now automatically:
+- Pre-fetches relevant cached code before each task
+- Injects proven code snippets into the system prompt
+- Stores successful outputs for future reuse
+
+## How It Works
+
+1. **On `query()`**: Retrieves cached code blocks matching your task
+2. **Downloads to sandbox**: Files ready for the agent to execute
+3. **Injects into prompt**: Agent sees proven code snippets
+4. **After success**: New code is cached for next time
+
+**Measured Results:**
+- Without RaySurfer: 34.2s, 11 iterations, 2 tool calls
+- With RaySurfer: 1.4s, 1 iteration, 0 tool calls
+- **Speedup: 24x faster**
+
+## RaysurferAgentOptions
+
+All `ClaudeAgentOptions` fields are supported, plus:
+
+```python
+RaysurferAgentOptions(
+    # Raysurfer-specific
+    raysurfer_api_key="your-api-key",
+    prefetch_count=5,           # Code files to pre-fetch
+    min_verdict_score=0.3,      # Quality threshold
+
+    # Standard Claude Agent SDK options
+    allowed_tools=["Read", "Write", "Bash"],
+    model="claude-sonnet-4-20250514",
+    system_prompt="You are helpful.",
+    permission_mode="acceptEdits",
+    # ... all other ClaudeAgentOptions
+)
+```
+
+## Low-Level API
+
+For direct code block storage and retrieval:
+
+```python
+from raysurfer import RaySurfer
+
+rs = RaySurfer(api_key="your-api-key")
+
+# Store a code block
+rs.store_code_block(
+    name="fetch_weather",
+    source="def fetch_weather(city): ...",
+    entrypoint="fetch_weather",
+    language="python",
+)
+
+# Retrieve by task
+results = rs.retrieve("get weather data")
+for match in results.code_blocks:
+    print(f"{match.code_block.name}: {match.score}")
+```
+
+## Verdict System
+
+RaySurfer learns which code actually works through thumbs up/down verdicts:
+- A technical error can be thumbs up (correct validation)
+- A successful run can be thumbs down (useless output)
+
+The system learns usefulness, not just whether code runs.
+
+## Examples
+
+See [examples/](./examples) for complete demos.

raysurfer-0.2.2/demo/before_after_comparison.md

@@ -0,0 +1,135 @@
+# RaySurfer: Before & After
+
+## The Problem
+
+Every time an AI agent encounters a common task, it regenerates code from scratch:
+
+```
+User: "Fetch my GitHub profile"
+
+🐌 WITHOUT RAYSURFER:
+├── Agent thinks... (2s)
+├── Claude generates code... (5s)
+├── Agent writes file... (0.5s)
+├── Agent runs code... (1s)
+└── Total: ~8.5 seconds + 1,500 tokens ($0.05)
+```
+
+## The Solution
+
+RaySurfer caches proven code and retrieves it instantly:
+
+```
+User: "Fetch my GitHub profile"
+
+⚡ WITH RAYSURFER:
+├── Semantic search for matching code... (100ms)
+├── Return cached, tested code... (50ms)
+├── Agent runs code... (1s)
+└── Total: ~1.2 seconds + 0 tokens ($0.0001)
+```
+
+---
+
+## Code Comparison
+
+### ❌ Before: Manual Agent Code
+
+```python
+from anthropic import Anthropic
+
+client = Anthropic()
+
+def run_agent(task: str):
+    """Agent regenerates code every single time."""
+    response = client.messages.create(
+        model="claude-sonnet-4-20250514",
+        messages=[{"role": "user", "content": task}],
+        # Agent generates fresh code each time
+        # Even for tasks it's done 100 times before
+    )
+    return response.content[0].text
+
+# Every call = new tokens, new latency, inconsistent output
+result = run_agent("fetch github user octocat")
+```
+
+**Problems:**
+- 3-10 seconds per generation
+- 500-2000 tokens consumed each time
+- Code quality varies run-to-run
+- No learning from past successes
+
+---
+
+### ✅ After: RaySurfer-Powered Agent
+
+```python
+from raysurfer import RaySurfer
+
+rs = RaySurfer()
+
+def run_agent(task: str):
+    """Agent retrieves proven code instantly."""
+    # Check cache first - 50ms
+    result = rs.retrieve_best(task)
+
+    if result.best_match and result.retrieval_confidence > 0.7:
+        # Cache hit! Return proven code instantly
+        return result.best_match.code_block.source
+
+    # Cache miss - generate new code and store it
+    code = generate_with_llm(task)
+    rs.store_code_block(
+        name=task[:50],
+        source=code,
+        entrypoint="main",
+        language="python"
+    )
+    return code
+
+# First call: generates + caches
+# All future calls: instant retrieval
+result = run_agent("fetch github user octocat")
+```
+
+**Benefits:**
+- 50-200ms retrieval (30x faster)
+- Zero tokens for cache hits
+- Consistent, proven code quality
+- Learns which code works via verdicts
+
+---
+
+## Integration: 3 Lines of Code
+
+```python
+# Before
+response = claude.generate(task)
+
+# After
+from raysurfer import RaySurfer
+rs = RaySurfer()
+cached = rs.retrieve_best(task)
+response = cached.best_match.code_block.source if cached.best_match else claude.generate(task)
+```
+
+---
+
+## Real Numbers
+
+| Metric | Without RaySurfer | With RaySurfer | Improvement |
+|--------|-------------------|----------------|-------------|
+| Latency | 5,000ms | 150ms | **33x faster** |
+| Tokens | 1,200 | 0 | **100% saved** |
+| Cost | $0.04 | $0.0001 | **400x cheaper** |
+| Consistency | Variable | Proven | **Reliable** |
+
+---
+
+## Try It Now
+
+```bash
+pip install raysurfer
+python -c "from raysurfer import RaySurfer; print('Ready!')"
+```