Skip to main content

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.

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:
ResponsibilityWhat it does
CatalogList, get, and delete ML model records registered in your workspace
RuntimeLoad by filename, slug, UUID, or catalog entry; run inference (edge or routed cloud)
Playground clientcw.models.playground(slug) for explicit /mlmodels/{uuid}/run calls (prompt, structured tasks, async 202 paths)
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: 
pip install cyberwave[ml]
For edge development, install in editable mode from the repository: 
pip install -e '.[ml]'

​
Catalog API

​
List models

# 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:
FieldDescription
uuidUnique identifier
slugUnified slug — {workspace}/models/{name}
nameHuman-readable name
model_external_idFilename or registry key used to reference the model
deployment"edge", "cloud", or "hybrid"
is_edge_compatibleTrue when the model can run on edge hardware
is_cloud_compatibleTrue when the model runs on cloud GPU workers
sdk_load_idThe id to pass to cw.models.load()

​
Get a single record

# 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

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:
ArgumentWhat loadsNotes
MLModelSchema entryResolved automaticallySDK picks sdk_load_id → slug → uuid
Local weight filenameEdge LoadedModel (YOLO / Ultralytics)e.g. "yolo26n.pt"
Catalog slugCloud CloudLoadedModele.g. "acme/models/my-model"
UUIDCloud CloudLoadedModelfallback
List of entriesCascadeModelruns 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: 
# 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(): 
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

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 PredictionResult with a unified pred.output (ModelOutput — detection, classification, pose, instance segmentation, OBB, embeddings, …). Convenience properties include pred.classification, pred.pose, pred.instance_segmentation, pred.obb_result, and pred.embedding.
FieldRole
pred.outputTyped primary result (DetectionResult, ClassificationPrediction, PoseResult, …)
pred.rawUnprocessed runtime payload when you need internals

​
Catalog-to-runtime workflow

Discover a model in the catalog, then load it by passing the entry directly: 
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: 
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, AI agents can query the model catalog with:
ToolDescription
cw_list_modelsList catalog records · optional workspace_uuid (client narrows + keeps public) · optional deployment: cloud / edge / hybrid
cw_get_modelGet full details for a single model record
cw_delete_modelDelete a model catalog record (preview then execute)

Python SDK

Full Python SDK reference

MCP Server

Let AI agents query the model catalog

ML Models (UI)

Manage models from the Cyberwave dashboard

Edge Workers

Run models on edge hardware