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