Skip to content

Monte-Neo v0.54.0

A simplified guide to the Monte-Neo file structure.

Format: [file path] - [description]

Root Configuration

  • docs/index.md - Public docs site landing page (MkDocs Home / site root)
  • docs/docs-map.md - Docs file map (maintenance index)
  • docs/stylesheets/extra.css - MkDocs Material extras (compact badges/logo)
  • docs/assets/logo-mark.png - Compact theme logo / favicon (96px)
  • docs/assets/logo-header.png - Compact header logo (128px)
  • docs/assets/demo-repair.gif, demo-alpha.gif, demo-dossier.gif - v0.53 demos (scripts/make_repair_gif.py, make_alpha_gif.py, make_dossier_gif.py; lines copied from real runs)
  • docs/assets/reports/dossier-sr11-7.html, repair-flicker.html - Example institutional reports (scripts/make_institutional_gallery.py)
  • examples/reference_alpha/, examples/ml_fit_predict.py, llm_news_signal.py, allocator_dd.py - v0.53 examples
  • README.md - Main project documentation
  • CLAUDE.md - Agent instructions (authorship rule: NeoZorK only, no AI attribution)
  • .claude/settings.json - Claude Code project settings (built-in attribution disabled)
  • pyproject.toml - Python package configuration and dependencies
  • uv.lock - Lockfile for consistent environment management
  • LICENSE - MIT License
  • CITATION.cff - Citation metadata (GitHub "Cite this repository")
  • glama.json - Glama MCP catalogue ownership claim
  • SECURITY.md - Vulnerability reporting (GitHub Security Advisories)
  • .github/workflows/pypi-smoke.yml - PyPI bare-install smoke (schedule / dispatch / release)
  • .github/workflows/docker.yml - Manual rebuild of the GHCR verifier image for a release (scripts/build_docker_image.sh)
  • .github/workflows/verify-action.yml - Self-test of action.yml (leaky strategy must be rejected)
  • .github/workflows/publish.yml - Tag-driven PyPI publish + GitHub Release from CHANGELOG + GHCR image
  • .github/workflows/release.yml - Manual release: version check, tag as NeoZorK, start publish
  • scripts/verify_pypi_install.sh - Installs a release from PyPI into a clean venv and runs verify, recheck, signing, bench and MCP (run by publish.yml after each release and weekly)
  • CONTRIBUTING.md - Root pointer to contributing guide
  • .gitignore - Git exclusion rules
  • .env.example - Environment variables template

Project Information (docs/project/)

  • docs/project/project-idea.md - The philosophy and vision behind Monte-Neo
  • docs/project/vision.md - Original design goals and core principles
  • docs/project/project-structure.md - Deep dive into physical directory layout
  • docs/project/features.md - Detailed overview of framework features
  • docs/project/dynamic_indicators.md - Explanation of dynamic indicator generation
  • docs/project/ROADMAP.md - Development roadmap and milestones (v0.51.0)
  • docs/project/CHANGELOG.md - Release changelog (current: v0.51.0)
  • docs/project/backtest_engine.md - Fee-aware research bar engine
  • docs/project/oms_engine.md - Paper OMS (bar + tick/L2) + venue adapters
  • docs/assets/monteneo-logo.png - Project logo (original, with the old tagline)
  • docs/assets/logo-sphere.png - Logo mark without text (transparent)
  • docs/assets/social-preview.png - 1280×640 banner: README hero and GitHub social preview
  • docs/assets/report-leak.png - Screenshot of the HTML report of a rejected strategy (README, from docs/assets/reports/leak.html)
  • docs/assets/demo-verify.gif - Animated demo: leaky agent strategy → fix → honest verdict (scripts/make_demo_gif.py)
  • docs/assets/demo-arrival.gif - Animated demo: a strategy that lives on data it could not have seen, and an honest one (scripts/make_arrival_gif.py)
  • docs/guides/arrival-time.md - Latency audit guide: arrival look-ahead, the delay where the profit vanishes, latency Monte Carlo, recorder, limits
  • docs/marketing/launch-kit.md - Ready-to-post launch texts, GitHub About text, catalogue entries
  • docs/marketing/article-six-ways.md - Article draft: six ways an agent's backtest lies
  • docs/project/BRANCHING.md - Branch and version policy
  • docs/project/v0.0.5_plan.md - Development plan for v0.0.5
  • docs/project/tech-stack.md - Technology stack and performance targets
  • docs/en/COMMERCIAL.md - Commercial notes (English)
  • docs/METAL_NATIVE_BUILD.md - Native Metal extension build notes

