cagrx 0.1.0__tar.gz

cagrx-0.1.0/.agent/workflows/publish_to_pypi.md

@@ -0,0 +1,27 @@
+---
+description: how to publish the package to PyPI using uv
+---
+1.  **Build the Package**: Generate the distribution files (sdist and wheel) using `uv`.
+    ```bash
+    uv build
+    ```
+    This will create a `dist/` directory containing the build artifacts.
+
+2.  **Upload to PyPI**: Upload the package using `uv`.
+    ```bash
+    # For TestPyPI (Recommended for first time)
+    # You need to set the token variable first or pass it directly
+    # $Env:UV_PUBLISH_TOKEN = "pypi-..." 
+    uv publish --publish-url https://test.pypi.org/legacy/
+    
+    # For Real PyPI
+    # $Env:UV_PUBLISH_TOKEN = "pypi-..."
+    uv publish
+    ```
+    `uv` will look for the `UV_PUBLISH_TOKEN` environment variable or can be configured via `uv.toml` or global configuration.
+
+3.  **Clean Up**: Remove the build artifacts if needed (optional, `uv` handles rebuilds well).
+    ```bash
+    # Windows (PowerShell)
+    Remove-Item -Recurse -Force dist
+    ```

cagrx-0.1.0/.gitignore

@@ -0,0 +1,36 @@
+# Python-generated files
+__pycache__/
+*.py[oc]
+build/
+dist/
+wheels/
+*.egg-info
+
+# Virtual environments
+.venv
+venv/
+env/
+
+# IDE settings
+.vscode/
+.idea/
+
+# Testing and Type Checking
+.coverage
+htmlcov/
+.mypy_cache/
+.pytest_cache/
+
+# Environment variables
+.env
+
+# System files
+.DS_Store
+Thumbs.db
+
+# Project specific
+*.csv
+!122639.csv
+.!amfi_navall.csv
+
+

cagrx-0.1.0/.python-version

@@ -0,0 +1 @@
+3.9

cagrx-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 rakesh
+
+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.

cagrx-0.1.0/PKG-INFO

