hummbl-governance 0.5.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 20 governance primitives for AI agent orchestration, including kill switch, circuit breaker, cost governor, delegation tokens, reasoning engine, and audit logging. It has zero third-party dependencies (stdlib only), 583 passing tests, and supports Python 3.11 through 3.14.

pip install hummbl-governance

What's New in v0.3.0 (on PyPI, GitHub release tag pending)

• ReasoningEngine -- structured governance reasoning with rule application, conflict detection, and decision tracing. Enables agents to explain why a governance decision was made, not just what the decision was.
• ValidationError -- now a top-level export from hummbl_governance, making it easier to catch and handle schema validation failures without importing from submodules.

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

• 20 governance primitives covering safety, cost, identity, compliance, reasoning, and coordination
• 583 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 20 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	Logical clock for causal ordering of distributed agent events
reasoning	Structured governance reasoning engine with rule application, conflict detection, and decision tracing
ValidationError	Top-level exception for schema validation failures (exported from schema_validator)

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. All 20 primitives were extracted from founder-mode, a multi-runtime AI orchestration platform with 15,600+ tests and 14 CI workflows. The governance layer 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	18 + 19	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: 583 tests across 20 primitives. 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"

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.