kaizen

name	kaizen
description	Kailash Kaizen (Python) — MANDATORY for AI agents/RAG/signatures. Custom LLM agents BLOCKED.

Kailash Kaizen - AI Agent Framework

Kaizen is a production-ready AI agent framework built on Kailash Core SDK that provides signature-based programming and multi-agent coordination.

Features

Kaizen enables building sophisticated AI agents with:

• Signature-Based Programming: Type-safe agent interfaces with automatic validation and optimization
• BaseAgent Architecture: Production-ready agent foundation with error handling, audit trails, and cost tracking
• Multi-Agent Coordination: Supervisor-worker, agent-to-agent protocols, hierarchical structures
• Orchestration Patterns: 9 composable patterns (Ensemble, Blackboard, Router, Parallel, Sequential, Supervisor-Worker, Handoff, Consensus, Debate)
• Multimodal Processing: Vision, audio, and text processing capabilities
• Autonomy Infrastructure: 6 integrated subsystems (Hooks, Checkpoint, Interrupt, Memory, Planning, Meta-Controller)
• Distributed Coordination: AgentRegistry for 100+ agent systems with O(1) capability discovery
• Enterprise Features: Cost tracking, streaming responses, automatic optimization
• Memory System: 3-tier hierarchical storage (Hot/Warm/Cold) with DataFlow backend
• Security: RBAC, process isolation, compliance controls (SOC2, GDPR, HIPAA, PCI-DSS)
• Enterprise Agent Trust Protocol (v0.8.0): Cryptographic trust chains, TrustedAgent, secure messaging, credential rotation
• Performance Optimization (v1.0): 7 caches with 10-100x speedup (SchemaCache, EmbeddingCache, PromptCache, etc.)
• Specialist System (v1.0): Claude Code-style specialists and skills with .kaizen/ directory
• GPT-5 Support (v1.0): Automatic temperature=1.0 enforcement, 8000 max_tokens for reasoning
• Wrapper Composition System: Stackable cross-cutting wrappers (governance, monitoring, streaming) with enforced ordering

Quick Start

Basic Agent

from kaizen.core.base_agent import BaseAgent
from kaizen.signatures import Signature, InputField, OutputField
from dataclasses import dataclass

# Define agent signature (type-safe interface)
class SummarizeSignature(Signature):
    text: str = InputField(description="Text to summarize")
    summary: str = OutputField(description="Generated summary")

# Define configuration
@dataclass
class SummaryConfig:
    llm_provider: str = os.environ.get("LLM_PROVIDER", "openai")
    model: str = os.environ["LLM_MODEL"]
    temperature: float = 0.7

# Create agent with signature
class SummaryAgent(BaseAgent):
    def __init__(self, config: SummaryConfig):
        super().__init__(
            config=config,
            signature=SummarizeSignature()
        )

# Execute
agent = SummaryAgent(SummaryConfig())
result = agent.run(text="Long text here...")
print(result['summary'])

Pipeline Patterns (Orchestration)

from kaizen_agents.patterns.pipeline import Pipeline

# Ensemble: Multi-perspective collaboration
pipeline = Pipeline.ensemble(
    agents=[code_expert, data_expert, writing_expert, research_expert],
    synthesizer=synthesis_agent,
    discovery_mode="a2a",  # A2A semantic matching
    top_k=3                # Select top 3 agents
)

# Execute - automatically selects best agents for task
result = pipeline.run(task="Analyze codebase", input="repo_path")

# Router: Intelligent task delegation
router = Pipeline.router(
    agents=[code_agent, data_agent, writing_agent],
    routing_strategy="semantic"  # A2A-based routing
)

# Blackboard: Iterative problem-solving
blackboard = Pipeline.blackboard(
    agents=[solver, analyzer, optimizer],
    controller=controller,
    max_iterations=10,
    discovery_mode="a2a"
)

Reference Documentation

Comprehensive Guides

For in-depth documentation, see the kaizen package (docs/):

