API Reference

from raysurfer import RaysurferClient
from claude_agent_sdk import ClaudeAgentOptions

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

async with RaysurferClient(options) as client:
    await client.query("Your task here")
    async for msg in client.response():
        print(msg)

from raysurfer import RaySurfer, AsyncRaySurfer

# Sync client
client = RaySurfer(api_key="your_api_key")

# Async client
async with AsyncRaySurfer(api_key="your_api_key") as client:
    result = await client.search(task="Fetch GitHub repos")

result = client.search(
    task="Fetch GitHub trending repos",
    top_k=5,
    min_verdict_score=0.3,
    prefer_complete=True,
)

for match in result.matches:
    print(f"{match.code_block.name}: {match.score}")
    print(f"  File: {match.filename}")
    print(f"  Source: {match.code_block.source[:80]}...")

from raysurfer.types import FileWritten

file = FileWritten(path="fetch_repos.py", content="def fetch(): ...")

# Let Raysurfer AI vote (default behavior)
result = client.upload(
    task="Fetch GitHub trending repos",
    file_written=file,
    succeeded=True,
    execution_logs="Fetched 10 trending repos successfully",
)

# Or provide your own vote (AI voting is automatically skipped)
result = client.upload(
    task="Fetch GitHub trending repos",
    file_written=file,
    succeeded=True,
    user_vote=1,  # 1 = thumbs up, -1 = thumbs down
)

print(f"Stored {result.code_blocks_stored} code blocks")

from raysurfer.types import FileWritten, LogFile

files = [
    FileWritten(path="app.py", content="def main(): ..."),
    FileWritten(path="utils.py", content="def helper(): ..."),
]

logs = [
    LogFile(path="logs/run.log", content="Task completed", encoding="utf-8"),
]

# Let Raysurfer AI grade each file (default behavior)
result = client.upload_bulk_code_snips(
    prompts=["Build a CLI tool", "Add CSV support"],
    files_written=files,
    log_files=logs,
)

# Or provide your own votes (AI grading is automatically skipped)
result = client.upload_bulk_code_snips(
    prompts=["Build a CLI tool", "Add CSV support"],
    files_written=files,
    log_files=logs,
    user_votes={
        "app.py": 1,     # thumbs up
        "utils.py": -1,  # thumbs down
    },
)

# Delete by ID
result = client.delete(snippet_id="cb_abc123")

# Or delete by name
result = client.delete(snippet_id="weather_fetcher.py")

print(f"Deleted {result.deleted_count} snippet(s)")

client.vote_code_snip(
    task="Fetch GitHub trending repos",
    code_block_id="abc123",
    code_block_name="github_fetcher",
    code_block_description="Fetches trending repos",
    succeeded=True,
)