English | Bahasa Indonesia | 简体中文 | 日本語 | 한국어 | Español | Français | Deutsch | Русский | العربية

Dual-Loop Cognitive Controller

State-of-the-Art Latent Deliberation & Cognitive Reasoning Framework for Any Transformer Model

What is Dual-Loop Cognitive Controller?

Standard autoregressive Transformers perform uniform $O(1)$ computation per token regardless of task complexity. While Chain-of-Thought (CoT) prompting enables multi-step reasoning, it consumes heavy output token bandwidth, creates severe serial latency, and exposes models to prompt distraction. Conversely, naive recurrent pondering suffers from overthinking (corrupting commonsense intuition) and the unsupervised falsification trap (second-guessing correct initial predictions).

Dual-Loop Cognitive Controller is a universal model-enhancement framework that equips any Transformer architecture with dual-process System 1 (intuitive) and System 2 (deliberative) reasoning:

• Outer Loop (System 2 / Latent Deliberation): Executes recursive mental simulation in continuous latent space without emitting intermediate discrete tokens.
• Inner Loop (System 1 / Generation): Decodes high-fidelity tokens conditioned on converged thought vectors.
• Cognitive Matrix Helper (Tversky Elimination-by-Aspects): Screens candidate options in Bench 1, eliminates distractor wrong logs, and focuses deliberation strictly on surviving contenders in Bench 2.
• Hippocampal Episodic Virtual Memory: Stores verified reasoning traces as Settled Anchors, enabling instant ($<0.01\text{s}$) zero-compute shortcut recall.
• Directional Safety Projection: Mathematically shields confident predictions from degradation, guaranteeing Zero Negative Drift.

Universal Compatibility: Works with Any Transformer

dual-loop-controller attaches seamlessly via non-invasive PyTorch forward hooks to any standard causal language model. No modifications to your underlying model weights are required:

Installation

Works with Python 3.9+ and PyTorch 2.0+.

With pip:

pip install dual-loop-controller

With uv:

uv pip install dual-loop-controller

Install with LLM dependencies (Transformers & Accelerate):

pip install "dual-loop-controller[llm]"

Install from Source:

git clone https://github.com/Ch3nOff/dual-loop-controller.git
cd dual-loop-controller
pip install -e .

Quickstart

1. Attach Dual-Loop to ANY Hugging Face Model in 3 Lines

You can attach the controller to any model family (Llama, Mistral, Qwen, Gemma, etc.) using the universal attach_dual_loop factory:

import torch
from transformers import AutoModelForCausalLM, AutoTokenizer
from dual_loop import attach_dual_loop

# Step 1: Load your favorite Hugging Face model
model_id = "meta-llama/Meta-Llama-3-8B-Instruct"  # or "mistralai/Mistral-7B-v0.3", "Qwen/Qwen2.5-7B", "google/gemma-2-9b"
tokenizer = AutoTokenizer.from_pretrained(model_id)
base_model = AutoModelForCausalLM.from_pretrained(model_id, torch_dtype=torch.bfloat16, device_map="auto")

# Step 2: Attach Dual-Loop Cognitive Controller
# layer_idx defaults to the optimal midpoint layer automatically
model = attach_dual_loop(base_model, k_steps=2)

# Step 3: Run inference with latent System 2 pondering
prompt = "Question: Under an inverted buoyancy physics law, denser objects float. If lead and cork drop in water, which floats?\nAnswer:"
inputs = tokenizer(prompt, return_tensors="pt").to(base_model.device)

# Model deliberates in latent space before generating output tokens
output = model.generate(**inputs, max_new_tokens=64)
print(tokenizer.decode(output[0], skip_special_tokens=True))

2. Multi-Choice Solving with 2-Bench Cognitive Matrix Helper

For challenging multiple-choice tasks (medical diagnosis, science QA, legal entailment), use CognitiveMatrixHelper to eliminate distractor options (wrong logs) and focus System 2 attention on surviving contenders:

import numpy as np
from dual_loop import CognitiveMatrixHelper

# Initialize helper with adaptive distractor cutoff
matrix_helper = CognitiveMatrixHelper(elimination_threshold=0.12, min_survivors=2)

