ipin-vr/README.md

# ipin-vr

Generator prostych, **gramatycznie poprawnych** polskich poleceń do terapii afazji
(np. *„Połóż jabłko na stole"*) wraz z wypowiadaniem ich przez Piper TTS.

Docelowo narzędzie ma działać w trybie mieszanej rzeczywistości na Meta Quest 3
(offline). **Etap 1** (ten kod) realizuje wyłącznie rdzeń: generowanie poleceń i ich
wypowiadanie na PC. Bez rozpoznawania mowy (STT), bez VR.

## Dokumentacja
- [`docs/SPEC.md`](docs/SPEC.md) — specyfikacja techniczna etapu 1 (cel buildu).
- [`docs/LEXICON.md`](docs/LEXICON.md) — zweryfikowany leksykon (formy gramatyczne).
- [`docs/ROADMAP.md`](docs/ROADMAP.md) — etapy i ograniczenia platformy docelowej.

## Zasada naczelna
Poprawność fleksji jest nienegocjowalna. Wszystkie formy słów pochodzą wyłącznie
z ręcznie zweryfikowanego leksykonu; model językowy (gdy włączony) wybiera tylko
identyfikatory elementów, a nie generuje polskiego tekstu.

## Szybki start (bez audio)

```bash
python -m ipin_vr --level 3 --count 6 --no-audio
```

Przykładowy wynik:
```
1. Połóż zieloną książkę na półce i umieść klucz na biurku.
2. Umieść żółtą piłkę na parapecie i połóż kubek na stole.
...
```

Dostępne opcje CLI:

| Flaga | Domyślnie | Opis |
|---|---|---|
| `--level {1,2,3}` | 1 | poziom trudności |
| `--count N` | 5 | liczba poleceń |
| `--delay S` | 4.0 | pauza między poleceniami (s) |
| `--voice PATH` | — | ścieżka do modelu Piper `.onnx` |
| `--no-audio` | — | wyłącza TTS |
| `--llm` | — | użyj LLM do wyboru poleceń |
| `--llm-endpoint URL` | localhost:8080 | endpoint llama.cpp |
| `--llm-model NAME` | `local` | nazwa modelu |
| `--seed N` | — | deterministyczny generator |

## Audio (Piper TTS)

```bash
pip install piper-tts
# pobierz głos polski, np. ze https://huggingface.co/rhasspy/piper-voices
python -m ipin_vr --level 2 --count 5 --voice pl_PL-gosia-medium.onnx
```

## LLM (llama.cpp, opcjonalny)

```bash
# uruchom lokalnie serwer llama.cpp na porcie 8080
python -m ipin_vr --level 3 --count 5 --no-audio --llm
```

LLM zwraca wyłącznie identyfikatory elementów; gramatykę buduje zawsze leksykon.
Przy błędzie (timeout, zły JSON, nieznany identyfikator) — fallback na generator losowy.

## Testy

```bash
pytest
```

## Status
Etap 1 — zrealizowany zgodnie z `docs/SPEC.md`.