raysurfer 0.4.1__py3-none-any.whl

raysurfer/types.py

@@ -0,0 +1,198 @@
+"""RaySurfer SDK types - mirrors the backend API types"""
+
+from datetime import datetime
+from enum import Enum
+from typing import Any
+
+from pydantic import BaseModel, Field
+
+
+class ExecutionState(str, Enum):
+    """Technical execution outcome - NOT a quality judgment"""
+
+    COMPLETED = "completed"
+    ERRORED = "errored"
+    TIMED_OUT = "timed_out"
+    CANCELLED = "cancelled"
+
+
+class AgentVerdict(str, Enum):
+    """Agent's judgment on whether an execution was useful"""
+
+    THUMBS_UP = "thumbs_up"
+    THUMBS_DOWN = "thumbs_down"
+    PENDING = "pending"
+
+
+class SnipsDesired(str, Enum):
+    """Scope of private snippets for retrieval"""
+
+    COMPANY = "company"  # Organization-level snippets (Team or Enterprise tier)
+    CLIENT = "client"  # Client workspace snippets (Enterprise tier only)
+
+
+class CodeBlock(BaseModel):
+    """A stored code block with metadata for semantic retrieval"""
+
+    id: str
+    name: str
+    description: str
+    source: str
+    entrypoint: str
+    input_schema: dict[str, Any] = Field(default_factory=dict)
+    output_schema: dict[str, Any] = Field(default_factory=dict)
+    language: str
+    language_version: str | None = None
+    dependencies: list[str] = Field(default_factory=list)
+    tags: list[str] = Field(default_factory=list)
+    capabilities: list[str] = Field(default_factory=list)
+    example_queries: list[str] | None = None
+    created_at: datetime | None = None
+    updated_at: datetime | None = None
+
+
+class ExecutionIO(BaseModel):
+    """Stores the actual input/output data"""
+
+    input_data: dict[str, Any]
+    input_hash: str = ""
+    output_data: Any = None
+    output_hash: str = ""
+    output_type: str = "unknown"
+
+
+class AgentReview(BaseModel):
+    """Agent's assessment of whether an execution was useful"""
+
+    timestamp: datetime = Field(default_factory=datetime.utcnow)
+    verdict: AgentVerdict
+    reasoning: str
+    what_worked: list[str] = Field(default_factory=list)
+    what_didnt_work: list[str] = Field(default_factory=list)
+    output_was_useful: bool
+    output_was_correct: bool
+    output_was_complete: bool
+    error_was_appropriate: bool | None = None
+    would_use_again: bool
+    suggested_improvements: list[str] = Field(default_factory=list)
+    required_workaround: bool = False
+    workaround_description: str | None = None
+
+
+class ExecutionRecord(BaseModel):
+    """Full execution trace"""
+
+    id: str
+    code_block_id: str
+    timestamp: datetime = Field(default_factory=datetime.utcnow)
+    execution_state: ExecutionState
+    duration_ms: int
+    error_message: str | None = None
+    error_type: str | None = None
+    io: ExecutionIO
+    triggering_task: str
+    retrieval_score: float = 0.0
+    verdict: AgentVerdict = AgentVerdict.PENDING
+    review: AgentReview | None = None
+
+
+class BestMatch(BaseModel):
+    """The best matching code block with full scoring"""
+
+    code_block: CodeBlock
+    combined_score: float
+    vector_score: float
+    verdict_score: float
+    error_resilience: float
+    thumbs_up: int
+    thumbs_down: int
+
+
+class AlternativeCandidate(BaseModel):
+    """An alternative candidate code block"""
+
+    code_block_id: str
+    name: str
+    combined_score: float
+    reason: str
+
+
+class FewShotExample(BaseModel):
+    """A few-shot example for code generation"""
+
+    task: str
+    input_sample: dict[str, Any]
+    output_sample: Any
+    code_snippet: str
+
+
+class TaskPattern(BaseModel):
+    """A proven task→code mapping"""
+
+    task_pattern: str
+    code_block_id: str
+    code_block_name: str
+    thumbs_up: int
+    thumbs_down: int
+    verdict_score: float
+    error_resilience: float
+    last_thumbs_up: datetime | None = None
+    last_thumbs_down: datetime | None = None
+
+
+# Response types
+class StoreCodeBlockResponse(BaseModel):
+    success: bool
+    code_block_id: str
+    embedding_id: str
+    message: str
+
+
+class StoreExecutionResponse(BaseModel):
+    success: bool
+    execution_id: str
+    pattern_updated: bool
+    message: str
+
+
+class RetrieveCodeBlockResponse(BaseModel):
+    code_blocks: list["CodeBlockMatch"]
+    total_found: int
+
+
+class CodeBlockMatch(BaseModel):
+    code_block: CodeBlock
+    score: float
+    verdict_score: float
+    thumbs_up: int
+    thumbs_down: int
+    recent_executions: list[ExecutionRecord] = Field(default_factory=list)
+
+
+class RetrieveBestResponse(BaseModel):
+    best_match: BestMatch | None
+    alternative_candidates: list[AlternativeCandidate]
+    retrieval_confidence: str
+
+
+class FileWritten(BaseModel):
+    """A file written during agent execution"""
+
+    path: str
+    content: str
+
+
+class SubmitExecutionResultRequest(BaseModel):
+    """Raw execution result - backend handles all processing"""
+
+    task: str
+    files_written: list[FileWritten]
+    succeeded: bool
+
+
+class SubmitExecutionResultResponse(BaseModel):
+    """Response from submitting execution result"""
+
+    success: bool
+    code_blocks_stored: int
+    message: str

