{"id":48419413,"url":"https://github.com/dislovelhl/acgs-lite","last_synced_at":"2026-04-09T06:03:20.889Z","repository":{"id":349362654,"uuid":"1201916496","full_name":"dislovelhl/acgs-lite","owner":"dislovelhl","description":"Constitutional governance infrastructure for AI agents — the missing safety layer between your LLM and production","archived":false,"fork":false,"pushed_at":"2026-04-06T06:35:06.000Z","size":110342,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2026-04-06T08:35:42.002Z","etag":null,"topics":["agents","ai","audit","constitutional-ai","eu-ai-act","governance","guardrails","maci","python","safety"],"latest_commit_sha":null,"homepage":"https://pypi.org/project/acgs-lite/","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/dislovelhl.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":".github/FUNDING.yml","license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":"AGENTS.md","dco":null,"cla":null},"funding":{"custom":["https://acgs.ai"]}},"created_at":"2026-04-05T10:41:34.000Z","updated_at":"2026-04-06T06:32:45.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/dislovelhl/acgs-lite","commit_stats":null,"previous_names":["dislovelhl/acgs-lite"],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/dislovelhl/acgs-lite","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dislovelhl%2Facgs-lite","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dislovelhl%2Facgs-lite/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dislovelhl%2Facgs-lite/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dislovelhl%2Facgs-lite/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/dislovelhl","download_url":"https://codeload.github.com/dislovelhl/acgs-lite/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dislovelhl%2Facgs-lite/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31588039,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-09T05:33:47.836Z","status":"ssl_error","status_checked_at":"2026-04-09T05:32:26.579Z","response_time":112,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.6:443 state=error: 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":["agents","ai","audit","constitutional-ai","eu-ai-act","governance","guardrails","maci","python","safety"],"created_at":"2026-04-06T08:02:25.836Z","updated_at":"2026-04-09T06:03:20.884Z","avatar_url":"https://github.com/dislovelhl.png","language":"Python","funding_links":["https://acgs.ai"],"categories":[],"sub_categories":[],"readme":"# ACGS-Lite: Constitutional AI Governance for Agents\n\n[![PyPI](https://img.shields.io/pypi/v/acgs-lite?color=blue\u0026style=for-the-badge)](https://pypi.org/project/acgs-lite/)\n[![Python](https://img.shields.io/pypi/pyversions/acgs-lite?style=for-the-badge)](https://pypi.org/project/acgs-lite/)\n[![License: Apache-2.0](https://img.shields.io/badge/License-Apache--2.0-green.svg?style=for-the-badge)](https://www.apache.org/licenses/LICENSE-2.0)\n[![CI](https://img.shields.io/github/actions/workflow/status/dislovelhl/acgs-lite/ci.yml?branch=main\u0026style=for-the-badge\u0026label=CI)](https://github.com/dislovelhl/acgs-lite/actions)\n[![Coverage](https://img.shields.io/badge/tests-4641%20passing-brightgreen?style=for-the-badge)](https://github.com/dislovelhl/acgs-lite/actions)\n[![Documentation](https://img.shields.io/badge/docs-acgs.ai-brightgreen?style=for-the-badge)](https://acgs.ai/docs)\n\n**The missing safety layer between your LLM and production.**\n\n`acgs-lite` is a deterministic governance engine for AI agents. Define rules in YAML, enforce them at runtime with MACI role separation, and prove compliance with tamper-evident audit trails. Every action is validated before it executes — violations are blocked, not just logged.\n\n---\n\n## 🚀 5-Line Quickstart\n\n```python\nfrom acgs_lite import Constitution, GovernedAgent\n\nconstitution = Constitution.from_yaml(\"constitution.yaml\")\nagent = GovernedAgent(my_llm_agent, constitution=constitution)\nresult = agent.run(\"Process this high-risk transaction\")\n```\n\nRules in YAML (`constitution.yaml`):\n\n```yaml\nconstitutional_hash: \"608508a9bd224290\"\nrules:\n  - id: no-pii\n    pattern: \"SSN|social security|passport number\"\n    severity: CRITICAL\n    description: Block PII exposure\n\n  - id: no-destructive\n    pattern: \"delete|drop table|rm -rf\"\n    severity: HIGH\n    description: Block destructive operations\n\n  - id: require-approval\n    pattern: \"transfer|payment|wire\"\n    severity: HIGH\n    description: Financial actions require human approval\n```\n\n---\n\n## 📦 Installation\n\n```bash\npip install acgs-lite\n```\n\nWith framework integrations:\n\n```bash\npip install \"acgs-lite[openai]\"       # OpenAI\npip install \"acgs-lite[anthropic]\"    # Anthropic Claude\npip install \"acgs-lite[langchain]\"    # LangChain / LangGraph\npip install \"acgs-lite[mcp]\"          # Model Context Protocol server\npip install \"acgs-lite[autogen]\"      # AutoGen / AG2\npip install \"acgs-lite[a2a]\"          # Google A2A protocol\npip install \"acgs-lite[all]\"          # All integrations\n```\n\n---\n\n## 🛡️ Core Concepts\n\n### Governance Engine\n\nThe `GovernanceEngine` sits between your agent and its tools. Every action passes through it before execution. Matching rules block or flag the action; the result is an immutable `ValidationResult`.\n\n```python\nfrom acgs_lite import Constitution, GovernanceEngine, Rule, Severity\n\nconstitution = Constitution.from_rules([\n    Rule(id=\"no-pii\", pattern=r\"SSN|\\bpassport\\b\", severity=Severity.CRITICAL),\n    Rule(id=\"no-delete\", pattern=r\"\\bdelete\\b|\\bdrop\\b\", severity=Severity.HIGH),\n])\n\nengine = GovernanceEngine(constitution)\nresult = engine.validate(\"summarize the quarterly report\", agent_id=\"analyst-01\")\n\nif not result.valid:\n    for v in result.violations:\n        print(f\"[{v.severity}] {v.rule_id}: {v.description}\")\n```\n\n### MACI — Separation of Powers\n\nMACI prevents a single agent from proposing, validating, and executing the same action:\n\n```python\nfrom acgs_lite import MACIEnforcer, MACIRole\n\nenforcer = MACIEnforcer()\n\n# Assign roles\nenforcer.assign(agent_id=\"planner\",   role=MACIRole.PROPOSER)\nenforcer.assign(agent_id=\"reviewer\",  role=MACIRole.VALIDATOR)\nenforcer.assign(agent_id=\"executor\",  role=MACIRole.EXECUTOR)\n\n# Proposer creates; Validator checks; Executor runs — never the same agent\nproposal = enforcer.propose(\"planner\", action=\"deploy v2.1 to production\")\napproval = enforcer.validate(\"reviewer\", proposal)\nenforcer.execute(\"executor\", approval)\n```\n\n### Tamper-Evident Audit Trail\n\nEvery governance decision is written to an append-only, SHA-256-chained log:\n\n```python\nfrom acgs_lite import AuditLog\n\nlog = AuditLog()\nengine = GovernanceEngine(constitution, audit_log=log)\n\nengine.validate(\"send email to user@example.com\", agent_id=\"mailer\")\n\nfor entry in log.entries():\n    print(entry.id, entry.valid, entry.constitutional_hash)\n\n# Verify chain integrity\nassert log.verify_chain(), \"Audit log tampered!\"\n```\n\n### GovernedAgent — Drop-in Wrapper\n\n```python\nfrom acgs_lite import Constitution, GovernedAgent\n\n@GovernedAgent.decorate(constitution=constitution, agent_id=\"summarizer\")\ndef summarize(text: str) -\u003e str:\n    return my_llm.complete(f\"Summarize: {text}\")\n\n# Raises ConstitutionalViolationError if text contains violations\nresult = summarize(\"Q4 revenue was $4.2M\")\n```\n\n---\n\n## 🌐 Integrations\n\n### OpenAI\n\n```python\nfrom acgs_lite.integrations.openai import GovernedOpenAI\nfrom openai import OpenAI\n\nclient = GovernedOpenAI(OpenAI(), constitution=constitution)\nresponse = client.chat.completions.create(\n    model=\"gpt-4o\",\n    messages=[{\"role\": \"user\", \"content\": \"Analyze the contract\"}],\n)\n```\n\n### Anthropic Claude\n\n```python\nfrom acgs_lite.integrations.anthropic import GovernedAnthropic\nimport anthropic\n\nclient = GovernedAnthropic(anthropic.Anthropic(), constitution=constitution)\nmessage = client.messages.create(\n    model=\"claude-opus-4-5\",\n    max_tokens=1024,\n    messages=[{\"role\": \"user\", \"content\": \"Review this code\"}],\n)\n```\n\n### LangChain\n\n```python\nfrom acgs_lite.integrations.langchain import GovernanceRunnable\nfrom langchain_openai import ChatOpenAI\n\ngoverned_llm = GovernanceRunnable(\n    ChatOpenAI(model=\"gpt-4o\"),\n    constitution=constitution,\n)\nresult = governed_llm.invoke(\"Translate this document\")\n```\n\n### MCP Server\n\nStart a governance server that any MCP-compatible agent can query:\n\n```bash\nacgs serve --host 0.0.0.0 --port 8080\n```\n\n```python\nfrom acgs_lite.integrations.mcp_server import create_mcp_server\napp = create_mcp_server(constitution=constitution)\n```\n\n---\n\n## 📋 Compliance Coverage\n\nACGS maps governance controls to 18 regulatory frameworks. Run `acgs assess` to generate a compliance report:\n\n```bash\nacgs assess --framework eu-ai-act --output report.pdf\n```\n\n| Framework | Coverage | Key Controls |\n|-----------|----------|--------------|\n| **EU AI Act (High-Risk)** | Art. 9, 10, 13, 14, 17 | Risk management, human oversight, transparency |\n| **NIST AI RMF** | 7 / 16 functions | Govern, Map, Measure, Manage |\n| **SOC 2 + AI** | 10 / 16 criteria | CC6, CC7, CC9 trust service criteria |\n| **HIPAA + AI** | 9 / 15 safeguards | PHI detection, access controls, audit controls |\n| **GDPR Art. 22** | 10 / 12 requirements | Automated decision-making, right to explanation |\n| **CCPA / CPRA** | 8 / 10 rights | Opt-out, data minimisation, transparency |\n| **ISO 42001** | Clause 6, 8, 9, 10 | AI management system controls |\n| **OWASP LLM Top 10** | 9 / 10 risks | Prompt injection, insecure output, data poisoning |\n\n---\n\n## 🔬 Advanced: Formal Verification\n\nFor the highest-risk scenarios, ACGS supports mathematical proof of safety properties.\n\n### Z3 SMT Solver\n\n```python\nfrom acgs_lite.integrations.z3_verifier import Z3ConstraintVerifier\n\nverifier = Z3ConstraintVerifier()\nresult = verifier.verify(\n    action=\"transfer $50,000 to external account\",\n    constraints=[\"amount \u003c= 10000\", \"recipient in approved_list\"],\n)\nprint(result.satisfiable, result.counterexample)\n```\n\n### Lean 4 Proof Certificates (Leanstral)\n\n```python\nfrom acgs_lite import LeanstralVerifier\n\nverifier = LeanstralVerifier()  # requires mistralai extra\ncertificate = await verifier.verify(\n    property=\"∀ action : Action, action.amount ≤ 10000\",\n    context={\"action\": \"transfer $5,000\"},\n)\nprint(certificate.kernel_verified)  # True only if Lean kernel accepted proof\nprint(certificate.to_audit_dict())  # attach to AuditEntry\n```\n\n---\n\n## ⚡ Performance\n\n| Operation | Latency | Notes |\n|-----------|---------|-------|\n| Rule validation (Python) | \u003c 1 ms | Aho-Corasick multi-pattern |\n| Rule validation (Rust) | ~560 ns | Optional Rust extension |\n| Engine batch (100 rules) | ~2 ms | Parallel severity evaluation |\n| Audit write (JSONL) | ~50 µs | Append-only, SHA-256 chained |\n| Compliance report | \u003c 500 ms | 18 frameworks, cached |\n\n---\n\n## 🖥️ CLI\n\n```bash\n# Validate a single action\nacgs validate \"send email to user@corp.com\" --constitution rules.yaml\n\n# Run governance status check\nacgs status\n\n# Generate compliance report\nacgs assess --framework hipaa --output hipaa_report.pdf\n\n# Audit log inspection\nacgs audit --tail 20\nacgs audit --verify-chain\n\n# Start MCP governance server\nacgs serve --port 8080\n\n# EU AI Act Art. 14(3) kill switch\nacgs halt --agent-id agent-01 --reason \"anomalous behaviour detected\"\nacgs resume --agent-id agent-01\n```\n\n---\n\n## 📖 Documentation\n\n| Guide | Description |\n|-------|-------------|\n| [Quickstart](https://acgs.ai/docs/quickstart) | Up and running in 5 minutes |\n| [Architecture](https://acgs.ai/docs/architecture) | Engine internals, MACI deep dive |\n| [Integrations](https://acgs.ai/docs/integrations) | OpenAI, Anthropic, LangChain, MCP, A2A |\n| [Compliance](https://acgs.ai/docs/compliance-2026) | 18-framework regulatory mapping |\n| [CLI Reference](https://acgs.ai/docs/cli) | Full command reference |\n| [Why Governance?](https://acgs.ai/docs/why-governance) | The case for deterministic guardrails |\n| [OWASP LLM Top 10](https://acgs.ai/docs/owasp-2026) | ACGS coverage of each risk |\n| [Testing Guide](https://acgs.ai/docs/testing-governance) | Testing governed agents |\n\n---\n\n## 🤝 Contributing\n\nWe welcome contributions! See [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.\n\n```bash\ngit clone https://github.com/dislovelhl/acgs-lite\ncd acgs-lite/packages/acgs-lite\npip install -e \".[dev]\"\npytest tests/ --import-mode=importlib\n```\n\n---\n\n## 📄 License\n\nApache-2.0. See [LICENSE](LICENSE) for details.\n\nCommercial enterprise licences (SLA, support, air-gapped deployment) available at [acgs.ai](https://acgs.ai).\n\n---\n\n*Constitutional Hash: `608508a9bd224290` — embedded in every validation path.*\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdislovelhl%2Facgs-lite","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fdislovelhl%2Facgs-lite","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdislovelhl%2Facgs-lite/lists"}