Epic 1: sable-cli Returns Loss Function

Status: ✅ Complete (January 2026)

Overview

The CLI loss function provides tooling for the iterative convergence approach to returns reconciliation. Rather than manually debugging each discrepancy, we compute a loss function and iteratively minimize it.

Commands Implemented

sable returns loss

Computes the total loss L = Σ(sable_return - btig_return)² across all entities and dates.

# Basic usage - shows summary metrics
sable returns loss

# Filter by entity
sable returns loss --entity "Anthracite Holdings LP"

# Filter to specific month
sable returns loss --month 2025-11

# Show last N days only
sable returns loss --days 30

# Show breakdown by entity/date
sable returns loss --breakdown

# Specify organization
sable returns loss --org 00000000-0000-0000-0000-000000000001

Output Example:

Returns Loss Function Results
==============================
Period: 2025-01-01 to 2026-01-13
Entities: 3
Data points: 782

Summary Metrics:
  Total Loss (L):  0.0847
  RMSE:           12.5 bps
  Max Diff (L∞):  61.22 bps
  Within 10 bps:  82.9%

Loss by Entity:
  Anthracite Holdings LP:        0.0523 (61.7%)
  Anthracite Realty Partners:    0.0289 (34.1%)
  Bird Family Foundation:        0.0035 (4.2%)

sable returns compare

Side-by-side comparison of Sable vs BTIG returns.

# Compare recent data
sable returns compare

# Compare specific entity
sable returns compare --entity "Anthracite Holdings LP"

# Compare specific month
sable returns compare --month 2025-11

# Filter by organization
sable returns compare --org <uuid>

Output Example:

Returns Comparison: Anthracite Holdings LP
==========================================

Date       | Sable    | BTIG     | Diff (bps)
-----------|----------|----------|------------
2026-01-13 | -0.26%   | -0.25%   | -1.0
2026-01-12 |  0.74%   |  0.73%   |  1.0
2026-01-11 | -0.14%   | -0.14%   |  0.0
...

Data Source

Both commands query gold.v_dietz_daily which contains:

• Daily returns calculated by Sable (Modified Dietz method)
• BTIG daily returns from sable.perf_daily_v2
• Pre-computed difference in basis points (daily_diff_bps)

Key Metrics

Metric	Formula	Target
Total Loss (L)	Σ(diff_bps/100)²	< 0.01
RMSE	√(L/n) × 100	< 10 bps
L∞ (max diff)	max(|diff_bps|)	< 50 bps
Within threshold	% of days ≤ 10 bps	> 90%

Implementation Details

File Location

sable-cli/sable.js - Functions:

• returnsLoss() - Main loss function logic
• returnsCompare() - Comparison table generator

Database Views Used

• gold.v_dietz_daily - Main data source with both Sable and BTIG returns
• sable.perf_daily_v2 - Raw BTIG performance data

Current Results (January 2026)

After implementing Modified Dietz v3:

Metric	Before	After	Improvement
Total Loss	3.93	0.085	98% ↓
Max Diff	148 bps	15 bps	90% ↓
Within 10 bps	45%	83%	38% ↑

Related

• Modified Dietz Method - Calculation methodology
• Epic 2: Method Configuration - Per-entity toggle
• Epic 3: Automated Reconciliation - Flagging system