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

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

# Resumable streaming (all tiers)
for event in kumiho.event_stream(cursor=saved_cursor):
    process(event)
    save_cursor(event.cursor)  # Persist for recovery

Environment Variables

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

Graph Traversal

Create Operations

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

Efficient memory retrieval (0.14.1)

The internal tool_memory_retrieve(..., include_resolved_metadata=True) path resolves current published tags in batches of at most 100 items, then resolves latest only for missing items. Returned resolved_metadata is keyed by the exact revision kref and restricted to final results. Search order, type/space filters, and revision unrolling semantics are preserved. On batch failure, individual resolution remains available and batch attempts back off for 60 seconds on that client. Deploy a server with the current-tag batch fix first. The public MCP tool schema is unchanged; older callers retain their response.

Opt-in memory search packets

Memory retrieval with include_resolved_metadata=True uses Search's additive memory_project and memory_revision_limit fields for ordinary query search and latest mode. Supporting servers validate the exact non-deprecated project under the authenticated tenant and attach current published/latest revisions to leading hits. The acknowledgement memory_project_validated is required before skipping the legacy project preflight; older servers keep the previous path. A resolved hit with no accessible revision is distinct from an unhydrated hit. Ranking, metadata, type/space filters and pattern fallbacks remain unchanged. Deploy the server support before releasing clients. Search and Evaluate remain separate at the memory orchestration layer; graph/sibling processing still runs before evaluation, so this change does not evaluate an incomplete candidate set.