# Guía de Desarrollo - Calculadora MAV CAS Híbrido

## Visión General

Este documento describe el estado actual y los objetivos de desarrollo para la **Calculadora MAV**, un **Sistema de Álgebra Computacional (CAS) híbrido**. El proyecto busca combinar la potencia de SymPy como motor algebraico central con capacidades especializadas (IP4, Hex, etc.) integradas de forma nativa.

## Objetivos Principales

### 1. **SymPy como Motor Central**
- ✅ Integrar todas las funciones de SymPy directamente
- ✅ SymPy maneja toda la evaluación algebraica y ecuaciones
- ✅ Cada línea de ingreso corresponde a una sola línea de resultados
- ✅ **CONTEXTO LIMPIO POR EVALUACIÓN**: Cada vez que se hace una evaluación se comienza con el contexto completamente limpio y se evalúa desde arriba hacia abajo, línea por línea. Esto garantiza comportamiento predecible sin "memoria" de evaluaciones anteriores.
- ✅ La interfaz de usuario se divide en 2 columnas, a la izquierda el área de ingreso de datos y ecuaciones a ser evaluadas, a la derecha el área de resultados que se colorean según cada tipo de respuesta.

### 2. **Sistema de Tokenización Automática** ⭐ **ACTUALIZADO**
- ❌ ~~Usar **exclusivamente** `Class[args]` en lugar de `Class("args")`~~ **ELIMINADO**
- ✅ **Tokenización automática de patrones específicos**:
  - `16#FF` → `IntBase('FF', 16)` automáticamente
  - `192.168.1.1` → `FourBytes('192.168.1.1')` automáticamente
- ✅ **Sistema distribuido**: Cada clase define sus propios patrones de tokenización
- ✅ **Precedencia automática**: Patrones más específicos tienen mayor prioridad
- ✅ **Parser genérico**: No hardcodea lógica específica de tipos

### 3. **Detección Automática y Manejo de Ecuaciones**
- ✅ Ecuaciones ingresadas directamente (ej. `3+b=5+c`) se detectan y añaden al sistema interno de SymPy.
- ✅ Soporte para comparaciones SymPy (ej. `x > 5`, `a == b`, `x <= 10`) como expresiones evaluables.
- ✅ Sintaxis de atajo para solve: `variable=?` equivale a `solve(variable)`

### 4. **Evaluación Híbrida con Variables SymPy Puras**
- ✅ Resultado simbólico (siempre disponible)
- ✅ Evaluación numérica con `.evalf()` (cuando sea aplicable y las variables estén definidas). Esta evaluación se muestra a la derecha del resultado simbólico.
- ✅ Las asignaciones son siempre simbólicas, solo los resultados se muestra la evaluación numérica.
- ✅ **Todas las variables son símbolos SymPy**: Sin variables Python tradicionales
- 🔄 **Conversión perezosa a SymPy**: Objetos nativos hasta que se necesite álgebra compleja

### 5. **Resultados Interactivos**
- ✅ **Tags clickeables** en el widget Text para resultados complejos que necesitan más de una línea de resultado como Plot, Matrices y Listas.
- ✅ **Detección automática** de tipos que requieren visualización especial:
  - ✅ Plots de SymPy → "📊 Ver Plot" (abre ventana matplotlib).
  - ✅ Matrices → "📋 Ver Matriz" (muestra matriz formateada).
  - ✅ Listas largas → "📋 Ver Lista" (muestra contenido expandido).
  - ✅ Objetos complejos → "🔍 Ver Detalles" (representación completa).
- ✅ **Implementación con tags**: Usar `text.tag_bind()` en widget existente
- ✅ **Ventanas popup** para contenido que no cabe en línea.

### 6. **Sistema de Tipos Auto-Descubrible** ⭐ **NUEVO**
- ✅ **Directorio unificado**: Todos los tipos en `custom_types/`
- ✅ **Auto-registro**: Sistema automático de descubrimiento de clases
- ✅ **Función de registro**: Cada módulo tiene `register_classes_in_module()`
- ✅ **Metadatos**: Categorías, opciones y descripciones por tipo
- ✅ **Helpers dinámicos**: Sistema de ayuda contextual distribuido

