Edge-Explorer/QuantIQ: QuantIQ is a personal learning project I built to deeply understand how real-world full-stack systems come together — from live data pipelines and machine learning inference to generative AI agents, WebSocket streaming, and production observability. · GitHub

QuantIQ is an AI-powered decision intelligence platform for retail investors. Instead of forcing users to switch between charts, news sites, screeners, and general-purpose LLMs, QuantIQ brings live market data, historical trends, technical indicators, machine learning predictions, and AI-assisted reasoning into a single experience. The goal is not to predict the market with certainty, but to reduce research time and provide transparent, data-backed insights that help users make more informed trading and investment decisions.

The platform operates on two distinct but coordinated intelligence layers:

• The AI Analyst runs a locally-hosted ONNX model to compute a bullish probability score and then passes that score — along with live indicators and watchlist data — to a multi-step Gemini ReAct agent that produces a fully grounded, structured market report.
• The AI Advisor is an interactive chat interface anchored to the same ONNX model score. It allows users to ask follow-up questions, customize their entry and exit levels, and receive context-aware guidance without losing the thread of the conversation.

Both components share the same underlying machine learning pipeline. When a new model version is trained, both tools update together automatically.

Infrastructure note: The entire platform runs on free-tier services. The only variable cost is the Gemini API, which amounts to a few rupees per analysis call.

The public entry point features a sleek, dark-themed responsive landing page outlining the platform's capabilities.

Stateless session management via JWT tokens, supporting traditional email signups and Google OAuth credential linking.

  

A real-time trading board with fluid, GPU-accelerated TradingView candlestick charts, interactive indicators (SMA, EMA, RSI), and a sidebar tape for watchlists and alert status.

Generate detailed, tool-grounded financial analysis reports dynamically utilizing the ReAct agent architecture.

Interact with your quantitative strategy co-pilot. Customize entry/exit targets on the chart, ask technical questions, and get real-time memory-anchored answers.

Comprehensive system monitoring. Live Grafana dashboard scraping FastAPI, Celery latency, Redpanda delay, and memory footprint in real time.

Interactive entity mapping and tables tracking watchlist coordinates, strategy backtesting predictions, and user checkouts.

• Live Market Data Pipeline — Ingests real-time stock price ticks from Yahoo Finance every 5 seconds via a Kafka-compatible Redpanda message broker.
• On-Device ONNX ML Inference — A RandomForest model trained on two years of OHLCV data is exported to ONNX and runs locally inside the FastAPI process. Inference latency is under 5ms with zero cloud cost.
• ReAct AI Analyst Agent — A multi-step reasoning agent powered by Google Gemini 2.5 Flash that calls typed Python tool functions to fetch watchlist data, compute technical indicators, and run the ONNX model before synthesizing a structured analysis report.
• Context-Aware AI Advisor Chat — A conversational interface that loads live chart context, active indicators, and user-drawn price markers into its system prompt on each turn. It references prior conversation turns to avoid contradicting its own previous recommendations.
• MLOps Feedback Loop — Every prediction made by the Analyst is logged to PostgreSQL. A Celery background task runs every two minutes, fetches current prices via Yahoo Finance, and automatically labels each prediction as a success or failure with a calculated PnL percentage.
• User vs. AI Strategy Tracker — When a user locks in custom entry, target, and stop-loss levels via the Advisor, those levels are stored alongside the AI's recommended levels. The Celery worker evaluates both configurations independently, enabling a direct performance comparison over time.
• User Intent Analytics — Analysis queries are logged per user. Two GraphQL queries — recentlyAnalyzed and trendingTickers — surface a personalized recently viewed list and a platform-wide trending stocks widget derived entirely from real user behavior.
• Live Model Diagnostics — A REST endpoint at /api/v1/auth/model-metrics exposes real-time win rates, average PnL, per-model-version breakdowns, and User vs. AI strategy performance comparisons.
• Price Alerts and Watchlists — Users can set price alert thresholds evaluated on every incoming tick. Notifications are dispatched via Gmail SMTP when a threshold is crossed.
• Production Observability — Custom Prometheus collectors expose token usage, agent latency, WebSocket connection counts, pipeline delay, and payment events, scraped every minute by Grafana Cloud.
• Subscription and Payments — A tiered credit system enforced server-side and backed by Razorpay with HMAC webhook verification.

                         [ Hugging Face Spaces (Docker) ]
                         +----------------------------------+
                         |  worker/worker.py                |
                         |   - yfinance tick polling (5s)   |
                         |   - AIOKafkaProducer publish      |
                         |   - 1-min OHLCV aggregation       |
                         |   - NeonDB batch write            |
                         |   - Price alert evaluation        |
                         +----------------------------------+
                                       |
                          Redpanda Cloud (Kafka-compatible)
                          topic: stock-ticks
                                       |
                         +----------------------------------+
                         |  backend/app/main.py             |
                         |   - FastAPI + Uvicorn (ASGI)     |
                         |   - Strawberry GraphQL           |
                         |   - AIOKafkaConsumer subscriber  |
                         |   - ONNX model inference         |
                         |   - Gemini ReAct Agent           |
                         |   - Advisor Chat endpoint        |
                         |   - Razorpay webhook handler     |
                         |   - /metrics (Prometheus)        |
                         +----------------------------------+
                         |  Celery + Redis                  |
                         |   - Prediction outcome labeling  |
                         |   - Strategy outcome comparison  |
                         +----------------------------------+
                                       |
                  +--------------------+-------------------+
                  |                                        |
         NeonDB (PostgreSQL)                    Grafana Cloud
         - users, watchlists                   scrapes /metrics
         - stock_history, alerts               via Prometheus
         - prediction_logs
         - strategy_logs
                  |
         Vercel (Frontend)
         - React 19 + Vite + TypeScript
         - GraphQL WebSocket subscription
         - Lightweight Charts candlestick
         - Real-time ticker tape
         - AI Analyst + Advisor Chat