Setup & Configuration (docs/setup/)

  • docs/setup/installation.md - Installation instructions for users and developers
  • docs/setup/development-setup.md - Guide for setting up the dev environment
  • docs/setup/auth.md - Authentication and Binance API key setup
  • docs/setup/user-settings.md - Configuration and environment variable guide

Development (docs/development/)

  • docs/development/rules.md - Project-specific rules and conventions
  • docs/development/testing.md - Testing strategy and execution guide
  • docs/development/performance.md - Performance notes and benchmarks
  • docs/development/generation_mechanics.md - Deep dive into generator and dynamic indicator logic
  • docs/development/external-libs.md - List and purpose of external dependencies
  • docs/development/api-documentation.md - Guide to API and code documentation
  • docs/development/CLAUDE.md - AI assistant guide and coding conventions

Guides & Examples (docs/guides/, docs/examples/)

  • docs/guides/quick-start.md - 3-step guide to get started
  • docs/guides/FAQ.md - Metal vs Numba, install, no-hang gate, PyPI timing
  • docs/guides/agents.md - Use the verifier from Claude Code / Codex / Gemini / Cursor / GitHub Actions
  • docs/guides/honesty-bench.md - Agent Backtest Honesty Bench: layout, metrics, fair-play rules
  • docs/verify.md - Browser page that checks a certificate's Ed25519 signature (docs/assets/verify-certificate.js)
  • docs/paper/methodology.md - Technical note on the verification method (probes, costs, selection, certificates, Trap Suite evaluation)
  • docs/marketing/trap-of-the-week.md - Twelve weekly post drafts built on Trap Suite strategies, with measured verdicts
  • packaging/conda-forge/meta.yaml - conda-forge recipe draft (not built)
  • .github/ISSUE_TEMPLATE/false_accusation.yml - Issue form for false accusations of honest strategies
  • docs/guides/alpha.md - monte-neo alpha: signal power (IC, decay, quantiles, placebos) and implementability (impact, capacity, shorts, rebalance day)
  • docs/guides/policy-trials-cutoff.md - verify --policy (TOML thresholds), --trials-from (MLflow, Optuna, W&B), team ledger, --model-cutoff
  • docs/guides/ml-and-events.md - fit/predict protocol (walk-forward run by the verifier, ml_refit_gap, ml_cv_overlap) and --events joined by publication time
  • docs/guides/phantom-profit.md - verify --legs, --null-test, --demo-phantom: phantom mean reversion in pairs and spread strategies
  • examples/phantom_pairs/ - pairs_buggy.py, pairs_fixed.py, make_legs.py: the wrong and the right booking of a rolling hedge
  • src/monte_neo/verify/legs.py, nulltest.py, phantom.py - legs accounting check, random-walk null test, reference pairs model
  • src/monte_neo/cli/legs_cmd.py - CLI for --legs, --null-test, --demo-phantom
  • tests/unit/test_phantom_legs.py - phantom-profit tests
  • paper/phantom-mean-reversion/ - preprint "Phantom Mean Reversion": main.tex, figures, code (phantom_mr_sim.py, other_hedges.py, make_figures.py), results, build_arxiv.sh
  • docs/guides/returns-due-diligence.md - verify --returns: smoothing, zero kink, implausible consistency, significance, benchmark
  • docs/guides/dossier-readiness-monitor.md - monte-neo dossier (frameworks SR 11-7, SS1/23, RTS 6), Alpha Readiness Level 1-9, monte-neo monitor
  • docs/guides/reference-alpha.md - Reference alpha 1 (trend following): rules, expectations, when it works and fails, measured verdicts
  • docs/guides/alpha-calibration.md - Generated: false alarms and power of the alpha checks on zoo A15 traps and honest twins
  • tests/zoo/test_zoo_alpha.py, alpha_cases.py; scripts/alpha_calibration.py - zoo A15 (alpha traps and twins) and its calibration
  • docs/guides/repair.md - monte-neo repair: protocol, catalogue R1-R11, outcomes, zoo A16
  • docs/guides/discover.md - monte-neo discover: verified indicator search (gate, effective trials, search null, lockbox)
  • scripts/check_english_only.py - Language guard: fails on Cyrillic text or private working files in tracked files, PR titles, PR descriptions and commit messages
  • scripts/mutation_check.py - Mutation check of the verifier core
  • tests/unit/test_mutation_pins.py - Exact values and boundaries pinned after the mutation check
  • docs/guides/local-agents.md - Local agents: Qwen Code, a model served by Ollama, bench run with --base-url, failure messages
  • docs/guides/real-data-and-wild-corpus.md - Honesty Bench run commands, discover on real markets, wild scan, why real Freqtrade and Lean runs
  • scripts/fetch_market_data.py, real_markets_run.py, wild_scan.py, wild_clone.sh - Real data and wild scan tools
  • src/monte_neo/main.py - python -m monte_neo
  • docs/guides/repaint.md - Repainting: history and forming-bar probes, lint rules, fixes
  • docs/guides/workflow-tools.md - history, register, oracle, portfolio, doctor
  • docs/guides/discover-calibration.md - Generated: discover on noise and the power to find a planted edge
  • scripts/discover_calibration.py - Builds the discover calibration page
  • src/monte_neo/verify/repaint.py - Repaint probes (history, forming bar)
  • src/monte_neo/verify/chainlog.py, history.py, register.py, oracle.py, portfolio.py, doctor.py, returns.py - Project tools of stage 10
  • src/monte_neo/cli/tools_cmd.py - history, register, oracle, portfolio, doctor commands
  • docs/guides/ledger-and-fixes.md - Trial ledger (--ledger) and suggested causal rewrites (--suggest-fix)
  • docs/guides/honesty-scorecard.md - Generated scorecard of the hypothesis zoo (Wilson intervals, known gaps)
  • scripts/zoo_scorecard.py - Builds the honesty scorecard from the zoo
  • tests/zoo/ - Hypothesis zoo: leak and honest mechanisms, disguises, independent oracle, data defects, claims, metamorphic relations, known gaps
  • src/monte_neo/discover/ - Verified indicator search (DSL, search, causality gate, canaries)
  • src/monte_neo/verify/ledger.py - Append-only trial ledger
  • src/monte_neo/verify/filelock.py - Cross-process file lock for the team ledger
  • src/monte_neo/verify/trials_import.py - --trials-from: trial counts from MLflow, Optuna, W&B, CSV, ledgers
  • src/monte_neo/verify/policy.py - --policy: an institution's thresholds as TOML, the policy row, apply_policy
  • src/monte_neo/verify/cutoff.py - --model-cutoff: does the edge survive a model's training cutoff
  • src/monte_neo/verify/model_protocol.py, model_rows.py - fit/predict protocol, ml_refit_gap, ml_cv_overlap
  • src/monte_neo/verify/events.py, events_checks.py, events_run.py - --events: load, join by publication time, quality, pit_events
  • src/monte_neo/verify/returns_dd.py, returns_dd_checks.py - verify --returns: due diligence on a return series
  • src/monte_neo/cli/returns_cmd.py - verify --returns and --demo-returns
  • src/monte_neo/dossier/ - validation-dossier/1: framework maps, build, HTML
  • src/monte_neo/readiness.py - Alpha Readiness Level 1-9
  • src/monte_neo/verify/live.py, live_seq.py - live-monitor/1: live vs backtest, slippage, CUSUM/SPRT, track needed
  • src/monte_neo/cli/dossier_cmd.py, monitor_cmd.py - monte-neo dossier and monte-neo monitor
  • examples/reference_alpha/ - Reference alpha 1: trend_v1.py, make_data.py, README
  • src/monte_neo/repair/ - repair-report/1: runtime transforms, catalogue and repaired file, protocol, report, demo
  • src/monte_neo/cli/repair_cmd.py - monte-neo repair
  • tests/zoo/test_zoo_repair.py - zoo A16: repair never reports REPAIRED on a leaking trap over a random walk
  • src/monte_neo/disclaimer.py - The one 'not investment advice' text for reports, CLI, MCP and docs
  • src/monte_neo/alpha/ - monte-neo alpha: panel alignment, signal power (A), attribution and self-built factors (B), value to a book (C), implementability (D), robustness (E), multiple testing (F), data and process (G), risk (I), alpha-report/1 with the readiness level
  • src/monte_neo/cli/alpha_cmd.py, policy_cmd.py - monte-neo alpha and monte-neo policy commands
  • .github/ISSUE_TEMPLATE/agent_report.yml - Report form for running Monte-Neo from a coding agent
  • src/monte_neo/verify/fixes.py - Causal rewrites for suggest_fix
  • src/monte_neo/cli/discover_cmd.py - monte-neo discover command
  • docs/guides/frameworks.md - Adapters (vectorbt, Freqtrade, Lean, Zipline, fills), Jupyter display, pandas accessor, pre-commit, badge, Docker image
  • docs/guides/trap-suite.md - Trap Suite catalogue (80 traps, 35 honest controls) and how to contribute a trap
  • src/monte_neo/bench/ - Honesty Bench (verify agent submissions, compare claims, leaderboard; v1 tasks + answer key)
  • src/monte_neo/cli/bench_cmd.py - monte-neo bench command
  • scripts/make_example_bench.py - Builds an example bench from the Trap Suite
  • src/monte_neo/bench/public_run.py - bench prepare / bench collect: clean aliased workspaces for a public run
  • scripts/honesty_bench_run.sh - Runs coding agents headless over bench workspaces, one session per task, with transcripts
  • docs/api/verify.md - Strategy verifier API, checks, verdicts, strategy-verdict/1 certificate
  • docs/examples/README.md - Standalone script examples (Placeholder)
  • docs/api/README.md - API reference (Placeholder)

