Framework Selection

The Kailash stack has three layers of abstraction: primitives, engines, and agents. Start at the highest layer that fits your problem. Drop down only when the higher layer cannot express the pattern you need.

The rule

1. Start with engines. DataFlowEngine, NexusEngine, PactEngine. They compose across all primitives and handle governance, middleware, and data classification automatically.
2. Add agents when you need autonomous execution. Delegate for a single governed agent. GovernedSupervisor for multi-agent orchestration.
3. Drop to primitives when the engine cannot express the pattern. WorkflowBuilder, BaseAgent, Signature. Raw building blocks with no composition layer.
4. Never write raw code when a framework exists. If you are writing SQL strings, use DataFlow. If you are writing HTTP handlers, use Nexus. If you are writing if-else agent routing, use Kaizen.

Decision table

You need to…	Use this	Layer
Store and query data with governance	DataFlowEngine	Engine
Fast CRUD without workflow overhead	DataFlow Express (db.express)	Engine
Deploy as API + CLI + MCP	NexusEngine	Engine
Evaluate governance constraints	PactEngine	Engine
Run a single autonomous agent	Delegate	Agent
Coordinate multiple governed agents	GovernedSupervisor	Agent
Build a custom workflow from nodes	WorkflowBuilder	Primitive
Build a custom agent type	BaseAgent + Signature	Primitive
Implement custom constraint logic	GovernanceEngine directly	Primitive

When to use engines

Engines are the right starting point for most projects. They compose across all primitives and enforce governance automatically.

DataFlowEngine when you have data models. Define a Python dataclass; receive governed CRUD operations, migrations, and query monitoring across PostgreSQL, MySQL, SQLite, and MongoDB. The Express path (db.express.create, db.express.list) provides 0.27ms CRUD when you do not need workflow composition.

NexusEngine when you need to deploy. One codebase, three channels (REST API, CLI, MCP server). Enterprise presets configure CSRF, audit logging, rate limiting, and security headers in one line. The middleware applies uniformly regardless of which primitives your workflows use.

PactEngine when you need organizational governance. D/T/R addressing, constraint envelopes, cost tracking. The Trust Plane facade that every agent and engine integrates with. Fail-closed: unknown states are denied.

When to use agents

Agents sit below the governance line. They use an LLM to reason and act, but every action passes through the engines above the line.

Delegate for a single agent that reasons autonomously within a constraint envelope. TAOD loop: Think (plan), Act (call tools), Observe (read results), Decide (continue or stop). The governance gate checks every action before execution.

GovernedSupervisor for multiple agents working together under governance. Seven subsystems handle accountability, budget, clearance, cascade, dereliction, bypass, and audit. Progressive disclosure: Layer 1 needs three lines of code.

from kaizen_agents import GovernedSupervisor

# Layer 1: three lines
supervisor = GovernedSupervisor(agents=[agent_a, agent_b])
result = await supervisor.run(task="Analyze Q4 revenue trends")

When to drop to primitives

Primitives are building blocks. Use them when the engine layer cannot express your specific pattern.

WorkflowBuilder when you need a custom workflow topology that DataFlowEngine’s auto-generated nodes do not cover. Connect nodes manually, add conditional branching, implement cyclic convergence patterns.

BaseAgent + Signature when Delegate’s TAOD loop does not fit your agent architecture. Build a custom agent with its own reasoning loop, tool selection strategy, or output structure.

GovernanceEngine directly when PactEngine’s facade does not expose the constraint evaluation you need. Rare; most projects use PactEngine or GovernedSupervisor.

The governance line in practice

The governance line is not just a diagram concept. It is an architectural boundary in the code.

Above the line (engines and primitives): deterministic. Given the same inputs, the same outputs. No LLM, no judgment, no probability. A constraint envelope evaluates the same way every time. A DataFlow query returns the same results. A Nexus deployment applies the same middleware.

Below the line (agents): autonomous. The LLM reasons. The plan may differ between runs. But every action the agent takes crosses back above the line through the governance gate. The non-determinism is contained; the enforcement is not.

This is why the governance line matters: it separates what you can prove from what you must trust. Above the line, you can audit deterministically. Below the line, the audit trail records what happened, but the reasoning is probabilistic. The stack is designed so that the things you need to be certain about (constraint enforcement, budget limits, data classification, audit trails) live above the line, and the things that benefit from flexibility (planning, tool selection, natural language interaction) live below it.