{"id":47307392,"url":"https://github.com/hummbl-dev/hummbl-governance","last_synced_at":"2026-03-17T08:49:42.274Z","repository":{"id":338276566,"uuid":"1130741513","full_name":"hummbl-dev/hummbl-governance","owner":"hummbl-dev","description":"governance repo for HUMMBL","archived":false,"fork":false,"pushed_at":"2026-03-03T11:12:03.000Z","size":78,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-03-03T14:25:08.296Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/hummbl-dev.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","support":null,"governance":"governance/CAES_CANONICAL.sha256","roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-01-09T00:13:10.000Z","updated_at":"2026-03-03T11:12:07.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/hummbl-dev/hummbl-governance","commit_stats":null,"previous_names":["hummbl-dev/hummbl-governance"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/hummbl-dev/hummbl-governance","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hummbl-dev%2Fhummbl-governance","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hummbl-dev%2Fhummbl-governance/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hummbl-dev%2Fhummbl-governance/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hummbl-dev%2Fhummbl-governance/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/hummbl-dev","download_url":"https://codeload.github.com/hummbl-dev/hummbl-governance/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hummbl-dev%2Fhummbl-governance/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":30619228,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-03-17T08:10:05.930Z","status":"ssl_error","status_checked_at":"2026-03-17T08:10:04.972Z","response_time":56,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2026-03-17T08:49:41.760Z","updated_at":"2026-03-17T08:49:42.265Z","avatar_url":"https://github.com/hummbl-dev.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# hummbl-governance\n\n**Agent Runtime Governance** -- five battle-tested primitives for building AI agents that govern themselves.\n\n*Ship agents that govern themselves.*\n\n---\n\n## What is this?\n\n`hummbl-governance` provides five standalone governance primitives extracted from production agent infrastructure. Each primitive is stdlib-only (zero third-party dependencies), thread-safe where noted, and designed to compose with any agent framework.\n\n| Primitive | Purpose |\n|-----------|---------|\n| **DelegationToken** | HMAC-SHA256 signed capability tokens for agent-to-agent delegation |\n| **DelegationContext** | DCTX state machine with chain depth enforcement and budget tracking |\n| **GovernanceBus** | Append-only JSONL audit log with rotation and retention |\n| **CircuitBreaker** | Automatic failure detection and recovery (CLOSED / OPEN / HALF_OPEN) |\n| **KillSwitch** | Graduated emergency halt system (DISENGAGED / HALT_NONCRITICAL / HALT_ALL / EMERGENCY) |\n\n## Installation\n\n```bash\npip install hummbl-governance\n```\n\nRequires Python 3.11+. Zero runtime dependencies.\n\n## Quickstart\n\n### DelegationToken\n\nHMAC-SHA256 signed tokens that bind agent capabilities to specific tasks and contracts. Enforce least-privilege delegation between agents.\n\n```python\nfrom hummbl_governance import DelegationToken\n\nmanager = DelegationToken.Manager(secret=b\"your-signing-secret\")\n\n# Create a scoped token\ntoken = manager.create_token(\n    issuer=\"orchestrator\",\n    subject=\"worker-agent\",\n    ops_allowed=[\"read_file\", \"write_file\"],\n    binding=DelegationToken.Binding(task_id=\"task-123\", contract_id=\"contract-456\"),\n    expiry_minutes=120,\n)\n\n# Validate before use\nis_valid, error_code = manager.validate_token(token)\nassert is_valid\n\n# Enforce least privilege\nis_allowed, error = manager.check_least_privilege(token, \"read_file\")\nassert is_allowed\n```\n\n### GovernanceBus\n\nAppend-only audit log for governance events. Supports daily rotation, configurable retention, and query by intent or task.\n\n```python\nfrom hummbl_governance import GovernanceBus\n\nbus = GovernanceBus(base_dir=\"/var/log/governance\", retention_days=180)\n\n# Append an audit entry\nsuccess, error = bus.append(\n    intent_id=\"intent-abc\",\n    task_id=\"task-123\",\n    tuple_type=\"DCT\",\n    tuple_data={\"action\": \"delegated\", \"to\": \"worker-agent\"},\n)\n\n# Query by intent\nfor entry in bus.query_by_intent(\"intent-abc\"):\n    print(f\"{entry.timestamp}: {entry.tuple_type} -- {entry.tuple_data}\")\n\n# Query by task\nfor entry in bus.query_by_task(\"task-123\"):\n    print(entry.to_jsonl())\n```\n\n### CircuitBreaker\n\nClassic three-state circuit breaker for wrapping external service calls. Tracks consecutive failures and auto-recovers after a configurable timeout.\n\n```python\nfrom hummbl_governance import CircuitBreaker, CircuitBreakerOpen\n\ncb = CircuitBreaker(failure_threshold=3, recovery_timeout=30.0)\n\ntry:\n    result = cb.call(external_api_call, arg1, arg2)\nexcept CircuitBreakerOpen:\n    result = fallback_value\n\n# State inspection\nprint(cb.state)          # CircuitBreakerState.CLOSED\nprint(cb.failure_count)  # 0\n\n# State change notifications\ndef on_change(old_state, new_state):\n    print(f\"Circuit breaker: {old_state.name} -\u003e {new_state.name}\")\n\ncb = CircuitBreaker(on_state_change=on_change)\n```\n\n### KillSwitch\n\nGraduated emergency halt with four modes. Supports critical task exemptions, subscriber notifications, and persistent state.\n\n```python\nfrom hummbl_governance import KillSwitch, KillSwitchMode\n\nks = KillSwitch()\n\n# Engage with graduated response\nks.engage(\n    mode=KillSwitchMode.HALT_NONCRITICAL,\n    reason=\"Budget threshold exceeded\",\n    triggered_by=\"cost_governor\",\n)\n\n# Check if a task is allowed\nresult = ks.check_task_allowed(\"briefing_generation\")\nif not result[\"allowed\"]:\n    print(f\"Blocked: {result['reason']}\")\n\n# Critical tasks continue even in HALT_NONCRITICAL\nresult = ks.check_task_allowed(\"safety_monitoring\")\nassert result[\"allowed\"]  # Critical tasks are exempt\n\n# Disengage when resolved\nks.disengage(triggered_by=\"admin\", reason=\"Budget replenished\")\n\n# Persistent state (survives restarts)\nks = KillSwitch(state_dir=\"/var/lib/governance\")\nks.engage(KillSwitchMode.HALT_ALL, \"Incident\", \"system\")\n# State written to /var/lib/governance/kill_switch_state.json\n\n# Load from persisted state\nks = KillSwitch.load_from_file(\"/var/lib/governance\")\nprint(ks.mode)  # KillSwitchMode.HALT_ALL\n```\n\n## Feature Flags\n\nDelegationToken and GovernanceBus support the `ENABLE_IDP` environment variable:\n\n- `ENABLE_IDP=true` (default): Full enforcement -- tokens are validated, audit entries are written\n- `ENABLE_IDP=false`: Bypass mode -- all tokens pass validation, no audit entries written\n\nThis allows gradual rollout in existing systems.\n\n## Design Principles\n\n1. **Stdlib only.** Zero third-party runtime dependencies. These primitives run anywhere Python runs.\n2. **Thread safe.** CircuitBreaker and GovernanceBus use internal locks for concurrent access. KillSwitch documents its threading model.\n3. **Fail safe.** Subscriber errors are swallowed. Persistence failures do not crash the system. Invalid state files result in clean defaults.\n4. **Composable.** Each primitive works independently. Combine them to build governance layers for any agent architecture.\n\n## License\n\nApache 2.0. See [LICENSE](LICENSE).\n\n## Links\n\n- Homepage: [hummbl.io](https://hummbl.io)\n- Repository: [github.com/hummbl-dev/hummbl-governance](https://github.com/hummbl-dev/hummbl-governance)\n- Issues: [github.com/hummbl-dev/hummbl-governance/issues](https://github.com/hummbl-dev/hummbl-governance/issues)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhummbl-dev%2Fhummbl-governance","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fhummbl-dev%2Fhummbl-governance","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhummbl-dev%2Fhummbl-governance/lists"}