Score de Riesgo de Cartera en Tiempo Real Riesgo de cartera y régimen de mercado con Hidden Markov

Sobre el Proyecto

Sistema de análisis y scoring de riesgo para carteras de inversión. Combina un GaussianHMM entrenado (Hidden Markov Model, 3 regímenes de mercado: Bull/Neutral/Bear) con análisis de correlaciones dinámicas entre activos para evaluar el riesgo real de una cartera en tiempo real con datos de Yahoo Finance.

Cómo medir la efectividad real del modelo

Para modelos financieros de gestión de riesgo, las métricas de clasificación (F1, MCC) son útiles pero no suficientes. Las métricas de backtest son las que importan en finanzas:

• Sharpe 2.12 vs. 1.11 (buy-and-hold): la estrategia HMM (estar largo solo en Bull/Neutral, fuera en Bear) genera el doble de rentabilidad por unidad de riesgo. Sharpe >2 es considerado excelente en gestión activa de carteras.
• CVaR reducido un 32%: el CVaR (Conditional Value at Risk) mide la pérdida media en los peores días. La estrategia HMM reduce la cola de riesgo un 32%: en las peores jornadas históricas, la pérdida esperada se reduce de -2.2% a -1.5% diario.
• Max Drawdown de -21.9% a -7.5%: el drawdown máximo mide la mayor caída desde máximos. El HMM pasa fuera del mercado en fases Bear, reduciendo la caída máxima en 14 puntos porcentuales.
• F1 Bear detection = 0.33, MCC = 0.18: el HMM es un modelo no supervisado — descubre patrones estadísticos latentes, no optimiza F1 directamente. La calidad del modelo se mide por su utilidad en backtest (Sharpe, CVaR) más que por F1 vs. una etiqueta arbitraria.

Arquitectura del Modelo

• GaussianHMM (3 estados): entrenado sobre 1.255 días reales de SPY (40%), IBEX35 (20%), EWP (15%), STOXX50E (15%), TLT (5%) y GLD (5%). Estados mapeados a Bull/Neutral/Bear según retorno medio de cada régimen.
• Features HMM (4): retorno diario log, volatilidad rolling 20 días, momentum 5 días, momentum 20 días.
• Regímenes detectados: Bear (-29% anual, alta vol), Neutral (+12% anual), Bull (+35% anual, baja vol).
• Risk Score (0-100): composición ponderada de volatilidad de cartera (50%), régimen HMM (30%) e índice de concentración HHI (20%).
• Métricas en tiempo real: VaR 95%, CVaR 95%, Sharpe, Sortino, Max Drawdown — calculados sobre datos reales de Yahoo Finance en cada análisis.

Datos y Fuentes

Precios históricos vía Yahoo Finance API (yfinance). 19 activos: Large-cap (AAPL, MSFT, NVDA...), ETFs (SPY, QQQ, GLD, TLT), Cripto (BTC, ETH) y Materias Primas. Datos actualizados en cada petición.

Stack Técnico

Python 3.12 · hmmlearn · NumPy · Pandas · yfinance · FastAPI · scikit-learn · joblib · Laravel (proxy HTTP)

Integración, datos y licencia

• Integración: API REST propia (FastAPI) con 3 endpoints documentados en el repositorio; se puede consumir desde cualquier lenguaje o plataforma, con especificación OpenAPI autogenerada.
• Tratamiento de datos: el procesamiento se realiza íntegramente en el servidor del proyecto, sin enviar datos a servicios de IA de terceros. No se almacenan las consultas de la demo.
• Nota: Proyecto educativo de análisis de riesgo: no constituye asesoramiento financiero.
• Licencia: MIT — uso libre, incluido comercial, manteniendo el aviso de copyright. El repositorio contiene la aplicación completa y puede desplegarse en infraestructura propia. El código es gratuito; los costes de motor de IA, infraestructura, implantación y mantenimiento corren por cuenta de quien lo despliega (no se ofrece soporte ni consultoría).

¿Cómo lo integro?

Disponible ahora: POST /analyse con la composición de la cartera devuelve su score de riesgo.

Integraciones habituales en este sector (valoradas como vía recomendada; salvo que se indique lo contrario, no vienen implementadas — el código está preparado para añadirlas):

• Agregación bancaria (PSD2 / Open Banking): leer la cartera real del usuario desde su banco con su consentimiento, en vez de que la introduzca a mano. Es la integración que más cambia la experiencia.
• APIs de bróker (MyInvestor, Alpaca, IBKR): misma idea a nivel de cartera de inversión.
• Excel / CSV: el analista financiero medio trabaja así: la carga masiva desde hoja de cálculo es la integración más usada en la práctica.