Docker (docker/)

  • docker/Dockerfile - Multi-stage Docker build using uv
  • docker/docker-compose.yml - Docker Compose service definitions
  • docker/verify/Dockerfile - Verifier image for untrusted strategy code (engines precompiled, runs as nobody)

Source Code (src/monte_neo/)

  • src/monte_neo/_version.py - Central version management (v0.51.0)
  • src/monte_neo/verify/ - Strategy verifier (ingest, single and universe markets, data quality, look-ahead probes, outside-data watch, strategy workers (jobs, timeout, isolation), lint, benchmark and breakdown, HTML report, costs, stats, checks, verdict, grid + walk-forward, certificate recheck)
  • src/monte_neo/mcp/ - MCP server (monte-neo-mcp) + agent-facing tool functions
  • src/monte_neo/cli/verify_cmd.py - monte-neo verify command (CI exit codes)
  • src/monte_neo/backtest/export_signals.py - Bring-your-own-signals export
  • integrations/ - Claude Code plugin (skill, /verify, PostToolUse reminder hook), Codex / Gemini / Cursor / Qwen Code agent configs (AGENT_RULES.md source of truth)
  • .claude-plugin/marketplace.json - Claude Code plugin marketplace entry
  • action.yml - Composite GitHub Action for strategy verification
  • server.json - Official MCP Registry entry (io.github.NeoZorK/monte-neo, PyPI package, monte-neo mcp)
  • tests/traps/ - Verifier Trap Suite (lying strategies + honest controls)
  • examples/verify_quickstart.py - Leaky vs causal strategy verifier demo
  • src/monte_neo/policy/ - HeuristicPolicy A (ResearchState + triage)
  • src/monte_neo/backtest/holdout.py - Train/holdout SMA helper
  • docs/api/holdout.md - Holdout API
  • docs/development/contributing.md - Contributing guide
  • .github/ISSUE_TEMPLATE/ - Bug / feature templates
  • docs/api/export.md - Research export API (schema / golden)
  • docs/api/policy.md - Local research policy triage
  • docs/project/mc_accel.md - MC Metal/MLX dispatch + 16GB budgets
  • src/monte_neo/init.py - Main package entry point
  • src/monte_neo/backtest/ - Professional fee-aware research bar engine + SMA sweep
  • src/monte_neo/oms/ - Paper OMS lane + Apple Silicon accel helpers

