acgs-lite 2.5.0

Public ACGS Lite package for constitutional governance in AI agents. Enforce rules, audit decisions, and prevent self-validation in production.

ACGS -- HTTPS for AI

If Machines Are Deciding Our Fate, Who Constrains the Machines?

Constitutional governance infrastructure for AI agents. The missing safety layer between your LLM and production.

ACGS 2.4.0 | AGPL-3.0-or-later | optional Rust fast path | pytest-backed verification

Hackathon fast path: If you're here for the GitLab AI Hackathon demo, start with Constitutional Sentinel — an ACGS-powered GitLab merge request governance agent that reviews AI-generated code, posts inline violations, and blocks unsafe merges. See hackathon/devpost-submission.md, hackathon/demo-video-script.md, hackathon/constitution.yaml, and the demo MR: https://gitlab.com/martin664/constitutional-sentinel-demo/-/merge_requests/1.

Note: Performance numbers are from the local benchmark suite (make bench) and the fastest figures refer to the optional Rust/PyO3 hot path under benchmark conditions. Python-only and mixed integration paths will be slower. The benchmark target runs focused pytest-benchmark microbenchmarks for engine construction and steady-state validation. Run benchmarks on your own hardware before quoting exact latency. The public import path for this package is from acgs_lite import .... Reserve from acgs import ... for the partial-open-source acgs distribution.

License: AGPL-3.0-or-later for open-source use. Commercial license available for proprietary/SaaS use.

Naming: ACGS is the product name, acgs-lite is the public PyPI package, and acgs_lite is the Python import namespace for this distribution. See ../../docs/brand-architecture.md.

---

GitLab AI Hackathon Demo: Constitutional Sentinel

Constitutional Sentinel is the hackathon demo built on ACGS. It is an independent governance agent for GitLab merge requests that:

• reacts to merge request events
• validates AI-generated diffs against constitutional rules
• posts inline comments on violating lines
• generates a governance summary with a constitutional hash
• blocks unsafe merges when violations are severe

Judge / reviewer quick links

• Devpost draft: hackathon/devpost-submission.md
• Demo script: hackathon/demo-video-script.md
• Demo constitution: hackathon/constitution.yaml
• CI example: hackathon/.gitlab-ci.yml
• Demo MR: https://gitlab.com/martin664/constitutional-sentinel-demo/-/merge_requests/1

Why it matters

AI coding agents can produce useful code quickly, but they do not inherently know your security, privacy, or compliance boundaries. Constitutional Sentinel inserts an independent validator into the GitLab workflow so unsafe changes are flagged before merge.

Demo architecture

1. GitLab merge request event triggers Sentinel
2. Sentinel fetches and validates the diff using ACGS rules
3. Violations are posted back inline on the merge request
4. A governance summary records risk, findings, and constitutional hash
5. Human executor decides whether the merge proceeds

---

The Problem

$203 billion was invested in building decision-making AI engines in 2025. Less than 1% went to the infrastructure required to constrain them.

We built the most powerful decision-making engines in human history and forgot the brakes.

A single mother applies for a mortgage. 742 credit score. 12 years of stable employment. 28% debt-to-income ratio. The AI system rejects her in 340 milliseconds.

{ "status": "REJECTED", "reason": "Risk score insufficient" }

• 0 Human Review
• 0 Appeal Process
• 0 Transparency

Billions of consequential decisions flow through AI systems daily -- none with verifiable governance.

---

The Solution

pip install acgs-lite

from acgs_lite import Constitution, GovernedAgent

constitution = Constitution.from_yaml("rules.yaml")
agent = GovernedAgent(my_agent, constitution=constitution)
result = agent.run("process this request")  # Governed.

Every action validated against constitutional rules. Every decision recorded in a tamper-evident audit trail. Every role boundary enforced.

---

Translating 300 Years of Constitutional Law into Code

The Human Legal Paradigm	The ACGS Machine Equivalent
Separation of Powers (Checks and Balances)	MACI Architecture. Agents cannot act as their own Validator. Role-based isolation ensures structural integrity.
The Rule of Law	Constitutional Engine. Immutable YAML rule definitions evaluated with O(n) Aho-Corasick deterministic scanning.
Due Process & Right to Appeal	Cryptographic Audit Trails. Every boundary check, role assignment, and validation is logged and tamper-evident.

