classificatore_immagini/AGENTS.md

# AGENTS.md - Agentic Coding Guidelines

## Project Overview
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) - multi-class classifier (default)
gcc -o classificatore_mnist classificatore.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

# Training with pre-trained weights
./classificatore_mnist_50_epoche
```

### Running Tests
```bash
# Quick test - compile and run MNIST classifier
gcc -o classificatore_mnist classificatore.c -lm && ./classificatore_mnist

# Memory leak detection
valgrind --leak-check=full ./classificatore_mnist

# Run pre-compiled binary 
./classificatore
```

### Running a Single Test
```bash
# Compile and run MNIST classifier (single test)
gcc -o classificatore_mnist classificatore.c -lm && ./classificatore_mnist

# For XOR test - edit percettroni.h first, then:
gcc -o test_xor classificatore.c -lm && ./test_xor
```

## Code Style Guidelines

### Language
- Use **Italian** for comments and variable names (maintain consistency)
- Use **English** for struct/type definitions and technical terms

### Formatting
- Indent with 4 spaces (no tabs)
- Opening braces on same line: `if (cond) {`
- Always use braces for control structures, even single lines
- Line length: ~80-100 characters preferred
- One space after keywords (if, for, while, return)
- No space between function name and opening parenthesis
- Blank line between functions

### Naming Conventions
- Functions: `snake_case` (e.g., `inizializza_rete_neurale`)
- Structs: `PascalCase` (e.g., `ReteNeurale`)
- Constants: `UPPER_SNAKE_CASE` (e.g., `EPOCHE`)
- Types: use `typedef` for structs
- Global variables: file scope preferred

### Types
- Use `byte` (typedef for `unsigned char`) for values 0-255
- Use `double` for all floating-point calculations
- Prefer explicit types over implicit conversions
- Use `size_t` for sizes and indices where appropriate

### Imports
- Standard library headers first (`<stdio.h>`, `<stdlib.h>`, `<math.h>`, `<time.h>`)
- Project headers after (use `"quotes"`)
- Group related includes together

### Memory Management
- Always check `malloc` return values
- Free memory in reverse allocation order
- Use `perror()` for error messages before exiting
- Avoid memory leaks in loops

### Error Handling
- Check file operations with `if (!file)` pattern
- Return `NULL` on failure for functions returning pointers
- Exit with `EXIT_FAILURE` on unrecoverable errors
- Validate function inputs at entry points

## Key Constants (from percettroni.h)
- `LRE = 0.01` (learning rate)
- `soglia_sigmoide = 0.5` (sigmoid threshold)
- `file_pesi = "rete_mnist.bin"` (model weights file)
- `TOLLERANZA = 99.5` (accuracy tolerance for early stopping)
- `FUNZIONE_ATTIVAZIONE = 1` (0=sigmoid, 1=ReLU, 2=step function)

## 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. `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 memory leaks with valgrind

## Linting and Type Checking
No formal linting or type checking tools are configured for this C project. Code quality is maintained through:
- Manual code review
- Compilation warnings (use `-Wall -Wextra` flags if needed)
- Valgrind for memory issues
- Consistent adherence to the style guidelines below

## Project Structure
- `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
- `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)

## Development Workflow

### Adding a Dataset
1. Create manager header (e.g., `custom_manager.h`)
2. Define `N_INPUTS` constant
3. Implement `get_dataset()` returning `Dataset*`
4. Update `percettroni.h` includes

### Debugging Tips
- Call `stampa_pesi_rete(rete)` to inspect weights
- Reference `xor_manager.h` for minimal working example
- Check epoch timing to monitor training progress

## Performance Notes
- 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, softmax

Italian terms: pesi (weights), bias, livello (layer), percettrone (perceptron), addestramento (training), epoca (epoch), errore (error), classificazione (label), previsione (prediction), istanza (instance)