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

# 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

# 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

# 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)