Usage Guide

Two Layers of API

• High-level models in package:kumiho/models.dart mirror the Python SDK and offer a fluent interface for creating spaces, items, revisions, artifacts, and bundles.

• gRPC wrapper mixins on KumihoClient (ProjectApi, SpaceApi, etc.) expose the raw request/response objects generated from kumiho.proto.

Most applications start with the high-level models for readability and only drop down to the gRPC layer for specialized workflows.

Krefs

Every object in Kumiho is addressable by a URI-style kref (for example kref:///project/space/item). API calls accept either human-readable paths or krefs, and responses include a kref you can store to revisit the object later or to attach relationships.

Working with Projects

Projects are the root namespace for everything in Kumiho.

final client = KumihoClient(host: 'localhost', port: 50051);
final project = await client.createProject('film-2025', description: 'VFX assets');

// Update settings or deprecate the project
await project.update(description: 'Updated description');
await project.setPublic(true);
await project.delete();

// List projects using the low-level API
final projects = await client.getProjects();

Spaces: Organizing Assets

Spaces form a hierarchical folder structure inside a project. You can nest spaces and attach metadata to them.

final assets = await project.createSpace('assets');
final characters = await project.createSpace('characters', parentPath: '/film-2025/assets');

final heroes = await project.getSpace('assets/characters');
final children = await heroes.getChildSpaces(recursive: true);

await client.updateSpaceMetadata(heroes.kref, {'status': 'active', 'owner': 'asset-team'});

Items and Revisions

Items represent versioned assets such as models, textures, or workflows. Each item holds one or more revisions.

final item = await project.createItem('hero', 'model', parentPath: '/film-2025/assets/characters');
final revision = await item.createRevision();

// Add artifacts that point to storage locations you control
await revision.createArtifact('mesh', '/mnt/assets/hero.fbx');
await revision.createArtifact('textures', 's3://bucket/hero/textures.tar');

// Link revisions with edges to express dependencies
final rig = await project.createItem('hero-rig', 'rig');
final rigRevision = await rig.createRevision();
await revision.addEdge(rigRevision, EdgeType.dependsOn);

Bundles

Bundles aggregate other items or revisions to represent releases or delivery packages.

final bundle = await project.createBundle('release-v1', metadata: {'channel': 'beta'});
await bundle.addMember(item.kref);
await bundle.addMember(rigRevision.kref);

Events and Tenants

Subscribe to event streams to monitor changes, or query tenant metadata when running inside a multi-tenant deployment.

final stream = client.subscribeEvents();
await for (final event in stream) {
  print('Event: ${event.kind} on ${event.kref}');
}

final tenantInfo = await client.getTenant();
print('Tenant: ${tenantInfo.name}');