### 7. **Clases Base Universales** ⭐ **NUEVO**
- ✅ **IntBase**: Representación universal de números en cualquier base
- ✅ **FourBytes**: Representación universal de patrones x.x.x.x
- ✅ **Manejo interno de símbolos**: Sin conversión prematura a SymPy
- ✅ **Aritmética nativa**: Operaciones que mantienen el tipo original
- ✅ **Conversión explícita**: `.to_sympy()` cuando se necesite álgebra compleja

## Arquitectura Actual ⭐ **ACTUALIZADA**

### Estructura de archivos
```
/
├── logs/                           # Subcarpeta de logs
├── docs/                           # Documentación técnica
├── custom_types/                   # ⭐ NUEVO: Sistema de tipos unificado
│   ├── intbase_type.py            # IntBase + tokenización + registro
│   ├── fourbytes_type.py          # FourBytes + tokenización + registro  
│   ├── hex_type.py                # Hex (usa IntBase)
│   ├── bin_type.py                # Bin (usa IntBase)
│   ├── dec_type.py                # Dec
│   ├── chr_type.py                # Chr
│   ├── ip4_type.py                # IP4 + IP4Mask (usa FourBytes)
│   └── latex_type.py              # LaTeX
├── calc.py                        # Launcher principal
├── main_calc_app.py               # Aplicación principal
├── main_evaluation.py             # Motor de evaluación híbrido
├── type_registry.py               # ⭐ NUEVO: Auto-descubrimiento de tipos
├── tl_popup.py                    # Motor de ventanas emergentes
├── tl_bracket_parser.py           # ⭐ ACTUALIZADO: Tokenizador universal
├── class_base.py                  # Clases base
├── sympy_Base.py                  # Base para integración SymPy
└── sympy_helper.py                # Helpers para SymPy
```

### Flujo de Procesamiento ⭐ **ACTUALIZADO**
```
Entrada Usuario → [Universal Tokenizer] → [Evaluación Híbrida] → {
    1. Resultado Nativo (FourBytes, IntBase, etc.)
    2. Conversión a SymPy (solo si es necesario)
    3. Evaluación numérica (evalf si aplica)
    4. Métodos especializados disponibles
}
```

### Transformación de Sintaxis ⭐ **ACTUALIZADA**
```python
# Tokenización automática (NUEVO):
16#FF + 2#1010              → IntBase("FF", 16) + IntBase("1010", 2)
192.168.1.1 + 5             → FourBytes("192.168.1.1") + 5
IP4(10.1.1.1, 255.255.0.0) → IP4(FourBytes("10.1.1.1"), FourBytes("255.255.0.0"))

# Detección contextual de ecuaciones (EXISTENTE):
3+b=5+c → Se detecta como ecuación standalone (agregar al sistema SymPy)
"x > 5" → Se procesa como desigualdad SymPy
x**2 + 2*x == 0 → Se detecta como igualdad lógica standalone

# Sintaxis de atajo para solve (EXISTENTE):
x=? → solve(x)
```

## Componentes Técnicos ⭐ **ACTUALIZADOS**

### 1. **Sistema de Auto-Descubrimiento de Tipos**
```python
# type_registry.py
class TypeRegistry:
    def discover_and_register_all(self):
        """Descubre y registra todas las clases en custom_types/"""
        for type_file in self.types_directory.glob("*_type.py"):
            self._process_type_file(type_file)
        
    def _register_classes_from_info(self, class_info_list):
        """Registra clases basándose en metadatos"""
        for name, class_obj, category, options in class_info_list:
            self._register_single_class(name, class_obj, category, options)
```

### 2. **Tokenizador Universal Distribuido**
```python
# tl_bracket_parser.py
class UniversalTokenizer:
    def _discover_tokenization_rules(self):
        """Auto-descubre reglas desde todas las clases registradas"""
        for class_name, class_obj in registered_classes.items():
            if hasattr(class_obj, 'get_tokenization_patterns'):
                patterns = class_obj.get_tokenization_patterns()
                for pattern_info in patterns:
                    self.tokenization_rules.append({
                        'class_name': class_name,
                        'class_obj': class_obj,
                        **pattern_info
                    })
```

