|
1 | | -<section class="neat-hero"> |
2 | | - <div> |
3 | | - <p class="neat-eyebrow">Keras-first optimizer library</p> |
4 | | - <h1 class="neat-title">Nash-Equilibrium Adaptive Training</h1> |
5 | | - <p class="neat-lede"> |
6 | | - NEAT adds conflict-aware gradient correction to neural network training. |
7 | | - Use it as a Keras 3 optimizer, validate the update rule in NumPy, and |
8 | | - inspect training diagnostics while experiments run. |
9 | | - </p> |
10 | | - <div class="neat-actions"> |
11 | | - <a class="neat-button neat-button-primary" href="quickstart/">Quickstart</a> |
12 | | - <a class="neat-button" href="api/">API Reference</a> |
13 | | - <a class="neat-button" href="research/math-spec/">Math Spec</a> |
14 | | - </div> |
15 | | - </div> |
16 | | - <div class="neat-panel"> |
17 | | - |
18 | | -```python |
19 | | -import keras |
20 | | -from neat_optim import NEAT |
21 | | - |
22 | | -model.compile( |
23 | | - optimizer=NEAT(learning_rate=1e-3), |
24 | | - loss=keras.losses.SparseCategoricalCrossentropy(from_logits=True), |
25 | | -) |
26 | | -``` |
27 | | - |
28 | | - </div> |
29 | | -</section> |
30 | | - |
31 | | -<section class="neat-grid"> |
32 | | - <div class="neat-card"> |
33 | | - <h3>Keras Optimizer</h3> |
34 | | - <p>Drop NEAT into <code>model.compile(...)</code> for standard Keras training workflows.</p> |
35 | | - </div> |
36 | | - <div class="neat-card"> |
37 | | - <h3>Reference Engine</h3> |
38 | | - <p>Use the NumPy implementation for deterministic validation and algorithm research.</p> |
39 | | - </div> |
40 | | - <div class="neat-card"> |
41 | | - <h3>Player-Aware Mode</h3> |
42 | | - <p>Treat examples or tasks as gradient players in custom TensorFlow loops.</p> |
43 | | - </div> |
44 | | -</section> |
45 | | - |
46 | | -## Install |
47 | | - |
48 | | -```bash |
49 | | -pip install "neat-optim[keras]" tensorflow |
50 | | -``` |
51 | | - |
52 | | -Core engine only: |
53 | | - |
54 | | -```bash |
55 | | -pip install neat-optim |
56 | | -``` |
57 | | - |
58 | | -## Docs |
59 | | - |
60 | | -- [Quickstart](quickstart.md): installation and first training examples |
61 | | -- [API](api.md): public objects, configuration, and diagnostics |
62 | | -- [Research](research/math-spec.md): update equations and algorithm notes |
63 | | -- [Contributing](contributing/development.md): development and release workflow |
| 1 | +# NEAT |
| 2 | + |
| 3 | +NEAT is a Keras-first optimizer library built around a Nash-inspired gradient |
| 4 | +conflict correction term. The repository is structured so the update rule can |
| 5 | +be reasoned about independently of Keras, validated in NumPy, and optionally |
| 6 | +accelerated with a native CPU extension. |
| 7 | + |
| 8 | +The package now exposes two distinct usage styles: |
| 9 | + |
| 10 | +- standard NEAT for aggregated batch gradients through the Keras optimizer API |
| 11 | +- player-aware NEAT for explicit per-example or per-task gradients in a custom |
| 12 | + TensorFlow training loop |
| 13 | + |
| 14 | +The repository also includes benchmark diagnostics and a NEAT sweep harness so |
| 15 | +optimizer changes can be measured instead of argued from theory alone. |
| 16 | + |
| 17 | +## Design Goals |
| 18 | + |
| 19 | +- Keep the public API small and production-friendly. |
| 20 | +- Keep the optimizer math explicit and versioned. |
| 21 | +- Keep the core testable outside any single deep-learning framework. |
| 22 | +- Keep native acceleration behind the same semantics as the reference engine. |
| 23 | + |
| 24 | +## Package Layers |
| 25 | + |
| 26 | +1. `docs/research/math-spec.md` |
| 27 | + The versioned mathematical contract for the update rule. |
| 28 | +2. `src/neat_optim/engine/reference.py` |
| 29 | + The canonical NumPy implementation used for correctness validation. |
| 30 | +3. `src/neat_optim/engine/native.py` |
| 31 | + Optional bridge to the native CPU kernel. |
| 32 | +4. `src/neat_optim/keras_optimizer.py` |
| 33 | + Keras optimizer adapter for model training. |
| 34 | +5. `src/neat_optim/engine/multiplayer.py` and `src/neat_optim/training/` |
| 35 | + Explicit per-player stepping and TensorFlow helpers. |
| 36 | +6. `tests/`, `examples/`, and `benchmarks/` |
| 37 | + Product-layer validation, usage, and measurement. |
| 38 | + |
| 39 | +## Start Here |
| 40 | + |
| 41 | +- For installation and first usage, read `Quickstart`. |
| 42 | +- For the public API surface, read `API`. |
| 43 | +- For algorithm details, read `Research`. |
| 44 | +- For local development and release workflow, read `Contributing`. |
0 commit comments