<div align="center"> <img width="124" height="124" alt="image" src="https://github.com/user-attachments/assets/bf450abd-f468-43fa-9750-464e3ef95651" />

KAIROS QUANT SYSTEM

End-to-End Data Analytics Pipeline for Financial Market Research

Stack: Python 3.12+ • Pandas • Polars • PyTorch • DuckDB • PyQt6 • CCXT

</div> <div align="left">

---

Quick Start

Want to run it immediately? Follow these 3 steps:

# 1. Clone repository and install dependencies
git clone https://github.com/PVinh-Quant/Kairos-v2 && cd Kairos-v2 && pip install -r requirements.txt

# 2. Run the main program
python main.py

# 3. Select mode (Demo, Backtest, Optimize, Dashboard)

See Installation & Setup for more details.

---

Core Capabilities & Value Proposition

KAIROS QUANT SYSTEM is an end-to-end data analytics and quantitative research platform designed to help strategy developers and traders transform raw market data into investment decisions backed by statistical rigor and machine learning.

🎯 Core Value & Utility (Why Kairos?)

• Eliminate Look-Ahead Bias: A strict 4-step multi-timeframe alignment pipeline guarantees that backtested signals reflect exactly what was historically available at the moment of execution.
• Rigorous Statistical Validation: Eliminate "lucky" parameters and overfitting via Walk-Forward Validation and Deflated Sharpe Ratio (DSR) metrics.
• 100x+ Research Acceleration: High-performance vectorized computations powered by Polars & Pandas allow you to backtest millions of rows of data in seconds.
• Zero Train-Serve Skew: The exact same feature-generation logic (calc_core_features) is shared between offline ML training and real-time live trading.

---

⚙️ Main System Functionalities

| Core Feature | Description | |---|---| | Automated ETL Pipeline | Raw API $\rightarrow$ Clean Dataset. Automatically downloads multi-timeframe OHLCV (1m–1d) from Binance, OKX, and Bybit using CCXT & WebSockets. Handles timestamp alignment and auto-fills missing candles. | | Feature Engineering Engine | Calculates 49 technical indicators in parallel across 8 timeframes (including Price Structure/SMC, Volume Profile, proxy CVD, and session indicators). | | Market Regime Classifier | A PyTorch ResBlock MLP neural network that classifies market conditions into 8 distinct regimes to adaptively route capital and strategies. | | Multi-Mode Backtester | Supports realistic single/multi-threaded bar-by-bar simulations (to prevent execution leaks) and lightning-fast Vectorized Backtesting. | | Bayesian Hyperparameter Optimizer | Automates parameter searches using Bayesian optimization combined with Walk-Forward tests, outputting deployable strategy parameters in JSON. | | DuckDB SQL Analytical Warehouse | Stores all execution logs and backtest records in an embedded DuckDB database for cross-run, ad-hoc SQL performance profiling. | | Interactive PyQt6 Dashboard | Desktop UI containing: Analytics Dashboard (equity, drawdown, heatmaps), Real-time Monitor for live positions, and the Indicator Live Workbench sandbox. | | Live & Paper Trading Execution | Connects to exchange APIs to manage orders, positions, and stops (SL/TP) in real-time or paper trading mode via CCXT. |

---

Analytics Dashboard Preview

<img width="1920" height="1080" alt="image" src="https://github.com/user-attachments/assets/8928cf66-ca8c-403d-815e-e6e05b2b03df" />

---

Key Results & Achievements

| Achievement | Detail | |-----------|---------| | Big Data Processing | Parallel processing of millions of historical rows (multi-year, multi-asset) without memory leaks. | | Computation Speed | Vectorization reduces calculation time from hours to minutes for the same data volume. | | No Look-Ahead Bias | Carefully designed multi-timeframe feature alignment prevents data leaks, aligning backtesting closely with live trading. | | Integrated Data Warehouse | Every backtest execution is stored in DuckDB, enabling multi-run cross queries (winrate, PnL, drawdown by hour/day/regime). | | Statistical Validation | Walk-Forward validation combined with Deflated Sharpe Ratio (DSR) and OOS/IS ratio builds confidence before deployment. | | Fully Automated | End-to-end automation from data ingestion, cleaning, feature engineering, modeling, storing, to PyQt6 visualization. |

