hummbl-governance 1.1.0

Governance primitives for AI agent orchestration: kill switch, circuit breaker, cost governor, delegation tokens, audit log, identity registry, schema validation, coordination bus, compliance mapper, and health probes.

hummbl-governance

hummbl-governance is a Python library that provides 25 governance primitives for AI agent orchestration, including kill switch, circuit breaker, cost governor, delegation tokens, reasoning engine, execution assurance, physical-AI safety, and audit logging. It has zero third-party dependencies (stdlib only), 1031 passing tests, and supports Python 3.11 through 3.14.

Repository health, validation, and stewardship expectations are tracked in docs/REPO_HEALTH.md.

Evidence-readiness review receipt mapping for HUMMBL Legal/Paralegal packet work is tracked in docs/evidence-readiness-review-receipt.md, with the draft JSON schema at hummbl_governance/data/evidence_readiness_review_receipt.schema.json.

pip install hummbl-governance

Or with uv (10-100x faster, 30-43% of new repos use it):

uv pip install hummbl-governance

Quick Start -- 5 Minutes

Run a complete governance example in 60 seconds:

pip install hummbl-governance
python -c "
from hummbl_governance import KillSwitch, KillSwitchMode
ks = KillSwitch()
ks.engage(KillSwitchMode.HALT_NONCRITICAL, reason='Demo', triggered_by='user')
print(ks.check_task_allowed('critical_task'))
"

Explore all 25 primitives:

git clone https://github.com/hummbl-dev/hummbl-governance.git
cd hummbl-governance
python examples/kill_switch_modes.py
python examples/circuit_breaker_wrap.py
python examples/cost_governor.py

Architecture

graph TD
    A[Agent Action] --> B{KillSwitch}
    B -->|ALLOWED| C{CircuitBreaker}
    C -->|CLOSED| D[External API]
    C -->|OPEN| E[Fast Fail]
    D --> F{CostGovernor}
    F -->|UNDER BUDGET| G[Execute]
    F -->|OVER BUDGET| H[Block + Audit]
    G --> I[AuditLog]
    H --> I
    I --> J[ComplianceMapper]
    J --> K[SOC2 / GDPR / NIST Report]

What's New in v0.8.0

• Four new MCP servers — expose 15 previously unexposed governance primitives as 32 JSON-RPC tools. Zero additional dependencies.
  • mcp_identity.py — 10 tools: identity_register, identity_lookup, identity_list, identity_validate, delegation_create, delegation_validate, delegation_check_op, clock_tick, clock_receive, clock_compare (wraps AgentRegistry, DelegationTokenManager, LamportClock)
  • mcp_agent_monitor.py — 11 tools: behavior_record, behavior_snapshot_baseline, behavior_detect_drift, convergence_record, convergence_check, convergence_scores, lifecycle_authorize, lifecycle_status, lineage_record_variant, lineage_get, lineage_drift (wraps BehaviorMonitor, ConvergenceDetector, GovernanceLifecycle, EvolutionLineage)
  • mcp_reasoning.py — reasoning, schema, and contract-net tools (wraps ReasoningEngine, SchemaValidator, ContractNetManager)
  • mcp_physical.py — 6 tools: kinematic_check_motion, kinematic_get_limits, kinematic_scaled_velocity, phri_check_safety, phri_get_config, phri_batch_check (wraps KinematicGovernor, pHRISafetyMonitor)
• 4 new CLI entry points: hummbl-identity-mcp, hummbl-agent-monitor-mcp, hummbl-reasoning-mcp, hummbl-physical-mcp
• 143 new tests — 927 total (784 → 927)

v0.7.0 highlights

• Three MCP servers -- expose all governance primitives as Model Context Protocol tools via stdio JSON-RPC. Zero additional dependencies.
  • mcp_server.py -- 10 tools: governance_status, kill_switch_status/engage/disengage, circuit_breaker_status, cost_budget_check/record_usage, audit_query, compliance_report, health_check
  • mcp_compliance.py -- 5 tools: nist_map_controls, soc2_assess, iso_crosswalk, stride_analysis, compliance_evidence_export
  • mcp_sandbox.py -- 5 tools: sandbox_create/check/validate_output/status/destroy
• 84 new tests covering all MCP tool handlers and protocol-level JSON-RPC round-trips (30 + 25 + 29)
• 784 total tests (700 → 784)

v0.6.0 highlights

