README.md

---
title: Portfolio Volatility Analyzer
emoji: 📊
colorFrom: blue
colorTo: green
sdk: docker
pinned: false
short_description: Portfolio risk analysis with OCR and LaTeX formulas
---

# 📊 Portfolio Volatility Analyzer

Analyze your investment portfolio risk using **Modern Portfolio Theory** with OCR, interactive visualizations, and beautiful mathematical formulas.

## Features

- 📸 **OCR Portfolio Parsing**: Upload screenshots of your portfolio and automatically extract tickers and amounts
- ✏️ **Editable JSON**: Correct OCR errors with an intuitive JSON editor
- 📈 **Historical Data**: Automatically fetch 1 year of price data from Yahoo Finance
- 🧮 **Full Calculations**:
  - Portfolio weights
  - Log returns
  - Covariance matrix
  - Portfolio variance and volatility
- 📐 **Beautiful LaTeX Formulas**: See every calculation step with symbolic and numerical formulas
- 📊 **Detailed Variance Expansion**: Step-by-step breakdown showing how each asset contributes to portfolio risk
- 🎚️ **Interactive Rebalancing**: Adjust portfolio amounts with sliders and see volatility update in real-time

## How to Use

1. **Upload Portfolio Screenshot**: Take a screenshot of your portfolio (must show ticker symbols and dollar amounts)
2. **Edit Portfolio JSON**: Review and correct any OCR errors in the JSON editor
3. **Validate Portfolio**: Click "Validate Portfolio" to start analysis
4. **View Results**: See historical data, covariance matrix, and detailed formulas
5. **Rebalance**: Use interactive sliders to adjust positions and see impact on volatility

## Technical Details

### Formula Highlights

**Portfolio Variance:**
```
σ²_p = w^T × Σ × w
```

Where:
- `w` = vector of portfolio weights
- `Σ` = covariance matrix (annualized)

**Portfolio Volatility:**
```
σ_p = √(σ²_p)
```

### Architecture

- **Frontend**: Streamlit
- **OCR**: Tesseract (pytesseract)
- **Financial Data**: yfinance (Yahoo Finance)
- **Math**: NumPy, Pandas, SymPy
- **Deployment**: Docker on Hugging Face Spaces

## Local Development

### Prerequisites
- Python 3.11+
- Tesseract OCR installed

### Setup
```bash
# Install dependencies
pip install -r requirements.txt

# Run the app
streamlit run app.py
```

### Docker Build
```bash
# Build
docker build -t portfolio-analyzer .

# Run
docker run -p 7860:7860 portfolio-analyzer
```

## Example Portfolio

Test the app with this JSON:
```json
{
  "AAPL": 5000,
  "GOOGL": 3000,
  "MSFT": 2000
}
```

## Notes

- Uses 252 trading days for annualization
- Calculates log returns: ln(P_t / P_{t-1})
- Smart truncation for portfolios with 4+ tickers
- 1-hour cache for historical data to reduce API calls

## Built With

- Modern Portfolio Theory
- LaTeX mathematical notation
- Real-time financial data

---

Check out the configuration reference at https://huggingface.co/docs/hub/spaces-config-reference