What are we trying to achieve with AI? We are building a trading robot that thinks exactly like a highly profitable human trader. Instead of writing rigid rules for the robot to follow, we are feeding the AI 271 days of the trader's actual winning trades from Sensibull. By analyzing those trades against 4 key market indicators, the AI will learn the hidden patterns—the "Smart Money Footprints"—and execute trades automatically with the exact same discretion and intuition as the professional trader.

The 4 indicators the AI tracks (detailed in the Trade Finder Strategy):

• Volume (Total shares traded)
• Open Interest (Buildup/decline of outstanding option contracts)
• Bid-Ask Spread (Urgency and liquidity)
• Turnover (Total value of the transactions)

Project-R (DeepQuant) is a sovereign AI-driven algorithmic trading ecosystem designed to reverse-engineer and automate the "Smart Money" execution patterns of high-performance institutional traders.

By synthesizing 271+ days of verified Sensibull P&L data with a proprietary 4-factor Z-score engine (Volume, OI, Spread, Turnover), Project-R builds a deterministic AI agent that thinks, scans, and executes like a professional market maker.

To fully automate the discretion of the "Smart Money" strategy (originally sourced from the Trade Finder YouTube Deep Dive), the hard-coded logic is superseded by a 4-phase Machine Learning pipeline:

1. Mindset Cloning (Supervised Learning): Training XGBoost models on Sensibull PnL data alongside Historify tick data to dynamically predict setup probability instead of relying on static thresholds.
2. Smart-Money Detection (Unsupervised): Using Isolation Forests on a rolling 20-day window of the 4 R-factors to identify mathematical anomalies in capital flow:
   • Open Interest: The buildup or decline of outstanding contracts (Directional Compass).
   • Volumes: The total number of shares traded (Participation Gate).
   • Bid-Ask Spread: The difference between the highest price a buyer is willing to pay and the lowest price a seller is willing to accept (Urgency Metric).
   • Turnover: The total value of the transactions (Quality Filter).
3. Adaptive Execution (Reinforcement Learning): PPO agents adapting execution routing (Limits vs. Market Order) dynamically based on the current regime (Elephant vs. Cheetah).
4. Trader Intuition (LLM Integration): Fine-tuned local LLM for post-trade journaling, translating the Z-Scores and OI data into human-readable rationale.

An autonomous engine that translates institutional thinking into code (Strategy sourced from Trade Finder YouTube Deep Dive):

• R-Factor Triggering: Detects when large investors are aggressively building positions relative to their normal 20-day activity.
• AI Filtering: Uses fine-tuned models to validate setups based on the "Blast Protocol" and seller-side option bias.
• Low-Latency Execution: Seamless integration with Dhan V2 for automated market entry and exit.

A specialized "Lab" for mastering market microstructure:

• Regime Classification: Dynamically identifies Elephant (stable) vs. Cheetah (volatile) stocks to optimize execution.
• Statistical Standardization: Filters out retail noise by standardizing Volume, OI, and Spread anomalies ($Z > 3.0$).
• Smart Money Footprinting: Deep-dive analysis of Cumulative Turnover Integrals to find accelerating flow.

Professional-grade infrastructure for high-performance data management:

• DuckDB Columnar Storage: Ultra-fast storage for millions of rows of OHLCV and OI data using local .parquet generation.
• Automated Sync Pipelines: Node architectures (sync_all_fno, sync_5min_fno) to scrape extensive 90-day chunks from Dhan V2.
• Cloud Data Lake Integration: Query 18+ months of F&O data directly from Hugging Face datasets (fno-5min & fno-data-18months) using DuckDB's httpfs extension—streaming only the required bytes without local downloads.

Reverse-engineering winning streaks via verified data (Target: Sensibull Verified P&L):

• Playwright Extractor: Scrapes and normalizes 271+ days of verified trades from Sensibull.
• AI-Powered Analysis: An MCP Server that enables natural language querying of trade history to extract tactical insights for model training.

The core engine transitions from static statistical rules to dynamic machine learning models to capture the "Smart Money" footprints modeled after verified sensible trades:

• AI Phase 1: Mindset Cloning: Supervised learning (XGBoost/LightGBM) trained on Playwright-extracted Sensibull PnL data integrated with Historify tick data, directly predicting the probability of the trader's setup.
• AI Phase 2: Dynamic Smart-Money Detection: Unsupervised learning (Isolation Forests/Autoencoders) on a rolling 20-day window of the 4 R-Factors to identify true market anomalies without hard-coded limits.
  • Open Interest ($Z_{OI}$): Tracking institutional put-selling vs. call-selling (e.g., Rising Put OI + Price > ORB).
  • Volumes ($Z_{Vol}$): Measuring total shares traded to confirm participation.
  • Bid-Ask Spread ($Z_{Spread}$): Calculating urgency and liquidity consumption.
  • Turnover ($Z_{Turn}$): Evaluating total capital commitment.
