Luna Voice Assistant

Luna adalah asisten suara lokal dengan antarmuka web real-time, fokus pada percakapan natural (ID input, JP response), tool use (web/news/vision), dan memory persisten.

Dokumen ini dirancang sebagai panduan operasional lengkap: setup, arsitektur, runbook, troubleshooting, dan referensi endpoint.

Highlights

• Real-time WebSocket orchestration antara frontend dan backend.
• Speech-to-Text input dari browser (speech recognition).
• Response TTS menggunakan VoiceVox (server lokal) untuk playback web.
• Tool pipeline: web search, news summary, vision capture, time, reminder, IoT.
• STM/LTM memory untuk konteks percakapan berkelanjutan.
• UI modern berbasis React + Vite + Zustand + Motion.

Tech Stack

• Backend: FastAPI, Uvicorn, Python async pipeline.
• Frontend: React 19, Vite, TypeScript, Tailwind, Motion.
• LLM runtime: Ollama (default model llama3.1).
• Vision model: Ollama moondream.
• TTS: VoiceVox engine (localhost:50021).
• Search: ddgs.

Project Structure

luna/
|- backend/
|  |- api.py                    # FastAPI app, WS events, runtime checks, audio serving
|  |- generated_audio/          # Cached/generated wav for web playback
|- web/
|  |- src/
|  |  |- App.tsx                # Main layout + runtime dependency polling
|  |  |- hooks/useLunaWebSocket.ts
|  |  |- components/            # Orb, CommandBar, ContextWindow, panels, popup
|- agent_tools/
|  |- web_tools.py              # Web search helpers
|  |- news_tools.py             # News retrieval/summarization helpers
|  |- vision_tool.py            # Camera capture + image describe
|  |- detectors.py              # Intent/tool detection
|- memory/
|  |- short_term.json
|  |- long_term.json
|  |- active_topic.json
|  |- memory_manager.py
|- tts/
|  |- voicevox.py               # VoiceVox integration
|- stt/
|  |- stt.py
|- iot/
|  |- mqtt_client.py
|  |- iot_controller.py
|- mjp.py                       # Main orchestration and tool registry
|- requirements.txt
|- scripts/
|  |- start_luna.ps1
|  |- start_luna_minimal.ps1

Runtime Architecture

1. User input dikirim dari frontend (chat text atau voice transcript).
2. Frontend mengirim event chat ke backend lewat WebSocket ws://localhost:8000/ws.
3. Backend mendeteksi tool (jika ada), mengelola memory context, menjalankan LLM/tool.
4. Backend broadcast event progres (tool_start, tts_start, search_results, tool_end, dst).
5. Untuk audio, backend generate file wav melalui VoiceVox lalu kirim event tts_audio.
6. Frontend memutar audio dari endpoint /audio/{filename}.

Prerequisites

• Windows 10/11 (rekomendasi, sesuai script PowerShell tersedia).
• Conda environment aktif (default: lunaproject).
• Python + package di requirements.txt.
• Node.js 18+.
• Ollama aktif di localhost:11434.
• VoiceVox engine/container aktif di localhost:50021.

Installation

1) Python dependencies

conda activate lunaproject
pip install -r requirements.txt

Jika environment Python Anda masih < 3.10, pasang kompatibilitas typing untuk Pydantic:

pip install eval_type_backport

2) Frontend dependencies

cd web
npm install

Quick Start

Opsi A - Full startup (recommended)

Menjalankan VoiceVox (docker start), Ollama model, backend, dan frontend dalam terminal terpisah.

powershell -ExecutionPolicy Bypass -File .\scripts\start_luna.ps1

Dengan parameter custom:

powershell -ExecutionPolicy Bypass -File .\scripts\start_luna.ps1 -CondaEnv lunaproject -OllamaModel llama3.1 -VoicevoxContainer voicevox

Opsi B - Minimal startup

Menjalankan backend + frontend saja.

powershell -ExecutionPolicy Bypass -File .\scripts\start_luna_minimal.ps1

Opsi C - Manual startup

1. Backend:

conda activate lunaproject
python -m uvicorn backend.api:app --host 0.0.0.0 --port 8000 --reload

2. Frontend:

cd web
npm run dev

3. Buka URL Vite yang aktif (biasanya http://localhost:3000, atau fallback 3001/3002 jika port terpakai).

Environment Variables

Frontend:

• VITE_LUNA_WS_URL default: ws://localhost:8000/ws
• VITE_LUNA_DEMO_MODE default: false

Contoh di PowerShell sebelum npm run dev:

$env:VITE_LUNA_WS_URL = "ws://localhost:8000/ws"
$env:VITE_LUNA_DEMO_MODE = "false"

API and WebSocket Reference

HTTP endpoints:

• GET /runtime/deps cek status VoiceVox dan Ollama.
• POST /chat chat request/response mode HTTP.
• GET /audio/{filename} serve file audio wav untuk frontend.

WebSocket endpoint:

• ws://localhost:8000/ws

Event yang umum dipakai frontend:

• stt
• tool_start / tool_end
• tts_start / tts_audio / tts_end / tts_audio_error
• search_results
• vision_frame
• system_stats

Tooling Capabilities

• Web Search: cari topik umum dan rangkum hasil.
• News Search: headline + artikel utama + rangkuman.
• Vision: capture kamera dan deskripsi gambar.
• Time Tool: waktu/tanggal lokal.
• Reminder Tool: pengingat lokal.
• IoT Tool: kontrol perangkat via MQTT.

Memory Model

• STM: konteks percakapan jangka pendek.
• LTM: fakta/preferensi yang disimpan lintas sesi.
• Active Topic: konteks artikel/topik terbaru untuk follow-up question.

Semua data disimpan di folder memory/ dalam format JSON.

Operational Notes

• Sistem web sekarang menggunakan VoiceVox-only playback untuk output suara.
• Jika VoiceVox tidak aktif, teks masih bisa muncul, tetapi audio TTS tidak diputar.
• Untuk vision, kamera diberi warm-up delay sebelum capture agar hasil lebih fokus.

Troubleshooting

Backend tidak bisa start di port 8000

Kemungkinan port sudah dipakai proses lama.

Get-NetTCPConnection -LocalPort 8000 | Select-Object LocalAddress,LocalPort,State,OwningProcess
Stop-Process -Id <PID> -Force

uvicorn tidak dikenali

Gunakan module mode setelah activate conda env:

conda activate lunaproject
python -m uvicorn backend.api:app --host 0.0.0.0 --port 8000 --reload

WebSocket connect gagal

Checklist:

• Backend hidup di :8000.
• VITE_LUNA_WS_URL mengarah ke endpoint benar.
• Tidak ada firewall policy yang memblokir localhost.

VoiceVox audio tidak berbunyi

Checklist:

• Container/engine VoiceVox berjalan di http://localhost:50021.
• Endpoint GET /runtime/deps mengembalikan voicevox.ok = true.
• Browser mengizinkan autoplay audio untuk situs localhost.

Developer Commands

Backend sanity:

conda activate lunaproject
python -m py_compile backend\api.py agent_tools\vision_tool.py

Frontend:

cd web
npm run lint
npm run build

Roadmap Suggestions

• Tambahkan .env.example root untuk endpoint/model defaults.
• Tambahkan health dashboard endpoint untuk observability.
• Tambahkan integration test sederhana untuk event WebSocket utama.