Python · open source · runs in your environment

Put governance in the path.

Start with one agent action. Define who may perform it, place the decision before execution, and keep evidence of the result.

The governed path

Authority before action. Evidence after.

HUMMBL supplies composable primitives. Your application decides where to place them and which actions must pass through them.

  1. 01

    Define authority

    Bind the agent to named operations, resources, a task, and a contract. Validate those expectations before execution.

    Inspect DelegationTokenManager ↗
  2. 02

    Mediate execution

    Route the action through the policy decision it must obey. Add containment primitives such as a kill switch, circuit breaker, or cost governor where the system can actually stop the call.

    Browse the primitive inventory ↗
  3. 03

    Preserve evidence

    Record the contract, delegated context, outcome, and output hash in an authenticated receipt. Verify the record and its chain inside the shared-secret trust domain.

    Inspect ReceiptEngine ↗

Native quickstart

One complete governed lifecycle.

This example composes authorization, execution, evidence binding, receipt validation, and chain verification explicitly against the published package API.

  1. Authorize
  2. Execute
  3. Record
governed_action.py
import hashlib
import secrets
from pathlib import Path
from tempfile import TemporaryDirectory

from hummbl_governance import DelegationTokenManager, ReceiptEngine

secret = secrets.token_bytes(32)  # Load a stable key in production.
contract = {"id": "summary-v1", "operations": ["summarize"]}
task_id = "task-42"

# AUTHORIZE — issue and validate scoped delegated authority.
tokens = DelegationTokenManager(secret)
dct = tokens.issue(
    issuer="orchestrator",
    subject="summarizer-agent",
    operations=contract["operations"],
    resources=["docs/report.md"],
    task_id=task_id,
    contract_id=contract["id"],
)
allowed, reason = tokens.validate_token(
    dct,
    expected_task_id=task_id,
    expected_contract_id=contract["id"],
    expected_subject="summarizer-agent",
)
if not allowed:
    raise PermissionError(f"Delegated authority denied: {reason}")

# EXECUTE — your runtime performs the authorized action.
source = "Bounded authority makes agent actions reviewable."
result = " ".join(source.split()[:5])

# RECORD + BIND + VERIFY — authenticate the tuple and verify its chain.
with TemporaryDirectory() as state:
    receipts = ReceiptEngine(Path(state), signing_secret=secret)
    receipt = receipts.create_and_store(
        agent_id=dct.subject,
        action_type="summarize",
        payload={
            "contract": contract,
            "dct": dct.to_dict() | {"signature": dct.signature},
            "evidence": {
                "outcome": "completed",
                "output_sha256": hashlib.sha256(result.encode()).hexdigest(),
            },
        },
    )
    if not receipts.validate(receipt):
        raise RuntimeError("Receipt authentication failed")
    chain_valid, chain_reason = receipts.verify_chain(dct.subject)
    if not chain_valid:
        raise RuntimeError(f"Receipt chain failed: {chain_reason}")

Version 1.4.2 exposes composable primitives rather than a dedicated GovernanceTuple object or one-call lifecycle. Use a stable, protected secret and durable receipt storage in a real deployment.

Place the control where it matters

Choose the boundary from the failure.

Begin with the action that could cause harm, then select the smallest controls that can prevent, contain, or explain it.

Authority drift

An agent acts outside its assigned task or resource.

  • DelegationTokenManager
  • IdentityRegistry
  • CapabilityMap

Runaway execution

A loop, dependency, or spend path stops behaving.

  • KillSwitch
  • CircuitBreaker
  • CostGovernor

Unclear outcome

A reviewer cannot reconstruct what happened.

  • ReceiptEngine
  • AuditLog
  • EvidenceBundle

Continue from here

Pick the surface that matches the job.

Implementation boundary

The library cannot place itself.

Route completeness
Only mediated actions are governed. Inventory every alternate path, retry, side effect, and privileged escape hatch.
Secrets and identity
Your system must protect signing material and establish the identities represented by delegated context.
Operations
Monitoring, durable storage, incident response, and recovery remain deployment responsibilities.
Compliance
Technical evidence can support an assessment. It does not determine legal applicability or confer certification.

Need another set of eyes?

Map the boundary before the sprint.

Bring an architecture, threat model, or agent workflow. HUMMBL can help identify the control points and the evidence they should leave.