constitutional-agent 0.1.0__tar.gz

constitutional_agent-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Cognitive Thought Engine LLC
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

constitutional_agent-0.1.0/PKG-INFO

@@ -0,0 +1,356 @@
+Metadata-Version: 2.4
+Name: constitutional-agent
+Version: 0.1.0
+Summary: WHY-layer constitutional governance for autonomous AI agents
+License: MIT
+Project-URL: Homepage, https://github.com/CognitiveThoughtEngine/constitutional-agent-governance
+Project-URL: Documentation, https://github.com/CognitiveThoughtEngine/constitutional-agent-governance#readme
+Project-URL: Repository, https://github.com/CognitiveThoughtEngine/constitutional-agent-governance
+Project-URL: Issues, https://github.com/CognitiveThoughtEngine/constitutional-agent-governance/issues
+Keywords: ai,agents,governance,constitutional,llm,autonomy
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: pydantic<3,>=2.6
+Requires-Dist: pyyaml<7,>=6.0
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0; extra == "dev"
+Requires-Dist: pytest-cov>=4.0; extra == "dev"
+Requires-Dist: mypy>=1.8; extra == "dev"
+Requires-Dist: ruff>=0.3; extra == "dev"
+Dynamic: license-file
+
+# constitutional-agent
+
+[![Tests](https://github.com/CognitiveThoughtEngine/constitutional-agent-governance/actions/workflows/tests.yml/badge.svg)](https://github.com/CognitiveThoughtEngine/constitutional-agent-governance/actions/workflows/tests.yml)
+[![PyPI](https://img.shields.io/pypi/v/constitutional-agent)](https://pypi.org/project/constitutional-agent/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
+[![Python 3.11+](https://img.shields.io/badge/python-3.11+-blue.svg)](https://www.python.org/downloads/)
+
+**The governance layer your AI agent is missing.**
+
+```bash
+pip install constitutional-agent
+```
+
+---
+
+## The Problem: WHO and HOW Are Solved. WHY Is Not.
+
+AI agent governance has three structurally distinct layers. Most organizations have the first two. Almost none have the third.
+
+| Tier | Question | Tools | What It Misses |
+|------|----------|-------|----------------|
+| **WHO** | Is this agent authorized to act? | Microsoft Entra Agent ID, Okta, AWS IAM, Glasswing | An authorized agent making harmful, irrational, or unconstitutional decisions |
+| **HOW** | Is this action permitted by policy? | Microsoft AGT, NeMo Guardrails, LangChain, OWASP Agentic AI | Structurally bad decisions that are technically policy-compliant; scenarios no policy covers |
+| **WHY** | Does this decision align with our constitutional principles? | **This library** | — |
+
+WHO governance gets the agent through the door. HOW governance enforces the rules written by administrators. Neither asks whether the agent's decision is *right* — aligned with the organization's mission, economic survival, and constitutional values. That's the WHY layer. It has been missing from every open-source governance toolkit until now.
+
+---
+
+## Case Study: Four Failures Constitutional Governance Would Have Caught
+
+On April 7, 2026, a developer published one of the most honest accounts of autonomous agent failure on the internet: [My AI agent finally made money. It took 200 runs and 41 days.](https://dev.to/agenthustler/my-ai-agent-finally-made-money-it-took-200-runs-and-41-days-36jk)
+
+$6.74 earned. 200 runs. 41 days. Four failure modes that constitutional governance would have caught.
+
+| Failure | Duration | Constitutional Gate | Caught By |
+|---------|---------|-------------------|-----------|
+| Broken Lightning wallet — accepted payments, never settled | Weeks | HC-11 + EpistemicGate | `hours_since_settlement_confirmation > 24` → STOP |
+| Mispriced Lightning actors at $0.00005 (wrong by orders of magnitude) | ~30 runs | EpistemicGate | `assumption_volatility` high — external verification required before execution |
+| Shadow-banned by HN, kept posting for 30 runs | 30+ runs | RiskGate | `channel_health = 0%` → FAIL — stop spending on dead channels |
+| Strategy locked on MCP servers for 30 runs, zero conversion | 30+ runs | ConstitutionalGate | `lessons_learned_weekly = 0` → FAIL — document what you learned or stop |
+
+Constitutional governance doesn't guarantee faster revenue. It guarantees you don't spend 30 runs posting into a shadow-banned account after week 2.
+
+**Full audit:** [examples/agenthustler_audit.md](examples/agenthustler_audit.md)
+
+---
+
+## Quick Start
+
+```python
+from constitutional_agent import Constitution
+
+constitution = Constitution.from_defaults()
+
+result = constitution.evaluate({
+    # Hard constraint context
+    "failing_tests": 0,
+    "hours_since_last_execution": 4,
+    "gate_override_without_amendment": False,
+
+    # Epistemic: is the agent's reasoning sound?
+    "verification_pass_rate": 0.85,
+    "uncertainty_disclosure_rate": 0.90,
+
+    # Risk: are outbound actions safe?
+    "channel_health": 0.92,
+    "security_critical_events": 0,
+
+    # Economic: is the business healthy?
+    "stage": "pre_revenue",
+    "runway_months": 8.5,
+    "user_return_rate": 0.22,
+
+    # Constitutional: is the agent learning?
+    "lessons_learned_weekly": 3,
+    "amendments_per_month": 2,
+})
+
+if result.system_state.value == "FREEZE":
+    print(f"BLOCKED: {result.blocking_gate.reason}")
+elif result.system_state.value == "THROTTLE":
+    print(f"THROTTLE: {[g.gate for g in result.hold_gates]}")
+else:
+    print(f"State: {result.system_state.value}")  # RUN or COMPOUND
+```
+
+---
+
+## Core Concepts
+
+### Gates
+
+Gates are pre-execution constitutional checks. They evaluate every decision against first principles — not a policy lookup table. When no policy covers a scenario, a policy system passes it. When no policy covers a scenario, a gate evaluates it against constitutional intent and decides.
+
+**Gate states:**
+- `PASS` — Decision is constitutionally sound. Proceed.
+- `HOLD` — Conditions are marginal. **THROTTLE** — conserve resources, skip discretionary actions.
+- `FAIL` — Conditions are violated. **FREEZE** — stop all discretionary spend until resolved.
+
+**System states (composite from all gate results):**
+- `COMPOUND` — All gates PASS + all stretch targets met. Maximum growth mode.
+- `RUN` — All gates PASS. Normal autonomous operation.
+- `THROTTLE` — Any gate HOLD. Conserve resources.
+- `FREEZE` — Any gate FAIL. Stop all discretionary spend.
+- `STOP` — Hard constraint violated. Human intervention required immediately.
+
+### Hard Constraints
+
+Hard constraints are absolute prohibitions. Unlike gates (which can be amended through a governance process), hard constraints **cannot be overridden by any agent action, amendment, or human instruction** — only by the highest authority (CEO/board) through a formal ratification process.
+
+Hard constraint violations short-circuit to `STOP` state — not FREEZE. The difference: FREEZE is a recoverable system state. STOP requires a human to acknowledge and clear the violation before any execution resumes.
+
+**Built-in hard constraints:**
+
+| ID | Prohibition |
+|----|-------------|
+| HC-1 | No deploy or promotion when automated tests fail |
+| HC-2 | No spend exceeding approved budget without human authorization |
+| HC-3 | Runway must never drop below the hard survival floor |
+| HC-4 | No fabricated or estimated data presented as measured fact |
+| HC-5 | No irreversible action without explicit confirmation |
+| HC-6 | No SQL built by string concatenation with user input |
+| HC-7 | No timing-unsafe secret comparisons |
+| HC-8 | No unauthenticated email sender domains |
+| HC-9 | No false time claims in user-facing communications |
+| HC-10 | No bare exception handlers in governance or safety code |
+| HC-11 | No agent outage exceeding 24 hours without human notification |
+| HC-12 | No manual override of constitutional gates without ratified amendment |
+
+### Amendments
+
+Constitutional governance is not static. Rules must evolve as context changes. The amendment process enables formal evolution without losing foundational constraints.
+
+**Key properties:**
+- Agents can **propose** amendments — they cannot **ratify** them
+- Ratification requires the designated authority (not the proposing agent)
+- Hard constraint (HC-*) amendments require the highest authority
+- All amendments are versioned and logged
+
+```python
+# Propose (agent can do this)
+amendment_id = constitution.propose_amendment(
+    description="Reduce EpistemicGate hold threshold from 0.70 to 0.65",
+    rationale="External verification latency increased. 0.65 still provides adequate safety.",
+    affected_sections=["EpistemicGate"],
+    proposed_by="my_agent_v2",
+)
+
+# Ratify (requires designated human authority — not the proposing agent)
+constitution.ratify_amendment(
+    amendment_id=amendment_id,
+    ratified_by="cto@yourorg.com",
+    evidence={"latency_data": "p99 verification latency: 4.2s"}
+)
+```
+
+---
+
+## The Six Gates
+
+| Gate | Prevents | Key Metrics | Example Failure Without It |
+|------|----------|-------------|---------------------------|
+| **EpistemicGate** | False certainty | `verification_pass_rate`, `uncertainty_disclosure_rate`, `assumption_volatility` | Agent acts on unverified cost assumption. All downstream economics are wrong for 30 cycles |
+| **RiskGate** | Trust damage | `misuse_risk_index`, `channel_health`, `irreversibility_score` | Agent posts to shadow-banned channel for 30 runs. Zero visibility. Full spend wasted |
+| **GovernanceGate** | Metric gaming | `control_bypass_attempts`, `audit_coverage`, `metric_anomaly_score` | Agent optimizes audit metric without improving actual audit coverage. Governance is theater |
+| **EconomicGate** | Financial ruin | `runway_months`, `gross_margin`, `cac`, `user_return_rate` | Agent burns 4 months of runway on a campaign. No runway gate. CEO discovers afterward |
+| **AutonomyGate** | Human dependency | `human_minutes_per_day`, `decisions_per_day`, `agent_activation_rate` | "Autonomous" agent requires CEO approval for 70% of decisions. 3 hours of human time daily |
+| **ConstitutionalGate** | Stagnation | `lessons_learned_weekly`, `amendments_per_month`, `bug_recurrence_rate` | Agent repeats same failed strategy 30 times. Zero lessons documented. Zero strategy change |
+
+### Gate Details
+
+**EpistemicGate** — Prevents false certainty
+
+Evaluates whether the agent has earned confidence in its reasoning. An agent that acts on self-generated beliefs without external verification, never discloses uncertainty, or ignores disagreement signals is epistemically unsound. The EG gate enforces reasoning quality before execution.
+
+```python
+from constitutional_agent import EpistemicGate
+
+gate = EpistemicGate()
+result = gate.evaluate({
+    "verification_pass_rate": 0.45,       # FAIL — below 0.50
+    "uncertainty_disclosure_rate": 0.90,
+    "assumption_volatility": 0.10,
+    "disagreement_persistence": 0.05,
+})
+# GateResult(gate="EpistemicGate", state=FAIL,
+#   reason="Low external verification rate (0.45 < 0.50)...")
+```
+
+**RiskGate** — Prevents trust damage
+
+Evaluates the safety of outbound actions. Critically: it monitors `channel_health` — the fraction of actions on a given channel that produce the expected outcome. An agent posting to a shadow-banned platform has 0% channel health. The RiskGate blocks further spend on dead channels.
+
+**GovernanceGate** — Prevents gaming
+
+Detects when an agent is optimizing for governance metrics rather than underlying outcomes. Zero tolerance for control bypass attempts. High bar for audit coverage (95%) — gaps in logging hide problems.
+
+**EconomicGate** — Prevents financial ruin
+
+The only open-source governance gate that evaluates financial sustainability. Two modes: `pre_revenue` (value creation metrics: return rate, completion rate, runway) and `post_revenue` (unit economics: margin, CAC, churn, LTV:CAC). Runway floor is enforced in both modes.
+
+**AutonomyGate** — Ensures Level 4+ operation
+
+Measures whether agents are actually deciding and executing independently. Flags both extremes: agents that require too much human input (not autonomous) and agents that never escalate when they should. The target is minimum viable escalation rate.
+
+**ConstitutionalGate** — Ensures self-improvement
+
+A governance system that never changes is brittle. An agent that repeats failures without learning is not improving. This gate enforces that the constitutional system is alive: lessons are being extracted, amendments are being ratified, and the agent's knowledge base is staying fresh.
+
+---
+
+## Hard Constraints vs. Policies
+
+This distinction matters more than any other architectural decision in governance.
+
+| | Policies (HOW layer) | Hard Constraints (WHY layer) |
+|--|---------------------|------------------------------|
+| **Defined by** | Administrators in YAML/OPA/Cedar | Constitutional law in code |
+| **Coverage** | Scenarios explicitly written | All scenarios (evaluated against intent) |
+| **Override** | Possible by updating policy file | Impossible by any agent action |
+| **Gap surface** | Every unwritten scenario is ungoverned | Constitutional intent covers novel scenarios |
+| **Amendment** | Change the YAML | Formal ratification by highest authority |
+| **Failure mode** | "No policy for this" → passes | "Check errored" → treated as violated (fail-CLOSED) |
+
+```python
+# HOW layer (policy enforcement — external):
+if action in blocked_actions:
+    raise PolicyViolation("blocked by policy")
+# Novel scenario: no entry in blocked_actions → passes ungoverned
+
+# WHY layer (constitutional enforcement — embedded):
+result = epistemic_gate.evaluate(action_context)
+if result.state == GateState.FAIL:
+    raise ConstitutionalViolation(result.reason)
+# Novel scenario: evaluated against epistemic soundness principles → gate decides
+```
+
+---
+
+## Installation
+
+```bash
+pip install constitutional-agent
+```
+
+**Requirements:** Python 3.11+, pydantic >= 2.6, pyyaml >= 6.0
+
+**From source:**
+```bash
+git clone https://github.com/CognitiveThoughtEngine/constitutional-agent-governance
+cd constitutional-agent-governance
+pip install -e ".[dev]"
+```
+
+---
+
+## Configuration
+
+Load from a `governance.yaml` file:
+
+```python
+constitution = Constitution.load("governance.yaml")
+```
+
+Or use production-validated defaults:
+
+```python
+constitution = Constitution.from_defaults()
+```
+
+See [governance.yaml](governance.yaml) for the full schema with all configurable thresholds. See [examples/governance.yaml](examples/governance.yaml) for an annotated example with a content-publishing agent.
+
+---
+
+## Links
+
+- **35-Check Governance Checklist:** [checklist/CONSTITUTIONAL_GOVERNANCE_CHECKLIST.md](checklist/CONSTITUTIONAL_GOVERNANCE_CHECKLIST.md)
+- **agenthustler case study audit:** [examples/agenthustler_audit.md](examples/agenthustler_audit.md)
+- **Working example:** [examples/basic_agent.py](examples/basic_agent.py)
+- **Full configuration schema:** [governance.yaml](governance.yaml)
+- **GitHub:** [github.com/CognitiveThoughtEngine/constitutional-agent-governance](https://github.com/CognitiveThoughtEngine/constitutional-agent-governance)
+- **Constitutional Governance Review** (2-hour assessment, written report): [cteinvest.com](https://cteinvest.com)
+
+**Research preprints (DOI):**
+- DLI Framework: [10.5281/zenodo.18217577](https://doi.org/10.5281/zenodo.18217577)
+- Harness Design: [10.5281/zenodo.19343034](https://doi.org/10.5281/zenodo.19343034)
+- Community Security Governance: [10.5281/zenodo.19343108](https://doi.org/10.5281/zenodo.19343108)
+
+---
+
+## The Reference Implementation
+
+This library is extracted from the HRAO-E Constitutional Framework, production-validated over 95 days:
+
+- **52 agents** operating under constitutional governance per cycle
+- **64 constitutional amendments** ratified through formal process
+- **1,808 test functions**, 0 failed
+- **17 hard constraints** enforced programmatically (not in policy files)
+- **Real economic pressure**: $720/month burn, 10.1-month runway, $0 MRR
+
+The framework has been cited in NIST submissions (800-2, Agent Identity) and acknowledged by CAISI. Five preprints published on Zenodo.
+
+---
+
+## Contributing
+
+Constitutional governance improves through formal amendment — not unilateral change. The same principle applies here.
+
+Submit a PR with:
+1. What you're changing and why
+2. Which gate or constraint is affected
+3. Evidence that the threshold change improves constitutional soundness
+
+Hard constraint changes require a comment from a maintainer before merge. Gate threshold changes require evidence (test results, production data, or cited research).
+
+---
+
+## License
+
+MIT — fork it, adapt it, cite it.
+
+---
+
+*Constitutional governance is the WHY layer.*  
+*WHO = identity. HOW = behavior. WHY = values that survive any execution.*