• NIST AI RMF report (generate_nist_rmf_report()) -- Maps governance traces to the four core functions: GOVERN, MAP, MEASURE, MANAGE. Evidence-backed controls aligned to NIST AI 100-1 (2023).
• EU AI Act report (generate_eu_ai_act_report()) -- Maps governance traces to Articles 9, 10, 12, 13, 14, 17 for High-Risk AI (Annex III). Includes human_initiated flag on KILLSWITCH events for Art.14 human oversight evidence.
• CHANGELOG.md -- full version history from v0.1.0.
• 673 tests -- 36 new tests covering all NIST RMF and EU AI Act mappings.

v0.5.0 highlights

• LamportClock hardening -- causal integrity checks for distributed audit logs; epoch-aware state handling across agents.
• EvolutionLineage -- in-memory lineage tracking for eAI variants; VariantRecord, ModificationRecord, EvolutionDriftReport.
• FailureModes catalog -- structured FailureModeRecord and ErrorRecord taxonomy; all_failure_modes(), classify_subclass(), get_errors_for_fm().
• Errors taxonomy -- HummblError, FailureMode, fm_to_errors() as top-level exports.

v0.4.0 highlights

• KinematicGovernor -- deterministic motion constraints (velocity, force, jerk) for physical-AI safety.
• pHRISafetyMonitor -- graduated pHRI safety modes (NORMAL/CAUTION/EMERGENCY).
• Execution Assurance Layer (EAL) -- Arbiter-verified code quality in execution receipts (E_CODE_QUALITY_FAIL).
• ReasoningEngine -- structured governance reasoning with rule application, conflict detection, and decision tracing.
• ValidationError -- top-level export from hummbl_governance.

Usage Example

from hummbl_governance import KillSwitch, KillSwitchMode, CircuitBreaker, CostGovernor

ks = KillSwitch()
ks.engage(KillSwitchMode.HALT_ALL, reason="Budget exceeded", triggered_by="cost_governor")
print(ks.check_task_allowed("data_export"))  # {"allowed": False, ...}

cb = CircuitBreaker(failure_threshold=3, recovery_timeout=10.0)
result = cb.call(my_function, arg1, arg2)  # Opens after 3 failures

gov = CostGovernor(":memory:", soft_cap=50.0, hard_cap=100.0)
gov.record_usage(provider="anthropic", model="claude-4", tokens_in=1000, tokens_out=500, cost=0.015)
status = gov.check_budget_status()  # status.decision in ("ALLOW", "WARN", "DENY")

Features

• 25 governance primitives covering safety, cost, identity, compliance, reasoning, coordination, physical-AI, and execution assurance
• 1031 tests with full coverage across all modules
• Zero dependencies -- Python stdlib only, no pip conflicts
• Thread-safe -- all modules use appropriate locking primitives
• Independently importable -- use only the modules you need
• Python 3.11 - 3.14 supported and tested

All 25 Primitives

Module	Description
kill_switch	Emergency halt system with 4 graduated modes (DISENGAGED, HALT_NONCRITICAL, HALT_ALL, EMERGENCY)
circuit_breaker	Automatic failure detection and recovery across 3 states (CLOSED, HALF_OPEN, OPEN)
cost_governor	Budget tracking with soft/hard caps and ALLOW/WARN/DENY decisions
delegation	HMAC-SHA256 signed capability tokens for agent delegation chains
audit_log	Append-only JSONL governance audit log with rotation and retention
identity	Agent registry with configurable aliases, trust tiers, and canonicalization
schema_validator	Stdlib-only JSON Schema validator (Draft 2020-12 subset) with top-level ValidationError export
coordination_bus	Append-only TSV message bus with flock locking and HMAC signing
compliance_mapper	Map governance traces to SOC2, GDPR, and OWASP controls
health_probe	Composable health probe framework with latency tracking
output_validator	Rule-based content validation for agent outputs (PII detection, injection detection, blocklists)
capability_fence	Soft sandbox enforcing capability boundaries per agent role
stride_mapper	Map agent interactions to STRIDE threat categories with mitigation suggestions
lifecycle	NIST AI RMF orchestrator composing kill switch, circuit breaker, cost governor, and audit log
contract_net	Market-based task allocation protocol for multi-agent systems
convergence_guard	Detect instrumental convergence patterns in agent behavior
reward_monitor	Behavioral drift and reward gaming detector
lamport_clock	Hardened logical clock for causal ordering of distributed agent events (v0.5.0)
reasoning	Structured governance reasoning engine with rule application, conflict detection, and decision tracing
eal	Execution Assurance Layer -- Arbiter-verified code quality in execution receipts
physical_governor	Kinematic constraints and pHRI safety modes for physical-AI deployments
errors	HummblError, FailureMode, and fm_to_errors() -- typed error taxonomy
failure_modes	Structured failure mode catalog with classification and error cross-reference
evolution_lineage	In-memory lineage tracking for eAI variants with drift detection
ValidationError	Top-level exception for schema validation failures (exported from schema_validator)