---

The MACI Architecture: Ending Self-Validation

PROPOSER          VALIDATOR          EXECUTOR          OBSERVER
(Agent)     -->   (ACGS Engine) -->  (System)    -->   (Audit Log)
                       |
Generates the    Validates against   Only triggers    Cryptographically
proposed action. immutable YAML      if Validator     chains every
Cannot execute.  constitution        explicitly       boundary check.
                 in benchmarked Rust paths. approves.

The Critical Structural Boundary: The Proposer can never act as its own Validator.

---

Deployment Without Provable Governance is Uninsurable

EU AI Act High-Risk Provisions Take Full Enforcement: August 2, 2026

Fines up to 7% of Global Annual Revenue.

• Liability has permanently shifted from "who built the model" to "who deployed the model into production."
• Most enterprise architectures currently have zero infrastructure in place to programmatically prove compliance.

---

ACGS is HTTPS for AI

The 1990s Web
HTTP (Insecure & Unverifiable)	--> SSL/TLS Protocol Introduced	--> E-Commerce Scales Globally

The web could not scale commercially without cryptographic proof of secure transactions.

The 2020s Enterprise AI
Naked LLMs (Black Box & Unconstrained)	--> ACGS Protocol Introduced	--> Regulated Enterprise AI Adoption

AI cannot scale into high-stakes domains without cryptographic proof of constitutional compliance.

---

The Three Pillars of ACGS Architecture

1. Definition (Constitutional Engine)

Code-first governance. Context-aware matching, custom validators, and tamper-proof constitutional hashing.

• Define rules in YAML with keywords, regex patterns, and severity levels
• 5 domain templates: Constitution.from_template("gitlab")
• ConstitutionBuilder fluent API for code-first governance
• Constitution.merge() for composable, layered governance
• Constitutional diff for change auditing between versions

2. Enforcement (MACI Framework)

Role-based execution. Explicit permission sets. Self-validation prevention. Action risk classification.

• Four roles: Proposer, Validator, Executor, Observer
• Self-validation prevention: agents cannot validate their own output
• Action risk classification: LOW / MEDIUM / HIGH / CRITICAL
• Escalation tiers with SLA recommendations

3. Verification (Tamper-Proof Audit)

Immutable RuleSnapshot history. Inter-rule dependency graphs. OpenTelemetry metrics export.

• SHA-256 chain-verified audit trail
• Constitutional hash: 608508a9bd224290
• Governance metrics collector for Prometheus/OpenTelemetry

---

Out-of-the-Box Global Compliance Coverage

Regulatory Framework	Primary Business Risk	ACGS Auto-Coverage
EU AI Act	7% global revenue penalty	5/9 items auto-covered
NIST AI RMF	US Federal Procurement gate	7/16 items auto-covered
ISO/IEC 42001	International Audit failure risk	9/18 items auto-covered
SOC 2 + AI	Enterprise gate / Lost contracts	10/16 items auto-covered
HIPAA + AI	$1.5M fine per violation	9/15 items auto-covered
GDPR Art. 22	4% global revenue	10/12 items auto-covered
ECOA/FCRA	Unlimited damages	6/12 items auto-covered
NYC LL 144	$1,500/day	6/12 items auto-covered
OECD AI	Baseline standard	10/15 items auto-covered

125 total compliance checklist items across 9 global frameworks. 72 auto-populated by ACGS instantly.

from acgs_lite.compliance import MultiFrameworkAssessor

assessor = MultiFrameworkAssessor()
report = assessor.assess({"jurisdiction": "EU", "domain": "healthcare"})
print(report.overall_score)        # 0.62 (auto-populated)
print(report.cross_framework_gaps) # Items needing manual evidence

---

Frictionless Adoption: 5 Lines of Code

from acgs_lite import Constitution, GovernedAgent

constitution = Constitution.from_template("general")
agent = GovernedAgent(my_agent, constitution=constitution)
result = agent.run("process this request")

