# PortBlend (RuleSense) — Full Technical Reference for Developers & AI Agents

PortBlend provides quantitative strategy correlation matrix calculation, portfolio weight optimization (SLSQP minimizer), equity curve blending, and drawdown minimization.

- **Developer Quickstart (llms.txt)**: https://portblend.com/llms.txt
- **Product Changelog & Release History**: https://portblend.com/changelog

---

## 1. Authentication & Headers

Bearer API Key required for `/api/v1/` endpoints:
`Authorization: Bearer pb_live_<hex>`
`Content-Type: application/json`

---

## 2. API Endpoints & Request/Response JSON Schemas

### A. POST /api/v1/correlate
Calculates pairwise return correlation matrix across 2 to 50 strategy NAV series.

Request Schema:
```json
{
  "series_ids": ["STRAT_A", "STRAT_B"],
  "series_data": {
    "STRAT_A": [["2025-01-01", 100.0], ["2025-01-02", 101.5]],
    "STRAT_B": [["2025-01-01", 100.0], ["2025-01-02", 98.8]]
  }
}
```

Response Schema:
```json
{
  "status": "success",
  "strategies": ["STRAT_A", "STRAT_B"],
  "correlation_matrix": {
    "STRAT_A": {"STRAT_A": 1.0, "STRAT_B": -0.42},
    "STRAT_B": {"STRAT_A": -0.42, "STRAT_B": 1.0}
  },
  "classifications": {
    "STRAT_A__STRAT_B": {
      "coefficient": -0.42,
      "category": "NEGATIVE",
      "label": "Negative / Hedging",
      "insight": "Strong hedging capability between strategy pair."
    }
  },
  "summary_stats": {
    "avg_off_diagonal_correlation": -0.42,
    "max_correlated_pair": ["STRAT_A", "STRAT_B"],
    "max_correlation_value": -0.42,
    "min_correlated_pair": ["STRAT_A", "STRAT_B"],
    "min_correlation_value": -0.42
  },
  "correlation_insight": "Average strategy correlation is -0.42 (low/uncorrelated)."
}
```

### B. POST /api/v1/blend (or POST /api/sii for guests)
Executes SLSQP portfolio weight optimization across 5 targets.

Optimization Targets (`target` field):
- `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%.

Request Schema:
```json
{
  "series_ids": ["STRAT_A", "STRAT_B"],
  "series_data": {
    "STRAT_A": [["2025-01-01", 100.0], ["2025-01-02", 101.5]],
    "STRAT_B": [["2025-01-01", 100.0], ["2025-01-02", 98.8]]
  },
  "weights": {"STRAT_A": 50.0, "STRAT_B": 50.0},
  "allowed_rebalancing": ["monthly"],
  "target": "protection",
  "allow_cash": true,
  "enable_weekly": true,
  "enable_daily": false,
  "enable_contribution": true,
  "enable_dominance": true
}
```

### C. POST /api/dcd
Public single-strategy Drawdown Dynamics analysis.

Request Schema:
```json
{
  "series_id": "STRATEGY_1",
  "series_data": [{"date": "2025-01-01", "nav": 100.0}, {"date": "2025-01-02", 101.5}],
  "enable_weekly": true,
  "enable_daily": false
}
```

---

## 3. Error Codes & HTTP Status

- `UNAUTHORIZED` (HTTP 401): Missing, invalid, or revoked Bearer API key.
- `LIMIT_EXCEEDED` (HTTP 403 / 400): Strategy count exceeds account tier quota.
- `VALIDATION_ERROR` (HTTP 400): Malformed dates, missing columns, or <2 valid rows.
- `ENGINE_ERROR` (HTTP 500): Server calculation engine exception.

---

## 4. Python SDK (`portblend`) Full Interface

```python
from portblend import PortBlendClient, DataTransformer

client = PortBlendClient(
    api_key="pb_live_...",
    base_url="https://app.portblend.com/api"
)

# 1. Correlation Matrix (returns pandas.DataFrame)
df_corr = client.correlate(data="strategies.csv") # accepts CSV, Excel, DataFrame, directory

# 2. Portfolio Optimization (returns BlendResult)
result = client.blend(
    data="strategies.csv",
    target="protection", # protection (min_drawdown) | efficiency (max_sharpe) | recovery (max_calmar) | stability (min_volatility) | downside_safety (max_sortino) | risk_balance (balanced_protection) | buffered (buffered_allocation)
    allow_cash=True
)

# Properties of BlendResult:
result.weights             # dict[str, float] — e.g. {'STRAT_A': 45.0, 'STRAT_B': 35.0}
result.max_drawdown        # float
result.annual_return       # float
result.sharpe_ratio        # float
result.drawdown_reduction  # float (%)
result.correlation_matrix  # pandas.DataFrame
result.raw_response        # dict — raw JSON backend payload
result.summary()           # prints formatted terminal summary
```

---

## 5. Command-Line Interface (`portblend` CLI)

Available Commands:
- `portblend login --key <API_KEY>` — Save API key locally
- `portblend logout` — Clear saved API key
- `portblend status` — Validate API key and server connectivity
- `portblend correlate --file <FILE_OR_DIR>` — Compute correlation matrix
- `portblend analyze --file <FILE_OR_DIR> [--target TARGET] [--no-cash] [--json]` — Portfolio weight optimization
- `portblend drawdown --file <FILE>` — Single-strategy drawdown dynamics (public)
- `portblend demo` — Zero-key offline walkthrough
- `portblend examples` — Display code recipes & Colab notebook link

---

## 6. Interactive Colab Notebook
Google Colab Quickstart: https://colab.research.google.com/github/portblend-research/portblend-python/blob/main/doc/examples/01_quickstart_portblend.ipynb