Core Concepts

This guide explains the core concepts of Kumiho Cloud and how they relate to the Dart SDK.

Graph-Native Architecture

Kumiho Cloud is built on a graph database (Neo4j), which means relationships between assets are first-class citizens. Unlike traditional file-based systems, Kumiho tracks:

• Dependencies: What assets does this asset depend on?

• Lineage: What was this asset created from?

• Usage: Where is this asset used?

┌───────────────────────────────────────────────────────┐
│                         PROJECT                       │
│  ┌─────────────────────────────────────────────────┐  │
│  │                        SPACE                    │  │
│  │  ┌─────────┐      ┌─────────┐     ┌─────────┐   │  │
│  │  │  ITEM   │────▶│  ITEM   │────▶│  ITEM   │   │  │
│  │  └────┬────┘      └────┬────┘     └────┬────┘   │  │
│  │       │                │               │        │  │
│  │  ┌────▼────┐      ┌────▼────┐     ┌────▼────┐   │  │
│  │  │REVISION │      │REVISION │     │REVISION │   │  │
│  │  │   v1    │      │   v1    │     │   v1    │   │  │
│  │  └────┬────┘      └────┬────┘     └────┬────┘   │  │
│  │       │                │               │        │  │
│  │  ┌────▼────┐      ┌────▼────┐     ┌────▼────┐   │  │
│  │  │ARTIFACT │      │ARTIFACT │     │ARTIFACT │   │  │
│  │  └─────────┘      └─────────┘     └─────────┘   │  │
│  └─────────────────────────────────────────────────┘  │
└───────────────────────────────────────────────────────┘

Entity Hierarchy

Project

A Project is the top-level container representing a production, show, or workspace. Each project is isolated within a tenant’s graph database.

final project = await client.createProject(
  'sci-fi-short',
  description: 'Sci-fi short film VFX assets',
);

Key attributes:

• name: URL-safe identifier (used in Kref URIs)

• description: Human-readable description

• kref: Reference URI (kref://sci-fi-short)

Space

A Space organizes assets within a project. Common groupings include:

• By type: characters, environments, props

• By episode: ep01, ep02

• By department: modeling, animation, lighting

final space = await client.createSpace('/sci-fi-short', 'characters');

Key attributes:

• name: URL-safe identifier

• path: Full path in the hierarchy (e.g., /sci-fi-short/characters)

• metadata: Custom key-value metadata

Item

An Item represents a single creative asset or AI artifact. Items have a kind that indicates what type of asset they are.

final item = await client.createItem(
  '/sci-fi-short/characters',
  'hero-robot',
  'model',
);

Common item kinds:

• model: 3D models

• texture: Textures and materials

• animation: Animation data

• rig: Character rigs

• composite: Compositing setups

• ai_model: Trained AI models

• dataset: Training datasets

• prompt: AI prompts

Key attributes:

• name: URL-safe identifier

• kind: Category of the asset

• kref: Reference URI (kref://sci-fi-short/characters/hero-robot.model)

Revision

A Revision represents a specific iteration of an item. Revisions are immutable once published.

// Create a revision
final revision = await client.createRevision(item.kref);

// Create a revision with metadata
final revision = await client.createRevision(
  item.kref,
  metadata: {'artist': 'john', 'status': 'wip'},
);

Key attributes:

• revisionNumber: Sequential version number

• metadata: Custom key-value metadata

• tags: Applied tags (e.g., latest, published, approved)

• kref: Reference URI (kref://sci-fi-short/characters/hero-robot.model?r=1)

Artifact

An Artifact is a file reference attached to a revision. Kumiho follows a BYO-storage philosophy — files stay on your storage, only paths are tracked.

await client.createArtifact(
  revision.kref,
  'mesh',
  '/mnt/assets/hero-robot.fbx',
);

await client.createArtifact(
  revision.kref,
  'textures',
  's3://bucket/hero-robot/textures.tar',
);

Key attributes:

• name: Artifact identifier

• location: File path or URI (file://, s3://, smb://, etc.)

• kref: Reference URI

Bundle

A Bundle groups related items or revisions together, useful for releases or delivery packages.

final bundle = await client.createBundle(
  '/sci-fi-short',
  'release-v1',
  metadata: {'channel': 'beta'},
);

await client.addBundleMember(bundle.kref, item.kref);
await client.addBundleMember(bundle.kref, rigRevision.kref);

Kref URIs

Every object in Kumiho is addressable by a URI-style Kref (Kumiho Reference):

Entity	Format	Example
Project	kref://project	kref://sci-fi-short
Space	kref://project/space	kref://sci-fi-short/characters
Item	kref://project/space/item.kind	kref://sci-fi-short/characters/hero.model
Revision	kref://project/space/item.kind?r=N	kref://sci-fi-short/characters/hero.model?r=1
Artifact	kref://project/space/item.kind?r=N&a=name	kref://sci-fi-short/characters/hero.model?r=1&a=mesh

Edges (Relationships)

Edges represent relationships between revisions. The standard edge types, named as constants on EdgeType, are:

Edge Type	Description
BELONGS_TO	Source belongs to / is grouped under the target
CREATED_FROM	Source was generated or created from the target
REFERENCED	Source holds a soft reference to the target
DEPENDS_ON	Source requires the target to function
DERIVED_FROM	Source was derived or modified from the target
PRODUCED_BY	Source was produced by the target FlowRun revision
MIGRATED_FROM	Source was migrated from the target revision or tombstone
CONTAINS	Source contains or includes the target
SUPERSEDES	Source replaces the target (belief revision)
SUPPORTS	Source corroborates the target (evidence chains)

The list is a shared vocabulary, not a closed set. The server accepts any edge type matching ^[A-Z][A-Z0-9_]{0,49}$, so an application-defined type is legal; EdgeType.isValid (and isValidEdgeType / validateEdgeType) apply that rule rather than checking membership in EdgeType.values.

// Create a dependency relationship
await client.createEdge(
  modelRevision.kref,
  textureRevision.kref,
  EdgeType.dependsOn,
);

// Analyze impact of changes
final impact = await client.analyzeImpact(textureRevision.kref);

Search and Discovery

Kumiho offers two complementary ways to find content:

• Full-text fuzzy search (search): typo-tolerant matching across items, returning ranked results with relevance scores.

• Semantic revision scoring (scoreRevisions): ranks a known set of revisions against a query using server-side embeddings.

final results = await client.search('hero robt', minScore: 0.2);
final scored = await client.scoreRevisions('weathered metal', [revA.kref.uri, revB.kref.uri]);

BYO Storage Philosophy

Kumiho does not store your files. Instead, it tracks references (artifacts) to files that remain on your storage:

• Local filesystems: file:///path/to/file.fbx

• Network shares: smb://server/share/file.fbx

• Cloud storage: s3://bucket/path/file.fbx

This approach provides:

• No egress costs: Files never leave your infrastructure

• Flexibility: Use any storage that works for your pipeline

• Control: Keep your data on your own storage solutions

Multi-Tenant Architecture

Kumiho Cloud is a multi-tenant SaaS platform:

• Each organization is a tenant

• Tenants are isolated in separate Neo4j databases

• Regional deployment ensures data locality

• The SDK automatically discovers your tenant’s region

// SDK handles tenant discovery automatically
final client = KumihoClient(host: 'api.kumiho.io', port: 443);
final usage = await client.getTenantUsage();
print('Using ${usage.nodeCount} of ${usage.nodeLimit} nodes');