invariantone 1.0.0__tar.gz

invariantone-1.0.0/LICENSE

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

invariantone-1.0.0/PKG-INFO

@@ -0,0 +1,263 @@
+Metadata-Version: 2.4
+Name: invariantone
+Version: 1.0.0
+Summary: InvariantOne: High-Assurance Permutation-Equivariant Natural-Language Decision Model
+Author: InvariantOne Team
+License: Apache-2.0
+Keywords: decision-model,permutation-equivariance,qwen,lora,machine-learning,nlp
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: Apache Software 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
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: torch>=2.1.0
+Requires-Dist: transformers>=4.45.0
+Requires-Dist: accelerate>=0.30.0
+Requires-Dist: pydantic>=2.0.0
+Requires-Dist: numpy>=1.24.0
+Requires-Dist: scipy>=1.10.0
+Requires-Dist: rich>=13.0.0
+Provides-Extra: server
+Requires-Dist: fastapi>=0.100.0; extra == "server"
+Requires-Dist: uvicorn>=0.20.0; extra == "server"
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0.0; extra == "dev"
+Requires-Dist: pytest-cov>=5.0.0; extra == "dev"
+Requires-Dist: fastapi>=0.100.0; extra == "dev"
+Requires-Dist: uvicorn>=0.20.0; extra == "dev"
+Requires-Dist: httpx>=0.25.0; extra == "dev"
+Dynamic: license-file
+
+# InvariantOne
+
+**InvariantOne is a natural-language decision model that scores runtime-defined options directly rather than generating an answer token-by-token.**
+
+[![Python 3.10+](https://img.shields.io/badge/python-3.10%20%7C%203.11%20%7C%203.12-blue.svg)](https://www.python.org/)
+[![License: Apache 2.0](https://img.shields.io/badge/License-Apache%202.0-green.svg)](LICENSE)
+[![Model: D5-L4](https://img.shields.io/badge/Architecture-D5--L4%20%7C%20Nop%3D16-purple.svg)](model_card/MODEL_CARD.md)
+[![Equivariance: Exact](https://img.shields.io/badge/Permutation%20TVD-0.000000-brightgreen.svg)](model_card/MODEL_CARD.md)
+
+---
+
+## Overview
+
+Traditional generative language models make decisions by auto-regressively generating candidate tokens (`"A"`, `"B"`, `"Option 1"`). This causes:
+- **Severe Order Sensitivity:** Changing option order alters probabilities and flips decisions.
+- **Cross-Option Attention Interference:** Later candidates attend to earlier candidates in the prompt.
+- **High Latency Overhead:** Enforcing order-invariance requires permutation averaging (e.g. evaluating $4! = 24$ prompt variants).
+
+**InvariantOne** resolves these problems architecturally:
+1. **Independent Branch Encoding:** Each candidate choice $[S, Q, O_k]$ is processed independently through an adapted `Qwen/Qwen3.5-4B-Base` backbone.
+2. **Exact Distributional Permutation Equivariance:** Pooled option representations pass into a direct comparative head ($d=2560 \to 256 \to 1$), guaranteeing $\text{TVD} = 0.000000$ across all option permutations.
+3. **Calibrated Confidence:** Output probabilities are normalized with a frozen temperature parameter ($\tau^* = 1.0091$).
+
+---
+
+## Installation
+
+```bash
+# From repository
+git clone https://github.com/invariantone/invariantone.git
+cd invariantone
+pip install -e .
+
+# With optional HTTP server support
+pip install -e ".[server]"
+```
+
+---
+
+## Quickstart
+
+```python
+from invariantone import InvariantOne
+
+# Load frozen v1 checkpoint (auto-detects CUDA / Apple MPS / CPU)
+model = InvariantOne.from_pretrained("invariantone-v1")
+
+result = model.decide(
+    state="Pressure is rising above the safe operating range.",
+    question="What action should the controller take?",
+    options=[
+        "Close the inlet valve",
+        "Increase feed pressure",
+        "Maintain the current state",
+        "Disable monitoring",
+    ],
+)
+
+print(f"Selected: {result.choice}")
+print(f"Index:    {result.choice_index}")
+print(f"Probabilities: {[round(p, 4) for p in result.probabilities]}")
+```
+
+Output:
+```text
+Selected: Close the inlet valve
+Index:    0
+Probabilities: [0.7952, 0.0389, 0.1547, 0.0112]
+```
+
+---
+
+## Dynamic Options Count ($K \ge 2$)
+
+> **Scope Note on Candidate Options Count ($K$):**  
+> The runtime supports arbitrary $K \ge 2$; the reported scientific evaluation results are for $K=4$ unless otherwise stated. Experimental generalization to arbitrary $K$ has not been independently established in the scientific benchmarks.
+
+InvariantOne supports arbitrary numbers of runtime options:
+
+```python
+# Binary decision (K=2)
+binary_res = model.decide(
+    state="High packet loss observed on eth0.",
+    question="Should traffic fail over to eth1?",
+    options=["Fail over to eth1", "Stay on eth0"],
+)
+
+# Multi-way decision (K=5)
+multi_res = model.decide(
+    state="Temperature at 520 C, cooling loop nominal.",
+    question="Select operational mode:",
+    options=[
+        "SCRAM shutdown",
+        "Engage loop B",
+        "Adjust control rods",
+        "Vent steam",
+        "Maintain baseline",
+    ],
+)
+```
+
+---
+
+## Batch Decisions
+
+Evaluate workloads with heterogeneous option counts:
+
+```python
+results = model.decide_batch([
+    {
+        "state": "Disk usage at 98%.",
+        "question": "Action:",
+        "options": ["Purge logs", "Extend disk", "Ignore"],
+    },
+    {
+        "state": "CPU nominal.",
+        "question": "Action:",
+        "options": ["Scale down", "Maintain size"],
+    },
+])
+```
+
+---
+
+## Command-Line Interface (CLI)
+
+```bash
+# Single decision (human-readable table)
+invariantone decide \
+  --state "Pressure is above limit" \
+  --question "What should the system do?" \
+  --option "Close inlet valve" \
+  --option "Increase pressure" \
+  --option "Maintain current state" \
+  --option "Disable monitoring"
+
+# Machine-readable JSON output
+invariantone decide \
+  --state "Pressure is above limit" \
+  --question "What should the system do?" \
+  --option "Close inlet valve" \
+  --option "Increase pressure" \
+  --json
+
+# Verify checkpoint cryptographic integrity
+invariantone verify
+
+# Inspect model metadata
+invariantone info
+```
+
+---
+
+## HTTP Inference Service
+
+Run the local API service:
+
+```bash
+invariantone serve --port 8000
+```
+
+Execute inference via REST:
+
+```bash
+curl -X POST http://127.0.0.1:8000/v1/decide \
+  -H "Content-Type: application/json" \
+  -d '{
+    "state": "Pressure is rising above the safe operating range.",
+    "question": "What action should the controller take?",
+    "options": [
+      "Close the inlet valve",
+      "Increase feed pressure",
+      "Maintain the current state",
+      "Disable monitoring"
+    ]
+  }'
+```
+
+---
+
+## Benchmark Performance Summary
+
+Evaluated on `FINAL-HOLDOUT-V2` ($1,536$ four-choice items) under strict preregistered one-shot governance:
+
+> **Benchmark Provenance Note:**  
+> A100 performance figures are from the frozen FINAL-HOLDOUT-V2 benchmarking run; release-wheel functionality was independently smoke-tested in a fresh Python 3.12 environment.
+
+| Evaluation Stratum | Focus | Unadapted $D_0$ | $B_1$-Raw | $B_1$-Sym ($24$-Perm) | **InvariantOne-v1** (Seed 42) |
+| :--- | :--- | :---: | :---: | :---: | :---: |
+| **`FINAL-REAL`** | Real operational control tasks ($N=256$) | 89.45% | 91.41% | 92.58% | **94.14%** |
+| **`FINAL-L1`** | Familiar-Operator Compositional Recombination ($N=256$) | 32.81% | 38.28% | 43.75% | **89.84%** |
+| **`FINAL-L2a`** | Semantic Extrapolation ($N=256$) | 28.12% | 45.31% | 50.39% | **86.33%** |
+| **`FINAL-L2b`** | Relational Extrapolation ($N=256$) | 22.27% | 62.50% | **65.23%** | 55.08% |
+| **`FINAL-L3`** | Double Extrapolation ($N=512$) | 25.20% | 60.94% | **65.43%** | 56.84% |
+| **`Aggregate`** | Total locked holdout pool ($N=1,536$) | 37.17% | 59.90% | 63.80% | **73.18%** (1,124/1,536) |
+
+*Multi-seed aggregate mean across Seeds 42, 43, 44 is **71.74%** ($\pm 1.97\%$).*
+
+**Permutation Equivariance:** $\text{TVD} = 0.000000$ across all 24 permutations.  
+**Inference Speedup:** $5.08\times$ faster than 24-permutation symmetrized causal baseline ($83.71\text{ ms}$ vs $425.31\text{ ms}$ on A100).
+
+---
+
+## Known Boundaries & Model Limitations
+
+1. **Dynamic-$K$ Scientific Generalization:** While the runtime supports arbitrary $K \ge 2$ and exact permutation equivariance holds algebraically, empirical benchmark accuracy ($94.14\%$, $89.84\%$, etc.) was evaluated on 4-choice tasks ($K=4$). Experimental generalization to arbitrary $K$ has not been independently established in the scientific benchmarks.
+2. **Novel Relational Operators:** InvariantOne excels at familiar-operator recombination ($89.84\%$) and semantic domain transfer ($86.33\%$). However, completely unseen operator grammars drop to $55.08\%$ ($L_{2b}$) and $56.84\%$ ($L_3$), where 24-permutation causal averaging remains stronger ($65.43\%$).
+3. **Top-1 Argmax Tie Breaking:** While the output probability distribution is strictly permutation-equivariant ($\text{TVD} = 0.000000$), argmax top-1 selection exhibits a $1.56\%$ flip rate under exact floating-point ties.
+4. **No Generative Explanations:** InvariantOne is a dedicated decision model; it does not produce token-by-token natural-language rationales.
+5. **Confidence Estimates:** Probabilities represent model confidence estimates and are not safety-critical certification guarantees.
+
+---
+
+## Documentation & Research
+
+- **Model Card:** [`model_card/MODEL_CARD.md`](model_card/MODEL_CARD.md)
+- **Academic Paper:** [`paper/main.pdf`](paper/main.pdf)
+- **Release Manifest:** [`INVARIANTONE_V1_RELEASE_MANIFEST.json`](INVARIANTONE_V1_RELEASE_MANIFEST.json)
+- **License Audit:** [`RELEASE_LICENSE_AUDIT.md`](RELEASE_LICENSE_AUDIT.md)
+
+---
+
+## License
+
+InvariantOne is licensed under the [Apache 2.0 License](LICENSE).
+Base foundation model weights are licensed under the upstream Apache 2.0 license by Alibaba Cloud.

invariantone-1.0.0/README.md

@@ -0,0 +1,226 @@
+# InvariantOne
+
+**InvariantOne is a natural-language decision model that scores runtime-defined options directly rather than generating an answer token-by-token.**
+
+[![Python 3.10+](https://img.shields.io/badge/python-3.10%20%7C%203.11%20%7C%203.12-blue.svg)](https://www.python.org/)
+[![License: Apache 2.0](https://img.shields.io/badge/License-Apache%202.0-green.svg)](LICENSE)
+[![Model: D5-L4](https://img.shields.io/badge/Architecture-D5--L4%20%7C%20Nop%3D16-purple.svg)](model_card/MODEL_CARD.md)
+[![Equivariance: Exact](https://img.shields.io/badge/Permutation%20TVD-0.000000-brightgreen.svg)](model_card/MODEL_CARD.md)
+
+---
+
+## Overview
+
+Traditional generative language models make decisions by auto-regressively generating candidate tokens (`"A"`, `"B"`, `"Option 1"`). This causes:
+- **Severe Order Sensitivity:** Changing option order alters probabilities and flips decisions.
+- **Cross-Option Attention Interference:** Later candidates attend to earlier candidates in the prompt.
+- **High Latency Overhead:** Enforcing order-invariance requires permutation averaging (e.g. evaluating $4! = 24$ prompt variants).
+
+**InvariantOne** resolves these problems architecturally:
+1. **Independent Branch Encoding:** Each candidate choice $[S, Q, O_k]$ is processed independently through an adapted `Qwen/Qwen3.5-4B-Base` backbone.
+2. **Exact Distributional Permutation Equivariance:** Pooled option representations pass into a direct comparative head ($d=2560 \to 256 \to 1$), guaranteeing $\text{TVD} = 0.000000$ across all option permutations.
+3. **Calibrated Confidence:** Output probabilities are normalized with a frozen temperature parameter ($\tau^* = 1.0091$).
+
+---
+
+## Installation
+
+```bash
+# From repository
+git clone https://github.com/invariantone/invariantone.git
+cd invariantone
+pip install -e .
+
+# With optional HTTP server support
+pip install -e ".[server]"
+```
+
+---
+
+## Quickstart
+
+```python
+from invariantone import InvariantOne
+
+# Load frozen v1 checkpoint (auto-detects CUDA / Apple MPS / CPU)
+model = InvariantOne.from_pretrained("invariantone-v1")
+
+result = model.decide(
+    state="Pressure is rising above the safe operating range.",
+    question="What action should the controller take?",
+    options=[
+        "Close the inlet valve",
+        "Increase feed pressure",
+        "Maintain the current state",
+        "Disable monitoring",
+    ],
+)
+
+print(f"Selected: {result.choice}")
+print(f"Index:    {result.choice_index}")
+print(f"Probabilities: {[round(p, 4) for p in result.probabilities]}")
+```
+
+Output:
+```text
+Selected: Close the inlet valve
+Index:    0
+Probabilities: [0.7952, 0.0389, 0.1547, 0.0112]
+```
+
+---
+
+## Dynamic Options Count ($K \ge 2$)
+
+> **Scope Note on Candidate Options Count ($K$):**  
+> The runtime supports arbitrary $K \ge 2$; the reported scientific evaluation results are for $K=4$ unless otherwise stated. Experimental generalization to arbitrary $K$ has not been independently established in the scientific benchmarks.
+
+InvariantOne supports arbitrary numbers of runtime options:
+
+```python
+# Binary decision (K=2)
+binary_res = model.decide(
+    state="High packet loss observed on eth0.",
+    question="Should traffic fail over to eth1?",
+    options=["Fail over to eth1", "Stay on eth0"],
+)
+
+# Multi-way decision (K=5)
+multi_res = model.decide(
+    state="Temperature at 520 C, cooling loop nominal.",
+    question="Select operational mode:",
+    options=[
+        "SCRAM shutdown",
+        "Engage loop B",
+        "Adjust control rods",
+        "Vent steam",
+        "Maintain baseline",
+    ],
+)
+```
+
+---
+
+## Batch Decisions
+
+Evaluate workloads with heterogeneous option counts:
+
+```python
+results = model.decide_batch([
+    {
+        "state": "Disk usage at 98%.",
+        "question": "Action:",
+        "options": ["Purge logs", "Extend disk", "Ignore"],
+    },
+    {
+        "state": "CPU nominal.",
+        "question": "Action:",
+        "options": ["Scale down", "Maintain size"],
+    },
+])
+```
+
+---
+
+## Command-Line Interface (CLI)
+
+```bash
+# Single decision (human-readable table)
+invariantone decide \
+  --state "Pressure is above limit" \
+  --question "What should the system do?" \
+  --option "Close inlet valve" \
+  --option "Increase pressure" \
+  --option "Maintain current state" \
+  --option "Disable monitoring"
+
+# Machine-readable JSON output
+invariantone decide \
+  --state "Pressure is above limit" \
+  --question "What should the system do?" \
+  --option "Close inlet valve" \
+  --option "Increase pressure" \
+  --json
+
+# Verify checkpoint cryptographic integrity
+invariantone verify
+
+# Inspect model metadata
+invariantone info
+```
+
+---
+
+## HTTP Inference Service
+
+Run the local API service:
+
+```bash
+invariantone serve --port 8000
+```
+
+Execute inference via REST:
+
+```bash
+curl -X POST http://127.0.0.1:8000/v1/decide \
+  -H "Content-Type: application/json" \
+  -d '{
+    "state": "Pressure is rising above the safe operating range.",
+    "question": "What action should the controller take?",
+    "options": [
+      "Close the inlet valve",
+      "Increase feed pressure",
+      "Maintain the current state",
+      "Disable monitoring"
+    ]
+  }'
+```
+
+---
+
+## Benchmark Performance Summary
+
+Evaluated on `FINAL-HOLDOUT-V2` ($1,536$ four-choice items) under strict preregistered one-shot governance:
+
+> **Benchmark Provenance Note:**  
+> A100 performance figures are from the frozen FINAL-HOLDOUT-V2 benchmarking run; release-wheel functionality was independently smoke-tested in a fresh Python 3.12 environment.
+
+| Evaluation Stratum | Focus | Unadapted $D_0$ | $B_1$-Raw | $B_1$-Sym ($24$-Perm) | **InvariantOne-v1** (Seed 42) |
+| :--- | :--- | :---: | :---: | :---: | :---: |
+| **`FINAL-REAL`** | Real operational control tasks ($N=256$) | 89.45% | 91.41% | 92.58% | **94.14%** |
+| **`FINAL-L1`** | Familiar-Operator Compositional Recombination ($N=256$) | 32.81% | 38.28% | 43.75% | **89.84%** |
+| **`FINAL-L2a`** | Semantic Extrapolation ($N=256$) | 28.12% | 45.31% | 50.39% | **86.33%** |
+| **`FINAL-L2b`** | Relational Extrapolation ($N=256$) | 22.27% | 62.50% | **65.23%** | 55.08% |
+| **`FINAL-L3`** | Double Extrapolation ($N=512$) | 25.20% | 60.94% | **65.43%** | 56.84% |
+| **`Aggregate`** | Total locked holdout pool ($N=1,536$) | 37.17% | 59.90% | 63.80% | **73.18%** (1,124/1,536) |
+
+*Multi-seed aggregate mean across Seeds 42, 43, 44 is **71.74%** ($\pm 1.97\%$).*
+
+**Permutation Equivariance:** $\text{TVD} = 0.000000$ across all 24 permutations.  
+**Inference Speedup:** $5.08\times$ faster than 24-permutation symmetrized causal baseline ($83.71\text{ ms}$ vs $425.31\text{ ms}$ on A100).
+
+---
+
+## Known Boundaries & Model Limitations
+
+1. **Dynamic-$K$ Scientific Generalization:** While the runtime supports arbitrary $K \ge 2$ and exact permutation equivariance holds algebraically, empirical benchmark accuracy ($94.14\%$, $89.84\%$, etc.) was evaluated on 4-choice tasks ($K=4$). Experimental generalization to arbitrary $K$ has not been independently established in the scientific benchmarks.
+2. **Novel Relational Operators:** InvariantOne excels at familiar-operator recombination ($89.84\%$) and semantic domain transfer ($86.33\%$). However, completely unseen operator grammars drop to $55.08\%$ ($L_{2b}$) and $56.84\%$ ($L_3$), where 24-permutation causal averaging remains stronger ($65.43\%$).
+3. **Top-1 Argmax Tie Breaking:** While the output probability distribution is strictly permutation-equivariant ($\text{TVD} = 0.000000$), argmax top-1 selection exhibits a $1.56\%$ flip rate under exact floating-point ties.
+4. **No Generative Explanations:** InvariantOne is a dedicated decision model; it does not produce token-by-token natural-language rationales.
+5. **Confidence Estimates:** Probabilities represent model confidence estimates and are not safety-critical certification guarantees.
+
+---
+
+## Documentation & Research
+
+- **Model Card:** [`model_card/MODEL_CARD.md`](model_card/MODEL_CARD.md)
+- **Academic Paper:** [`paper/main.pdf`](paper/main.pdf)
+- **Release Manifest:** [`INVARIANTONE_V1_RELEASE_MANIFEST.json`](INVARIANTONE_V1_RELEASE_MANIFEST.json)
+- **License Audit:** [`RELEASE_LICENSE_AUDIT.md`](RELEASE_LICENSE_AUDIT.md)
+
+---
+
+## License
+
+InvariantOne is licensed under the [Apache 2.0 License](LICENSE).
+Base foundation model weights are licensed under the upstream Apache 2.0 license by Alibaba Cloud.

invariantone-1.0.0/cli/__init__.py

@@ -0,0 +1,7 @@
+"""
+CLI package for InvariantOne.
+"""
+
+from cli.invariantone_cli import main
+
+__all__ = ["main"]