# mgf-vm-sdk

> **The client SDK for the Magogi Foundation distributed vm-vmanager-app.**
> One `VmManagerClient` interface, two transports: `InProcessTransport`
> (vm-vmanager-app Local) and `GrpcTransport` (vm-vmanager-app Fleet). The single
> library every client — CLI, GUI, third-party tools — imports.

| Field | Value |
|---|---|
| **Status** | Pre-`0.1.0`. Phase 0 of the vm-vmanager-app roadmap. |
| **Federation sibling.** | Depends on `mgf-common>=0.38,<0.39` + `mgf-vm-core>=0.1,<0.2`. |
| **Conformance level.** | **L2 — Standard.** Per-rule ledger: [`docs/inprogress/MGF_STANDARDS_CONFORMANCE.md`](docs/inprogress/MGF_STANDARDS_CONFORMANCE.md). |
| **License.** | MIT. |
| **Python.** | 3.11 / 3.12 / 3.13. |

---

## Where the docs live

> **`vm-vmanager-docs`** — `~/PycharmProjects/vm-vmanager-docs/` ·
> Codeberg: `vm-vmanager-docs`

| What | Where |
|---|---|
| End-to-end architecture | `vm-vmanager-docs/ARCHITECTURE.md` |
| Component inventory + this library's role | `vm-vmanager-docs/COMPONENTS.md` |
| The decision register (D-A4 = one SDK both modes) | `vm-vmanager-docs/DECISIONS.md` |
| The contracts the SDK exposes | `vm-vmanager-docs/component-specs/contracts.md` |
| The gRPC API the GrpcTransport implements (Phase 1) | `vm-vmanager-docs/component-specs/api.md` (TBD) |
| The roadmap (Phase 0 Stream C) | `vm-vmanager-docs/ROADMAP.md` |
| The test strategy | `vm-vmanager-docs/TESTING.md` |
| Dev loop | `vm-vmanager-docs/DEV-LOOP.md` |

---

## What this library contains

(Phase 0 — see `vm-vmanager-docs/ROADMAP.md` Stream C.)

```
src/mgf/vm/sdk/
├── __init__.py            # public re-exports (AP-01)
├── py.typed
├── client.py              # VmManagerClient
├── transports/
│   ├── __init__.py
│   ├── _base.py           # the Transport ABC
│   ├── in_process.py      # InProcessTransport (Phase 0)
│   └── grpc.py            # GrpcTransport ([grpc] extra; Phase 1)
├── handles.py             # OperationHandle, streaming iterators
└── errors.py              # SDK-level rehydration of gRPC error details (D-G3)
```

**Per D-A4: one client, two transports.** Same `VmManagerClient`
class. Construction picks the transport:

```python
# vm-vmanager-app Local — in-process, no daemons
from mgf.vm.sdk import VmManagerClient
from mgf.vm.sdk.transports import InProcessTransport
from mgf.vm.libvirt import LibvirtAdapter

client = VmManagerClient(InProcessTransport.from_adapters(
    hypervisor=LibvirtAdapter("qemu:///system"),
    # ... etc
))
```

```python
# vm-vmanager-app Fleet — remote CP over gRPC (Phase 1)
from mgf.vm.sdk import VmManagerClient
from mgf.vm.sdk.transports import GrpcTransport

client = VmManagerClient(GrpcTransport("grpc://cp.example:443"))
```

CLI and GUI auto-select via `VMANAGER_ENDPOINT` (D-A5).

---

## What this library does NOT contain

- **No engine code** — adapters live in `mgf-vm-libvirt`,
  `mgf-vm-firecracker`.
- **No CP service** — that's `vm-vmanager-control-plane`.
- **No agent daemon** — that's `vm-vmanager-agent`.
- **No CLI / GUI** — those are `vm-vmanager-app`.
- **No `.proto` files in v0** — they land alongside `GrpcTransport`
  in Phase 1; spec at `vm-vmanager-docs/component-specs/api.md`.

Layering enforced by `import-linter` (D-H4).

---

## Install (consumer)

```bash
pip install mgf-vm-sdk            # local mode only (no gRPC deps)
pip install 'mgf-vm-sdk[grpc]'    # + GrpcTransport for fleet mode (Phase 1)
```

## Develop

```bash
cd ~/PycharmProjects/mgf_vm_sdk
uv venv --python 3.12
uv sync --extra dev --extra grpc          # all extras for development
uv run pytest -q                           # unit + contract
uv run mypy --strict src/
uv run ruff check src tests
uv run lint-imports
```

For the full system dev loop, see `vm-vmanager-docs/DEV-LOOP.md`.

---

## Federation context

`mgf-vm-sdk` is a federation sibling. Depends on `mgf-common` and
`mgf-vm-core`. Depended on by `vm-vmanager-app` (CLI + GUI) — both
clients import only the SDK, enforced by `import-linter` (D-H4).

Per federation discipline:
- **`USERS.md`** — who depends on this library
- **`STANDARDS_NOTE.md`** — conformance-level argument
- **`docs/inprogress/MGF_STANDARDS_CONFORMANCE.md`** — per-rule status

## Reporting issues

- **Feedback / design pushback / API friction**: file in this repo's
  `FEEDBACK.md` (or `mgf-vm-core`'s if it's about the contracts
  upstream).
- **Security vulnerabilities**: see `SECURITY.md`.
