PRD: ExSize SizeAgent

[MrCrystal2]

PRD: ExSize SizeAgent

Overview

SizeAgent to głosowy asystent wbudowany w przeglądarkę w istniejącym ExSize (FastAPI + SQLAlchemy + React/Vite/TS; SQLite lokalnie / Neon Postgres prod). Klikasz przycisk (mikrofon) na stronie, mówisz, a agent rozumie polecenia w języku naturalnym (AI) i tworzy / pokazuje / usuwa Twoje To-Do oraz obowiązki (Task). Nie dzwoni nigdzie — cała rozmowa dzieje się w przeglądarce. Samodzielny projekt Adama.

Problem Statement

Stukanie w klawiaturę, by zarządzać zadaniami, jest wolne i przeszkadza. Mowa jest najszybszym interfejsem: mówisz „dodaj kup mleko" albo „co mam do zrobienia?" i gotowe — bez dotykania ekranu.

Users

User type	Description	Volume
Użytkownik	Każdy zalogowany (rodzic/dziecko) zarządzający swoimi To-Do/obowiązkami głosem	1-3 (demo)

Goals & Success Criteria

• Przycisk mikrofonu w UI uruchamia rozmowę z agentem w przeglądarce
• Agent rozumie polecenia w języku naturalnym (AI) i wykonuje CRUD na To-Do i Task
• Agent odpowiada głosem (potwierdzenie wykonanej akcji)
• Transport głosu w pełni darmowy (Web Speech API)

User Stories

1. Jako użytkownik, chcę kliknąć przycisk i powiedzieć „dodaj kup mleko do Zakupów", żeby agent stworzył To-Do bez pisania.
2. Jako użytkownik, chcę zapytać „co mam do zrobienia?" i usłyszeć listę moich To-Do.
3. Jako użytkownik, chcę powiedzieć „usuń zadanie o mleku", żeby agent je skasował (z potwierdzeniem).
4. Jako użytkownik, chcę głosem zarządzać też obowiązkami („odhacz pranie", „pokaż moje obowiązki").
5. Jako rodzic, chcę widzieć, co dziecko zrobiło głosem (log akcji), żeby mieć kontekst.

Scope

In scope

• Nowy moduł sizeagent/ w istniejącym repo ExSize
• Przycisk mikrofonu (push-to-talk) w UI + Web Speech API (STT + TTS) — transport głosu w przeglądarce, darmowy
• LLM z function-calling jako „mózg": narzędzia = CRUD na To-Do i Task
• Endpoint backendu przyjmujący wypowiedź → decyzja LLM → wykonanie akcji → odpowiedź głosowa
• Log akcji głosowych (co powiedziano → co zrobiono)
• Język z User.language (domyślnie polski)

Out of scope

• Telefony / outbound calling — agent jest TYLKO w przeglądarce, nie dzwoni nigdzie
• Nowa gamifikacja (XP/streaks/badge) — bez zmian
• Zmiany w istniejących, działających funkcjach niezwiązane z SizeAgent
• Rozbudowany onboarding

System Components

• Frontend: React/Vite/TS — przycisk mikrofonu, Web Speech API (SpeechRecognition + SpeechSynthesis), wyświetlanie odpowiedzi
• Backend: FastAPI + nowy moduł sizeagent/ — endpoint przyjmujący tekst wypowiedzi, wywołanie LLM z narzędziami (function-calling), wykonanie CRUD na To-Do/Task, zwrot odpowiedzi
• Baza danych: SQLite/Neon (istniejące) + opcjonalna tabela voice_action_log
• Zewnętrzna integracja: LLM API (klucz w zmiennej środowiskowej) do rozumienia języka naturalnego

Implementation Decisions

Decision	Choice	Rationale
Gdzie działa agent	W przeglądarce (nie telefon)	Darmowe, proste, demo bez kosztów telefony
Transport głosu	Web Speech API (SpeechRecognition + SpeechSynthesis)	Darmowe, wbudowane w przeglądarkę (Chrome/Edge), wspiera PL
Mózg / rozumienie	LLM z function-calling	Naturalny język; narzędzia = CRUD To-Do/Task
Zarządzane obiekty	To-Do + obowiązki (Task)	Pełna kontrola głosem nad zadaniami i obowiązkami
Język	Z User.language (domyślnie PL)	Pole istnieje; rozpoznawanie mowy PL w Chrome
Trigger	Przycisk push-to-talk	Jasne, przewidywalne; bez ciągłego nasłuchiwania

Validation Strategy

• Klikasz mikrofon → mówisz „dodaj kup mleko" → To-Do tworzy się w aplikacji (test ręczny + automatyczny)
• „Pokaż moje zadania" → agent mówi listę
• „Usuń X" → agent pyta o potwierdzenie → po tak usuwa
• Działa w Chrome/Edge z polskim językiem
• Brak klucza LLM → graceful (jasny komunikat, nie crash)

Open Questions

• Którego dostawcę LLM wybrać (free tier: Groq, Gemini Flash) — kryteria: cena (free), latencja, jakość PL, function-calling
• Czy log akcji głosowych widzi tylko użytkownik, czy też rodzic (story 5)

Dependencies (ExSize 2.0)

• Wymaga CRUD na To-Do → Fazy To-Do (ExSize 2.0 — Faza 1: To-Do tracer bullet (CRUD end-to-end) #60–63)
• Wymaga istniejącego systemu Task (już działa)
• Wymaga klucza API modelu LLM (env)