CodeVF Python SDK

The official Python client for the CodeVF API. This SDK helps you manage projects, submit tasks for human review, and monitor your credits.

Installation

pip install codevf-sdk

Quick Start

1. Authentication

The client looks for the CODEVF_API_KEY environment variable by default.

export CODEVF_API_KEY="cvf_live_..."

Or you can pass it directly:

fromcodevfimportCodeVFClientclient=CodeVFClient(api_key="cvf_live_...")

2. Verify Connection

Check your account balance to verify connectivity:

fromcodevfimportCodeVFClientclient=CodeVFClient()
balance=client.credits.get_balance()
print(f"Available Credits: {balance.available}")

3. Submitting a Task

Here is a complete example of creating a project and submitting a task.

fromcodevfimportCodeVFClient, ServiceModeclient=CodeVFClient()
# 1. Create a project to organize your tasksproject=client.projects.create(
name="API Migration",
description="Tasks related to the v2 migration"# Optional
)
# 2. Submit a task for reviewtask=client.tasks.create(
prompt="Check this code for security vulnerabilities.",
max_credits=240,
project_id=project.id,
mode=ServiceMode.FAST, # Optional: defaults to STANDARD# metadata={"env": "prod"}, # Optional: custom tags# attachments=[...], # Optional: file attachments
)
print(f"Task submitted! ID: {task.id}")
# 3. Check statuscurrent_task=client.tasks.retrieve(task.id)
print(f"Status: {current_task.status}")

Features

• Project Management - Create and organize reusable projects.
• Task Submission - Submit prompts with code files and instructions for human engineers.
• Credit System - Monitor your available budget.
• Engineer Expertise - Choose expertise levels (Tags) to match the task difficulty.
• Attachments - Upload files, logs, or screenshots.
• Error Handling - Typed exceptions for easy debugging and retries.

Architecture

The SDK mirrors the API surface:

• Core - CodeVFClient handles authentication and requests.
• Resources - client.projects, client.tasks, client.credits, etc.
• Models - Typed objects like Project, TaskResponse, CreditBalance.

API Reference

Projects

# Create a new projectproject=client.projects.create(name="My Project")

Tasks

# Submit a taskclient.tasks.create(
prompt="Refactor this function",
max_credits=240,
project_id=123
)
# Check statusclient.tasks.retrieve(task_id="...")
# Cancelclient.tasks.cancel(task_id="...")

Credits

# Check balanceclient.credits.get_balance()

Tags

# List available expertise levelsclient.tags.list()

Task Credits and Modes

• realtime_answer: 60-600 credits, 2x multiplier
• fast: 240-115200 credits, 1.5x multiplier
• standard: 240-115200 credits, 1x multiplier

The SDK validates these ranges client-side.

Attachments

• Max 5 attachments per task
• Images (PNG/JPG/GIF/WebP): up to 10MB, base64-encoded
• PDFs: up to 10MB, base64-encoded
• Source code and text files (PY/JS/JSON/MD/etc.): up to 1MB, raw text

Error Handling

Exceptions are available in codevf.exceptions:

fromcodevf.exceptionsimportAuthenticationError, RateLimitErrortry:
client.credits.get_balance()
exceptAuthenticationError:
print("Check your API key")
exceptRateLimitError:
print("Slow down!")

Development

git clone https://github.com/codevf/codevf-sdk-python.git
cd codevf-sdk-python
# Install dependencies
pip install -e .[dev]
# Run tests
pytest

License

MIT - see the LICENSE file for details.