### 3. **Clases con Tokenización Propia**
```python
# custom_types/intbase_type.py
class IntBase(ClassBase):
    @staticmethod
    def get_tokenization_patterns():
        return [
            {
                'pattern': r'(\d+)#([0-9A-Fa-fx]+)',
                'replacement': lambda match: f'IntBase("{match.group(2)}", {match.group(1)})',
                'priority': 5,
                'description': 'Números con base: 16#FF, 2#1010'
            }
        ]
```

### 4. **Conversión Perezosa a SymPy** ⭐ **NUEVO CONCEPTO**
```python
class FourBytes(ClassBase):  # No SympyClassBase
    def substitute(self, **kwargs):
        """Sustitución interna sin involucrar SymPy"""
        # Lógica nativa
        
    def to_sympy(self):
        """Conversión EXPLÍCITA cuando se necesite álgebra"""
        # Solo convertir cuando se requiera
```

### 5. **Sistema de Evaluación Integrado**
```python
# main_evaluation.py
class HybridEvaluationEngine:
    def __init__(self, auto_discover_types=True):
        # Auto-descubrir tipos dinámicamente
        self.registered_types_info = discover_and_register_types()
        
        # Configurar parser con tokenización distribuida
        self.parser = BracketParser(enable_tokenization=True)
        
        # Configurar contexto con tipos descubiertos
        self._setup_base_context()
```

## Capacidades Expandidas ⭐ **ACTUALIZADAS**

### 1. **Funciones SymPy Completas con Objetos Nativos**
```python
# Objetos nativos en álgebra (conversión automática cuando es necesario):
diff(IP4(192.168.x.1) + offset, x)              # FourBytes → SymPy automático
integrate(Hex(16#x0) * sin(x), x)               # IntBase → SymPy automático
solve([IP4(192.168.x.y) == IP4(192.168.1.10)], [x, y])

# Aritmética nativa (mantiene tipos):
base_ip = 192.168.1.1                           # → FourBytes automático
next_ip = base_ip + 5                            # → FourBytes('192.168.1.6')
hex_val = 16#FF + 16#10                          # → IntBase('10F', 16)
```

### 2. **Conversiones Automáticas Bidireccionales**
```python
# Conversiones fluidas entre tipos:
ip = 192.168.1.1                                # → FourBytes automático
ip_hex = ip.ToHex()                              # → "16#C0.16#A8.16#1.16#1"
mask = 255.255.255.0                             # → FourBytes automático
mask_cidr = IP4Mask(mask)                        # → /24 automático

# Constructores inteligentes:
IP4(192.168.1.1, 16#ffffff00)                   # FourBytes + IntBase → IP4
Hex(192.168.1.1)                                # FourBytes → Hex automático
```

### 3. **Sistema de Ayuda Dinámico**
```python
# Helpers auto-descubiertos:
help_functions = get_registered_helper_functions()  # De todas las clases
help_context = obtener_ayuda("16#FF")               # Helper de IntBase
autocompletado = obj.PopupFunctionList()            # Métodos disponibles
```

## Ejemplos de Uso Objetivo ⭐ **ACTUALIZADOS**

```python
# Tokenización automática de patrones:
16#FF + 2#1010                    # → IntBase('FF', 16) + IntBase('1010', 2)
192.168.1.1 + 5                   # → FourBytes('192.168.1.6')
10.x.1.y                          # → FourBytes('10.x.1.y') simbólico

# Constructores inteligentes:
IP4(192.168.1.1, 24)             # → IP4(FourBytes('192.168.1.1'), 24)
IP4(10.1.1.1, 255.255.0.0)       # → Ambos FourBytes automáticamente
Hex(192.168.1.1)                 # → Conversión FourBytes → Hex

# Conversiones fluidas:
mask = 255.255.255.0              # → FourBytes automático
mask.ToHex()                      # → "16#FF.16#FF.16#FF.16#0"
mask.ToBase(2)                    # → "2#11111111.2#11111111.2#11111111.2#0"

# Álgebra con objetos nativos:
network = 10.x.0.0                # → FourBytes simbólico
solve(network + 256 == 10.5.0.0, x)  # → x = 5

# Aritmética que preserva tipos:
base = 192.168.0.0                # → FourBytes
for i in range(4):
    subnet = base + (i * 256)      # → Cada resultado es FourBytes
    print(f"Red {i}: {subnet}")

# Evaluación directa con SymPy:
solve(x + 10 - 15, x)             # → [5]
diff(16#x0, x)                    # → 16*log(16) (conversión automática)

# Variables puras SymPy:
x = 5                             # → x es Symbol('x') con valor 5
y = x + 2                         # → y es expresión simbólica: Symbol('x') + 2

# Funciones avanzadas con resultados interactivos:
plot(sin(2*pi*16#x/256), (x, 0, 255))  # → "📊 Ver Plot"
Matrix([[1, 2, 3], [4, 5, 6]])         # → "📋 Ver Matriz"
```

