# Modular Reasoning Scaffold (MRS) — v1.1.4
### Author: Sabouhi (2025)
Lightweight Meta-Reasoning Architecture for Small & Medium LLMs

## Overview
MRS is a model-agnostic meta-reasoning architecture that overlays an explicit recursive structure on top of any language model (LLM) without modifying its weights. It gives tiny models the ability to:
- maintain intermediate variables  
- perform structured multi-step reasoning  
- detect drift and stabilize outputs  
- ground reasoning through rules and patterns  
- execute self-correction and verification steps  

MRS behaves like a symbolic cognitive skeleton wrapped around an LLM, providing:
- State slots (persistent memory)  
- Update rules (monotonic + stable transformations)  
- Constraint layers (drift, contradiction, instability)  
- Topology engine (flow, recursion, branching, halting)  

This creates the effect of a “larger mind’’ without increasing parameter scale.

## Why MRS Matters
Small LLMs normally fail at reasoning because they cannot:
1. Store intermediate results  
2. Maintain coherence across steps  
3. Prevent drift or contradictions  
4. Stabilize their own trajectories  

MRS externally supplies these abilities through structure rather than scale.

It is:
- Model-agnostic  
- Parameter-free  
- Computationally cheap  
- Robust against drift  
- Transparent and interpretable  

Ideal for:
- On-device / low-resource reasoning  
- Safety layers  
- Interpretability research  
- Emergent behavior study  
- Multi-agent coordination  
- Deterministic / reproducible inference  

## Core Components

### 1. Recursion Nodes (Rᵢ)
```
Rᵢ = (input xᵢ, rule φᵢ, drift Δᵢ, output oᵢ)
```

### 2. State Trackers (S)
Persistent memory for slots and signatures.

### 3. Constraint Monitors (C)
Guardrails preventing collapse.

### 4. Topology Engine (𝒯)
Determines recursion depth, continuation, halting, branching.

## Architecture Diagram (v1.2)
```
[Diagram omitted in markdown rendering]
```

## Mathematical Core

Recursion node:
```
Rᵢ = (xᵢ, φᵢ, Δᵢ, oᵢ)
```

State aggregation:
```
Sₙ = {o₁, …, oₙ}
```

Cumulative drift:
```
C(Sₙ) = Σ Δᵢ
```

Continuation:
```
C(Sₙ) < τ
```

Stop:
```
C(Sₙ) ≥ τ
```

Topology:
```
Rᵢ₊₁ = 𝒯(Rᵢ, Sᵢ, C(Sᵢ))
```

## Minimal Reference Implementation
```python
class MRS:
    def __init__(self, model, num_slots=4, max_depth=8):
        self.model = model
        self.slots = [None] * num_slots
        self.max_depth = max_depth
        self.depth = 0

    def update_slot(self, i, value):
        self.slots[i % len(self.slots)] = value

    def drift(self, text):
        return abs(hash(text)) % 1000 / 1000.0

    def run(self, prompt):
        x = prompt
        history = []

        while self.depth < self.max_depth:
            self.depth += 1

            o = self.model(x)
            Δ = self.drift(o)
            history.append((x, o, Δ))

            if Δ > 0.65:
                break

            self.update_slot(self.depth, o)
            x = o

        return {
            "history": history,
            "slots": self.slots,
            "final": history[-1][1]
        }
```

## Example Usage

Run the included example script to see the scaffold in action:

```bash
python example_mrs_usage.py
```

This will demonstrate:
1.  Initializing MRS with slots and limits
2.  Running a query
3.  Inspecting internal metrics (steps, drift, halt reasons)

## Legacy Example
```bash
python scaffold.py --prompt "Explain gravity at two levels of detail."
```

Outputs:
- slot history  
- drift scores  
- stability markers  
- topology transitions  
- verified final answer  

## Roadmap

### v1.2
- upgraded diagrams  
- improved drift monitors  
- clearer slot signatures  

### v1.3
- probabilistic drift model  
- dynamic slot allocation  
- multi-branch topology  

### v1.4
- differentiable topology engine  
- multi-agent shared MRS states  
- hardware/runtime integration  

## Citation
Sabouhi (2025). *Modular Reasoning Scaffold (MRS).*

## Running Tests
```
pytest -q
```

## Contact
For research or collaboration:
Email: sabouhi.research@gmail.com
LinkedIn: https://www.linkedin.com/in/ryan-sabouhi/
