Nothing Gambles Like A Bot (NGLAB)

A Comprehensive Multimodal Intelligence Framework for Quantitative Finance and Automated Gambling.

📚 Documentation | Overview | Features | Quickstart | Paradigms | Models | Datasets | Setup | Usage

---

📚 Documentation Hub

Start here! We have expanded our documentation to cover every aspect of the system.

Document	Description	Target Audience
TUTORIAL.md	The Developer Encyclopedia. Exhaustive deep dives into every module, code snippets, and implementation details.	Developers, Contributors
Interactive Notebooks	Hands-on Learning. A series of 10 Jupyter notebooks covering architecture, RL training, and backtesting.	Everyone
AGENTS.md	The Strategy Handbook. Classification of Agents (RL vs Heuristic), Policy Architectures (Mamba/CNN), and Observation Spaces.	Quants, Researchers
ARCHITECTURE.md	The System Blueprint. High-level design, data flow diagrams, system boundaries, and deployment topology.	Architects, DevOps
DEVELOPMENT.md	The Setup Guide. IDE configuration, environment variables, local development, profiling, and debugging.	New Contributors
TESTING.md	The Quality Guide. Testing philosophy, coverage requirements, mocking strategies, and CI/CD integration.	All Engineers
CONTRIBUTING.md	The Developer Handbook. Code style, PR process, RFC workflow, and release procedures.	Contributors
TROUBLESHOOTING.md	The Field Repair Manual. Common issues, diagnostic steps, GPU/CUDA debugging, and ML troubleshooting.	Everyone
IMPROVEMENTS.md	The Roadmap. Active tasks, feature requests, and the long-term vision for the platform.	Project Managers

📓 Interactive Notebooks

Experience NGLab hands-on through our curated tutorial series. Each notebook provides a deep dive into specific components with runnable code and real-time visualizations.

#	Topic	Key Concepts
01	Quickstart Intro	Polyglot Architecture, Component Communication
02	Rust OrderBook	Matching Engine, Time-Price Priority, VaR
03	Trading Environment	Gymnasium Interface, Step Lifecycle, Rewards
04	Forecasting	ARIMA, GARCH, RNN/Mamba Predictions
05	Deep Learning	VAE Regime Detection, Dilated Convolutions
06	HPO Optimization	DEHB Algorithm, Successive Halving
07	RL Training	PPO Algorithm, Policy/Value Networks
08	Multi-Agent	Strategic Emergence, Competitive Game Theory
09	Backtesting	Slippage, Transaction Costs, Performance Metrics
10	Advanced Topics	Custom Reward Shaping, Probabilistic Ensembles

Tip

Start with 01_quickstart_introduction.ipynb to verify your environment and understand the core data flow.

---

Overview

NGLAB is a high-performance framework designed to navigate the complexities of financial markets. It combines state-of-the-art Deep Learning, Classical Machine Learning, and Reinforcement Learning to fuse numerical price data with global sentiment analysis.

NGLAB isn't just a trading bot; it's an end-to-end research and execution arena that decouples financial engineering from model experimentation. The platform provides:

• High-fidelity market simulation with microsecond-level order book dynamics
• Modular ML pipeline supporting 30+ model architectures
• Real-time visualization through a modern desktop application
• Production-ready infrastructure with Docker, Kubernetes, and CI/CD support

---

Key Features

🚀 Performance

Metric	Achievement
Order Matching	< 100μs latency
Environment Steps	> 20,000 steps/second
Data Bridge	Zero-copy NumPy via PyO3
UI Rendering	Locked 60 FPS

🧠 Intelligence

• 30+ Model Architectures: From classical ARIMA to cutting-edge Mamba (SSM)
• Multiple RL Algorithms: PPO, SAC, DQN with TorchRL integration
• Automated HPO: DEHB (Differential Evolution Hyperband) for efficient hyperparameter search
• Meta-Learning: MAML for rapid adaptation to new market regimes

🎯 Simulation

• Central Limit Order Book (CLOB): Full price-time priority matching
• Advanced Order Types: Iceberg, Trailing Stop, Stop-Loss, Take-Profit
• Multi-Asset Support: Trade portfolios across multiple instruments
• Polymarket Integration: Prediction market simulation and data scraping

