Metadata-Version: 2.3
Name: monte-neo
Version: 0.17.7
Summary: Fast local research for trading strategies on Apple Silicon: fee-aware bar backtests, Monte Carlo, paper OMS (Metal/MLX/Numba)
Project-URL: Homepage, https://github.com/NeoZorK/Monte-Neo
Project-URL: Repository, https://github.com/NeoZorK/Monte-Neo
Project-URL: Issues, https://github.com/NeoZorK/Monte-Neo/issues
Project-URL: Changelog, https://github.com/NeoZorK/Monte-Neo/blob/main/docs/project/CHANGELOG.md
Project-URL: Documentation, https://neozork.github.io/Monte-Neo/
Author: Monte-Neo Team
License: MIT
License-File: LICENSE
Keywords: apple-silicon,backtesting,metal,monte-carlo,oms,research,trading
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Financial and Insurance Industry
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: MacOS
Classifier: Operating System :: POSIX :: Linux
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Office/Business :: Financial :: Investment
Classifier: Topic :: Scientific/Engineering
Requires-Python: >=3.11
Requires-Dist: numba>=0.58
Requires-Dist: numpy>=1.24
Requires-Dist: pandas>=2.0
Requires-Dist: prompt-toolkit>=3.0
Requires-Dist: pyarrow>=23.0.1
Requires-Dist: pybind11>=2.10.0
Requires-Dist: python-dotenv>=1.2.2
Requires-Dist: pyyaml>=6.0
Requires-Dist: questionary>=2.0
Requires-Dist: rich>=13.0
Provides-Extra: apple
Requires-Dist: mlx>=0.11.0; (sys_platform == 'darwin') and extra == 'apple'
Requires-Dist: pyobjc-framework-cocoa>=12.2.2; (sys_platform == 'darwin') and extra == 'apple'
Requires-Dist: pyobjc-framework-metal>=12.2.2; (sys_platform == 'darwin') and extra == 'apple'
Provides-Extra: data
Requires-Dist: binance-connector>=3.12.0; extra == 'data'
Provides-Extra: dev
Requires-Dist: binance-connector>=3.12.0; extra == 'dev'
Requires-Dist: black>=26.3.1; extra == 'dev'
Requires-Dist: build>=1.2; extra == 'dev'
Requires-Dist: matplotlib>=3.10.8; extra == 'dev'
Requires-Dist: mplfinance; extra == 'dev'
Requires-Dist: mypy>=1.5; extra == 'dev'
Requires-Dist: pandas-stubs; extra == 'dev'
Requires-Dist: pillow>=12.3.0; extra == 'dev'
Requires-Dist: plotext>=5.2; extra == 'dev'
Requires-Dist: pre-commit>=3.4; extra == 'dev'
Requires-Dist: pytest-asyncio>=0.21; extra == 'dev'
Requires-Dist: pytest-cov>=4.1; extra == 'dev'
Requires-Dist: pytest-xdist>=3.3; extra == 'dev'
Requires-Dist: pytest>=9.0.3; extra == 'dev'
Requires-Dist: ruff>=0.1; extra == 'dev'
Requires-Dist: scipy>=1.11; extra == 'dev'
Requires-Dist: seaborn>=0.13.2; extra == 'dev'
Requires-Dist: setuptools>=75.0; extra == 'dev'
Requires-Dist: twine>=5.0; extra == 'dev'
Requires-Dist: types-pyyaml; extra == 'dev'
Provides-Extra: full
Requires-Dist: binance-connector>=3.12.0; extra == 'full'
Requires-Dist: fastapi>=0.138.2; extra == 'full'
Requires-Dist: lightgbm>=4.6.0; extra == 'full'
Requires-Dist: matplotlib>=3.10.8; extra == 'full'
Requires-Dist: mlx>=0.11.0; (sys_platform == 'darwin') and extra == 'full'
Requires-Dist: mplfinance; extra == 'full'
Requires-Dist: pillow>=12.3.0; extra == 'full'
Requires-Dist: plotext>=5.2; extra == 'full'
Requires-Dist: psycopg2-binary>=2.9.12; extra == 'full'
Requires-Dist: pyobjc-framework-cocoa>=12.2.2; (sys_platform == 'darwin') and extra == 'full'
Requires-Dist: pyobjc-framework-metal>=12.2.2; (sys_platform == 'darwin') and extra == 'full'
Requires-Dist: redis>=8.0.1; extra == 'full'
Requires-Dist: scikit-learn>=1.9.0; extra == 'full'
Requires-Dist: scipy>=1.11; extra == 'full'
Requires-Dist: seaborn>=0.13.2; extra == 'full'
Requires-Dist: statsmodels>=0.14.6; extra == 'full'
Requires-Dist: ta>=0.10; extra == 'full'
Requires-Dist: uvicorn>=0.49.0; extra == 'full'
Provides-Extra: ml
Requires-Dist: lightgbm>=4.6.0; extra == 'ml'
Requires-Dist: scikit-learn>=1.9.0; extra == 'ml'
Requires-Dist: scipy>=1.11; extra == 'ml'
Requires-Dist: statsmodels>=0.14.6; extra == 'ml'
Requires-Dist: ta>=0.10; extra == 'ml'
Provides-Extra: plot
Requires-Dist: matplotlib>=3.10.8; extra == 'plot'
Requires-Dist: mplfinance; extra == 'plot'
Requires-Dist: pillow>=12.3.0; extra == 'plot'
Requires-Dist: plotext>=5.2; extra == 'plot'
Requires-Dist: seaborn>=0.13.2; extra == 'plot'
Provides-Extra: server
Requires-Dist: fastapi>=0.138.2; extra == 'server'
Requires-Dist: psycopg2-binary>=2.9.12; extra == 'server'
Requires-Dist: redis>=8.0.1; extra == 'server'
Requires-Dist: uvicorn>=0.49.0; extra == 'server'
Description-Content-Type: text/markdown