Core Engine (core/)

  • src/monte_neo/core/init.py - Core exports
  • src/monte_neo/core/generator.py - Main indicator generation logic (entry point)
  • src/monte_neo/core/generator_search.py - Generator search and filtering logic
  • src/monte_neo/core/generator_utils.py - Generator constants and helpers
  • src/monte_neo/core/generator_worker.py - Generator parallel worker functions
  • src/monte_neo/core/gpu_engine.py - MLX GPU backtesting engine
  • src/monte_neo/core/gpu_lazy.py - Lazy GPU backtesting helpers
  • src/monte_neo/core/gpu_scenarios.py - GPU scenario backtesting helper
  • src/monte_neo/core/optimizer.py - Parameter optimization strategies
  • src/monte_neo/core/validator.py - Overfitting and robustness validation
  • src/monte_neo/core/acceleration/ - Directory for Metal/C++ accelerators (v0.0.4)

Data Handling (data/)

  • src/monte_neo/data/init.py - Data module exports
  • src/monte_neo/data/downloader.py - Binance OHLCV data downloader
  • src/monte_neo/data/storage.py - Efficient Parquet storage handler
  • src/monte_neo/data/sampler.py - Bootstrap and synthetic data sampling
  • src/monte_neo/data/websocket.py - Binance WebSocket streaming wrapper