## Beneficios Logrados ⭐ **ACTUALIZADOS**

### 1. **Usabilidad Mejorada**
- ✅ Sintaxis natural sin artificios (no más `Class[args]`)
- ✅ Tokenización invisible al usuario
- ✅ Acceso completo a capacidades de CAS
- ✅ Evaluación automática simbólica + numérica

### 2. **Potencia Matemática Expandida**
- ✅ Todas las funciones de SymPy disponibles
- ✅ Objetos especializados participan en álgebra cuando es necesario
- ✅ Aritmética nativa que preserva tipos
- ✅ Conversiones automáticas bidireccionales

### 3. **Extensibilidad Real**
- ✅ Sistema verdaderamente modular sin hardcoding
- ✅ Fácil agregar nuevos tipos sin modificar código core
- ✅ Tokenización distribuida y auto-descubrible
- ✅ Compatible con ecosystem SymPy completo

### 4. **Arquitectura Limpia**
- ✅ Responsabilidad única: cada clase maneja su tokenización
- ✅ Parser genérico sin conocimiento específico de tipos
- ✅ Auto-descubrimiento completo del sistema de tipos
- ✅ Manejo unificado de errores

## Sistema de Autocompletado y Ayuda Contextual ⭐ **IMPLEMENTADO**

### 1. **Helpers Dinámicos**
- ✅ **Auto-descubrimiento**: Sistema obtiene helpers de todas las clases registradas
- ✅ **Ayuda contextual**: Cada tipo define su propio `Helper(input_str)`
- ✅ **Integración con SymPy**: Helper especializado para funciones SymPy
- ✅ **Manejo centralizado**: Lista dinámica de helpers disponibles

### 2. **Autocompletado Inteligente**
- ✅ **Popup tras punto**: Evaluación automática del objeto para métodos disponibles
- ✅ **PopupFunctionList()**: Cada clase define sus métodos sugeridos
- ✅ **Filtrado inteligente**: Solo métodos útiles y públicos
- ✅ **No invasivo**: Solo aparece cuando el usuario lo solicita

### 3. **Ejemplos de Integración**
```python
# Sistema distribuido:
HELPERS = get_registered_helper_functions()  # Auto-descubierto

# Ayuda contextual:
16#FF.                            # → Popup con métodos de IntBase
192.168.1.1.                      # → Popup con métodos de FourBytes
IP4(10.1.1.1).                    # → Popup con métodos de IP4

# Helpers específicos:
ayuda = obtener_ayuda("16#FF")    # → "Números con base: 16#FF, 2#1010..."
```

## Estado de Implementación ⭐ **ACTUALIZADO**