Table of Contents

1. Vision & Methodology — Core philosophy, key quantitative problems.
2. System Overview — 8 operating modes, modular architecture.
3. Core Skills & Technologies — Data engineering, ML, visualization.
4. Data Ingestion & Ingress Pipeline — ETL, OHLCV resampler.
5. Feature Engineering & Ensemble Scoring — 49 indicators, 8 timeframes.
6. ML Pipeline: Regime Classification — 8 market regimes, PyTorch model.
7. Analytics Dashboard, Optimizer & Indicator Live — PyQt6 apps, Walk-Forward.
8. SQL Analytics & Data Warehouse — DuckDB embedded warehouse.
9. Risk Management & Validation Guardrails — Quality control, ATR stops, dynamic leverage.
10. Directory Layout — Project structure.
11. Requirements & Installation — CLI steps and packages.
12. Configuration & Running Guide — CLI menu, configs.
13. Roadmap — Future development suggestions.
14. Tutorial: Researching a Strategy from Scratch — Step-by-step quant workflow.
15. Risk Disclaimer — Performance warnings.
16. Author's Note — Development thoughts.
17. Detailed Technical Reference Manual — Deep dives.

---

<a name="1"></a>

1. VISION & METHODOLOGY

KAIROS QUANT SYSTEM represents an institutional-grade quantitative research and execution ecosystem. The platform enforces a scientific, data-driven approach to algorithmic trading: every trading hypothesis must be quantified and validated statistically against historical data before deployment.

Core Philosophy

"Data is the only source of truth. Every investment assumption must pass rigorous statistical verification."

Core Problems Addressed

| # | Trader Challenge | KAIROS Solution | |---|------------------|-----------------| | 1 | Siloed and fragmented data: Handling raw data from multiple exchanges and formats is complex and error-prone. | Unified ETL Pipeline: Standardizes multi-source REST/WebSocket data into a single, clean Source of Truth. | | 2 | Look-Ahead Bias / Data Leaks: Backtests show unrealistically good results due to using future information. | Anti-Leakage MTF Engine: A strict 4-step timestamp alignment process ensuring backtests reflect 100% reality. | | 3 | Overfitting / Backtest Over-optimization: Strategies look perfect on past data but fail quickly in live markets. | Walk-Forward Validation & DSR: Multi-phase split-testing combined with Deflated Sharpe Ratio calculation to filter out luck. | | 4 | Lack of adaptability to market shifts: Fixed strategies lose edge when market conditions transition. | ML Regime Router (PyTorch): Identifies 8 distinct market regimes to dynamically route capital to optimal strategies. |

Data Science Lifecycle

| Stage | Tech Stack | Value Added | |-----------|-------------------|------------------| | Ingest | REST API (CCXT) + WebSocket streams | Automatically ingests historical OHLCV and real-time market streams. | | Clean | Multi-TF resampling & gap-filling | Normalizes timestamps and automatically recovers missing candles. | | Feature| 49 indicators across 8 timeframes | High-performance feature engineering using Polars/Pandas. | | Validate| Walk-forward backtester | Simulates performance without look-ahead bias or survival bias. | | Model | Regime Classification (ResBlock MLP) | Classifies market behaviors using deep neural network states. | | Analyze| DuckDB SQL Analytical Warehouse | Evaluates and cross-compares performance across multiple runs. |

---

<a name="2"></a>

2. SYSTEM OVERVIEW & OPERATING MODES

KAIROS is structured as a closed-loop data analytics ecosystem, integrating research, validation, and execution into a single unified workspace.

Modular Architecture

The codebase strictly adheres to:

"Decoupled, Stateless Modules (Zero Shared External State Dependency)" — Every class and function receives explicit inputs and returns deterministic outputs.

This allows quant developers to easily test individual pipeline layers in isolation, perform unit testing, and update machine learning models without breaking the operational pipeline.

8 Operating Modes

The interactive Command-Line Interface (CLI) allows researchers to run 8 specialized modes matching various stages of quant development:

| Mode | Operation | Target Use Case | Target Audience | |:---:|---|---|---| | 1 | Realtime Trading | Integrates with exchange APIs to execute real trades. | Live Traders | | 2 | Demo / Paper | Processes real-time data and logs virtual executions. | Risk-Free Live Test