Ships with 11 integration surfaces for common agent runtimes and deployment paths:

Platform	Install	Status
Anthropic	acgs-lite[anthropic]	Production
MCP Server	acgs-lite[mcp]	Production
GitLab CI/CD	acgs-lite[gitlab]	Production
OpenAI	acgs-lite[openai]	Maintained
xAI (OpenAI-compatible)	acgs-lite[openai]	Experimental
LangChain	acgs-lite[langchain]	Maintained
LiteLLM	acgs-lite[litellm]	Maintained
Google GenAI	acgs-lite[google]	Experimental
LlamaIndex	acgs-lite[llamaindex]	Experimental
AutoGen	acgs-lite[autogen]	Experimental
A2A	acgs-lite[a2a]	Experimental

Additional built-in surfaces include HTTP middleware (acgs_lite.middleware), the OpenShell governance API (create_openshell_governance_app), the Cloud Run webhook server (acgs_lite.integrations.cloud_run_server), and optional Cloud Logging export (acgs-lite[google-cloud]).

CLI Surface

acgs-lite ships a package-local CLI for scaffolding, compliance scoring, report generation, policy lifecycle management, telemetry export, and license flows.

acgs-lite init
acgs-lite assess --jurisdiction european_union --domain healthcare
acgs-lite report --markdown
acgs-lite eu-ai-act --domain healthcare
acgs-lite lint rules.yaml
acgs-lite test --fixtures tests.yaml
acgs-lite lifecycle summary
acgs-lite observe "approve deployment" --prometheus
acgs-lite activate ACGS-PRO-...
acgs-lite status
acgs-lite verify

---

HTTP Middleware for Existing Apps

ACGS can be attached directly to HTTP services so inbound requests and outbound responses are checked against your constitution without rewriting your app.

from acgs_lite.middleware import GovernanceASGIMiddleware

app.add_middleware(
    GovernanceASGIMiddleware,
    strict=False,
    validate_responses=True,
    agent_id="http-middleware",
)

from acgs_lite.middleware import GovernanceWSGIMiddleware

app.wsgi_app = GovernanceWSGIMiddleware(
    app.wsgi_app,
    strict=False,
    agent_id="http-middleware",
)

Both middleware variants restore engine strictness after non-blocking validation paths, so response/request checks do not leak validation mode across requests.

---

OpenShell Governance API

acgs-lite also exposes a stable FastAPI surface for the OpenClaw + OpenShell + ACGS integration model. This is intended for PoC work where OpenClaw proposes actions, ACGS makes the governance decision, and OpenShell enforces the execution boundary.

Run it with uvicorn:

uvicorn "acgs_lite.server:create_governance_app" --factory --host 0.0.0.0 --port 8000

The app exposes both the original validation API and the OpenShell governance routes:

• POST /validate
• GET /stats
• POST /governance/evaluate-action
• POST /governance/submit-for-approval
• POST /governance/review-approval
• POST /governance/record-outcome
• GET /governance/audit-log

Minimal example:

curl -X POST http://127.0.0.1:8000/governance/evaluate-action \
  -H "content-type: application/json" \
  -d '{
    "action_type": "github.write",
    "operation": "write",
    "risk_level": "high",
    "actor": {
      "actor_id": "agent/openclaw-primary",
      "role": "proposer",
      "sandbox_id": "sandbox-demo"
    },
    "resource": {
      "uri": "github://repo/org/repo/issues",
      "kind": "github_repo"
    },
    "context": {
      "request_id": "req_123",
      "session_id": "sess_456",
      "environment": "prod"
    },
    "requirements": {
      "requires_network": true,
      "requires_secret": true,
      "mutates_state": true
    },
    "payload": {
      "payload_hash": "sha256:abcd1234",
      "summary": "Create a GitHub issue for follow-up."
    }
  }'

POST /governance/record-outcome writes into the package's real tamper-evident AuditLog, and GET /governance/audit-log returns the current entries plus chain verification state.

Stable import surface:

from acgs_lite import (
    ActionEnvelope,
    JsonFileGovernanceStateBackend,
    RedisGovernanceStateBackend,
    SQLiteGovernanceStateBackend,
    create_openshell_governance_app,
)

