🛡️ RakshaQuant

Agentic Paper Trading System for NSE

Where Large Language Models Meet Financial Markets

</div>

🎯 About This Project

RakshaQuant (रक्षा = Protection in Sanskrit) is an autonomous agentic trading system designed for the Indian NSE market. It leverages LangGraph to orchestrate a team of specialized AI agents that analyze market data, formulate strategies, validate signals, and manage risk in real-time.

Unlike traditional algorithmic trading that relies solely on hardcoded logic, RakshaQuant introduces cognitive flexibility—using LLMs to reason about market regimes (bull/bear/ranging) and adapt its strategies accordingly.

Key Capabilities

🤖 Cognitive Agents: Multi-agent system that "thinks" before it trades
🌐 Live Market Analysis: Real-time multi-stock monitoring via WebSocket
🛡️ Dynamic Risk Management: Agents that can veto trades based on risk parameters
📊 Professional Dashboard: Real-time CLI interface for monitoring agent thought processes
📝 Self-Improving Memory: Learns from past mistakes using semantic memory
🆓 100% Free Tier Mode: Paper trading without any paid API dependencies

🆕 What's New (v2.0)

Free Tier Paper Trading

No paid broker API required! RakshaQuant now supports 100% free paper trading:

| Feature | Free Tier | Description | | ------------------- | -------------------- | ---------------------------------------- | | Market Data | ✅ YFinance | Real NSE quotes (1-15 min delay) | | Execution | ✅ Local Paper | Virtual ₹10L wallet simulation | | News Sentiment | ✅ Google RSS + Groq | AI-powered news analysis | | Stock Discovery | ✅ Dynamic | Finds trending stocks from news & movers |

Dynamic Stock Discovery

No more hardcoded watchlists! The system now automatically discovers which stocks to trade based on:

📰 News Mentions - Scans Google News for trending stocks
📈 Market Movers - Identifies top gainers/losers

New Modules

| Module | Purpose | | ------------------------------- | ------------------------------------- | | src/utils/rate_limiter.py | Prevents Groq API rate limit errors | | src/utils/cache.py | TTL cache for news, quotes, sentiment | | src/notifications/telegram.py | Trade alerts on your phone | | src/backtesting/ | Test strategies on historical data | | src/market/stock_discovery.py | Dynamic stock discovery | | src/execution/paper_engine.py | Local paper trading engine |

🏗️ Architecture

RakshaQuant uses a hierarchical agent graph where specialized agents collaborate to make trading decisions.

High Level Design(HLD)

System Overview

