kumiho 0.8.4

Python SDK for Kumiho Cloud - Graph-native creative & AI asset management

Kumiho Python SDK

The official Python SDK for Kumiho Cloud — a graph-native creative and AI asset management platform for VFX, animation, and AI-driven workflows.

Features

• Graph-Native Design: Built on Neo4j for tracking asset relationships and lineage
• Revision Control: Semantic versioning for creative assets with full history
• AI Lineage Tracking: Track AI model training data / GenAI image, video output provenance and dependencies
• BYO Storage: Files stay on your local/NAS/on-prem storage — only metadata is in the cloud
• Multi-Tenant SaaS: Secure, region-aware multi-tenant architecture
• Event Streaming: Real-time notifications for asset changes with tier-based capabilities
• Graph Traversal: Powerful dependency analysis and impact assessment
• Type-Safe: Full type hints for IDE autocomplete and static analysis

Installation

pip install kumiho

For development:

pip install kumiho[dev]

Quick Start

1. Authenticate

Run the built-in CLI to cache your Firebase credentials:

kumiho-auth login

This stores credentials at ~/.kumiho/kumiho_authentication.json and automatically refreshes tokens when needed.

2. Connect and Use

import kumiho

# Auto-configure from cached credentials and discovery
kumiho.auto_configure_from_discovery()

# Create a project
project = kumiho.create_project(
    name="my-vfx-project",
    description="VFX assets for 2025 film"
)

# Create a space (organizational container)
space = project.create_space("characters")

# Create an item (versioned asset)
item = space.create_item(
    item_name="hero",
    kind="model"
)

# Create a revision with metadata
revision = item.create_revision(
    metadata={
        "artist": "jane",
        "software": "maya-2024",
        "notes": "Initial model with base topology"
    }
)

# Attach file artifacts (files stay on your storage)
artifact = revision.create_artifact(
    name="hero_model.fbx",
    location="smb://studio-nas/projects/film/hero_model.fbx"
)

# Tag the revision
revision.tag("approved")

Core Concepts

Entity Hierarchy

Project
  └── Space (organizational container)
        └── Item (versioned asset)
              └── Revision (immutable snapshot)
                    └── Artifact (file reference)

Kref URIs

Kumiho uses URI-based references to address any entity:

kref://project/space/item.kind?r=revision&a=artifact

Examples:

# Reference an item (latest revision)
item = kumiho.get_item("kref://my-project/characters/hero.model")

# Reference a specific revision
revision = kumiho.get_revision("kref://my-project/characters/hero.model?r=3")

# Reference a specific artifact
artifact = kumiho.get_artifact("kref://my-project/characters/hero.model?r=3&a=mesh.fbx")

# Reference by tag
published = kumiho.get_revision("kref://my-project/characters/hero.model?t=published")

Edges (Relationships)

Track dependencies and lineage between revisions:

# Create a dependency edge
texture = kumiho.get_revision("kref://my-project/textures/skin.texture?r=2")
revision.create_edge(
    target_revision=texture,
    edge_type=kumiho.DEPENDS_ON,
    metadata={"usage": "skin material"}
)

# Query edges
outgoing = revision.get_edges(direction=kumiho.OUTGOING)
incoming = revision.get_edges(direction=kumiho.INCOMING)

Graph Traversal

Analyze dependencies and impact:

# Find all dependencies (what this revision uses)
deps = revision.get_all_dependencies(max_depth=5)
for kref in deps.revision_krefs:
    print(f"Depends on: {kref}")

# Find all dependents (what uses this revision)
dependents = revision.get_all_dependents(max_depth=5)

# Impact analysis (what would be affected by changes)
impact = revision.analyze_impact()
for impacted in impact:
    print(f"Would affect: {impacted.revision_kref} at depth {impacted.impact_depth}")

# Find shortest path between revisions
path = source.find_path_to(target)

Bundles

Aggregate items into versioned collections:

# Create a bundle
bundle = project.create_bundle("character-bundle")

# Add items
bundle.add_member(hero_model)
bundle.add_member(hero_rig)
bundle.add_member(hero_textures)

# Get members and history
members = bundle.get_members()
history = bundle.get_history()  # Full audit trail

Event Streaming

React to changes in real-time:

import kumiho

# Stream all events with filtering
for event in kumiho.event_stream(routing_key_filter="revision.*"):
    print(f"{event.action}: {event.kref}")

# Filter by kref pattern (glob syntax)
for event in kumiho.event_stream(kref_filter="kref://my-project/**/*.model"):
    print(f"Model changed: {event.kref}")

