System Requirements Document for kishan-ai

1. Introduction

The kishan-ai project is an autonomous Indian intraday AI paper-trading system designed to simulate trading activities on the National Stock Exchange (NSE) without placing real orders or handling real funds. The system is intended for traders and analysts who wish to explore trading strategies in a risk-free environment. It leverages a multi-agent architecture to analyze market data, rank trading candidates, and simulate trade execution while ensuring compliance with strict safety boundaries.

2. System Overview

The kishan-ai system operates as a fully autonomous trading pipeline that runs during NSE market hours. It is designed to scan, rank, analyze, and simulate trades without manual intervention, except for a manual STOP/HALT control. The system integrates with Upstox for market data access using a read-only scope and ensures that no real orders are placed. The system's architecture includes various agents responsible for different aspects of the trading process, such as market data acquisition, opportunity scouting, technical analysis, and risk management.

2a. Product Interpretation and Delivery Boundary

The system is strictly a paper-trading platform with no capability to place real orders. It uses Upstox's read-only market data API and requires manual daily login for authentication. The system's behavior is governed by a set of configurable parameters, and it operates autonomously once started. The system's UI is minimalistic, focusing on essential information and controls.

2b. Source Content Inventory

Not applicable as no explicit content source directive was provided.

2c. Page Content and Component Coverage

Landing

• Purpose: Introduces the paper-trading system, its purpose, and its audience.
• Components:
  • Overview of the system's capabilities and safety boundaries.
  • Explanation of the paper-trading concept and its benefits.

Login

• Purpose: Facilitates user authentication for accessing protected features.
• Components:
  • User login form.
  • Authentication via Upstox OAuth2-style login.
  • Access to Dashboard, Configuration, Trade Journal, and Analytics upon successful login.

Dashboard

• Purpose: Provides real-time trading information and controls.
• Components:
  • Live price chart from Market Data Agent.
  • Upstox connection status.
  • Current trading position details (entry, target, stop-loss).
  • Equity curve and distance to kill switch.
  • Manual STOP/HALT control.

Configuration

• Purpose: Allows users to configure trading parameters.
• Components:
  • Editable fields for starting capital, kill switch, position limits, risk percentage, net R:R minimum, candidate count, re-scan interval, price cap, cost model, and session windows.

Trade Journal

• Purpose: Displays a log of closed trades with detailed context.
• Components:
  • Structured trade journal from the Learning Engine.
  • Contextual information on each trade, including agent reasoning and outcomes.

Analytics

• Purpose: Provides analytical insights into trading performance.
• Components:
  • Dashboards and analytics from the Learning Engine.
  • Tools for reviewing and approving parameter changes.

3. Functional Requirements

1. As a Trader/Operator, I should be able to configure trading parameters such as starting capital, kill switch, and risk limits through a single config layer, ensuring flexibility without code changes. (explicit)
2. As a Trader/Operator, I should be able to manually log into Upstox daily to authenticate and activate the trading pipeline, ensuring secure and controlled access. (explicit)
3. As a Trader/Operator, I should be able to monitor live trading data on the Dashboard, including price charts and current positions, to make informed decisions. (explicit)
4. As a Trader/Operator, I should be able to manually stop or halt the trading pipeline during market hours, providing control over the trading process. (explicit)
5. As a Trade Reviewer/Analyst, I should be able to review the trade journal to understand the context and reasoning behind each trade, facilitating post-trade analysis. (explicit)
6. As a Trade Reviewer/Analyst, I should be able to access analytics dashboards to evaluate trading performance and approve any parameter changes. (explicit)

4. User Personas

Trader / Operator

• Context: Manages the configuration and operation of the paper-trading system.
• Primary Goal: Ensure the system runs autonomously with accurate simulation of trades.
• Responsibilities: Configure parameters, perform daily Upstox login, monitor the Dashboard, and use STOP/HALT control.
• Success: The system operates smoothly, simulating trades without real orders.

Trade Reviewer / Analyst

• Context: Analyzes trade outcomes and system performance.
• Primary Goal: Understand trade decisions and improve future strategies.
• Responsibilities: Review trade journals, analyze performance, and approve parameter changes.
• Success: Gains insights into trading strategies and system effectiveness.

5. Core User Flows

1. Trader/Operator Login and Setup

   • Start: User accesses the Login page.
   • Action: Logs into Upstox via OAuth2.
   • Result: Gains access to the Dashboard and Configuration pages.
   • Next Step: Configures trading parameters.

2. Starting the Trading Pipeline

   • Start: User accesses the Dashboard.
   • Action: Initiates the trading pipeline.
   • Result: System runs autonomously, simulating trades.
   • Next Step: Monitors live data and uses STOP/HALT if needed.

3. Trade Review and Analysis

   • Start: User accesses the Trade Journal.
   • Action: Reviews closed trades and agent reasoning.
   • Result: Gains insights into trade decisions.
   • Next Step: Accesses Analytics for further analysis.

6. Visuals Colors and Theme

• Muse: Minimalistic and functional design.
• Headline: "Efficiency in Simplicity"
• Colors:
  • Primary: #1A73E8 (Blue)
  • Secondary: #FFFFFF (White)
  • Accent: #F1F3F4 (Light Gray)
• Fonts:
  • Headings: Roboto Bold
  • Body: Roboto Regular
• Type Scale: 1.2em for headings, 1em for body text.
• Radius/Shape: Rounded corners with a 4px radius.
• Spacing Rhythm: 8px grid system.
• Imagery Style: Clean and data-focused visuals.

7. Signature Design Concept

The Landing page will feature a clean and minimalistic design, highlighting the system's paper-trading capabilities. The hero section will include a concise introduction to the system, using the primary blue color for emphasis. The layout will be simple, with clear call-to-action buttons guiding users to learn more or log in.

8. Interaction Model & Motion Direction

• Interaction Model: Static
• Motion Tempo: Restrained
• Hero Dimensionality: Flat
• Landing Hero Motion Brief: The hero section will feature a static image of a trading dashboard, with key features highlighted through subtle animations on hover. The transformation will focus on providing clear information without overwhelming the user. In reduced-motion mode, animations will be disabled for accessibility.

9. Non-Functional Requirements

1. Performance: The system must handle real-time data updates without lag.
2. Security: Ensure secure handling of user credentials and data.
3. Reliability: The system should operate continuously during market hours without failure.
4. Usability: The interface should be intuitive and easy to navigate.

10. Tech Stack

• Frontend: React
• Backend: Python/FastAPI
• Database: PostgreSQL
• Integration: Upstox API (read-only)
• Deployment: Docker, Kubernetes (if necessary)

11. Assumptions and Constraints

• The system will never place real orders or handle real funds.
• Upstox integration will remain read-only.
• Manual daily login is required for Upstox authentication.
• The system's UI will remain minimalistic and functional.

12. Glossary

• NSE: National Stock Exchange of India.
• Upstox: A brokerage platform providing market data.
• OAuth2: An authorization framework for secure login.
• R:R: Reward to Risk ratio, a measure of trade profitability.
• LLM: Large Language Model, used for natural language processing.