Metadata-Version: 2.4
Name: portblend
Version: 0.2.2
Summary: Python SDK and CLI for PortBlend strategy correlation matrix calculation, portfolio weight optimization, and drawdown minimization.
Author-email: PortBlend Research <research@portblend.com>
License: MIT
Project-URL: Homepage, https://app.portblend.com
Project-URL: Documentation, https://app.portblend.com/docs
Project-URL: Repository, https://github.com/portblend-research/portblend-python
Keywords: correlation-matrix,portfolio-blending,equity-curve,drawdown-minimization,quant-finance,sharpe-optimization,ai-agent-tools,llm-tools,nav-analytics,trading-telemetry
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Topic :: Office/Business :: Financial :: Investment
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: requests>=2.28.0
Requires-Dist: pandas>=1.5.0
Requires-Dist: openpyxl>=3.0.0
Requires-Dist: tabulate>=0.9.0
Dynamic: license-file

# PortBlend Python SDK (`portblend`)

[![PyPI version](https://img.shields.io/badge/pypi-v0.2.0-blue.svg)](https://pypi.org/project/portblend/)
[![Open In Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/portblend-research/portblend-python/blob/main/doc/examples/01_quickstart_portblend.ipynb)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![Python 3.10+](https://img.shields.io/badge/python-3.10%2B-blue.svg)](https://www.python.org/)

Official Python SDK and Command-Line Interface (`portblend`) for strategy return correlation matrix calculation, SLSQP portfolio weight optimization, and quantitative risk management.

---

## 1. Quickstart — Python SDK Tutorial

### Installation
```bash
pip install portblend
```

### Code Example: Compute Correlation Matrix & Optimize Portfolio Weights
```python
from portblend import PortBlendClient
import pandas as pd

# 1. Initialize PortBlend Client with Developer API Key
client = PortBlendClient(
    api_key="pb_live_abcdef1234567890",
    base_url="https://app.portblend.com/api"  # Or http://localhost:8000/api
)

# 2. Compute Pairwise Strategy Correlation Matrix
# Accepts CSV, TSV, Excel file path, pandas.DataFrame, or raw CSV text string
df_corr = client.correlate(data="path/to/strategy_navs.csv")
print("Pairwise Return Correlation Matrix:")
print(df_corr)

# 3. Optimize Portfolio Weights for Protection (min_drawdown)
result = client.blend(
    data="path/to/strategy_navs.csv",
    target="protection",  # "protection" | "efficiency" | "recovery" | "stability" | "downside_safety" | "risk_balance" | "buffered"
    allow_cash=True       # Allow allocation to synthetic CASH buffer
)

# 4. Print Educational Quantitative Summary
result.summary()

# 5. Access Optimal Weights Dictionary
print("Optimal Weights (%):", result.weights)
```

---

## 2. Optimization Targets

- `protection` (min_drawdown) — Cuts maximum portfolio loss depth to the absolute minimum.
- `efficiency` (max_sharpe) — Maximizes overall risk-adjusted return.
- `recovery` (max_calmar) — Maximizes return relative to maximum peak-to-trough drawdown.
- `stability` (min_volatility) — Minimizes daily portfolio price swings and variance.
- `downside_safety` (max_sortino) — Ignores upside gains, penalizing only negative losses.
- `risk_balance` (balanced_protection) — Balances drawdown and return dynamically using a scaled utility model.
- `buffered` (buffered_allocation) — Optimizes strategy blend first, then applies a cash buffer of up to 50%.

---

## 3. Quickstart — Command-Line Interface (CLI) Tutorial

### Login & Save API Key
```bash
portblend login --key pb_live_abcdef1234567890
```

### Calculate Strategy Correlation Matrix
```bash
portblend correlate --file strategies.csv
```

### Run Portfolio Weight Optimization
```bash
# Target Protection (min_drawdown) with CASH buffer allowed
portblend optimize --file strategies.csv --target protection

# Target Efficiency (max_sharpe) with 100% strategy allocation (no CASH)
portblend optimize --file strategies.csv --target efficiency --no-cash
```
