Metadata-Version: 2.4
Name: kotak-dashboard
Version: 1.0.0
Summary: A Production-Ready Portfolio Dashboard for Kotak Neo API
Project-URL: Homepage, https://github.com/yourusername/kotak-dashboard
Project-URL: Bug Tracker, https://github.com/yourusername/kotak-dashboard/issues
Author-email: Your Name <your.email@example.com>
License: MIT License
        
        Copyright (c) 2026 Jayesh Arun Bafna
        
        Permission is hereby granted, free of charge, to any person obtaining a copy
        of this software and associated documentation files (the "Software"), to deal
        in the Software without restriction, including without limitation the rights
        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
        copies of the Software, and to permit persons to whom the Software is
        furnished to do so, subject to the following conditions:
        
        The above copyright notice and this permission notice shall be included in all
        copies or substantial portions of the Software.
        
        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
        SOFTWARE.
License-File: LICENSE
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Requires-Python: >=3.11
Requires-Dist: altair>=5.0.0
Requires-Dist: neo-api-client
Requires-Dist: pandas>=2.0.0
Requires-Dist: pyotp>=2.9.0
Requires-Dist: python-dotenv>=1.0.0
Requires-Dist: streamlit>=1.30.0
Provides-Extra: test
Requires-Dist: build>=1.0.0; extra == 'test'
Requires-Dist: pre-commit>=3.6.0; extra == 'test'
Requires-Dist: pytest-mock>=3.10.0; extra == 'test'
Requires-Dist: pytest>=7.0.0; extra == 'test'
Requires-Dist: ruff>=0.3.0; extra == 'test'
Requires-Dist: twine>=4.0.0; extra == 'test'
Description-Content-Type: text/markdown

# Kotak Neo Portfolio Dashboard 📈

A professional, production-ready Python dashboard for tracking your Kotak Securities portfolio in real-time. Built with Streamlit, this application connects to the Kotak Neo API to provide live P&L tracking, sector analytics, and visual portfolio insights.

## 🚀 Features

### 📊 Live Portfolio Hydration

- Automatically fetches live market quotes (LTP)
- Updates your portfolio value in real-time

### 🧠 Intelligent Caching

- Smart fallback logic
- Calculates Day's Change using OHLC data if the live feed is incomplete

### 📈 Visual Analytics

- **Day's P&L Tracking**: See exactly how much your portfolio moved today
- **Sector Allocation**: Interactive Donut charts showing exposure by sector
- **Allocation Bar Chart**: Visual breakdown of investment distribution

### 🔐 Secure Authentication

- Uses TOTP (Time-based OTP) for seamless 2FA login
- Credentials stored securely in a local `.env` file (never hardcoded)

### 🧱 Robust Architecture

- Modular backend design
- Separation of:
  - Authentication
  - Data Fetching
  - Analytics

## 📂 Project Structure

```
kotak-dashboard/
├── .devcontainer/       # VS Code Dev Container configuration
├── .github/workflows/   # CI/CD Pipelines
├── kotak_dashboard/     # Main Application Package
│   ├── __init__.py
│   ├── app.py           # Streamlit UI Layer
│   ├── backend.py       # Core Logic (Auth, API, Math)
│   └── cli.py           # Command-line entry point
├── tests/               # Test Suite
│   ├── conftest.py
│   ├── test_backend_analytics.py
│   └── test_backend_data.py
├── .env.example         # Template for API credentials
├── Dockerfile           # Production-ready Docker image
├── pyproject.toml       # Modern Python dependency management
└── README.md            # Documentation

```

## 🛠️ Prerequisites

### Python Environment

- **Python 3.11+** (Strict requirement for neo_api_client compatibility)

### Kotak Neo API Credentials

You will need the following from the Kotak Neo API Portal:

- **Consumer Key**
- **Mobile Number**
- **UCC** (User Client Code)
- **TOTP Secret Key** (The alphanumeric key used to generate 2FA codes)
- **MPIN**

## ⚙️ Installation & Setup

### Option 1: Standard Local Install (Recommended)

1. **Clone the repository**

   ```bash
   git clone https://github.com/yourusername/kotak-dashboard.git
   cd kotak-dashboard
   ```

2. **Create a Virtual Environment (Python 3.11)**

   ```bash
   # macOS/Linux
   python3.11 -m venv .venv
   source .venv/bin/activate

   # Windows
   py -3.11 -m venv .venv
   .venv\Scripts\activate
   ```

3. **Install Dependencies**
   We use pip to install the package in editable mode.

   ```bash
   pip install --upgrade pip
   pip install -e .
   ```

### Option 2: Using Docker 🐳

Run the dashboard in an isolated container without installing Python locally.

1. **Build the image**

   ```bash
   docker build -t kotak-dashboard .
   ```

2. **Run the container**

   ```bash
   docker run -p 8501:8501 -v $(pwd)/.env:/app/.env kotak-dashboard
   ```

### Option 3: VS Code Dev Container

1. Open the project folder in VS Code.
2. Install the **Dev Containers** extension.
3. Press **F1** and select **"Dev Containers: Reopen in Container"**.
4. VS Code will build a fully configured environment for you.

## 🧪 Running Tests

This project uses **pytest** for unit testing. The test suite covers:

- Authentication flows  
- Data hydration logic  
- Analytics calculations  

### Install Test Dependencies
```bash
pip install -e .[test]
```

## 🚀 CI/CD Pipeline

The project includes a **GitHub Actions workflow** (`.github/workflows/ci_cd.yml`) that automatically:

- Sets up Python 3.11  
- Runs the full test suite with `pytest`  
- Builds the Python package (Source Distribution & Wheel)  
- Uploads the build artifacts to GitHub  


## 🔑 Configuration

### First Run Setup

When you run the app for the first time, a sidebar will appear asking for your credentials.

1. Enter your **Consumer Key**, **Mobile**, **UCC**, **TOTP Secret**, and **MPIN**.
2. Click **"Save & Login"**.
3. This will automatically create a `.env` file in your project root.

### Manual Setup (Optional)

Copy the example file and fill it in manually:

```bash
cp .env.example .env
```

Edit `.env`:

```
KOTAK_CONSUMER_KEY=your_key_here
KOTAK_MOBILE=9876543210
KOTAK_UCC=YA004
KOTAK_TOTP_SECRET=YOURSECRETKEY123
KOTAK_MPIN=123456
```

## 🏃‍♂️ Usage

Once installed, you can start the dashboard using the command line:

```bash
kotak-dashboard
```

Or directly via Streamlit:

```bash
streamlit run kotak_dashboard/app.py
```

Open your browser to **http://localhost:8501** to view your portfolio.

## ⚠️ Disclaimer

This application is an **unofficial** tool built for educational and personal tracking purposes. It interacts with the Kotak Neo API but is **not affiliated** with Kotak Securities.

- **Trading Risk**: Stock market investments are subject to market risks. This tool does not provide financial advice.
- **Security**: Your credentials are stored locally on your machine in the `.env` file. Do not share this file or commit it to public repositories.

Built with ❤️ using Python & Streamlit.