flowchart TB
    subgraph External["🌐 External Services"]
        GROQ["Groq LLM API<br/>llama-3.3-70b"]
        YFINANCE["Yahoo Finance<br/>(Free Market Data)"]
        DHAN["DhanHQ Broker API<br/>(Optional)"]
        LANGSMITH["LangSmith<br/>Observability"]
        TELEGRAM["Telegram Bot API"]
        POSTGRES[("PostgreSQL<br/>Agent Memory")]
    end

    subgraph Config["⚙️ Configuration Layer"]
        SETTINGS["Settings<br/>(Pydantic)"]
        ENV[".env File"]
    end

    subgraph Market["📊 Market Data Layer"]
        direction TB
        MANAGER["MarketDataManager"]

        subgraph DataSources["Data Sources"]
            WS_FEED["WebSocket Feed<br/>(Live Hours)"]
            YF_FEED["YFinance Feed<br/>(Free Tier)"]
            SIM_FEED["Simulated Data<br/>(After Hours)"]
        end

        INDICATORS["Indicator Calculator<br/>(RSI, MACD, Bollinger)"]
        SIGNALS["Signal Engine<br/>(Buy/Sell Generation)"]
        DISCOVERY["Stock Discovery<br/>(NSE Top Movers)"]
    end

    subgraph Agents["🤖 Agent Decision Layer (LangGraph)"]
        direction TB
        STATE["TradingState<br/>(TypedDict)"]

        subgraph AgentGraph["Agent Workflow Graph"]
            direction LR
            REGIME["Market Regime Agent"]
            STRATEGY["Strategy Selection Agent"]
            VALIDATION["Signal Validation Agent"]
            RISK["Risk & Compliance Agent"]
        end

        subgraph SupportAgents["Support Agents"]
            NEWS["News Analyst Agent"]
            SENTIMENT["Sentiment Agent"]
            PREDICTION["Prediction Agent"]
        end
    end

    subgraph Memory["🧠 Memory & Learning Layer"]
        direction TB
        MEMORY_DB["AgentMemoryDB<br/>(Lessons Storage)"]
        CLASSIFIER["MistakeClassifier<br/>(Loss Analysis)"]
        ANALYZER["TradeAnalyzer<br/>(Outcome Review)"]
        INJECTOR["MemoryInjector<br/>(Context Injection)"]
    end

    subgraph Execution["⚡ Execution Layer"]
        direction TB
        ADAPTER["ExecutionAdapter"]

        subgraph ExecutionModes["Execution Modes"]
            LOCAL_PAPER["LocalPaperEngine<br/>(100% Free)"]
            DHAN_PAPER["Dhan Sandbox<br/>(Paper Trading)"]
            LIVE["Live Trading"]
        end

        JOURNAL["TradeJournal<br/>(History Logging)"]
    end

    subgraph Backtest["📈 Backtesting"]
        BT_ENGINE["BacktestEngine"]
        STRATEGIES["Strategy Library<br/>(SMA Cross, RSI, etc.)"]
    end

    %% Configuration connections
    ENV --> SETTINGS
    SETTINGS --> MANAGER
    SETTINGS --> ADAPTER
    SETTINGS --> MEMORY_DB

    %% Market data flow
    YFINANCE --> YF_FEED
    DHAN --> WS_FEED
    WS_FEED --> MANAGER
    YF_FEED --> MANAGER
    SIM_FEED --> MANAGER
    MANAGER --> INDICATORS
    INDICATORS --> SIGNALS
    DISCOVERY --> MANAGER

    %% Agent workflow
    SIGNALS --> STATE
    STATE --> REGIME
    REGIME -->|"regime + confidence"| STRATEGY
    STRATEGY -->|"active strategies"| VALIDATION
    VALIDATION -->|"validated signals"| RISK
    RISK -->|"approved trades"| STATE

    %% Support agents
    NEWS --> STATE
    SENTIMENT --> STATE
    PREDICTION --> STATE

    %% Memory feedback loop
    INJECTOR -->|"inject lessons"| STATE
    STATE -->|"trade outcomes"| ANALYZER
    ANALYZER --> CLASSIFIER
    CLASSIFIER --> MEMORY_DB
    MEMORY_DB --> INJECTOR

    %% Execution
    STATE -->|"trades_to_execute"| ADAPTER
    ADAPTER --> LOCAL_PAPER
    ADAPTER --> DHAN_PAPER
    ADAPTER --> LIVE
    ADAPTER --> JOURNAL
    JOURNAL --> ANALYZER

    %% Observability
    REGIME --> LANGSMITH
    STRATEGY --> LANGSMITH
    VALIDATION --> LANGSMITH
    RISK --> LANGSMITH

    %% LLM connections
    GROQ --> REGIME
    GROQ --> STRATEGY
    GROQ --> NEWS

    %% Notifications
    RISK -->|"trade alerts"| TELEGRAM

    %% Storage
    MEMORY_DB --> POSTGRES

    %% Backtesting
    YF_FEED --> BT_ENGINE
    STRATEGIES --> BT_ENGINE

Agent Workflow Detail

The 4-agent decision pipeline with conditional edges:

flowchart LR
    START((Start)) --> REGIME["🎯 Market Regime<br/>Agent"]

    REGIME -->|"confidence < 0.3"| END1((End))
    REGIME -->|"confidence ≥ 0.3"| STRATEGY["📊 Strategy Selection<br/>Agent"]

    STRATEGY --> VALIDATION["✓ Signal Validation<br/>Agent"]

    VALIDATION -->|"no validated<br/>signals"| END2((End))
    VALIDATION -->|"has signals"| RISK["🛡️ Risk & Compliance<br/>Agent"]

    RISK --> END3((End))

    subgraph Legend["State Fields Modified"]
        L1["regime, regime_confidence"]
        L2["active_strategies"]
        L3["validated_signals, rejected_signals"]
        L4["approved_trades, risk_warnings"]
    end

    REGIME -.-> L1
    STRATEGY -.-> L2
    VALIDATION -.-> L3
    RISK -.-> L4

Memory Feedback Loop

How the system learns from trade losses:

flowchart TB
    subgraph TradingCycle["Trading Cycle"]
        TRADE["Trade Executed"]
        OUTCOME["Trade Outcome<br/>(Win/Loss)"]
    end

    subgraph AnalysisPhase["Loss Analysis"]
        ANALYZER["TradeAnalyzer"]
        CLASSIFIER["MistakeClassifier"]
    end

    subgraph Storage["Persistent Memory"]
        DB[("PostgreSQL<br/>agent_memory table")]
        DECAY["Time Decay<br/>Scoring"]
    end

    subgraph Injection["Next Trading Cycle"]
        INJECTOR["MemoryInjector"]
        CONTEXT["Agent Context<br/>(Top 5 Lessons)"]
    end

    TRADE --> OUTCOME
    OUTCOME -->|"if loss"| ANALYZER
    ANALYZER --> CLASSIFIER
    CLASSIFIER -->|"lesson_id, category,<br/>severity, description"| DB
    DB --> DECAY
    DECAY --> DB
    DB --> INJECTOR
    INJECTOR --> CONTEXT
    CONTEXT -->|"memory_lessons"| TRADE

✨ Features

🤖 The Agent Team

| Agent | Responsibilities | Model (Groq) | | ----------------------- | -------------------------------------------------------------------------------------------------------- | --------------- | | Market Regime | Analyzes volatility and price acti

RakshaQuant

Install / Use

README