# Monte-Neo

<p align="center">
  <img src="docs/assets/monteneo-logo.png" alt="Monte-Neo logo" width="120"/>
</p>

<p align="center">
  <strong>Fast local research</strong> for trading strategies on Apple Silicon<br/>
  Fee-aware next-bar economics · Monte Carlo · paper OMS<br/>
  MIT · Python 3.11+ · Metal / MLX / Numba
</p>

<p align="center">
  <a href="https://github.com/NeoZorK/Monte-Neo/actions/workflows/ci.yml"><img src="https://github.com/NeoZorK/Monte-Neo/actions/workflows/ci.yml/badge.svg" alt="CI"/></a>
  <a href="https://pypi.org/project/monte-neo/"><img src="https://img.shields.io/pypi/v/monte-neo.svg" alt="PyPI"/></a>
  <a href="LICENSE"><img src="https://img.shields.io/badge/license-MIT-blue.svg" alt="MIT license"/></a>
  <a href="https://github.com/NeoZorK/Monte-Neo/releases/latest"><img src="https://img.shields.io/github/v/release/NeoZorK/Monte-Neo?label=release" alt="Latest release"/></a>
  <img src="https://img.shields.io/badge/python-3.11%2B-blue.svg" alt="Python 3.11+"/>
  <img src="https://img.shields.io/badge/macOS-Apple%20Silicon-black.svg" alt="macOS Apple Silicon"/>
</p>

