Fox

Proaktiver KI-Assistent. Laravel 12 · Livewire 3 (class-based) · Tailwind v4 · Reverb · Postgres + pgvector · Redis · Ollama (llama3.1:8b) · whisper.cpp · piper.

Quickstart (Debian 13, nur Docker installiert)

git clone <repo> fox && cd fox
docker compose up -d
make install

Fox ist dann erreichbar unter http://10.10.90.175.

make install baut die Images, fährt Postgres/Redis/Ollama hoch, installiert Composer- und npm-Pakete, generiert den App-Key, führt die Migrations aus, pullt das Ollama-Modell und das whisper.cpp ggml Modell und baut die Frontend-Assets.

Architektur

docker-compose.yml ─┬─ app (PHP-FPM 8.3)
                    ├─ nginx
                    ├─ postgres (pgvector/pg16)
                    ├─ redis
                    ├─ ollama (llama3.1:8b + nomic-embed-text)
                    ├─ queue worker
                    ├─ scheduler
                    ├─ reverb (WebSockets, Port 8080)
                    ├─ whisper (whisper.cpp Sidecar)
                    └─ searxng (Meta-Suchmaschine)

Code-Struktur

Pfad	Was
app/Services/FoxAgent.php	Agent-Loop: think → plan → act → reflect
app/Services/SpeechService.php	whisper.cpp + piper Bridge
app/Services/MemoryService.php	pgvector Embeddings via Ollama
app/Tools/WebSearchTool.php	SearXNG (lokale Meta-Suche)
app/Tools/BuildTemplateTool.php	HTML-Page erzeugen + Broadcast
app/Tools/FileManagerTool.php	Sandbox-Filesystem
app/Jobs/FoxProactiveJob.php	Alle 5 Min: LLM entscheidet, ob Fox spricht
app/Events/FoxMessage.php	Broadcast → Livewire
app/Livewire/Chat.php	Haupt-Chat (PTT, Feed)
app/Livewire/Goals.php	Ziele
app/Livewire/Modals/NewGoal.php	Modal für neues Ziel

Routen liegen in routes/web.php und zeigen direkt auf Livewire-Klassen — Ausnahme: POST /fox/voice für Audio-Upload (FoxVoiceController).

Tailwind v4

Farben kommen aus resources/css/app.css via @theme — keine tailwind.config.js. Nutzbar als bg-primary, bg-surface, bg-glass …

Livewire 3

config/livewire.php ist auf class-based Layout gestellt (class_namespace = App\Livewire, view_path = resources/views/livewire). Klassen und Blades sind getrennt.

Make-Targets

make install         First-time Setup
make up | down       Container starten / stoppen
make shell           Shell im app-Container
make logs            Container-Logs folgen
make migrate         DB-Migrations
make fresh           DB komplett zurücksetzen
make tinker          Tinker REPL
make ollama-pull     Ollama-Modell pullen
make whisper-model   whisper.cpp ggml-Modell laden
make npm-build       Frontend-Assets bauen

Proaktive Engine

bootstrap/app.php registriert den Scheduler: alle FOX_PROACTIVE_INTERVAL_MINUTES (Default 5) wird FoxProactiveJob queued. Der Job ruft FoxAgent::shouldISpeak(), das via Prism-Structured-Output ein ProactiveDecision { shouldSpeak, message, priority } zurückbekommt und bei Bedarf eine proaktive Nachricht broadcastet.

Voice

Push-to-Talk via Strg+Leertaste oder gedrückt halten des Mikro-Buttons. Audio wird per multipart/form-data an /fox/voice geschickt → ffmpeg konvertiert nach 16kHz wav → whisper.cpp transkribiert → FoxAgent antwortet → piper synthetisiert die Antwort → Browser spielt den .wav-Stream automatisch ab.

ENV-Variablen

Siehe .env.example. Wichtig:

• OLLAMA_MODEL=llama3.1:8b
• OLLAMA_EMBEDDING_MODEL=nomic-embed-text (768-dim Vector — passt zur Migration)
• SEARXNG_URL=http://searxng:8080 (Default — Service läuft im selben Netz)
• REVERB_* für WebSockets (Default-Werte funktionieren lokal)