raysurfer-0.4.1.dist-info/METADATA

@@ -0,0 +1,157 @@
+Metadata-Version: 2.4
+Name: raysurfer
+Version: 0.4.1
+Summary: Drop-in replacement for Claude Agent SDK with automatic code caching - just swap your import
+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
+)
+```
+
+## Snippet Retrieval Scope
+
+Control which snippets are retrieved using `public_snips` and `snips_desired`:
+
+```python
+from raysurfer import RaysurferClient
+
+# Include both public and company snippets
+client = RaysurferClient(
+    options=options,
+    public_snips=True,       # Include public/shared snippets
+    snips_desired="company", # Also include company-level snippets (Team/Enterprise)
+)
+
+# Enterprise: Retrieve client-specific snippets only
+client = RaysurferClient(
+    options=options,
+    snips_desired="client",  # Client workspace snippets (Enterprise only)
+)
+```
+
+| Configuration | Required Tier |
+|--------------|---------------|
+| `public_snips=True` only | FREE (default) |
+| `snips_desired="company"` | TEAM or ENTERPRISE |
+| `snips_desired="client"` | ENTERPRISE only |
+
+## 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.4.1.dist-info/RECORD

@@ -0,0 +1,9 @@
+raysurfer/__init__.py,sha256=T3RhatqdJg_bSOjBaS_TCcNfGeo0iTvqZAHGs3NeHxg,2355
+raysurfer/client.py,sha256=i4K5YcSPiBv1pU65EE4vopE2DsvNWNb7-ao7QcM8B5o,27338
+raysurfer/exceptions.py,sha256=3HIkH4OPMRWyceHxegeiL0mVXAIRgE55DT2YrkWVEwU,425
+raysurfer/sdk_client.py,sha256=JNbqsLTKgy-J4Z6iCo1jfo-gYdkTq5f20sgoIDjondA,22207
+raysurfer/sdk_types.py,sha256=obp1oF4_MlFsylpIdOICHChNeK3OgqQvr2aPkjr8FoI,775
+raysurfer/types.py,sha256=BnA5lZu9mW9XaOLPW4f4PmYazpUQX9-joIGOeMWcmAQ,4910
+raysurfer-0.4.1.dist-info/METADATA,sha256=8-XDU9sLK0oJB-qWKExnOIMoTCDc-TAlr3Iu-tLPHj8,4694
+raysurfer-0.4.1.dist-info/WHEEL,sha256=WLgqFyCfm_KASv4WHyYy0P3pM_m7J5L9k2skdKLirC8,87
+raysurfer-0.4.1.dist-info/RECORD,,

raysurfer-0.4.1.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.28.0
+Root-Is-Purelib: true
+Tag: py3-none-any