# FireVM Python SDK

Official Python client for executing code in isolated Firecracker VMs.

## Installation

```bash
pip install firevm-sdk
```

Or install from source:

```bash
cd sdk/python
pip install -e .
```

## Quick Start

```python
from firevm_sdk import FireVMClient

# Initialize client with your API key
client = FireVMClient(api_key="your_api_key_here")

# Create a VM
vm = client.create_vm(name="my-vm")
print(f"VM created: {vm.vm_id}")

# Execute Python code
result = client.execute_python(vm.vm_id, """
print("Hello from FireVM!")
print(f"2 + 2 = {2 + 2}")
""")

print(result.stdout)  # Hello from FireVM!\n2 + 2 = 4
print(result.exit_code)  # 0
```

## Examples

### Execute Python Code

```python
result = client.execute_python(vm.vm_id, "print('Hello World')")
print(result.stdout)  # Hello World
```

### Execute Bash Commands

```python
result = client.execute_bash(vm.vm_id, "ls -la && whoami")
print(result.stdout)
```

### Handle Errors

```python
result = client.execute_python(vm.vm_id, "1/0")
if result.exit_code != 0:
    print(f"Error: {result.stderr}")
```

### Multiple Languages

```python
# Python
client.execute(vm.vm_id, "print('Python!')", language="python")

# Bash
client.execute(vm.vm_id, "echo 'Bash!'", language="bash")

# Node.js
client.execute(vm.vm_id, "console.log('JavaScript!')", language="nodejs")
```

## Error Handling

### VM Quota Exceeded

When you reach your VM limit, the SDK raises a `VMQuotaExceeded` exception:

```python
from firevm_sdk import FireVMClient, VMQuotaExceeded

client = FireVMClient(api_key="your_key")

try:
    vm = client.create_vm("my-vm")
except VMQuotaExceeded as e:
    print(f"❌ {e.message}")
    print(f"   Current VMs: {e.current_vms}/{e.max_vms}")
    print(f"   Your tier: {e.tier}")
    print(f"   Suggested: Stop unused VMs or upgrade your tier")
```

### Tier Limits

- **Free tier**: 5 concurrent VMs, auto-stop after 10min idle
- **Paid tier**: 10 concurrent VMs, auto-stop after 10min idle
- **Pro tier**: 20 concurrent VMs, auto-stop after 10min idle
- **Enterprise**: 999 concurrent VMs, auto-stop after 10min idle

Upgrade at: https://firevm-frontend-345160625255.asia-northeast1.run.app/pricing

## API Reference

### FireVMClient

```python
FireVMClient(api_key: str, base_url: str = "https://firevm-backend-345160625255.asia-northeast1.run.app")
```

Initialize the FireVM client.

### create_vm()

```python
create_vm(name: str, tier: str = "small", wait: bool = True) -> VM
```

Create a new VM instance.

**Parameters:**
- `name`: VM name
- `tier`: VM size (`"small"`, `"medium"`, `"large"`)
- `wait`: Wait for VM to be ready (default: True)

### execute()

```python
execute(vm_id: str, code: str, language: str = "python", timeout: int = 30, wait: bool = True) -> ExecutionResult
```

Execute code in a VM.

**Parameters:**
- `vm_id`: VM identifier
- `code`: Code to execute
- `language`: `"python"`, `"bash"`, or `"nodejs"`
- `timeout`: Execution timeout in seconds
- `wait`: Wait for execution to complete

**Returns:** `ExecutionResult` with:
- `stdout`: Standard output
- `stderr`: Standard error
- `exit_code`: Exit code (0 = success)
- `execution_time`: Time taken in seconds
- `error`: Error message if any

## Get Your API Key

1. Visit [https://firevm-frontend-345160625255.asia-northeast1.run.app](https://firevm-frontend-345160625255.asia-northeast1.run.app)
2. Sign up for an account
3. Copy your API key from the dashboard

## Support

- Documentation: [https://docs.firevm.dev](https://docs.firevm.dev)
- Issues: [https://github.com/firevm/firevm-python-sdk/issues](https://github.com/firevm/firevm-python-sdk/issues)
- Email: support@firevm.dev

## License

MIT License - see LICENSE file for details.
