grx-tensor 0.2.0 → 0.2.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: e72486318839399760aded34a10566bfa919ddec52212dc7694b6d4d8c47e843
-  data.tar.gz: 7c52178af28a4d75ce1a424539a088270501b0cd5087f0e97c901c228749e827
+  metadata.gz: ef573ddb7f047d0fbe2a87a1bb9fe9d102870cdb9c31791129335eda4724baa2
+  data.tar.gz: c65fb09c8d9c769415870d60ede2efd50dbdd3367fb6ad700c95c686c3d2376d
 SHA512:
-  metadata.gz: 5248ca76ea0f17611cd11c0c883169f17f998fa8270373473559dd1897263192e7c2af3592d7fcca8276798877755edeb058de095cdb8be424388d3b679dcea8
-  data.tar.gz: 9f7461cd793bca1347ed006bdde5ff35fdfea968f1706cd03d66d56c0a1d2cbf2cf58036bcceee2096a26747455389f1d0df9f3cd6b4adcf574b5d412c39af5f
+  metadata.gz: 997603cfd5b43ab6800e8f24300d9771e1ca06edca26b15e61447c68076637bb2103112c13af98d3c98c8c9d9b76cbcab89323b3a42e5b56beeebd84da625134
+  data.tar.gz: b0623d6572185c7590dd1cf34f0b225950fc459a6d653cc2ae60188e239c00e368e0073ae20c27a66a9516d4b80966b7d0b0f6dd9b8ee1308100ccaeebc941cd

data/CHANGELOG.md