### ✅ **Completamente Implementado**
- **Sistema de auto-descubrimiento**: `type_registry.py`
- **Tokenizador universal**: `tl_bracket_parser.py` refactorizado
- **Clases base universales**: `intbase_type.py`, `fourbytes_type.py`
- **Motor híbrido integrado**: `main_evaluation.py` con auto-descubrimiento
- **Tipos en custom_types/**: Todos los tipos migrados al sistema unificado
- **Helpers dinámicos**: Sistema de ayuda contextual distribuido
- **Resultados interactivos**: Tags clickeables y ventanas popup
- **Contexto limpio**: Evaluación completa desde cero en cada cambio

### 🔄 **En Progreso**
- **Conversión perezosa a SymPy**: Algunos objetos aún se convierten prematuramente
- **Aritmética que preserva tipos**: Necesita refinamiento para todos los casos
- **Optimización de precedencia**: Ajuste fino de prioridades de tokenización

### 📋 **Pendiente**
- **Tipos adicionales**: MAC addresses, timestamps, coordenadas
- **Performance optimization**: Caching y evaluación lazy
- **Documentación de usuario**: Guías y ejemplos actualizados

## Métricas de Éxito ⭐ **ACTUALIZADAS**

- ✅ **Sistema de tokenización automática funcional**:
  - ✅ Patrones `16#FF`, `2#1010` → IntBase automático
  - ✅ Patrones `192.168.1.1` → FourBytes automático  
  - ✅ Precedencia automática por especificidad
  - ✅ Parser genérico sin hardcoding

- ✅ **Sistema de tipos auto-descubrible**:
  - ✅ Todas las clases en `custom_types/`
  - ✅ Función `register_classes_in_module()` en cada módulo
  - ✅ Auto-registro con metadatos y opciones
  - ✅ Helpers dinámicos desde todas las clases

- ✅ **Clases base universales funcionales**:
  - ✅ IntBase con aritmética nativa y tokenización propia
  - ✅ FourBytes con aritmética nativa y tokenización propia
  - ✅ Conversión explícita `.to_sympy()` cuando sea necesario
  - ✅ Operadores que mantienen tipos nativos

- ✅ **Motor híbrido integrado**:
  - ✅ Auto-descubrimiento de tipos al inicializar
  - ✅ Tokenización distribuida automática
  - ✅ Contexto limpio por evaluación
  - ✅ Evaluación simbólica + numérica

- 🔄 **Conversión perezosa optimizada**:
  - ✅ Objetos nativos por defecto
  - 🔄 Conversión solo cuando se necesite álgebra compleja
  - 🔄 Aritmética preservando tipos en todos los casos

- ✅ **Detección contextual de ecuaciones**:
  - ✅ Ecuaciones standalone detectadas y agregadas al sistema
  - ✅ Sintaxis de atajo `variable=?` → `solve(variable)`
  - ✅ Protección contra detección en argumentos de función

- ✅ **Resultados interactivos**:
  - ✅ Tags clickeables para plots, matrices, listas
  - ✅ Ventanas popup con posicionamiento inteligente  
  - ✅ Detección automática de tipos complejos

- ✅ **Sistema de ayuda avanzado**:
  - ✅ Helpers auto-descubiertos desde todas las clases
  - ✅ Autocompletado tras punto con métodos disponibles
  - ✅ Ayuda contextual no invasiva

- ✅ **Performance aceptable**: Debounce y evaluación optimizada
- ✅ **Manejo robusto de errores**: Logging centralizado y presentación clara
- ✅ **Documentación actualizada**: Guías técnicas y de desarrollo

## Consideraciones Futuras

### **Tipos Adicionales Planeados**
```python
custom_types/
├── mac_type.py          # Direcciones MAC: AA:BB:CC:DD:EE:FF
├── time_type.py         # Timestamps: HH:MM:SS, ISO format
├── coordinate_type.py   # Coordenadas: lat,lon
├── ipv6_type.py         # IPv6: 2001:db8::1
└── range_type.py        # Rangos: 1..100, a..z
```

### **Optimizaciones de Performance**
- Caching de patrones de tokenización frecuentes
- Evaluación lazy de `evalf()` solo cuando se muestre
- Memoización de conversiones SymPy costosas

### **Extensiones del Parser**
- Soporte para sintaxis de múltiples líneas
- Macros y templates definidos por usuario
- Validación contextual más sofisticada

## Conclusión

La calculadora MAV ha evolucionado hacia un **sistema verdaderamente híbrido y extensible** que combina:

1. **Potencia algebraica completa** de SymPy
2. **Objetos nativos especializados** con aritmética propia
3. **Tokenización automática invisible** al usuario
4. **Arquitectura modular** sin hardcoding
5. **Auto-descubrimiento completo** del sistema de tipos

El resultado es una herramienta que es **más simple para el usuario** (sintaxis natural) pero **más poderosa internamente** (álgebra simbólica + tipos especializados), con una **arquitectura limpia y extensible** que facilita agregar nuevas capacidades sin modificar código existente.