Pre-Reasoning

Pre-Reasoning is a Mia Labs structural analysis engine for grounding an LLM before it answers. It surfaces dependencies, root blockers, unlock order, parallel work, cycles, and conflicts from problem text.

The shipped system has two modes:

Mode	What runs	Parameters	Heavy dependencies	Best for
Lite	Deterministic text patterns + graph reasoning	0	None	Lightweight grounding, local hooks, package default
Full	Lite core + optional neural perception layer	about 3M	`torch` + bundled safetensors weights	Neural conflict, cycle, and requirement detection

The deterministic graph-reasoning core is genuinely 0-parameter. Neural perception features are not 0-parameter and require the optional [neural] extra plus the bundled weights-only safetensors artifact.

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 in full mode when neural perception is available

Lite mode can detect explicit dependency, cycle, and conflict patterns with no model, no torch, and no weights. Full mode can enrich that analysis with the 3M-parameter neural perception layer in reasoning_v3.py.

Install

pip install pre-reasoning

For local development from this repo:

pip install .

Optional extras:

pip install "pre-reasoning[api]"      # REST API dependencies
pip install "pre-reasoning[mcp]"      # MCP server dependencies
pip install "pre-reasoning[neural]"   # torch for full neural mode

Python Usage

from pre_reasoning import analyze, pulse

result = analyze("Frontend depends on API. API depends on Auth.", mode="lite")
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

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

Full mode requires the neural extra. The weights-only safetensors file is bundled with the package, so clone/install works offline:

pip install "pre-reasoning[neural]"
pre-reasoning "A depends on B. B conflicts with C."

To test a different converted weights file, set PRE_REASONING_CHECKPOINT=/path/to/weights.safetensors or pass --checkpoint. If neural dependencies or weights are missing, the engine falls back to lite mode and reports the reason in engine_info().

REST API and MCP

The REST API and MCP server are optional service surfaces:

pip install "pre-reasoning[api]"
python reasoning_api.py

pip install "pre-reasoning[mcp]"
python reasoning_mcp.py

REST examples:

curl -X POST http://localhost:8420/analyze \
  -H "Content-Type: application/json" \
  -d '{"text": "Frontend depends on API. API depends on Auth. CTO conflicts with senior dev."}'

MCP with Claude Code:

claude mcp add mia-reasoning-engine -- python /path/to/reasoning_mcp.py

Results

The early comparison table below is illustrative and based on 5 architectural decision problems. It is not yet a reproducible benchmark because the exact problem set and run harness are not included in this repo.

Comparison	Illustrative result, n=5	Current status
9B + trace vs 32B baseline	3W 2T 0L	Needs reproducible eval harness
9B + trace vs 120B baseline	4W 1T 0L	Needs reproducible eval harness
120B + trace vs 120B baseline	3W 2T 0L	Needs reproducible eval harness

Use these as product-research notes, not benchmark claims. See eval/README.md for the reproducibility gap.

Architecture

Lite mode:
User text
  -> deterministic text_to_blocks adapter
  -> ReasoningEngineV2 graph analysis
  -> structural trace

Full mode:
User text
  -> ReasoningEngineV3 neural perception, if torch + safetensors weights are available
  -> V3 findings converted to V2 blocks
  -> ReasoningEngineV2 graph analysis
  -> neural-enriched structural trace

The graph core is deterministic. The optional neural layer is a learned perception layer for richer extraction and validation.

File Map

Path	Purpose
`pre_reasoning/`	Installable Python package wrapper and CLI entry point
`reasoning_v2.py`	0-parameter deterministic graph-reasoning core
`reasoning_v3.py`	Optional about-3M-parameter neural perception layer, requires torch
`reasoning_v25.py`	Hybrid orchestrator with full/lite modes
`pre_reasoning/checkpoints/pre-reasoning-3m-v2.5.safetensors`	Bundled weights-only neural inference artifact
`reasoning_api.py`	Optional FastAPI REST service
`reasoning_mcp.py`	Optional MCP server
`examples/`	Runnable usage examples
`tests/`	Pytest suite for lite mode behavior
`eval/README.md`	Reproducibility status for the illustrative results
`scripts/inspect_weights.py`	Bundled weights inspection helper
`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. The safetensors format also avoids public pickle loading.

Base installs are intentionally lightweight and default to lite mode with no torch and no weights loaded. To use full mode, install the neural extra; the bundled safetensors file is used automatically. PRE_REASONING_CHECKPOINT and --checkpoint are only overrides for another .safetensors file.

License

MIT License. See LICENSE.

Authors

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