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)

import { RaysurferClient } from "raysurfer";

const client = new RaysurferClient({
  allowedTools: ["Read", "Write", "Bash"],
  systemPrompt: "You are a helpful assistant.",
});

for await (const msg of client.query("Your task here")) {
  console.log(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")

import { RaySurfer } from "raysurfer";

const client = new RaySurfer({ apiKey: "your_api_key" });
const 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]}...")

const result = await client.search({
  task: "Fetch GitHub trending repos",
  topK: 5,
  minVerdictScore: 0.3,
  preferComplete: true,
});

for (const match of result.matches) {
  console.log(`${match.codeBlock.name}: ${match.score}`);
  console.log(`  File: ${match.filename}`);
  console.log(`  Source: ${match.codeBlock.source.slice(0, 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")

const file = { path: "fetch_repos.ts", content: "function fetch() { ... }" };

// Let Raysurfer AI vote (default behavior)
const result = await client.upload({
  task: "Fetch GitHub trending repos",
  fileWritten: file,
  succeeded: true,
  executionLogs: "Fetched 10 trending repos successfully",
});

// Or provide your own vote (AI voting is automatically skipped)
const result2 = await client.upload({
  task: "Fetch GitHub trending repos",
  fileWritten: file,
  succeeded: true,
  userVote: 1, // 1 = thumbs up, -1 = thumbs down
});

console.log(`Stored ${result.codeBlocksStored} 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
    },
)

const files = [
  { path: "app.ts", content: "function main() { ... }" },
  { path: "utils.ts", content: "function helper() { ... }" },
];

const logs = [
  { path: "logs/run.log", content: "Task completed", encoding: "utf-8" },
];

// Let Raysurfer AI grade each file (default behavior)
const result = await client.uploadBulkCodeSnips({
  prompts: ["Build a CLI tool", "Add CSV support"],
  filesWritten: files,
  logFiles: logs,
});

// Or provide your own votes (AI grading is automatically skipped)
const result2 = await client.uploadBulkCodeSnips({
  prompts: ["Build a CLI tool", "Add CSV support"],
  filesWritten: files,
  logFiles: logs,
  userVotes: { "app.ts": 1, "utils.ts": -1 },
});

# 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)")

// Delete by ID
const result = await client.delete("cb_abc123");

// Or delete by name
const result2 = await client.delete("weather_fetcher.py");

console.log(`Deleted ${result.deletedCount} 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,
)

await client.voteCodeSnip({
  task: "Fetch GitHub trending repos",
  codeBlockId: "abc123",
  codeBlockName: "github_fetcher",
  codeBlockDescription: "Fetches trending repos",
  succeeded: true,
});