# Public Contract

This document defines the supported public interface for `pyro-mcp`.

## Package Identity

- Distribution name: `pyro-mcp`
- Public executable: `pyro`
- Public Python import: `from pyro_mcp import Pyro`

## CLI Contract

Top-level commands:

- `pyro mcp serve`
- `pyro run`
- `pyro doctor`
- `pyro demo`
- `pyro demo ollama`

Stable `pyro run` flags:

- `--profile`
- `--vcpu-count`
- `--mem-mib`
- `--timeout-seconds`
- `--ttl-seconds`
- `--network`

Behavioral guarantees:

- `pyro run -- <command>` returns structured JSON.
- `pyro doctor` returns structured JSON diagnostics.
- `pyro demo ollama` prints log lines plus a final summary line.

## Python SDK Contract

Primary facade:

- `Pyro`

Supported public methods:

- `create_server()`
- `list_profiles()`
- `create_vm(...)`
- `start_vm(vm_id)`
- `exec_vm(vm_id, *, command, timeout_seconds=30)`
- `stop_vm(vm_id)`
- `delete_vm(vm_id)`
- `status_vm(vm_id)`
- `network_info_vm(vm_id)`
- `reap_expired()`
- `run_in_vm(...)`

## MCP Contract

Primary tool:

- `vm_run`

Advanced lifecycle tools:

- `vm_list_profiles`
- `vm_create`
- `vm_start`
- `vm_exec`
- `vm_stop`
- `vm_delete`
- `vm_status`
- `vm_network_info`
- `vm_reap_expired`

## Compatibility Rule

Changes to any command name, public flag, public method name, or MCP tool name are breaking changes and should be treated as a deliberate contract version change.