> ## Documentation Index > Fetch the complete documentation index at: https://docs.cyberwave.com/llms.txt > Use this file to discover all available pages before exploring further. # ML Models > Browse the model catalog, load models at runtime, and run inference — all from a single cw.models entry point

Cyberwave is in Private Beta.

Request early access to get access to the Cyberwave dashboard.

## Overview `cw.models` is the unified surface for ML model management in the Cyberwave Python SDK. It combines responsibilities behind one namespace: | Responsibility | What it does | | --------------------- | ------------------------------------------------------------------------------------------------------------------ | | **Catalog** | List, get, and delete ML model records registered in your workspace | | **Runtime** | Load by filename, slug, UUID, or catalog entry; run inference (edge or routed cloud) | | **Playground client** | `cw.models.playground(slug)` for explicit `/mlmodels/{uuid}/run` calls (prompt, structured tasks, async 202 paths) | ```python theme={null} from cyberwave import Cyberwave cw = Cyberwave() # --- Catalog: discover what models exist (optional client-side filters) --- for m in cw.models.list(filters=["edge", "image"]): print(m.slug, m.deployment, m.sdk_load_id) # --- Runtime: load directly from a catalog entry --- entry = cw.models.list(deployment="edge")[0] model = cw.models.load(entry) # resolves sdk_load_id → slug → uuid pred = model.predict(image, confidence=0.25) # Structured summary covers detection, classification, pose, segmentation, OBB, etc. print(pred.describe()) ``` *** ## Installation The ML inference extras require the `[ml]` optional dependency group: ```bash theme={null} pip install cyberwave[ml] ``` For edge development, install in editable mode from the repository: ```bash theme={null} pip install -e '.[ml]' ``` *** ## Catalog API ### List models ```python theme={null} # All models visible in your workspace models = cw.models.list() # Filter by deployment target (server-side query param) edge_models = cw.models.list(deployment="edge") cloud_models = cw.models.list(deployment="cloud") # Extra client-side shorthands (ANDed): edge + image-capable catalog rows edge_vision = cw.models.list(filters=["edge", "image"]) # Unknown filter strings → tag substring match (case-insensitive) # Public models (no workspace membership required) public_models = cw.models.list_public() ``` `cw.models.create()` and `cw.models.update()` are not implemented yet — use `POST` / `PUT` on `/api/v1/mlmodels`, or generated `cw.api.*` helpers, until typed wrappers ship. Each record exposes: | Field | Description | | --------------------- | ---------------------------------------------------- | | `uuid` | Unique identifier | | `slug` | Unified slug — `{workspace}/models/{name}` | | `name` | Human-readable name | | `model_external_id` | Filename or registry key used to reference the model | | `deployment` | `"edge"`, `"cloud"`, or `"hybrid"` | | `is_edge_compatible` | `True` when the model can run on edge hardware | | `is_cloud_compatible` | `True` when the model runs on cloud GPU workers | | `sdk_load_id` | The id to pass to `cw.models.load()` | ### Get a single record ```python theme={null} # By slug m = cw.models.get("acme/models/yolov8-nano") # By UUID m = cw.models.get_by_uuid("3f2a1b4c-…") # By slug (explicit) m = cw.models.get_by_slug("acme/models/yolov8-nano") ``` ### Delete a model ```python theme={null} result = cw.models.delete("model-uuid-here") ``` Deletion removes the catalog record. Local weight files on your device are unaffected. *** ## Runtime API ### Load a model `cw.models.load()` accepts a catalog entry **or** a string: | Argument | What loads | Notes | | --------------------- | --------------------------------------- | --------------------------------------------- | | `MLModelSchema` entry | Resolved automatically | SDK picks `sdk_load_id` → `slug` → `uuid` | | Local weight filename | Edge `LoadedModel` (YOLO / Ultralytics) | e.g. `"yolo26n.pt"` | | Catalog slug | Cloud `CloudLoadedModel` | e.g. `"acme/models/my-model"` | | UUID | Cloud `CloudLoadedModel` | fallback | | List of entries | `CascadeModel` | runs every model on the same input; see below | Passing a catalog entry directly is the preferred pattern — no need to inspect which field to use: ```python theme={null} # Preferred: pass the entry from list() or get() directly entry = cw.models.list(deployment="edge")[0] model = cw.models.load(entry) # SDK resolves sdk_load_id automatically # Also accepted: explicit string IDs model = cw.models.load("yolo26n.pt") # edge — local filename model = cw.models.load("acme/models/my-yolo") # cloud — slug # Cascade: independent predictions keyed by catalog name edges = cw.models.list(filters=["edge", "image"]) cascade = cw.models.load([edges[0], edges[1]], store_input=True) multi = cascade.predict(image) ``` Both return an object with the same `.predict()` interface (unless a list was passed). ### Cloud playground (`cw.models.playground`) For full control over the playground HTTP payload (conversation history, `structured_task`, async workloads), bind a slug and call `run()`: ```python theme={null} handle = cw.models.playground("acme/models/gemini-robotics-er") sync_or_queued = handle.run( image="scene.jpg", prompt="cups", structured_task="detect_points", ) ``` This returns typed REST schemas (`MLModelRunResultSchema` or `MLModelRunQueuedSchema`), not `PredictionResult`. ### Run inference ```python theme={null} from PIL import Image img = Image.open("frame.jpg").convert("RGB") pred = model.predict(img, confidence=0.25) # Summary for whichever output type the runtime produced print(pred.describe()) # Bounding-box-only shorthand (delegates to detection output); prefer describe() print(pred.describe_detections_text()) # Iterate bbox detections when output is DetectionResult-shaped for d in pred: print(d.label, d.confidence, d.bbox) ``` `predict()` returns a concrete **`PredictionResult` subclass** — e.g. **`DetectionResult`**, **`ClassificationResult`**, **`TextResult`**, **`PoseResult`**, **`InstanceSegmentationResult`**, **`OBBResult`**, **`EmbeddingResult`**. Use type-specific fields (`.detections`, `.top`, `.text`, …) rather than a wrapper. | Field | Role | | ---------- | ------------------------------------------------------------------------------------- | | `pred` | Concrete result subclass (`DetectionResult`, `ClassificationResult`, `TextResult`, …) | | `pred.raw` | Unprocessed runtime payload when you need internals | *** ## Catalog-to-runtime workflow Discover a model in the catalog, then load it by passing the entry directly: ```python theme={null} cw = Cyberwave() # 1. Find an edge-compatible model models = cw.models.list(deployment="edge") entry = models[0] print(f"Loading '{entry.name}' sdk_load_id={entry.sdk_load_id}") # 2. Load by passing the entry — SDK resolves sdk_load_id automatically model = cw.models.load(entry) pred = model.predict(image, confidence=0.3) print(pred.describe()) ``` The same pattern works for cloud models — the entry's `slug` is used instead: ```python theme={null} cloud_entry = cw.models.list(deployment="cloud")[0] model = cw.models.load(cloud_entry) # routes via slug to playground-backed inference where applicable pred = model.predict(image) print(pred.describe()) ``` *** ## MCP tools When using the [Cyberwave MCP Server](/tools/mcp-server), AI agents can query the model catalog with: | Tool | Description | | ----------------- | --------------------------------------------------------------------------------------------------------------------------------------- | | `cw_list_models` | List catalog records · optional `workspace_uuid` (client narrows + keeps `public`) · optional `deployment`: `cloud` / `edge` / `hybrid` | | `cw_get_model` | Get full details for a single model record | | `cw_delete_model` | Delete a model catalog record (preview then execute) | *** ## Related resources Full Python SDK reference Let AI agents query the model catalog Manage models from the Cyberwave dashboard Run models on edge hardware