Metadata-Version: 2.4
Name: subneutralize
Version: 0.1.2
Summary: Universal Parameter-Free Runtime Inference Governor for Autoregressive Reasoning Models
Author: Arnab Dutta
License: Apache-2.0
Project-URL: Homepage, https://github.com/Arnab758/subneutralize
Project-URL: Bug Tracker, https://github.com/Arnab758/subneutralize/issues
Keywords: deepseek,reasoning,inference-optimization,vllm,test-time-compute,mechanistic-interpretability,overthinking
Classifier: Development Status :: 4 - Beta
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.9
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.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: torch>=2.0.0
Requires-Dist: transformers>=4.40.0
Dynamic: license-file

# SubNeutralize: Universal Runtime Inference Governor for Reasoning Models

[![PyPI version](https://badge.fury.io/py/subneutralize.svg)](https://pypi.org/project/subneutralize/)
[![License](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](https://opensource.org/licenses/Apache-2.0)
[![Python](https://img.shields.io/badge/Python-3.9%2B-blue.svg)](https://www.python.org/)
[![NVIDIA A100](https://img.shields.io/badge/Hardware-NVIDIA%20A100--SXM4--40GB-76B900?logo=nvidia)](https://www.nvidia.com)

> **SubNeutralize** is a parameter-free, scale-free runtime inference governor that eliminates the **"Overthinking Crisis"** in autoregressive reasoning models (DeepSeek-R1, Qwen, and frontier reasoning LLMs) by tracking latent trajectory dynamics and transitioning immediately upon reaching dynamical consensus equilibrium.

---

## ⚡ The Breakthrough: 77.9% Compute Reduction on DeepSeek-R1-32B

In up to 40% of reasoning tasks, models like **DeepSeek-R1** deduce the correct algorithmic solution within the first 80–120 tokens, but then enter an ungrounded monologue loop (*"Wait, let me double check..."*), burning 1,500+ tokens and 2.5 minutes before emitting code.

Evaluated on an **NVIDIA A100-SXM4-40GB** running `DeepSeek-R1-Distill-Qwen-32B` under an identical **1,500-token ceiling** for both Vanilla and SubNeutralize:
* **77.9% Net Compute Reduction:** Total token consumption dropped from **5,698 tokens to 1,261 tokens**.
* **4.51× Wall-Clock Speedup:** Response latency dropped from **596.1s to 132.3s** (from ~2.5 minutes down to ~25 seconds per query).
* **100% Unit Test Pass Rate (4/4 PASS ✓):** Zero accuracy loss or syntax degradation on complex enterprise backend tasks.
* **Zero External Scissoring:** Stopping occurs purely via internal dynamical consensus equilibrium.

---

## 📊 Empirical Benchmarks (NVIDIA A100 SXM4)

### Table 1: Per-Problem Enterprise Coding Benchmark

| Problem ID | Problem Description | Vanilla Tokens (Latency) | SubNeutralize (Th + Co) | Token Savings | Latency Savings | Unit Test Result |
| :--- | :--- | :---: | :---: | :---: | :---: | :---: |
| **PROB-01** | SQL Injection Sanitizer & Query Builder | 1,500t (156.2s) | 87t + 148t (24.6s) | **84.3%** | **84.2%** | **PASS ✓** |
| **PROB-02** | Token Bucket Rate Limiter with Refill | 1,500t (157.0s) | 125t + 218t (35.9s) | **77.1%** | **77.1%** | **PASS ✓** |
| **PROB-03** | JWT Claims & Expiry Validator | 1,198t (125.3s) | 92t + 136t (23.8s) | **81.0%** | **81.0%** | **PASS ✓** |
| **PROB-04** | LRU Cache with Time-To-Live (TTL) | 1,500t (157.6s) | 101t + 354t (47.9s) | **69.7%** | **69.6%** | **PASS ✓** |

### Table 2: Infrastructure ROI & Deployment Impact

| Metric | Vanilla Baseline | SubNeutralize | Net Improvement |
| :--- | :---: | :---: | :---: |
| **Total Tokens Consumed** | 5,698 | **1,261** | **77.9% Compute Saved** |
| **Total Inference Latency** | 596.1 s | **132.3 s** | **4.51× Faster** |
| **Average Query Latency** | 149.0 s | **33.1 s** | **-115.9 s per query** |
| **Verified Unit Tests Passed** | 4/4 | **4/4** | **100% Correctness** |
| **Estimated GPU Bill / 1M Queries** | $3,800 USD | **$841 USD** | **-$2,959 USD per 1M queries** |

---

## 🚀 Quickstart

### 1. Installation
```bash
pip install subneutralize
```

---

### 2. Method A: Instant Terminal CLI (Zero Python Code)

Run SubNeutralize on any custom prompt directly from your terminal:

```bash
# Direct governed generation on any prompt
subneutralize "Write a thread-safe token bucket rate limiter in Python"

# Run a live head-to-head comparison vs. unconstrained Vanilla baseline
subneutralize --compare "Write a thread-safe token bucket rate limiter in Python"

# Launch the interactive prompt shell
subneutralize
```

---

### 3. Method B: 2 Lines in Python

```python
import torch
from transformers import AutoModelForCausalLM, AutoTokenizer
from subneutralize import SubNeutralize

# 1. Load any reasoning model (DeepSeek-R1, Qwen-QwQ, etc.)
model_id = "deepseek-ai/DeepSeek-R1-Distill-Qwen-1.5B" # Or 7B / 14B / 32B
tokenizer = AutoTokenizer.from_pretrained(model_id)
model = AutoModelForCausalLM.from_pretrained(model_id, torch_dtype=torch.bfloat16, device_map="auto")

# 2. Wrap with SubNeutralize (automatically resolves cognitive midpoint layer)
engine = SubNeutralize(model, tokenizer)

# 3. Generate governed response on ANY prompt
output = engine.generate("Write a thread-safe token bucket rate limiter in Python:")

print(output.clean_code)
print(f"Thinking Tokens: {output.thinking_tokens} | Code Tokens: {output.code_tokens}")
print(f"Latency: {output.wall_clock_seconds:.1f}s | Consensus Reached: {output.consensus_reached}")
```

---

### 4. Method C: Drop-in `StoppingCriteria` for Existing Pipelines

If you already have an existing generation loop or server calling `model.generate()`, drop SubNeutralize directly into your stopping criteria:

```python
engine = SubNeutralize(model, tokenizer)

outputs = model.generate(
    **inputs,
    max_new_tokens=1500,
    stopping_criteria=[engine.as_stopping_criteria()]
)
```

---

## 🔬 How It Works (The Mathematics)

### 1. Latent Manifold Cosine Velocity
SubNeutralize listens to residual representations at the model's cognitive bottleneck layer (situated at $\approx 50\%$ depth). At decoding step $t$, the directional velocity of the representation trajectory is:
$$v_t = 1 - \frac{h_t \cdot h_{t-1}}{\|h_t\|_2 \|h_{t-1}\|_2}$$

### 2. Dimension-Invariant Scale-Free Momentum Ratio ($R_t$)
Because absolute velocity scales differently across model dimensions ($d=3584$ for 7B vs $d=5120$ for 32B), SubNeutralize normalizes instantaneous velocity against its own Exponential Moving Average (EMA):
$$\text{EMA}_t(v) = \alpha v_t + (1 - \alpha) \text{EMA}_{t-1}(v), \quad \alpha = 0.10$$
$$R_t = \frac{v_t}{\text{EMA}_t(v)}$$

### 3. Consensus Equilibrium Condition
Equilibrium is mathematically certified when:
$$t \ge 60 \quad \text{and} \quad (R_t < 0.82 \quad \text{or} \quad v_t < 0.135)$$
Once stabilized across a 2-token persistence debounce window, SubNeutralize cleanly transitions the model from internal monologue into greedy code emission.

---

## 🧪 Running the Enterprise Benchmark

Run the full 4-problem enterprise test suite (SQL Injection Sanitizer, Token Bucket Rate Limiter, JWT Validator, LRU Cache with TTL) locally:

```bash
python -m subneutralize.benchmark
```

---

## 📜 Citation

If you use SubNeutralize in your research or production systems, please cite:
```bibtex
@article{dutta2026subneutralize,
  title={SubNeutralize: The Geometry of Reasoning and the Elimination of the Overthinking Trap},
  author={Dutta, Arnab},
  journal={arXiv preprint},
  year={2026}
}
```

## 📄 License
Apache-2.0 License. Free for commercial and research use.