> Current: **v0.17.7** · [Docs site](https://neozork.github.io/Monte-Neo/) · [Changelog](docs/project/CHANGELOG.md) · [FAQ](docs/guides/FAQ.md)

## What this is (and is not)

**Job:** on Apple Silicon macOS, build and verify trading-domain strategies **very quickly**
with fee-aware next-bar economics you can re-check (export API + golden vectors).

**Lanes:** research bar (primary speed path) · Monte Carlo research · paper OMS (validation).

**Not a goal:** replace full event-driven production / live-bot platforms. Research sweep
throughput is not an OMS event-loop claim.

## Why Monte-Neo

| Advantage | What you get |
|-----------|----------------|
| Local Apple Silicon speed | Metal economics + Numba (MLX optional for signals) |
| Fee-aware research bar | Next-bar fills, costs (bps), SL/TP/trail, funding, sessions |
| Honest export API | `export_single` / `export_batch` / `export_sma_sweep` + golden vectors |
| 16GB-class memory planner | `plan_research_bytes` + **no-hang** Metal size gate → `cpu_numba` fallback |
| Local research triage | `HeuristicPolicy` after export → next action / promote / MC |
| Holdout check | `holdout_sma_sweep` train→holdout gap (anti-overfit, no ML) |
| Clear non-goals | macOS research tool first; paper OMS is a separate lane |
| MIT | Use, fork, and ship without drama |

## Install

**From PyPI (recommended):**

```bash
pip install monte-neo                 # research-core (slim)
pip install "monte-neo[apple]"        # Metal / MLX (Apple Silicon)
pip install "monte-neo[plot]"         # charts
pip install "monte-neo[data]"         # Binance downloader / websocket
pip install "monte-neo[full]"         # kitchen-sink local parity
```

**From git:**

```bash
pip install "git+https://github.com/NeoZorK/Monte-Neo.git"
pip install "monte-neo[apple] @ git+https://github.com/NeoZorK/Monte-Neo.git"
```

**In-repo (contributors):**

```bash
git clone https://github.com/NeoZorK/Monte-Neo.git
cd Monte-Neo
uv sync --extra apple --extra plot --extra data --group dev
```

See [PACKAGING.md](docs/project/PACKAGING.md) · [Export API](docs/api/export.md) · [Policy triage](docs/api/policy.md).

**Requirements:** Python **3.11+**. Best experience on **Apple Silicon** macOS. Numba CPU
paths work more broadly; Metal/MLX are the `[apple]` extra.

## Quick start

```bash
uv sync --extra apple --extra plot --extra data --group dev
uv run monte-neo
uv run pytest tests -n auto
# After an export_sma_sweep JSON:
# uv run monte-neo --policy-triage path/to/export.json
```

### Research export (recommended)

```python
from monte_neo.backtest import (
    ExecutionModel,
    export_sma_sweep,
    synthetic_ohlcv,
)

ohlc = synthetic_ohlcv(100_000, seed=42)
model = ExecutionModel(commission_bps=5.0, slippage_bps=5.0, warmup_bars=50)
out = export_sma_sweep(
    ohlc["open"], ohlc["high"], ohlc["low"], ohlc["close"],
    combos=16,
    model=model,
    device="auto",  # Metal when safe; else cpu_numba (see fallback_reason)
)
print(out["device"], out.get("fallback_reason"), out["combos"])
```

### Single bar backtest

```python
from monte_neo.backtest import (
    ExecutionModel,
    frame_to_ohlc,
    run_bar_backtest,
    sma_signal,
    synthetic_ohlcv,
)

ohlc = frame_to_ohlc(synthetic_ohlcv(5_000, seed=42))
model = ExecutionModel(
    commission_bps=5.0,
    slippage_bps=5.0,
    size_fraction=0.25,
    sl_pct=1.0,
    tp_pct=2.0,
)
sig = sma_signal(ohlc["close"], fast=10, slow=40)
out = run_bar_backtest(
    ohlc["open"], ohlc["high"], ohlc["low"], ohlc["close"], sig, model=model
)
print(out["total_return"], out["metrics"]["max_drawdown"], len(out["trades"]))
```

More: [docs/guides/quick-start.md](docs/guides/quick-start.md) · [backtest engine](docs/project/backtest_engine.md) · [FAQ](docs/guides/FAQ.md)

## How to use (research workflow)

1. Load or synthesize OHLCV (`synthetic_ohlcv` / your frame → `frame_to_ohlc`).
2. Set an `ExecutionModel` (fees, SL/TP, sessions, side mode).
3. Sweep with `export_sma_sweep` / `export_batch`, or a single `export_single`.
4. Check `device`, `signal_device`, and `fallback_reason` when using `auto`.
5. Optional depth: `equity_stride`, journal, `plan_research_bytes` / `memory` on exports.
6. Paper OMS (`monte_neo.oms`) only when you need event-lane validation — not for sweep cps claims.

**Devices:** `auto` · `metal` · `cpu_numba` (and MLX where signal paths allow). Oversized Metal
jobs demote to Numba instead of hanging (v0.14.1+).

## Features (honest)

| Area | Status |
|------|--------|
| MC indicator / robustness workflows | Available via CLI and library |
| Fee-aware research bar engine | `monte_neo.backtest` |
| Research export + golden vectors | `export_*` / `verify_golden_vectors` |
| Memory / no-hang accelerator gate | `plan_research_bytes` / `decide_research_accelerator` |
| Paper OMS + venue adapters | `monte_neo.oms` |
| Metal / MLX / Numba device select | Best-effort on Apple Silicon; CPU fallbacks |
| Docker | Supported for headless/CI-style runs |

## Project structure

```
Monte-Neo/
├── src/monte_neo/
│   ├── backtest/      # Research bar engine + export
│   ├── oms/           # Paper OMS + accel
│   ├── core/          # Generator / Metal bridges
│   ├── data/          # Market data downloaders
│   ├── monte_carlo/   # MC methods
│   ├── metrics/       # Trading metrics
│   ├── cli/           # Interactive CLI
│   └── visualization/
├── tests/
├── docs/
└── docker/
```

## Screenshots / demos

<p align="center">
  <img src="docs/assets/demo_sma_sweep.png" alt="SMA sweep demo" width="720"/>
</p>
<p align="center">
  <img src="docs/assets/demo_memory_plan.png" alt="Memory plan demo" width="720"/>
</p>

More under `docs/assets/`. Runnable script: [`examples/export_sma_sweep_quickstart.py`](examples/export_sma_sweep_quickstart.py).

## Contributing

See [CONTRIBUTING.md](CONTRIBUTING.md) · [docs](docs/development/contributing.md).

## Security

Report vulnerabilities privately — see [SECURITY.md](SECURITY.md) (GitHub Security Advisories preferred; do not open public issues for exploitable bugs).

## License

MIT — see [LICENSE](LICENSE).

Public repository: https://github.com/NeoZorK/Monte-Neo
