constraint-architecture 1.5.0__tar.gz

constraint_architecture-1.5.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Xu Renwu (续仁舞, 1nour2567)
+
+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.

constraint_architecture-1.5.0/PKG-INFO

@@ -0,0 +1,159 @@
+Metadata-Version: 2.4
+Name: constraint-architecture
+Version: 1.5.0
+Summary: LLM reasons. Code decides what's allowed. Audit keeps it traceable.
+Author-email: "Xu Renwu (续仁舞)" <1nour2567@gmail.com>
+License: MIT
+Project-URL: Homepage, https://github.com/1nour2567/kylin-agent
+Project-URL: Documentation, https://github.com/1nour2567/kylin-agent/blob/master/CONSTRAINT_EN.md
+Project-URL: Bug Reports, https://github.com/1nour2567/kylin-agent/issues
+Project-URL: Source, https://github.com/1nour2567/kylin-agent
+Keywords: ai-agent,agent-safety,llm-security,guardrails,deterministic-constraints,agent-architecture,audit-trail,constraint-engine
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Classifier: Topic :: Security
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: license-file
+
+# Constraint Architecture
+
+**LLM reasons. Code decides what's allowed. Audit keeps it traceable.**
+
+[![Python 3.10+](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/downloads/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![Version](https://img.shields.io/badge/version-1.5.0-green.svg)]()
+
+A production-grade abstract skeleton for AI agent systems. Four deterministic constraint layers wrapped around an LLM reasoning core — independently validated in two completely unrelated domains.
+
+---
+
+## Quickstart
+
+```bash
+pip install constraint-architecture
+```
+
+```python
+from constraint_architecture import ConstraintEngine, ValidationResult
+
+class MyGuardrails(ConstraintEngine):
+    async def validate(self, context, reasoning_output):
+        if "rm -rf" in reasoning_output.get("command", ""):
+            return ValidationResult(
+                allowed=False,
+                reason="destructive command blocked"
+            )
+        return ValidationResult(allowed=True)
+```
+
+Done. Your agent now has a deterministic constraint layer the LLM cannot override.
+
+---
+
+## The Architecture
+
+```
+User Input → [1. LLM Reasoning] → [2. Code Constraints] → [3. Sandbox Execute] → [4. Audit Trail]
+                  "think"            "decide if allowed"      "do it safely"        "prove it happened"
+```
+
+| Layer | What it does | Runs on |
+|-------|-------------|---------|
+| **1. Reasoning** | LLM freely reasons about what to do | Probabilistic |
+| **2. Constraints** | Deterministic validation. Rules only increase, never decrease | Code |
+| **3. Execution** | Tiered execution (auto / confirm / veto). Role enforcement | Code |
+| **4. Audit** | Immutable SHA256 hash chain. Every step, every decision | Code |
+
+**Core principle:** the LLM can only *propose*. Code decides what actually executes. No amount of prompt engineering can bypass a deterministic constraint.
+
+---
+
+## What's Inside
+
+This package is an **abstract skeleton** — not a framework, not a library, not a service. It defines the *interfaces* and *data contracts* that every agent system needs:
+
+```
+constraint_architecture/
+├── skeleton.py          # 1384 lines — the full skeleton
+│   ├── 7 ABCs           # Shell, Identity, Scheduler, Memory, Protocol, Tools
+│   ├── 7 Protocols      # Duck-typing versions (for non-inheritance wiring)
+│   ├── 4 Constraint ABCs # ReasoningLayer, ConstraintEngine, ExecutionProxy, AuditTrail
+│   ├── 12 dataclasses   # 10 frozen (immutable), 2 mutable
+│   ├── 4 custom exceptions # VetoError, ExecutionRefusedError, AuditIntegrityError
+│   ├── 4 enums          # Tier (auto/confirm/veto), EventType, MemoryLevel
+│   └── 25 self-checks   # Automated: ABCs uninstantiable, frozen immutable, bounds validated
+└── __init__.py           # Re-exports the full public API
+```
+
+You subclass the ABCs for your domain. The wiring is *yours* — the skeleton doesn't know whether you're building a security agent or a music DJ. That's the point.
+
+---
+
+## Why This Exists
+
+I'm a freshman. Three weeks after touching AI agents for the first time, I had built two of them:
+
+- **Kylin-Agent**: security-hardened ops agent deployed on Kylin OS V11. 16 red-team attacks, 0 breaches. 149 tests.
+- **Malio**: embodied AI music agent. 800 particles, 9 physics systems. PersonaEngine with central-bank-style emotional currency.
+
+After finishing both, I realized they share the **same four-layer architecture** — despite being in completely unrelated domains. This skeleton is the extraction of that pattern.
+
+If someone uses this architecture in a third domain (healthcare? finance? education?), that third independent validation would prove the pattern is real.
+
+---
+
+## Certified: Production Engineering Quality
+
+- **ABC + Protocol dual-interface**: every subsystem exposes both an abstract class (for inheritance) and a Protocol (for duck-typing)
+- **10 of 12 dataclasses frozen**: downstream code cannot silently flip a veto into a pass
+- **`__post_init__` validation**: risk_score bounded 0-9, ScheduleTrigger type-enforced, AuditEvent.prev_hash mandatory
+- **4 custom exceptions**: each carries structured, machine-consumable fields (VetoError has reason + alternative + ref)
+- **25 automated self-checks**: run `python -m constraint_architecture.skeleton` to verify integrity
+- **Design rationale in every class**: not just "what", but "why this design and not the alternative"
+
+---
+
+## Requirements
+
+- Python 3.10+
+- Zero dependencies. Zero.
+
+You don't need FastAPI, Redis, PostgreSQL, JWT, or any other infrastructure. This skeleton defines *contracts*. The implementation is yours.
+
+---
+
+## Reference Implementations
+
+| Project | Domain | Key Metric |
+|---------|--------|------------|
+| [Kylin-Agent](https://github.com/1nour2567/kylin-agent) | Security ops on Kylin OS V11 | 16 attacks, 0 breaches |
+| [Malio](https://github.com/1nour2567/Malio) | Embodied AI music | 800 particles, 9 physics systems |
+| Quant Trading | Daily multi-factor strategy | Sharpe 1.36, MDD 12.7% |
+
+Same skeleton. Three domains. Different wiring.
+
+---
+
+## Related Reading
+
+- [Constraint Architecture — Chinese](https://github.com/1nour2567/kylin-agent/blob/master/CONSTRAINT.md)
+- [Constraint Architecture — English](https://github.com/1nour2567/kylin-agent/blob/master/CONSTRAINT_EN.md)
+- [Agent OS Architecture — 7-layer design](https://github.com/1nour2567/kylin-agent)
+
+---
+
+## License
+
+MIT — Xu Renwu (续仁舞), 2026.
+
+*大一。三周。一个人。*

constraint_architecture-1.5.0/README.md

@@ -0,0 +1,132 @@
+# Constraint Architecture
+
+**LLM reasons. Code decides what's allowed. Audit keeps it traceable.**
+
+[![Python 3.10+](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/downloads/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![Version](https://img.shields.io/badge/version-1.5.0-green.svg)]()
+
+A production-grade abstract skeleton for AI agent systems. Four deterministic constraint layers wrapped around an LLM reasoning core — independently validated in two completely unrelated domains.
+
+---
+
+## Quickstart
+
+```bash
+pip install constraint-architecture
+```
+
+```python
+from constraint_architecture import ConstraintEngine, ValidationResult
+
+class MyGuardrails(ConstraintEngine):
+    async def validate(self, context, reasoning_output):
+        if "rm -rf" in reasoning_output.get("command", ""):
+            return ValidationResult(
+                allowed=False,
+                reason="destructive command blocked"
+            )
+        return ValidationResult(allowed=True)
+```
+
+Done. Your agent now has a deterministic constraint layer the LLM cannot override.
+
+---
+
+## The Architecture
+
+```
+User Input → [1. LLM Reasoning] → [2. Code Constraints] → [3. Sandbox Execute] → [4. Audit Trail]
+                  "think"            "decide if allowed"      "do it safely"        "prove it happened"
+```
+
+| Layer | What it does | Runs on |
+|-------|-------------|---------|
+| **1. Reasoning** | LLM freely reasons about what to do | Probabilistic |
+| **2. Constraints** | Deterministic validation. Rules only increase, never decrease | Code |
+| **3. Execution** | Tiered execution (auto / confirm / veto). Role enforcement | Code |
+| **4. Audit** | Immutable SHA256 hash chain. Every step, every decision | Code |
+
+**Core principle:** the LLM can only *propose*. Code decides what actually executes. No amount of prompt engineering can bypass a deterministic constraint.
+
+---
+
+## What's Inside
+
+This package is an **abstract skeleton** — not a framework, not a library, not a service. It defines the *interfaces* and *data contracts* that every agent system needs:
+
+```
+constraint_architecture/
+├── skeleton.py          # 1384 lines — the full skeleton
+│   ├── 7 ABCs           # Shell, Identity, Scheduler, Memory, Protocol, Tools
+│   ├── 7 Protocols      # Duck-typing versions (for non-inheritance wiring)
+│   ├── 4 Constraint ABCs # ReasoningLayer, ConstraintEngine, ExecutionProxy, AuditTrail
+│   ├── 12 dataclasses   # 10 frozen (immutable), 2 mutable
+│   ├── 4 custom exceptions # VetoError, ExecutionRefusedError, AuditIntegrityError
+│   ├── 4 enums          # Tier (auto/confirm/veto), EventType, MemoryLevel
+│   └── 25 self-checks   # Automated: ABCs uninstantiable, frozen immutable, bounds validated
+└── __init__.py           # Re-exports the full public API
+```
+
+You subclass the ABCs for your domain. The wiring is *yours* — the skeleton doesn't know whether you're building a security agent or a music DJ. That's the point.
+
+---
+
+## Why This Exists
+
+I'm a freshman. Three weeks after touching AI agents for the first time, I had built two of them:
+
+- **Kylin-Agent**: security-hardened ops agent deployed on Kylin OS V11. 16 red-team attacks, 0 breaches. 149 tests.
+- **Malio**: embodied AI music agent. 800 particles, 9 physics systems. PersonaEngine with central-bank-style emotional currency.
+
+After finishing both, I realized they share the **same four-layer architecture** — despite being in completely unrelated domains. This skeleton is the extraction of that pattern.
+
+If someone uses this architecture in a third domain (healthcare? finance? education?), that third independent validation would prove the pattern is real.
+
+---
+
+## Certified: Production Engineering Quality
+
+- **ABC + Protocol dual-interface**: every subsystem exposes both an abstract class (for inheritance) and a Protocol (for duck-typing)
+- **10 of 12 dataclasses frozen**: downstream code cannot silently flip a veto into a pass
+- **`__post_init__` validation**: risk_score bounded 0-9, ScheduleTrigger type-enforced, AuditEvent.prev_hash mandatory
+- **4 custom exceptions**: each carries structured, machine-consumable fields (VetoError has reason + alternative + ref)
+- **25 automated self-checks**: run `python -m constraint_architecture.skeleton` to verify integrity
+- **Design rationale in every class**: not just "what", but "why this design and not the alternative"
+
+---
+
+## Requirements
+
+- Python 3.10+
+- Zero dependencies. Zero.
+
+You don't need FastAPI, Redis, PostgreSQL, JWT, or any other infrastructure. This skeleton defines *contracts*. The implementation is yours.
+
+---
+
+## Reference Implementations
+
+| Project | Domain | Key Metric |
+|---------|--------|------------|
+| [Kylin-Agent](https://github.com/1nour2567/kylin-agent) | Security ops on Kylin OS V11 | 16 attacks, 0 breaches |
+| [Malio](https://github.com/1nour2567/Malio) | Embodied AI music | 800 particles, 9 physics systems |
+| Quant Trading | Daily multi-factor strategy | Sharpe 1.36, MDD 12.7% |
+
+Same skeleton. Three domains. Different wiring.
+
+---
+
+## Related Reading
+
+- [Constraint Architecture — Chinese](https://github.com/1nour2567/kylin-agent/blob/master/CONSTRAINT.md)
+- [Constraint Architecture — English](https://github.com/1nour2567/kylin-agent/blob/master/CONSTRAINT_EN.md)
+- [Agent OS Architecture — 7-layer design](https://github.com/1nour2567/kylin-agent)
+
+---
+
+## License
+
+MIT — Xu Renwu (续仁舞), 2026.
+
+*大一。三周。一个人。*

constraint_architecture-1.5.0/pyproject.toml

@@ -0,0 +1,50 @@
+[build-system]
+requires = ["setuptools>=68.0", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "constraint-architecture"
+version = "1.5.0"
+description = "LLM reasons. Code decides what's allowed. Audit keeps it traceable."
+readme = "README.md"
+license = {text = "MIT"}
+authors = [
+    {name = "Xu Renwu (续仁舞)", email = "1nour2567@gmail.com"},
+]
+keywords = [
+    "ai-agent",
+    "agent-safety",
+    "llm-security",
+    "guardrails",
+    "deterministic-constraints",
+    "agent-architecture",
+    "audit-trail",
+    "constraint-engine",
+]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "Intended Audience :: Science/Research",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Topic :: Scientific/Engineering :: Artificial Intelligence",
+    "Topic :: Security",
+    "Topic :: Software Development :: Libraries :: Python Modules",
+]
+requires-python = ">=3.10"
+dependencies = []
+
+[project.urls]
+Homepage = "https://github.com/1nour2567/kylin-agent"
+Documentation = "https://github.com/1nour2567/kylin-agent/blob/master/CONSTRAINT_EN.md"
+"Bug Reports" = "https://github.com/1nour2567/kylin-agent/issues"
+Source = "https://github.com/1nour2567/kylin-agent"
+
+[tool.setuptools]
+package-dir = {"" = "src"}
+
+[tool.setuptools.packages.find]
+where = ["src"]

constraint_architecture-1.5.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

constraint_architecture-1.5.0/src/constraint_architecture/__init__.py

@@ -0,0 +1,138 @@
+"""
+Constraint Architecture — LLM reasons, code decides, audit keeps it traceable.
+
+A production-grade abstract skeleton for AI agent systems with four
+deterministic constraint layers wrapped around an LLM reasoning core.
+Independently validated in two reference implementations spanning
+security operations (Kylin-Agent) and embodied AI (Malio).
+
+Quickstart
+----------
+    pip install constraint-architecture
+
+    from constraint_architecture import ConstraintEngine, ValidationResult
+
+    class MyGuardrails(ConstraintEngine):
+        async def validate(self, context, reasoning_output):
+            if "rm -rf" in reasoning_output.get("command", ""):
+                return ValidationResult(
+                    allowed=False,
+                    reason="destructive command blocked",
+                )
+            return ValidationResult(allowed=True)
+
+Layers
+------
+1. Reasoning (LLM)     — free reasoning, no execution authority
+2. Constraints (Code)   — deterministic validation, unbypassable rules
+3. Execution (Sandbox)  — tiered execution: auto / confirm / veto
+4. Audit (Immutable)    — SHA256 chain, every step traceable
+
+Reference Implementations
+-------------------------
+- Kylin-Agent: security-hardened ops agent on Kylin OS.
+  16 red-team attacks, 0 breaches. 149 tests.
+- Malio: embodied AI music agent. 800 particles, 9 physics systems.
+- Quant Trading: daily frequency multi-factor strategy.
+  L3 circuit-breaker (Ombudsman) enforcing Constraint Architecture in finance.
+
+Copyright (c) 2026 Xu Renwu (续仁舞). MIT License.
+"""
+
+from constraint_architecture.skeleton import (
+    # Version
+    __version__,
+    # Data
+    ValidationResult,
+    ExecutionResult,
+    AuditEvent,
+    PipelineContext,
+    StateEvent,
+    UserIntent,
+    ScheduleTrigger,
+    LoopTurn,
+    AuthorizationResult,
+    Identity,
+    ToolDefinition,
+    # Enums
+    Tier,
+    EventType,
+    MemoryLevel,
+    # Shell
+    AgentShell,
+    Shell,
+    ToolResult,
+    # Identity
+    AgentIdentity,
+    IdentityProvider,
+    # Scheduler
+    AgentScheduler,
+    SchedulerProvider,
+    # Memory
+    AgentMemory,
+    MemoryProvider,
+    # Protocol
+    AgentProtocol,
+    AgentWire,
+    # Tools
+    AgentTools,
+    ToolProvider,
+    # Constraint layer ABCs
+    ReasoningLayer,
+    ConstraintEngine,
+    ExecutionProxy,
+    AuditTrail,
+    # Constraint layer Protocols
+    Reasoner,
+    ConstraintValidator,
+    Executor,
+    Auditor,
+    # Exceptions
+    ConstraintError,
+    VetoError,
+    ExecutionRefusedError,
+    AuditIntegrityError,
+)
+
+__all__ = [
+    "__version__",
+    "ValidationResult",
+    "ExecutionResult",
+    "AuditEvent",
+    "PipelineContext",
+    "StateEvent",
+    "UserIntent",
+    "ScheduleTrigger",
+    "LoopTurn",
+    "AuthorizationResult",
+    "Identity",
+    "ToolDefinition",
+    "Tier",
+    "EventType",
+    "MemoryLevel",
+    "AgentShell",
+    "Shell",
+    "ToolResult",
+    "AgentIdentity",
+    "IdentityProvider",
+    "AgentScheduler",
+    "SchedulerProvider",
+    "AgentMemory",
+    "MemoryProvider",
+    "AgentProtocol",
+    "AgentWire",
+    "AgentTools",
+    "ToolProvider",
+    "ReasoningLayer",
+    "ConstraintEngine",
+    "ExecutionProxy",
+    "AuditTrail",
+    "Reasoner",
+    "ConstraintValidator",
+    "Executor",
+    "Auditor",
+    "ConstraintError",
+    "VetoError",
+    "ExecutionRefusedError",
+    "AuditIntegrityError",
+]