# Bench 1: Raw candidate scores from base model
scores_bench1 = [-9.1488, -9.2891, -9.5007, -11.0977, -10.9492]
labels = ["D", "E", "F", "A", "B"]

# Step 1: Populate Cognitive Evidence Matrix & prune distractors
matrix = matrix_helper.build_evidence_matrix(scores_bench1, labels=labels)
print("Pruned Distractor Logs :", matrix["eliminated_labels"])  # -> ['A', 'B'] (Noise eliminated)
print("Surviving Contenders    :", matrix["survivor_labels"])    # -> ['D', 'E', 'F'] (Viable dilemma)

# Bench 2: System 2 deliberates strictly on surviving candidates [D, E, F]
scores_delib_survivors = [-6.9465, -5.8747, -4.4858]

# Step 2: Fuse scores (eliminated distractors are locked to -infinity)
final_scores = matrix_helper.fuse_scores(
    scores_base=scores_bench1,
    scores_delib_survivors=scores_delib_survivors,
    survivor_indices=matrix["survivors"],
    lambda_delib=0.85
)

best_idx = np.argmax(final_scores)
print("Final Rescued Decision :", labels[best_idx])  # -> 'F' (Correct Answer!)

3. Accelerated Reasoning with Hippocampal Virtual Memory

Enable human-like memory consolidation where familiar queries bypass deliberation with instant $<0.01\text{s}$ retrieval (3,146x speedup):

import torch
from dual_loop import CognitiveWorkingMemory
from dual_loop.memory import EpisodicMemoryBuffer

# Initialize continuous key-value memory bank
memory = EpisodicMemoryBuffer(d_model=2048, capacity=512, sim_threshold=0.95)

# Store verified reasoning trace
query_vector = torch.randn(1, 2048)
thought_vector = torch.randn(1, 2048)

memory.store(
    key=query_vector,
    thought=thought_vector,
    margin=0.45,
    meta={"answer": "F", "task": "colored_objects"},
    is_settled=True
)

# Recall instantly on subsequent encounters (Zero FLOPs, Zero Token Waste)
match = memory.recall_settled(query_vector, sim_threshold=0.95)
if match:
    print("Instant Memory Recall:", match["metadata"]["answer"])

Why Should I Use Dual-Loop Controller?

• Universal Compatibility: Works with Llama, Mistral, Qwen, Gemma, DeepSeek, and any causal LM.
• Zero Output Token Waste: Deliberates in continuous latent thought space instead of generating hundreds of CoT scratchpad tokens.
• Distractor Elimination (Amos Tversky EBA): Solves multi-choice attention dilution by filtering superficial distractor options.
• Zero Negative Drift Guarantee: Directional Safety Projection ensures confident intuitive answers are never degraded.
• Hardware-Aligned & Cache-Friendly: Cognitive Working Memory (CWM) fits directly inside GPU SRAM / L2 cache, eliminating redundant KV-cache lookups.
• 100% Offline & Private: Runs entirely locally on your machine or server. Zero external API bills, zero data leakage.

When Shouldn't I Use Dual-Loop Controller?

• Pure Embedding Models: Dual-Loop is designed for generative causal autoregressive decoders, not encoder-only models (like BERT) without generation heads.
• Ultra-Low Latency Sub-5ms Audio Streams: Latent pondering adds a small computational budget ($K$ iterations) at an intermediate layer, suited for high-accuracy reasoning rather than hard real-time streaming audio.

Benchmark Suite & Empirical Research

For comprehensive benchmarks (including ARC-Challenge, Big-Bench Hard, 20-Task Macro Suites, and procedural stress tests), please consult BENCHMARKS.md and eval_results/.

Citation

If you use dual-loop-controller in your research or production systems, please cite:

@software{chen2026dualloop,
  author = {Matthew Chen and Contributors},
  title = {Dual-Loop Cognitive Controller: Hardware-Aligned Latent Deliberation & Memory Architecture for Transformers},
  year = {2026},
  publisher = {PyPI},
  version = {2.2.1},
  url = {https://github.com/Ch3nOff/dual-loop-controller}
}

License

This project is licensed under the MIT License.