dovrebbe convergere su mnist, da completare con persistenza e visualizzatore

AGENTS.md

@@ -1,47 +1,45 @@
 # AGENTS.md - Agentic Coding Guidelines
 
 ## Project Overview
-C-based neural network implementation from scratch for image classification on CIFAR-10 and MNIST datasets.
+C-based neural network implementation from scratch for image classification on MNIST and CIFAR-10 datasets. Uses header-only library design with `percettroni.h`.
 
 ## Build Commands
 
 ### Compilation
 ```bash
-# Main classifier (MNIST) - compiles the single-classifier training program
-gcc -o classificatore_singolo_mnist classificatore_singolo.c -lm
+# Main classifier (MNIST) - multi-class classifier (default)
+gcc -o classificatore_mnist classificatore.c -lm
 
-# XOR test/demo - simple test to verify neural network works
-gcc -o codice_ricordo codice_ricordo.c -lm
+# XOR test - quick validation that neural network converges
+# Change percettroni.h: uncomment `#include "xor_manager.h"` and comment out MNIST include
+gcc -o classificatore_xor classificatore.c -lm
 
 # Visualizer (requires Allegro library)
 gcc -o visualizzatore visualizzatore.c -lalleg -lm
 
-# Older multi-layer implementation
-gcc -o rete_neurale rete_neurale.c -lm
+# Training with pre-trained weights
+./classificatore_mnist_50_epoche
 ```
 
 ### Running Tests
 ```bash
-# Run XOR validation test (quick sanity check for neural network)
-./codice_ricordo
+# Quick test - compile and run MNIST classifier
+gcc -o classificatore_mnist classificatore.c -lm && ./classificatore_mnist
 
-# Run full training loop with existing compiled binary
-./classificatore_singolo_mnist
+# Memory leak detection
+valgrind --leak-check=full ./classificatore_mnist
 
-# Automated training with pauses (prevents overheating)
-./addestratore.sh
-
-# Memory leak detection (valgrind)
-valgrind --leak-check=full ./codice_ricordo
+# Run pre-compiled binary (50 epochs)
+./classificatore_mnist_50_epoche
 ```
 
 ### Running a Single Test
 ```bash
-# Compile and run XOR test (single test case)
-gcc -o codice_ricordo codice_ricordo.c -lm && ./codice_ricordo
+# Compile and run MNIST classifier (single test)
+gcc -o classificatore_mnist classificatore.c -lm && ./classificatore_mnist
 
-# Compile and run classifier with specific category
-gcc -o classificatore_singolo_mnist classificatore_singolo.c -lm && ./classificatore_singolo_mnist
+# For XOR test - edit percettroni.h first, then:
+gcc -o test_xor classificatore.c -lm && ./test_xor
 ```
 
 ## Code Style Guidelines
@@ -63,8 +61,8 @@ gcc -o classificatore_singolo_mnist classificatore_singolo.c -lm && ./classifica
 - Functions: `snake_case` (e.g., `inizializza_rete_neurale`)
 - Structs: `PascalCase` (e.g., `ReteNeurale`)
 - Constants: `UPPER_SNAKE_CASE` (e.g., `EPOCHE`)
-- Global variables: file scope preferred
 - Types: use `typedef` for structs
+- Global variables: file scope preferred
 
 ### Types
 - Use `byte` (typedef for `unsigned char`) for values 0-255
@@ -75,7 +73,6 @@ gcc -o classificatore_singolo_mnist classificatore_singolo.c -lm && ./classifica
 ### Imports
 - Standard library headers first (`<stdio.h>`, `<stdlib.h>`, `<math.h>`, `<time.h>`)
 - Project headers after (use `"quotes"`)
-- No include guards needed for header-only library
 - Group related includes together
 
 ### Memory Management
@@ -90,67 +87,60 @@ gcc -o classificatore_singolo_mnist classificatore_singolo.c -lm && ./classifica
 - Exit with `EXIT_FAILURE` on unrecoverable errors
 - Validate function inputs at entry points
 
-### Key Constants (from percettroni.h)
-- `LRE = 0.1` (learning rate - was 1.414, now 0.1)
-- `soglia_sigmoide = 0.5` (sigmoid threshold for binary classification)
+## Key Constants (from percettroni.h)
+- `LRE = 0.1` (learning rate)
+- `soglia_sigmoide = 0.5` (sigmoid threshold)
 - `file_pesi = "rete_pesi.bin"` (model weights file)
+- `SOFTMAX = 1` (use softmax for multi-class prediction)
 
-### Dataset Configuration
-In `percettroni.h`, uncomment the desired dataset section:
-- XOR: `#include "xor_manager.h"` (for testing - currently active)
-- MNIST: Uncomment mnist includes and set file paths
-- CIFAR-10: Uncomment cifar-10 includes and file paths
+## Dataset Configuration
+In `percettroni.h`, include the desired dataset manager:
+- MNIST: `#include "mnist/mnist_manager.h"` (currently active)
+- XOR: `#include "xor_manager.h"` (for testing)
+- CIFAR-10: `#include "cifar-10/cifar10_manager.h"`
 
 ## Testing
 No formal test framework. Use these approaches:
-1. `codice_ricordo.c` - XOR validation (4 inputs, quick convergence test)
-2. Visual inspection of weight outputs via `stampa_pesi_rete()`
+1. `xor_manager.h` - XOR validation (quick convergence test)
+2. Visual inspection via `stampa_pesi_rete()`
 3. Monitor epoch error rates in training output
-4. Check for memory leaks with valgrind
+4. Check memory leaks with valgrind
 
 ## Project Structure
-- `percettroni.h` - Core neural network (header-only library with implementations)
-- `classificatore_singolo.c` - Single-category classifier main program
-- `codice_ricordo.c` - XOR test/demo
-- `xor_manager.h` - XOR dataset for testing
+- `percettroni.h` - Core neural network (header-only library)
+- `classificatore.c` - Main classifier program
+- `xor_manager.h` - XOR dataset (4 samples)
 - `mnist/mnist_manager.h` - MNIST dataset loader
 - `cifar-10/cifar10_manager.h` - CIFAR-10 dataset loader
 - `rete_pesi.bin` - Saved model weights
-- `addestratore.sh` - Training automation script
+- `visualizzatore.c` - Image visualizer (requires Allegro)
 
 ## Neural Network Architecture
 - Activation: sigmoid function
 - Training: backpropagation with gradient descent
+- Prediction: softmax for multi-class, sigmoid threshold for binary
 - Configurable: layer count and perceptrons per layer
 - Learning rate: controlled via `LRE` constant (default 0.1)
-- Binary threshold: 0.5 for classification decisions
 
 ## Development Workflow
 
-### Adding a New Dataset
+### Adding a Dataset
 1. Create manager header (e.g., `custom_manager.h`)
-2. Define `N_INPUTS` constant for input size
+2. Define `N_INPUTS` constant
 3. Implement `get_dataset()` returning `Dataset*`
-4. Update `percettroni.h` includes and file paths
+4. Update `percettroni.h` includes
 
 ### Debugging Tips
 - Call `stampa_pesi_rete(rete)` to inspect weights
-- Reference `codice_ricordo.c` for minimal working example
-- Verify dataset loading before training loop
+- Reference `xor_manager.h` for minimal working example
 - Check epoch timing to monitor training progress
 
-### File I/O
-- Weights saved as binary in `rete_pesi.bin`
-- Use `salvaReteNeurale()` and `caricaReteNeurale()` for persistence
-- Dataset files must match expected binary format
-
 ## Performance Notes
-- Training is CPU-intensive (minutes per epoch expected)
-- Use `addestratore.sh` with sleep intervals to prevent overheating
-- Memory allocated dynamically based on network architecture
+- Training is CPU-intensive (minutes per epoch)
 - No GPU acceleration - pure CPU implementation
+- Pre-compiled binary available for quick testing
 
 ## Language Reference
-Technical terms (English): activation function, gradient descent, sigmoid, neural network, backpropagation
+Technical terms (English): activation function, gradient descent, sigmoid, neural network, backpropagation, softmax
 
-Italian terms: pesi (weights), bias, livello (layer), percettrone (perceptron), addestramento (training), epoca (epoch), errore (error), classificazione (label/classification), previsione (prediction), istanza (instance)
+Italian terms: pesi (weights), bias, livello (layer), percettrone (perceptron), addestramento (training), epoca (epoch), errore (error), classificazione (label), previsione (prediction), istanza (instance)