• AI Phase 3: The "Blast" Protocol Execution Engine: Reinforcement Learning (PPO) agent adapting execution logic between "Elephant" (limit orders) and "Cheetah" (market orders) regimes to minimize slippage.
• AI Phase 4: Trader's Intuition: Fine-tuned local LLM (e.g., Llama 3) for trade journaling and post-trade natural language analysis, mimicking the trader's thought process.

Project-R (DeepQuant) is a sovereign AI-driven algorithmic trading ecosystem designed to reverse-engineer and automate the "Smart Money" execution patterns of high-performance institutional traders.

By synthesizing 271+ days of verified Sensibull P&L data with a proprietary 4-factor Z-score engine, Project-R builds a deterministic AI agent that thinks, scans, and executes like a professional market maker.

The ultimate goal of Project-R is to "crack" and automate an institutional-grade trading mindset by combining:

1. Mindset Automation: Training and fine-tuning AI models on specific historical "Trade Finder" datasets to replicate the logic of elite traders.
2. The Put OI Compass: Moving beyond simple volume to track Put Option Open Interest as the true indicator of "Smart Money" bias (Put writing = Bullish conviction).
3. Relative Intelligence (R-Factor): Benchmarking every market variable against its 20-day historical mean to identify high-conviction institutional participation.

Sovereign, layered architecture inspired by the OpenClaw topology:

• Layer 1: Surfaces: Next.js 16 Web Dashboard & CLI.
• Layer 2: Channels: Dhan WebSocket & Filesystem adapters.
• Layer 3: Sessions: State isolation via Zustand.
• Layer 4: Gateway: Central control plane for secure ingress/egress.
• Layer 5: Runtime: The deterministic R-Factor logic substrate.
• Layer 6: Tools: SQLite/DuckDB persistence and technical modules.

• Framework: Next.js 16 (App Router) + React 19
• Language: TypeScript 5.7+ (Node.js 22+)
• Database: SQLite (better-sqlite3) + DuckDB (Parquet)
• AI Tools: MCP Server + Playwright (Extraction)
• Charting: Lightweight Charts v5 (Real-time)
• Package Manager: pnpm 10.x

• Node.js 22+
• pnpm 10.x (packageManager: [email protected])
• Git LFS — required to fetch the bundled database backup (see the Database section below)

# 1. Clone and fetch LFS-tracked assets (e.g. the DB backup)
git clone https://github.com/charan1922/Project-R.git
cd Project-R
git lfs install
git lfs pull

# 2. Install dependencies
pnpm install

# 3. Generate the Prisma client (REQUIRED — not run automatically by pnpm install)
pnpm db:generate

# 4. Configure environment (see below), then start the dev server
pnpm dev            # http://localhost:5000

Heads up: pnpm install does not generate the Prisma client on this setup (pnpm no longer reads the pnpm field in package.json). If the dev server crashes with Cannot find module '.prisma/client/default', run pnpm db:generate and restart.

Create a .env.local file in the project root (never commit it):

DHAN_CLIENT_ID=<client-id>
DHAN_ACCESS_TOKEN=<jwt-token>        # Optional if TOTP is configured
DHAN_PIN=<6-digit-pin>               # For TOTP auto-token generation
DHAN_TOTP_SECRET=<base32-secret>     # From the Dhan authenticator setup
DATABASE_URL=<url>                   # Optional: defaults to SQLite file:data/project-r.db
NEXT_PUBLIC_SENTRY_DSN=<sentry-dsn>  # Optional: error tracking
SENTRY_ORG=<org>                     # Optional: source maps
SENTRY_PROJECT=<project>             # Optional: source maps

• Engine: SQLite via Prisma (@prisma/adapter-better-sqlite3); large market datasets use DuckDB/Parquet.
• Location: data/project-r.db (gitignored — never committed directly).
• Schema: prisma/schema.prisma. After install, run pnpm db:generate; apply migrations with pnpm db:migrate.
• Backup via Git LFS: Database snapshots (*.db.bak-*) are tracked with Git LFS so the ~100 MB+ binaries stay out of regular git history. After cloning, run git lfs install && git lfs pull to download them. To restore a snapshot, copy it over the active DB:

cp project-r.db.bak-<timestamp> data/project-r.db

• Verified Performance: Sensibull Verified P&L (fanged-okra)
• Strategy Insights: Smart Money & R-Factor Deep Dive (YouTube)
• Design Docs: See the /strategy/ and /openspec/ directories for detailed architectural and algorithmic specifications.