Metadata-Version: 2.4
Name: ebrm-system
Version: 0.8.0
Summary: EBRM System — a full reasoning pipeline with hierarchical latents, adaptive test-time compute, symbolic verification, and self-consistency voting.
Project-URL: Homepage, https://github.com/piyushptiwari1/ebrm-system
Project-URL: Documentation, https://piyushptiwari1.github.io/ebrm-system
Project-URL: Repository, https://github.com/piyushptiwari1/ebrm-system
Project-URL: Issues, https://github.com/piyushptiwari1/ebrm-system/issues
Project-URL: Related (v2 paper), https://github.com/piyushptiwari1/ebrm
Author-email: Piyush Tiwari <piyush@bytical.ai>
License: Apache-2.0
License-File: LICENSE
Keywords: ai,energy-based-model,inference,llm,reasoning,verifier
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Requires-Python: >=3.10
Requires-Dist: numpy>=1.26
Requires-Dist: pydantic>=2.7
Requires-Dist: pyyaml>=6.0
Requires-Dist: rich>=13.7
Requires-Dist: sympy>=1.13
Requires-Dist: typer>=0.12
Provides-Extra: benchmark
Requires-Dist: datasets>=2.20; extra == 'benchmark'
Requires-Dist: pandas>=2.2; extra == 'benchmark'
Requires-Dist: tqdm>=4.66; extra == 'benchmark'
Requires-Dist: trackio>=0.2; extra == 'benchmark'
Provides-Extra: dev
Requires-Dist: hypothesis>=6.100; extra == 'dev'
Requires-Dist: mypy>=1.11; extra == 'dev'
Requires-Dist: pre-commit>=3.7; extra == 'dev'
Requires-Dist: pytest-cov>=5.0; extra == 'dev'
Requires-Dist: pytest-xdist>=3.6; extra == 'dev'
Requires-Dist: pytest>=8.2; extra == 'dev'
Requires-Dist: ruff>=0.6; extra == 'dev'
Provides-Extra: docs
Requires-Dist: mkdocs-material>=9.5; extra == 'docs'
Requires-Dist: mkdocs>=1.6; extra == 'docs'
Requires-Dist: mkdocstrings[python]>=0.25; extra == 'docs'
Provides-Extra: model
Requires-Dist: torch>=2.4; extra == 'model'
Requires-Dist: transformers>=4.45; extra == 'model'
Description-Content-Type: text/markdown

# ebrm-system

