CactusBrain developer guide

Platform overview

cellm owns model loading, preprocessing, execution, and low-level postprocessing. CactusBrain SDKs expose task-oriented APIs. CactusBrain manages discovery, documentation, projects, entitlements, and model delivery.

Create an account

Create a developer account to access the workspace. Accounts can organize projects and view model or SDK artifacts assigned to their organization. Creating an account does not automatically grant a model entitlement.

Model delivery

Models are delivered securely through the CactusBrain SDK when your application needs them. You assign an approved model package to a project; the SDK handles authorization, encrypted delivery, integrity verification, local storage, and runtime loading. Your users never manage model files, and your app does not bundle large weights in its initial download.

Sign in and open Model delivery in the workspace to see which packages a project is entitled to, which version it resolves to, and whether delivery is succeeding. The public catalog describes available model families, but a catalog entry does not imply an entitlement or a production-ready Vision package.

Installation

CactusBrain Vision is currently in Developer Preview. Package coordinates and supported versions will be published with the first public SDK release.

Model format

Use model packages distributed for cellm. A package must keep weights, tokenizer or preprocessing assets, model metadata, and compatibility information together. Do not substitute an upstream checkpoint unless it has been converted and validated for the target cellm release.

• Model identifier and task
• Required runtime version
• Input and output contract
• Supported platforms and backends
• License and commercial-use terms

CLI

The cellm command-line interface validates compatible model packages and runtime behavior. Versioned command documentation will be published with each public CLI release. CactusBrain Vision applications use the product SDK and do not require the CLI for normal integration.

Runtime

cellm is the inference engine beneath CactusBrain Vision. The Vision SDK coordinates model delivery and local execution without requiring applications to implement model loading, preprocessing, or tensor execution.

• Inference remains inside your application process.
• Inputs are not sent to a CactusBrain inference API.
• Backend and model support must be measured per release.

Quick start

Connect CactusBrain Vision to a project, then create a named collection for the objects your application recognizes. The SDK resolves an entitled model, installs it when needed, verifies compatibility, and runs inference locally through cellm.

Executable setup instructions and package coordinates will be published with the first public SDK release.

Collections

A collection is the persistent matching boundary for related identities. Its identifier becomes the snapshot filename. Identifiers may contain letters, numbers, -, _, and ., and are limited to 128 characters.

Matching policy is supplied by the compatible model package and SDK release. Opening an existing collection validates its model and embedding contract before identification begins.

Enrollment

Enroll one identity with one or more reference images. Images are embedded and normalized independently. Adding an existing identity ID replaces its references and metadata atomically.

try await collection.add(
    id: "coke-500",
    images: referenceImages,
    metadata: ["displayName": "Coke 500 ml"]
)

let count = await collection.identityCount()

Use varied, representative reference images for the same identity. The SDK requires at least one image; production quality requirements depend on the released embedding model.

Identification

Identification embeds the query image, scores each identity by its best reference-image cosine similarity, and returns up to topK ranked identities when the best result satisfies the collection's matching policy.

let result = try await collection.identify(
    image: queryImage,
    topK: 3
)

if result.identified, let match = result.matches.first {
    print(match.id, match.score, match.metadata)
}

The result also reports the best score and end-to-end SDK latency in milliseconds. Equal scores are ordered by identity ID for deterministic results.

Unknown handling

An unknown result is explicit: identified is false and matches is empty. Inspect reason to distinguish no acceptable match from an empty collection.

switch result.reason {
case .noMatch:
  print("No enrolled identity matched")
case .emptyCollection:
    print("Enroll at least one identity before identifying")
case nil:
    break
}

Offline behavior

Model authorization and initial delivery require network access. After an entitled model is installed and verified, collection operations and inference run on-device without a network connection.

Privacy

Reference images, query images, embeddings, and identification results remain inside the application. CactusBrain does not provide a cloud inference endpoint and does not receive inference content.

SDK status

CactusBrain Vision is available as a Developer Preview for evaluating collection, enrollment, identification, persistence, and unknown-handling workflows. Public package coordinates and production support commitments will be published with the first generally available SDK release.

Model compatibility

The workspace lists the model packages currently available to your organization and projects. A model is developer-accessible only when its release channel, platform support, and entitlement are shown there.

Collections record both modelIdentifier and embeddingDimensions. Opening a collection with a different model or vector size fails rather than silently comparing incompatible embeddings.