Pluggable persistence backends share a common state-storage protocol:

app = create_openshell_governance_app(
    state_backend=JsonFileGovernanceStateBackend("state/openshell-governance.json")
)

# Or:
app = create_openshell_governance_app(
    state_backend=SQLiteGovernanceStateBackend("state/openshell-governance.db")
)

# Or:
app = create_openshell_governance_app(
    state_backend=RedisGovernanceStateBackend(redis_client)
)

---

Human Oversight for High-Impact Decisions

For Article 14 style human-in-the-loop control, route risky decisions through the human oversight gateway:

from acgs_lite.eu_ai_act.human_oversight import HumanOversightGateway

gateway = HumanOversightGateway(
    system_id="cv-screener-v1",
    oversight_threshold=0.8,
)

decision = gateway.submit(
    "reject_candidate",
    "Rejected: insufficient Python experience",
    impact_score=0.91,
    context={"candidate_id": "abc123"},
)

if decision.requires_human_review:
    gateway.approve(decision.decision_id, reviewer_id="hr-1", notes="Approved after review")

Optional review/approval/rejection callbacks may fail without interrupting the governance decision record itself, which makes notification hooks safe to use with email, queue, or webhook transports.

---

Frictionless CI/CD: The GitLab Duo Integration

1. MR Webhook Fires -- GitLab event triggered. Code diffs and commit messages enter the ACGS pipeline.
2. The Governance Gate -- MACI enforces separation: The MR Author (Proposer) cannot act as the Approver (Validator).
3. Inline Violations -- Findings appear directly on the exact line of the Git diff in the developer's native workflow.
4. Cryptographic Chain -- The MR is merged or hard-blocked. The final decision is instantly committed to a tamper-evident audit log.

# .gitlab-ci.yml
governance:
  stage: test
  image: python:3.11-slim
  before_script:
    - pip install acgs-lite
  script:
    - python3 -c "
      import asyncio, os, sys
      from acgs_lite import Constitution
      from acgs_lite.integrations.gitlab import GitLabGovernanceBot

      async def main():
          constitution = Constitution.from_yaml('rules.yaml')
          bot = GitLabGovernanceBot(
              token=os.environ['GITLAB_TOKEN'],
              project_id=int(os.environ['CI_PROJECT_ID']),
              constitution=constitution,
          )
          report = await bot.run_governance_pipeline(
              mr_iid=int(os.environ['CI_MERGE_REQUEST_IID'])
          )
          return 1 if report.violations else 0

      sys.exit(asyncio.run(main()))
      "
  rules:
    - if: $CI_PIPELINE_SOURCE == 'merge_request_event'

---

The Engine Built by the Machines

This entire constitutional governance engine -- 3,133 passing tests, Aho-Corasick optimization, MACI architecture -- was built by a non-technical founder who could not write a for loop two years ago. It was built entirely through conversation with Claude.

If an AI is capable enough to help a non-technical founder build its own constitutional governance engine, it is capable enough to do immense damage without one.

Governance must be democratic. The infrastructure that constrains the machines must be accessible to the people affected by them -- not just the corporations deploying them.

---

Govern Responsibly.

pip install acgs-lite

AGPL-3.0-or-later Licensed | Open Source | Commercial License Available

The question was never whether power would be constrained -- it was whether the constraints would be built by the people affected or imposed after the damage was done.

Development Verification

For local package development, run pytest with importlib mode from the package root:

python -m pytest tests -q --import-mode=importlib

The test configuration forces pytest to prefer the checked-out src/ tree over an already installed acgs_lite copy, so local verification exercises the code you are editing.

License

ACGS is dual-licensed:

• AGPL-3.0-or-later -- Free for open-source use, internal pipelines, CI/CD, and on-premise deployment.
• Commercial License -- Required if you embed ACGS in a proprietary SaaS product served to external users. Contact [e-mail].

See COMMERCIAL_LICENSE.md for details and FAQ.

---

PyPI | GitHub | Website

Constitutional Hash: 608508a9bd224290