Data Flow:

1. worker.py polls Yahoo Finance every 5 seconds. The ticker list is fetched dynamically from NeonDB each cycle.
2. Each tick is published as a JSON message to Redpanda Cloud via AIOKafkaProducer.
3. The worker accumulates ticks in-memory and flushes 1-minute OHLCV candles to NeonDB.
4. The FastAPI backend subscribes to the topic via AIOKafkaConsumer. Each connected browser gets its own consumer group.
5. When the AI Analyst is triggered, the Gemini ReAct agent runs a multi-step tool loop, calls the ONNX inference helper, and logs the prediction to prediction_logs.
6. When the Advisor Chat is used, it calls the same ONNX helper and loads live chart context, user markers, and conversation history into the system prompt. Locked-in strategies are persisted to strategy_logs.
7. The Celery beat worker fires every 2 minutes, fetches current prices, and updates outcomes for both prediction_logs and strategy_logs.
8. All metrics are exposed at /metrics and scraped every minute by Grafana Cloud.

The initial implementation used asyncio.sleep loops and Redis Pub/Sub. The migration to Redpanda was driven by three specific requirements:

1. Message retention — Redis Pub/Sub is fire-and-forget. Redpanda retains messages on disk; consumers can replay from any offset after a restart.
2. Consumer isolation — Each browser client gets its own consumer group with an independent offset, so two users watching different tickers never interfere with each other's stream.
3. Real scalability path — Swapping Redpanda Cloud free tier for a paid Kafka cluster requires changing only the connection string.

Rather than calling a hosted inference API on every request, the model is trained once locally with train.py, exported to ONNX, and loaded into the FastAPI process on startup.

• Inference latency: under 5ms on CPU versus 200-800ms for a remote API call.
• Cost: zero per-request cost regardless of volume.
• Reliability: works even if external services are unavailable.

Model details:

• Algorithm: RandomForestClassifier (50 estimators, max depth 6)
• Features: RSI-14, MACD (12/26/9), MACD signal line, EMA-20 ratio
• Target: Binary — 1 if next-day close > current close, 0 otherwise
• Training data: 2 years of daily OHLCV for AAPL, TSLA, TCS.NS, RELIANCE.NS
• Export: ONNX opset 15, FloatTensorType, dynamic batch size

The agent runs a multi-step loop until it has sufficient context, then produces a structured JSON response: {"bullish_probability": int, "reason": "..."}.

Agent Tools:

On every message, the system prompt is dynamically constructed with the live ticker price, active indicators, user-drawn price markers, the real-time ONNX probability score, and the last 30 turns of conversation history. This allows the Advisor to cross-reference its own prior recommendations when evaluating the user's current chart markers, rather than treating each message as an independent request.

Every Analyst prediction is logged to prediction_logs. A Celery periodic task runs every two minutes, fetches the current price, calculates outcome and PnL, and marks the record as completed.

The strategy tracker extends this to user-defined levels. When a user locks in a strategy through the Advisor, both the AI recommended levels and the user's custom levels are stored in strategy_logs. The worker evaluates both configurations independently on each cycle, enabling a direct AI vs. user performance comparison over time.

All metrics are exposed at /metrics and scraped by Grafana Cloud every minute.

HTTP Layer (auto via prometheus-fastapi-instrumentator):

• Request rate by endpoint and status code
• p50 / p95 / p99 response latency histograms

AI Strategy Engine (custom collectors):

• quantiq_llm_tokens_total — input/output token counts by user tier
• quantiq_agent_steps_total — ReAct reasoning turns per session
• quantiq_agent_latency_seconds — end-to-end agent report generation time
• quantiq_agent_tool_calls_total — tool invocations by name and status

Market Data Pipeline (custom collectors):

• quantiq_websocket_connections_active — live GraphQL WebSocket session count
• quantiq_ingestion_delay_seconds — latency from tick generation to browser broadcast
• quantiq_external_api_calls_total — yfinance API call count by success/failure

Application Core (custom collectors):

• quantiq_payment_callbacks_total — Razorpay webhook events by package and status
• quantiq_db_pool_connections_active — SQLAlchemy connection pool utilisation

Payments go through Razorpay with HMAC webhook verification before any tier or credit update happens server-side. New users see a 3-day discount offer evaluated from the account creation timestamp.

