Skip to content

About

JEV InvariantOne: Order-Equivariant Decision Model & Zero-Bias Action Routing for AI Agents

Topics

Resources

Contributing

Stars

2 stars

Watchers

1 watching

Forks

Repository files navigation

JEV InvariantOne

JEV InvariantOne is an order-equivariant decision model that scores runtime-defined options directly without candidate-order bias.

Hugging Face Model | Live Demo

Python 3.10+ License: Apache 2.0 Model: D5-L4 Equivariance: Exact


Overview

Many LLM-based multi-option decision pipelines and AI agent routers evaluate candidates jointly in a single prompt, using next-token logits, sequence scoring, or generated answer tokens. Joint candidate presentation introduces severe option-order sensitivity and position bias, while exhaustive permutation symmetrization requires evaluating all $K!$ candidate orders.

JEV 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. Analytic Distributional Permutation Equivariance: Option-span pooled representations pass into a lightweight direct comparative head (Projection: $\text{Linear}(2560 \to 256) \to \text{LayerNorm}(256)$; Absolute Scorer: $\text{Linear}(256 \to 256) \to \text{SiLU} \to \text{Linear}(256 \to 1)$), producing scalar scores normalized via calibrated softmax. The candidate-independent scoring architecture is exactly permutation-equivariant by construction in real arithmetic. In the finite-precision implementation audit, the measured distributional TVD was 0.000000 to six decimal places across all tested permutations. Discrete argmax selection showed a 1.56% top-choice flip rate in tied/near-tied cases due to tie-breaking behavior.
  3. Calibrated Confidence: Output probabilities are normalized with a frozen temperature parameter ($\tau^* = 1.0091$).

Architecture & Specifications

Component Specification
Base Model Qwen/Qwen3.5-4B-Base (32 transformer layers, $d_{\text{model}} = 2560$)
Backbone Status Layers 0–27 strictly frozen (zero parameter updates)
LoRA Adaptation Layers 28–30 (in_proj_qkv, out_proj) and layer 31 (q_proj, v_proj, o_proj); $r=8, \alpha=16$
Active LoRA Parameters 585,728 parameters
Readout Head DirectComparativeHead: Projection (Linear(2560 → 256, bias=True) → LayerNorm(256)) + Absolute Scorer (Linear(256 → 256, bias=True) → SiLU → Linear(256 → 1, bias=True))
Active Head Parameters 722,177 parameters (frozen absolute_only inference mode: 656,128 projection + 66,049 scorer)
Auxiliary Stored Head Parameters 262,657 parameters (pair_net, stored in head.pt checkpoint but bypassed during v1 inference)
Total Stored Head Parameters 984,834 parameters (in checkpoint file head.pt)
Total Active Adapted Parameters 1,307,905 parameters (585,728 LoRA + 722,177 Head; <0.05% of base model)
Permutation Equivariance Mathematically exact by construction in real arithmetic (measured TVD = 0.000000 to six decimal places)
Calibration Temperature $\tau^* = 1.0091$ (pre-calibrated temperature scaling)

Installation

# Install from PyPI
pip install invariantone

# With optional HTTP server support
pip install "invariantone[server]"

# Or install from repository
git clone https://github.com/tradertanmay/InvariantOne.git
cd InvariantOne
pip install -e .

Quickstart

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:

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:

# 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:

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)

# 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:

invariantone serve --port 8000

Execute inference via REST:

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: Measured finite-precision $\text{TVD} = 0.000000$ across all 24 permutations (exact by construction in real arithmetic).
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: Discrete argmax selection showed a 1.56% top-choice flip rate in tied/near-tied cases due to tie-breaking behavior under finite floating-point precision. The underlying continuous probabilistic output distribution is strictly permutation-equivariant in real arithmetic.
  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

The v1 public release includes the runtime, tests, checkpoint hashes, model card, and release manifest. The full FINAL-HOLDOUT-V2 evaluation corpus and generation pipeline are not included in this repository.


License

InvariantOne is licensed under the Apache 2.0 License. Base foundation model weights are licensed under the upstream Apache 2.0 license by Alibaba Cloud.

About

JEV InvariantOne: Order-Equivariant Decision Model & Zero-Bias Action Routing for AI Agents

Topics

Resources

Contributing

Stars

2 stars

Watchers

1 watching

Forks

Releases

Packages

Contributors

Languages