refactor(v0.4.0): caches externos, from_logits, JSON+NPZ, shape fail-fast

BREAKING CHANGE: refactor arquitectónico que resuelve los 5 riesgos
estructurales de v0.3 identificados en el code review.

Arreglos:

- [#1] Acoplamiento matemático oculto CCE↔Softmax:
  * Softmax.backward ahora implementa el Jacobiano-vector completo
    (s * (d_output - sum(d_output * s))). Matemáticamente correcto
    con cualquier función de pérdida.
  * BinaryCrossEntropy y CategoricalCrossEntropy aceptan from_logits.
    Con from_logits=True: capa final Linear, loss aplica sigmoid/
    softmax internamente con el atajo estable (pred - y) / N.
  * Eliminada la suposición silenciosa 'la capa previa es Softmax'.

- [#2] Estado mutable en capas:
  * forward(x, training) -> (output, cache). Las capas ya NO guardan
    self.inputs / self.z. El cache viaja explícitamente.
  * backward(d_output, cache) -> (d_input, grads_dict).
  * Activaciones también stateless: forward -> (out, cache).
  * Habilita arquitecturas multi-entrada (siamesas, triplet loss)
    con pesos compartidos sin corromperse.

- [#3] Serialización pickle-frágil:
  * save(directory) produce topology.json + weights.npz.
  * JSON es legible, no ejecutable, sobrevive a refactors.
  * NPZ es formato NumPy estándar, incluye estado no entrenable
    (running_mean/running_var de BatchNorm).
  * get_config / from_config en TODOS los componentes (layers,
    optimizers, losses, activations, initializers, regularizers,
    metrics).
  * save_model/load_model (pickle) mantenidos con warning.

- [#4] Inferencia de shapes tardía:
  * NeuralNetwork.build(input_shape) propaga shapes a lo largo de
    toda la red y valida compatibilidad ANTES de entrenar.
  * Se invoca automáticamente en compile() si la primera capa tiene
    input_size definido, o en fit() como fallback.
  * Cada capa tiene input_shape / output_shape accesibles.
  * Mismatches dimensionales fallan fail-fast con mensaje claro.

- [#5] Fugas de abstracción en optimizadores:
  * Capas: parameters() -> Dict[str, ndarray] con nombres arbitrarios.
  * Optimizer.apply_gradients(list_of_tuples) donde cada tupla es
    (layer_id, param_name, param_ref, grad). No conoce 'weights' ni
    'biases' hardcodeados.
  * BatchNormalization declara {'gamma', 'beta'} como parámetros
    entrenables y {'running_mean', 'running_var'} como estado no
    entrenable. Se eliminan los @Property falsos que 'engañaban' al
    optimizer en v0.3.
  * Capas futuras pueden tener N parámetros con cualquier nombre
    sin tocar el código de los optimizers.

Nuevo:
- examples/siamese_network.py: encoder con pesos compartidos que
  demuestra state isolation entre forwards intercalados.
- tests/test_activations.py: valida stateless y Jacobiano de Softmax
  contra gradiente numérico.
- tests/test_gradient_check.py: ahora cubre Softmax+CCE con Jacobiano
  real y el camino Linear+CCE(from_logits=True).
- 68 tests (antes 51).

Migración desde v0.3:

# Persistencia
- model.save_model('file.pkl')          ->  model.save('dir/')
- NeuralNetwork.load_model('file.pkl')  ->  NeuralNetwork.load('dir/')

# Clasificación (path recomendado, numéricamente estable)
- Dense(n_classes, activation='softmax')    ->  Dense(n_classes, activation='linear')
- loss='cce'                                ->  CategoricalCrossEntropy(from_logits=True)
- probs = model.predict(X)                  ->  logits = model.predict(X)
                                                probs = softmax(logits)

# API de capas
- layer.get_params()                    ->  layer.parameters()       (dict)
- output = layer.forward(x)             ->  output, cache = layer.forward(x)
- d_in = layer.backward(d_out)          ->  d_in, grads = layer.backward(d_out, cache)

# API de optimizadores
- optimizer.update(layers)              ->  optimizer.apply_gradients(grad_tuples)
  (el modelo lo maneja internamente; usuarios de fit() no se ven afectados)

Los archivos .pkl de v0.3 no son compatibles. Re-entrenar y guardar
con model.save('dir/') para persistencia portable futura.

Resultados:
- XOR: 100% accuracy (path from_logits estable)
- Multiclass blobs: 100% test accuracy con BatchNorm + Dropout + callbacks
- Siamese encoder: converge con pesos compartidos (loss 0.34 -> 0.005)
- Gradient check: todos los caminos validados numéricamente

Author: elJulioDev

README.md

@@ -1,30 +1,27 @@
 """
-Demo avanzado: clasificación multiclase con dataset sintético.
-
-Muestra:
-- BatchNormalization y Dropout combinados.
-- Optimizer Adam con gradient clipping.
-- Regularización L2 sobre los pesos.
-- validation_split para monitorear sobreajuste.
-- EarlyStopping y ReduceLROnPlateau.
-- Predicción y evaluación final.
+Demo multiclase con BatchNorm, Dropout, callbacks y from_logits.
+
+- Capa final Linear + CategoricalCrossEntropy(from_logits=True):
+  camino numéricamente estable que evita el acoplamiento Softmax/Loss.
+- L2 regularización, gradient clipping, EarlyStopping, ReduceLROnPlateau.
+- save(dir) + load(dir) con topology JSON + pesos NPZ.
 """
 import os
 import sys
+import tempfile
 import numpy as np
 
 sys.path.insert(0, os.path.abspath(os.path.join(os.path.dirname(__file__), "..")))
 
 from src import (
     NeuralNetwork, Dense, Dropout, BatchNormalization,
-    Adam, L2,
+    Adam, L2, CategoricalCrossEntropy,
     EarlyStopping, ReduceLROnPlateau,
     train_test_split, to_categorical, standardize,
 )
 
 
-def make_blobs(n_per_class: int = 200, n_features: int = 4, n_classes: int = 3, seed: int = 0):
-    """Genera clusters gaussianos en distintos centros (dataset sintético)."""
+def make_blobs(n_per_class=300, n_features=8, n_classes=4, seed=0):
     rng = np.random.default_rng(seed)
     centers = rng.uniform(-5, 5, size=(n_classes, n_features))
     X, y = [], []
@@ -37,50 +34,55 @@ def make_blobs(n_per_class: int = 200, n_features: int = 4, n_classes: int = 3,
 def main():
     np.random.seed(0)
 
-    # Datos
     X, y = make_blobs(n_per_class=300, n_features=8, n_classes=4, seed=0)
     X = standardize(X)
     y_oh = to_categorical(y, num_classes=4)
+    X_train, X_test, y_train, y_test = train_test_split(X, y_oh, test_size=0.2, random_state=0)
 
-    X_train, X_test, y_train, y_test = train_test_split(
-        X, y_oh, test_size=0.2, random_state=0
-    )
-
-    # Modelo profundo con regularización
+    # Capa final 'linear' — la loss aplica softmax internamente
     model = NeuralNetwork()
     model.add(Dense(32, input_size=8, activation="relu", kernel_regularizer=L2(0.001)))
     model.add(BatchNormalization(32))
     model.add(Dropout(0.2))
     model.add(Dense(16, activation="relu", kernel_regularizer=L2(0.001)))
     model.add(Dropout(0.2))
-    model.add(Dense(4, activation="softmax"))
+    model.add(Dense(4, activation="linear"))  # logits
 
     model.compile(
         optimizer=Adam(learning_rate=0.01, clip_norm=1.0),
-        loss="cce",
-        metrics=["categorical_accuracy"],
+        loss=CategoricalCrossEntropy(from_logits=True),
     )
     model.summary()
 
-    # Callbacks
     callbacks = [
         EarlyStopping(monitor="val_loss", patience=15, restore_best_weights=True),
         ReduceLROnPlateau(monitor="val_loss", factor=0.5, patience=5),
     ]
 
-    # Entrenar
-    history = model.fit(
+    model.fit(
         X_train, y_train,
-        epochs=100,
-        batch_size=32,
+        epochs=100, batch_size=32,
         validation_split=0.2,
         callbacks=callbacks,
         verbose=1,
     )
 
-    # Evaluar en test set
-    print("\n--- Test set ---")
-    model.evaluate(X_test, y_test)
+    # Evaluación: necesitamos accuracy, así que aplicamos softmax manualmente
+    logits_test = model.predict(X_test)
+    probs = np.exp(logits_test - logits_test.max(axis=1, keepdims=True))
+    probs = probs / probs.sum(axis=1, keepdims=True)
+    acc = np.mean(np.argmax(probs, axis=1) == np.argmax(y_test, axis=1))
+    print(f"\n--- Test accuracy: {acc:.4f}")
+
+    # Persistencia portable
+    with tempfile.TemporaryDirectory() as tmp:
+        path = os.path.join(tmp, "multiclass_model")
+        model.save(path)
+        print(f"Modelo guardado en {path}/")
+        loaded = NeuralNetwork.load(path)
+        loaded_logits = loaded.predict(X_test)
+        assert np.allclose(logits_test, loaded_logits)
+        print("save/load JSON+NPZ: OK")
 
 
 if __name__ == "__main__":

examples/multiclass_classification.py

@@ -1,24 +1,69 @@
-# Nuevo main.py de ejemplo
+"""
+Demo XOR — v0.4.
+
+Muestra el camino recomendado de producción:
+- capa final 'linear' + BinaryCrossEntropy(from_logits=True).
+  Es numéricamente estable y evita el acoplamiento Softmax/Loss.
+- build() propaga shapes antes de entrenar (fail-fast).
+- save() genera topology.json + weights.npz sin pickle.
+"""
+import os
+import tempfile
 import numpy as np
-from src.neural_network import NeuralNetwork
-from src.activations import LeakyReLU, Sigmoid
-from src.losses import BinaryCrossEntropy
-from src.optimizers import SGD
+
+from src import (
+    NeuralNetwork, Dense,
+    Adam, BinaryCrossEntropy,
+    EarlyStopping,
+)
+
+
+def main():
+    np.random.seed(42)
+
+    X = np.array([[0, 0], [0, 1], [1, 0], [1, 1]], dtype=float)
+    y = np.array([[0], [1], [1], [0]], dtype=float)
+
+    model = NeuralNetwork()
+    model.add(Dense(8, input_size=2, activation="relu"))
+    model.add(Dense(1, activation="linear"))   # logits
+
+    model.compile(
+        optimizer=Adam(learning_rate=0.05),
+        loss=BinaryCrossEntropy(from_logits=True),
+        metrics=[],
+    )
+
+    model.summary()
+
+    model.fit(
+        X, y,
+        epochs=500,
+        batch_size=4,
+        callbacks=[EarlyStopping(monitor="loss", patience=50)],
+        verbose=0,
+    )
+
+    # Inferencia: aplicar sigmoid al logit
+    logits = model.predict(X)
+    probs = 1.0 / (1.0 + np.exp(-logits))
+
+    print("\n--- Predicciones ---")
+    for i in range(len(X)):
+        print(
+            f"Input: {X[i]}, Esperado: {int(y[i, 0])}, "
+            f"Prob: {float(probs[i, 0]):.4f}, "
+            f"Clase: {int(probs[i, 0] >= 0.5)}"
+        )
+
+    # Persistencia portable (JSON + NPZ)
+    with tempfile.TemporaryDirectory() as tmp:
+        path = os.path.join(tmp, "xor_model")
+        model.save(path)
+        loaded = NeuralNetwork.load(path)
+        assert np.allclose(model.predict(X), loaded.predict(X))
+        print("\nsave/load JSON+NPZ: OK")
+
 
 if __name__ == "__main__":
-    X = np.array([[0,0], [0,1], [1,0], [1,1]])
-    y = np.array([[0], [1], [1], [0]])
-
-    # Definimos optimizador con Momentum (Acelera el entrenamiento)
-    optimizer = SGD(learning_rate=0.1, momentum=0.9)
-    
-    nn = NeuralNetwork(loss_function=BinaryCrossEntropy(), optimizer=optimizer)
-    
-    # Arquitectura
-    nn.add_layer(num_neurons=4, input_size=2, activation=LeakyReLU())
-    nn.add_layer(num_neurons=1, activation=Sigmoid())
-    
-    # Entrenar (Batch size 4 es todo el dataset en este caso pequeño)
-    nn.train(X, y, epochs=100000, batch_size=4)
-    
-    print(nn.predict(X))
+    main()

main.py

@@ -8,33 +8,23 @@
 
 setup(
     name="NeuralNetwork",
-    version="0.3.0",
+    version="0.4.0",
     packages=find_packages(),
-    install_requires=[
-        "numpy>=1.21.0",
-    ],
-    extras_require={
-        "dev": [
-            "matplotlib>=3.5.0",
-            "python-dotenv",
-        ],
-    },
+    install_requires=["numpy>=1.21.0"],
+    extras_require={"dev": ["matplotlib>=3.5.0", "python-dotenv"]},
     author="elJulioDev",
-    description="Librería de Deep Learning vectorizada con API estilo Keras",
+    description="Deep Learning vectorizado con API Keras, caches externos y persistencia portable",
     long_description=long_description,
     long_description_content_type="text/markdown",
     python_requires=">=3.8",
     classifiers=[
         "Programming Language :: Python :: 3",
         "Programming Language :: Python :: 3.8",
-        "Programming Language :: Python :: 3.9",
         "Programming Language :: Python :: 3.10",
-        "Programming Language :: Python :: 3.11",
         "Programming Language :: Python :: 3.12",
         "License :: OSI Approved :: MIT License",
         "Operating System :: OS Independent",
         "Topic :: Scientific/Engineering :: Artificial Intelligence",
-        "Topic :: Software Development :: Libraries :: Python Modules",
         "Intended Audience :: Developers",
         "Intended Audience :: Science/Research",
     ],

setup.py

@@ -1,123 +1,65 @@
-"""
-NeuralNetwork - librería de Deep Learning vectorizada.
-
-Exports principales para uso ergonómico:
-    from src import NeuralNetwork, Dense, Dropout, Adam, ...
-"""
+"""NeuralNetwork v0.4 — librería de Deep Learning vectorizada."""
 from .neural_network import NeuralNetwork
 
 from .layer import (
-    BaseLayer,
-    Layer,
-    Dense,
-    Dropout,
-    BatchNormalization,
+    BaseLayer, Layer, Dense, Dropout, BatchNormalization, layer_from_config,
 )
 
 from .activations import (
-    Activation,
-    Sigmoid,
-    ReLU,
-    LeakyReLU,
-    ELU,
-    Tanh,
-    Softmax,
-    Linear,
+    Activation, Sigmoid, ReLU, LeakyReLU, ELU, Tanh, Softmax, Linear,
     get_activation,
 )
 
 from .losses import (
-    Loss,
-    MSE,
-    MAE,
-    Huber,
-    BinaryCrossEntropy,
-    CategoricalCrossEntropy,
-    SparseCategoricalCrossEntropy,
+    Loss, MSE, MAE, Huber,
+    BinaryCrossEntropy, CategoricalCrossEntropy, SparseCategoricalCrossEntropy,
     get_loss,
 )
 
 from .optimizers import (
-    Optimizer,
-    SGD,
-    AdaGrad,
-    RMSprop,
-    Adam,
-    get_optimizer,
+    Optimizer, SGD, AdaGrad, RMSprop, Adam, get_optimizer,
 )
 
 from .initializers import (
-    Initializer,
-    HeNormal,
-    XavierNormal,
-    XavierUniform,
-    Zeros,
-    Ones,
+    Initializer, HeNormal, XavierNormal, XavierUniform, Zeros, Ones,
     get_initializer,
 )
 
 from .regularizers import (
-    Regularizer,
-    L1,
-    L2,
-    L1L2,
-    get_regularizer,
+    Regularizer, L1, L2, L1L2, get_regularizer,
 )
 
 from .metrics import (
-    Metric,
-    BinaryAccuracy,
-    CategoricalAccuracy,
-    SparseCategoricalAccuracy,
-    MeanAbsoluteError,
-    RootMeanSquaredError,
-    R2Score,
-    get_metric,
+    Metric, BinaryAccuracy, CategoricalAccuracy, SparseCategoricalAccuracy,
+    MeanAbsoluteError, RootMeanSquaredError, R2Score, get_metric,
 )
 
 from .callbacks import (
-    Callback,
-    History,
-    EarlyStopping,
-    ModelCheckpoint,
-    ReduceLROnPlateau,
+    Callback, History, EarlyStopping, ModelCheckpoint, ReduceLROnPlateau,
 )
 
 from .utils import (
-    train_test_split,
-    to_categorical,
-    normalize,
-    standardize,
-    shuffle_arrays,
-    batch_iterator,
+    train_test_split, to_categorical, normalize, standardize,
+    shuffle_arrays, batch_iterator,
 )
 
-__version__ = "0.3.0"
+__version__ = "0.4.0"
 
 __all__ = [
     "NeuralNetwork",
-    # Layers
-    "BaseLayer", "Layer", "Dense", "Dropout", "BatchNormalization",
-    # Activations
+    "BaseLayer", "Layer", "Dense", "Dropout", "BatchNormalization", "layer_from_config",
     "Activation", "Sigmoid", "ReLU", "LeakyReLU", "ELU", "Tanh", "Softmax", "Linear",
     "get_activation",
-    # Losses
     "Loss", "MSE", "MAE", "Huber",
     "BinaryCrossEntropy", "CategoricalCrossEntropy", "SparseCategoricalCrossEntropy",
     "get_loss",
-    # Optimizers
     "Optimizer", "SGD", "AdaGrad", "RMSprop", "Adam", "get_optimizer",
-    # Initializers
     "Initializer", "HeNormal", "XavierNormal", "XavierUniform", "Zeros", "Ones",
     "get_initializer",
-    # Regularizers
     "Regularizer", "L1", "L2", "L1L2", "get_regularizer",
-    # Metrics
     "Metric", "BinaryAccuracy", "CategoricalAccuracy", "SparseCategoricalAccuracy",
     "MeanAbsoluteError", "RootMeanSquaredError", "R2Score", "get_metric",
-    # Callbacks
     "Callback", "History", "EarlyStopping", "ModelCheckpoint", "ReduceLROnPlateau",
-    # Utils
     "train_test_split", "to_categorical", "normalize", "standardize",
     "shuffle_arrays", "batch_iterator",
 ]