Portfolio Rebalancer

portfolio-rebalancer

You hand over a positions map plus book value, a per-name variance- share cap, a per-name weight cap, and a max churn per rebalance. The skill returns a specific trade-ticket list with dollar amounts, weight deltas, and before/after variance-share readings.

risk-report tells you which name is driving the risk. This skill tells you what to trim, by how much, and where to redistribute.

When to invoke

• After a risk-report run flags a name with variance share far disproportionate to its weight
• Portfolio-review workflow, decision-support step
• The user says "rebalance", "trim my winners", "cut variance", "what should I sell", "reduce concentration"
• Any time the operator wants an actionable answer, not a report

What you need

• MASSIVE_API_KEY — Stocks Starter for daily aggs on every name + benchmark

What you get back

Layer 1 JSON matching output-schema.json. Per-name trade tickets sorted by absolute dollar amount, plus portfolio-level before/after summary (vol, top-3 variance share, Herfindahl, max variance share), constraint-satisfaction status.

Layer 2 rendered table. Before/after summary block, then a table of trades, then a status line. See references/rendering.md.

How it works

1. Parse positions from either a comma-separated string (TICKER=WEIGHT) or a book JSON file. Same shape as risk-report for consistency.
2. Pull daily aggs for every position + benchmark over the lookback_days window (default 252).
3. Compute covariance: per-name annualized vol, shrinkage- adjusted correlation, covariance matrix. Same machinery as risk-report.
4. Compute current variance shares via w_i * (Σw)_i / total.
5. Solve iteratively:
   • For every over-cap name, trim by sqrt(target/current) since variance share scales roughly quadratically with weight.
   • Redistribute freed weight to under-cap names in proportion to their current weight.
   • Enforce max_weight cap after distribution; clip and re- redistribute if needed.
   • Renormalize to preserve gross exposure.
   • Iterate to convergence or max_iter.
6. Apply churn cap: if the target rebalance exceeds max_churn one-way turnover, scale the delta vector down proportionally until it fits. Emit a status flag when this happens.
7. Emit trade tickets: delta_weight * book_value per name, drop trades below min_trade_dollar.

Endpoints used

• GET /v2/aggs/ticker/{ticker}/range/1/day/{from}/{to} for every position + benchmark

Doesn't handle (yet)

• Not tax-aware. Selling appreciated positions incurs capital gains; the tool ignores this. Apply the trade list through a tax- lot-aware execution layer if lots matter.
• Not liquidity-aware. Dollar amounts do not consider ADV, spread, or market impact. Verify with slippage-cost before executing large trades in illiquid names.
• Descriptive against a risk cap, not return-maximizing. The tool does not use forward return estimates. It solves for a specified risk-share target only.
• Covariance is estimated with shrinkage but still relies on the last N trading days. Regime shifts can change covariance faster than the estimator adapts.
• Single-asset-class only. Multi-asset books (equities + fixed income + crypto) need the correlation panel to align across asset types — not handled in v1.