Core Guides:

• [BaseAgent Architecture](../../../the kaizen package directory docs/guides/baseagent-architecture.md) - Complete unified agent system guide
• [Multi-Agent Coordination](../../../the kaizen package directory docs/guides/multi-agent-coordination.md) - Google A2A protocol, 5 coordination patterns
• [Signature Programming](../../../the kaizen package directory docs/guides/signature-programming.md) - Complete signature system guide
• [Hooks System Guide](../../../the kaizen package directory docs/guides/hooks-system-guide.md) - Event-driven observability framework
• [Integration Patterns](../../../the kaizen package directory docs/guides/integration-patterns.md) - DataFlow, Nexus, MCP integration
• [Meta-Controller Guide](../../../the kaizen package directory docs/guides/meta-controller-guide.md) - Intelligent task delegation
• [Planning System Guide](../../../the kaizen package directory docs/guides/planning-system-guide.md) - Structured workflow orchestration

Reference Documentation:

• [API Reference](../../../the kaizen package directory docs/reference/api-reference.md) - Complete API documentation
• [Checkpoint API](../../../the kaizen package directory docs/reference/checkpoint-api.md) - State persistence API
• [Coordination API](../../../the kaizen package directory docs/reference/coordination-api.md) - Multi-agent coordination API
• [Interrupts API](../../../the kaizen package directory docs/reference/interrupts-api.md) - Graceful shutdown API
• [Memory API](../../../the kaizen package directory docs/reference/memory-api.md) - 3-tier memory system API
• [Observability API](../../../the kaizen package directory docs/reference/observability-api.md) - Hooks and monitoring API
• [Planning Agents API](../../../the kaizen package directory docs/reference/planning-agents-api.md) - Planning/PEV/ToT agents API
• [Tools API](../../../the kaizen package directory docs/reference/tools-api.md) - Tool calling and approval API
• [Configuration Guide](../../../the kaizen package directory docs/reference/configuration.md) - All configuration options
• [Troubleshooting](../../../the kaizen package directory docs/reference/troubleshooting.md) - Common issues and solutions

Quick Start (Skills)

• kaizen-quickstart-template - Quick start guide with templates
• kaizen-baseagent-quick - BaseAgent fundamentals
• kaizen-signatures - Signature-based programming
• kaizen-agent-execution - Agent execution patterns
• README - Framework overview

LLM Wire Layer (Lower-Level)

