Metadata-Version: 2.4
Name: mrs-scaffold
Version: 1.1.9
Summary: Modular Reasoning Scaffold (MRS) – a lightweight meta-reasoning layer for small LLMs.
Author-email: RJ Sabouhi <symbolicsuite@gmail.com>
Project-URL: Homepage, https://rjsabouhi.github.io/Modular-Reasoning-Scaffold/
Project-URL: Repository, https://github.com/rjsabouhi/Modular-Reasoning-Scaffold
Project-URL: Documentation, https://rjsabouhi.github.io/Modular-Reasoning-Scaffold/
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
License-File: NOTICE
Dynamic: license-file

# MRS v1.0 — Modular Recursion Scaffold
*A lightweight architectural layer for controlled recursive reasoning in small LLMs*

## Overview
Modern language models show emergent reasoning capabilities only once they reach large parameter scales.  
**MRS (Modular Recursion Scaffold)** provides an architectural alternative:  
a *structural layer* that gives even very small models the ability to maintain intermediate variables, reuse prior states, and perform stable multi-step reasoning.

MRS does not modify the underlying model.  
It wraps it with:

- **Memory slots**  
- **State update rules**  
- **Invariant structural constraints**  
- **Recursion operators**

This gives a tiny model **the functional profile of a much larger one**, without requiring scale.

## Why This Matters
Most lightweight models fail at reasoning because they cannot:

1. Store intermediate results  
2. Correct their own trajectories  
3. Maintain stable representations over recursive steps  

MRS adds these abilities explicitly through structure rather than scale.

It is **model-agnostic**, **parameter-free**, and **computationally cheap**.

This makes it ideal for:

- On-device / low-resource models  
- Custom agents  
- Safety layers  
- Interpretability research  
- Experiments in emergent behavior at small scale  

## Core Concepts

### 1. Structural Slots (S)
Named containers that hold intermediate reasoning variables.  
Example:  
`S = {s0, s1, s2, …}`  
Slots persist across recursion steps.

### 2. Update Rules (U)
Explicit functions controlling how each slot transforms.  
Each U is stable, monotonic, or self-correcting.

### 3. Constraint Layer (C)
A lightweight rule set ensuring:

- bounded drift  
- state coherence  
- step-to-step consistency  

C acts like a guardrail system for stability.

### 4. Recursion Operator (R)
The loop engine:  
R(S, U, C) → S′  
applied until termination or max depth.

This combination gives a small model the equivalent of “scratchpad reasoning” without needing the internal capacity of a large transformer.

## Minimal Reference Implementation (C1)

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

    def update(self, model, prompt):
        self.depth += 1
        state_repr = {f"s{i}": v for i, v in enumerate(self.S)}
        inp = {"prompt": prompt, "state": state_repr}
        out = model(inp)
        for i in range(len(self.S)):
            self.S[i] = out.get(f"s{i}", self.S[i])
        if self.depth > self.max_depth:
            return self.S, True
        return self.S, False

    def run(self, model, prompt):
        done = False
        while not done:
            _, done = self.update(model, prompt)
        return self.S
```

## Intended Use

```python
mrs = MRS()
result = mrs.run(small_llm, "Solve this in steps.")
```

## What MRS Enables
- Stable chain-of-thought  
- Deterministic recursive loops  
- Intermediate variable tracking  
- Multi-pass self-correction  
- Mild emergent behavior without scale  
- Interpretability-friendly internal state  
- Reduced hallucination drift  
- Structured reasoning on models as small as 100M parameters  

## Roadmap
### v1.0
- Base scaffold  
- 4 slots  
- Simple update rule  
- Basic drift constraints  
- Terminal recursion depth

### v1.1
- Weighted slot updates  
- Error-corrective constraints  
- Deterministic rollback mode

### v2.0
- Hierarchical recursion  
- Specialized slot types  
- Cross-slot influence graphs  
- Stability metrics  
- Metastability detector  
- External verifier mode

## License
Apache 2.0

## Citation
RJ Sabouhi (2025). Modular Recursion Scaffold v1.0.#
