# Quantitative Finance Tools 💹

![Python](https://img.shields.io/badge/Python-3.9%2B-blue)
![License](https://img.shields.io/badge/License-MIT-green)
![Status](https://img.shields.io/badge/Status-Active-success)

A high-performance Python library for **quantitative portfolio construction**, **risk management**, and **financial analysis**. Built for data engineers and quants to streamline research workflows.

## 🚀 Key Features

*   **Portfolio Optimization**: Mean-Variance Optimization (MVO) using `scipy.optimize` to maximize returns or Sharpe Ratio.
*   **Risk Metrics**: Calculate Value at Risk (VaR) and Conditional VaR (CVaR/Expected Shortfall) with strict statistical rigor.
*   **Modular Design**: Clean, type-hinted, and testable components ready for production pipelines.

## 📦 Installation

```bash
git clone https://github.com/YOUR_USERNAME/quantitative-finance-tools.git
cd quantitative-finance-tools
pip install -r requirements.txt
```

## ⚡ Usage

### Portfolio Optimization

```python
import numpy as np
from src.optimization import optimize_portfolio

# Example Data
returns = np.array([0.12, 0.18, 0.15])
cov_matrix = np.array([[0.04, 0.004, 0.002], 
                       [0.004, 0.09, 0.003], 
                       [0.002, 0.003, 0.05]])

result = optimize_portfolio(returns, cov_matrix)
print(f"Optimal Weights: {result['weights']}")
```

### Risk Analysis

```python
from src.risk import calculate_var

# Historical daily returns
daily_returns = np.random.normal(0.001, 0.02, 1000)
var_95 = calculate_var(daily_returns, confidence_level=0.95)
print(f"Value at Risk (95%): {var_95:.4f}")
```

## 📚 Theory

This library implements Modern Portfolio Theory (MPT) principles:

$$
\text{Maximize } S_p = \frac{R_p - R_f}{\sigma_p}
$$

Where $S_p$ is the Sharpe Ratio.

## 🤝 Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

## 📄 License

MIT License.