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 — specyfikacja techniczna etapu 1 (cel buildu).
• docs/LEXICON.md — zweryfikowany leksykon (formy gramatyczne).
• docs/ROADMAP.md — etapy i ograniczenia platformy docelowej.
• docs/ONDEVICE.md — PoC-1 na Meta Quest 3 (Unity + sherpa-onnx).
• ondevice/README.md — ręczne kroki w Unity Editorze.

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)

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)

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)

# 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.

Eksport banku poleceń (na urządzenie)

Generuje gotowe, deduplikowane polecenia do JSON — używane przez aplikację Unity na Quest 3 (PoC-1, docs/ONDEVICE.md):

python -m ipin_vr export --per-level 300 --out commands.json [--seed N]

Flaga	Domyślnie	Opis
--per-level N	300	liczba unikatów na poziom
--out PATH	- (stdout)	ścieżka pliku wyjściowego
--seed N	—	powtarzalny wynik

Format wyjściowy:

{
  "meta": {"version": "1", "per_level": 300},
  "commands": [
    {"level": 1, "text": "Połóż jabłko na stole."},
    {"level": 2, "text": "Umieść niebieskie jabłko na stole."},
    {"level": 3, "text": "Połóż zieloną książkę na półce i umieść klucz na biurku."}
  ]
}

Przestrzeń każdego poziomu: L1 = 120 unikatów, L2 = 720, L3 ≈ 635 000. Jeśli --per-level przekracza dostępną przestrzeń, zwracane jest tyle ile możliwe.

Testy

pytest

Status

Etap 1 zrealizowany wg docs/SPEC.md. PoC-1 (Quest 3): skrypty C# w ondevice/.