398 lines
20 KiB
Python
398 lines
20 KiB
Python
"""
|
|
Instrument-level "Curve Regime" — distinct from the global macro regime
|
|
(services.data_fetcher.score_macro_scenarios / snapshot.macro_regime, one dominant
|
|
scenario for the whole market). This classifies a SINGLE instrument's current price/vol
|
|
state into one of 15 canonical regimes (spec below, provided by the user as an analyst
|
|
reference table), combining:
|
|
|
|
- direction / dynamique: from the instrument's wavelet decomposition — the SAME cache
|
|
services.wavelet_signals writes and the Wavelet tab reads (services.database.
|
|
get_wavelet_decomposition_cache), so this tab can never disagree with the Wavelet tab
|
|
it sits next to — plus the trend/regime signals instrument_service already computes
|
|
(ATR ratio, momentum, MA slopes) for confirmation.
|
|
- volatilite: realized-vol level (ATR vs its own 3-month average) + the direction that
|
|
level has been moving in over the last ~10 sessions (rising/falling fast).
|
|
- structure_iv / liquidite: Saxo options IV/skew/term-structure (services.saxo_iv_engine),
|
|
only when this instrument has a saxo_option_symbol linked (Config -> Instruments
|
|
Watchlist -> "Option") — otherwise both axes are "n/a" and excluded from scoring
|
|
rather than guessed at. Only a single 25-delta skew point + term-structure shape exist
|
|
today (see saxo_iv_engine.py), not a full smile/butterfly curve — so structure_iv only
|
|
distinguishes flat / skew_put / skew_put_fort / degraded, not the finer smile/BF/RR
|
|
categories some regime rows reference; those regimes fall back to their other axes.
|
|
- facteur_dominant: the global macro regime's asset-class bias (already computed per
|
|
snapshot) — shown alongside the match for context, NOT used as a hard scoring
|
|
criterion, since instrument category -> macro asset-class is an approximate mapping.
|
|
|
|
Cross-asset correlation (the spec table's "Corrélation cross-actifs" column) has no
|
|
existing data source anywhere in this codebase (checked: only a portfolio-scoped pairwise
|
|
correlation exists, for the Risk radar) — always "n/a" here, not scored. A real version
|
|
would need a new rolling-correlation-vs-benchmark fetch; flagged as a known gap rather than
|
|
approximated.
|
|
|
|
This is a transparent rule-based scorer, not a black box: classify_instrument_regime()
|
|
returns every candidate regime's per-axis score breakdown, not just the winner, so a wrong
|
|
call is inspectable and the thresholds/weights can be tuned without re-deriving the whole
|
|
design.
|
|
"""
|
|
import logging
|
|
from typing import Any, Dict, List, Optional
|
|
|
|
logger = logging.getLogger(__name__)
|
|
|
|
# ── Regime reference table (digitized from the user-provided spec) ────────────────────
|
|
# Each entry's axis values are what THAT regime expects to see. `None` means "this axis
|
|
# doesn't discriminate this regime" (not scored against it). volatilite accepts either a
|
|
# level bucket (faible/moyenne/elevee/tres_elevee/explosive) or a trend word
|
|
# (hausse/baisse_rapide) — matched against the corresponding computed signal, see
|
|
# _score_regime() below.
|
|
REGIME_SPECS: List[Dict[str, Any]] = [
|
|
{"key": "bull_trend", "label": "Bull Trend",
|
|
"direction": "up", "dynamique": "progressive", "volatilite": "faible", "structure_iv": "flat",
|
|
"facteur_dominant": "Croissance / BCE",
|
|
"declencheurs": "BCE plus hawkish que Fed, croissance Europe",
|
|
"strategies": "Bull Call Spread, Bull Put Spread", "exemple": "+120 pips, IV stable → +60 à 90%"},
|
|
{"key": "bear_trend", "label": "Bear Trend",
|
|
"direction": "down", "dynamique": "progressive", "volatilite": "faible", "structure_iv": "skew_put",
|
|
"facteur_dominant": "USD / Diff. de taux",
|
|
"declencheurs": "Fed hawkish, différentiel de taux",
|
|
"strategies": "Bear Put Spread", "exemple": "-120 pips → +60 à 90%"},
|
|
{"key": "bull_breakout", "label": "Bull Breakout",
|
|
"direction": "up", "dynamique": "explosive", "volatilite": "elevee", "structure_iv": "smile",
|
|
"facteur_dominant": "Événement",
|
|
"declencheurs": "BCE surprise, cassure technique",
|
|
"strategies": "Long Call, Call Backspread", "exemple": "+150 à 250%"},
|
|
{"key": "bear_breakout", "label": "Bear Breakout",
|
|
"direction": "down", "dynamique": "explosive", "volatilite": "elevee", "structure_iv": "skew_put_fort",
|
|
"facteur_dominant": "Événement",
|
|
"declencheurs": "Fed surprise, cassure, crise localisée",
|
|
"strategies": "Long Put, Put Backspread", "exemple": "+150 à 250%"},
|
|
{"key": "compression", "label": "Compression",
|
|
"direction": "flat", "dynamique": "progressive", "volatilite": "faible", "structure_iv": "flat",
|
|
"facteur_dominant": "Attente",
|
|
"declencheurs": "Vacances, avant FOMC/BCE",
|
|
"strategies": "Calendar, Gamma positif", "exemple": "Préparer une cassure"},
|
|
{"key": "iv_crush", "label": "IV Crush",
|
|
"direction": "flat", "dynamique": "progressive", "volatilite": "tres_elevee", "structure_iv": "flat",
|
|
"facteur_dominant": "Décroissance du risque",
|
|
"declencheurs": "Après BCE/Fed/NFP sans surprise",
|
|
"strategies": "Iron Condor, Butterfly", "exemple": "+30 à 70%"},
|
|
{"key": "whipsaw", "label": "Whipsaw",
|
|
"direction": "flat", "dynamique": "chaotique", "volatilite": "elevee", "structure_iv": "smile",
|
|
"facteur_dominant": "Flux contradictoires",
|
|
"declencheurs": "Faux breakouts, marché sans conviction",
|
|
"strategies": "Petite taille, Gamma contrôlé", "exemple": "Peu de stratégies robustes"},
|
|
{"key": "stress_prolonge", "label": "Stress prolongé",
|
|
"direction": "mixed", "dynamique": "progressive", "volatilite": "elevee", "structure_iv": "skew_put",
|
|
"facteur_dominant": "Inflation / Taux / EM",
|
|
"declencheurs": "Brexit, crise EM, inflation durable",
|
|
"strategies": "Calendar directionnel, Diagonal", "exemple": "+40 à 80%"},
|
|
{"key": "explosion_incertitude", "label": "Explosion d'incertitude",
|
|
"direction": "mixed", "dynamique": "explosive", "volatilite": "explosive", "structure_iv": "skew_put_fort",
|
|
"facteur_dominant": "Géopolitique / Banque centrale",
|
|
"declencheurs": "Guerre, surprise extrême, banques",
|
|
"strategies": "Long Straddle, Reverse Iron Condor", "exemple": "IV 5→8 : +50 à 120%"},
|
|
{"key": "flash_crash", "label": "Flash Crash / Crise de liquidité",
|
|
"direction": "mixed", "dynamique": "explosive", "volatilite": "explosive", "structure_iv": "degradee",
|
|
"facteur_dominant": "Déleveraging",
|
|
"declencheurs": "Vente forcée, défaut, crise systémique",
|
|
"strategies": "Hedges existants uniquement", "exemple": "Priorité = survie et exécution"},
|
|
{"key": "retour_normale", "label": "Retour à la normale",
|
|
"direction": "flat", "dynamique": "progressive", "volatilite": "baisse_rapide", "structure_iv": "flat",
|
|
"facteur_dominant": "Dissipation du risque",
|
|
"declencheurs": "Cessez-le-feu, marché rassuré",
|
|
"strategies": "Vente Vega", "exemple": "+40 à 80%"},
|
|
{"key": "transition_regime", "label": "Transition de régime",
|
|
"direction": "mixed", "dynamique": "accelere", "volatilite": "hausse", "structure_iv": "skew_put",
|
|
"facteur_dominant": "Changement macro",
|
|
"declencheurs": "Brent, COT, Fed/BCE changent progressivement",
|
|
"strategies": "Calendar, Diagonal, structures hybrides", "exemple": "+40 à 90%"},
|
|
{"key": "risk_on", "label": "Risk-On",
|
|
"direction": "up", "dynamique": "progressive", "volatilite": "faible", "structure_iv": "flat",
|
|
"facteur_dominant": "Sentiment",
|
|
"declencheurs": "QE, détente géopolitique",
|
|
"strategies": "Bull Spread", "exemple": "+50 à 80%"},
|
|
{"key": "risk_off", "label": "Risk-Off",
|
|
"direction": "down", "dynamique": "accelere", "volatilite": "elevee", "structure_iv": "skew_put",
|
|
"facteur_dominant": "Sentiment",
|
|
"declencheurs": "Flight to Quality",
|
|
"strategies": "Bear Put, Long Put", "exemple": "+70 à 150%"},
|
|
{"key": "dispersion", "label": "Dispersion / Décorrélation",
|
|
"direction": "mixed", "dynamique": "variable", "volatilite": "moyenne", "structure_iv": None,
|
|
"facteur_dominant": "Rotation sectorielle",
|
|
"declencheurs": "Corrélations qui cassent",
|
|
"strategies": "Paniers, dispersion, relative value",
|
|
"exemple": "Plus adapté au multi-actifs qu'au single instrument"},
|
|
]
|
|
|
|
# Per-axis scoring weight — direction/dynamique/volatilite are the axes we can compute with
|
|
# real confidence (wavelets + price data, always available); structure_iv only weighs in
|
|
# when options data exists, so it's naturally excluded (not zero-penalized) otherwise.
|
|
_AXIS_WEIGHTS = {"direction": 3.0, "dynamique": 2.5, "volatilite": 2.0, "structure_iv": 1.5}
|
|
|
|
|
|
# ── Axis 1+2: direction & dynamique, from the wavelet cache + trend/regime signals ─────
|
|
|
|
def _wavelet_band_slopes(decomposition: Optional[Dict]) -> List[float]:
|
|
"""Last-point slope of each band's series (today vs yesterday) — same math as
|
|
services.wavelet_signals._compute_slope, applied directly to whatever's already in the
|
|
cached decomposition rather than recomputing anything."""
|
|
if not decomposition:
|
|
return []
|
|
bands = decomposition.get("bands") or []
|
|
slopes = []
|
|
for band in bands:
|
|
series = band.get("series") or []
|
|
if len(series) >= 2 and series[-1] is not None and series[-2] is not None:
|
|
slopes.append(float(series[-1]) - float(series[-2]))
|
|
return slopes
|
|
|
|
|
|
def _axis_direction(trend: Dict, regime_signals: Dict, wavelet_slopes: List[float]) -> str:
|
|
"""'up'/'down' on a clear, consistent trend; 'flat' when momentum is negligible;
|
|
'mixed' when the fast (wavelet) and slow (momentum/MA) signals disagree — that
|
|
disagreement IS the "?"/"↑ ou ↓" state several regimes in the spec are built around
|
|
(stress prolongé, explosion d'incertitude, transition, flash crash)."""
|
|
mom = trend.get("momentum_1m_pct")
|
|
ma_above = regime_signals.get("ma50_above_ma200")
|
|
if mom is None:
|
|
return "flat"
|
|
slow_dir = "up" if mom > 1.0 else "down" if mom < -1.0 else "flat"
|
|
if wavelet_slopes:
|
|
up_count = sum(1 for s in wavelet_slopes if s > 0)
|
|
down_count = sum(1 for s in wavelet_slopes if s < 0)
|
|
fast_dir = "up" if up_count > down_count else "down" if down_count > up_count else "flat"
|
|
if slow_dir != "flat" and fast_dir != "flat" and slow_dir != fast_dir:
|
|
return "mixed"
|
|
if slow_dir == "flat":
|
|
return "flat"
|
|
if ma_above is not None:
|
|
# MA50/MA200 disagreeing with recent momentum direction = the trend is stalling/
|
|
# reversing under the surface, not a clean trend — treat as mixed too.
|
|
ma_dir = "up" if ma_above else "down"
|
|
if ma_dir != slow_dir:
|
|
return "mixed"
|
|
return slow_dir
|
|
|
|
|
|
def _axis_dynamique(trend: Dict, regime_signals: Dict, wavelet_slopes: List[float]) -> str:
|
|
"""progressive (steady) / explosive (sharp acceleration) / chaotique (bands
|
|
disagreeing on direction) / accelere (momentum building) / variable (bands agree on
|
|
neither direction nor magnitude — dispersion-like)."""
|
|
vol_ratio = regime_signals.get("vol_ratio_pct")
|
|
mom_1m = trend.get("momentum_1m_pct")
|
|
mom_3m = trend.get("momentum_3m_pct")
|
|
|
|
if wavelet_slopes and len(wavelet_slopes) >= 2:
|
|
signs = [1 if s > 0 else -1 if s < 0 else 0 for s in wavelet_slopes]
|
|
disagreement = len(set(signs)) > 1 and 0 not in signs # genuine split, not just noise near zero
|
|
else:
|
|
disagreement = False
|
|
|
|
if vol_ratio is not None and vol_ratio > 180:
|
|
return "explosive"
|
|
if disagreement and vol_ratio is not None and vol_ratio > 110:
|
|
return "chaotique"
|
|
if disagreement:
|
|
return "variable"
|
|
if mom_1m is not None and mom_3m is not None and mom_3m != 0:
|
|
# This month's pace vs the trailing 3-month pace — accelerating if 1m alone is
|
|
# already running hotter than the average of the last 3.
|
|
monthly_avg_3m = mom_3m / 3
|
|
if abs(mom_1m) > abs(monthly_avg_3m) * 1.8 and abs(mom_1m) > 3:
|
|
return "accelere"
|
|
return "progressive"
|
|
|
|
|
|
# ── Axis 3: volatilite level + trend, from ATR ratio + the realized-vol series ─────────
|
|
|
|
def _axis_volatilite(trend: Dict, regime_signals: Dict, vol_series: List[Dict]) -> Dict[str, Optional[str]]:
|
|
"""Returns {"level": ..., "trend": ...} — level is the primary bucket regimes are
|
|
matched against; trend (hausse/baisse_rapide/stable) only matters for the couple of
|
|
regimes defined by a MOVE in vol rather than its absolute level (Retour à la normale,
|
|
Transition de régime)."""
|
|
vol_ratio = regime_signals.get("vol_ratio_pct") # ATR14 / its own 3-month average, %
|
|
level = None
|
|
if vol_ratio is not None:
|
|
if vol_ratio > 200:
|
|
level = "explosive"
|
|
elif vol_ratio > 160:
|
|
level = "tres_elevee"
|
|
elif vol_ratio > 115:
|
|
level = "elevee"
|
|
elif vol_ratio >= 85:
|
|
level = "moyenne"
|
|
else:
|
|
level = "faible"
|
|
|
|
trend_word = None
|
|
values = [p.get("value") for p in (vol_series or []) if p.get("value") is not None]
|
|
if len(values) >= 10:
|
|
recent = values[-1]
|
|
baseline = sum(values[-10:-3]) / len(values[-10:-3]) if len(values[-10:-3]) else None
|
|
if baseline and baseline > 0:
|
|
change_pct = (recent - baseline) / baseline * 100
|
|
if change_pct <= -25:
|
|
trend_word = "baisse_rapide"
|
|
elif change_pct >= 30:
|
|
trend_word = "hausse"
|
|
else:
|
|
trend_word = "stable"
|
|
return {"level": level, "trend": trend_word}
|
|
|
|
|
|
# ── Axis 4+5: structure_iv / liquidite, from Saxo options data when linked ─────────────
|
|
|
|
def _axis_options(watchlist_row: Optional[Dict]) -> Dict[str, Any]:
|
|
"""None when this instrument has no saxo_option_symbol link — the caller excludes
|
|
structure_iv from scoring entirely in that case rather than defaulting to 'flat'."""
|
|
if not watchlist_row or not watchlist_row.get("saxo_option_symbol"):
|
|
return {"structure_iv": None, "liquidite": None, "iv_snapshot": None}
|
|
try:
|
|
from services.saxo_iv_engine import get_saxo_iv_snapshot
|
|
snap = get_saxo_iv_snapshot(watchlist_row["saxo_option_symbol"])
|
|
except Exception as e:
|
|
logger.warning(f"[curve_regime] IV snapshot failed for '{watchlist_row.get('saxo_option_symbol')}': {e}")
|
|
return {"structure_iv": None, "liquidite": None, "iv_snapshot": None}
|
|
|
|
if snap.get("iv_current_pct") is None:
|
|
# No usable Saxo option data at all (empty/stale chain) — this itself is the
|
|
# "surface cassée" signal, not just an absent one.
|
|
return {"structure_iv": "degradee", "liquidite": "degradee", "iv_snapshot": snap}
|
|
|
|
skew_pct = (snap.get("skew") or {}).get("skew_pct")
|
|
structure_iv = "flat"
|
|
if skew_pct is not None:
|
|
if skew_pct > 4:
|
|
structure_iv = "skew_put_fort"
|
|
elif skew_pct > 1.2:
|
|
structure_iv = "skew_put"
|
|
elif skew_pct < -1.2:
|
|
structure_iv = "smile" # calls bid up relative to puts — treated as the closest bucket we can score
|
|
|
|
liquidite = "faible" if (snap.get("history_days") or 0) < 5 else "normal"
|
|
|
|
return {"structure_iv": structure_iv, "liquidite": liquidite, "iv_snapshot": snap}
|
|
|
|
|
|
# ── Scoring ──────────────────────────────────────────────────────────────────────────
|
|
|
|
def _score_regime(spec: Dict, profile: Dict) -> Dict[str, Any]:
|
|
axis_hits: Dict[str, bool] = {}
|
|
total_weight = 0.0
|
|
earned = 0.0
|
|
|
|
for axis in ("direction", "dynamique"):
|
|
expected = spec.get(axis)
|
|
observed = profile.get(axis)
|
|
if expected is None or observed is None:
|
|
continue
|
|
w = _AXIS_WEIGHTS[axis]
|
|
total_weight += w
|
|
hit = observed == expected
|
|
if hit:
|
|
earned += w
|
|
axis_hits[axis] = hit
|
|
|
|
# volatilite: match level OR trend, whichever the spec entry is actually about
|
|
expected_vol = spec.get("volatilite")
|
|
vol = profile.get("volatilite") or {}
|
|
if expected_vol is not None:
|
|
w = _AXIS_WEIGHTS["volatilite"]
|
|
total_weight += w
|
|
observed_vol = vol.get("trend") if expected_vol in ("hausse", "baisse_rapide") else vol.get("level")
|
|
hit = observed_vol == expected_vol
|
|
if hit:
|
|
earned += w
|
|
axis_hits["volatilite"] = hit
|
|
|
|
expected_iv = spec.get("structure_iv")
|
|
observed_iv = profile.get("structure_iv")
|
|
if expected_iv is not None and observed_iv is not None:
|
|
w = _AXIS_WEIGHTS["structure_iv"]
|
|
total_weight += w
|
|
hit = observed_iv == expected_iv
|
|
if hit:
|
|
earned += w
|
|
axis_hits["structure_iv"] = hit
|
|
|
|
score = (earned / total_weight) if total_weight > 0 else 0.0
|
|
return {"key": spec["key"], "label": spec["label"], "score": round(score, 3), "axis_hits": axis_hits}
|
|
|
|
|
|
def classify_instrument_regime(instrument_id: str, snapshot: Dict) -> Dict[str, Any]:
|
|
"""Main entry point — called by routers/instruments.py with the already-built snapshot
|
|
(indicators/regime/trend/macro_regime) so this doesn't refetch price history a second
|
|
time. Returns the top match, full ranked scores, the computed axis profile (for the UI
|
|
to show its work), and the matched regime's reference info (déclencheurs/stratégies)."""
|
|
from services.instrument_service import resolve_watchlist_ticker
|
|
from services.database import get_wavelet_decomposition_cache, get_instruments_watchlist
|
|
|
|
watchlist_ticker = resolve_watchlist_ticker(instrument_id)
|
|
cached = get_wavelet_decomposition_cache(watchlist_ticker)
|
|
decomposition = cached.get("decomposition") if cached else None
|
|
wavelet_slopes = _wavelet_band_slopes(decomposition)
|
|
|
|
watchlist_row = next(
|
|
(r for r in get_instruments_watchlist() if r["ticker"].upper() == watchlist_ticker.upper()), None
|
|
)
|
|
|
|
regime_signals = (snapshot.get("regime") or {}).get("signals") or {}
|
|
trend = snapshot.get("trend") or {}
|
|
vol_series = (snapshot.get("indicators") or {}).get("volatility") or []
|
|
|
|
direction = _axis_direction(trend, regime_signals, wavelet_slopes)
|
|
dynamique = _axis_dynamique(trend, regime_signals, wavelet_slopes)
|
|
volatilite = _axis_volatilite(trend, regime_signals, vol_series)
|
|
options_axes = _axis_options(watchlist_row)
|
|
|
|
profile = {
|
|
"direction": direction,
|
|
"dynamique": dynamique,
|
|
"volatilite": volatilite,
|
|
"structure_iv": options_axes["structure_iv"],
|
|
"liquidite": options_axes["liquidite"],
|
|
"correlation": None, # no data source — always n/a, see module docstring
|
|
}
|
|
|
|
scored = sorted(
|
|
(_score_regime(spec, profile) for spec in REGIME_SPECS),
|
|
key=lambda s: -s["score"],
|
|
)
|
|
top = scored[0] if scored else None
|
|
top_spec = next((s for s in REGIME_SPECS if s["key"] == (top or {}).get("key")), None)
|
|
|
|
macro_regime = snapshot.get("macro_regime") or {}
|
|
config_category = (snapshot.get("instrument") or {}).get("category")
|
|
facteur_dominant_bias = _macro_bias_for_category(macro_regime.get("asset_bias") or {}, config_category)
|
|
|
|
return {
|
|
"instrument_id": instrument_id,
|
|
"watchlist_ticker": watchlist_ticker,
|
|
"profile": profile,
|
|
"top_match": {
|
|
"key": top_spec["key"], "label": top_spec["label"], "score": top["score"],
|
|
"axis_hits": top["axis_hits"],
|
|
"facteur_dominant_ref": top_spec["facteur_dominant"],
|
|
"declencheurs": top_spec["declencheurs"],
|
|
"strategies": top_spec["strategies"],
|
|
"exemple": top_spec["exemple"],
|
|
} if top_spec else None,
|
|
"ranked": scored,
|
|
"macro_regime_label": macro_regime.get("label"),
|
|
"facteur_dominant_bias": facteur_dominant_bias,
|
|
"iv_snapshot": options_axes.get("iv_snapshot"),
|
|
"has_options_data": options_axes["structure_iv"] is not None,
|
|
}
|
|
|
|
|
|
# instruments.json's own category vocabulary -> macro asset_bias's asset-class keys
|
|
_CATEGORY_TO_ASSET_BIAS_KEY = {
|
|
"fx": "forex", "energy": "energy", "metal": "metals",
|
|
"equity_index": "indices", "equity_intl": "indices", "stock": "equities",
|
|
}
|
|
|
|
|
|
def _macro_bias_for_category(asset_bias: Dict[str, str], category: Optional[str]) -> Optional[str]:
|
|
key = _CATEGORY_TO_ASSET_BIAS_KEY.get(category or "")
|
|
return asset_bias.get(key) if key else None
|