147 lines
5.1 KiB
Markdown
147 lines
5.1 KiB
Markdown
# 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 (50 epochs)
|
|
./classificatore_mnist_50_epoche
|
|
```
|
|
|
|
### 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.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`, 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
|
|
|
|
## 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)
|