docs/api_reqs.md

Documento de Especificaciones Técnicas: Munger Intelligence Engine API

Versión: 1.0
Tecnologías: Node.js, Next.js (App Router), TypeScript, yahoo-finance2
Despliegue: Hugging Face Spaces (Docker)

---

1. Resumen del Proyecto

El "Munger Intelligence Engine" es una API de análisis financiero diseñada para automatizar la estrategia de inversión de Charlie Munger: comprar empresas de "alta calidad" cuando cotizan cerca de su media móvil de 200 semanas (200-WMA). El sistema debe realizar descargas diarias, filtrar por capitalización de mercado y gestionar estados de señales en tiempo real.

---

2. Definición de la Watchlist e Ingesta de Datos

2.1 Segmentación por Capitalización (Market Cap)

El sistema debe ignorar cualquier activo que no cumpla con los umbrales de seguridad institucional:

• Elite Compounders (Mega Cap): > $100B. Empresas con fosos económicos globales.
• Blue Chips (Large Cap): > $10B. Estándar mínimo de liquidez y estabilidad para la estrategia.

2.2 Estrategia de Descarga Paralelizada (Batching)

Para optimizar el rendimiento y evitar bloqueos de IP/Rate Limiting de Yahoo Finance:

• Tamaño de Lote (Batch): 50 tickers por iteración.
• Concurrencia: Utilizar Promise.all para procesar los 50 tickers de cada lote simultáneamente.
• Frecuencia: Descarga diaria automatizada de quote y quoteSummary.

---

3. Lógica del Motor de Análisis (Munger Strategy)

Cada ticker debe ser evaluado bajo tres filtros secuenciales:

1. Filtro Fundamental (Calidad):
   • ROE (Return on Equity): > 15% (Mínimo), > 25% (Excelente).
   • Debt/Equity: < 50% (Mínimo), < 15% (Ideal).
2. Filtro Técnico (Valor):
   • 200-WMA: Media móvil simple de los últimos 200 cierres semanales.
   • Gatillo (Trigger): Precio Actual $\leq$ (200-WMA * 1.05).
3. Margen de Seguridad: Diferencia porcentual entre el Precio Actual y el Target Mean de analistas.

---

4. Gestión de Estados por Ticker

El sistema debe mantener un estado persistente para cada ticker en la base de datos o archivo de estado en Hugging Face:

Estado	Descripción
SCANNING	Iniciando descarga de datos de yahoo-finance2.
FILTERING	Validando Market Cap y métricas de calidad (ROE/Deuda).
TECHNICAL_EVAL	Calculando posición respecto a la 200-WMA.
SIGNAL_READY	Activo listo para compra o seguimiento activo.
ERROR	Fallo en la ingesta de datos o ticker no encontrado.

---

5. Especificación de Endpoints de la API

GET /api/v1/health

• Propósito: Monitorización del sistema y estado de las APIs externas.
• Response: JSON con status, last_sync_timestamp y api_latency.

POST /api/v1/sync

• Propósito: Disparador del ciclo de descarga diaria (vía Cron).
• Lógica: Ejecuta el procesamiento por lotes (50 tickers) usando Promise.all.
• Payload: { "force": boolean, "segments": ["mega", "large"] }.

GET /api/v1/signals

• Propósito: Listar oportunidades activas para el Dashboard.
• Filtros: Por sector, munger_score (0-100) y upside.
• Response: Array de objetos MungerStock.

GET /api/v1/ticker/:id

• Propósito: Deep Dive de un activo específico.
• Response: Detalle completo incluyendo quoteSummary, histórico de WMA y catalizadores fundamentales.

GET /api/v1/portfolio

• Propósito: Estado de las posiciones actuales en Alpaca (Paper Trading).
• Response: Equity total, P&L de posiciones y "Días de Disciplina" (tiempo sin trades impulsivos).

---

6. Despliegue en Hugging Face Spaces

• Docker Image: Base node:20-slim.
• Persistencia: Utilizar HF Datasets o R2 de Cloudflare para evitar pérdida de datos por reinicio del Space.
• Variables de Entorno: ALPACA_KEY, ALPACA_SECRET, HF_TOKEN.