hummbl-governance

HUMMBL = Highly Useful Mental Model Base Language. Base120 (120 mental models across 6 transformation families) is the "Base Language" for reasoning. HUMMBL wraps those models in governance, coordination, and operational infrastructure — making them "Highly Useful."

The Problem

Your AI agent calls an API. The API starts returning errors. Your agent retries, and retries, and retries — burning through hundreds of dollars in API credits before anyone notices. Or worse: your agent decides to "optimize" and starts calling endpoints it was never supposed to touch.

Teams shipping AI agents can face runaway costs, cascading failures, unauthorized actions, and incomplete audit trails. General-purpose agent frameworks emphasize orchestration; their governance coverage varies by framework, version, and deployment, so teams still need to evaluate runtime controls explicitly.

hummbl-governance is a safety and evidence layer. It provides 51 implemented governance primitives — kill switch, circuit breaker, cost governor, delegation tokens, audit log, identity registry, compliance mapping, and more — as a single stdlib-only Python package. It has no third-party runtime dependencies and no required orchestration framework.

The package is classified Alpha in pyproject.toml. Evaluate it against your own risk, security, and production-readiness requirements.

pip install hummbl-governance

30-Second Example

Stop a runaway agent in 5 lines:

from hummbl_governance import KillSwitch, KillSwitchMode, CircuitBreaker, CostGovernor

# Kill switch: 4 graduated halt modes, survives process restart
ks = KillSwitch()
ks.engage(KillSwitchMode.HALT_NONCRITICAL, reason="Error rate > 50%", triggered_by="monitor")
ks.check_task_allowed("data_export")  # {"allowed": False, ...}

# Circuit breaker: auto-opens after 3 failures, auto-recovers
cb = CircuitBreaker(failure_threshold=3, recovery_timeout=10.0)
result = cb.call(lambda: 1 / 0)  # Raises ZeroDivisionError 3x, then fast-fails

# Cost governor: soft cap warns, hard cap blocks
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)
gov.check_budget_status()  # .decision in ("ALLOW", "WARN", "DENY")

Every primitive works standalone. Use KillSwitch without pulling in CostGovernor. Use CircuitBreaker without the audit log. No framework lock-in.

Design scope

The package combines runtime controls, identity and delegation, audit evidence, and engineering mappings in one stdlib-only runtime. This is a description of the package inventory, not a claim that competing projects lack equivalent capabilities. Compare current versions and deployment requirements directly before selecting a governance layer.

Why hummbl-governance?

No dependency conflicts. Uses only Python stdlib at runtime. Installs without runtime dependency resolution overhead and avoids transitive runtime dependencies, reducing dependency supply-chain risk for a library that exists to make agents safer. The package itself, build backend, publishing path, CI, and optional/test tooling remain supply-chain surfaces that require normal review.

Built for multi-agent systems. Delegation tokens with HMAC-SHA256 signing and chain-depth limits. Coordination bus with flock-based mutual exclusion. Kill switch with 4 graduated halt modes. Circuit breakers wrapping external adapters. These are primitives that AI orchestration platforms need at runtime.

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 — evidence you can hand to an auditor or compliance team.

Evidence-first. Package metrics, cross-repo extraction notes, production-use statements, and framework mappings are governed by docs/public-claims.md. Public test counts follow this package's own docs/public-claims.md (the landing claims ledger is a separate, not-yet-refreshed surface): public oss CI reported 3,479 passed and 16 skipped on Python 3.13, full 3.11-3.14 matrix (run 34610754121). That is repository CI evidence, not a production-use receipt.

Sponsorship boundary. The canonical draft sponsorship policy (in the HUMMBL OSS monorepo) does not sell support, priority, favorable findings, or roadmap control. Sponsorship is not active until its documented launch gates pass.

OWASP Top 10 for Agentic Applications. The README includes an engineering mapping to the OWASP Top 10 for Agentic Applications (2026). It is not a third-party certification or attestation. See the mapping below.

Quick Start

pip install hummbl-governance

Integrate with your framework (CrewAI, LangChain, AutoGen, raw OpenAI): See docs/integrations/README.md for copy-paste examples.

Explore all 51 implemented primitives:

git clone https://github.com/hummbl-io/oss.git
cd packages/python/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]

Features