Monte Carlo (monte_carlo/)

  • src/monte_neo/monte_carlo/init.py - MC module exports
  • src/monte_neo/monte_carlo/engine.py - Main simulation execution engine
  • src/monte_neo/monte_carlo/types.py - MC configuration and result types
  • src/monte_neo/monte_carlo/sequential.py - Sequential MC "Wizard" runner
  • src/monte_neo/monte_carlo/scenarios.py - Scenario generation logic
  • src/monte_neo/monte_carlo/shuffler.py - Return and block shuffling methods
  • src/monte_neo/monte_carlo/noise.py - Noise injection and slippage simulation
  • src/monte_neo/monte_carlo/sensitivity.py - Parameter sensitivity analysis
  • src/monte_neo/monte_carlo/walk_forward.py - Rolling walk-forward validation

Metrics (metrics/)

  • src/monte_neo/metrics/init.py - Metrics module exports
  • src/monte_neo/metrics/calculator.py - Unified trading metrics calculator (entry point)
  • src/monte_neo/metrics/numba_funcs.py - Numba-optimized calculation functions
  • src/monte_neo/metrics/types.py - Metric data types and dataclasses
  • src/monte_neo/metrics/utils.py - Helper functions for metric calculations
  • src/monte_neo/metrics/profit_factor.py - Profit Factor calculation
  • src/monte_neo/metrics/sharpe.py - Sharpe and Sortino ratio metrics
  • src/monte_neo/metrics/drawdown.py - Max and average drawdown metrics
  • src/monte_neo/metrics/winrate.py - Winrate and expectancy metrics

Trading Logic (indicators/)

  • src/monte_neo/indicators/init.py - Indicator exports
  • src/monte_neo/indicators/base.py - Abstract base indicator class
  • src/monte_neo/indicators/technical.py - Portfolio of technical indicators (entry point)
  • src/monte_neo/indicators/technical_lib.py - Core library of technical indicators
  • src/monte_neo/indicators/numba_funcs.py - Numba-optimized indicator functions
  • src/monte_neo/indicators/sma.py - Simple Moving Average implementation
  • src/monte_neo/indicators/rsi.py - Relative Strength Index implementation
  • src/monte_neo/indicators/macd.py - MACD implementation
  • src/monte_neo/indicators/custom.py - Build-your-own indicator builder
  • src/monte_neo/indicators/dynamic.py - Dynamic indicator with evolutionary generation

Interface (cli/)

  • src/monte_neo/cli/init.py - CLI module exports
  • src/monte_neo/cli/entry.py - monte-neo entry point: dispatches verify / bench / mcp / --version without loading the research CLI
  • src/monte_neo/cli/app.py - Interactive research CLI and its argument parsing
  • src/monte_neo/cli/menu.py - Interactive arrow-navigation menu
  • src/monte_neo/cli/progress.py - Rich progress bars and ETA
  • src/monte_neo/cli/styles.py - Terminal styling and themes

Visuals (visualization/)

  • src/monte_neo/visualization/init.py - Viz module exports
  • src/monte_neo/visualization/charts.py - Candlestick and signal charting
  • src/monte_neo/visualization/trades.py - Trade-by-trade visualization
  • src/monte_neo/visualization/metrics.py - Performance metrics dashboard

