The portfolio library: architecture

Written 2026-10-02 by lane 2 (quant). This is the design of pipeline/tipsheet/lab/, the library behind the portfolio lab v2 (portfolio_lab_v2_spec.md) and the SIP studies (sip_studies_spec.md). The v1 script (compute/portfolio_lab.py) stays in place until v2 is merged and the site has moved to the v2 bundles.

Why a library

The v1 lab was one script with nine portfolios hard-wired into if branches. Adding a portfolio meant editing the simulator, the tax code lived in two copies, and the only cash-flow pattern was a lump sum. The owner’s priorities (a full library of allocation models, SIP outcome distributions, Indian tax by date, honest multiple-testing statistics) need building blocks that compose:

asset universe ──► allocation rule ──► rebalancing policy ──┐
                                                            ├──► engine ──► result ──► evaluators ──► bundles
cash-flow schedule ──► cost model ──► tax engine ───────────┘

Every portfolio is a declarative entry in lab/portfolios.yaml. The registry turns an entry into a rule plus a rebalancing policy, and the same entry is rendered on the site as the portfolio’s construction note. Adding a portfolio means adding an entry, not code, unless it needs a rule type that does not exist yet.

Modules

The data contract inside the library

• Prices: a daily panel of total-return levels on the NSE trading calendar, one column per asset key, forward-filled only across non-NSE holidays of the non-equity series. A column is NaN before its first real observation and never back-filled.
• The view: rules never see the panel directly. They receive a View that is cut at the decision date (view.upto(d) raises if asked for anything later). This is the look-ahead guard, and a test checks it by scrambling every price after d and asserting the decision at d does not move.
• Timing: decisions are taken at a close (a month-end by default) and traded at the next session’s close. Cash flows land on their scheduled session and are invested at that close.
• Units: the engine holds units of each asset, priced at the asset’s NAV: the total-return level times the running-cost drag up to that day. Running costs therefore reduce the NAV the way a fund’s TER does, and the tax engine sees gains on that NAV.

The engine

An event loop over the sessions where something happens (a trade, a cash flow, a financial-year end), with the wealth path between events valued in one vectorised step (units are fixed between events). Each event, in order:

1. Cash flow in: the instalment buys assets. Under the default cash-flow policy it goes to the sleeves furthest below target first (“cash-flow rebalancing”), so a SIP into a multi-asset portfolio sells less.
2. Rebalance: if the policy says so, sell overweight sleeves (lots go through the tax engine; the tax is accrued, not paid yet) and buy underweight ones with the proceeds net of costs.
3. Financial-year end (31 March, or the last session before it): the ledger settles the year’s realised gains with Indian set-off rules and the optional exemption, and the tax is paid by selling every sleeve pro rata. Gains realised by that sale fall into the next year’s ledger, which is how a real investor pays tax from the portfolio.
4. Withdrawals (SWP) are sales like any other.
5. Liquidation: at the end of a window everything is sold and that final year is settled at once, so buy-and-hold pays its deferred tax too.

The engine records the daily wealth, month-end weights, every trade, costs paid, tax paid by year, turnover, and the external cash flows (for XIRR).

The tax engine

lab/tax.py replaces the simplified compute/aftertax.py for v2 work (the trend models keep using the old one until they are moved). It encodes, by sale date and buy date:

• Equity-oriented funds: the pre-2004 regime, the STT era from 1 October 2004 (long-term gains exempt, short-term at 10%, then 15% from April 2008), section 112A from April 2018 (10% above the annual exemption, with the 31 January 2018 grandfathered cost), and the 23 July 2024 rates (20% short, 12.5% long, exemption Rs 1.25 lakh).
• Debt and other funds: the holding period for long-term status (12 months, then 36 months from the 2014 Budget), 20% with indexation using the Cost Inflation Index, the section 50AA “specified mutual fund” rule for units bought from April 2023 (slab rate whatever the holding period), the 2024 changes (12.5% without indexation; 24 months for unlisted units, 12 for listed ones), and the 2025 narrowing of “specified mutual fund” to funds with more than 65% in debt.
• Gold: taxed as a non-equity fund (gold ETF or fund of fund), with the 2024 and 2025 rules above.
• The investor: a resident individual in the top slab (30%) without surcharge, plus the cess in force (3% to FY2017-18, 4% from FY2018-19). The annual equity exemption is off by default (it depends on the investor’s other gains) and on in a sensitivity run.
• Set-off: within a financial year, short-term losses offset any gains; long-term losses offset only long-term gains. Carry-forward of unabsorbed losses (eight years) is modelled.

Every rule carries its source in a comment and a worked example in tests/test_lab_tax.py.

Evaluators

Return measures (CAGR for lump sums, XIRR for flows; pre-tax, after-tax, and real after CPI), risk (volatility and downside deviation from monthly returns, Sharpe and Sortino over the T-bill, Ulcer index), drawdown anatomy (each drawdown’s peak, trough, recovery and length), rolling windows (3, 5, 10 years), calendar years, regime splits, tracking error and beta against 60/40, turnover, cost drag and tax drag, start-date sensitivity, and the multiple-testing set: the deflated Sharpe ratio (Bailey and López de Prado 2014), the probability of backtest overfitting by combinatorially symmetric cross-validation (Bailey, Borwein, López de Prado and Zhu 2017), and stationary block-bootstrap confidence intervals (Politis and Romano 1994).

Tests

pipeline/tests/test_lab_*.py: worked tax examples for each regime, XIRR against closed forms, rebalancing arithmetic (wealth conservation with zero costs, bands that trigger only outside the band), the look-ahead guard, optimiser sanity (ERC equalises risk contributions, min variance beats any random long-only mix), registry round-trips, and the SIP study’s window bookkeeping.

What it does not do (yet)

• No leverage and no shorting: Indian retail allocators cannot easily do either, and every rule is long-only and fully invested (cash is an asset).
• No intraday or daily rules: the finest decision grid is monthly.
• No international sleeve in the headline window (see the v2 spec).