# BotManifold SDK

Official Python SDK for [BotManifold](https://botmanifold.com) - Robot Policy Verification & Competition Platform.

## Installation

```bash
pip install botmanifold
```

## Quick Start

```python
from botmanifold import BotManifoldClient

client = BotManifoldClient(api_key="bm_live_...")

# Verify a policy (primary use case)
report = client.verify.run("my_policy.zip", scenario="messy_room")
print(f"Verdict: {report.verdict}")  # SAFE, UNSAFE, or ERROR
print(f"Score: {report.score}")

# Submit to arena (competition)
submission = client.arena.submit("my_policy.zip", scenario="messy_room")
print(f"Submission ID: {submission.id}")
```

## CLI Usage

```bash
# Verify a policy (primary command)
botmanifold verify my_policy.zip --scenario messy_room

# Submit to arena
botmanifold arena submit my_policy.zip --scenario messy_room

# Check submission status
botmanifold arena status <submission_id>

# View leaderboard
botmanifold arena leaderboard --scenario messy_room
```

## API Reference

### BotManifoldClient

The main entry point for the SDK.

```python
client = BotManifoldClient(
    api_key="...",      # Or set BOTMANIFOLD_API_KEY env var
    base_url="...",     # Optional, defaults to production
    timeout=30,         # Request timeout in seconds
)
```

### Verify API (Primary)

```python
# Quick verification (waits for result)
report = client.verify.run(
    policy="policy.zip",
    scenario="messy_room",
    num_episodes=5,
    timeout=300,
)

# Check if safe
if report.is_safe:
    print("Policy is safe!")

# Async verification (non-blocking)
job = client.verify.submit(policy, config)
report = client.verify.wait(job.job_id)
```

### Arena API (Competition)

```python
# Submit to competition
submission = client.arena.submit(policy, scenario)

# Check status
status = client.arena.status(submission.id)

# Wait for completion
result = client.arena.wait(submission.id)

# View leaderboard
entries = client.arena.leaderboard(scenario="messy_room", limit=10)
```

## Environment Variables

| Variable | Description |
|----------|-------------|
| `BOTMANIFOLD_API_KEY` | API key for authentication |
| `BOTMANIFOLD_API_URL` | Custom API base URL |
| `BOTARENA_API_KEY` | Legacy API key (deprecated) |

## Migration from botarena

The `botarena` package is deprecated. Update your imports:

```python
# Old (deprecated)
from botarena import Client
client = Client()
submission = client.submit("policy.zip", scenario="messy_room")

# New (recommended)
from botmanifold import BotManifoldClient
client = BotManifoldClient()
report = client.verify.run("policy.zip", scenario="messy_room")  # Primary
submission = client.arena.submit("policy.zip", scenario="messy_room")  # Arena
```

## Development

```bash
# Install development dependencies
pip install -e ".[dev]"

# Run tests
pytest tests/ -v

# Run linting
ruff check botmanifold/
```

## License

Proprietary - see LICENSE file.
