kailash 0.13.0

Python SDK for the Kailash container-node architecture

Kailash SDK

Enterprise Workflow Engine with Cryptographic Trust

The core engine for building trust-verified workflows with 140+ production-ready nodes, sync and async runtimes, cyclic workflow support, and the CARE/EATP cryptographic trust framework. Three application frameworks -- Kaizen (AI agents), Nexus (multi-channel platform), and DataFlow (database operations) -- are built on this foundation.

---

Why Kailash?

• Only workflow engine with cryptographic trust chains -- CARE/EATP provides human-origin tracking, constraint propagation, trust verification, and RFC 3161 timestamped audit trails. No other framework has anything comparable.
• 140+ production-ready workflow nodes -- AI, API, code execution, data, database, file, logic, monitoring, and transform nodes out of the box.
• Embeddable runtime with no external dependencies -- LocalRuntime runs entirely in-process. No server cluster, no external database, no message broker. Works in CLI tools, serverless functions, and embedded applications.
• Sync and async runtime parity -- LocalRuntime and AsyncLocalRuntime share the same API and return identical (results, run_id) structures. Use sync for scripts, async for Docker/FastAPI.
• Foundation for three application frameworks -- Kaizen (AI agents with trust), Nexus (multi-channel deploy), and DataFlow (zero-config database) are all built on this Core SDK.

---

Architecture

+------------------------------------------------------------------+
|                    Application Frameworks                         |
|                                                                   |
|   Kaizen v1.2.5          Nexus v1.4.2        DataFlow v0.12.4    |
|   AI Agents              Multi-Channel        Zero-Config DB      |
|   CARE/EATP Trust        API + CLI + MCP      @db.model           |
|   Multi-Agent Coord.     Auth + RBAC          11 Nodes/Model      |
+------------------------------------------------------------------+
|                    Core SDK v0.12.5                                |
|                                                                   |
|   140+ Nodes    |  WorkflowBuilder   |  Runtime (Sync + Async)   |
|   MCP Server    |  Cyclic Workflows  |  CARE Trust Layer          |
|                 |  Conditional Exec  |  Trust Verification        |
+------------------------------------------------------------------+
|                    Enterprise Capabilities                        |
|                                                                   |
|   RBAC + Auth   |  Audit Trails      |  Multi-Tenancy            |
|   Secret Mgmt   |  Resource Limits   |  Access Control            |
+------------------------------------------------------------------+

---

Quick Start

Installation

# Core SDK
pip install kailash

# Application frameworks (each includes Core SDK)
pip install kailash-kaizen     # AI agents with trust
pip install kailash-nexus      # Multi-channel platform (API + CLI + MCP)
pip install kailash-dataflow   # Zero-config database operations

Workflow Orchestration

The Core SDK provides WorkflowBuilder and LocalRuntime for building and executing DAG-based workflows with 140+ built-in nodes.

from kailash.workflow.builder import WorkflowBuilder
from kailash.runtime import LocalRuntime

workflow = WorkflowBuilder()
workflow.add_node("PythonCodeNode", "process", {
    "code": "result = {'message': 'Hello from Kailash!'}"
})

runtime = LocalRuntime()
results, run_id = runtime.execute(workflow.build())
print(results["process"]["result"])  # {'message': 'Hello from Kailash!'}

Async runtime for Docker/FastAPI deployments:

import asyncio
from kailash.runtime import AsyncLocalRuntime

async def main():
    runtime = AsyncLocalRuntime()
    results, run_id = await runtime.execute_workflow_async(workflow.build(), inputs={})
    print(results)

asyncio.run(main())
# Or use `await` directly inside FastAPI route handlers

Trust Verification (CARE/EATP)

Kailash is the only workflow engine with built-in cryptographic trust verification. Trust context propagates through all workflow execution automatically.

from kailash.runtime.trust import (
    RuntimeTrustContext,
    TrustVerificationMode,
    runtime_trust_context,
)
from kailash.runtime import LocalRuntime

# Create a trust context with enforcing verification
ctx = RuntimeTrustContext(
    trace_id="audit-trace-2024-001",
    verification_mode=TrustVerificationMode.ENFORCING,
    delegation_chain=["human-operator-jane", "supervisor-agent", "worker-agent"],
    constraints={"max_tokens": 1000, "allowed_tools": ["read", "analyze"]},
)

# Trust context propagates through all workflow execution
with runtime_trust_context(ctx):
    runtime = LocalRuntime()
    results, run_id = runtime.execute(workflow.build())

# Constraints can only be tightened (immutable pattern)
tighter_ctx = ctx.with_constraints({"allowed_tools": ["read"]})  # Removes "analyze"
node_ctx = ctx.with_node("data_processor")  # Tracks execution path

---

Ecosystem Frameworks

Three application frameworks are built on Core SDK, each in its own package within this monorepo:

Kaizen: AI Agents with Cryptographic Trust

Production-ready AI agents with signature-based programming, multi-agent coordination, and the CARE/EATP trust framework.

import asyncio, os
from dotenv import load_dotenv
load_dotenv()

from kaizen.api import Agent

async def main():
    model = os.environ.get("DEFAULT_LLM_MODEL", "gpt-4o")
    agent = Agent(model=model)
    result = await agent.run("Analyze this quarterly report for compliance risks")

asyncio.run(main())

