Nifty 100 Index Portfolio Allocator

A Python application that helps retail investors replicate the Nifty 100 index by calculating proportional buy orders based on investment amounts. The system fetches real-time stock prices from NSE and generates portfolio allocation reports with equal weight distribution (1% per security).

What This Skill Does

This skill enables you to work with a Python application that:

Instructions for AI Agent

Understanding the Project Structure

When working with this codebase, you should know:

1. **Entry Point**: `src/main.py` - CLI interface and orchestration

2. **Data Models** (`src/models/`):

- `security.py`: Security dataclass representing stocks

- `portfolio.py`: Portfolio, Allocation, and Summary dataclasses

3. **Services** (`src/services/`):

- `price_fetcher.py`: Fetches real-time prices from NSE via yfinance

- `allocator.py`: Implements equal-weight portfolio allocation logic

- `csv_handler.py`: Handles all CSV read/write operations

4. **Utilities** (`src/utils/`):

- `validators.py`: Input validation (amounts, file paths)

- `helpers.py`: Formatting and helper functions

5. **Configuration**: `config/settings.py` - Centralized settings

Key Implementation Details

Common Development Tasks

#### Setting Up the Environment

```bash

pip install -r requirements.txt

```

#### Downloading Latest Constituents

```bash

python src/main.py --download-constituents

```

#### Enhancing Securities Data with Prices

```bash

python src/main.py --hydratedata data/ind_nifty100list_*.csv --output data/nifty100_enhanced_securities.csv

```

#### Generating Portfolio Allocation

```bash

python src/main.py --amount 1100000 --securities data/nifty100_enhanced_securities.csv --exclusion data/nifty100_exclusions.csv

```

#### Creating Test Data

```bash

Create sample securities

python src/main.py --create-sample

Create sample exclusion list

python src/main.py --create-exclusion-sample

```

#### Debug Mode

```bash

python src/main.py --amount 100000 --log-level DEBUG

```

Data Flow

When processing portfolio allocations:

1. Load Nifty 100 constituents from CSV or download from NSE

2. Apply optional exclusion filters (matched by Symbol and ISIN)

3. Fetch real-time prices using yfinance (with retry logic)

4. Calculate equal-weight allocations (1% per security)

5. Generate buy orders (whole shares only)

6. Output results in CSV/JSON format with summary statistics

Making Code Changes

When modifying the codebase:

1. **Configuration Changes**: Update `config/settings.py` for constants and constraints

2. **Allocation Logic**: Modify `src/services/allocator.py` for algorithm changes

3. **Price Fetching**: Update `src/services/price_fetcher.py` for NSE integration changes

4. **CLI Arguments**: Modify `src/main.py` for new command-line options

5. **Data Models**: Update dataclasses in `src/models/` for schema changes

Testing

Currently no test framework is configured. For manual testing:

```bash

Run with sample data

python src/main.py --amount 10000 --securities data/sample_securities.csv

```

Error Handling

The application includes:

Output Formats

Constraints

Example Usage

Generate a ₹1.1 lakh portfolio allocation excluding specific securities:

```bash

python src/main.py \

--amount 110000 \

--securities data/nifty100_enhanced_securities.csv \

--exclusion data/nifty100_exclusions.csv

```