Metadata-Version: 2.4
Name: canopy-optimizer
Version: 3.0.2
Summary: Institutional-grade hierarchical portfolio optimization (HRP, HERC, NCO) with data loading, metrics, and backtesting — by Anagatam Technologies
Author: Anagatam Technologies
License-Expression: Apache-2.0
Project-URL: Homepage, https://github.com/Anagatam/Canopy
Project-URL: Documentation, https://canopy-institutional-hierarchical-optimization-engine.readthedocs.io/en/latest/
Project-URL: Repository, https://github.com/Anagatam/Canopy
Project-URL: Issues, https://github.com/Anagatam/Canopy/issues
Project-URL: PyPI, https://pypi.org/project/canopy-optimizer/
Project-URL: Changelog, https://github.com/Anagatam/Canopy/blob/main/docs/changelog.md
Keywords: portfolio-optimization,hierarchical-risk-parity,hrp,herc,nco,quantitative-finance,risk-management,asset-allocation,covariance-estimation,random-matrix-theory,backtesting,portfolio-metrics
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Financial and Insurance Industry
Classifier: Intended Audience :: Science/Research
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Office/Business :: Financial :: Investment
Classifier: Topic :: Scientific/Engineering :: Mathematics
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: numpy>=1.24
Requires-Dist: pandas>=2.0
Requires-Dist: scipy>=1.10
Requires-Dist: plotly>=5.18
Requires-Dist: scikit-learn>=1.3
Requires-Dist: networkx>=2.6
Provides-Extra: dev
Requires-Dist: pytest>=7.0; extra == "dev"
Requires-Dist: pytest-cov>=4.0; extra == "dev"
Requires-Dist: yfinance>=0.2; extra == "dev"
Provides-Extra: data
Requires-Dist: yfinance>=0.2; extra == "data"
Dynamic: license-file