QuantIQ/
|
|-- backend/                        # FastAPI backend service
|   +-- app/
|       |-- main.py                 # App entrypoint, ONNX loader, Prometheus init
|       |-- api/
|       |   +-- endpoints.py        # REST routes: auth, watchlist, alerts, payments, metrics
|       |-- config/
|       |   |-- settings.py         # Pydantic Settings: all env vars
|       |   +-- metrics.py          # Custom Prometheus collector definitions
|       |-- database/
|       |   |-- session.py          # SQLAlchemy async engine + session factory
|       |   |-- models.py           # ORM models: User, Watchlist, StockHistory,
|       |   |                       #   Alert, PredictionLog, StrategyLog
|       |   +-- crud.py             # Database query functions
|       |-- graphql/
|       |   +-- schema.py           # Strawberry GraphQL: queries, mutations, subscriptions
|       |-- schemas/
|       |   +-- schemas.py          # Pydantic request/response models
|       +-- services/
|           |-- gemini.py           # Gemini ReAct agent, ONNX inference helper
|           +-- celery_app.py       # Celery worker: prediction + strategy outcome labeling
|
|-- worker/
|   +-- worker.py                   # yfinance polling, AIOKafkaProducer, OHLCV aggregation
|
|-- frontend/                       # React 19 + Vite + TypeScript
|   +-- src/
|       |-- pages/                  # LandingPage, Dashboard, UpgradePage
|       |-- components/             # StockChart, AIAnalyst, AdvisorChat,
|       |                           #   WatchlistSidebar, PriceAlerts
|       +-- App.tsx                 # Router, auth state, Google OAuth
|
|-- alembic/                        # Alembic migration scripts
|-- train.py                        # Offline ML training + ONNX export
|-- model.onnx                      # Trained ONNX model
|-- pyproject.toml                  # uv project config + Python dependencies
|-- supervisord.conf                # Process supervisor for HF Spaces Docker container
+-- README.md

# Google Gemini API Key — aistudio.google.com (free quota available)
GEMINI_API_KEY=your_gemini_api_key_here

# Database — NeonDB free tier PostgreSQL connection string
DATABASE_URL=postgresql://user:password@host/dbname

# Redpanda Cloud bootstrap server (free tier)
KAFKA_BOOTSTRAP_SERVERS=your_redpanda_bootstrap_server:9092

# JWT secret key for token signing
SECRET_KEY=your_secret_key_here

# Razorpay credentials — dashboard.razorpay.com
RAZORPAY_KEY_ID=your_razorpay_key_id
RAZORPAY_KEY_SECRET=your_razorpay_key_secret

# Cloudinary — free tier for profile image uploads
CLOUDINARY_CLOUD_NAME=your_cloud_name
CLOUDINARY_API_KEY=your_api_key
CLOUDINARY_API_SECRET=your_api_secret

# Gmail SMTP for transactional email
SMTP_HOST=smtp.gmail.com
SMTP_PORT=587
SMTP_USER=your_email@gmail.com
SMTP_PASS=your_app_password

# Hugging Face model repository
HF_MODEL_REPO=Karan6124/quantiq-model

Prerequisites: Python 3.12+, Node.js 18+, uv (pip install uv), Docker Desktop

# 1. Clone the repo
git clone https://github.com/Edge-Explorer/QuantIQ.git
cd QuantIQ

# 2. Install Python dependencies
uv sync

# 3. Start local PostgreSQL
docker-compose up -d

# 4. Add your .env file (copy the template above)

# 5. Run database migrations
uv run alembic upgrade head

# 6. Start the backend
uv run uvicorn backend.app.main:app --reload

# 7. Start the ingestion worker
uv run python worker/worker.py

# 8. Start the Celery worker (for MLOps background tasks)
uv run celery -A backend.app.services.celery_app worker --beat --loglevel=info

# 9. Start the frontend
cd frontend && npm install && npm run dev

uv run python train.py

This fetches 2 years of daily OHLCV data, computes RSI/MACD/EMA features, trains a RandomForestClassifier, exports to model.onnx via skl2onnx, and verifies the output with a test inference call. Upload the resulting model.onnx to your Hugging Face Hub repo so the backend can download it on cold starts.

To deploy backend updates to Hugging Face Spaces, do not push manually. Run the automated deployment script from the project root:

.\deploy_hf.ps1

This script prepends required YAML frontmatter config, commits and pushes to the HF remote space, and automatically restores the clean README.md file for GitHub. After running the script, push your clean branch updates to GitHub: git push origin main.

The project uses GitHub Actions for automated code quality and build verification on every push and pull request to the main branch:

• Frontend CI: Automatically installs dependencies, checks TypeScript compiler types, and verifies production bundles run correctly (npm run build).
• Backend CI: Dynamically configures a Python environment using the fast uv package manager, validates code quality/formatting using the ruff linter, and checks that entry points compile cleanly.

Interested in adding features or helping us scale? Check out our Contribution Guidelines for local setup instructions and a list of active Open Issues (like Discord webhooks and ONNX model metadata APIs).

MIT — do whatever you want with it. See LICENSE.