Metadata-Version: 2.4
Name: pre-reasoning
Version: 2.5.2
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 model (V3) to surface dependencies, root blockers, unlock order, parallel work, cycles, and conflicts from problem text.

The engine ships with bundled safetensors weights and torch -- install and run, no downloads 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

## 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"])

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
  -> V3 neural perception (3M params, safetensors)
  -> neural findings converted to structural blocks
  -> V2 heuristic graph analysis
  -> structural trace
```

## File Map

| Path | Purpose |
|---|---|
| `pre_reasoning/` | Installable Python package and CLI entry point |
| `pre_reasoning/inference.py` | 3M-parameter V3 neural perception layer |
| `pre_reasoning/heuristic.py` | Deterministic graph-reasoning core (fallback) |
| `pre_reasoning/pre_reasoning_v2_5.py` | v2.5 orchestrator: V3 neural + heuristic |
| `pre_reasoning/checkpoints/pre-reasoning-3m-v2.5.safetensors` | Bundled V3 weights (11MB) |
| `examples/` | Runnable usage examples |
| `tests/` | Pytest suite |
| `skill/SKILL.md` | Agent skill descriptor for model adoption |
| `CLAUDE.md` | Optional Claude Code hooks configuration |
| `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`, a weights-only inference artifact. It ships no training metadata: 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.