Utilities (utils/)

  • src/monte_neo/utils/init.py - Utils module exports
  • src/monte_neo/utils/config.py - Configuration management
  • src/monte_neo/utils/logger.py - Standardized logging setup
  • src/monte_neo/utils/parallel.py - Multiprocessing and parallel execution

Tests (tests/)

  • tests/conftest.py - Shared pytest fixtures
  • tests/unit/ - Targeted unit tests for all modules
  • tests/unit/test_dynamic_indicator.py - Tests for dynamic code generation and evolution
  • tests/unit/test_gpu_engine_parallel.py - Tests for GPU parallel path selection
  • tests/unit/test_binance_websocket.py - Tests for Binance WebSocket streaming
  • tests/unit/legacy_coverage/ - Legacy gap-filling tests for the frozen research lanes (not extended)
  • tests/traps/ - Verifier Trap Suite (strategies that lie + honest controls)
  • tests/integration/ - End-to-end workflow tests
  • tests/stress/ - Memory and CPU performance stress tests

Utility Scripts (scripts/)

  • scripts/run_full_test_suite.sh - Master verification script (uv + docker)
  • scripts/check_system.py - Native verification of Genetic Algorithms & Dynamic Indicators
  • scripts/verify_hardware.py - Float8 / Metal hardware check (Apple Silicon)
  • scripts/experiments/ - One-off Metal / MLX experiments, not maintained
  • scripts/make_demo_gif.py - Renders docs/assets/demo-verify.gif from real verify output
  • scripts/validate_on_real_quotes.py - Runs the quote checks on real recordings (honest strategies, foresight control, planted lead-lag) and prints what happened
  • scripts/requirements/runtime.txt - Hash-locked runtime dependencies (made from uv.lock with uv export; used for the SBOM; a test keeps it in step with the lock)
  • scripts/pin_release.py - Writes the hash-locked requirement line of a release on PyPI (the verifier image installs it with --require-hashes)
  • scripts/make_arrival_gif.py - Renders docs/assets/demo-arrival.gif from live verify_quotes runs
  • docs/project/PACKAGING.md - PyPI / TestPyPI free packaging checklist
  • SECURITY.md - Security policy and threat model
  • .github/workflows/security.yml - Bandit and pip-audit on every push, PR and weekly
  • .github/workflows/scorecard.yml - OpenSSF Scorecard (weekly)
  • docs/gallery.md - Gallery of example HTML reports (leak, no edge, honest, grid, universe, bad ticks)
  • docs/assets/reports/ - The example reports (generated by scripts/make_report_gallery.py)
  • scripts/make_report_gallery.py - Regenerate the example reports
  • src/monte_neo/verify/report_charts.py - SVG charts of the HTML report
  • src/monte_neo/verify/report_data.py - Data behind the report's charts (monthly returns, histogram, rolling Sharpe, cost curve, trade statistics)
  • src/monte_neo/verify/confidence.py - Bootstrap confidence intervals and the Minimum Track Record Length
  • src/monte_neo/verify/pbo.py - Probability of Backtest Overfitting (CSCV) for parameter searches
  • src/monte_neo/verify/claim.py - Claimed numbers against verified ones (--claim)
  • src/monte_neo/verify/microstructure.py - Spread estimate from high and low, capacity from volume
  • src/monte_neo/verify/quotes.py - Top-of-book quotes with arrival time: loading, quote quality, bars on the exchange and arrival clocks
  • src/monte_neo/verify/arrival.py - Arrival look-ahead, latency scan and latency Monte Carlo on quotes
  • src/monte_neo/verify/quotes_probes.py - The look-ahead probes of verify_strategy, run on the arrival bars of a quote run
  • src/monte_neo/verify/quotes_verdict.py - verify_quotes: one certificate for a strategy run on quotes with arrival time
  • src/monte_neo/verify/report_latency.py - "Time and latency" section and chart of the HTML report
  • src/monte_neo/data/quote_recorder.py - Records Binance futures bookTicker quotes with latency for verify --quotes
  • src/monte_neo/cli/quotes_cmd.py - monte-neo verify --quotes and --demo-quotes
  • .github/workflows/language-guard.yml - CI: runs the language guard on pull requests and on main
  • tests/unit/test_language_guard.py - Tests of the language guard