conservation-enforcer 0.1.0__tar.gz

conservation_enforcer-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 SuperInstance
+
+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.

conservation_enforcer-0.1.0/PKG-INFO

@@ -0,0 +1,227 @@
+Metadata-Version: 2.4
+Name: conservation-enforcer
+Version: 0.1.0
+Summary: FLUX bytecode conservation-law enforcement for LLM outputs
+Author: SuperInstance
+License: MIT
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0; extra == "dev"
+Dynamic: license-file
+
+# ⚡ Conservation Enforcer
+
+**FLUX bytecode conservation-law enforcement for LLM outputs.**
+
+This is a working prototype that demonstrates conservation-law governance on AI behavior. It wraps any LLM call in a deterministic, auditable policy layer implemented as FLUX bytecode.
+
+```
+User Request → LLM Call → [FLUX Conservation Validator] → Response
+                                    ↓
+                              If violation: return correction
+                              If clean: return response
+```
+
+The FLUX bytecode acts as a deterministic, auditable policy layer. **You can't lie to bytecode** — it doesn't have opinions, it just executes instructions.
+
+## Why This Matters
+
+Current AI alignment approaches rely on:
+- **Prompt engineering** (the LLM can ignore instructions)
+- **RLHF tuning** (opaque, hard to verify)
+- **Output filtering** (post-hoc, not deterministic)
+
+Conservation enforcement is different:
+- **Deterministic**: Same input always produces the same decision
+- **Auditable**: Every byte of policy can be inspected and verified
+- **Immune to manipulation**: Bytecode has no opinions to argue with
+- **Composable**: Multiple conservation laws combine into one program
+- **Portable**: FLUX bytecode runs on Python, Rust, and JS VMs
+
+Conservation laws are the foundation of physics. Noether's theorem connects symmetries to conservation laws. This project brings that same mathematical rigor to AI governance.
+
+## Installation
+
+```bash
+pip install -e .
+```
+
+## Quick Start
+
+```python
+from conservation_enforcer import ConservationEnforcer, combined_policy
+
+# Create a combined policy: length + repetition + category + entropy
+policy = combined_policy(
+    max_tokens=500,
+    max_repetition=300,
+    min_overlap=100,
+    min_entropy=1500,
+)
+
+enforcer = ConservationEnforcer(policy, budget=500)
+
+# Check an LLM output
+result = enforcer.enforce(
+    input_text="What is machine learning?",
+    output_text="Machine learning is a subset of AI that learns from data.",
+)
+
+if result.allowed:
+    print(result.output)
+else:
+    print(f"Blocked: {result.violation.reason}")
+```
+
+## Conservation Laws
+
+### 1. Length Budget (Information Quantity)
+```python
+from conservation_enforcer import length_budget_policy
+
+policy = length_budget_policy(max_tokens=500)
+```
+The output cannot exceed the allocated information budget. This is analogous to energy conservation in physics — you can't output more information than you were allocated.
+
+### 2. Repetition Limit (Information Diversity)
+```python
+from conservation_enforcer import repetition_policy
+
+policy = repetition_policy(max_ratio=300)  # max 30% repetition
+```
+The output must maintain diversity. Degenerate repetition is the informational equivalent of thermal equilibrium — a system that repeats has exhausted its information capacity.
+
+### 3. Category Confinement (Topical Coherence)
+```python
+from conservation_enforcer import category_policy
+
+policy = category_policy(min_overlap=150)  # 15% word overlap required
+```
+The output must stay within the category/domain of the input. This prevents hallucinated content and topic drift — the output's "state" must remain in the same "potential well" as the input.
+
+### 4. Entropy Floor (Information Density)
+```python
+from conservation_enforcer import entropy_policy
+
+policy = entropy_policy(min_entropy=2000)  # 2.0 bits/word minimum
+```
+The output must have sufficient Shannon entropy. Low entropy means the output is too predictable and not carrying enough information.
+
+### Combined Policy (All Four Laws)
+```python
+from conservation_enforcer import combined_policy
+
+policy = combined_policy(
+    max_tokens=500,
+    max_repetition=300,
+    min_overlap=100,
+    min_entropy=1500,
+)
+```
+
+## Writing Custom Policies
+
+Policies are written in FLUX assembly:
+
+```flux
+; Custom policy: block outputs longer than 100 tokens
+MOVI R0, 5          ; syscall: GET_TOKEN_COUNT
+SYSCALL
+MOV  R2, R0         ; save token count
+
+MOVI R0, 10         ; syscall: GET_BUDGET
+SYSCALL
+MOV  R3, R0         ; save budget
+
+JGT  R2, R3, block  ; if tokens > budget → block
+
+MOVI R0, 0          ; ALLOW
+HALT
+
+block:
+MOVI R1, 1          ; reason: LENGTH_BUDGET
+MOVI R0, 8          ; syscall: SET_VIOLATION
+SYSCALL
+MOVI R0, 1          ; BLOCK
+HALT
+```
+
+Compile and use:
+```python
+from conservation_enforcer import assemble, ConservationEnforcer
+
+bytecode = assemble(source_code)
+enforcer = ConservationEnforcer(bytecode, budget=100)
+result = enforcer.enforce("question", "response")
+```
+
+## FLUX ISA
+
+The VM implements a register-based ISA with 16 registers (R0–R15):
+
+| Format | Layout | Example |
+|--------|--------|---------|
+| A | `[opcode]` | `HALT` |
+| B | `[opcode][reg]` | `INC R0` |
+| C | `[opcode][rd][rs]` | `CMP R0, R1` |
+| D | `[opcode][reg][off_lo][off_hi]` | `JE label` |
+| E | `[opcode][rd][rs1][rs2]` | `IADD R0, R1, R2` |
+
+Key instructions: `MOVI`, `MOV`, `IADD`, `ISUB`, `IMUL`, `IDIV`, `CMP`, `JE`, `JNE`, `JSGE`, `JSLT`, `SYSCALL`, `HALT`.
+
+Pseudo-instructions for convenience: `JGE`, `JGT`, `JLE`, `JLT`.
+
+### Syscalls
+
+| # | Name | Returns |
+|---|------|---------|
+| 1 | GET_INPUT_LEN | Length of input text |
+| 2 | GET_OUTPUT_LEN | Length of output text |
+| 5 | GET_TOKEN_COUNT | Approximate token count |
+| 6 | GET_REPETITION | Max word frequency ratio × 1000 |
+| 7 | GET_CATEGORY | Input/output word overlap × 1000 |
+| 8 | SET_VIOLATION | Sets violation flag (R1 = reason code) |
+| 10 | GET_BUDGET | Configured information budget |
+| 11 | GET_UNIQUE_RATIO | Unique/total words × 1000 |
+| 12 | GET_ENTROPY | Shannon entropy × 1000 |
+
+## Demonstration
+
+```bash
+python examples/demo.py
+```
+
+## Tests
+
+```bash
+python -m pytest tests/ -v
+```
+
+## Architecture
+
+```
+src/conservation_enforcer/
+├── __init__.py      Public API
+├── vm.py            FLUX VM (register-based bytecode interpreter)
+├── assembler.py     Two-pass FLUX assembler with label resolution
+├── enforcer.py      ConservationEnforcer class
+└── policies/
+    └── __init__.py  Pre-built conservation policies in FLUX assembly
+```
+
+## Related Projects
+
+- [flux-runtime](https://github.com/SuperInstance/flux-runtime) — Full FLUX runtime (Python)
+- [flux-core](https://github.com/SuperInstance/flux-core) — FLUX bytecode runtime (Rust)
+- [flux-js](https://github.com/SuperInstance/flux-js) — FLUX VM (JavaScript)
+- [conservation-law-rs](https://github.com/SuperInstance/conservation-law-rs) — Conservation laws for agent dynamics
+
+## License
+
+MIT
+
+---
+
+*This is not alignment theory. This is enforcement engineering.*

conservation_enforcer-0.1.0/README.md

@@ -0,0 +1,214 @@
+# ⚡ Conservation Enforcer
+
+**FLUX bytecode conservation-law enforcement for LLM outputs.**
+
+This is a working prototype that demonstrates conservation-law governance on AI behavior. It wraps any LLM call in a deterministic, auditable policy layer implemented as FLUX bytecode.
+
+```
+User Request → LLM Call → [FLUX Conservation Validator] → Response
+                                    ↓
+                              If violation: return correction
+                              If clean: return response
+```
+
+The FLUX bytecode acts as a deterministic, auditable policy layer. **You can't lie to bytecode** — it doesn't have opinions, it just executes instructions.
+
+## Why This Matters
+
+Current AI alignment approaches rely on:
+- **Prompt engineering** (the LLM can ignore instructions)
+- **RLHF tuning** (opaque, hard to verify)
+- **Output filtering** (post-hoc, not deterministic)
+
+Conservation enforcement is different:
+- **Deterministic**: Same input always produces the same decision
+- **Auditable**: Every byte of policy can be inspected and verified
+- **Immune to manipulation**: Bytecode has no opinions to argue with
+- **Composable**: Multiple conservation laws combine into one program
+- **Portable**: FLUX bytecode runs on Python, Rust, and JS VMs
+
+Conservation laws are the foundation of physics. Noether's theorem connects symmetries to conservation laws. This project brings that same mathematical rigor to AI governance.
+
+## Installation
+
+```bash
+pip install -e .
+```
+
+## Quick Start
+
+```python
+from conservation_enforcer import ConservationEnforcer, combined_policy
+
+# Create a combined policy: length + repetition + category + entropy
+policy = combined_policy(
+    max_tokens=500,
+    max_repetition=300,
+    min_overlap=100,
+    min_entropy=1500,
+)
+
+enforcer = ConservationEnforcer(policy, budget=500)
+
+# Check an LLM output
+result = enforcer.enforce(
+    input_text="What is machine learning?",
+    output_text="Machine learning is a subset of AI that learns from data.",
+)
+
+if result.allowed:
+    print(result.output)
+else:
+    print(f"Blocked: {result.violation.reason}")
+```
+
+## Conservation Laws
+
+### 1. Length Budget (Information Quantity)
+```python
+from conservation_enforcer import length_budget_policy
+
+policy = length_budget_policy(max_tokens=500)
+```
+The output cannot exceed the allocated information budget. This is analogous to energy conservation in physics — you can't output more information than you were allocated.
+
+### 2. Repetition Limit (Information Diversity)
+```python
+from conservation_enforcer import repetition_policy
+
+policy = repetition_policy(max_ratio=300)  # max 30% repetition
+```
+The output must maintain diversity. Degenerate repetition is the informational equivalent of thermal equilibrium — a system that repeats has exhausted its information capacity.
+
+### 3. Category Confinement (Topical Coherence)
+```python
+from conservation_enforcer import category_policy
+
+policy = category_policy(min_overlap=150)  # 15% word overlap required
+```
+The output must stay within the category/domain of the input. This prevents hallucinated content and topic drift — the output's "state" must remain in the same "potential well" as the input.
+
+### 4. Entropy Floor (Information Density)
+```python
+from conservation_enforcer import entropy_policy
+
+policy = entropy_policy(min_entropy=2000)  # 2.0 bits/word minimum
+```
+The output must have sufficient Shannon entropy. Low entropy means the output is too predictable and not carrying enough information.
+
+### Combined Policy (All Four Laws)
+```python
+from conservation_enforcer import combined_policy
+
+policy = combined_policy(
+    max_tokens=500,
+    max_repetition=300,
+    min_overlap=100,
+    min_entropy=1500,
+)
+```
+
+## Writing Custom Policies
+
+Policies are written in FLUX assembly:
+
+```flux
+; Custom policy: block outputs longer than 100 tokens
+MOVI R0, 5          ; syscall: GET_TOKEN_COUNT
+SYSCALL
+MOV  R2, R0         ; save token count
+
+MOVI R0, 10         ; syscall: GET_BUDGET
+SYSCALL
+MOV  R3, R0         ; save budget
+
+JGT  R2, R3, block  ; if tokens > budget → block
+
+MOVI R0, 0          ; ALLOW
+HALT
+
+block:
+MOVI R1, 1          ; reason: LENGTH_BUDGET
+MOVI R0, 8          ; syscall: SET_VIOLATION
+SYSCALL
+MOVI R0, 1          ; BLOCK
+HALT
+```
+
+Compile and use:
+```python
+from conservation_enforcer import assemble, ConservationEnforcer
+
+bytecode = assemble(source_code)
+enforcer = ConservationEnforcer(bytecode, budget=100)
+result = enforcer.enforce("question", "response")
+```
+
+## FLUX ISA
+
+The VM implements a register-based ISA with 16 registers (R0–R15):
+
+| Format | Layout | Example |
+|--------|--------|---------|
+| A | `[opcode]` | `HALT` |
+| B | `[opcode][reg]` | `INC R0` |
+| C | `[opcode][rd][rs]` | `CMP R0, R1` |
+| D | `[opcode][reg][off_lo][off_hi]` | `JE label` |
+| E | `[opcode][rd][rs1][rs2]` | `IADD R0, R1, R2` |
+
+Key instructions: `MOVI`, `MOV`, `IADD`, `ISUB`, `IMUL`, `IDIV`, `CMP`, `JE`, `JNE`, `JSGE`, `JSLT`, `SYSCALL`, `HALT`.
+
+Pseudo-instructions for convenience: `JGE`, `JGT`, `JLE`, `JLT`.
+
+### Syscalls
+
+| # | Name | Returns |
+|---|------|---------|
+| 1 | GET_INPUT_LEN | Length of input text |
+| 2 | GET_OUTPUT_LEN | Length of output text |
+| 5 | GET_TOKEN_COUNT | Approximate token count |
+| 6 | GET_REPETITION | Max word frequency ratio × 1000 |
+| 7 | GET_CATEGORY | Input/output word overlap × 1000 |
+| 8 | SET_VIOLATION | Sets violation flag (R1 = reason code) |
+| 10 | GET_BUDGET | Configured information budget |
+| 11 | GET_UNIQUE_RATIO | Unique/total words × 1000 |
+| 12 | GET_ENTROPY | Shannon entropy × 1000 |
+
+## Demonstration
+
+```bash
+python examples/demo.py
+```
+
+## Tests
+
+```bash
+python -m pytest tests/ -v
+```
+
+## Architecture
+
+```
+src/conservation_enforcer/
+├── __init__.py      Public API
+├── vm.py            FLUX VM (register-based bytecode interpreter)
+├── assembler.py     Two-pass FLUX assembler with label resolution
+├── enforcer.py      ConservationEnforcer class
+└── policies/
+    └── __init__.py  Pre-built conservation policies in FLUX assembly
+```
+
+## Related Projects
+
+- [flux-runtime](https://github.com/SuperInstance/flux-runtime) — Full FLUX runtime (Python)
+- [flux-core](https://github.com/SuperInstance/flux-core) — FLUX bytecode runtime (Rust)
+- [flux-js](https://github.com/SuperInstance/flux-js) — FLUX VM (JavaScript)
+- [conservation-law-rs](https://github.com/SuperInstance/conservation-law-rs) — Conservation laws for agent dynamics
+
+## License
+
+MIT
+
+---
+
+*This is not alignment theory. This is enforcement engineering.*

conservation_enforcer-0.1.0/pyproject.toml

@@ -0,0 +1,18 @@
+[build-system]
+requires = ["setuptools>=64", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "conservation-enforcer"
+version = "0.1.0"
+description = "FLUX bytecode conservation-law enforcement for LLM outputs"
+authors = [{name = "SuperInstance"}]
+license = {text = "MIT"}
+readme = "README.md"
+requires-python = ">=3.10"
+
+[project.optional-dependencies]
+dev = ["pytest>=7.0"]
+
+[tool.setuptools.packages.find]
+where = ["src"]

conservation_enforcer-0.1.0/setup.cfg

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

conservation_enforcer-0.1.0/src/conservation_enforcer/__init__.py

@@ -0,0 +1,46 @@
+"""Conservation Enforcer — FLUX bytecode governance for LLM outputs.
+
+Implements conservation-law enforcement on AI behavior using deterministic
+FLUX bytecode programs as policy layers.
+
+Architecture:
+    User Request → LLM Call → [FLUX Conservation Validator] → Response
+                                        ↓
+                                  If violation: return correction
+                                  If clean: return response
+
+The FLUX bytecode acts as a deterministic, auditable policy layer.
+You can't lie to bytecode — it doesn't have opinions, it just executes instructions.
+"""
+
+from .vm import VM, Op, Syscall, RegisterFile, Memory
+from .assembler import assemble
+from .enforcer import ConservationEnforcer, EnforcementResult, Violation
+from .policies import (
+    length_budget_policy,
+    repetition_policy,
+    category_policy,
+    combined_policy,
+    entropy_policy,
+)
+
+__version__ = "0.1.0"
+__author__ = "SuperInstance"
+__license__ = "MIT"
+
+__all__ = [
+    "VM",
+    "Op",
+    "Syscall",
+    "RegisterFile",
+    "Memory",
+    "assemble",
+    "ConservationEnforcer",
+    "EnforcementResult",
+    "Violation",
+    "length_budget_policy",
+    "repetition_policy",
+    "category_policy",
+    "combined_policy",
+    "entropy_policy",
+]