KMI30 Tracker - Setup Instructions for macOS

Overview

KMI30 Tracker is a Python-based tool that scrapes KMI30 index data from PSX website, calculates portfolio allocations with a custom multiplier, and tracks your investments over time.

Features

• Web scraping of live KMI30 data from PSX
• Portfolio calculation with customizable investment amount and multiplier (default 1.22)
• SQLite database for historical tracking
• Automated daily data collection
• Portfolio rebalancing calculations
• Detailed reporting and analysis

Prerequisites

• macOS (tested on macOS 10.15+)
• Python 3.8 or higher
• Internet connection for data scraping

Installation

1. Check Python Version

python3 --version

If Python 3.8+ is not installed, install it via Homebrew:

/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
brew install python3

2. Navigate to Project Directory

cd /Users/mbp/Desktop/kmi30tracker

3. Create Virtual Environment (Recommended)

python3 -m venv venv
source venv/bin/activate

4. Install Dependencies

pip install -r requirements.txt

Quick Start

1. Basic Usage - Scrape and Calculate

python3 kmi30_tracker.py --investment 100000 --multiplier 1.22

2. Check Status

python3 kmi30_tracker.py status

3. Scrape Only (no calculations)

python3 kmi30_tracker.py --scrape-only

4. Calculate from Existing Data

python3 kmi30_tracker.py --calculate-only --investment 200000

Command Line Options

Option	Description	Default
--investment, -i	Total investment amount in PKR	100,000
--multiplier, -m	Index weight multiplier	1.22
--scrape-only	Only scrape data, don't calculate	False
--calculate-only	Only calculate from existing data	False
--date	Specific date (YYYY-MM-DD)	Today
--top-n	Show top N allocations	15
--log-level	Logging level (DEBUG/INFO/WARNING/ERROR)	INFO

Examples

Example 1: Basic Portfolio Calculation

python3 kmi30_tracker.py --investment 500000 --multiplier 1.22 --top-n 20

Example 2: Historical Analysis

python3 kmi30_tracker.py --calculate-only --date 2025-08-30 --investment 300000

Example 3: Debug Mode

python3 kmi30_tracker.py --log-level DEBUG --scrape-only

File Structure

kmi30tracker/
├── kmi30_tracker.py     # Main script
├── scraper.py           # Web scraper module
├── database.py          # Database operations
├── calculator.py        # Portfolio calculations
├── requirements.txt     # Python dependencies
├── setup_automation.sh  # Automation script
├── README.md           # This file
├── kmi30_tracker.db    # SQLite database (created automatically)
├── kmi30_tracker.log   # Log file (created automatically)
└── portfolio_summary_*.txt # Daily summary files

Database Schema

Tables Created:

1. daily_snapshots - Raw KMI30 data for each day
2. portfolio_allocations - Calculated allocations per day
3. portfolio_settings - Investment settings history
4. portfolio_performance - Performance tracking (future)

Automation Setup

1. Make Automation Script Executable

chmod +x setup_automation.sh

2. Run Automation Setup

./setup_automation.sh

This will:

• Set up daily cron job to run at 6 PM (after market close)
• Configure proper paths and environment
• Set up log rotation

3. Manual Cron Setup (Alternative)

crontab -e

Add this line for daily execution at 6 PM:

0 18 * * 1-5 cd /Users/mbp/Desktop/kmi30tracker && /usr/bin/python3 kmi30_tracker.py --investment 100000 >> cron.log 2>&1

Portfolio Calculation Logic

1. Fetch KMI30 Data: Current prices and index weightings
2. Apply Multiplier: Multiply each IDX WTG by 1.22 (configurable)
3. Calculate Percentages: Normalize to get portfolio percentages
4. Determine Shares: Calculate whole shares based on current prices
5. Track Cash: Monitor uninvested cash due to fractional shares

Troubleshooting

Common Issues:

1. Permission Denied

chmod +x kmi30_tracker.py
chmod +x setup_automation.sh

2. Import Errors

source venv/bin/activate  # Activate virtual environment
pip install -r requirements.txt  # Reinstall dependencies

3. Web Scraping Fails

• Check internet connection
• PSX website might be down
• Website structure may have changed
• Check firewall/proxy settings

4. Database Errors

rm kmi30_tracker.db  # Delete and recreate database
python3 database.py  # Test database creation

Log Files:

• Check kmi30_tracker.log for detailed error messages
• Use --log-level DEBUG for verbose output

Data Validation

Check Data Quality:

python3 -c "
from database import KMI30Database
db = KMI30Database()
data = db.get_latest_data()
print(f'Latest data: {len(data)} stocks')
for stock in data[:5]:
    print(f'{stock[\"symbol\"]}: {stock[\"current\"]} PKR')
"

Performance Monitoring

View Database Size:

ls -lh kmi30_tracker.db

Check Log Size:

ls -lh kmi30_tracker.log

Security Considerations

1. Respectful Scraping: Built-in delays and proper headers
2. Local Storage: All data stored locally in SQLite
3. No Credentials: No API keys or passwords required
4. Rate Limiting: Automatic throttling to avoid being blocked

Support

For issues or questions:

1. Check the log files first
2. Review this README
3. Test individual modules:

   python3 scraper.py      # Test scraping
   python3 database.py     # Test database
   python3 calculator.py   # Test calculations

Legal Notice

This tool is for educational and personal use only. Please ensure compliance with:

• PSX website terms of service
• Pakistani securities regulations
• Your broker's trading policies

The authors are not responsible for any financial decisions made using this tool.