🖥️ User Experience

• Cross-Platform Desktop App: Built with Tauri 2.0 (Rust + React)
• Real-Time Charts: High-performance visualization with lightweight-charts
• Interactive Analysis: EDA tools, backtesting, and model comparison

---

Quickstart

Get up and running in 5 minutes:

# 1. Clone the repository
git clone https://github.com/acfharbinger/nglab.git
cd nglab

# 2. Run automated setup
just setup

# 3. Build the Rust extension
just build-python

# 4. Start training
python python/src/pipeline/train_ppo.py

# 5. Launch the GUI (optional)
npm run tauri dev

Verify Installation

# Check all components
just check-health

# Run tests
just test

---

Learning Paradigms

NGLAB implements a modular pipeline system supporting diverse learning strategies:

Paradigm	Description	Use Case
Reinforcement Learning	Vectorized environments for portfolio optimization	Trading agent training
Supervised Learning	High-precision forecasting and regression	Price prediction
Self-Supervised	Latent representation learning using VAEs	Market regime detection
Unsupervised	Clustering and anomaly detection	Outlier identification
Semi-Supervised	Leveraging unlabeled data with sparse labels	Label-efficient learning
Meta-Learning	Rapid adaptation via MAML	Market regime shifts
Online Learning	Continuous adaptation to market drift	Live trading

---

Model Ecosystem

We provide a vast library of models categorized into two primary families:

🏛️ Classical Machine Learning (Mac Models)

Efficient, interpretable, and robust baseline models:

Category	Models
Trees & Ensembles	Random Forest, Gradient Boosting, XGBoost, LightGBM, CatBoost
Linear & Kernel	Ridge, Lasso, ElasticNet, SVM
Probabilistic	Naive Bayes, Bayesian Networks
Instance-based	K-Nearest Neighbors (KNN)
Time Series	ARIMA, GARCH, Exponential Smoothing, Prophet

🧠 Deep Learning (Deep Models)

Modern neural architectures specialized for sequence and multimodal data:

Category	Models
Attention	NS-Transformers, Multi-Head Attention
State Space	Mamba (SSM), S4, Liquid Neural Networks
Recurrent	LSTM, GRU, xLSTM
Generative	VAE, TimeGAN, Diffusion U-Net, Flow-based
Advanced	Neural ODE, PINN, DNC, SNN

---

Datasets

NGLAB leverages a diverse range of data sources for training and inference:

📈 Stock Market Data

Dataset	Description	Source
Stock Market Dataset	Stocks and ETFs from 1999 to 2020	Kaggle
S&P 500	Historical index data	Yahoo Finance
Crypto	Bitcoin, Ethereum tick data	Binance API

📰 Textual & Sentiment Data

Dataset	Description	Source
BBC News	News articles 2004-2005	UCD
Australia News	News from 2003-2021	Harvard Dataverse
World Politics	International news	NewsData.io
Global News	Multi-source news	Kaggle
Twitter/X	Social media sentiment	Kaggle

🎲 Prediction Markets

Dataset	Description	Source
Polymarket	Real-time prediction market data	Polymarket API
Metaculus	Historical forecasting data	Metaculus

---

Project Structure

nglab/
├── rust/                 # 🦀 Rust simulation engine
│   ├── src/
│   │   ├── simulation/   # TradingEnv, OrderBook, PolymarketArena
│   │   ├── models/       # Black-Scholes, Heston, Credit Risk
│   │   ├── moon/         # ARIMA, GARCH, Prophet
│   │   └── web/          # Polymarket scraper
│   └── Cargo.toml
├── python/               # 🐍 Python ML pipeline
│   ├── src/
│   │   ├── models/       # VAE, GAN, Diffusion, Mamba, etc.
│   │   ├── pipeline/     # Training scripts, HPO
│   │   ├── agents/       # RL agents, wrappers
│   │   ├── policies/     # Trading strategies
│   │   └── env/          # Environment wrappers
│   └── pyproject.toml
├── typescript/           # 📱 Tauri desktop app
│   ├── src/              # React frontend
│   │   ├── components/   # UI components
│   │   ├── hooks/        # React hooks
│   │   └── App.tsx
│   └── src-tauri/        # Rust backend for Tauri
├── android/              # 🤖 Android mobile app (Kotlin)
│   └── src/              # App logic and UI
├── deploy/               # 🚀 Deployment configs
│   ├── nginx/            # Nginx (Reverse Proxy)
│   ├── k8s/              # Kubernetes (Overlays: dev, staging, prod)
│   └── helm/             # Helm charts (Chart.yaml, values.yaml)
├── scripts/              # 🛠️ Utility scripts
└── .github/              # CI/CD workflows

