raysurfer 0.2.0__tar.gz

raysurfer-0.2.0/.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.0/CLAUDE.md

@@ -0,0 +1,189 @@
+# Raysurfer Python SDK
+
+Python SDK for Raysurfer - code block caching and retrieval for AI agents with Claude Agent SDK integration.
+
+## 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.0/PKG-INFO

@@ -0,0 +1,125 @@
+Metadata-Version: 2.4
+Name: raysurfer
+Version: 0.2.0
+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>=7.0.0; extra == 'dev'
+Requires-Dist: ruff>=0.1.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# RaySurfer Python SDK
+
+Store and retrieve code blocks for AI agents with semantic search and verdict-aware scoring.
+
+## Install
+
+```bash
+pip install raysurfer
+```
+
+## Quick Start
+
+```python
+from raysurfer import RaySurfer
+
+rs = RaySurfer(api_key="your-api-key")
+
+# Store a code block
+result = rs.store_code_block(
+    name="fetch_weather",
+    source="""
+def fetch_weather(city: str) -> dict:
+    import requests
+    resp = requests.get(f"https://api.weather.com/{city}")
+    return resp.json()
+""",
+    entrypoint="fetch_weather",
+    language="python",
+    description="Fetches weather data for a city",
+    tags=["api", "weather"],
+)
+print(f"Stored: {result.code_block_id}")
+
+# Retrieve code blocks by task
+results = rs.retrieve("get weather data for a location")
+for match in results.code_blocks:
+    print(f"{match.code_block.name}: {match.score}")
+
+# Get the single best match with verdict-aware scoring
+best = rs.retrieve_best("fetch current temperature")
+if best.best_match:
+    print(f"Best: {best.best_match.code_block.name}")
+    print(f"Confidence: {best.retrieval_confidence}")
+```
+
+## Async Usage
+
+```python
+from raysurfer import AsyncRaySurfer
+
+async def main():
+    async with AsyncRaySurfer(api_key="your-api-key") as rs:
+        results = await rs.retrieve("parse JSON data")
+        print(results.code_blocks)
+```
+
+## Store Execution Records
+
+Track how code blocks perform to improve future retrieval:
+
+```python
+from raysurfer import RaySurfer, ExecutionState, AgentVerdict
+
+rs = RaySurfer(api_key="your-api-key")
+
+# After running a code block
+rs.store_execution(
+    code_block_id="cb_xxx",
+    triggering_task="get weather for NYC",
+    input_data={"city": "NYC"},
+    output_data={"temp": 72, "conditions": "sunny"},
+    execution_state=ExecutionState.COMPLETED,
+    duration_ms=150,
+    verdict=AgentVerdict.THUMBS_UP,
+)
+```
+
+## API Reference
+
+### `RaySurfer` / `AsyncRaySurfer`
+
+**Store methods:**
+- `store_code_block(...)` - Store a new code block
+- `store_execution(...)` - Store an execution record with optional verdict
+
+**Retrieve methods:**
+- `retrieve(task)` - Semantic search for code blocks
+- `retrieve_best(task)` - Get the single best match with scoring
+- `get_few_shot_examples(task)` - Get examples for code generation
+- `get_task_patterns(...)` - Get proven task→code mappings
+
+## Verdict System
+
+RaySurfer uses thumbs up/down verdicts that are **independent** of execution state:
+- A technical error can be thumbs up (correct validation behavior)
+- A successful execution can be thumbs down (useless output)
+
+This allows the system to learn which code blocks are actually *useful*, not just which ones run without errors.

raysurfer-0.2.0/README.md

