docs: update AGENTS.md with callbacks, utils, logging convention

Author: elJulioDev

AGENTS.md

@@ -0,0 +1,64 @@
+# AGENTS.md
+
+Python/NumPy deep learning library (v1.0.0). Pure NumPy, no CUDA or PyTorch.
+
+## Commands
+
+```bash
+# Run all tests (unittest, not pytest)
+python -m unittest discover tests -v
+
+# Run a single test file
+python -m unittest tests.test_layer -v
+
+# Run a single test case
+python -m unittest tests.test_losses.TestLosses.test_mse -v
+
+# Demo scripts
+python main.py
+python examples/multiclass_classification.py
+python examples/siamese_network.py
+
+# Install in editable mode
+pip install -e .
+
+# Install with dev tools (ruff, matplotlib)
+pip install -e ".[dev]"
+
+# Lint
+ruff check nnlib/ tests/
+```
+
+## Architecture
+
+All source code lives in `nnlib/`. The public API is re-exported from `nnlib/__init__.py`.
+
+- `nnlib/neural_network.py` — `NeuralNetwork` class: model assembly, `compile()`, `fit()`, `predict()`, `save()/load()` (topology.json + weights.npz)
+- `nnlib/layer.py` — `Dense`, `Dropout`, `BatchNormalization`. Interface: `forward(x) -> (output, cache)`, `backward(d_output, cache) -> (d_input, grads_dict)`, `parameters() -> Dict[str, ndarray]`
+- `nnlib/activations.py` — Stateless activations. Same forward/backward cache pattern.
+- `nnlib/losses.py` — Losses. `BinaryCrossEntropy` and `CategoricalCrossEntropy` accept `from_logits=True`.
+- `nnlib/optimizers.py` — `SGD`, `AdaGrad`, `RMSprop`, `Adam`. Interface: `apply_gradients(list_of_tuples)`. They do not know about `weights`/`biases` names.
+- `nnlib/callbacks.py` — `EarlyStopping`, `ReduceLROnPlateau`, `ModelCheckpoint`, `History`. Uses `logging` module, not `print()`.
+- `nnlib/utils.py` — `train_test_split`, `shuffle_arrays`, `batch_iterator`, `to_categorical`, `normalize`, `standardize`.
+- `examples/siamese_network.py` — Standalone demo, not part of the library API. Imports directly from `nnlib.layer`/`nnlib.activations`.
+
+## Key conventions
+
+- **Layers are stateless w.r.t. trainable state.** Caches are returned from `forward()`, never stored on `self`. This is critical for siamese/shared-weight architectures.
+- **`from_logits=True` is the recommended pattern.** Final layer uses `activation='linear'`, loss applies softmax/sigmoid internally with a numerically stable shortcut.
+- **Persist via `save(dir)`/`load(dir)`** → `topology.json` + `weights.npz`. Do NOT use pickle (`save_model()`).
+- **`build()` is called by `compile()`**, not `fit()`. Shape mismatches fail immediately at compile time.
+- **Parameter interface is generic.** Layers expose `parameters() -> Dict[str, ndarray]` with arbitrary key names. Optimizers consume these without knowing internal structure.
+- **Use `logging`, not `print()`.** Training output goes through `logging.getLogger("neural_network")`. Callbacks use `logging.getLogger("neural_network.callbacks")`.
+- **`requirements.txt` is a redirect.** The real dependency spec is in `pyproject.toml`. `requirements.txt` just points to `pip install -e .`.
+
+## Tests
+
+68 tests using `unittest` (no pytest). Key test files:
+
+- `test_gradient_check.py` — Numerical gradient validation for backprop correctness
+- `test_model.py` — Integration tests + JSON/NPZ persistence roundtrip
+- `test_layer.py` — Includes state isolation test for shared-weight forward calls
+- `test_losses.py` — Covers `from_logits` paths
+
+Run all before pushing. No coverage tool configured.