mts1b-reportslibrary

Reports library + CLI: trade_report, postmortem_auto_rca, alpha_decay, NAV reports, settlement reports, TCA dashboards.

Repo: github.com/MTS1B/mts1b-reportslibrary Layer: 4 Wave: 2 (months 4-7) Depends on: foundation, platform, quantkit, jinja2, plotly, weasyprint Audience: every operator + auditor

What it is

A reusable report library. Each report:

• Takes structured inputs (fund ids, date range, options)
• Reads from mts1b-datalake + mts1b-oms + mts1b-treasury
• Produces HTML (interactive) + PDF (auditable) + JSON (machine-readable)

Reports shipped

Report	Purpose	Output
trade_report	Per-fund trade ledger + P/L breakdown	HTML, PDF, parquet
nav_report	NAV trajectory + benchmarks + risk metrics	HTML, PDF
postmortem_auto_rca	Auto root-cause analysis of a drawdown event	HTML
alpha_decay	Strategy IC over time + decay diagnostics	HTML, PDF
settlement_report	Per-broker settled trades, fees, taxes	PDF, CSV (for tax software)
risk_envelope_report	Risk envelope events, gate-failure breakdown	HTML, PDF
tca_report	Transaction Cost Analysis (vs VWAP/arrival/IS benchmarks)	HTML, PDF
regime_attribution	P/L decomposition by market regime	HTML
factor_attribution	P/L decomposition by factor exposure	HTML
position_attribution	Per-symbol cumulative contribution	HTML

Module layout

mts1b_reportslibrary/
├── reports/
│   ├── trade_report.py
│   ├── nav_report.py
│   ├── postmortem_auto_rca.py
│   ├── alpha_decay.py
│   ├── settlement_report.py
│   ├── risk_envelope_report.py
│   ├── tca_report.py
│   ├── regime_attribution.py
│   ├── factor_attribution.py
│   └── position_attribution.py
├── templates/
│   ├── trade_report.html.j2
│   ├── components/
│   │   ├── equity_curve.html.j2
│   │   ├── dd_chart.html.j2
│   │   └── ...
│   └── base.html.j2
├── renderers/
│   ├── html.py
│   ├── pdf.py                 # weasyprint
│   └── parquet.py
└── cli.py

CLI

mts1b-report trade \
  --fund-id paper-momentum \
  --start 2026-01-01 --end 2026-05-23 \
  --output reports/trade-paper-momentum-2026-q1.html

mts1b-report postmortem \
  --fund-id paper-momentum \
  --drawdown-start 2026-04-12 \
  --drawdown-end 2026-04-18 \
  --output reports/postmortem-2026-04.html

The postmortem report auto-pulls relevant events from the audit chain + price action + news + sentiment + factor exposures to construct a narrative.

Programmatic

from mts1b_reportslibrary import trade_report

html = await trade_report(
    fund_id="paper-momentum",
    start=date(2026, 1, 1),
    end=date(2026, 5, 23),
    format="html",
    include=["equity_curve", "trade_table", "regime_attribution"],
)

Mix-and-match sections via include=[...].

TCA report

For every order, compute and display:

Metric	Formula
Realized	actual fill avg price
Arrival	quote at order arrival (pre-execution)
VWAP benchmark	venue's VWAP during execution window
Implementation shortfall	(realized - arrival) × side_sign
Slippage	(realized - arrival) - fees

Aggregated per strategy, broker, asset class, order type. Goal: detect when an algorithm or broker is consistently giving up edge.

Settlement report

Per-broker monthly statement:

• Trades settled (date, symbol, side, qty, price)
• Fees by category (commission, regulatory, exchange)
• Realized P/L (FIFO or HIFO)
• Tax-lot history (per broker's reporting)
• 1099-equivalent fields for U.S. brokers

Exports to CSV in formats accepted by major tax software (TurboTax, FreeTaxUSA, GainsKeeper).

Postmortem RCA

For a P/L event (defined drawdown window):

1. Pull every order + fill in window.
2. Pull every NATS event in window.
3. Pull market context (regime, VIX, sector returns).
4. Pull news + sentiment for held names.
5. Build attribution: which strategy / symbol / action contributed how much?
6. Feed to mts1b-llm persona "rca_analyst" for narrative summary.
7. Render: timeline + attribution table + LLM narrative + suggested fixes.

mts1b-report postmortem ... --output postmortem.html

Templates

Jinja2 + Plotly + custom React-free components (so PDFs render correctly without browser). Templates customizable per-tenant via ~/.mts1b/templates/.

Scheduling

Reports can be scheduled via Prefect:

mts1b.config

reports:
  daily_nav:
    cron: "0 18 * * 1-5"      # 6pm ET, weekdays
    funds: [paper-momentum, live-crypto]
    distribute: [email, telegram]

  weekly_tca:
    cron: "0 8 * * 1"          # 8am Mon
    distribute: [pdf-to-s3]

Distribution targets: file (local), s3, telegram, slack, email.

Build + test

pip install -e ".[dev]"
pytest -m unit

Reports are tested via golden-file comparison: re-render against fixture data, diff against a known-good HTML/PDF. Plotly outputs deterministic SVG by seeding the layout engine.

Roadmap

Version	Items
0.1 (Wave 2)	10 core reports, HTML + PDF + parquet renderers, CLI
0.2 (Wave 2)	Scheduled reports via Prefect, email + Slack delivery
0.3 (Wave 3)	Interactive dashboards (in mts1b-frontends), real-time TCA
1.0 (LTS)	Stable report schemas

See also

• mts1b-datalake — read source
• mts1b-llm — narrative summarization for postmortem RCA
• mts1b-operations — audit chain