pip install kailash-kaizen | Repository | Documentation

Nexus: Multi-Channel Platform

Write a function once. Deploy it as a REST API, CLI command, and MCP tool simultaneously.

from nexus import Nexus

app = Nexus()

@app.handler("analyze", description="Analyze a document")
async def analyze(document: str, format: str = "summary") -> dict:
    return {"analysis": f"Analyzed '{document}' as {format}"}

app.start()
# REST API:  POST /workflows/analyze {"document": "report.pdf"}
# CLI:       nexus run analyze --document report.pdf
# MCP:       AI agents can call the 'analyze' tool directly

pip install kailash-nexus | Repository | Documentation

DataFlow: Zero-Config Database

One decorator generates 11 database operation nodes per model. Supports PostgreSQL, MySQL, and SQLite.

from dataflow import DataFlow

db = DataFlow("sqlite:///app.db")

@db.model
class User:
    id: str
    name: str
    email: str

# Automatically generated:
# UserCreateNode, UserReadNode, UserUpdateNode, UserDeleteNode,
# UserListNode, UserCountNode, UserUpsertNode,
# UserBulkCreateNode, UserBulkUpdateNode, UserBulkDeleteNode, UserBulkUpsertNode

pip install kailash-dataflow | Repository | Documentation

---

CARE Trust Framework

The CARE (Context, Action, Reasoning, Evidence) framework and EATP (Enterprise Agent Trust Protocol) are Core SDK features that provide:

• Human origin tracking -- trace every AI action back to the human who authorized it, across delegation chains
• Constraint propagation -- constraints can only be tightened as they flow through agent delegations, never loosened
• Trust verification -- three modes (disabled, permissive, enforcing) with cached verification and high-risk node awareness
• EATP-compliant audit trails -- every workflow start, node execution, trust verification, and resource access is recorded with RFC 3161 timestamps

Trust verification for workflows, nodes, and resources:

from kailash.runtime.trust import TrustVerifier, TrustVerifierConfig

verifier = TrustVerifier(
    config=TrustVerifierConfig(
        mode="enforcing",
        high_risk_nodes=["BashCommand", "HttpRequest", "DatabaseQuery"],
    ),
)

# Verify before execution -- blocks unauthorized access in enforcing mode
result = await verifier.verify_workflow_access(
    workflow_id="financial-report-gen",
    agent_id="analyst-agent-42",
    trust_context=ctx,
)

if result.allowed:
    # Execute with full audit trail
    pass

---

Key Features

Core SDK (v0.12.5)

• 140+ production nodes: AI, API, code execution, data, database, file, logic, monitoring, transform
• Runtime parity: LocalRuntime (sync) and AsyncLocalRuntime (async) with identical return structures
• CARE trust layer: RuntimeTrustContext, TrustVerifier, RuntimeAuditGenerator
• Cyclic workflows: CycleBuilder API with convergence detection
• MCP integration: Built-in Model Context Protocol server support
• Conditional execution: SwitchNode branching and skip patterns
• Embeddable: Runs in-process with no external dependencies
• Performance optimized: Cached topological sort, networkx removed from hot path, opt-in resource limits

Ecosystem Frameworks

Framework	Version	Key Capabilities
Kaizen	v1.2.5	Signature-based AI agents, multi-agent coordination, CARE/EATP trust, FallbackRouter, MCP sessions
Nexus	v1.4.2	Multi-channel deploy (API+CLI+MCP), handler pattern, NexusAuthPlugin, presets, middleware API
DataFlow	v0.12.4	11 nodes per model, PostgreSQL/MySQL/SQLite parity, auto-wired multi-tenancy, async transactions

---

Testing

# Core SDK unit tests (7,800+ tests)
pytest tests/unit/ -m 'not (slow or integration or e2e)' --timeout=1

# Runtime parity tests
pytest tests/parity/ -v

# Integration tests (requires Docker for PostgreSQL/Redis)
pytest tests/integration/ --timeout=5

# End-to-end tests
pytest tests/e2e/ --timeout=10

Testing policy: Tier 1 (unit) allows mocking. Tier 2 (integration) and Tier 3 (E2E) require real infrastructure -- no mocking permitted.

---

Documentation

Resource	Description
Kaizen Guide	AI agents, signatures, multi-modal, CARE/EATP trust
Nexus Guide	Multi-channel platform, auth, middleware, handlers
DataFlow Guide	Database operations, models, queries, multi-tenancy
Sphinx Docs	Full API reference and guides

---

Contributing

# Clone and setup
git clone https://github.com/terrene-foundation/kailash-py.git
cd kailash-py
uv sync

# Run tests
pytest tests/unit/ -m 'not (slow or integration or e2e)' --timeout=1

# Code quality
black .
isort .
ruff check .

See Contributing Guide for details.

---

License

This project is licensed under the Apache License, Version 2.0. You may use, modify, distribute, and commercialize the software freely, subject to the terms of the license.

See the LICENSE file for the full license text.

The Kailash SDK is the subject of patent applications owned by Terrene Foundation See the PATENTS file for details. Under Apache License 2.0, Section 3, each Contributor grants a patent license covering claims necessarily infringed by their Contribution(s) alone or by combination of their Contribution(s) with the Work, subject to the defensive termination clause in Section 3.

---

Install from PyPI | Documentation | GitHub