@@ -17,6 +17,15 @@ Versioning follows [Semantic Versioning](https://semver.org/).
 - `Conv2d`, `LSTM`, `MultiheadAttention` layers
 - CUDA extension (`grx-tensor-cuda`)
 
+## [0.2.1] - 2026-08-29
+
+### Fixed
+- **Illegal Instruction Crash Resolved (`SIGILL`)**: Removed forced global `-mavx2` compiler flags that produced opcode crashes on older Intel/AMD CPUs, VMs, and ARM architectures.
+- **Dynamic Multi-Target SIMD Dispatch**: Runtime CPU detection (`grx_simd_level`) dynamically selects between AVX2+FMA (4 doubles/cycle), SSE, or portable scalar C with zero overhead.
+- **Automated Native Compilation**: Extension builds seamlessly on `gem install grx-tensor` without requiring manual make invocations.
+- **Windows DevKit Support & Documentation**: Streamlined MinGW-w64 build path and clarified standalone binary progress.
+- **Post-Install Experience**: Clean dual-language (EN/ES) thank-you notice and direct repository documentation links.
+
 ---
 
 ## [0.2.0] - 2026-08-21

data/GUIA_PRINCIPIANTES.md

@@ -28,15 +28,18 @@
 8. [Algebra Lineal Intuitiva: Multiplicacion de Matrices](#8-algebra-lineal-intuitiva-multiplicacion-de-matrices)
 9. [El Superpoder de GRX: Que es Autograd?](#9-el-superpoder-de-grx-que-es-autograd)
 10. [Construyendo Redes Neuronales Bloque a Bloque](#10-construyendo-redes-neuronales-bloque-a-bloque)
-11. [El Ciclo Sagrado del Entrenamiento (Con loss.backward directo)](#11-el-ciclo-sagrado-del-entrenamiento-con-lossbackward-directo)
-12. [Proyectos Guiados Paso a Paso (Completos y Ejecutables)](#12-proyectos-guiados-paso-a-paso-completos-y-ejecutables)
-    - [Proyecto 1: El Predictor de Formulas (Regresion Lineal)](#proyecto-1-el-predictor-de-formulas-regresion-lineal)
-    - [Proyecto 2: Ajuste de Curvas No Lineales y Guardado en .grx](#proyecto-2-ajuste-de-curvas-no-lineales-y-guardado-en-grx)
-    - [Proyecto 3: Clasificador Binario Inteligente con BCELoss](#proyecto-3-clasificador-binario-inteligente-con-bceloss)
-    - [Proyecto 4: Entrenamiento con Datasets Masivos (5,000 Filas con DataLoader)](#proyecto-4-entrenamiento-con-datasets-masivos-5000-filas-con-dataloader)
-    - [Proyecto 5: Chatbot Financiero Inteligente con Base de Conocimiento y Filtro de Incertidumbre](#proyecto-5-chatbot-financiero-inteligente-con-base-de-conocimiento-y-filtro-de-incertidumbre)
-13. [Buenas Practicas y Errores Comunes](#13-buenas-practicas-y-errores-comunes)
-14. [Glosario de Terminos Clave](#14-glosario-de-terminos-clave)
+11. [El Ciclo Sagrado del Entrenamiento (Explicacion Paso a Paso)](#11-el-ciclo-sagrado-del-entrenamiento-explicacion-paso-a-paso)
+12. [El Diccionario Sagrado de Parametros e Hiperparametros](#12-el-diccionario-sagrado-de-parametros-e-hiperparametros)
+13. [Proyectos Guiados Paso a Paso (Completos y Ejecutables)](#13-proyectos-guiados-paso-a-paso-completos-y-ejecutables)
+    - [Proyecto 1: El Conversor de Temperatura (Celsius a Fahrenheit)](#proyecto-1-el-conversor-de-temperatura-celsius-a-fahrenheit)
+    - [Proyecto 2: Compuertas Logicas (AND Lineal vs XOR No Lineal)](#proyecto-2-compuertas-logicas-and-lineal-vs-xor-no-lineal)
+    - [Proyecto 3: El Predictor de Formulas (Regresion Lineal)](#proyecto-3-el-predictor-de-formulas-regresion-lineal)
+    - [Proyecto 4: Ajuste de Curvas No Lineales y Guardado en .grx](#proyecto-4-ajuste-de-curvas-no-lineales-y-guardado-en-grx)
+    - [Proyecto 5: Clasificador Binario Inteligente con BCELoss](#proyecto-5-clasificador-binario-inteligente-con-bceloss)
+    - [Proyecto 6: Entrenamiento con Datasets Masivos (5,000 Filas con DataLoader)](#proyecto-6-entrenamiento-con-datasets-masivos-5000-filas-con-dataloader)
+    - [Proyecto 7: Chatbot Financiero Inteligente con Base de Conocimiento y Filtro de Incertidumbre](#proyecto-7-chatbot-financiero-inteligente-con-base-de-conocimiento-y-filtro-de-incertidumbre)
+14. [Buenas Practicas y Errores Comunes](#14-buenas-practicas-y-errores-comunes)
+15. [Glosario de Terminos Clave](#15-glosario-de-terminos-clave)
 
 ---
 
@@ -48,7 +51,15 @@ Por otro lado, C ofrece velocidad extrema, pero programar grafos de autograd y r
 
 **GRX-Tensor une lo mejor de ambos mundos:**
 - **Ruby habla:** Escribes codigo fluido, declarativo y limpio para definir arquitecturas, procesar datos y crear aplicaciones.
-- **C calcula:** Cada operacion matematica, producto matricial, retropropagacion y actualizacion de pesos se ejecuta en un buffer nativo de C con aceleracion vectorial **SIMD (AVX2 + FMA)**, procesando 4 numeros de doble precision por ciclo de CPU.
+- **C calcula:** Cada operacion matematica, producto matricial, retropropagacion y actualizacion de pesos se ejecuta en un buffer nativo de C con aceleracion vectorial **SIMD multi-target (AVX2 + FMA, SSE y C escalar)**.
+
+### Instalacion y Compatibilidad de Hardware Universal
+1. **Instalacion 100% automatica:** Al instalar con `gem install grx-tensor`, RubyGems compila y enlaza automaticamente la extension nativa de C en segundo plano sin requerir comandos de compilacion manuales.
+2. **Despacho Dinamico por CPU:** El motor en C detecta en tiempo real las caracteristicas de tu procesador:
+   - Si tu procesador soporta **AVX2 + FMA**, activa la maxima aceleracion vectorial (4 doubles/ciclo).
+   - Si tu procesador soporta **SSE**, activa las instrucciones vectoriales SSE.
+   - Si tu maquina es ARM, una maquina virtual o una CPU clasica, conmuta a **C escalar**, evitando cualquier error de "instruccion ilegal".
+3. **Estado del Soporte en Windows:** En Windows, la aceleracion nativa funciona compilando automaticamente mediante **RubyInstaller con DevKit (MSYS2 / MinGW-w64)**. Si no hay compilador presente, el framework corre en modo fallback de Ruby puro de forma segura. El empaquetado de binarios pre-compilados (.dll) sin necesidad de DevKit se encuentra en desarrollo activo.
 
 ---
 
@@ -405,23 +416,295 @@ puts modelo
 
 ---
 
-## 11. El Ciclo Sagrado del Entrenamiento (Con `loss.backward` directo)
+## 11. El Ciclo Sagrado del Entrenamiento (Explicacion Paso a Paso)
+
+El entrenamiento de cualquier modelo en GRX sigue un ciclo de 5 pasos universales:
 
 ```ruby
-opt.zero_grad                         # 1. Limpiar gradientes anteriores
-pred = modelo.call(train_x)           # 2. Forward pass
-loss = loss_fn.call(pred, train_y)    # 3. Calcular la perdida
-loss.backward                         # 4. Backward pass automatico
-opt.step                              # 5. Ajustar pesos
+# 1. Limpiar gradientes anteriores
+#    En cada paso, el optimizador calcula la direccion del cambio.
+#    Si no limpias los gradientes, se acumularan como una bola de nieve.
+opt.zero_grad
+
+# 2. Pase hacia adelante (Forward Pass)
+#    Los datos entran a la red y se procesan a traves de capas de matrices en C con SIMD.
+pred = modelo.call(train_x)
+
+# 3. Calculo de la Perdida (Loss / Error)
+#    La funcion de perdida mide numericamente que tan lejos estamos de la realidad.
+loss = loss_fn.call(pred, train_y)
+
+# 4. Pase hacia atras (Backward Pass / Autograd)
+#    GRX recorre el grafo DAG hacia atras calculando la derivada exacta de cada peso.
+loss.backward
+
+# 5. Paso de Optimizacion (Optimizer Step)
+#    El optimizador (Adam o SGD) actualiza los pesos en C para reducir el error.
+opt.step
 ```
 
 ---
 
-## 12. Proyectos Guiados Paso a Paso (Completos y Ejecutables)
+## 12. El Diccionario Sagrado de Parametros e Hiperparametros
+
+Cuando creas optimizadores, capas o funciones de perdida, veras expresiones como `lr: 0.001`, `lr: 1e-3`, `momentum: 0.9`, `weight_decay: 1e-4`, `eps: 1e-8` o `betas: [0.9, 0.999]`. Que significan, que valores admiten y como se deben configurar?
+
+---
+
+### 1. Que significa la Notacion Cientifica en Machine Learning (`1e-1` a `1e-8`)?
+
+En Ruby y en Inteligencia Artificial, los numeros muy pequenos se escriben en **notacion cientifica exponencial** (`1e-X` que equivale a $1.0 \times 10^{-X}$). Esto evita errores tipograficos al contar ceros decimales:
+
+| Notacion Ruby | Valor Decimal Exacto | Fraccion | Nombre Comun | Uso Tipico en GRTensor |
+|---|---|---|---|---|
+| `1e-1` | `0.1` | $1/10$ | Una decima | Momentum de actualizacion en `BatchNorm1d`, learning rate rapido. |
+| `1e-2` | `0.01` | $1/100$ | Una centesima | Learning rate estandar para `SGD`, pendiente `alpha` en `LeakyReLU`. |
+| `1e-3` | `0.001` | $1/1,000$ | Una milesima | Learning rate estandar de oro para `Adam` en redes profundas. |
+| `1e-4` | `0.0001` | $1/10,000$ | Una diezmilesima | Penalizacion de regularizacion L2 (`weight_decay`) para evitar sobreajuste. |
+| `1e-5` | `0.00001` | $1/100,000$ | Una cienmilesima | Epsilon (`eps`) de varianza en `LayerNorm` y `BatchNorm1d`. |
+| `1e-7` | `0.0000001` | $1/10,000,000$ | Una diezmillonesima | Epsilon de corte en `BCELoss` para evitar $\log(0) \to -\infty$. |
+| `1e-8` | `0.00000001` | $1/100,000,000$ | Una cienmillonesima | Epsilon de estabilidad numerica en el denominador de `Adam`. |
+
+---
+
+### 2. Parametros de Optimizadores (`GRX::Optim`)
+
+#### `lr` (Learning Rate / Tasa de Aprendizaje)
+* **Que es:** La velocidad y tamano del paso que da la red hacia el error minimo en cada iteracion.
+* **Analogia:** Caminar hacia el fondo de un valle con los ojos vendados.
+  * Si `lr` es muy grande (`lr: 10.0`), saltaras de una colina a otra sin tocar el fondo y la perdida explotara (`Infinity` o `NaN`).
+  * Si `lr` es muy pequeno (`lr: 1e-6`), tardaras semanas en dar 3 pasos.
+* **Valores recomendados:**
+  * `0.001` o `1e-3` (Valor por defecto de oro para `Adam` en casi todas las redes neuronales).
+  * `0.01` a `0.1` (`1e-2` a `1e-1`) (Para `SGD` con momentum o regresiones lineales rapidas).
+  * `0.5` a `0.8` (Para modelos de 1 sola neurona como el conversor de temperatura).
+
+#### `momentum` (Momento / Inercia en SGD)
+* **Que es:** Acumula la velocidad y direccion de los gradientes anteriores para acelerar el descenso.
+* **Analogia:** Una bola pesada de boliche rodando colina abajo. En lugar de detenerse o rebotar caoticamente por cada bache diminuto en los datos, la bola mantiene su inercia hacia adelante.
+* **Valores:** `0.0` (sin momento) a `0.99`. Valor recomendado estandar: `0.9`.
+
+#### `weight_decay` (Decaimiento de Pesos / Regularizacion L2)
+* **Que es:** Una penalizacion matematica que encoge ligeramente los pesos hacia cero en cada paso ($w \leftarrow w - \lambda \cdot w$).
+* **Analogia:** La Navaja de Ockham. Evita que la red memorice las respuestas exactas (*Overfitting* o Sobreajuste) forzandola a preferir explicaciones simples y pesos pequenos y equilibrados.
+* **Valores recomendados:** `0.0` (por defecto, sin penalizacion), `1e-4` ($0.0001$) o `1e-5` para datasets del mundo real.
+
+#### `betas` / `beta1`, `beta2` (En `GRX::Optim::Adam`)
+* **Que es:** Las tasas de decaimiento exponencial para la estimacion de momentos de 1er y 2do orden.
+  * $\beta_1$ (defecto: `0.9`): Memoria del 90% de la direccion del gradiente anterior (momento direccional).
+  * $\beta_2$ (defecto: `0.999`): Memoria del 99.9% de la varianza del gradiente al cuadrado (escala automaticamente pasos grandes para gradientes raros y pasos pequenos para gradientes frecuentes).
+* **Valores recomendados:** `[0.9, 0.999]` (el estandar probado de Kingma & Ba).
+
+#### `eps` / `epsilon` (Estabilidad Numerica)
+* **Que es:** Un numero microscopico ($1e-8$ en Adam, $1e-5$ en LayerNorm/BatchNorm) sumado al denominador.
+* **Por que existe:** Si la varianza de un parametro es 0, dividir entre 0 causaria un fallo critico de hardware (`NaN`). El epsilon actua como cinturon de seguridad matematico.
+
+---
+
+### 3. Parametros de Capas Neuronales (`GRX::NN`)
+
+| Capa / Modulo | Parametro | Tipo | Por Defecto | Rango Valido | Explicacion Didactica |
+|---|---|---|---|---|---|
+| `GRX::NN::Linear` | `in_features` | Integer | (Requerido) | $\ge 1$ | Cantidad de numeros de entrada que recibe la capa. |
+| `GRX::NN::Linear` | `out_features` | Integer | (Requerido) | $\ge 1$ | Cantidad de neuronas o caracteristicas que produce de salida. |
+| `GRX::NN::Linear` | `bias` | Boolean | `true` | `true` / `false` | Si es `true`, agrega el termino de sesgo $b$ ($y = Wx + b$). |
+| `GRX::NN::Embedding`| `num_embeddings` | Integer | (Requerido) | $\ge 1$ | Tamano del vocabulario o numero total de entidades unicas. |
+| `GRX::NN::Embedding`| `embedding_dim` | Integer | (Requerido) | $\ge 1$ | Dimension del vector denso continuo para representar cada palabra. |
+| `GRX::NN::Dropout` | `p` | Float | `0.5` | `0.0` a `0.99` | Probabilidad de desactivar aleatoriamente una neurona durante el entrenamiento (0.2 = 20%, 0.5 = 50%) para evitar que la red se vuelva dependiente de una sola neurona. |
+| `GRX::NN::LeakyReLU`| `alpha` | Float | `0.01` | `0.001` a `0.3` | Pendiente para numeros negativos. Evita que las neuronas "mueran" permitiendo pasar un 1% de gradiente cuando $x < 0$. |
+| `GRX::NN::LayerNorm`| `normalized_shape`| Integer/Array | (Requerido) | Dimensiones | Dimension sobre la que se calcula la media y varianza unitaria. |
+| `GRX::NN::LayerNorm`| `eps` / `epsilon` | Float | `1e-5` | `1e-8` a `1e-4` | Termino sumado a la varianza para evitar division entre 0. |
+| `GRX::NN::BatchNorm1d`| `num_features` | Integer | (Requerido) | $\ge 1$ | Cantidad de canales a normalizar a lo largo del lote (*batch*). |
+| `GRX::NN::BatchNorm1d`| `eps` / `epsilon` | Float | `1e-5` | `1e-8` a `1e-4` | Termino de estabilidad sumado a la varianza por lote. |
+| `GRX::NN::BatchNorm1d`| `momentum` | Float | `0.1` | `0.01` a `0.5` | Factor de actualizacion de medias y varianzas moviles para inferencia. |
+
+---
+
+### 4. Parametros de Funciones de Perdida (`GRX::Loss`)
+
+| Funcion de Perdida | Parametro | Opciones / Tipo | Por Defecto | Explicacion |
+|---|---|---|---|---|
+| `MSELoss` / `MAELoss` | `reduction` | Symbol | `:mean` | `:mean` promedia el error entre todas las muestras del lote. `:sum` suma todos los errores directos. |
+| `BCELoss` | `reduction` | Symbol | `:mean` | `:mean` o `:sum`. |
+| `BCELoss` | `eps` | Float | `1e-7` | Limite de seguridad para evitar $\log(0) \to -\infty$ en probabilidades extremas (0.0 o 1.0). |
+| `CrossEntropyLoss` | `reduction` | Symbol | `:mean` | `:mean` o `:sum`. Aplica Softmax con Log-Sum-Exp. |
+| `HuberLoss` | `delta` | Float | `1.0` | Umbral de transicion: si el error es menor a $\delta$ se calcula como cuadratico (MSE); si es mayor, se calcula lineal (MAE) para no volverse loco con datos atipicos (*outliers*). |
+| `HuberLoss` | `reduction` | Symbol | `:mean` | `:mean` o `:sum`. |
+
+---
+
+### 5. Parametros de Creacion y Manipulacion de Tensores (`GRX::Tensor`)
+
+| Metodo / Factory | Parametro | Tipo | Por Defecto | Descripcion |
+|---|---|---|---|---|
+| `GRX.tensor` | `data` | Array / Storage | (Requerido) | Datos numericos en arreglo plano (`[1.0, 2.0]`) o anidado (`[[1, 2], [3, 4]]`). |
+| `GRX.tensor` | `shape` | Array[Integer] | `nil` (Auto) | Dimensiones del tensor (ej. `[2, 3]` para 2 filas y 3 columnas). |
+| `GRX.tensor` | `requires_grad`| Boolean | `false` | Activa el rastreo en el grafo DAG para calcular gradientes con `backward`. |
+| `GRX.zeros` / `GRX.ones` | `shape` | Array[Integer] | (Requerido) | Dimensiones del tensor a inicializar con ceros o unos. |
+| `GRX.rand` | `shape` | Array[Integer] | (Requerido) | Genera tensor con distribucion uniforme $U[0, 1)$. |
+| `GRX.randn` | `shape` | Array[Integer] | (Requerido) | Genera tensor con distribucion normal estandar $N(0, 1)$ mediante Box-Muller. |
+| `Tensor.xavier_uniform`| `shape` | Array[Integer] | (Requerido) | Inicializador Xavier/Glorot ($U[-\sqrt{6/(f_{in}+f_{out})}, \sqrt{6/(f_{in}+f_{out})}]$). |
+| `Tensor.he_normal` | `shape` | Array[Integer] | (Requerido) | Inicializador He/Kaiming ($N(0, \sqrt{2/f_{in}})$), optimo para capas con ReLU. |
+| `Tensor.zeros_like` | `other` | Tensor | (Requerido) | Crea un tensor de ceros con la misma forma que `other`. |
+| `Tensor.ones_like` | `other` | Tensor | (Requerido) | Crea un tensor de unos con la misma forma que `other`. |
+| `tensor.clip` | `lo`, `hi` | Numeric | (Requeridos) | Limites inferior y superior. Fija valores fuera del intervalo $[lo, hi]$. |
+| `tensor.pow` | `exponent` | Numeric | (Requerido) | Exponente al que se eleva cada elemento ($x^e$). Totalmente diferenciable. |
+| `tensor.reshape` | `new_shape` | Array[Integer] | (Requerido) | Nueva forma manteniendo el mismo `numel` total. Vista zero-copy. |
+| `tensor.transpose` | (sin args) | - | - | Intercambia filas y columnas en tensores 2D. Vista zero-copy por strides. |
+| `tensor.flatten` | (sin args) | - | - | Aplana el tensor a 1 dimension `[numel]`. Vista zero-copy. |
+| `tensor.contiguous`| (sin args) | - | - | Re-empaca la memoria no contigua (tras un transpose) en un buffer contiguo nuevo. |
+| `tensor.get` | `*indices` | Integers | (Requerido) | Coordenadas del elemento a leer (ej. `t.get(0, 2)`). |
+| `tensor.set` | `*indices, val`| Integers, Float | (Requeridos) | Modifica directamente el valor en la posicion especificada. |
+| `tensor.item` | (sin args) | - | - | Extrae el valor numerico Float de un tensor escalar de 1 solo elemento. |
+| `tensor.argmax` | (sin args) | - | - | Retorna el indice del elemento con el valor maximo. |
+| `tensor.argmin` | (sin args) | - | - | Retorna el indice del elemento con el valor minimo. |
+| `tensor.backward` | `gradient` | Tensor | `nil` | Ejecuta la retropropagacion inversa a lo largo del grafo computacional DAG. |
+
+---
+
+### 6. Parametros de Carga de Datos, Persistencia y Utilidades (`GRX::Data`, `GRX::Serialization`, `GRX::Utils`)
+
+* `TensorDataset.new(*tensors)`:
+  * `*tensors` (Tensors requeridos): Tensores paralelos (ej. caracteristicas $X$ y etiquetas $Y$) que comparten la dimension 0 de lote.
+* `DataLoader.new(dataset, batch_size: 32, shuffle: true)`:
+  * `dataset` (`GRX::Data::Dataset`): Coleccion indexable de datos.
+  * `batch_size` (Integer, por defecto: `32`): Cantidad de muestras agrupadas que se procesan simultaneamente en C por iteracion antes de actualizar pesos.
+  * `shuffle` (Boolean, por defecto: `true`): Si es `true`, desordena aleatoriamente los indices en cada epoca para que la red no aprenda el orden de los datos.
+* `GRX::Serialization.save(model, path)` / `model.save_weights(path)`:
+  * `model` (`GRX::NN::Module`): Instancia del modelo a persistir.
+  * `path` (String): Ruta del archivo destino `.grx`. Vuelca directamente los doubles IEEE 754 de 64 bits de la memoria C sin sobrecosto de JSON/YAML.
+* `GRX::Serialization.load(model, path)` / `model.load_weights(path)`:
+  * `model` (`GRX::NN::Module`): Modelo con la misma arquitectura en memoria.
+  * `path` (String): Ruta del archivo `.grx` binario a cargar.
+* `model.train!` y `model.eval!`:
+  * `train!`: Pone el modelo en modo de entrenamiento (activa `Dropout` y calcula medias dinamicas en `BatchNorm1d`).
+  * `eval!`: Pone el modelo en modo de evaluacion/inferencia (desactiva `Dropout` y usa medias moviles fijas en `BatchNorm1d`).
+* `GRX::Utils.clip_grad_norm!(params, max_norm: 1.0)`:
+  * `params` (Array[Tensor]): Coleccion de parametros con gradientes acumulados.
+  * `max_norm` (Float, por defecto: `1.0`): Norma L2 maxima permitida. Si la norma combinada supera `max_norm`, los gradientes se reescalan proporcionalmente para evitar explosiones.
+* `GRX::Utils.one_hot(indices, num_classes: nil, requires_grad: false)`:
+  * `indices` (Array[Integer] o Tensor): Vector con identificadores enteros de clase (ej. `[0, 2, 1]`).
+  * `num_classes` (Integer, opcional): Numero total de columnas de clase (si no se indica, se autocalcula como `max + 1`).
+  * `requires_grad` (Boolean, por defecto: `false`): Si la matriz resultante requiere autograd.
+* `GRX.simd_mode`:
+  * Retorna el nivel de aceleracion de hardware activo en la maquina: `:avx2` (4 doubles/ciclo con FMA), `:sse` (2 doubles/ciclo), `:scalar` (C portable) o `:ruby` (fallback).
+
+---
+
+### 7. Jerarquia de Excepciones de GRTensor
+
+| Excepcion | Hereda de | Causa Principal |
+|---|---|---|
+| `GRX::Error` | `StandardError` | Clase base para todas las excepciones del framework. |
+| `GRX::ShapeError` | `GRX::Error` | Dimensiones incompatibles en operaciones algebraicas (ej. sumar matrices de distinto tamano o multiplicar dimensiones internas dispares). |
+| `GRX::DimensionError` | `GRX::Error` | Rango de dimensiones invalido (ej. llamar `transpose` o `matmul` sobre tensores de 1 sola dimension). |
+| `GRX::StorageError` | `GRX::Error` | Fallo de memoria nativa C (`malloc` OOM) o error de lectura en archivos binarios `.grx` corruptos. |
+
+---
+
+## 13. Proyectos Guiados Paso a Paso (Completos y Ejecutables)
+
+---
+
+### Proyecto 1: El Conversor de Temperatura (Celsius a Fahrenheit)
+
+Este es el "Hello World" absoluto de la Inteligencia Artificial. La formula fisica real es:
+$$F = 1.8 \times C + 32$$
+
+La red neuronal tiene **1 sola neurona** (`Linear(1, 1)`: $y = w \cdot x + b$). La red no conoce la formula, pero tras 1,500 iteraciones con Adam, descubrira por si sola que el peso $w \approx 1.8$ y el sesgo $b \approx 32.0$.
+
+```ruby
+require "grx"
+
+# 1. Datos de entrenamiento (8 pares de temperaturas reales)
+celsius_datos    = [18.0, 25.0, 14.0, 21.0,  9.0, 16.0,  4.0, 32.0]
+fahrenheit_datos = [64.4, 77.0, 57.2, 69.8, 48.2, 60.8, 39.2, 89.6]
+
+# Convertir a tensores 2D [8 filas, 1 columna]
+x = GRX.tensor(celsius_datos, [8, 1])
+y = GRX.tensor(fahrenheit_datos, [8, 1])
+
+# 2. Definir la arquitectura (1 neurona)
+termometro = GRX::NN::Sequential.new(
+  GRX::NN::Linear.new(1, 1)
+)
+
+# 3. Optimizador y funcion de error cuadratico medio (MSE)
+opt = GRX::Optim::Adam.new(termometro.parameters, lr: 0.8)
+loss_fn = GRX::Loss::MSELoss.new
+
+puts "Entrenando la neurona para aprender la escala Fahrenheit..."
+
+# 4. Bucle de entrenamiento
+1500.times do
+  opt.zero_grad
+  pred = termometro.call(x)
+  loss = loss_fn.call(pred, y)
+  loss.backward
+  opt.step
+end
+
+puts "Entrenamiento finalizado!"
+
+# 5. Pruebas con temperaturas nunca vistas
+test_celsius = GRX.tensor([[100.0], [0.0], [37.0]], [3, 1])
+predicciones = termometro.call(test_celsius).to_a
+
+puts "\n--- Resultados del Termometro Neuronal ---"
+puts "100.0 C -> #{predicciones[0].round(2)} F (Esperado: 212.00 F)"
+puts "  0.0 C -> #{predicciones[1].round(2)} F (Esperado:  32.00 F)"
+puts " 37.0 C -> #{predicciones[2].round(2)} F (Esperado:  98.60 F)"
+```
+
+---
+
+### Proyecto 2: Compuertas Logicas (AND Lineal vs XOR No Lineal)
+
+Una compuerta **AND** se puede resolver con 1 sola neurona lineal porque los datos son linealmente separables.
+Sin embargo, la compuerta **XOR** (Or Exclusivo) es el clasico problema no lineal: una sola linea recta no puede separar los ceros de los unos. Por eso agregamos una **capa oculta con activacion ReLU**:
+
+```ruby
+require "grx"
+
+# Tabla de verdad XOR:
+# (0, 0) -> 0
+# (0, 1) -> 1
+# (1, 0) -> 1
+# (1, 1) -> 0
+entradas_xor = GRX.tensor([[0.0, 0.0], [0.0, 1.0], [1.0, 0.0], [1.0, 1.0]], [4, 2])
+salidas_xor  = GRX.tensor([[0.0], [1.0], [1.0], [0.0]], [4, 1])
+
+# Red neuronal multicapa: 2 entradas -> 4 ocultas (ReLU) -> 1 salida (Sigmoide)
+red_xor = GRX::NN::Sequential.new(
+  GRX::NN::Linear.new(2, 4),
+  GRX::NN::ReLU.new,
+  GRX::NN::Linear.new(4, 1),
+  GRX::NN::Sigmoid.new
+)
+
+opt = GRX::Optim::Adam.new(red_xor.parameters, lr: 0.05)
+loss_fn = GRX::Loss::BCELoss.new
+
+# Entrenamiento
+400.times do
+  opt.zero_grad
+  pred = red_xor.call(entradas_xor)
+  loss = loss_fn.call(pred, salidas_xor)
+  loss.backward
+  opt.step
+end
+
+puts "\n--- Predicciones de la Compuerta XOR ---"
+entradas_xor.to_a.each_slice(2).each_with_index do |(in1, in2), i|
+  muestra = GRX.tensor([[in1, in2]], [1, 2])
+  resultado = red_xor.call(muestra).item
+  puts "XOR(#{in1.to_i}, #{in2.to_i}) = #{resultado.round(3)} -> #{resultado >= 0.5 ? 1 : 0}"
+end
+```
 
 ---
 
-### Proyecto 1: El Predictor de Formulas (Regresion Lineal)
+### Proyecto 3: El Predictor de Formulas (Regresion Lineal)
 
 Aprende la relacion $y = 3x + 2$ usando `loss.backward` nativo.
 
@@ -452,7 +735,7 @@ puts "Prediccion para x=6 (esperado=20): #{modelo.call(test_x).to_a[0].round(3)}
 
 ---
 
-### Proyecto 2: Ajuste de Curvas No Lineales y Guardado en `.grx`
+### Proyecto 4: Ajuste de Curvas No Lineales y Guardado en `.grx`
 
 ```ruby
 require "grx"
@@ -496,7 +779,7 @@ puts "Inferencia x=11: #{modelo_nuevo.call(GRX.tensor([11.0], [1, 1])).to_a[0].r
 
 ---
 
-### Proyecto 3: Clasificador Binario Inteligente con BCELoss
+### Proyecto 5: Clasificador Binario Inteligente con BCELoss
 
 ```ruby
 require "grx"
@@ -527,7 +810,7 @@ puts "Resultados OR: #{clasificador.call(train_x).to_a.map { |v| v.round(4) }}"
 
 ---
 
-### Proyecto 4: Entrenamiento con Datasets Masivos (5,000 Filas con DataLoader)
+### Proyecto 6: Entrenamiento con Datasets Masivos (5,000 Filas con DataLoader)
 
 ```ruby
 require "grx"
@@ -577,7 +860,7 @@ puts "Error de Validacion MSE (5,000 muestras): #{val_loss.round(6)}"
 
 ---
 
-### Proyecto 5: Chatbot Financiero Inteligente con Base de Conocimiento y Filtro de Incertidumbre
+### Proyecto 7: Chatbot Financiero Inteligente con Base de Conocimiento y Filtro de Incertidumbre
 
 Este proyecto crea un agente de atencion al cliente que comprende intenciones mediante redes neuronales y recupera respuestas exactas de su memoria. Si una consulta es incomprensible o fuera de tema, lo reconoce honestamente:
 
@@ -744,7 +1027,7 @@ end
 
 ---
 
-## 13. Buenas Practicas y Errores Comunes
+## 14. Buenas Practicas y Errores Comunes
 
 1. **Llamar `opt.zero_grad` en cada iteracion:** Evita que los gradientes se acumulen indefinidamente.
 2. **Dimensiones compatibles:** Las capas lineales esperan siempre tensores 2D `[batch_size, num_features]`.
@@ -752,7 +1035,7 @@ end
 
 ---
 
-## 14. Glosario de Terminos Clave
+## 15. Glosario de Terminos Clave
 
 - **Shape:** Dimensiones del tensor (ej. `[10, 4]` -> 10 filas, 4 columnas).
 - **Numel:** Total de elementos del tensor.