---

Setup Dependencies

You can choose to install this repository's dependencies using any of the following methods:

⚡ UV (Recommended)

Fastest setup using the uv package manager.

# Sync the project and create a virtual environment
uv sync

# Activate the environment
source .venv/bin/activate  # Linux/macOS
.venv\Scripts\activate.bat # Windows CMD

To deactivate and/or delete the created virtual environment:

deactivate
rm -rf .venv

🐍 Anaconda

conda env create --file env/environment.yml -y --name wsr
conda activate wsr

📦 Virtual Environment (Standard)

Note

This method requires Python 3.11 pre-installed on your system.

python3 -m venv env/.wsr
source env/.wsr/bin/activate
pip install -r env/requirements.txt
pip install -r env/pip_requirements.txt

To deactivate and/or delete the created virtual environment:

deactivate
rm -rf env/.wsr

🐳 Docker

# Build the image
docker build -f Dockerfile.prod -t nglab:latest .

# Run the container
docker run --gpus all -p 8080:8080 nglab:latest

---

Execute Program

Choose your preferred interface to interact with the program!

🛠️ Terminal User Interface (TUI)

Run the Rust-based CLI for high-performance operations:

cargo run --bin nglab-cli

🖥️ Graphical User Interface (GUI)

Run the TypeScript/Tauri GUI for a modern, cross-platform experience:

cd typescript
npm run tauri dev

🐍 Python Scripts

Run training and inference directly:

# Train a PPO agent
python python/src/pipeline/train_ppo.py

# Run inference
python python/src/pipeline/infer.py --model checkpoint.pt

# Hyperparameter optimization
python python/src/pipeline/hpo/run_dehb.py

📊 Just Commands

Use the task runner for common operations:

just              # List all available commands
just setup        # Full environment setup
just build        # Build all components
just test         # Run all tests
just lint         # Run linters
just fmt          # Format code
just dev          # Start development environment
just clean        # Clean build artifacts

---

Setup Scripts

For a fully automated environment setup, use the provided scripts:

# Environment setup (choose method)
bash scripts/setup_env.sh <uv|conda|venv>

# Build Rust components
bash scripts/build_rust.sh

# Build Docker images
bash scripts/build_docker.sh

# Database backup
bash scripts/backup_db.sh

# Cleanup
bash scripts/cleanup.sh

---

Performance Benchmarks

Component	Metric	Target	Achieved
OrderBook Insert	Latency	< 1ms	~0.1ms
TradingEnv Step	Latency	< 1ms	~0.5ms
Order Matching	Throughput	> 10k ops/sec	~50k ops/sec
Memory Usage	RAM	< 100MB	~50MB
Model Forward	Latency	< 10ms	~5ms (Mamba)
Training Step	Latency	< 100ms	~80ms

---

Contributing

We welcome contributions! Please read our CONTRIBUTING.md for guidelines on:

• Code style and linting
• Pull request process
• RFC workflow for major changes
• Release procedures

---

License

This project is licensed under the GNU Affero General Public License v3.0 - see the LICENSE file for details.

---

Acknowledgments

• PyTorch - Deep learning framework
• TorchRL - Reinforcement learning library
• Tauri - Desktop application framework
• Hydra - Configuration management
• Mamba - State space model architecture
• Kubernetes - Container orchestration
• PostgreSQL - Primary database
• Redis - Caching and real-time state
• Kotlin - Android development
• MyPy - Static type checking for Python

---

NGLab - Where AI meets the markets