90 lines
3.7 KiB
Markdown
90 lines
3.7 KiB
Markdown
# 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)
|
|
|
|
```bash
|
|
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)
|