25 Runnable Examples

Every primitive has a standalone example in examples/. Each runs with just python examples/<name>.py -- no setup, no config.

Example	Primitive	What it shows
kill_switch_modes.py	KillSwitch	4 graduated halt modes
circuit_breaker_wrap.py	CircuitBreaker	3-state failure recovery
cost_governor.py	CostGovernor	Soft/hard budget caps
delegate_task.py	DelegationToken	HMAC-signed agent delegation
audit_log.py	AuditLog	Append-only governance log
agent_registry.py	AgentRegistry	Identity + trust tiers
schema_validator.py	SchemaValidator	Stdlib JSON Schema validation
compliance_mapper.py	ComplianceMapper	SOC2/GDPR evidence mapping
health_probe.py	HealthProbe	Composable health checks
output_validator.py	OutputValidator	Content safety filtering
capability_fence.py	CapabilityFence	Role-based capability boundaries
stride_mapper.py	StrideMapper	STRIDE threat analysis
lifecycle.py	GovernanceLifecycle	NIST AI RMF orchestration
contract_net.py	ContractNetManager	Multi-agent task allocation
convergence_guard.py	ConvergenceGuard	Instrumental convergence detection
behavior_monitor.py	BehaviorMonitor	Behavioral drift detection
lamport_clock.py	LamportClock	Distributed causal ordering
reasoning.py	ReasoningEngine	Structured governance reasoning
eal.py	EAL	Execution assurance
physical_governor.py	KinematicGovernor	Physical-AI safety limits
errors.py	HummblError	Typed error taxonomy
failure_modes.py	FailureMode	Failure classification
evolution_lineage.py	EvolutionLineage	eAI variant lineage tracking
agent_runner.py	--	End-to-end agent with governance stack
failure_injection.py	--	Chaos testing with kill switch + circuit breaker

Run them all:

for f in examples/*.py; do echo "=== $f ==="; python "$f"; done

Why hummbl-governance?

No dependency conflicts. hummbl-governance uses only Python stdlib. It installs in under 1 second and never conflicts with your existing packages. Every governance module is independently importable -- use KillSwitch without pulling in CostGovernor.

Built for multi-agent systems. The library provides primitives that AI orchestration platforms actually need: delegation tokens with HMAC-SHA256 signing, a coordination bus with mutual exclusion, kill switch with 4 graduated halt modes, and circuit breakers wrapping external adapters.

Compliance-aware by design. The compliance_mapper maps governance events to SOC2, GDPR, and OWASP controls. The stride_mapper produces STRIDE threat analysis for agent interactions. These modules generate audit evidence, not just runtime safety.

Production-tested. The governance primitives were extracted from founder-mode, a multi-runtime AI orchestration platform with 15,600+ tests and 14 CI workflows across its full surface. The governance layer extracted here has 1031 dedicated tests and runs daily in production.

hummbl-governance vs Alternatives

Capability	hummbl-governance	Raw stdlib	LangChain Guardrails	CrewAI Guardrails
Zero dependencies	Yes	Yes	No (requires langchain)	No (requires crewai)
Kill switch (graduated modes)	4 modes	DIY	No	No
Circuit breaker	3 states	DIY	No	No
Cost governance (budget caps)	Soft + hard caps	DIY	No	No
Delegation tokens (HMAC signed)	Yes	DIY	No	No
Append-only audit log	Yes	DIY	Partial	No
Agent identity registry	Yes	DIY	No	No
STRIDE threat mapping	Yes	No	No	No
SOC2/GDPR/OWASP compliance mapping	Yes	No	No	No
JSON Schema validation (stdlib)	Draft 2020-12	No	Requires jsonschema	Requires pydantic
Governance reasoning engine	Yes	No	No	No
Thread-safe	Yes	Varies	Varies	Varies
Modules work standalone	Yes	N/A	No (framework lock-in)	No (framework lock-in)

OWASP Top 10 for Agentic Applications (2026) Coverage

hummbl-governance addresses all 10 risks in the OWASP Top 10 for Agentic Applications. Every row below links to the primitive and its test suite.

OWASP Risk	Primitive(s)	Tests	How
ASI01 Agent Goal Hijack	KillSwitch	27	4-mode graduated shutdown (DISENGAGED → EMERGENCY). Survives process restart. Stops hijacked agents mid-execution.
ASI02 Tool Misuse	CapabilityFence	27	Allowlist/blocklist enforcement per tool. Agents cannot invoke tools outside their granted capabilities.
ASI03 Identity & Privilege Abuse	DelegationTokenManager, AgentRegistry	16 + 26	HMAC-signed scoped tokens with chain-depth limits. Identity registry with trust tiers and alias canonicalization.
ASI04 Supply Chain	Zero dependencies	—	Stdlib-only. No transitive dependencies to compromise. pip audit finds nothing because there is nothing to audit.
ASI05 Unexpected Code Execution	OutputValidator, InjectionDetector	49	Prompt injection detection, blocked-term filtering, and content validation before agent output reaches downstream systems.
ASI06 Memory & Context Poisoning	BusWriter, AuditLog	63 + 17	Append-only governance bus with content hashing. Tamper-evident audit log. Poisoned entries are detectable.
ASI07 Insecure Inter-Agent Comms	LamportClock, ContractNetManager	20 + 19	Hardened logical clocks for causal ordering. Contract Net protocol for structured multi-agent task allocation with bid verification.
ASI08 Cascading Failures	CircuitBreaker, HealthProbe	17 + 30	CLOSED/HALF_OPEN/OPEN state machine isolates failing components. Health probes detect degradation before cascade.
ASI09 Human-Agent Trust Exploitation	ReasoningEngine, ComplianceMapper	7 + 34	Structured decision traces explain why a governance decision was made. Compliance mapping to NIST/ISO provides external validation anchor.
ASI10 Rogue Agents	BehaviorMonitor, GovernanceLifecycle	20 + 17	Jensen-Shannon divergence detects behavioral drift from baseline. Lifecycle FSM enforces PROVISIONED → ACTIVE → SUSPENDED → DECOMMISSIONED transitions.

Total: 1031 tests across 25 primitives + 7 MCP servers. 10/10 OWASP coverage. Zero dependencies.

For the formal governance primitive underlying all 10 mitigations, see The Governance Tuple (Bowlby, 2026).

Research

The evidence base behind hummbl-governance is documented in the AI Slop Crisis research corpus:

• Why Libraries, Not Platforms -- the architectural thesis behind stdlib-only, independently importable governance primitives
• Vendor Comparison Table -- how hummbl-governance compares to platform-locked alternatives across dependency count, modularity, and compliance coverage

Newsletter

Subscribe to the HUMMBL Slop Tracker for monthly AI governance intelligence: hummbl.substack.com

Read Issue #1 for the inaugural edition.

FAQ

How do I add a kill switch to my AI agent system?

Install hummbl-governance and use the KillSwitch class. It provides 4 graduated modes: DISENGAGED (normal operation), HALT_NONCRITICAL (stop non-essential tasks), HALT_ALL (stop everything except monitoring), and EMERGENCY (immediate full shutdown). Call ks.check_task_allowed("task_name") before each agent action.

from hummbl_governance import KillSwitch, KillSwitchMode
ks = KillSwitch()
ks.engage(KillSwitchMode.HALT_NONCRITICAL, reason="High error rate", triggered_by="monitor")

How do I track AI API costs and enforce budget limits?

Use CostGovernor with soft and hard caps. Record each API call with record_usage(), then call check_budget_status() to get an ALLOW, WARN, or DENY decision. The soft cap triggers warnings; the hard cap blocks further spending.

from hummbl_governance import CostGovernor
gov = CostGovernor(":memory:", soft_cap=50.0, hard_cap=100.0)
gov.record_usage(provider="openai", model="gpt-4", tokens_in=500, tokens_out=200, cost=0.02)

How do I implement delegation tokens for multi-agent AI systems?

Use DelegationTokenManager to create HMAC-SHA256 signed tokens that grant specific operations to specific agents. Tokens are scoped by issuer, subject, allowed operations, and an optional binding to a task and contract. Validate tokens before executing delegated actions.

from hummbl_governance import DelegationTokenManager
from hummbl_governance.delegation import TokenBinding
mgr = DelegationTokenManager(secret=b"shared-secret")
token = mgr.create_token(issuer="orchestrator", subject="worker", ops_allowed=["read", "write"],
                         binding=TokenBinding("task-1", "contract-1"))
valid, error = mgr.validate_token(token)

Does hummbl-governance work without any third-party packages?

Yes. Every module uses only Python stdlib (3.11+). There are zero entries in the dependencies list in pyproject.toml. Test dependencies (pytest) are isolated in [test] extras. This means no dependency conflicts, no supply chain risk from transitive dependencies, and fast installs.

How do I generate compliance evidence for SOC2 or GDPR from my AI system?

Use ComplianceMapper to map governance audit log entries to compliance framework controls. Pass your AuditLog entries through the mapper to produce a ComplianceReport that links each governance event to the relevant SOC2, GDPR, or OWASP control. Use StrideMapper for threat-level analysis of agent interactions.

from hummbl_governance import ComplianceMapper, AuditLog
mapper = ComplianceMapper()
report = mapper.map_events(audit_entries)  # Returns ComplianceReport with control mappings

Extended Quick Start

from hummbl_governance import (
    KillSwitch, KillSwitchMode,
    CircuitBreaker,
    CostGovernor,
    DelegationToken, DelegationTokenManager,
    AuditLog,
    AgentRegistry,
    SchemaValidator,
)

# Kill Switch
ks = KillSwitch()
ks.engage(KillSwitchMode.HALT_ALL, reason="Budget exceeded", triggered_by="cost_governor")
result = ks.check_task_allowed("data_export")
# result["allowed"] == False

# Circuit Breaker
cb = CircuitBreaker(failure_threshold=3, recovery_timeout=10.0)
result = cb.call(some_function, arg1, arg2)

# Cost Governor
gov = CostGovernor(":memory:", soft_cap=50.0, hard_cap=100.0)
gov.record_usage(provider="anthropic", model="claude-4", tokens_in=1000, tokens_out=500, cost=0.015)
status = gov.check_budget_status()
# status.decision in ("ALLOW", "WARN", "DENY")

# Delegation Tokens
mgr = DelegationTokenManager(secret=b"my-secret")
from hummbl_governance.delegation import TokenBinding
token = mgr.create_token(
    issuer="orchestrator", subject="worker",
    ops_allowed=["read"], binding=TokenBinding("task-1", "contract-1"),
)
valid, error = mgr.validate_token(token)

# Agent Registry
registry = AgentRegistry()
registry.register_agent("orchestrator", trust="high")
registry.add_alias("orch-1", "orchestrator")
registry.canonicalize("orch-1")  # -> "orchestrator"

MCP Servers

hummbl-governance ships three Model Context Protocol servers that expose governance primitives as tools to any MCP-compatible client (Claude Code, Claude Desktop, etc.).

hummbl-governance (core)

{
  "mcpServers": {
    "hummbl-governance": {
      "command": "python",
      "args": ["/path/to/hummbl-governance/mcp_server.py"],
      "env": {
        "GOVERNANCE_STATE_DIR": "/path/to/state"
      }
    }
  }
}

10 tools: governance_status, kill_switch_status, kill_switch_engage, kill_switch_disengage, circuit_breaker_status, cost_budget_check, cost_record_usage, audit_query, compliance_report, health_check

hummbl-compliance

{
  "mcpServers": {
    "hummbl-compliance": {
      "command": "python",
      "args": ["/path/to/hummbl-governance/mcp_compliance.py"],
      "env": {
        "GOVERNANCE_AUDIT_DIR": "/path/to/audit"
      }
    }
  }
}

5 tools: nist_map_controls, soc2_assess, iso_crosswalk, stride_analysis, compliance_evidence_export

agent-sandbox

{
  "mcpServers": {
    "agent-sandbox": {
      "command": "python",
      "args": ["/path/to/hummbl-governance/mcp_sandbox.py"],
      "env": {
        "SANDBOX_STATE_DIR": "/path/to/sandbox"
      }
    }
  }
}

5 tools: sandbox_create, sandbox_check, sandbox_validate_output, sandbox_status, sandbox_destroy

All three servers use stdio JSON-RPC and have zero third-party dependencies.

Design Principles

• Zero third-party runtime dependencies -- stdlib only (Python 3.11+)
• Thread-safe -- all modules use appropriate locking
• Configurable -- no hardcoded agent names or paths
• Independently importable -- each module works standalone

Development

python -m venv .venv && source .venv/bin/activate
pip install -e ".[test]"
python -m pytest tests/ -v

HUMMBL Ecosystem

This repo is part of the HUMMBL cognitive AI architecture. Related repos:

Repo	Purpose
base120	Deterministic cognitive framework -- 120 mental models across 6 transformations
mcp-server	Model Context Protocol server for Base120 integration
arbiter	Agent-aware code quality scoring and attribution
agentic-patterns	Stdlib-only safety patterns for agentic AI systems
governed-iac-reference	Reference architecture for governed infrastructure-as-code

Links

• PyPI
• GitHub
• hummbl.io
• Linktree
• HUMMBL Slop Tracker (Substack)

License

Apache 2.0. Copyright 2026 HUMMBL, LLC.