You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
An autonomous quantitative trading system for the Indian NSE market. 5-model ML ensemble, meta-controller combining 14 signal modules, persistent SQLite ledger, paper trading with short selling, model interpretability, and a React dashboard with FastAPI backend.
Quick Start
Requires uv (Python package manager) and Node.js 22.22+ (see web/.nvmrc).
start_dev.sh / start_dev.bat install both toolchains' dependencies automatically — you only need uv and Node.
# 1. Clone the repo
git clone https://github.com/uttampaliwal/stomar.git
cd stomar
# 2. Install uv (if not already installed)
curl -LsSf https://astral.sh/uv/install.sh | sh # Linux/macOS# powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex" # Windows# 3. Install Python + frontend dependencies and start both servers (FastAPI + React)
./start_dev.sh # Linux/macOS
start_dev.bat # Windows# 4. Train all models
uv run run_pipeline.py --train-all
# 5. Backfill history + train meta-controller
uv run run_daily.py --backfill
# 6. Start paper trading
uv run run_daily.py --paper-trade --capital 200000
All Python dependencies are declared in pyproject.toml and pinned in uv.lock.
uv sync creates the .venv (Python 3.13, pinned via .python-version) and installs
everything reproducibly — no manual venv/pip management.
Stacked meta-learner learns optimal model combinations from base predictions
Regime-conditional routing — Bull favors tree models, Bear favors DL
Walk-forward validation — 5-fold chronological splits, no data leakage
48+ technical features (RSI, MACD, Bollinger, ATR, ADX, Stochastic, Williams %R, CCI, MFI, VWAP, skew/kurtosis, triple-barrier labels)
Meta-Controller (14 → 1 decision)
Input Signal
Source
Learned Weight
Ensemble direction
ML models
Strongest
Ensemble confidence
ML models
High
Options PCR
NSE options chain
Negative (contrarian)
Sharpe ratio
Risk module
Positive
Regime bull/bear
Regime detection
Conditional
Sentiment score
5-source NLP
Variable
FII/DII flow
NSE institutional
Variable
MTF signal
Multi-timeframe
Variable
VaR/CVaR
Risk module
Negative (risk-off)
Volatility forecast
GARCH
Negative
Fundamental score
Screener.in
Positive
Model Interpretability
Feature importance — XGBoost/LightGBM gain-based ranking of top features driving predictions
Prediction explanations — Human-readable breakdown of why BUY/SELL/HOLD was chosen
Direction signals — Overbought/oversold, trend strength, volume analysis for top features
SHAP support — Optional SHAP-based explanations (install shap for full support)
Triple-Barrier Labels
Superior ML training targets that account for realistic trading conditions:
Upper barrier — Profit-taking level (2% default)
Lower barrier — Stop-loss level (2% default)
Vertical barrier — Maximum holding period (5 days default)
Labels: 1 = profit hit first, 0 = loss hit first, 2 = time expired
Autonomous Daily Loop
The recommended entry point is the auto-pipeline — one idempotent run
covers gap detection, backfill, training, today's decisions, paper trades,
and the Telegram summary:
uv run auto_pipeline.py # Everything, idempotent (safe to rerun)
uv run auto_pipeline.py --force # Force even if already ran today
uv run auto_pipeline.py --setup # One-command device setup: env + Telegram + GPU + scheduler
uv run auto_pipeline.py --setup-run # Same, plus run the pipeline immediately
uv run auto_pipeline.py --capital 200000 # Paper starting capital
The lower-level single-day loop remains available:
uv run run_daily.py # Run all 20 NSE stocks
uv run run_daily.py --ticker RELIANCE.NS # Specific tickers
uv run run_daily.py --backfill # Backfill 1 year + train meta
uv run run_daily.py --train-meta # Retrain meta-controller
uv run run_daily.py --paper-trade # Auto-execute paper trades
uv run run_daily.py --dry-run # Signals only, no ledger writes
Paper Trading (with short selling)
Short positions — SELL without existing position opens short
Cover — BUY covers short position
Position sizing — Meta-controller confidence scales trade size
State persistence — data/paper_state.json survives restarts
Full prediction explanation with direction signals
Meta-Controller
Endpoint
Method
Description
/api/consensus/
GET
All tickers consensus
Paper Trading
Endpoint
Method
Description
/api/paper-trading/state
GET
Current portfolio state
/api/paper-trading/order
POST
Place paper order
/api/paper-trading/positions
GET
Open positions
/api/paper-trading/trades
GET
Trade history
/api/paper-trading/close-position
POST
Close/cover a position
/api/paper-trading/reset
POST
Reset paper trading account
Monitoring
Endpoint
Method
Description
/api/monitoring/
GET
System health + model status
/api/pipeline/status
GET
Training pipeline status
/api/pipeline/run
POST
Start orchestrator run
/api/pipeline/run/status
GET
Orchestrator run progress
/api/pipeline/train/{ticker}
POST
Train one ticker's models
CLI Usage
# Recommended: auto-pipeline (idempotent full run: backfill + daily + paper + summary)
uv run auto_pipeline.py # Everything (safe to rerun daily)
uv run auto_pipeline.py --force # Force even if already ran today
uv run auto_pipeline.py --setup-run # Setup device + run (one command)# Single-day loop (legacy)
uv run run_daily.py # All 20 NSE stocks
uv run run_daily.py --ticker RELIANCE.NS # Specific tickers
uv run run_daily.py --backfill # Backfill 1 year
uv run run_daily.py --train-meta # Retrain meta-controller
uv run run_daily.py --paper-trade # Auto paper trades
uv run run_daily.py --paper-trade --capital 500000
# Retraining pipeline
uv run run_pipeline.py --train-all # Train all 20 stocks
uv run run_pipeline.py --train RELIANCE.NS # Specific tickers
uv run run_pipeline.py --paper # Train + paper trade# Scheduler (host cron / systemd timer / Windows Task Scheduler)
uv run schedule_pipeline.py # Install daily 15:45 IST + boot catch-up
uv run schedule_pipeline.py --remove # Remove task
uv run schedule_pipeline.py --run-now # Run immediately
Docker (one-command startup)
cp .env.example .env # set STOMAR_API_KEY, SMTP, PAPER_CAPITAL...
docker compose up -d --build
api — FastAPI + bundled React SPA on port 8000, healthchecked, auto-restart.
scheduler — cron daemon in-container running the tested schedule_pipeline.py
(weekdays 15:45 IST auto-pipeline run + boot catch-up for missed days).
State persists in named volumes stomar-data (SQLite/ledger/paper state/logs)
and stomar-models (trained weights + meta-controller).
CPU-only torch is baked into the image (see pyproject.toml[tool.uv.sources]);
no GPU or CUDA runtime needed.
Verify: curl http://localhost:8000/api/health and docker compose exec scheduler crontab -l.
Tests
# Run all 750 tests
uv run pytest tests/ -v
# Run with coverage
uv run pytest tests/ --cov=src --cov-report=term-missing
# Lint check (whole repo, same as CI)
uv run ruff check .
AI-powered quantitative stock market research platform with ML ensemble models, multi-timeframe analysis, explainable signals, paper trading, backtesting, risk management, FastAPI APIs, and production-focused architecture for algorithmic trading research.
