Professional

Portfolio Rebalancer Tool

Tax-aware equity-sleeve rebalancing tool that reduced workflow from hours to seconds

PythonStreamlitPandasPyInstallerPydantic

The Problem

Rebalancing done by spreadsheet and manual checks creates drift mistakes, inconsistent decisions across advisors, and a brutal amount of repetitive work. In taxable accounts, selling to rebalance can blow up realized gains, violate short-vs-long tax treatment, and break netting rules—so 'hit target weights' is often the wrong objective. Broker-dealer approved tools couldn't handle these constraints, especially for legacy/merged portfolios with embedded gains.

The Solution

Built a Python rebalancing engine with a Streamlit GUI that encodes the CIO's trading philosophy: sector/security drift constraints, tax sensitivity with budget limits, wash-sale guardrails, and phase-out logic for legacy holdings. The engine produces audit-friendly trade logs including cash before/after, tax impact, and price provenance. After multiple iterations under CIO scrutiny, shipped as a PyInstaller executable so portfolio managers can run it with one click—no Python required.

Product Decisions

  • Deterministic rules over black-box optimization—every output is auditable and explainable for compliance
  • Preserved human control for white-glove trading context instead of full automation
  • Tax budget enforcement mechanism constrains sell decisions by tax impact, not just allocation math
  • Evolved from CLI → Streamlit UI → PyInstaller executable to maximize PM adoption
  • Multi-phase logic with state snapshots to prevent phases from undoing each other

Architecture

Backend

Python package with modular services: RebalancerEngine orchestrator, TaxManager, WashSaleService, ExposureGroupManager

Database

Excel/CSV file-based inputs for portability; JSON state snapshots for audit trails

APIs

Pricing subsystem with cache + API fallbacks + manual override for corporate network resilience

Other

Streamlit UI with session persistence → PyInstaller desktop executable

Constraints I Designed Around

  • Broker-dealer tool limitations—approved tools couldn't handle complex tax scenarios
  • White-glove trading for UHNW clients—human control must be preserved, not black-box
  • Embedded gains / tax constraints—legacy portfolios with significant unrealized gains
  • Non-technical users—PM team adoption without Python installation
  • CIO-level scrutiny—every trade decision must be auditable and explainable
  • SSL/certificate issues—corporate network proxies breaking pricing API calls

Tradeoffs & Decisions

Deterministic rules enginevsBlack-box optimization

Auditable outputs required for compliance and CIO sign-off

Human control preservedvsFull automation

White-glove context matters for UHNW clients

Desktop executable (PyInstaller)vsWeb application

Security requirements, offline capability, and zero-install deployment

Multi-phase orchestration with snapshotsvsSingle-pass algorithm

Prevents phases from undoing each other (canceling trades bug)

Resilient pricing with fallbacksvsSingle API dependency

Corporate SSL/proxy issues required graceful degradation

Technical Highlights

  • Tax accounting layer with ST/LT gain/loss buckets + netting rules + tax budget enforcement
  • TLH strategy: loss-only harvesting, wash-sale guardrails (30-day window), sibling/alternate symbol awareness
  • Raise Cash service: deterministic target-weight adjustment with normalization that preserves cash targets + audit change logs
  • Exposure group manager for reasoning about security groups (GOOG/GOOGL) with caps and consumption tracking
  • Enterprise-grade pricing: resilient cache + API fallbacks + manual override to survive SSL/proxy failures
  • 726 automated tests including golden rule invariants and end-to-end workflows
  • Multi-phase orchestration with checkpoints to prevent 'canceling trades' between phases

Results & Outcomes

  • Paid internal engagement—CIO-sponsored tool adopted across the firm
  • Reduced rebalance cycle time from hours to seconds
  • Zero-Python adoption path—non-technical PM team uses it independently
  • Standardized trading workflow into repeatable, auditable outputs aligned to CIO-defined constraints

What I'd Do Next

  • Web-based dashboard for real-time portfolio monitoring
  • API layer for integration with custodian platforms
  • Expand to support additional asset classes beyond equities
Back to Projects