🌳 Canopy

  The Institutional Hierarchical Portfolio Optimization Engine
  HRP · HERC · NCO — Three algorithms. One facade. Zero matrix inversions.

  Documentation (https://canopy-institutional-hierarchical-optimization-engine.readthedocs.io/en/latest/) ·
  PyPI (https://pypi.org/project/canopy-optimizer/) ·
  Wiki (https://github.com/Anagatam/Canopy/wiki) ·
  Release Notes (https://github.com/Anagatam/Canopy/releases) ·
  Disclaimer (https://github.com/Anagatam/Canopy/blob/main/DISCLAIMER.md)

  HRP
  HERC
  NCO

  Tests
  Code style: black

---

**Canopy** is an open-source, institutional-grade Python library for hierarchical portfolio allocation. It implements three algorithms — **HRP**, **HERC**, and **NCO** — with four covariance estimators, four risk measures, walk-forward backtesting, and a full compliance audit trail.

One facade. One import. One line to optimal weights.

```python
from canopy.MasterCanopy import MasterCanopy

weights = MasterCanopy(method='HRP', cov_estimator='ledoit_wolf').cluster(returns).allocate()
```

> [!NOTE]
> **Canopy Pro** — featuring next-generation hierarchical algorithms (HRCP, HERC-DRL, Spectral NCO, Bayesian HRP), 12+ risk measures, real-time streaming covariance, and enterprise support — is under active development.
> [📩 Sign up for early access →](https://github.com/Anagatam/Canopy/issues)

---

## Table of Contents

- [Why Canopy?](#why-canopy)
- [Quick Start](#quick-start)
- [Examples](#examples)
- [Algorithms](#algorithms)
- [Covariance Estimators](#covariance-estimators)
- [Risk Measures & Portfolio Modes](#risk-measures--portfolio-modes)
- [New in v3.0](#-new-in-v30)
- [Performance Benchmarks](#performance-benchmarks)
- [Architecture](#architecture)
- [Installation](#installation)
- [Documentation](#-documentation)
- [Canopy Pro](#-canopy-pro)
- [License & Disclaimer](#%EF%B8%8F-license--disclaimer)

---

## Why Canopy?

| | What | Why it matters |
|---|------|---------------|
| 🏗️ | **Three algorithms, one facade** | HRP, HERC, NCO — each with distinct risk-return properties. Switch with one parameter. |
| 📐 | **Four covariance estimators** | Ledoit-Wolf, Marchenko-Pastur denoising, EWMA, detoning. The covariance _is_ the portfolio. |
| 📊 | **Four risk measures** | Variance, CVaR, CDaR, MAD — HERC allocates across clusters using the measure you choose. |
| 🔍 | **Full audit trail** | ISO 8601 timestamped. Export as JSON. MiFID II / SEC Rule 15c3-5 compliant traceability. |
| 🧪 | **Zero matrix inversion** | HRP never inverts Σ. Stable even when condition number > 10⁸. |
| ⚡ | **Fast** | HRP: 11ms, HERC: 17ms, NCO: 46ms on 20 assets. Pure NumPy/SciPy. |

---

## Quick Start

```bash
pip install canopy-optimizer
```

```python
import yfinance as yf
from canopy.MasterCanopy import MasterCanopy

# Fetch → Optimize → Allocate
data = yf.download(['AAPL', 'MSFT', 'GOOGL', 'AMZN', 'JPM'], start='2020-01-01')
returns = data['Close'].pct_change().dropna()

opt = MasterCanopy(method='HRP', cov_estimator='ledoit_wolf')
weights = opt.cluster(returns).allocate()
print(weights)
```

```
AAPL     0.1824
MSFT     0.2016
GOOGL    0.1953
AMZN     0.1892
JPM      0.2315
```

---

## Examples

### 📊 DataLoader — Zero-Boilerplate Data Pipeline

```python
from canopy.data import DataLoader
from canopy.MasterCanopy import MasterCanopy

# One-liner: fetch Nifty stocks + benchmark
returns, nifty = DataLoader.yfinance(
    ['RELIANCE.NS', 'TCS.NS', 'HDFCBANK.NS', 'INFY.NS', 'ICICIBANK.NS',
     'SBIN.NS', 'BHARTIARTL.NS', 'KOTAKBANK.NS', 'LT.NS', 'ITC.NS'],
    start='2021-01-01',
    benchmark='^NSEI'   # Auto-fetches Nifty 50
)

opt = MasterCanopy(method='HRP')
weights = opt.cluster(returns).allocate()
print(weights)
```

### 🎯 HERC — Tail-Risk-Aware Allocation with CVaR

```python
opt = MasterCanopy(
    method='HERC',
    cov_estimator='denoised',    # Marchenko-Pastur denoising
    risk_measure='cvar',         # CVaR for tail-risk-aware allocation
    detone=True,                 # Remove market mode for better clustering
    min_weight=0.01,             # UCITS-compliant floor
    max_weight=0.10              # UCITS-compliant ceiling
)
weights = opt.cluster(returns).allocate()
```

### 🔬 NCO — Full Audit Trail for Compliance

```python
opt = MasterCanopy(
    method='NCO',
    cov_estimator='ledoit_wolf',
    max_k=8,                     # Up to 8 clusters
)
weights = opt.cluster(returns).allocate()

# Institutional-grade audit
print(opt.summary())             # Human-readable report
audit = opt.tojson()             # Machine-readable JSON for compliance
diag = opt.diagnostics()         # Eigenvalue + condition number analysis
print(f"Condition Number: {diag['covariance']['condition_number']:.0f}")
```

### 📈 Full Backtest + Performance Metrics

```python
from canopy.data import DataLoader
from canopy.MasterCanopy import MasterCanopy
from canopy.metrics import PortfolioMetrics
from canopy.backtest import BacktestEngine

# Load data
returns, sp500 = DataLoader.yfinance(
    ['AAPL', 'MSFT', 'GOOGL', 'AMZN', 'NVDA', 'META',
     'JPM', 'JNJ', 'PG', 'KO'],
    start='2020-01-01',
    benchmark='^GSPC'
)

# Walk-forward backtest with monthly rebalancing
engine = BacktestEngine(
    optimizer=MasterCanopy(method='HRP', cov_estimator='ledoit_wolf'),
    frequency='monthly',
    lookback=252,
)
result = engine.run(returns)
print(result.summary())

# Performance analytics
opt = MasterCanopy(method='HRP', cov_estimator='ledoit_wolf')
weights = opt.cluster(returns).allocate()

pm = PortfolioMetrics(returns, weights, benchmark=sp500)
print(f"Sharpe Ratio      : {pm.sharpe():.3f}")
print(f"Sortino Ratio     : {pm.sortino():.3f}")
print(f"Max Drawdown      : {pm.maxdrawdown():.2%}")
print(f"CVaR (5%)         : {pm.cvar():.4f}")
print(f"Information Ratio : {pm.informationratio():.3f}")
print(pm.report())              # Full formatted report
```

---

## Algorithms

Canopy implements three hierarchical allocation algorithms. Each solves the portfolio construction problem differently:

![Allocation Comparison](images/allocation.svg)

| Algorithm | Method | Key Property | Speed |
|-----------|--------|-------------|-------|
| **HRP** | Recursive bisection under inverse-variance risk parity. No Σ⁻¹ required. | Maximum stability | 11 ms |
| **HERC** | Two-stage: inter-cluster risk parity + intra-cluster inverse-variance. 4 risk measures. | Cluster-aware diversification | 17 ms |
| **NCO** | Tikhonov-regularized nested optimization: `(Σ_k + λI)⁻¹ · 1` | Lowest tail risk | 46 ms |

### Cumulative Returns: India — Canopy vs Nifty 50

![India Cumulative Returns](images/cumulative_india.svg)

### Cumulative Returns: US — Canopy vs S&P 500

![US Cumulative Returns](images/cumulative_us.svg)

---

## Covariance Estimators

The covariance matrix is the single most important input. Canopy provides four institutional-grade estimators:

| Estimator | Formula | When to Use |
|-----------|---------|-------------|
| **Sample** | `Σ̂ = (1/T)·Rᵀ·R` | Baseline. T/N ratio > 10× |
| **Ledoit-Wolf** | `Σ_LW = α·F + (1−α)·Σ̂` | **Default.** Reduces estimation error ~40% |
| **Denoised** | Marchenko-Pastur RMT: clip eigenvalues below `λ₊ = σ²(1+√(N/T))²` | High-noise. N/T > 0.5 |
| **EWMA** | `Σ_t = λ·Σ_{t-1} + (1−λ)·rₜ·rₜᵀ` | Regime-adaptive |

**Detoning** (Lopez de Prado, 2020): Removes the market mode (first eigenvector) before clustering for more discriminative sector-level grouping.

---

## Risk Measures & Portfolio Modes

### HERC Inter-Cluster Risk Allocation

| Measure | Use Case |
|---------|----------|
| **Variance** | Classic Raffinot (2017). Symmetric risk budgeting. |
| **CVaR** | Tail risk. Allocates _away_ from crash-prone clusters. |
| **CDaR** | Drawdown risk. Penalizes deep underwater periods. |
| **MAD** | Robust to outliers. No squared deviations. |

### Portfolio Modes

| Mode | Constraint | Use Case |
|------|-----------|----------|
| `long_only` | `wᵢ ≥ 0` | Mutual funds, ETFs, pensions, UCITS |
| `long_short` | `Σwᵢ = 1` | Hedge funds, 130/30 strategies |
| `market_neutral` | `Σwᵢ = 0` | Statistical arbitrage |

---

## Dendrogram & Cluster Analysis

Canopy builds a full hierarchical clustering tree using 7 linkage methods (Ward, Single, Complete, Average, Weighted, Centroid, Median) with optional optimal leaf ordering (Bar-Joseph et al., 2001):

![Dendrogram](images/dendrogram.svg)

The dendrogram reveals the correlation structure of the asset universe. Strongly correlated assets cluster together at low distances, while uncorrelated assets are separated at higher distances.

### Risk Decomposition

Canopy decomposes portfolio risk to show each asset's marginal contribution to total variance:

![Risk Contribution](images/risk.svg)

Equal Risk Contribution (the gold dashed line at 5% for N=20) is the theoretical target. HRP with denoised covariance achieves near-equal risk contribution without any explicit optimization constraint.

---

## 📦 New in v3.0

### DataLoader

Zero-boilerplate data pipeline. Fetch from Yahoo Finance, CSV, Parquet, or DataFrame.

```python
from canopy.data import DataLoader

returns, nifty = DataLoader.yfinance(
    ['RELIANCE.NS', 'TCS.NS', 'HDFCBANK.NS', 'INFY.NS'],
    start='2021-01-01',
    benchmark='^NSEI'
)

returns = DataLoader.csv('prices.csv')
returns = DataLoader.parquet('bloomberg.parquet')
```

### PortfolioMetrics

Math separated from logic. Pure functions + comprehensive reporting class.

```python
from canopy.metrics import PortfolioMetrics

pm = PortfolioMetrics(returns, weights, benchmark=nifty)
print(pm.sharpe())           # Annualized Sharpe Ratio
print(pm.maxdrawdown())      # Maximum peak-to-trough decline
print(pm.cvar())             # Conditional Value-at-Risk
print(pm.report())           # Full formatted report
```

### BacktestEngine

Walk-forward rebalancing. Daily, weekly, monthly, quarterly, annual frequencies.

```python
from canopy.backtest import BacktestEngine, MasterCanopy

engine = BacktestEngine(
    optimizer=MasterCanopy(method='HRP', cov_estimator='ledoit_wolf'),
    frequency='monthly',
    lookback=252,
)
result = engine.run(returns)
print(result.summary())
```

> 📖 [Full API Reference on ReadTheDocs →](https://canopy-institutional-hierarchical-optimization-engine.readthedocs.io/en/latest/)

---

## Performance Benchmarks

Benchmarked on 20 global assets (US + India), 5 years of daily data (2020–2025):

| Method | Cov Estimator | Sharpe | Sortino | CVaR 95% | Max DD | Speed |
|--------|--------------|--------|---------|----------|--------|-------|
| **HRP** | Denoised | **0.83** | 0.95 | -2.27% | -30.5% | 11 ms |
| **HRP** | Ledoit-Wolf | 0.79 | 0.91 | -2.29% | -31.0% | 11 ms |
| **HERC** | LW + CVaR | 0.70 | 0.81 | -2.35% | -31.8% | 17 ms |
| **NCO** | Ledoit-Wolf | 0.68 | 0.79 | **-2.19%** | **-23.2%** | 46 ms |

### Feature Matrix

| Feature | Status |
|---------|:------:|
| HRP, HERC, NCO Allocation | ✅ |
| 4 Covariance Estimators (Sample, Ledoit-Wolf, Denoised, EWMA) | ✅ |
| 4 Risk Measures (Variance, CVaR, CDaR, MAD) | ✅ |
| Correlation Matrix Detoning | ✅ |
| Weight Constraints (min/max) | ✅ |
| 3 Portfolio Modes | ✅ |
| DataLoader (yfinance, CSV, Parquet) | ✅ |
| PortfolioMetrics (Sharpe, Sortino, CVaR, Calmar, IR) | ✅ |
| Walk-Forward BacktestEngine | ✅ |
| ISO 8601 Audit Trail + JSON Export | ✅ |
| 9 Interactive Plotly Charts | ✅ |
| 7 Linkage Methods + Optimal Leaf Ordering | ✅ |
| Block Bootstrap Confidence Intervals | ✅ |
| 29 Tests Passing (0.84s) | ✅ |

---

## Architecture

```
canopy/
├── MasterCanopy.py              ← Facade (v3.0.0)
├── core/
│   ├── CovarianceEngine.py      ← Ledoit-Wolf, Denoised, EWMA, Detoning
│   └── ClusterEngine.py         ← 7 Linkage Methods, 4 Distance Metrics
├── optimizers/
│   ├── HRP.py                   ← Vectorized Recursive Bisection
│   ├── HERC.py                  ← 4 Risk Measures (Var, CVaR, CDaR, MAD)
│   └── NCO.py                   ← Tikhonov-Regularized Nested Optimization
├── data/
│   └── loader.py                ← DataLoader (.yfinance, .csv, .parquet)
├── metrics/
│   └── performance.py           ← Sharpe, Sortino, MaxDD, CVaR, Calmar, IR
├── backtest/
│   └── engine.py                ← Walk-Forward BacktestEngine
├── viz/ChartEngine.py           ← 9 Interactive Plotly Charts
├── tests/test_canopy.py         ← 29 Tests (all passing)
└── docs/                        ← Sphinx + ReadTheDocs
```

### Design Principles

1. **Fail fast, fail loud.** Inputs validated at construction time, not compute time.
2. **Zero matrix inversion for HRP.** Stable even for near-singular covariance matrices.
3. **Audit everything.** Every step timestamped. Export JSON for compliance.
4. **Modular kernel.** `core/` (math), `optimizers/` (allocation), `viz/` (charts), `data/` (loading), `metrics/` (analytics), `backtest/` (simulation).
5. **Fluent API.** `opt.cluster(returns).allocate()` — one chain, readable, Pythonic.

---

## Installation

```bash
pip install canopy-optimizer
```

With data loading:
```bash
pip install canopy-optimizer[data]
```

From source:
```bash
git clone https://github.com/Anagatam/Canopy.git
cd Canopy && pip install -e .[dev]
```

**Requirements:** Python ≥ 3.10 · NumPy · Pandas · SciPy · scikit-learn · Plotly · NetworkX

---

## Testing

```bash
pytest tests/test_canopy.py -v          # Run tests
pytest tests/test_canopy.py -v --cov    # With coverage
```

**29/29 tests passing** in 0.84 seconds.

---

## 📚 Documentation

| Resource | Link |
|----------|------|
| **ReadTheDocs** | [canopy-institutional-hierarchical-optimization-engine.readthedocs.io](https://canopy-institutional-hierarchical-optimization-engine.readthedocs.io/en/latest/) |
| **PyPI** | [pypi.org/project/canopy-optimizer](https://pypi.org/project/canopy-optimizer/) |
| **GitHub Wiki** | [github.com/Anagatam/Canopy/wiki](https://github.com/Anagatam/Canopy/wiki) |
| **API Reference** | [docs/api_reference.md](docs/api_reference.md) |
| **Algorithms** | [docs/algorithms.md](docs/algorithms.md) |
| **Linkage Methods** | [docs/linkage_methods.md](docs/linkage_methods.md) |
| **Diagnostics** | [docs/diagnostics.md](docs/diagnostics.md) |

---

## 🔮 Canopy Pro

**Canopy Pro** is our advanced premium engine designed for **institutional portfolio managers, financial analysts, and investment advisors** who need cutting-edge capabilities beyond the open-source edition. It builds on Canopy's proven foundation with next-generation algorithms, expanded risk analytics, and enterprise-grade integrations.

### 🧬 Next-Generation Algorithms

| Algorithm | What It Does |
|-----------|-------------|
| **HRCP** (Hierarchical Risk Contribution Parity) | Achieves **exact risk budgets** (< 0.01% tolerance) through iterative scaling within the hierarchical tree. Designed for Basel III/IV risk parity mandates. |
| **HERC-DRL** (Deep Reinforcement Learning) | A policy gradient agent **dynamically reweights clusters** based on rolling covariance features. Trained on 20+ years of crisis data (GFC, COVID, SVB). |
| **Spectral NCO** | Combines **spectral graph theory** with **persistent homology** (topological data analysis) to capture higher-order asset dependencies beyond pairwise correlations. |
| **Bayesian HRP** | Integrates **Black-Litterman posterior returns** into the hierarchical tree, enabling view-consistent allocation for portfolio managers with conviction ideas. |

### 📐 Advanced Covariance

| Estimator | What It Delivers |
|-----------|------------------|
| **DCC-GARCH** | Time-varying correlations that capture regime shifts during market stress — critical for VaR models under Basel III. |
| **Factor Models** (Barra-style) | Handles universes of 500+ assets via factor-based decomposition (style + industry), reducing dimensionality from N² to K². |
| **Realized Kernels** | Reconstructs covariance from intraday tick data with microstructure noise removal. Purpose-built for HFT and intraday rebalancing. |

### 📊 12+ Risk Measures

| Measure | What It Captures |
|---------|------------------|
| **EVaR** (Entropic VaR) | Coherent + convex. Tighter tail bound than CVaR. The preferred measure for robust optimization. |
| **RLVaR** (Relativistic VaR) | Handles heavy-tailed (non-Gaussian) return distributions. Based on Kaniadakis entropy. |
| **EDaR** (Entropic Drawdown-at-Risk) | Drawdown-aware tail risk for multi-horizon institutional portfolios. |
| **Tail Gini** | Measures inequality in the return tail — a more nuanced view of concentration risk than VaR alone. |
| **Omega Ratio** | Uses the full return distribution, not just the left tail, for a complete risk-return picture. |

### 🔌 Enterprise Integration

| Integration | Use Case |
|------------|----------|
| **Bloomberg B-PIPE / SAPI** | Direct market data ingestion from Bloomberg Terminal |
| **Refinitiv Eikon** | Alternative data source for firms on Refinitiv |
| **MOSEK Solver** | Convex optimization backend for constrained Pro algorithms |
| **Real-Time Streaming** | WebSocket-based covariance updates for intraday rebalancing |

### Feature Comparison

| Capability | Canopy (Open Source) | Canopy Pro |
|-----------|:-------------------:|:----------:|
| Algorithms | 3 (HRP, HERC, NCO) | **7+** (HRCP, HERC-DRL, Spectral NCO, Bayesian HRP) |
| Covariance Estimators | 4 | **8+** (DCC-GARCH, Factor Models, Realized Kernels) |
| Risk Measures | 4 | **12+** (EVaR, RLVaR, EDaR, Tail Gini, Omega) |
| Portfolio Modes | 3 | **6+** (Risk Budgeting, Black-Litterman, Regime-Aware) |
| Data Sources | yfinance, CSV | **Bloomberg, Refinitiv, streaming** |
| Backtesting | Walk-forward | **Walk-forward + Monte Carlo + Stress Testing** |
| Support | Community | **Priority SLA + Dedicated Engineering** |

> **Interested in Canopy Pro?** [📩 Sign up for early access →](https://github.com/Anagatam/Canopy/issues)
>
> Built specifically for institutional portfolio managers, financial analysts, and investment advisors.

---

## ⚖️ License & Disclaimer

**Apache License 2.0** — Copyright © 2026 [Anagatam Technologies](https://github.com/Anagatam). All rights reserved.

> [!CAUTION]
> **Not investment advice.** Canopy is a mathematical software library for educational and research purposes only. It does not provide financial recommendations or trading signals. Consult a licensed financial professional before making investment decisions. See [DISCLAIMER.md](https://github.com/Anagatam/Canopy/blob/main/DISCLAIMER.md) for SEC, SEBI, and global regulatory compliance.

---

  Built with precision for the institutional quantitative finance community.

  📖 Docs (https://canopy-institutional-hierarchical-optimization-engine.readthedocs.io) ·
  📦 PyPI (https://pypi.org/project/canopy-optimizer/) ·
  📚 Wiki (https://github.com/Anagatam/Canopy/wiki) ·
  📰 Wikipedia (https://en.wikipedia.org/wiki/Draft:Canopy_(software)) ·
  🐛 Issues (https://github.com/Anagatam/Canopy/issues) ·
  ⚖️ Disclaimer (https://github.com/Anagatam/Canopy/blob/main/DISCLAIMER.md)