[![CI](https://github.com/piyushptiwari1/ebrm-system/actions/workflows/ci.yml/badge.svg)](https://github.com/piyushptiwari1/ebrm-system/actions/workflows/ci.yml)
[![PyPI version](https://img.shields.io/pypi/v/ebrm-system.svg)](https://pypi.org/project/ebrm-system/)
[![Python 3.10+](https://img.shields.io/badge/python-3.10%2B-blue.svg)](https://www.python.org/downloads/)
[![License: Apache 2.0](https://img.shields.io/badge/License-Apache%202.0-brightgreen.svg)](LICENSE)

> **Energy-Based Reasoning Machine — the system.**
> A production reasoning pipeline: intent routing, adaptive test-time compute, energy-based scoring, external verifier bridge, and self-consistency voting.

This repository is the **system layer** on top of the [ebrm](https://github.com/piyushptiwari1/ebrm) model (research / paper reference). `ebrm-system` is the framework you deploy — `ebrm` is the model you cite.

---

## Why this exists

Modern reasoning LLMs are strong but unverifiable: they emit plausible chains that are hard to check mechanically. `ebrm-system` wraps any base reasoner with a pipeline that makes answers **auditable, budget-aware, and consistency-checked**.

## Architecture

```
query
  │
  ▼
┌──────────────────────────┐
│ 1. Intent Classifier     │   rule-based or neural; emits difficulty + budget
└──────────────────────────┘
  │
  ▼
┌──────────────────────────┐
│ 2. Hierarchical Reasoner │   latent-thought inner loop (Coconut-inspired)
└──────────────────────────┘
  │
  ▼
┌──────────────────────────┐
│ 3. Adaptive Langevin     │   steps scale with difficulty; K parallel traces
└──────────────────────────┘
  │
  ▼
┌──────────────────────────┐
│ 4. Process Reward Model  │   stepwise energy → trace confidence
└──────────────────────────┘
  │
  ▼
┌──────────────────────────┐
│ 5. External Verifier     │   SymPy / sandboxed exec / regex — mechanical check
└──────────────────────────┘
  │
  ▼
┌──────────────────────────┐
│ 6. Self-Consistency Vote │   weighted by confidence or 1/energy
└──────────────────────────┘
  │
  ▼
 answer + audit trail
```

Every stage is a swappable component behind a Protocol. The verifier layer never hallucinates — it only confirms what SymPy / Python / regex can mechanically check.

## Install

```bash
pip install ebrm-system
```

From source:

```bash
git clone https://github.com/piyushptiwari1/ebrm-system
cd ebrm-system
pip install -e ".[dev]"
```

## Quick start

```bash
# See what the intent router thinks about a query
ebrm-system classify "Solve: 3x + 7 = 22"

# Verify an answer mechanically
ebrm-system verify "x**2 + 2*x + 1" "(x+1)**2"
```

Python API:

```python
from ebrm_system.intent import RuleBasedClassifier
from ebrm_system.verifiers import SymPyVerifier, VerifierChain
from ebrm_system.voting import Candidate, SelfConsistencyVoter

clf = RuleBasedClassifier()
pred = clf.classify("Solve: 3x + 7 = 22")
# pred.suggested_langevin_steps, pred.suggested_trace_count, ...

chain = VerifierChain([SymPyVerifier()])
results = chain.verify("5", {"expected": "5"})
assert chain.all_passed(results)

voter = SelfConsistencyVoter(numerical=True, tolerance=0.01, weight_by="inverse_energy")
result = voter.vote([
    Candidate(answer=5.0, energy=-2.0),
    Candidate(answer=5.0, energy=-1.5),
    Candidate(answer=4.0, energy= 3.0),
])
# result.answer == 5.0, weighted by low energy
```

## Components

| Module | Status | Purpose |
| --- | --- | --- |
| `ebrm_system.intent` | ✅ stable | Intent + difficulty + compute budget |
| `ebrm_system.verifiers` | ✅ stable | SymPy / exec / regex / Lean / DRI + intent routing |
| `ebrm_system.voting` | ✅ stable | Self-consistency with weighted bucketing |
| `ebrm_system.inference` | ✅ stable | Langevin candidates, QJL, TurboQuant KV + attention |
| `ebrm_system.reward` | ✅ stable | LatentIndex (QJL-backed nearest-neighbour reward) |
| `ebrm_system.core` | ✅ stable | `HierarchicalLatentReasoner` — end-to-end orchestrator |

## Development

```bash
pip install -e ".[dev]"
pytest                           # run tests
ruff check .                     # lint
mypy src                         # type-check
pre-commit install               # optional hooks
```

CI runs lint + type + test on Python 3.10/3.11/3.12/3.13. See [`.github/workflows/ci.yml`](.github/workflows/ci.yml).

## Design principles

1. **Mechanical over mystical** — verifiers confirm with SymPy / exec / regex; never an LLM grading an LLM.
2. **Budget-aware** — easy queries don't pay for hard-query compute. Intent routing controls Langevin steps, restarts, and trace count.
3. **Audit-first** — every candidate carries its trace, energy, and verifier evidence.
4. **Swappable** — everything is a Protocol. Swap the rule-based classifier for a neural one; swap SymPy for Z3; drop in your own voter.

## Citation

If you use this system in academic work, please cite the model paper:

```bibtex
@software{ebrm_system_2026,
  author  = {Tiwari, Piyush},
  title   = {ebrm-system: An Energy-Based Reasoning Machine pipeline},
  year    = {2026},
  url     = {https://github.com/piyushptiwari1/ebrm-system}
}
```

## License

Apache 2.0. See [LICENSE](LICENSE).
