Gemma 4 Ultimate Sandbox & Tester
# 🛠️ Gemma 4 Ultimate Sandbox & Tester
Toto sandboxové prostředí slouží jako ultimátní testovací stanice pro modely **Gemma 4 MoE** s velkým kontextem a Vision (Clip) schopnostmi. Celé prostředí běží na FastAPI backendu s `llama-cpp-python` a Matrix-themed frontendu v Next.js.
---
## 📖 Popis Aplikace
Aplikace poskytuje plnou kontrolu nad parametry LLM modelu a procesem generování, což z ní dělá ideální nástroj pro vývojáře a AI inženýry. Umožňuje podrobnou inspekci odpovědí modelu, včetně vnitřních myšlenkových pochodů (CoT - Chain of Thought), rychlosti generování a práce s pamětí.
Sandbox je plně izolovaný od hlavní asistentní logiky, avšak obě vrstvy sdílejí stejné Conda prostředí (`assistant_env`).
---
## 📂 Dokumentace
Pro kompletní informace o nastavení, vývoji a historii změn přejdi na tyto dokumenty:
* 🛠️ **[Návod k instalaci a CUDA nastavení (setup-info.md)](files/setup-info.md)** – Návod pro BFU i pokročilé na instalaci CUDA ovladačů, kompilaci pro GPU a PyTorch.
* 🤖 **[Pokyny pro vývojáře a agenty (agent.md)](files/agent.md)** – Informace o stacku, osvědčených postupech a cheatsheet pro urychlení práce.
* 📝 **[Historie změn (changelog.md)](files/changelog.md)** – Záznamy o verzích a vývoji aplikace.
---
## ✨ Hlavní Funkce
* **Předdefinované Modely**: Podpora a přepínání mezi přednastavenými modely (Gemma 4, Gemma 3, Qwen 3.6 GGUF) včetně auto-nastavení chat templátů (Raw vs. ChatML) a stop tokenů přes UI Dropdown.
* **Prompt Library & Editor**: Pravý panel obsahuje 21 různorodých benchmarkovacích promptů (filosofie, kódování, logika, styl). Umožňuje rychlou editaci, ukládání custom promptů a odesílání do M1/M2/Arény jedním kliknutím.
* **System Prompts Editor**: Přímá editace a ukládání systémových promptů pro oba modely (M1/M2) přímo na pravém panelu bez nutnosti otevírat dolní konzoli.
* **Zelený text v chatu**: Odpovědi modelů (asistentů) v Single Chatu jsou zvýrazněné zelenou barvou pro dokonalé vizuální oddělení.
* **Lokalizace (EN/CS/PL)**: Možnost přepínat jazyk rozhraní v hlavičce (výchozí EN).
* **Exporty a kopírování**: Ukládání celých chatů (Single, Split, Arena) do formátů Markdown (.md) a JSON, a možnost kopírovat nebo stahovat jednotlivé zprávy.
* **Arena Duel & Continue**: Dva modely mohou diskutovat v kruhu. Duel lze po přerušení nechat pokračovat s novým promptem i bez, nastavit `Max Turns` a spouštět nástroje (tools) nezávisle na modelech.
* **Tools / Funkce**: Přidáno nativní rozhraní pro vkládání a odesílání `tools` konfigurace (JSON) s automatickou podporou spouštění Python skriptů a kalkulačky.
* **SSE Streamování a Přerušení**: Odpovědi jsou streamovány přes Server-Sent Events s možností okamžitého zastavení (`Stop`) nebo plynulého přerušení s novým dotazem (`Interrupt`).
* **Multimodalita (Vision)**: Podpora nahrávání obrázků (Image Upload), které jsou pomocí clip modelu zpracovány a předány přímo do LLM.
* **Metriky v Reálném Čase**: Každá odpověď obsahuje přesná data o rychlosti (TPS), času generování a počtu spotřebovaných tokenů.
* **RAG-lite (Context Loader)**: Aplikace dokáže načíst veškerý obsah `.txt` a `.md` souborů umístěných do složky `context_files` a dynamicky je přidat k systémovému promptu.
* **Inspekce Myšlenek (Thinking Mode)**: Zvláštní tagy pro uvažování (`<|think|>`) lze sbalit/rozbalit. Pokud je Thinking mód vypnutý, celý output běží hladce bez rušivých tagů.
* **Persistentní Konfigurace**: Všechna nastavení (seed, model, teplota, threads, batch size, tools) se dají z frontendu jediným kliknutím uložit do `backend/config.json`.
* **Pokročilé Parametry Generování**: V UI dostupné ladění `Seed`, `n_threads` (Threads), `n_batch` (Batch Size), `Top P`, `Min P`, `Top K`, `Repeat Penalty`, `Temp`, `History Limit`, `Flash Attention`, `Exclude Stop Tokens` a velikosti dávky.
---
## 🚀 Rychlý Start
1. **Instalace**: Spusť `install.bat`. Skript připraví conda prostředí (`assistant_env`) a nainstaluje backendové a frontendové závislosti.
* *Pokud chceš plnou GPU/CUDA akceleraci, přečti si nejdříve podrobný **[setup-info.md](files/setup-info.md)**.*
2. **Spuštění**: Spusť `run.bat`. Vytvoří se výchozí složky (`output`, `context_files`) a spustí se obě služby (Backend na portu 8080, Frontend na 3030).
3. **Přístup**: Otevři v prohlížeči `http://localhost:3030`.
---
## 📂 Strom Souborů Aplikace
```text
gemmaSandbox/
│
├── backend/
│ ├── main.py # FastAPI server, SSE streamování, Llama instancování
│ ├── config.json # Persistentní globální konfigurace a systémové prompty
│ └── requirements.txt # Python závislosti pro backend
│
├── frontend/
│ ├── src/app/page.tsx # Hlavní uživatelské rozhraní v React/Next.js
│ ├── package.json # Node závislosti
│ └── ... # Standardní Next.js struktura
│
├── context_files/ # Všechny .txt, .md a .json z této složky se mohou načíst do kontextu
│
├── output/ # Automaticky generované výstupy
│ ├── logs/ # Backend / batch logy
│ ├── prog/ # Tady budou padat vygenerované skripty
│ └── text/ # Textové výstupy (např. last_response.txt)
│
├── install.bat # Příprava prostředí a instalace
├── run.bat # Spouštěč celého sandboxu
├── questions.json # Dávkové otázky pro Test Bench
│
├── README.md # Hlavní rozcestník dokumentace (Tento soubor)
├── setup-info.md # Blbuvzdorný instalační návod pro GPU & CUDA
├── agent.md # Pokyny pro AI agenty a cheatsheet
└── changelog.md # Záznamy o verzích
```
---
## ⚠️ Důležité Informace
* **Cesty k Modelům**: V UI zadávej cesty striktně jako absolutní (např. `C:/LLM/gemma.gguf`). Llama-cpp neřeší relativní kontext tvojí plochy.
* **LM Studio & Fallback**: Ideální nástroj pro stahování modelů a testování parametrů/promptů je **LM Studio**. Aplikace využívá výchozí složku LM Studia (`C:\Users\<username>\.lmstudio\models\lmstudio-community`) jako výchozí umístění modelů.
* **Seed a Context**: Context 256k u Gemma 4 bere ohromné množství paměti. Pokud nepotřebuješ RAG, sniž ho na 8192 v levém panelu, abys ušetřil VRAM pro model samotný.
*Viel Spaß při testování!*
## Download
- [Kompletní archiv projektu](files/gemma-sandbox-ALL.zip) - Kompletní balík zdrojových kódů a dokumentace
- [gemmaSandbox_installer.zip](files/gemmasandbox_installer.zip) - Automatický instalátor
- [Návod k instalaci (setup-info.md)](files/setup-info.md) - Podrobný průvodce
- [Pokyny pro agenty (agent.md)](files/agent.md) - Dokumentace pro vývojáře