@@ -0,0 +1,98 @@
+# RaySurfer Python SDK
+
+Store and retrieve code blocks for AI agents with semantic search and verdict-aware scoring.
+
+## Install
+
+```bash
+pip install raysurfer
+```
+
+## Quick Start
+
+```python
+from raysurfer import RaySurfer
+
+rs = RaySurfer(api_key="your-api-key")
+
+# Store a code block
+result = rs.store_code_block(
+    name="fetch_weather",
+    source="""
+def fetch_weather(city: str) -> dict:
+    import requests
+    resp = requests.get(f"https://api.weather.com/{city}")
+    return resp.json()
+""",
+    entrypoint="fetch_weather",
+    language="python",
+    description="Fetches weather data for a city",
+    tags=["api", "weather"],
+)
+print(f"Stored: {result.code_block_id}")
+
+# Retrieve code blocks by task
+results = rs.retrieve("get weather data for a location")
+for match in results.code_blocks:
+    print(f"{match.code_block.name}: {match.score}")
+
+# Get the single best match with verdict-aware scoring
+best = rs.retrieve_best("fetch current temperature")
+if best.best_match:
+    print(f"Best: {best.best_match.code_block.name}")
+    print(f"Confidence: {best.retrieval_confidence}")
+```
+
+## Async Usage
+
+```python
+from raysurfer import AsyncRaySurfer
+
+async def main():
+    async with AsyncRaySurfer(api_key="your-api-key") as rs:
+        results = await rs.retrieve("parse JSON data")
+        print(results.code_blocks)
+```
+
+## Store Execution Records
+
+Track how code blocks perform to improve future retrieval:
+
+```python
+from raysurfer import RaySurfer, ExecutionState, AgentVerdict
+
+rs = RaySurfer(api_key="your-api-key")
+
+# After running a code block
+rs.store_execution(
+    code_block_id="cb_xxx",
+    triggering_task="get weather for NYC",
+    input_data={"city": "NYC"},
+    output_data={"temp": 72, "conditions": "sunny"},
+    execution_state=ExecutionState.COMPLETED,
+    duration_ms=150,
+    verdict=AgentVerdict.THUMBS_UP,
+)
+```
+
+## API Reference
+
+### `RaySurfer` / `AsyncRaySurfer`
+
+**Store methods:**
+- `store_code_block(...)` - Store a new code block
+- `store_execution(...)` - Store an execution record with optional verdict
+
+**Retrieve methods:**
+- `retrieve(task)` - Semantic search for code blocks
+- `retrieve_best(task)` - Get the single best match with scoring
+- `get_few_shot_examples(task)` - Get examples for code generation
+- `get_task_patterns(...)` - Get proven task→code mappings
+
+## Verdict System
+
+RaySurfer uses thumbs up/down verdicts that are **independent** of execution state:
+- A technical error can be thumbs up (correct validation behavior)
+- A successful execution can be thumbs down (useless output)
+
+This allows the system to learn which code blocks are actually *useful*, not just which ones run without errors.

raysurfer-0.2.0/pyproject.toml

@@ -0,0 +1,54 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "raysurfer"
+version = "0.2.0"
+description = "Python SDK for RaySurfer - code block caching and retrieval for AI agents with Claude Agent SDK integration"
+readme = "README.md"
+license = "MIT"
+requires-python = ">=3.10"
+authors = [
+    { name = "Raymond Xu" }
+]
+keywords = ["ai", "agents", "code-blocks", "retrieval", "embeddings", "claude", "anthropic"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Topic :: Software Development :: Libraries :: Python Modules",
+]
+dependencies = [
+    "httpx>=0.25.0",
+    "pydantic>=2.0.0",
+    "claude-agent-sdk>=0.1.0",
+]
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=7.0.0",
+    "pytest-asyncio>=0.21.0",
+    "ruff>=0.1.0",
+]
+
+[project.urls]
+Homepage = "https://raysurfer.com"
+Repository = "https://github.com/raymondxu/raysurfer-python"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/raysurfer"]
+
+[tool.ruff]
+line-length = 100
+target-version = "py310"
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "W"]
+
+[tool.pytest.ini_options]
+asyncio_mode = "auto"

raysurfer-0.2.0/src/raysurfer/__init__.py

@@ -0,0 +1,51 @@
+"""
+RaySurfer Python SDK
+
+Store and retrieve code blocks for AI agents with semantic search
+and verdict-aware scoring.
+
+Includes Claude Agent SDK integration via RaysurferClient.
+"""
+
+from raysurfer.client import RaySurfer, AsyncRaySurfer
+from raysurfer.sdk_client import RaysurferClient, RaysurferAgentOptions
+from raysurfer.types import (
+    AgentReview,
+    AgentVerdict,
+    BestMatch,
+    CodeBlock,
+    ExecutionIO,
+    ExecutionRecord,
+    ExecutionState,
+    FewShotExample,
+    TaskPattern,
+)
+from raysurfer.sdk_types import CodeFile, GetCodeFilesResponse
+from raysurfer.exceptions import RaySurferError, APIError, AuthenticationError
+
+__version__ = "0.2.0"
+
+__all__ = [
+    # Clients
+    "RaySurfer",
+    "AsyncRaySurfer",
+    # Claude Agent SDK integration
+    "RaysurferClient",
+    "RaysurferAgentOptions",
+    # Types
+    "AgentReview",
+    "AgentVerdict",
+    "BestMatch",
+    "CodeBlock",
+    "CodeFile",
+    "ExecutionIO",
+    "ExecutionRecord",
+    "ExecutionState",
+    "FewShotExample",
+    "GetCodeFilesResponse",
+    "TaskPattern",
+    # Exceptions
+    "RaySurferError",
+    "APIError",
+    "AuthenticationError",
+]