Tier-Based Streaming Capabilities

Feature	Free	Creator	Studio	Enterprise
Real-time streaming	✅	✅	✅	✅
Routing key filters	✅	✅	✅	✅
Kref glob filters	✅	✅	✅	✅
Event persistence	❌	1 hour	24 hours	30 days
Cursor-based resume	❌	✅	✅	✅
Consumer groups	❌	❌	❌	✅

Note: Creator tier and above features are Coming Soon. Currently only Free tier is available.

# Check your tier's capabilities
caps = kumiho.get_event_capabilities()
print(f"Tier: {caps.tier}, Replay: {caps.supports_replay}")

# Resumable streaming (Creator+ tiers, Coming Soon)
for event in kumiho.event_stream(cursor=saved_cursor):
    process(event)
    save_cursor(event.cursor)  # Persist for recovery

Environment Variables

Variable	Required	Description
KUMIHO_SERVER_ENDPOINT	No	gRPC endpoint. Defaults to localhost:8080.
KUMIHO_AUTH_TOKEN	For live calls	Firebase ID token (JWT).
KUMIHO_AUTH_TOKEN_FILE	No	Path to file containing the Firebase token.
KUMIHO_CONTROL_PLANE_URL	No	Control plane URL. Defaults to https://control.kumiho.cloud.
KUMIHO_AUTO_CONFIGURE	No	Set to true to auto-bootstrap on import.
KUMIHO_DISCOVERY_CACHE_FILE	No	Discovery cache path. Defaults to ~/.kumiho/discovery-cache.json.

Multi-Tenant Usage

# Use discovery to auto-configure for your tenant
kumiho.auto_configure_from_discovery()

# Or specify a tenant explicitly
kumiho.auto_configure_from_discovery(tenant_hint="my-studio")

# Switch between tenants using context managers
tenant_a = kumiho.connect(endpoint="tenant-a.kumiho.cloud:443")
tenant_b = kumiho.connect(endpoint="tenant-b.kumiho.cloud:443")

with kumiho.use_client(tenant_a):
    projects_a = kumiho.get_projects()

with kumiho.use_client(tenant_b):
    projects_b = kumiho.get_projects()

MCP Server (Model Context Protocol)

Kumiho includes an MCP server that enables AI assistants (GitHub Copilot, Claude, Cursor, etc.) to interact with your asset graph.

Installation

pip install kumiho[mcp]

Running the MCP Server

# Ensure you're authenticated first
kumiho-auth login

# Start the MCP server
kumiho-mcp

VS Code Configuration

Add to your VS Code settings.json:

{
    "mcp": {
        "servers": {
            "kumiho": {
                "command": "kumiho-mcp"
            }
        }
    }
}

Available Tools

The MCP server exposes 39 tools organized by category:

Read Operations

Tool	Description
kumiho_list_projects	List all accessible projects
kumiho_get_project	Get project details by name
kumiho_get_spaces	Get spaces within a project
kumiho_get_item	Get an item by kref URI
kumiho_search_items	Search items with filters
kumiho_get_revision	Get a revision by kref
kumiho_get_artifacts	Get all artifacts for a revision
kumiho_resolve_kref	Resolve kref to file location

Graph Traversal

Tool	Description
kumiho_get_dependencies	Get what a revision depends on
kumiho_get_dependents	Get what depends on a revision
kumiho_analyze_impact	Analyze downstream impact of changes
kumiho_find_path	Find shortest path between revisions
kumiho_get_edges	Get edges (relationships) for a revision

Create Operations

Tool	Description
kumiho_create_project	Create a new project
kumiho_create_space	Create a space within a project
kumiho_create_item	Create an item within a space
kumiho_create_revision	Create a new revision for an item
kumiho_create_artifact	Create an artifact for a revision
kumiho_create_edge	Create relationship between revisions
kumiho_tag_revision	Apply a tag to a revision

For full MCP documentation, see the MCP Server Guide.

Running Tests

# Run all tests
pytest tests/ -v

# Run with coverage
pytest tests/ --cov=kumiho

Documentation

• Getting Started Guide
• Core Concepts
• API Reference
• MCP Server

Requirements

• Python 3.10+
• Kumiho Cloud account (sign up)

License

MIT - See LICENSE for details.

Contributing

Contributions are welcome! See CONTRIBUTING.md for guidelines.

Links

• Website: kumiho.io
• Documentation: docs.kumiho.io
• GitHub: github.com/kumihoclouds/kumiho-python
• PyPI: pypi.org/project/kumiho