Metadata-Version: 2.4
Name: pre-reasoning
Version: 2.5.4
Summary: 3M-parameter neural pre-reasoning engine for grounding LLMs before they answer.
Author: Luis Lozano, Dr. Shannon (Mia Labs AI co-researcher), Mia Labs
License-Expression: MIT
Project-URL: Repository, https://github.com/luislozanogmia/pre-reasoning
Keywords: reasoning,llm,graph,deterministic
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: torch>=2.0.0
Requires-Dist: safetensors>=0.4.0
Provides-Extra: dev
Requires-Dist: pytest>=8.0.0; extra == "dev"
Dynamic: license-file

# Pre-Reasoning

Pre-Reasoning is a Mia Labs structural analysis engine that grounds an LLM before it answers. It uses a 3M-parameter neural perception model plus a bundled tiny derive expert to surface dependencies, derived assumptions, root blockers, unlock order, parallel work, cycles, and conflicts from problem text.

The engine ships with bundled weights and declares its torch dependency -- install and run, no model download needed.

## What It Does

Given natural-language problem text, the engine returns:

- ROOT BLOCKERS: what must be resolved first
- UNLOCK SEQUENCE: a dependency-aware resolution order
- PARALLEL WORK: independent items that can proceed now
- CYCLES: circular dependencies that cannot be solved sequentially
- CONFLICTS: competing positions or incompatible entities
- REQUIREMENTS: numeric or threshold requirements
- DERIVED ASSUMPTIONS: transitive dependency assumptions inferred by the tiny derive expert
- BLOCK OUTPUT: direct and derived structural blocks used by the graph reasoner

## Install

```bash
pip install pre-reasoning
```

For local development from this repo:

```bash
pip install -e .
```

## Python Usage

```python
from pre_reasoning import analyze, pulse

result = analyze("Frontend depends on API. API depends on Auth.")
print(result["trace"])
print(result["derived_assumptions"])

check = pulse(
    "Frontend depends on API. API depends on Auth.",
    "Fix Auth first, then verify the API before frontend work."
)
print(check["status"])
```

## CLI Usage

```bash
pre-reasoning "A depends on B. B depends on C."
pre-reasoning --json "CTO conflicts with senior dev."
pre-reasoning --info
```

To use a different weights file, set `PRE_REASONING_CHECKPOINT=/path/to/weights.safetensors` or pass `--checkpoint`.

## Results

Early comparison table, illustrative, n=5 architectural decision problems:

| Comparison | Illustrative result, n=5 |
|---|---:|
| 9B + trace vs 32B baseline | 3W 2T 0L |
| 9B + trace vs 120B baseline | 4W 1T 0L |
| 120B + trace vs 120B baseline | 3W 2T 0L |

These are product-research notes, not benchmark claims.

## Architecture

```text
User text
  -> neural perception (3M params, safetensors)
  -> neural findings converted to structural blocks
  -> tiny derive expert infers transitive assumptions
  -> derived assumptions appended as dependency blocks
  -> graph reasoning
  -> structural trace
```

## File Map

| Path | Purpose |
|---|---|
| `pre_reasoning/` | Installable Python package and CLI entry point |
| `pre_reasoning/inference.py` | 3M-parameter neural perception layer |
| `pre_reasoning/heuristic.py` | Graph-reasoning core |
| `pre_reasoning/pre_reasoning_v2_5_2.py` | Default v2.5.4 engine: neural perception + derive expert + graph reasoning |
| `pre_reasoning/pre_reasoning_v2_5.py` | Legacy v2.5 engine: neural perception + graph reasoning |
| `pre_reasoning/checkpoints/pre-reasoning-3m-v2.5.safetensors` | Bundled model weights (11MB) |
| `derive_expert/` | Tiny derive expert used for transitive-closure enrichment |
| `derive_expert/weights/thin_expert_d128L3.safetensors` | Bundled derive expert weights (2.5MB) |
| `examples/` | Runnable usage examples |
| `tests/` | Pytest suite |
| `skill/SKILL.md` | Agent skill descriptor for model adoption |
| `hooks/` | Claude Code before/after hooks for enforced pre-reasoning |
| `INSTALL.md` | Manual install and hook setup guide |
| `CLAUDE.md` | Claude Code adoption and grounding-hook guide |
| `WHY_TRACES_WORK.md` | Literature connection, 9 cited papers |

## Weights Policy

The raw training checkpoint is not part of the release. The package bundles `pre_reasoning/checkpoints/pre-reasoning-3m-v2.5.safetensors` for neural perception and `derive_expert/weights/thin_expert_d128L3.safetensors` for the tiny derive expert. These are inference artifacts. They ship no optimizer state, LR schedules, step counters, RNG state, training config, or raw checkpoint provenance.

## License

MIT License. See `LICENSE`.

## Authors

Luis Lozano and Dr. Shannon, Mia Labs' AI co-researcher, 2026.
