backend/app/api/methodology.py

"""Methodology endpoint — machine-readable description of our pricing + confidence rules."""
from __future__ import annotations

from fastapi import APIRouter

from app.services.confidence.engine import DRIVER_WEIGHTS

router = APIRouter()


@router.get("")
def methodology() -> dict:
    return {
        "pricing_waterfall": [
            {
                "rank": 1,
                "method": "TRADE_ANCHORED",
                "when": "Recent TRACE print within 48h and ≥3 trades in 30d.",
                "note": "Evaluated yield is inverted from the anchor price.",
            },
            {
                "rank": 2,
                "method": "MATRIX",
                "when": "No recent anchor; peer universe provides ≥1 comparable.",
                "note": "G-spread = similarity-weighted median of peer g-spreads; price from curve + spread.",
            },
        ],
        "curve": {
            "type": "Treasury (piecewise-linear in yield over tenor)",
            "benchmark_snap": [2, 3, 5, 7, 10, 20, 30],
        },
        "confidence": {
            "weights": DRIVER_WEIGHTS,
            "label_thresholds": {"High": ">=7.5", "Medium": "4.5-7.4", "Low": "<4.5"},
        },
        "anomaly_rules": [
            "|Δprice| > 5% 1d not explained by rates",
            "spread > 2× sector median and not news-justified",
            "|target spread − issuer median| > 40 bps",
        ],
        "data_limits": [
            "TRACE prints are public-disseminated with volume caps; not execution-quality.",
            "News/filings are best-effort public ingestion; missing headlines are possible.",
            "No Bloomberg / ICE / MarketAxess / Tradeweb data is used.",
        ],
    }