🎲 Optimizador de Bingo Chileno

Sistema de optimización para selección inteligente de cartones de bingo que maximiza las probabilidades de ganar mediante análisis combinatorio y scoring avanzado.

🎯 Características

• ✅ Generación de cartones válidos según reglas chilenas
• ✅ Sistema de scoring delta para medir valor incremental de cartones
• ✅ Algoritmos de selección (greedy y genético)
• ✅ Simulación Monte Carlo para validar estrategias
• ✅ Análisis ROI con múltiples modalidades de juego
• ✅ Interfaz por consola clara y colorida

📋 Reglas del Bingo Chileno

Estructura del Cartón

• Matriz 5×5 con 24 números + centro vacío
• Rangos por columna:
  • B (azul): 1-15
  • I (rojo): 16-30
  • N (blanco): 31-45 (4 números + centro vacío)
  • G (verde): 46-60
  • O (amarillo): 61-75

Modalidades Soportadas

• Línea: Horizontal, vertical o diagonal
• Letras: T, L, O, X
• Cartón completo: Todos los 24 números
• Patrones personalizados

🚀 Instalación

Requisitos

• Python 3.10 o superior
• pip

Pasos

1. Clonar el repositorio

git clone https://github.com/tu-usuario/bingo-optimizer.git
cd bingo-optimizer

2. Crear entorno virtual (recomendado)

python -m venv venv
source venv/bin/activate  # Linux/Mac
# o
venv\Scripts\activate  # Windows

3. Instalar dependencias

pip install -r requirements.txt

4. Verificar instalación

python -m pytest tests/ -v

💻 Uso Rápido

Generar un cartón aleatorio

from core.carton import generar_carton_aleatorio

# Generar cartón
carton = generar_carton_aleatorio()

# Visualizar
print(carton.visualizar())

# Verificar validez
assert carton.es_valido()
print(f"Números: {sorted(carton.numeros)}")

Salida:

┌────┬────┬────┬────┬────┐
│ B  │ I  │ N  │ G  │ O  │
├────┼────┼────┼────┼────┤
│ 03 │ 22 │ 31 │ 52 │ 61 │
│ 07 │ 18 │ 39 │ 46 │ 68 │
│ 12 │ 29 │ XX │ 55 │ 73 │
│ 01 │ 25 │ 44 │ 48 │ 70 │
│ 15 │ 16 │ 33 │ 60 │ 64 │
└────┴────┴────┴────┴────┘

Ejecutar programa principal

python main.py

📁 Estructura del Proyecto

bingo-optimizer/
├── core/                 # Componentes fundamentales
│   ├── carton.py        # Clase Carton y generación
│   ├── conjunto.py      # Gestión de conjuntos
│   └── patrones.py      # Definición de patrones
├── scoring/             # Sistema de evaluación
│   ├── evaluador.py     # Cálculo del delta score
│   └── cobertura.py     # Análisis de cobertura
├── optimizacion/        # Algoritmos de selección
│   ├── greedy.py        # Algoritmo greedy
│   └── genetico.py      # Algoritmo genético
├── simulacion/          # Validación
│   ├── juego.py         # Simulador de partidas
│   └── monte_carlo.py   # Experimentos masivos
├── ui/                  # Interfaz
│   └── consola.py       # CLI
├── tests/               # Tests unitarios
├── docs/                # Documentación
├── config/              # Configuración
└── main.py             # Punto de entrada

🧪 Tests

Ejecutar todos los tests:

pytest tests/ -v

Ejecutar tests con cobertura:

pytest tests/ --cov=core --cov=scoring --cov-report=html

Ver reporte de cobertura:

open htmlcov/index.html  # Mac/Linux
# o
start htmlcov/index.html  # Windows

📊 Ejemplos

Ejemplo 1: Validar un cartón

import numpy as np
from core.carton import Carton

matriz = np.array([
    [1,  16, 31, 46, 61],
    [2,  17, 32, 47, 62],
    [3,  18,  0, 48, 63],
    [4,  19, 34, 49, 64],
    [5,  20, 35, 50, 65]
])

carton = Carton(matriz)
print(f"¿Es válido? {carton.es_valido()}")

Ejemplo 2: Generar desde lista

from core.carton import generar_carton_desde_lista

numeros = [
    1, 2, 3, 4, 5,           # B
    16, 17, 18, 19, 20,      # I
    31, 32, 34, 35,          # N (4 números)
    46, 47, 48, 49, 50,      # G
    61, 62, 63, 64, 65       # O
]

carton = generar_carton_desde_lista(numeros)
print(carton)

🎓 Documentación

• Arquitectura del Sistema
• Guía para Agentes de IA

🛠️ Desarrollo

Estado Actual: Fase 1 ✅

• Estructura de directorios
• Clase Carton completa
• Generación aleatoria
• Validación estricta
• Tests completos
• Sistema de patrones
• Clase ConjuntoCartones

Próximos Pasos: Fase 2

• Implementar patrones de victoria
• Sistema de scoring (delta)
• Evaluador de cobertura
• Evaluador de proximidad

🤝 Contribuir

1. Fork el proyecto
2. Crea una rama (git checkout -b feature/nueva-funcionalidad)
3. Commit cambios (git commit -m 'feat: Agregar nueva funcionalidad')
4. Push a la rama (git push origin feature/nueva-funcionalidad)
5. Abre un Pull Request

📝 Convenciones de Código

• Docstrings: Todas las clases y funciones públicas
• Type hints: Obligatorios en funciones públicas
• Tests: Cobertura mínima 80%
• Formato: Black (línea 88 caracteres)
• Imports: Ordenados y agrupados

📜 Licencia

MIT License - Ver archivo LICENSE para detalles.

👤 Autor

Desarrollado por [Tu Nombre]

🙏 Agradecimientos

• Comunidad Python
• Eventos de bingo a beneficio

---

Versión: 0.1.0 (Fase 1 completada)
Estado: En desarrollo activo
Última actualización: Noviembre 2025