Metadata-Version: 2.4
Name: sandflare-autogen
Version: 0.1.5
Summary: AutoGen code executor for Sandflare Firecracker microVM sandboxes — run agent-generated code safely
Project-URL: Homepage, https://sandflare.io
Project-URL: Documentation, https://docs.sandflare.io
Project-URL: Repository, https://github.com/sandflare/sandflare
License: MIT
Keywords: agent,autogen,code-interpreter,firecracker,llm,sandbox,sandflare
Requires-Python: >=3.9
Requires-Dist: ag2>=0.5.0
Requires-Dist: sandflare>=0.1.0
Description-Content-Type: text/markdown

# sandflare-autogen

AutoGen `CodeExecutor` that runs agent-generated code in isolated [Sandflare](https://sandflare.io) Firecracker microVM sandboxes.

## Installation

```bash
pip install sandflare-autogen
```

## Usage

### Basic — `SandflareCodeExecutor`

Each `execute_code_blocks()` call runs in the same sandbox. The sandbox is destroyed when `stop()` is called or the context manager exits.

```python
from sandflare_autogen import SandflareCodeExecutor
from autogen.coding import CodeBlock

with SandflareCodeExecutor(api_key="pa_live_...") as executor:
    result = executor.execute_code_blocks([
        CodeBlock(code="print('hello from Firecracker!')", language="python")
    ])
    print(result.output)
    # hello from Firecracker!
```

Set `SANDFLARE_API_KEY` in your environment to omit the `api_key` argument.

### Persistent State — `SandflarePersistentExecutor`

Variables, imports, and installed packages are preserved between calls via a persistent Jupyter kernel.

```python
from sandflare_autogen import SandflarePersistentExecutor
from autogen.coding import CodeBlock

with SandflarePersistentExecutor() as executor:
    executor.execute_code_blocks([
        CodeBlock(code="import numpy as np\nx = np.array([1, 2, 3])", language="python")
    ])
    result = executor.execute_code_blocks([
        CodeBlock(code="print(x.mean())", language="python")
    ])
    print(result.output)  # 2.0
```

### ConversableAgent Example

```python
from sandflare_autogen import SandflareCodeExecutor
from autogen import ConversableAgent

with SandflareCodeExecutor(api_key="pa_live_...") as executor:
    agent = ConversableAgent(
        name="coder",
        llm_config={"model": "gpt-4o", "api_key": "sk-..."},
        code_execution_config={"executor": executor},
    )
    user = ConversableAgent(
        name="user",
        human_input_mode="NEVER",
        is_termination_msg=lambda x: x.get("content", "").rstrip().endswith("TERMINATE"),
    )
    user.initiate_chat(
        agent,
        message="Write Python code to find the 50th prime number. Reply TERMINATE when done.",
    )
```

## Constructor Options

| Parameter     | Type   | Default   | Description                                              |
|---------------|--------|-----------|----------------------------------------------------------|
| `api_key`     | `str`  | env var   | Sandflare API key (`SANDFLARE_API_KEY`)                  |
| `template_id` | `str`  | `""`      | Sandbox template ID (empty = base Ubuntu + Python 3)     |
| `size`        | `str`  | `"small"` | VM size: `nano`, `small`, `medium`, `large`, `xl`        |
| `timeout`     | `int`  | `60`      | Per-execution timeout in seconds                         |
| `persistent`  | `bool` | `False`   | Preserve sandbox state across `restart()` calls          |
| `base_url`    | `str`  | `None`    | Override API base URL (self-hosted deployments)          |
| `env`         | `dict` | `{}`      | Environment variables injected into the sandbox          |

## Docs

- [https://docs.sandflare.io](https://docs.sandflare.io)
- [https://sandflare.io](https://sandflare.io)
