PROPOSAL: Supervised trenovani doprednych siti v dalsi verzi Cognie
==================================================================

Kontext
-------

Pri priprave prikladu 03 (rozhodovani o zalevani rostlin) jsem chtel postavit
bezny klasifikacni retezec:

    9 vstupu -> nelinearni skryta vrstva -> 3 logity -> softmax -> rozhodnuti

Vstupy jsou vlhkost pudy, teplota, vlhkost vzduchu, slunce, predpoved deste,
cas od posledniho zaliti a one-hot typ rostliny. Dataset ma 600 syntetickych a
presne vyvazenych prikladu: 200 x NO_WATER, 200 x LIGHT_WATER a
200 x DEEP_WATER. Generator i sit pouzivaji seed 103.

Parser, sestaveni topologie, trenovani, ulozeni site, nacteni site i REST
inference funguji. Problem je kvalita a semantika supervised uceni pres vice
vrstev.


Co bylo namereno
----------------

Vsechny varianty byly trenovany na stejnem datasetu pomoci:

    cognia_train ... watering.dataset 5000 <network> --softmax

1. Pevna nahodna skryta vrstva 9 -> 24 -> 3:

       accuracy 408/600 = 68.0 %

2. Pevny one-to-one transform 9 -> 9 -> 3 bez prime zkratky:

       accuracy 314/600 = 52.3 %

3. Stejny transform s primou zkratkou vstup -> vystup:

       accuracy 403/600 = 67.2 %
       MSE      0.4355

4. Diagnosticka melka sit 9 -> 3 bez skryte vrstvy:

       accuracy 400/600 = 66.7 %
       MSE      0.3947

5. Puvodni nevyvazeny nahodny dataset vykazoval 76.3 %, ale obsahoval prevahu
   NO_WATER. Po vyvazeni trid presnost klesla. Samotna accuracy bez rozdeleni
   podle trid tedy davala prilis optimisticky obraz.

Zaver z mereni:

- pridani skryte vrstvy neprineslo proti melke variante prokazatelne zlepseni;
- vysledek je citlivy na gain, leak, velikost a typ skryte vrstvy;
- pevna one-to-one mezivrstva muze vykon dokonce vyrazne zhorsit;
- primy skip obnovi zhruba vykon melkeho readoutu, ale nevyuzije potencial
  skryte reprezentace;
- problem neni jen obecny deep credit assignment: i melka tritridni ordinalni
  klasifikace zustala okolo 2/3;
- vyvazeny dataset odhalil problem, ktery nevyvazena accuracy maskovala.


Co je potvrzene a co je zatim hypoteza
--------------------------------------

Potvrzene chovani:

- Cognia nema obecny backpropagation/autodiff pres dopredny DAG;
- --softmax uci finalni readout, ale skryta transformace nedostava end-to-end
  kredit podle klasifikacni chyby;
- REST vraci surove aktivace. Klient musi pravdepodobnosti znovu vypocitat;
- vystupni aktivace prochazi tanh/leak dynamikou, tedy nejde o neomezene logity;
- trainer vypisuje vsechny vzorky pred i po treninku, coz u vetsich datasetu
  zahlcuje vystup;
- reportuje pouze celkovou accuracy a MSE, nikoli confusion matrix, per-class
  recall nebo samostatnou validaci.

Pravdepodobne priciny, ktere je nutne overit jednotkovymi testy:

- gradient softmax cross-entropy nemusi byt konzistentni s hodnotou, nad kterou
  se softmax pri evaluaci skutecne pocita (net vs. tanh activation);
- update readoutu pravdepodobne nezahrnuje derivaci vystupni aktivacni funkce,
  nebo naopak kombinuje CE gradient s derivaci, ktera pro logity nema byt;
- normalizace sum(weighted) podle in-degree meni efektivni meritko logitu a nuti
  uzivatele rucne hadat gain;
- leak a opakovane settle kroky mohou zpusobit rozdil mezi treninkovym a REST
  forwardem;
- vystupni neurony nemaji trenovatelny bias. U tridy LIGHT_WATER, ktera ma
  vyhravat v intervalu mezi dvema prahy, je bias zasadni;
- pojem "5000 iteraci" neni z CLI vystupu dostatecne zrejmy: neni jasne, zda
  jde o epochy, vzorky nebo jednotlive update kroky.

Tyto body jsou diagnosticke hypotezy, nikoli potvrzene chyby implementace.


Navrh pro dalsi verzi
---------------------

P0 - Jednoznacny klasifikacni vystup

Zavest specialni neuron nebo output head, jehoz stav jsou skutecne logity:

    output classification from area.cells as watering {
        vocab: "no_water", "light_water", "deep_water";
        loss: softmax_cross_entropy;
    }

Pro tento vystup musi platit:

- softmax se pocita z net/logits pred tanh, leakem a fire mechanismem;
- gradient CE podle logitu je presne p - target;
- stejna hodnota se pouzije pri treninku, evaluaci, accuracy i REST odpovedi;
- REST vrati vedle logits take probabilities a selected_index/selected_label;
- klasifikacni hlava ma trenovatelny bias pro kazdou tridu;
- in-degree normalizace se na logity bud nepouzije, nebo je explicitni a trainer
  ji zahrne do gradientu. Uzivatel nema rucne kompenzovat gain podle poctu hran.

P0 - Regresni test melkeho softmaxu

Pridat maly deterministicky test tritridni ordinalni klasifikace. Napriklad jeden
vstup x a tri tridy LOW/MID/HIGH, kde MID lezi mezi dvema prahy. Sit s naucenymi
vahami a biasy musi dosahnout alespon 95 % na vyvazenem datasetu.