• 51 implemented governance primitives (58 tracked total: 51 implemented, 4 proposed, 3 candidate — see PRIMITIVES.md) covering safety, cost, identity, compliance, reasoning, coordination, physical-AI, execution assurance, and governance Kernel
• 3,479 passed / 16 skipped on public oss CI (Python 3.11-3.14 matrix, coverage collected); see docs/public-claims.md
• Zero third-party Core runtime dependencies -- Python stdlib only, no pip conflicts
• Thread-safe -- all modules use appropriate locking primitives
• Independently importable -- use only the modules you need
• Experimental sandbox lifecycle contracts -- closed schemas and fail-closed bundle validation for profiles, leases, checkpoints, receipts, and host-controlled kill switches; validation is not runtime isolation
• Python 3.13 is the public oss CI version. Package classifiers declare 3.11–3.13; a public 3.11/3.12/3.13 CI matrix is not verified (GAP-003).

governance.yml

Every HUMMBL package ships a governance.yml file declaring its governance posture — safety controls, cost limits, compliance frameworks, and build provenance. This is the first-class metadata artifact for the HUMMBL ecosystem.

# hummbl_governance/governance.yml (shipped in the wheel)
package:
  name: hummbl-governance
  version: 1.4.2
  license: Apache-2.0

safety:
  kill_switch:
    supported: true
    default_mode: DISENGAGED
    modes_available: [DISENGAGED, HALT_NONCRITICAL, HALT_ALL, EMERGENCY]

cost:
  cost_governor:
    supported: true
    soft_cap_usd: 50.0
    hard_cap_usd: 100.0

provenance:
  build_system: github-actions
  trusted_publishing: true
  dependencies: zero
  tests: 3479  # public oss CI passed, 3.11-3.14 matrix; 16 skipped

Read it at runtime (the file is human-readable YAML; parse with PyYAML if available, or read as text):

from pathlib import Path

governance_file = Path(__file__).parent / "governance.yml"
text = governance_file.read_text()
# Parse with yaml.safe_load(text) if PyYAML is installed
# Or just inspect the raw YAML — it's designed to be human-readable

Every HUMMBL PyPI package includes governance.yml inside its wheel, giving consumers a machine- and human-readable statement of the package's declared governance posture.

All 51 Implemented Primitives

Core Primitives (26)

Expansion & Post-v1.2 Primitives (25)

Shipped after the original 26 (v1.3–v1.5); see PRIMITIVES.md for the full canonical reference, including the 4 proposed and 3 candidate primitives not counted here.

Runnable Examples

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

Run them all:

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

OWASP Top 10 for Agentic Applications (2026) Engineering Mapping

The table below maps hummbl-governance primitives to the OWASP Top 10 for Agentic Applications. This is an engineering evidence map, not a third-party certification or attestation. Most rows below link to a primitive and its test suite; ASI04 is a supply-chain posture row for the package runtime surface.

Current posture: 51 implemented primitives, 7 MCP server entry points, and zero third-party Core runtime dependencies. Public oss CI on the full 3.11-3.14 matrix last reported 3,479 passed and 16 skipped (run 34610754121, commit 77854dd), with coverage collected (no percentage published). That figure is repository CI evidence, not a production-use receipt. See docs/public-claims.md.

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 (migrating to the HUMMBL OSS monorepo):

• 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 runtime module uses only Python stdlib (3.11+). There are zero entries in the dependencies list in pyproject.toml. Test dependencies are isolated under project.optional-dependencies.test in pyproject.toml. This means no runtime dependency conflicts, reduced transitive dependency risk, 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

Multi-Agent Example

Delegation tokens and agent identity for multi-agent systems:

from hummbl_governance import DelegationTokenManager, AgentRegistry
from hummbl_governance.delegation import TokenBinding

# Agent registry: identity + trust tiers
registry = AgentRegistry()
registry.register_agent("orchestrator", trust="high")
registry.register_agent("worker-1", trust="medium")
registry.add_alias("orch-1", "orchestrator")
registry.canonicalize("orch-1")  # -> "orchestrator"

# Delegation tokens: HMAC-signed, scoped, chain-depth-limited
mgr = DelegationTokenManager(secret=b"shared-secret")
token = mgr.create_token(
    issuer="orchestrator",
    subject="worker-1",
    ops_allowed=["read", "write"],
    binding=TokenBinding("task-1", "contract-1"),
)
valid, error = mgr.validate_token(token)  # (True, None)

# Worker can now prove it's authorized for "read"/"write" on "task-1"
# Token is tamper-evident — any modification invalidates the signature

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

hummbl-sandbox

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

This server is part of hummbl-governance and is launched through the hummbl-sandbox-mcp entry point. It is not related to the third-party npm package named agent-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 package is part of the HUMMBL cognitive AI architecture. Public packages are consolidating into the HUMMBL OSS monorepo. Related packages:

Links

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

License

Apache 2.0. Copyright 2026 HUMMBL, LLC.

Author

Reuben Bowlby — Founder, HUMMBL

• GitHub: @hummbl-io
• X/Twitter: @ReubenBowlby
• LinkedIn: reuben-bowlby
• Website: hummbl.io