Metadata-Version: 2.4
Name: taxrebalance
Version: 0.1.0
Summary: Tax-aware portfolio rebalancing with Canadian ACB and U.S. tax-lot models
Author: Garros Gong
License-Expression: MIT
Project-URL: Homepage, https://github.com/garroshub/taxrebalance
Project-URL: Repository, https://github.com/garroshub/taxrebalance
Project-URL: Demo, https://garroshub.github.io/taxrebalance/
Keywords: portfolio,optimization,tax,rebalancing,risk
Classifier: Development Status :: 3 - Alpha
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 :: Scientific/Engineering :: Mathematics
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: numpy<3,>=1.26
Requires-Dist: cvxpy<2,>=1.6.5
Requires-Dist: osqp<1.1,>=1.0.4
Provides-Extra: test
Requires-Dist: pytest>=8; extra == "test"
Requires-Dist: build>=1.2; extra == "test"
Requires-Dist: twine>=6; extra == "test"
Dynamic: license-file

# TaxRebalance

Tax-aware portfolio rebalancing in Python, with Canadian average adjusted cost base (ACB), U.S. tax-lot accounting, and tracking-error constrained optimization.

The package accepts user-supplied securities, prices, target weights, covariance matrices, and dated taxable holdings. It produces proposed trades with modeled tax effects, transaction fees, risk penalties, post-trade cash, and solver feasibility diagnostics.

**Python 3.10+ · CVXPY and Clarabel · CAD and USD research models**

## Install

```bash
pip install taxrebalance
```

## Quickstart

```python
from datetime import date
from taxrebalance import (
    CADTransaction, CanadaACB, Portfolio, RebalanceConfig, rebalance
)

portfolio = Portfolio(
    jurisdiction="CA",
    prices={"XIC": 100.0, "XEF": 100.0},
    transactions=(
        CADTransaction(date(2025, 1, 10), "XIC", "BUY", 60, 115),
        CADTransaction(date(2025, 2, 12), "XEF", "BUY", 40, 85),
    ),
    valuation_date=date(2026, 10, 8),
)
result = rebalance(
    portfolio,
    target_weights={"XIC": 0.50, "XEF": 0.50},
    covariance=[[0.04, 0.01], [0.01, 0.04]],
    tax_policy=CanadaACB(marginal_rate=0.42, inclusion_rate=0.50),
    config=RebalanceConfig(max_tracking_error=0.015),
)
print(result.summary())
print(result.trades)
```

The default `tax_aware` method uses a convex relaxation and local fixed-direction search. The package also supports `risk_only`, `greedy`, `hold`, and `small_exact`. Exhaustive direction enumeration applies to at most four securities in the continuous-share model.

## Inputs and results

- **Canada:** dated purchase and sale transactions, aggregated into average ACB pools for identical securities across the taxpayer's own taxable accounts.
- **United States:** individual tax lots with acquisition basis, holding period, and limited replacement-purchase flags.
- **Constraints:** target weights, annual tracking-error cap, transaction fees, cash availability, nonnegative holdings, and sale quantities.
- **Results:** per-security trades, modeled current and future tax effects, estimated trading fees, risk penalties, solver status, and risk feasibility.
- **Interfaces:** Python API, CSV and JSON inputs, JSON results, CSV trade export, and a command-line entry point.

This is a continuous-share decision model. Tax-loss eligibility, superficial-loss and wash-sale treatment, and future transactions require review outside the package. No live market feed, trading execution, tax-return filing, or return forecast is provided.

## Links

- Repository and complete documentation: https://github.com/garroshub/taxrebalance
- Interactive synthetic portfolio demo: https://garroshub.github.io/taxrebalance/

MIT License.
