Metadata-Version: 2.1
Name: mrs-scaffold
Version: 1.1.3
Summary: MRS (Modular Reasoning Scaffold): a mesoscale architecture for symbolic meta-reasoning and recursive cognitive pipelines.
Home-page: https://github.com/rjsabouhi/Modular-Reasoning-Scaffold
Author: Sabouhi
License: MIT
Requires-Python: >=3.8
Description-Content-Type: text/markdown
Classifier: Programming Language :: Python :: 3
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence

# Modular Reasoning Scaffold (MRS) — v1.1
### 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 needing 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_i = (x_i, φ_i, Δ_i, o_i)
```

State aggregation:
```
S_n = {o_1, ..., o_n}
```

Cumulative drift:
```
C(S_n) = Σ Δ_i
```

Continuation:
```
C(S_n) < τ
```

Stop:
```
C(S_n) ≥ τ
```

Topology:
```
R_{i+1} = T(R_i, S_i, C(S_i))
```

## 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
```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).*  

## Contact
For research and collaboration inquiries:  
**Sabouhi (2025)**  