• kaizen-llm-deployment - kaizen.llm.LlmClient + four-axis LlmDeployment + 24 presets + from_env() precedence + wire-send dispatch. Load first when touching LlmDeployment, LlmClient.embed()/complete(), wire_protocols/*, or adding a new wire-send method. Spec: specs/kaizen-llm-deployments.md.

Agent Patterns

• kaizen-agent-patterns - Common agent design patterns
• kaizen-chain-of-thought - Chain of thought reasoning
• kaizen-react-pattern - ReAct (Reason + Act) pattern
• kaizen-rag-agent - Retrieval-Augmented Generation agents
• kaizen-config-patterns - Agent configuration strategies

Multi-Agent Systems & Orchestration

• kaizen-multi-agent-setup - Multi-agent system setup
• kaizen-supervisor-worker - Supervisor-worker coordination
• kaizen-a2a-protocol - Agent-to-agent communication
• kaizen-shared-memory - Shared memory between agents
• kaizen-agent-registry - Distributed agent coordination for 100+ agent systems

Pipeline Patterns (9 Composable Patterns):

• Ensemble: Multi-perspective collaboration with A2A discovery + synthesis
• Blackboard: Controller-driven iterative problem-solving
• Router (Meta-Controller): Intelligent task routing via A2A matching
• Parallel: Concurrent execution with aggregation
• Sequential: Linear agent chain
• Supervisor-Worker: Hierarchical coordination
• Handoff: Agent handoff with context transfer
• Consensus: Voting-based decision making
• Debate: Adversarial deliberation

Multimodal Processing

• kaizen-multimodal-orchestration - Multimodal coordination
• kaizen-vision-processing - Vision and image processing
• kaizen-audio-processing - Audio processing agents
• kaizen-multimodal-pitfalls - Common pitfalls and solutions

Advanced Features

• kaizen-control-protocol - Bidirectional agent ↔ client communication
• kaizen-tool-calling - Autonomous tool execution with approval workflows
• kaizen-memory-system - Persistent memory, learning, FAQ detection
• kaizen-checkpoint-resume - Checkpoint & resume for long-running agents
• kaizen-interrupt-mechanism - Graceful shutdown, Ctrl+C handling
• kaizen-persistent-memory - DataFlow-backed conversation persistence
• kaizen-streaming - Streaming agent responses
• kaizen-cost-tracking - Cost monitoring and optimization
• kaizen-ux-helpers - UX enhancement utilities

Observability & Monitoring

• kaizen-observability-hooks - Lifecycle event hooks, production security (RBAC)
• kaizen-observability-tracing - Distributed tracing with OpenTelemetry
• kaizen-observability-metrics - Prometheus metrics collection
• kaizen-observability-logging - Structured JSON logging
• kaizen-observability-audit - Compliance audit trails

Enterprise Agent Trust Protocol (v0.8.0)

• kaizen-trust-eatp - Complete trust infrastructure for AI agents
  • Trust lineage chains with cryptographic verification
  • TrustedAgent and TrustedSupervisorAgent with built-in trust
  • Secure messaging with HMAC authentication and replay protection
  • Trust-aware orchestration with policy enforcement
  • Enterprise System Agent (ESA) for legacy system integration
  • A2A HTTP service for cross-organization trust operations
  • Credential rotation, rate limiting, and security audit logging

Agent Manifest & Deploy (v1.3)

• kaizen-agent-manifest - TOML-based agent declaration, governance metadata, and deployment
  • AgentManifest with [agent] and [governance] TOML sections
  • GovernanceManifest with risk_level, suggested_posture, budget
  • introspect_agent() for runtime metadata extraction (Python API only, NOT MCP)
  • deploy() / deploy_local() for local FileRegistry or remote CARE Platform
  • FileRegistry with atomic writes and path traversal prevention

Composition Validation (v1.3)

• kaizen-composition - DAG validation, schema compatibility, cost estimation
  • validate_dag() with iterative DFS cycle detection (max_agents=1000)
  • check_schema_compatibility() with JSON Schema structural subtyping and type widening
  • estimate_cost() with historical data projection and confidence levels

MCP Catalog Server (v1.3)

• kaizen-catalog-server - Standalone MCP server for agent catalog operations
  • CatalogMCPServer with 11 tools: Discovery (4), Deployment (3), Application (2), Governance (2)
  • Separate from KaizenMCPServer (which handles BaseAgent tools)
  • Pre-seeds 14 built-in agents on startup
  • Entry point: python -m kaizen.mcp.catalog_server

Budget Tracking & Posture Integration (v1.3)

• kaizen-budget-tracking - Atomic budget accounting and posture-budget governance
  • BudgetTracker with two-phase reserve/record, threshold callbacks, on_record() API
  • PostureBudgetIntegration links budget to posture state machine
  • Configurable thresholds: warning (80%), downgrade to SUPERVISED (95%), emergency to PSEUDO_AGENT (100%)

L3 Autonomy Primitives

• kaizen-l3-overview - L3 primitives overview (5 subsystems)
  • EnvelopeTracker/Splitter/Enforcer for continuous budget tracking
  • ScopedContext for hierarchical context with access control
  • MessageRouter/Channel for typed inter-agent messaging
  • AgentFactory/Registry for runtime agent spawning
  • PlanValidator/Executor for DAG task graph execution
• kaizen-l3-envelope - Budget tracking, splitting, and non-bypassable enforcement
  • EnvelopeTracker with atomic recording, child allocation, reclamation
  • EnvelopeSplitter for stateless ratio-based budget division
  • EnvelopeEnforcer middleware with gradient zones (AutoApproved/Flagged/Held/Blocked)
• kaizen-l3-context - Hierarchical scoped context with projection-based access control
  • ContextScope tree with parent traversal and child merge
  • ScopeProjection glob patterns (allow/deny with deny precedence)
  • DataClassification 5-level clearance filtering
• kaizen-l3-messaging - Typed inter-agent communication
  • MessageRouter with 8-step validation
  • 6 typed payloads: Delegation, Status, Clarification, Completion, Escalation, System
  • DeadLetterStore bounded ring buffer for undeliverable messages
• kaizen-l3-factory - Runtime agent spawning with lifecycle tracking
  • AgentFactory with 8-check spawn preconditions
  • 6-state lifecycle machine (Pending/Running/Waiting/Completed/Failed/Terminated)
  • Cascade termination (leaves-first)
• kaizen-l3-plan-dag - Dynamic task graph execution
  • PlanValidator structural + envelope validation
  • PlanExecutor with gradient rules (G1-G8)
  • 7 typed modifications with batch-atomic application

v1.0 Developer Guides

Located in the package source:

• Performance Optimization (09-performance-optimization-guide.md) - Caching (10-100x speedup), parallel execution
• Specialist System (06-specialist-system-guide.md) - Claude Code-style specialists and skills
• Native Tool System (00-native-tools-guide.md) - TAOD loop tool integration
• Runtime Abstraction (01-runtime-abstraction-guide.md) - Multi-runtime support
• LocalKaizenAdapter (02-local-kaizen-adapter-guide.md) - TAOD loop implementation
• Memory Provider (03-memory-provider-guide.md) - Memory provider interface
• Multi-LLM Routing (04-multi-llm-routing-guide.md) - Intelligent LLM selection
• Unified Agent API (05-unified-agent-api-guide.md) - Simplified 2-line agent creation
• Task/Skill Tools (07-task-skill-tools-guide.md) - Subagent spawning
• Claude Code Parity (08-claude-code-parity-tools-guide.md) - 7 parity tools

Testing & Quality

• kaizen-testing-patterns - Testing AI agents
• [Performance Benchmarks](../../../the kaizen package directory docs/benchmarks/BENCHMARK_GUIDE.md) - Measure Kaizen performance

Key Concepts

Signature-Based Programming

Signatures define type-safe interfaces for agents:

• Input: Define expected inputs with descriptions
• Output: Specify output format and structure
• Validation: Automatic type checking and validation
• Optimization: Framework can optimize prompts automatically

BaseAgent Architecture

Foundation for all Kaizen agents:

• Error Handling: Built-in retry logic and error recovery
• Audit Trails: Automatic logging of agent actions
• Cost Tracking: Monitor API usage and costs
• Streaming: Support for streaming responses
• Memory: State management across invocations
• Hooks System: Zero-code-change observability and lifecycle management

Autonomy Infrastructure (6 Subsystems)

1. Hooks System - Event-driven observability framework

• Zero-code-change monitoring via lifecycle events (PRE/POST hooks)
• 6 builtin hooks: Logging, Metrics, Cost, Performance, Audit, Tracing
• Production security: RBAC, Ed25519 signatures, process isolation, rate limiting
• Performance: <0.01ms overhead (625x better than 10ms target)

2. Checkpoint System - Persistent state management

• Save/load/fork agent state for failure recovery
• 4 storage backends: Filesystem, Redis, PostgreSQL, S3
• Automatic compression and incremental checkpoints
• State manager with deduplication and versioning

3. Interrupt Mechanism - Graceful shutdown and execution control

• 3 interrupt sources: USER (Ctrl+C), SYSTEM (timeout/budget), PROGRAMMATIC (API)
• 2 shutdown modes: GRACEFUL (finish cycle + checkpoint) vs IMMEDIATE (stop now)
• Signal propagation across multi-agent hierarchies

4. Memory System - 3-tier hierarchical storage

• Hot tier: In-memory buffer (<1ms retrieval, last 100 messages)
• Warm tier: Database (10-50ms, agent-specific history with JSONL compression)
• Cold tier: Object storage (100ms+, long-term archival with S3/MinIO)
• DataFlow-backed with auto-persist and cross-session continuity

5. Planning Agents - Structured workflow orchestration

• PlanningAgent: Plan before you act (pre-execution validation)
• PEVAgent: Plan, Execute, Verify, Refine (iterative refinement)
• Tree-of-Thoughts: Explore multiple reasoning paths
• Multi-step decomposition, validation, and replanning

6. Meta-Controller Routing - Intelligent task delegation

• A2A-based semantic capability matching (no hardcoded if/else)
• Automatic agent discovery, ranking, and selection
• Fallback strategies and load balancing
• Integrated with Router, Ensemble, and Supervisor-Worker patterns

AgentRegistry - Distributed Coordination

For 100+ agent distributed systems:

• O(1) capability-based discovery with semantic matching
• Event broadcasting (6 event types for cross-runtime coordination)
• Health monitoring with automatic deregistration
• Status management (ACTIVE, UNHEALTHY, DEGRADED, OFFLINE)
• Multi-runtime coordination across processes/machines

When to Use This Skill

Use Kaizen when you need to:

• Build AI agents with type-safe interfaces
• Implement multi-agent systems with orchestration patterns
• Process multimodal inputs (vision, audio, text)
• Create RAG (Retrieval-Augmented Generation) systems
• Implement chain-of-thought reasoning
• Build supervisor-worker or ensemble architectures
• Track costs and performance of AI agents
• Add zero-code-change observability to agents
• Monitor, trace, and audit agent behavior in production
• Secure agent observability with RBAC and compliance controls
• Create production-ready agentic applications
• Enterprise trust and accountability (v0.8.0):
  • Cryptographic trust chains for AI agents
  • Cross-organization agent coordination
  • Regulatory compliance with audit trails
  • Secure inter-agent communication
• Agent manifest, deploy, and composition (v1.3):
  • Declare agents with TOML manifests and governance metadata
  • Deploy agents to local FileRegistry or remote CARE Platform
  • Validate composite agent DAGs for cycles
  • Check schema compatibility between connected agents
  • Estimate pipeline costs from historical data
  • Discover/deploy agents via MCP Catalog Server
  • Link budget thresholds to automatic posture transitions
• L3 Autonomy Primitives:
  • Agent spawning with PACT-governed lifecycle tracking
  • Continuous budget tracking with gradient zones and non-bypassable enforcement
  • Hierarchical scoped context with projection-based access control
  • Typed inter-agent messaging with 8-step routing validation
  • Dynamic task graph execution with gradient-driven failure handling

Use Pipeline Patterns When:

• Ensemble: Need diverse perspectives synthesized (code review, research)
• Blackboard: Iterative problem-solving (optimization, debugging)
• Router: Intelligent task delegation to specialists
• Parallel: Bulk processing or voting-based consensus
• Sequential: Linear workflows with dependency chains

Integration Patterns

With DataFlow (Data-Driven Agents)

from kaizen.core.base_agent import BaseAgent
from dataflow import DataFlow

class DataAgent(BaseAgent):
    def __init__(self, config, db: DataFlow):
        self.db = db
        super().__init__(config=config, signature=MySignature())

With Nexus (Multi-Channel Agents)

from kaizen.core.base_agent import BaseAgent
from nexus import Nexus

# Deploy agents via API/CLI/MCP
agent_workflow = create_agent_workflow()
app = Nexus()
app.register("agent", agent_workflow.build())
app.start()  # Agents available via all channels

With Core SDK (Custom Workflows)

from kaizen.core.base_agent import BaseAgent
from kailash.workflow.builder import WorkflowBuilder

# Embed agents in workflows
workflow = WorkflowBuilder()
workflow.add_node("KaizenAgent", "agent1", {
    "agent": my_agent,
    "input": "..."
})

Provider Configuration (v2.5.0 -- Explicit over Implicit)

As of v2.5.0, provider configuration follows an explicit over implicit model. Structured output config is separated from provider-specific settings.

BaseAgentConfig Fields

Field	Purpose	Example
response_format	Structured output config (json_schema, json_object)	{"type": "json_schema", "json_schema": {}}
provider_config	Provider-specific operational settings only	{"api_version": "2024-10-21"}
structured_output_mode	Controls auto-generation: "auto" (deprecated), "explicit", "off"	"explicit"

Quick Pattern

from kaizen.core.config import BaseAgentConfig
from kaizen.core.structured_output import create_structured_output_config

# Explicit mode (recommended)
config = BaseAgentConfig(
    llm_provider="openai",
    model=os.environ["LLM_MODEL"],
    response_format=create_structured_output_config(MySignature(), strict=True),
    structured_output_mode="explicit",
)

# Azure with provider-specific settings (separate from response_format)
config = BaseAgentConfig(
    llm_provider="azure",
    model=os.environ["LLM_MODEL"],
    response_format={"type": "json_object"},
    provider_config={"api_version": "2024-10-21"},
    structured_output_mode="explicit",
)

Azure Env Vars (Canonical Names)

Canonical	Legacy (deprecated)
AZURE_ENDPOINT	AZURE_OPENAI_ENDPOINT, AZURE_AI_INFERENCE_ENDPOINT
AZURE_API_KEY	AZURE_OPENAI_API_KEY, AZURE_AI_INFERENCE_API_KEY
AZURE_API_VERSION	AZURE_OPENAI_API_VERSION

Legacy vars emit DeprecationWarning. Use resolve_azure_env() from kaizen.nodes.ai.azure_detection for canonical-first resolution.

Anti-Patterns

• Never put structured output config in provider_config -- use response_format
• Never rely on auto-generated structured output without understanding it -- set structured_output_mode="explicit"
• Never use multiple env var names for the same Azure setting without deprecation
• Never use error-based backend switching -- detect the backend upfront or set AZURE_BACKEND explicitly

Prompt Utilities

kaizen.core.prompt_utils is the single source of truth for signature-based prompt generation:

• generate_prompt_from_signature(signature) -- builds system prompt from signature fields
• json_prompt_suffix(output_fields) -- returns JSON format instructions for Azure json_object compatibility

For detailed configuration patterns, see:

• kaizen-config-patterns -- Domain configs, auto-extraction, provider-specific patterns
• kaizen-structured-outputs -- Full structured output guide with migration examples

Critical Rules

• Define signatures before implementing agents
• Extend BaseAgent for production agents
• Use type hints in signatures for validation
• Track costs in production environments
• Test agents with real infrastructure (real infrastructure recommended)
• Enable hooks for observability
• Use AgentRegistry for distributed coordination
• Use response_format for structured output (not provider_config)
• Set structured_output_mode="explicit" for new agents
• NEVER skip signature definitions
• NEVER ignore cost tracking in production
• NEVER put structured output keys in provider_config
• Avoid mocking LLM calls in integration tests (real infrastructure recommended)

Kaizen-Agents Governance (v0.1.0)

• kaizen-agents-governance -- GovernedSupervisor, progressive disclosure (Layer 1/2/3), 7 governance modules
  • GovernedSupervisor with 3-layer progressive API (2-param simple -> 8-param configured -> 9 governance subsystems)
  • AccountabilityTracker -- D/T/R addressing, policy source chain
  • BudgetTracker -- reclamation, predictive warnings, reallocation
  • CascadeManager -- monotonic envelope tightening, BFS termination
  • ClearanceEnforcer + ClassificationAssigner -- data classification (C0-C4), regex pre-filter
  • DerelictionDetector -- insufficient tightening detection
  • BypassManager -- time-limited emergency overrides with anti-stacking
  • VacancyManager -- orphan detection, grandparent auto-designation
  • AuditTrail -- EATP hash chain with hmac.compare_digest()
  • SDK integration: EnvelopeAllocator -> EnvelopeSplitter, ScopeBridge -> ScopedContext

L3 Integration & Event System

• kaizen-l3-overview -- L3 autonomy primitives, L3Runtime integration, EATP event system

  • L3Runtime convenience class wiring all 5 subsystems (Factory->Enforcer, Factory->Router, Factory->Context, Enforcer->Plan)
  • L3EventBus pub/sub for 15 governance event types across all primitives
  • EatpTranslator converts L3 events into EATP audit records with severity classification

• kaizen-agents-security -- Security patterns for governance

  • Anti-self-modification via _ReadOnlyView proxies
  • Pervasive NaN/Inf defense (math.isfinite() on all numeric paths)
  • Bounded collections, monotonic invariants, thread safety
  • Delegate tool security (mandatory BashTool gate, ExecPolicy, session sanitization)

Wrapper Composition System

Composition wrappers add cross-cutting concerns (governance, monitoring, streaming) around a BaseAgent without modifying it. WrapperBase enforces a canonical stacking order and duplicate detection.

Canonical stacking order (innermost to outermost):

BaseAgent -> L3GovernedAgent -> MonitoredAgent -> StreamingAgent

WrapperBase rejects duplicate wrappers (DuplicateWrapperError) and out-of-order stacking (WrapperOrderError). Every wrapper proxies get_parameters() and to_workflow() to the inner agent. The innermost property walks the full stack to the non-wrapper agent.

Key files:

• the kaizen-agents package (src/kaizen_agents/wrapper_base.py) -- WrapperBase with stack ordering + duplicate detection
• the kaizen-agents package (src/kaizen_agents/governed_agent.py) -- L3GovernedAgent with ConstraintEnvelope enforcement (Financial, Operational, Temporal, Data Access, Communication, Posture ceiling). Rejects BEFORE LLM cost is incurred. Uses _ProtectedInnerProxy to block governance bypass via .inner._inner.
• the kaizen-agents package (src/kaizen_agents/monitored_agent.py) -- MonitoredAgent with CostTracker, budget enforcement via BudgetExhaustedError, NaN/Inf defense on budget values
• the kaizen-agents package (src/kaizen_agents/streaming_agent.py) -- StreamingAgent with run_stream() async iterator, typed StreamEvent events, buffer overflow protection, timeout enforcement. Falls back to batch when provider lacks StreamingProvider.
• the kaizen-agents package (src/kaizen_agents/events.py) -- Frozen dataclass events: TextDelta, ToolCallStart, ToolCallEnd, TurnComplete, BudgetExhausted, ErrorEvent, StreamBufferOverflow
• the kaizen-agents package (src/kaizen_agents/supervisor_wrapper.py) -- SupervisorWrapper for task delegation to worker pool via LLMBased routing

Building a wrapper stack:

from kaizen.core.base_agent import BaseAgent
from kaizen_agents.governed_agent import L3GovernedAgent
from kaizen_agents.monitored_agent import MonitoredAgent
from kaizen_agents.streaming_agent import StreamingAgent
from kaizen_agents.events import TextDelta, TurnComplete
from kailash.trust.envelope import ConstraintEnvelope, FinancialConstraint

# Stack innermost to outermost
agent = MyAgent(config=config)
governed = L3GovernedAgent(agent, envelope=ConstraintEnvelope(
    financial=FinancialConstraint(budget_limit=10.0)
))
monitored = MonitoredAgent(governed, budget_usd=5.0)
streaming = StreamingAgent(monitored)

# Stream typed events
async for event in streaming.run_stream(prompt="analyze this"):
    match event:
        case TextDelta(text=t): print(t, end="")
        case TurnComplete(text=t): print(f"\n[Done: {t[:50]}]")

SupervisorWrapper -- delegates tasks to a worker pool using LLM-based routing:

from kaizen_agents.supervisor_wrapper import SupervisorWrapper
from kaizen_agents.patterns.llm_routing import LLMBased

supervisor = SupervisorWrapper(inner_agent, workers=[w1, w2], routing=LLMBased())
result = await supervisor.run_async(task="complex task")

Provider Capability Protocols

SPEC-02 defines runtime_checkable protocols in kaizen.providers.base for structural capability discovery. Providers satisfy protocols structurally -- no explicit inheritance needed.

Protocol	Key Method	Purpose
StreamingProvider	stream_chat() -> StreamEvent	Token-by-token streaming
ToolCallingProvider	chat_with_tools(messages, tools)	Native function calling
StructuredOutputProvider	chat_structured(messages, schema)	JSON schema structured outputs
AsyncLLMProvider	chat_async(messages)	Async chat completions

ProviderCapability enum: CHAT_SYNC, CHAT_ASYNC, CHAT_STREAM, TOOLS, STRUCTURED_OUTPUT, EMBEDDINGS, VISION, AUDIO, REASONING_MODELS, BYOK.

Use get_provider_for_model(model) from kaizen.providers.registry to resolve a model string to a provider instance. Use isinstance(provider, StreamingProvider) for capability checks.

LLM-Based Routing

LLMBased from kaizen_agents.patterns.llm_routing scores agent capabilities against task requirements using Kaizen signatures (not keyword matching or dispatch tables).

from kaizen_agents.patterns.llm_routing import LLMBased

routing = LLMBased(config=config)  # config optional; falls back to .env defaults
score = await routing.score("analyze revenue data", agent_capability)
best = await routing.select_best("analyze revenue data", [agent1, agent2, agent3])

score() returns [0.0, 1.0]. Accepts Capability dataclasses (.name + .description) or plain strings. select_best() returns the highest-scoring candidate or None when empty.

Convergence Status (SPEC-02 / SPEC-05 / SPEC-10)

Three convergence SPECs have shipped on the feat/spec04-baseagent-slim branch:

SPEC-02 (Provider Split) -- The provider monolith (kaizen.nodes.ai.ai_providers) is now split into per-provider modules under kaizen/providers/. See kaizen-multi-provider for the updated registry, protocols, and CostTracker.

• kaizen.providers.base -- ProviderCapability enum (10 members), 5 runtime-checkable protocols
• kaizen.providers.registry -- ProviderRegistry with 14 provider entries and prefix-dispatch model detection
• kaizen.providers.cost -- CostTracker with thread-safe accumulation
• Backward-compat shim at kaizen.nodes.ai.ai_providers re-exports all public names

SPEC-05 (Delegate Facade) -- Delegate is now a composition facade wrapping AgentLoop -> [L3GovernedAgent] -> [MonitoredAgent]. See kaizen-delegate for the updated API surface.

• ConstructorIOError -- raised on outbound IO in __init__
• ToolRegistryCollisionError -- raised on duplicate tool name registration
• run_sync() refuses under a running event loop with an actionable error message
• Deferred MCP: mcp_servers= stores configs, connects on first run()
• Introspection: .core_agent, .signature, .model read-only properties

SPEC-10 (Multi-Agent) -- 11 deprecated agent subclasses (SupervisorAgent, WorkerAgent, CoordinatorAgent, PipelineStageAgent, etc.) now emit DeprecationWarning. Composition patterns accept plain BaseAgent instances. max_total_delegations cap (default 20) with DelegationCapExceeded exception.

Related Skills

• 01-core-sdk - Core workflow patterns
• 02-dataflow - Database integration
• 03-nexus - Multi-channel deployment
• 05-kailash-mcp - MCP server integration
• 17-gold-standards - Best practices

Support

For Kaizen-specific questions, invoke:

• kaizen-specialist - Kaizen framework implementation
• testing-specialist - Agent testing strategies
• ``decide-framework skill - When to use Kaizen vs other frameworks