@@ -0,0 +1,300 @@
+Metadata-Version: 2.4
+Name: cagrx
+Version: 0.1.0
+Summary: A Python library to calculate return metrics like CAGR, XIRR, and SIP returns using AMFI data
+Project-URL: Homepage, https://github.com/yourusername/cagrx
+Project-URL: Repository, https://github.com/yourusername/cagrx
+Project-URL: Issues, https://github.com/yourusername/cagrx/issues
+Author-email: Your Name <your.email@example.com>
+License: MIT
+License-File: LICENSE
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Requires-Python: >=3.9
+Requires-Dist: pandas
+Requires-Dist: requests
+Description-Content-Type: text/markdown
+
+# 📈 cagrx
+
+![Status](https://img.shields.io/badge/status-work--in--progress-orange) ![Python](https://img.shields.io/badge/python-3.9%2B-blue)
+
+> **No Cap, only CAGR – Calculate Mutual fund Returns Like a Pro**
+
+*Download, analyze, and unlock insights from Indian mutual funds with ease.*
+
+---
+ 
+> [!WARNING]
+> **Work in Progress**: This library is under active development. APIs may change, and some features are still being refined. Contributions and feedback are welcome!
+
+**CagrX** is a powerful Python library to analyze mutual funds using AMFI (Association of Mutual Funds in India) data. Whether you're building a fintech app, conducting investment research, or analyzing portfolio performance, cagrx provides the tools you need to work with mutual fund data effortlessly.
+
+## ✨ Features
+
+- **Download Mutual Fund Data**: Fetch NAV (Net Asset Value) data for any Indian mutual fund scheme
+- **Historical Data**: Access historical NAV data with automatic chunking for large date ranges
+- **Fund Discovery**: Browse and search through all available mutual fund schemes
+- **Performance Analysis**: Built-in metrics for calculating returns:
+  - CAGR (Compound Annual Growth Rate)
+  - Trailing returns (1Y, 3Y, 5Y, etc.)
+  - Rolling returns with max/min/average statistics
+  - SIP (Systematic Investment Plan) return calculations
+- **Data Persistence**: Automatic caching of schemes list for faster subsequent access
+
+## 🚀 Installation
+
+> [!NOTE]
+> This library is not yet published to PyPI. Install from source for now.
+
+**Install from source:**
+
+```bash
+git clone https://github.com/yourusername/cagrx.git
+cd cagrx
+pip install -e .
+```
+
+**Or install dependencies manually:**
+
+```bash
+pip install pandas requests
+```
+
+## 📦 Requirements
+
+- Python >= 3.9
+- pandas
+- requests
+
+## 🔧 Usage
+
+### Getting Started with AMFI Data
+
+```python
+from cagrx.amfi import Amfi
+
+# Initialize AMFI client
+amfi = Amfi()
+```
+
+### Browse Available Mutual Funds
+
+```python
+# Get all fund houses
+fund_houses = amfi.get_fund_houses()
+print(fund_houses)
+
+# Get all schemes from a specific fund house
+schemes = amfi.get_schemes_by_fund_house("HDFC Mutual Fund")
+print(schemes)
+
+# Get complete schemes list (cached locally as amfi_navall.csv)
+all_schemes = amfi.list_all_schemes()
+
+# Force refresh the schemes list from AMFI and update cache
+# Useful when you want to ensure you have the new funds included
+refreshed_schemes = amfi.refresh_schemes()
+```
+
+### Download Historical NAV Data
+
+```python
+# Download NAV data for a specific scheme
+# Scheme code can be found from list_all_schemes()
+nav_data = amfi.get_nav_history(
+    scheme_id="122639",  # Example: HDFC Flexi Cap Fund
+    start_date="2020-01-01",
+    end_date="2023-12-31"
+)
+
+# Returns a pandas DataFrame with date as index and NAV values
+print(nav_data.head())
+```
+
+### Calculate Performance Metrics
+
+#### CAGR (Compound Annual Growth Rate)
+
+> [!NOTE]
+> You can use `-1` as a period to calculate the CAGR for the entire available historical data (Max CAGR).
+
+```python
+from cagrx.return_metrics import cagr, calculate_trailing_cagr
+
+# Calculate overall CAGR
+overall_cagr = cagr(nav_data)
+print(f"Overall CAGR: {overall_cagr * 100:.2f}%")
+
+# Calculate trailing CAGR for multiple periods
+trailing_returns = calculate_trailing_cagr(
+    nav_data,
+    periods=[-1, 1, 3, 5]  # -1 for Max CAGR, 1Y, 3Y, 5Y
+)
+print(trailing_returns)
+# Output: {'Max_CAGR': 0.165, '1Y_CAGR': 0.123, '3Y_CAGR': 0.156, '5Y_CAGR': 0.142}
+```
+
+#### Rolling Returns
+
+```python
+from cagrx.return_metrics import calculate_rolling_returns
+import pandas as pd
+
+# Calculate 1-year rolling returns
+rolling_metrics = calculate_rolling_returns(
+    nav_data,
+    period=pd.DateOffset(years=1)
+)
+
+print(f"Max rolling return: {rolling_metrics['max_returns'] * 100:.2f}%")
+print(f"Period: {rolling_metrics['max_return_period']}")
+print(f"Min rolling return: {rolling_metrics['min_returns'] * 100:.2f}%")
+print(f"Average rolling return: {rolling_metrics['avg_return'] * 100:.2f}%")
+```
+
+#### SIP Returns (What-If Analysis)
+
+Analyze how your periodic investments would have performed:
+
+```python
+from cagrx.amfi import Amfi
+from cagrx.return_metrics import calculate_sip_returns
+import pandas as pd
+
+# First, get the NAV data for the fund
+amfi = Amfi()
+nav_data = amfi.get_nav_history(
+    scheme_id="122639",
+    start_date="2020-01-01",
+    end_date="2023-12-31"
+)
+
+# Example 1: Regular monthly SIP of ₹5,000 for 3 years
+sip_dates = pd.date_range(start='2020-01-01', periods=36, freq='MS')
+sip_cashflows = pd.DataFrame({'amount': 5000}, index=sip_dates)
+
+returns = calculate_sip_returns(sip_cashflows, nav_data)
+print(f"Invested: ₹{returns['total_invested']:,.0f} → Current: ₹{returns['current_value']:,.0f}")
+print(f"Returns: {returns['return_percentage']:.2f}% (Annualized: {returns['annualized_return']:.2f}%)")
+
+# Example 2: Irregular investments (lump sum + step-up SIP)
+irregular_investments = pd.DataFrame({
+    'amount': [50000, 5000, 7500, 10000, 15000]
+}, index=pd.to_datetime([
+    '2020-01-15',   # Initial lump sum
+    '2020-06-01',   # ₹5k after 6 months
+    '2021-01-01',   # Stepped up to ₹7.5k
+    '2021-06-01',   # Stepped up to ₹10k
+    '2022-01-01'    # Stepped up to ₹15k
+]))
+
+irregular_returns = calculate_sip_returns(irregular_investments, nav_data)
+print(f"Irregular Returns: {irregular_returns['return_percentage']:.2f}%")
+```
+
+### Complete Example
+
+```python
+from cagrx.amfi import Amfi
+from cagrx.return_metrics import cagr, calculate_trailing_cagr, calculate_rolling_returns
+import pandas as pd
+
+# Initialize
+amfi = Amfi()
+
+# Browse HDFC schemes
+hdfc_schemes = amfi.get_schemes_by_fund_house("HDFC Mutual Fund")
+print("Available HDFC Schemes:")
+print(hdfc_schemes.head())
+
+# Download NAV data for HDFC Flexi Cap Fund
+nav_data = amfi.get_nav_history(
+    scheme_id="122639",
+    start_date="2018-01-01",
+    end_date="2024-12-31"
+)
+
+# Save to CSV for future use
+nav_data.to_csv("hdfc_flexi_cap_nav.csv")
+
+# Calculate performance metrics
+print("\n=== Performance Metrics ===")
+
+# Overall CAGR
+overall_return = cagr(nav_data)
+print(f"\nOverall CAGR: {overall_return * 100:.2f}%")
+
+# Trailing returns
+trailing = calculate_trailing_cagr(nav_data, periods=[1, 3, 5])
+print("\nTrailing Returns:")
+for period, value in trailing.items():
+    if value:
+        print(f"  {period}: {value * 100:.2f}%")
+    else:
+        print(f"  {period}: Insufficient data")
+
+# Rolling returns
+rolling = calculate_rolling_returns(nav_data, period=pd.DateOffset(years=1))
+print(f"\n1-Year Rolling Returns:")
+print(f"  Max: {rolling['max_returns'] * 100:.2f}%")
+print(f"  Min: {rolling['min_returns'] * 100:.2f}%")
+print(f"  Avg: {rolling['avg_return'] * 100:.2f}%")
+```
+
+## 📊 Data Sources
+
+All data is sourced from official AMFI (Association of Mutual Funds in India) APIs:
+- **Schemes List**: https://www.amfiindia.com/spages/NAVAll.txt
+- **Historical NAV**: https://www.amfiindia.com/api/nav-history
+
+## 🏗️ Project Structure
+
+```
+cagrx/
+├── src/
+│   └── cagrx/
+│       ├── __init__.py          # Main package entry point
+│       ├── amfi.py              # AMFI data fetching and management
+│       ├── return_metrics.py    # Performance calculation utilities
+│       └── utils.py             # Helper functions
+├── pyproject.toml               # Project configuration
+└── README.md                    # This file
+```
+
+## 🧪 Development
+
+### Running Tests
+
+```bash
+# Run the test file
+python src/cagrx/amfi_tests.py
+```
+
+## 🤝 Contributing
+
+Contributions are welcome! Please feel free to submit a Pull Request.
+
+1. Fork the project
+2. Create your feature branch (`git checkout -b feature/AmazingFeature`)
+3. Commit your changes (`git commit -m 'Add some AmazingFeature'`)
+4. Push to the branch (`git push origin feature/AmazingFeature`)
+5. Open a Pull Request
+
+## 📝 License
+
+This project is licensed under the MIT License - see the LICENSE file for details.
+
+## 🙏 Acknowledgments
+
+- Data provided by AMFI (Association of Mutual Funds in India)
+- Built with Python, pandas, and requests
+
+## 📮 Contact
+
+For questions or feedback, please open an issue on GitHub.
+
+---
+
+**Note**: This library is for educational and research purposes. Please verify all calculations independently before making investment decisions.

cagrx-0.1.0/README.md

@@ -0,0 +1,282 @@
+# 📈 cagrx
+
+![Status](https://img.shields.io/badge/status-work--in--progress-orange) ![Python](https://img.shields.io/badge/python-3.9%2B-blue)
+
+> **No Cap, only CAGR – Calculate Mutual fund Returns Like a Pro**
+
+*Download, analyze, and unlock insights from Indian mutual funds with ease.*
+
+---
+ 
+> [!WARNING]
+> **Work in Progress**: This library is under active development. APIs may change, and some features are still being refined. Contributions and feedback are welcome!
+
+**CagrX** is a powerful Python library to analyze mutual funds using AMFI (Association of Mutual Funds in India) data. Whether you're building a fintech app, conducting investment research, or analyzing portfolio performance, cagrx provides the tools you need to work with mutual fund data effortlessly.
+
+## ✨ Features
+
+- **Download Mutual Fund Data**: Fetch NAV (Net Asset Value) data for any Indian mutual fund scheme
+- **Historical Data**: Access historical NAV data with automatic chunking for large date ranges
+- **Fund Discovery**: Browse and search through all available mutual fund schemes
+- **Performance Analysis**: Built-in metrics for calculating returns:
+  - CAGR (Compound Annual Growth Rate)
+  - Trailing returns (1Y, 3Y, 5Y, etc.)
+  - Rolling returns with max/min/average statistics
+  - SIP (Systematic Investment Plan) return calculations
+- **Data Persistence**: Automatic caching of schemes list for faster subsequent access
+
+## 🚀 Installation
+
+> [!NOTE]
+> This library is not yet published to PyPI. Install from source for now.
+
+**Install from source:**
+
+```bash
+git clone https://github.com/yourusername/cagrx.git
+cd cagrx
+pip install -e .
+```
+
+**Or install dependencies manually:**
+
+```bash
+pip install pandas requests
+```
+
+## 📦 Requirements
+
+- Python >= 3.9
+- pandas
+- requests
+
+## 🔧 Usage
+
+### Getting Started with AMFI Data
+
+```python
+from cagrx.amfi import Amfi
+
+# Initialize AMFI client
+amfi = Amfi()
+```
+
+### Browse Available Mutual Funds
+
+```python
+# Get all fund houses
+fund_houses = amfi.get_fund_houses()
+print(fund_houses)
+
+# Get all schemes from a specific fund house
+schemes = amfi.get_schemes_by_fund_house("HDFC Mutual Fund")
+print(schemes)
+
+# Get complete schemes list (cached locally as amfi_navall.csv)
+all_schemes = amfi.list_all_schemes()
+
+# Force refresh the schemes list from AMFI and update cache
+# Useful when you want to ensure you have the new funds included
+refreshed_schemes = amfi.refresh_schemes()
+```
+
+### Download Historical NAV Data
+
+```python
+# Download NAV data for a specific scheme
+# Scheme code can be found from list_all_schemes()
+nav_data = amfi.get_nav_history(
+    scheme_id="122639",  # Example: HDFC Flexi Cap Fund
+    start_date="2020-01-01",
+    end_date="2023-12-31"
+)
+
+# Returns a pandas DataFrame with date as index and NAV values
+print(nav_data.head())
+```
+
+### Calculate Performance Metrics
+
+#### CAGR (Compound Annual Growth Rate)
+
+> [!NOTE]
+> You can use `-1` as a period to calculate the CAGR for the entire available historical data (Max CAGR).
+
+```python
+from cagrx.return_metrics import cagr, calculate_trailing_cagr
+
+# Calculate overall CAGR
+overall_cagr = cagr(nav_data)
+print(f"Overall CAGR: {overall_cagr * 100:.2f}%")
+
+# Calculate trailing CAGR for multiple periods
+trailing_returns = calculate_trailing_cagr(
+    nav_data,
+    periods=[-1, 1, 3, 5]  # -1 for Max CAGR, 1Y, 3Y, 5Y
+)
+print(trailing_returns)
+# Output: {'Max_CAGR': 0.165, '1Y_CAGR': 0.123, '3Y_CAGR': 0.156, '5Y_CAGR': 0.142}
+```
+
+#### Rolling Returns
+
+```python
+from cagrx.return_metrics import calculate_rolling_returns
+import pandas as pd
+
+# Calculate 1-year rolling returns
+rolling_metrics = calculate_rolling_returns(
+    nav_data,
+    period=pd.DateOffset(years=1)
+)
+
+print(f"Max rolling return: {rolling_metrics['max_returns'] * 100:.2f}%")
+print(f"Period: {rolling_metrics['max_return_period']}")
+print(f"Min rolling return: {rolling_metrics['min_returns'] * 100:.2f}%")
+print(f"Average rolling return: {rolling_metrics['avg_return'] * 100:.2f}%")
+```
+
+#### SIP Returns (What-If Analysis)
+
+Analyze how your periodic investments would have performed:
+
+```python
+from cagrx.amfi import Amfi
+from cagrx.return_metrics import calculate_sip_returns
+import pandas as pd
+
+# First, get the NAV data for the fund
+amfi = Amfi()
+nav_data = amfi.get_nav_history(
+    scheme_id="122639",
+    start_date="2020-01-01",
+    end_date="2023-12-31"
+)
+
+# Example 1: Regular monthly SIP of ₹5,000 for 3 years
+sip_dates = pd.date_range(start='2020-01-01', periods=36, freq='MS')
+sip_cashflows = pd.DataFrame({'amount': 5000}, index=sip_dates)
+
+returns = calculate_sip_returns(sip_cashflows, nav_data)
+print(f"Invested: ₹{returns['total_invested']:,.0f} → Current: ₹{returns['current_value']:,.0f}")
+print(f"Returns: {returns['return_percentage']:.2f}% (Annualized: {returns['annualized_return']:.2f}%)")
+
+# Example 2: Irregular investments (lump sum + step-up SIP)
+irregular_investments = pd.DataFrame({
+    'amount': [50000, 5000, 7500, 10000, 15000]
+}, index=pd.to_datetime([
+    '2020-01-15',   # Initial lump sum
+    '2020-06-01',   # ₹5k after 6 months
+    '2021-01-01',   # Stepped up to ₹7.5k
+    '2021-06-01',   # Stepped up to ₹10k
+    '2022-01-01'    # Stepped up to ₹15k
+]))
+
+irregular_returns = calculate_sip_returns(irregular_investments, nav_data)
+print(f"Irregular Returns: {irregular_returns['return_percentage']:.2f}%")
+```
+
+### Complete Example
+
+```python
+from cagrx.amfi import Amfi
+from cagrx.return_metrics import cagr, calculate_trailing_cagr, calculate_rolling_returns
+import pandas as pd
+
+# Initialize
+amfi = Amfi()
+
+# Browse HDFC schemes
+hdfc_schemes = amfi.get_schemes_by_fund_house("HDFC Mutual Fund")
+print("Available HDFC Schemes:")
+print(hdfc_schemes.head())
+
+# Download NAV data for HDFC Flexi Cap Fund
+nav_data = amfi.get_nav_history(
+    scheme_id="122639",
+    start_date="2018-01-01",
+    end_date="2024-12-31"
+)
+
+# Save to CSV for future use
+nav_data.to_csv("hdfc_flexi_cap_nav.csv")
+
+# Calculate performance metrics
+print("\n=== Performance Metrics ===")
+
+# Overall CAGR
+overall_return = cagr(nav_data)
+print(f"\nOverall CAGR: {overall_return * 100:.2f}%")
+
+# Trailing returns
+trailing = calculate_trailing_cagr(nav_data, periods=[1, 3, 5])
+print("\nTrailing Returns:")
+for period, value in trailing.items():
+    if value:
+        print(f"  {period}: {value * 100:.2f}%")
+    else:
+        print(f"  {period}: Insufficient data")
+
+# Rolling returns
+rolling = calculate_rolling_returns(nav_data, period=pd.DateOffset(years=1))
+print(f"\n1-Year Rolling Returns:")
+print(f"  Max: {rolling['max_returns'] * 100:.2f}%")
+print(f"  Min: {rolling['min_returns'] * 100:.2f}%")
+print(f"  Avg: {rolling['avg_return'] * 100:.2f}%")
+```
+
+## 📊 Data Sources
+
+All data is sourced from official AMFI (Association of Mutual Funds in India) APIs:
+- **Schemes List**: https://www.amfiindia.com/spages/NAVAll.txt
+- **Historical NAV**: https://www.amfiindia.com/api/nav-history
+
+## 🏗️ Project Structure
+
+```
+cagrx/
+├── src/
+│   └── cagrx/
+│       ├── __init__.py          # Main package entry point
+│       ├── amfi.py              # AMFI data fetching and management
+│       ├── return_metrics.py    # Performance calculation utilities
+│       └── utils.py             # Helper functions
+├── pyproject.toml               # Project configuration
+└── README.md                    # This file
+```
+
+## 🧪 Development
+
+### Running Tests
+
+```bash
+# Run the test file
+python src/cagrx/amfi_tests.py
+```
+
+## 🤝 Contributing
+
+Contributions are welcome! Please feel free to submit a Pull Request.
+
+1. Fork the project
+2. Create your feature branch (`git checkout -b feature/AmazingFeature`)
+3. Commit your changes (`git commit -m 'Add some AmazingFeature'`)
+4. Push to the branch (`git push origin feature/AmazingFeature`)
+5. Open a Pull Request
+
+## 📝 License
+
+This project is licensed under the MIT License - see the LICENSE file for details.
+
+## 🙏 Acknowledgments
+
+- Data provided by AMFI (Association of Mutual Funds in India)
+- Built with Python, pandas, and requests
+
+## 📮 Contact
+
+For questions or feedback, please open an issue on GitHub.
+
+---
+
+**Note**: This library is for educational and research purposes. Please verify all calculations independently before making investment decisions.

cagrx-0.1.0/pyproject.toml

@@ -0,0 +1,31 @@
+[project]
+name = "cagrx"
+version = "0.1.0"
+description = "A Python library to calculate return metrics like CAGR, XIRR, and SIP returns using AMFI data"
+readme = "README.md"
+requires-python = ">=3.9"
+license = {text = "MIT"}
+authors = [
+  {name = "Your Name", email = "your.email@example.com"},
+]
+classifiers = [
+    "Programming Language :: Python :: 3",
+    "License :: OSI Approved :: MIT License",
+    "Operating System :: OS Independent",
+]
+dependencies = [
+    "pandas",
+    "requests",
+]
+
+[project.urls]
+Homepage = "https://github.com/yourusername/cagrx"
+Repository = "https://github.com/yourusername/cagrx"
+Issues = "https://github.com/yourusername/cagrx/issues"
+
+[project.scripts]
+cagrx = "cagrx:main"
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"

cagrx-0.1.0/src/cagrx/__init__.py

@@ -0,0 +1,20 @@
+from cagrx.amfi import Amfi
+from cagrx.return_metrics import (
+    cagr,
+    calculate_trailing_cagr,
+    calculate_rolling_returns,
+    calculate_sip_returns,
+    xirr
+)
+
+__all__ = [
+    "Amfi",
+    "cagr",
+    "calculate_trailing_cagr",
+    "calculate_rolling_returns",
+    "calculate_sip_returns",
+    "xirr",
+]
+
+def main() -> None:
+    print("Hello from cagrx!")

cagrx-0.1.0/src/cagrx/amfi.py

@@ -0,0 +1,157 @@
+import requests
+import csv, os
+import pandas as pd
+from functools import cache
+
+from cagrx.utils import split_into_date_pairs
+
+SCHEMES_URL = "https://www.amfiindia.com/spages/NAVAll.txt"
+NAV_HISTORY_URL = "https://www.amfiindia.com/api/nav-history"
+
+class Amfi:
+
+    def __init__(self):
+        self.cache_file = "amfi_navall.csv"
+        self.schemes_list = self._load_schemes()
+        
+    
+    def list_all_schemes(self):
+        """
+        Get all schemes from the AMFI list
+        
+        :returns: pandas dataframe containing all schemes
+        """
+        return self.schemes_list
+
+    def get_fund_houses(self):
+        """
+        Get all the available fund houses from the AMFI list
+        
+        :returns: set of fund house names
+        """
+        return set(self.schemes_list["fund_house"].dropna().unique())
+        
+    def refresh_schemes(self) -> pd.DataFrame:
+        """
+        Force refresh schemes list from AMFI and update cache.
+        """
+        self.schemes_list = self._get_schemes_from_amfi()
+        self.schemes_list.to_csv(self.cache_file, index=False)
+        return self.schemes_list
+
+    def get_schemes_by_fund_house(self, fund_house):
+        """
+        Get available schemes for a given fund house
+        
+        :param fund_house: name of the fund house
+        :returns: pandas dataframe containing scheme codes and names
+        """
+        return self.schemes_list[self.schemes_list["fund_house"] == fund_house][['scheme_code', 'scheme_name']]
+
+    def get_nav_history(self, scheme_id, start_date, end_date):
+        """ 
+        Download NAV data for a given mutual fund scheme within the date range
+        
+        This method fetches the data in chunks of 5 years
+
+        :param start_date: start_date of the requested data period
+        :param end_date: end_date of the requested data period
+        :param scheme_id: scheme_id of the mutual fund for which the NAV should be fetched
+        :param freq: frequency of the data
+        
+        :returns: pandas dataframe containing nav data
+        """
+        
+        # AMFI allows maximum of five_years to be downloaded at a time
+        date_ranges = split_into_date_pairs(start_date, end_date, n_days=365 * 5) 
+        nav_records = []
+
+        for from_date, to_date in date_ranges:
+            records = self._fetch_historical_nav(scheme_id, from_date, to_date)
+            nav_records.extend(records)
+
+        return self._create_dataframe(nav_records)
+
+    def _get_schemes_from_amfi(self):
+        """
+        Get all schemes from the AMFI list
+        
+        :returns: pandas dataframe containing all schemes
+        """
+        # Fetch data
+        raw_lines = self._fetch_raw_nav_lines()
+        
+        current_fund_house = None
+        lines = []
+        
+        for line in raw_lines[1:]: #skip first line containing headers
+            line = line.strip()
+
+            if line.endswith("Mutual Fund"):
+                current_fund_house = line #if the current line is fund house name, store it and skip the iteration
+                continue
+
+            row = line.split(";")
+            if len(row) < 5:
+                continue #skip invalid or header lines
+            
+            row.append(current_fund_house)
+            lines.append(row)
+
+        columns = ["scheme_code", "isin_growth", "isin_reinv", "scheme_name", "nav", "date", "fund_house"]
+
+        return pd.DataFrame(lines, columns=columns)
+
+    def _fetch_historical_nav(self, scheme_id, from_date, to_date):
+        """ 
+        Actual method implementing the network/API call to the AMFI URL
+
+        :param scheme_id: scheme_id of the mutual fund for which the NAV should be fetched
+        :param from_date: start_date of the requested data period
+        :param to_date: end_date of the requested data period
+        """
+        
+        query_params = {
+            "query_type": "historical_period",
+            "sd_id": scheme_id,
+            "from_date": from_date,
+            "to_date": to_date,
+        }
+        resp = requests.get(
+            NAV_HISTORY_URL, params=query_params
+        )
+
+        if resp.status_code == 200:
+            raw_json = resp.json()
+            if "data" in raw_json:
+                return raw_json["data"]["nav_groups"][0]["historical_records"]
+            return [] #if no data found for the given date range
+        else:
+            raise ValueError(resp.text)
+
+    def _load_schemes(self):
+        """
+        Load schemes list from cache if available, otherwise sync from AMFI
+        """
+        if os.path.exists(self.cache_file):
+            return pd.read_csv(self.cache_file)
+        
+        return self.refresh_schemes()
+        
+    def _fetch_raw_nav_lines(self):
+        response = requests.get(SCHEMES_URL)
+        response.raise_for_status()
+        
+        return response.text.strip().splitlines()
+
+    def _create_dataframe(self, records):
+        """creates pandas dataframe from the raw records"""
+        
+        df = pd.DataFrame(records)
+        df['nav'] = pd.to_numeric(df['nav'])
+        df["date"] = pd.to_datetime(df["date"])
+        return df.set_index("date")
+    
+    
+
+

cagrx-0.1.0/src/cagrx/return_metrics.py

@@ -0,0 +1,238 @@
+import pandas as pd
+
+
+def cagr(df, column="nav"):
+    """
+    Calculate the Compound Annual Growth Rate (CAGR) for the given column over the DataFrame's period.
+    
+    :param df: DataFrame with datetime index
+    :param column: Column name to calculate CAGR on (default: 'nav')
+    :returns CAGR as a float (e.g., 0.12 for 12% annualized growth)
+
+    note: This method doesn't sort the index of the DataFrame. It is expected that the index is sorted in ascending order.
+    """   
+    start_value = df[column].iloc[0]
+    end_value = df[column].iloc[-1]
+
+    num_years = (df.index[-1] - df.index[0]).days / 365
+
+    if start_value <= 0 or num_years <= 0:
+        raise ValueError("Invalid data for CAGR calculation.")
+    
+    cagr = (end_value / start_value) ** (1 / num_years) - 1
+    return round(cagr, 3)
+
+
+def calculate_trailing_cagr(df, column="nav", periods=None):
+    """
+    Calculate the Compound Annual Growth Rate (CAGR) of a fund over the given periods.
+    
+    :param df: DataFrame with datetime index
+    :param column: Column name to calculate CAGR on (default: 'nav')
+    :returns CAGR as a float (e.g., 0.12 for 12% annualized growth)
+
+    note: -1 period is used to calculate CAGR of MAX period (considering all the data available)
+    """
+    if column not in df.columns:
+        raise ValueError(f"Column '{column}' not found in DataFrame")
+    
+    df = df.sort_index()
+    cagr_metrics = {}
+
+    for period in periods:
+        if period == -1:
+            cagr_metrics[f'Max_CAGR'] = cagr(df, column=column)
+            continue
+        
+        start_date = df.index[-1] - pd.DateOffset(years=period)
+        
+        # Not enough historical data for this period
+        if start_date < df.index[0]:
+            cagr_metrics[f'{period}Y_CAGR'] = None
+            continue
+        
+        #calculate cagr for the `n` period
+        cagr_metrics[f'{period}Y_CAGR'] = cagr(df.loc[start_date:], column=column)
+    
+    return cagr_metrics
+    
+def calculate_rolling_returns(df, column="nav", period=pd.DateOffset(years=1)):
+    """
+    Calculate the rolling returns for the given column over the DataFrame's period.
+    
+    :param df: DataFrame with datetime index
+    :param column: Column name to calculate rolling returns on (default: 'nav')
+    :param period: Period to calculate rolling returns for (default: 1 year)
+    :returns Rolling returns as a float (e.g., 0.12 for 12% annualized growth)
+    """
+    df = df.copy()[[column]]
+    dates_in_df = df.index.date
+    df['past_date'] = dates_in_df - period
+    
+    rolling_df = pd.merge_asof(df, df[['nav']], left_on='past_date', right_on='date', suffixes=('_current', '_past'))
+    rolling_df['past_date'] = rolling_df['past_date'].dt.date
+    rolling_df.index = dates_in_df
+
+    #drop rows where historical data for past dates are not available
+    rolling_df = rolling_df.dropna(subset=['nav_past'])
+    rolling_df['returns'] = ((rolling_df['nav_current'] - rolling_df['nav_past']) /  rolling_df['nav_past']).round(3)
+    
+    max_row  = rolling_df.loc[rolling_df['returns'].idxmax()]
+    min_row  = rolling_df.loc[rolling_df['returns'].idxmin()]
+    metrics = {
+        'max_returns': float(max_row['returns']),
+        'max_return_period': (str(max_row['past_date']), str(max_row.name)),
+        'min_returns': float(min_row['returns']),
+        'min_return_period': (str(min_row['past_date']), str(min_row.name)),
+        'avg_return': float(rolling_df['returns'].mean().round(3))
+    }
+    
+    return metrics
+
+def xirr(cashflows, dates, guess=0.1, max_iterations=100, tolerance=1e-6):
+    """
+    Calculate XIRR (Extended Internal Rate of Return) for irregular cash flows.
+    
+    Uses the Newton-Raphson method to find the rate that makes NPV = 0.
+    
+    :param cashflows: List or array of cash flows (negative for investments, positive for returns)
+    :param dates: List or array of dates corresponding to each cash flow (datetime objects)
+    :param guess: Initial guess for the rate (default: 0.1 or 10%)
+    :param max_iterations: Maximum number of iterations (default: 100)
+    :param tolerance: Convergence tolerance (default: 1e-6)
+    :returns: XIRR as a decimal (e.g., 0.15 for 15% annual return)
+    
+    Example:
+        cashflows = [-5000, -5000, -5000, 17500]
+        dates = pd.to_datetime(['2020-01-01', '2020-07-01', '2021-01-01', '2021-12-31'])
+        rate = xirr(cashflows, dates)
+        print(f"XIRR: {rate * 100:.2f}%")
+    """
+    if len(cashflows) != len(dates):
+        raise ValueError("cashflows and dates must have the same length")
+    
+    if len(cashflows) < 2:
+        raise ValueError("At least 2 cash flows are required")
+    
+    # Convert dates to pandas datetime if not already
+    dates = pd.to_datetime(dates)
+    
+    # Sort by dates
+    sorted_indices = dates.argsort()
+    cashflows = [cashflows[i] for i in sorted_indices]
+    dates = dates[sorted_indices]
+    
+    # Calculate days from first date
+    start_date = dates[0]
+    days = [(date - start_date).days for date in dates]
+    
+    # Newton-Raphson method
+    rate = guess
+    
+    for iteration in range(max_iterations):
+        # Calculate NPV (Net Present Value)
+        npv = sum(cf / ((1 + rate) ** (day / 365.0)) for cf, day in zip(cashflows, days))
+        
+        # Calculate derivative of NPV
+        dnpv = sum(-cf * day / 365.0 / ((1 + rate) ** (day / 365.0 + 1)) for cf, day in zip(cashflows, days))
+        
+        # Check for convergence
+        if abs(npv) < tolerance:
+            return round(rate, 6)
+        
+        # Avoid division by zero
+        if abs(dnpv) < 1e-10:
+            raise ValueError("XIRR calculation failed: derivative too small")
+        
+        # Update rate using Newton-Raphson formula
+        rate = rate - npv / dnpv
+        
+        # Check if rate is becoming unreasonable
+        if rate < -0.99 or rate > 10:  # -99% to 1000% range
+            raise ValueError("XIRR calculation failed: rate out of reasonable bounds")
+    
+    raise ValueError(f"XIRR did not converge after {max_iterations} iterations")
+
+def calculate_sip_returns(sip_cashflows, nav_df, column="nav"):
+    """
+    Calculate total returns using SIP (Systematic Investment Plan) cashflow.
+    
+    :param sip_cashflows: DataFrame with datetime index and 'amount' column representing investment amounts
+    :param nav_df: DataFrame with datetime index and NAV column
+    :param column: Column name for NAV values (default: 'nav')
+    :returns: Dictionary with total invested, current value, absolute returns, and return percentage
+    
+    Example:
+        sip_cashflows = pd.DataFrame({
+            'amount': [5000, 5000, 5000]
+        }, index=pd.to_datetime(['2024-01-01', '2024-02-01', '2024-03-01']))
+        
+        nav_df = pd.DataFrame({
+            'nav': [100, 105, 110, 115]
+        }, index=pd.to_datetime(['2024-01-01', '2024-02-01', '2024-03-01', '2024-04-01']))
+        
+        returns = calculate_sip_returns(sip_cashflows, nav_df)
+    """
+    if 'amount' not in sip_cashflows.columns:
+        raise ValueError("sip_cashflows must have 'amount' column")
+    if column not in nav_df.columns:
+        raise ValueError(f"Column '{column}' not found in nav_df")
+    
+    # Sort both dataframes by index
+    sip_cashflows = sip_cashflows.sort_index()
+    nav_df = nav_df.sort_index()
+    
+    # Merge SIP cashflows with NAV data to get NAV at each investment date
+    # direction is set to `forward` because we want the NAV that's available on the 
+    # same day or after the investment date
+    # eg: If investment is made on a holiday, we want the NAV that's available on the next trading day (not the previous trading day)
+    merged = pd.merge_asof(
+        sip_cashflows,
+        nav_df[[column]],
+        left_index=True,
+        right_index=True,
+        direction='forward' 
+    )
+    
+    print(merged)
+    # Calculate units purchased at each SIP date
+    merged['units'] = merged['amount'] / merged[column]
+    
+    # Calculate total invested and total units
+    total_invested = merged['amount'].sum()
+    total_units = merged['units'].sum()
+    
+    # Get current NAV (last available NAV)
+    current_nav = nav_df[column].iloc[-1]
+    
+    # Calculate current value
+    current_value = total_units * current_nav
+    
+    # Calculate absolute returns
+    absolute_returns = current_value - total_invested
+    return_percentage = (absolute_returns / total_invested) * 100 if total_invested > 0 else 0
+    
+    # Calculate annualized returns (XIRR approximation using simple CAGR)
+    if len(sip_cashflows) > 1:
+        # Time period from first investment to last NAV date
+        days = (nav_df.index[-1] - sip_cashflows.index[0]).days
+        years = days / 365.25
+        
+        if years > 0 and total_invested > 0:
+            # Simple annualized return approximation
+            annualized_return = ((current_value / total_invested) ** (1 / years) - 1) * 100
+        else:
+            annualized_return = 0
+    else:
+        annualized_return = 0
+    
+    return {
+        'total_invested': round(total_invested, 2),
+        'current_value': round(current_value, 2),
+        'absolute_returns': round(absolute_returns, 2),
+        'return_percentage': round(return_percentage, 2),
+        'annualized_return': round(annualized_return, 2),
+        'total_units': round(total_units, 4),
+        'current_nav': round(current_nav, 2),
+        'investment_period_days': (nav_df.index[-1] - sip_cashflows.index[0]).days if len(sip_cashflows) > 0 else 0
+    }

cagrx-0.1.0/src/cagrx/utils.py

@@ -0,0 +1,22 @@
+import time
+from datetime import datetime, timedelta
+
+def split_into_date_pairs(start_date_str, end_date_str, n_days=100):
+    """
+    Splits the range between start_date and end_date into `n_days=n` intervals
+    Returns a list of (start, end) date pairs.
+    """
+    start_date = datetime.strptime(start_date_str, "%Y-%m-%d")
+    end_date = datetime.strptime(end_date_str, "%Y-%m-%d")
+
+    pairs = []
+    current_start = start_date
+
+    while current_start < end_date:
+        current_end = min(current_start + timedelta(days=n_days - 1), end_date)
+        pairs.append(
+            (current_start.strftime("%Y-%m-%d"), current_end.strftime("%Y-%m-%d"))
+        )
+        current_start = current_end + timedelta(days=1)
+
+    return pairs

cagrx-0.1.0/tests/test_cagrx.py

@@ -0,0 +1,95 @@
+
+import unittest
+import pandas as pd
+from datetime import datetime
+from cagrx.return_metrics import cagr, calculate_trailing_cagr, calculate_rolling_returns, xirr, calculate_sip_returns
+from cagrx.amfi import Amfi
+import os
+
+class TestReturnMetrics(unittest.TestCase):
+    
+    def setUp(self):
+        # Setup common data
+        self.dates = pd.date_range(start='2020-01-01', end='2023-01-01', freq='D')
+        self.nav_values = [100 * (1.00032)**i for i in range(len(self.dates))] # Approx 12% annual growth
+        self.df = pd.DataFrame({'nav': self.nav_values}, index=self.dates)
+
+    def test_cagr_calculation(self):
+        # Test basic CAGR
+        result = cagr(self.df)
+        self.assertIsInstance(result, float)
+        self.assertAlmostEqual(result, 0.123, places=2) # Expect approx 12-13%
+
+    def test_trailing_cagr(self):
+        # Test trailing CAGR including Max (-1)
+        periods = [1, -1]
+        result = calculate_trailing_cagr(self.df, periods=periods)
+        
+        self.assertIn('1Y_CAGR', result)
+        self.assertIn('Max_CAGR', result)
+        self.assertIsNotNone(result['1Y_CAGR'])
+        self.assertIsNotNone(result['Max_CAGR'])
+        
+        # Max CAGR should equal total period cagr
+        self.assertEqual(result['Max_CAGR'], cagr(self.df))
+
+    def test_xirr(self):
+        # Test cases from original test_xirr.py
+        
+        # Test 1: Regular investments
+        cashflows = [-5000, -5000, -5000, 17500]
+        dates = pd.to_datetime(['2020-01-01', '2020-07-01', '2021-01-01', '2021-12-31'])
+        rate = xirr(cashflows, dates)
+        self.assertAlmostEqual(rate, 0.11, places=1) # Approx 11%
+
+        # Test 2: Irregular investments
+        cashflows2 = [-10000, -5000, -7500, 25000]
+        dates2 = pd.to_datetime(['2020-01-15', '2020-06-01', '2021-01-01', '2022-06-30'])
+        rate2 = xirr(cashflows2, dates2)
+        self.assertIsInstance(rate2, float)
+
+        # Test 3: Loss scenario
+        cashflows3 = [-10000, -10000, 18000]
+        dates3 = pd.to_datetime(['2020-01-01', '2020-06-01', '2021-12-31'])
+        rate3 = xirr(cashflows3, dates3)
+        self.assertLess(rate3, 0) # Should be negative
+
+    def test_sip_returns(self):
+        # Simple SIP test
+        sip_dates = pd.date_range(start='2020-01-01', periods=12, freq='MS')
+        sip_cashflows = pd.DataFrame({'amount': 1000}, index=sip_dates)
+        
+        result = calculate_sip_returns(sip_cashflows, self.df)
+        
+        self.assertIn('total_invested', result)
+        self.assertIn('current_value', result)
+        self.assertIn('return_percentage', result)
+        self.assertEqual(result['total_invested'], 12000)
+
+class TestAmfiIntegration(unittest.TestCase):
+    
+    def setUp(self):
+        self.amfi = Amfi()
+        self.scheme_id = "122639" # Common fund for testing
+    
+    def test_get_historical_nav(self):
+        # This test hits the network
+        try:
+            nav = self.amfi.get_historical_nav(self.scheme_id, "2023-01-01", "2023-01-10")
+            self.assertIsInstance(nav, pd.DataFrame)
+            self.assertFalse(nav.empty)
+            self.assertIn('nav', nav.columns)
+            self.assertEqual(len(nav), len(nav.dropna()))
+        except Exception as e:
+            self.skipTest(f"Network or API issue: {e}")
+
+    def test_refresh_schemes(self):
+        try:
+            schemes = self.amfi.refresh_schemes()
+            self.assertIsInstance(schemes, pd.DataFrame)
+            self.assertFalse(schemes.empty)
+        except Exception as e:
+            self.skipTest(f"Network or API issue: {e}")
+
+if __name__ == '__main__':
+    unittest.main()