Clawdfolio

¿Qué hace Clawdfolio?

Kit de herramientas cuantitativas para portafolios destinado a inversores profesionales. Agregación multi-broker (Longport, Moomoo/Futu, demo), análisis de riesgo institucional, gestión del ciclo de vida de estrategias de opciones, más de 20 flujos de trabajo financieros automatizados y exportación de datos CSV/JSON.

PyPI: pip install clawdfolio · Repo: https://github.com/YichengYang-Ethan/clawdfolio · Python >= 3.10 (probado 3.10–3.13)

Consulta API.md para la referencia completa de la API Python y CONFIG.md para configuración, variables de entorno, configuración de brokers y detalles de monitoreo.

---

Comandos CLI

Todos los comandos admiten --broker {longport,futu,demo,all}, --output {console,json} y --config RUTA.

Portafolio

clawdfolio summary              # Resumen del portafolio (comando predeterminado)
clawdfolio summary --top 20     # Mostrar las 20 principales tenencias
clawdfolio quotes AAPL MSFT     # Cotizaciones en tiempo real
clawdfolio alerts               # Alertas de precio/RSI/PnL/concentración
clawdfolio alerts --severity critical

Análisis de Riesgo

clawdfolio risk                 # Volatilidad, Beta, Sharpe, Sortino, VaR, CVaR, drawdown
clawdfolio risk --detailed      # + Extremos RSI, concentración, exposición sectorial, RSI del portafolio

Métricas de riesgo calculadas:

• Volatilidad: 20d, 60d, anualizada
• Beta: vs SPY, vs QQQ
• Ratio Sharpe: anualizada, exceso de rendimiento / volatilidad total
• Ratio Sortino: anualizada, exceso de rendimiento / solo volatilidad negativa
• VaR: 95% y 99% (histórico), absoluto y porcentual
• CVaR / Déficit Esperado: 95% y 99% — riesgo de cola más allá del VaR
• Drawdown Máximo: histórico y actual
• HHI: Índice de concentración Herfindahl-Hirschman
• RSI: RSI de 14 días a nivel de portafolio
• Correlación: detección de pares con alta correlación (>= 0.8)

Ganancias

clawdfolio earnings             # Próximas ganancias (predeterminado 14 días)
clawdfolio earnings --days 30   # Vista de 30 días

DCA (Promedio de Costo en Dólares)

clawdfolio dca                  # Señales DCA para el portafolio (rebalanceo + detección de caídas)
clawdfolio dca AAPL --months 12 --amount 1000   # Backtest histórico DCA

Tipos de señales: REGULAR (programada), DIP (caída de precio desde máximo reciente), REBALANCE (desviación de peso respecto al objetivo).

Exportación

clawdfolio export portfolio                  # CSV a salida estándar
clawdfolio export portfolio --format json    # JSON a salida estándar
clawdfolio export risk --file risk.csv       # Métricas de riesgo a archivo
clawdfolio export alerts --format json --file alerts.json

Objetivos de exportación: portfolio, risk, alerts. Formatos: csv, json.

Opciones

clawdfolio options expiries TQQQ
clawdfolio options chain TQQQ --expiry 2026-03-21 --side calls --limit 10
clawdfolio options quote TQQQ --expiry 2026-03-21 --strike 80 --type C
clawdfolio options buyback          # Verificar disparadores de recompra desde la configuración
clawdfolio options buyback --strict # Código de salida 1 si no se activa ningún objetivo

Flujos de Trabajo Financieros

20 flujos de trabajo incluidos en 7 categorías. Secuencia de configuración validada:

1. Verificar conectividad del broker: clawdfolio summary --broker demo (debería mostrar 10 posiciones demo)
2. Inicializar espacio de trabajo: clawdfolio finance init luego verificar con ls ~/.clawdfolio/finance
3. Listar flujos de trabajo disponibles: clawdfolio finance list
4. Ejecutar un flujo de trabajo: clawdfolio finance run portfolio_daily_brief_tg
5. Verificar salida: añade --output json para resultados legibles por máquina; en caso de error, reintenta con --broker demo para aislar problemas entre broker y flujo de trabajo

clawdfolio finance list --category alerts_monitors  # Filtrar por categoría
clawdfolio finance run dca_proposal_tg -- --budget 5000  # Pasar argumentos adicionales

Categorías: portfolio_reports, briefing_cards, alerts_monitors, market_intel, broker_snapshots, strategy, security.

Flujos de trabajo clave:

ID	Descripción
portfolio_report	Informe diario del portafolio con rendimiento, riesgo y tenencias
portfolio_daily_brief_tg	Tarjeta de resumen diario amigable para Telegram
portfolio_alert_monitor	Alertas deduplicadas de RSI/PnL/concentración/movimiento
option_buyback_monitor	Monitor de disparadores de recompra de opciones con estado
earnings_calendar	Próximas ganancias para las tenencias actuales
dca_proposal_tg	Tarjeta de propuesta DCA con restricción presupuestaria
account_report	Instantánea combinada de Longport + moomoo

Espacio de trabajo: ~/.clawdfolio/finance (configurable con --workspace).

---

Instalación

pip install clawdfolio               # Núcleo (yfinance + broker demo)
pip install clawdfolio[longport]     # + Broker Longport
pip install clawdfolio[futu]         # + Broker Moomoo/Futu
pip install clawdfolio[all]          # Todos los brokers
pip install clawdfolio[dev]          # + pytest, mypy, ruff (desarrollo)

---

API Python

Importaciones clave para uso programático:

from clawdfolio import Symbol, Position, Quote, Portfolio, RiskMetrics, Alert
from clawdfolio.brokers import get_broker
from clawdfolio.analysis.risk import analyze_risk
from clawdfolio.analysis.technical import calculate_rsi, calculate_macd
from clawdfolio.market import get_price, get_history, is_market_open
from clawdfolio.strategies.dca import DCAStrategy, calculate_dca_performance
from clawdfolio.output import export_portfolio_csv, export_risk_json

Consulta API.md para la referencia completa de la API con ejemplos de uso.

---

Configuración

Orden de búsqueda: bandera --config > variable de entorno CLAWDFOLIO_CONFIG > ./config.yaml > ~/.config/clawdfolio/config.yaml. Admite YAML y JSON.

Brokers compatibles: Longport (variables de entorno), Moomoo/Futu (OpenD local), Demo (integrado), Agregador (fusión multi-broker).

Consulta CONFIG.md para la referencia completa de configuración, variables de entorno, configuración de brokers y detalles de monitoreo.