# Modular Reasoning System (MRS-Core)
*A deterministic, operator-based reasoning engine for LLMs and autonomous agents.*

MRS-Core provides a transparent, modular, reproducible reasoning substrate built from a small set of reusable operators:

- Transform  
- Reflect  
- Evaluate  
- Rewrite  
- Summarize  
- Inspect  
- Filter  

MRS makes reasoning traceable, auditable, and deterministic all without requiring chain-of-thought exposure or hidden model internals.

---

# Why MRS-Core Exists

### Every agent framework today suffers from the same structural failures:

- No consistent reasoning sequence  
- No deterministic backbone  
- No visibility into intermediate states  
- No enforceable phases or operator logic  

### MRS-Core solves this by introducing:

- Explicit operator-level reasoning  
- Strict phase transition model  
- Complete execution trace  
- Deterministic, reproducible outputs  
- Plug-and-play integration for ANY agent system  

MRS is **not** an alignment system.  
MRS is **not** a sandbox.  
### MRS is a *reasoning substrate*.

---

# Features

### Deterministic Reasoning Chains  
- Operators execute in strict order.  
- Output is repeatable.

### Transparent Logs & History  
MRS records:  
- final text  
- operator log  
- phase trace  
- structured history of every step  

### Simple, Extensible Operators  
- Each operator is a small Python class registered via the Operator Registry.

### Drop-In Presets  
`simple`, `reasoning`, `full_chain` presets included for immediate use and extension.

---

# Install

```bash
pip install mrs-core
```

---


# Quick Start
```bash
from mrs.engine import MRSCoreEngine
from mrs.presets import get_preset

engine = MRSCoreEngine()
ops = get_preset("reasoning")

result = engine.run_chain(ops, "MRS-Core is a modular deterministic reasoning pipeline.")

print(result["text"])
print(result["log"])
print(result["phase"])
```
---

# Example Output
```bash 
FINAL TEXT:
[REFLECT] [TRANSFORM] THIS IS A TEST OF MRS-CORE.
[EVAL CHARS=49 WORDS=8]

LOG:
- Transform applied
- [PHASE] start → transform
- Reflect applied
- [PHASE] transform → reflect
- Evaluate applied
- [PHASE] reflect → evaluate
- Rewrite applied
- [PHASE] evaluate → rewrite
```
---

# Running a Manual Operator Chain
```bash
from mrs.engine import MRSCoreEngine

engine = MRSCoreEngine()

ops = [
    ("transform", {}),
    ("reflect", {}),
    ("evaluate", {}),
    ("rewrite", {}),
]

result = engine.run_chain(ops, "Explain symbolic reasoning.")

print(result["text"])
print(result["history"])
```
---

# Using Presets

### MRS-Core includes preset chains:
- simple
- reasoning
- full_chain

```bash
from mrs.engine import MRSCoreEngine
from mrs.presets import get_preset

engine = MRSCoreEngine()

for name in ["simple", "reasoning", "full_chain"]:
    ops = get_preset(name)
    result = engine.run_chain(ops, "MRS-Core preset test")
    print(f"=== {name.upper()} ===")
    print(result["text"])
```

Note: Presets are *example chains*, not semantic models.
Operators are deterministic components; their meaning depends on the chain design. 
`full_chain` is intentionally simple and does not represent a cognitive process.

---

# Operator Anatomy

### Every operator:
- receives the current ReasoningState
- modifies state.text
- appends to state.log
- engine updates state.phase automatically based on the operator's phase transition rules
- records an entry in state.history

### Example:
```bash
@register_operator("reflect")
class ReflectOperator(Operator):
    phase = ("transform", "reflect")

    def run(self, state, **kwags):
        state.text = f"[REFLECT] {state.text}"
        state.log.append("Reflect applied")
        return state
```
---

# Project Structure
```bash
mrs-core/
    engine.py
    registry.py
    state.py
    presets.py
    exceptions.py
    operators/
        base.py
        transform.py
        reflect.py
        evaluate.py
        rewrite.py
        summarize.py
        inspect.py
        filter.py
tests/
examples/
```
---

# What MRS-Core Is Not

### MRS-Core is **NOT**:
- an alignment system  
- a safety guarantee  
- a sandbox  
- a replacement for secure execution layers  

### MRS-Core **IS**:
- a deterministic reasoning layer  
- an operator execution engine  
- an audit-friendly cognition scaffold  
- a missing substrate for agent stability  

---

# Contributing

PRs welcome, especially new operators, presets, or diagnostics.

---

# License

Apache 2.0 (see LICENSE file).

Copyright 2026  
Ryan Sabouhi

---

# Notice

This software contains original work developed as part of the  
**Modular Reasoning System (MRS-Core)** by **Ryan Sabouhi**.  
See the `NOTICE` file for attribution details.

#