Test musi kontrolovat:

- numerickou shodu analytickeho a implementovaneho gradientu;
- pokles cross-entropy;
- nauceni vsech tri trid, ne pouze krajich trid;
- shodu predikce traineru, cognia_run a REST /evaluate;
- stejny vysledek po save/load;
- reprodukovatelnost pri stejnem seedu.

P1 - Supervised kontrakt pro dopredny DAG

Rozsirit jazyk o explicitni trenovaci oblast, aby nebylo nejasne, ktere hrany
jsou soucasti gradientu:

    training FeedForwardWatering {
        objective: supervised;
        input: sensors.environment, sensors.plant_type;
        output: brain.decision;
        loss: softmax_cross_entropy;
        optimizer: adam;
        owns: learnable path;
    }

Minimalni podporovany rozsah:

- acyklicka podsit;
- dense/full a one_to_one hrany;
- tanh, sigmoid, ReLU nebo linear aktivace;
- vahy a biasy;
- topologicky forward a reverse pass;
- jasna chyba pri cyklu, gate, stochastic fire nebo jine nepodporovane operaci;
- gradient check pomoci konecnych diferenci na malych sitich;
- save/load optimizer state jako volitelna funkce.

Neni nutne delat obecny autodiff cele Cognie. Staci ohraniceny supervised DAG,
ktery vedle lokalnich biologicky inspirovanych mechanismu poskytne spolehlivy
zpusob nauceni bezne dopredne klasifikacni hlavy.

P1 - Pokud backprop neni zadouci

Jestlize Cognia nechce pridat reverse-mode gradient ani pro DAG, je potreba
poskytnout jinou explicitni a otestovanou cestu:

- trainable random-feature/ELM head s uzavrenym ridge resenim;
- lokalni target propagation s definovanym kontraktem;
- staged controller training s targetem pro kazdou vrstvu;
- CHL pouze tam, kde je zajistena potrebna zpetna symetrie a konvergence.

V dokumentaci se musi rozlisit "dopredna inference pres vice vrstev" od
"end-to-end naucena dopredna sit". Pevna skryta vrstva s naučenym readoutem nema
byt prezentovana jako hluboke supervised uceni.

P1 - Metriky a validace

Rozsirit cognia_train o:

    --validation validation.dataset
    --metrics-json result.json
    --quiet
    --report-every 100
    --early-stopping 20

Minimalni report:

- train a validation loss;
- accuracy;
- confusion matrix;
- precision/recall pro kazdou tridu;
- pocty prikladu jednotlivych trid;
- best epoch a final epoch;
- learning rate a skutecny pocet update kroku.

Trainer by mel upozornit na silne nevyvazeny dataset. U prikladu zalevani by
takove upozorneni okamzite odhalilo, proc 76.3 % nebylo lepsi nez 68 % na
vyvazene sade.

P2 - Kalibrace a rozhodovaci logika

Pro prakticke rozhodovani nestaci argmax. REST klasifikacni vystup by mel vracet:

    logits
    probabilities
    selected_label
    confidence
    entropy

Volitelne lze pridat temperature scaling na validacni sade. Bezpecnostni pravidla
typu "nezalevat mokrou pudu" maji zustat mimo neuronovou sit v bezne ridici
logice. Model doporucuje, deterministicka policy rozhoduje, zda je akce dovolena.

P2 - Dataset a CLI diagnostika

- pri neshode dimenzi vypsat ocekavany a skutecny rozmer;
- pri prazdnem datasetu vypsat cislo prvniho neplatneho radku a duvod;
- dokumentovat hlavicku "cognia-dataset <input_dim> <output_dim>";
- umoznit --dry-run-dataset;
- vypsat mapovani senzoru a vystupu na sloupce datasetu;
- jednoznacne definovat iterations/epochs/batch-size.


Navrzena akceptacni kriteria
----------------------------

1. Melky test LOW/MID/HIGH dosahne >= 95 % na vyvazene testovaci sade.
2. Sit 9 -> 16 -> 3 na zalevani dosahne >= 90 % train a >= 85 % na samostatne
   deterministicke testovaci sade generovane jinym seedem.
3. Skryte vahy se pri end-to-end treninku prokazatelne zmeni.
4. Numericky gradient check ma relativni chybu < 1e-4 na male siti.
5. Trainer, cognia_run a REST vrati stejny label i pravdepodobnosti v toleranci.
6. Save/load nezmeni predikci ani metriky.
7. Confusion matrix potvrdi, ze se uci vsechny tri tridy.
8. Pri nepodporovanem cyklu nebo stochasticke operaci trainer skonci jasnou
   diagnostikou, ne tichym treninkem pouze posledni vrstvy.


Doporucene poradi implementace
------------------------------

1. Opravit a numericky otestovat melkou softmax klasifikacni hlavu vcetne biasu.
2. Sjednotit logits/probabilities mezi trainerem a REST.
3. Pridat confusion matrix, validaci a tichy/JSON vystup.
4. Implementovat ohraniceny backprop pro acyklickou supervised podsit, nebo
   explicitne zvolit a otestovat alternativu bez backpropu.
5. Teprve potom vydavat example 03 za end-to-end trenovanou doprednou sit.

Nejvyssi prioritu ma bod 1. Namerenych 66.7 % u melke varianty ukazuje, ze nema
smysl nejprve resit libovolne hluboke grafy. Nejdrive musi byt spolehliva a
matematicky konzistentni finalni tritridni klasifikacni hlava.
