Athena-Deck/README.md

# Athena Deck · Router 0.7

Eigenständige neue Oberfläche, Python-Standardbibliothek und HTML/CSS/JavaScript.
Keine Installation von Python-Paketen oder Frontend-Builds nötig. Python >= 3.10.

## Vorläufige Testinstallation auf Debian

Zielprodukt: nativer systemd-Dienst auf Debian. Der derzeitige Docker-Installer dient ausschließlich der isolierten Testphase.

Ein eigenständiger Testinstaller ohne WireGuard ist vorhanden: [Debian-Installation](INSTALL.md).
Auf dem Zielserver: `sudo ./install.sh --check`, anschließend `sudo ./install.sh --install`.
Vorhandenes Docker wird vorausgesetzt; produktive Dienste werden nicht verändert.

## Neu: Modellverwaltung und llama.cpp-Einstellungen

Katalog, Datei-Downloads, Bibliothek, serverseitig gespeicherte Profile und
llama.cpp-Buildverwaltung sind live. Der Download-Reiter erlaubt das Ausblenden
abgeschlossener Einträge ohne Dateiverlust. Entdecken zeigt Größen und eine
konservative Gewichts-Speicherprüfung; noch keine vollständige Laufzeitprognose.
Bildprofile mit vollständigem Qwen-Image-2.1-GGUF-Rezept lassen sich unter „Testen“ ausführen. Textprofile sind am eigenen [OpenAI-kompatiblen Endpunkt](ENDPOINT.md) ausführbar. Qwen3-TTS CustomVoice ist über eine eigene CUDA-Laufzeit ausführbar; Qwen3-ASR bietet Spracherkennung; Musik, Voice und Video bleiben vorbereitet. Sprachmodelle besitzen außerdem einen internen Testchat mit Abbruch und Speicherdiagnose. Details: [Modellverwaltung](STUDIO.md).

## Zugang und API-Token

Beim ersten Öffnen werden Oberflächenkennwort und separater API-Token eingerichtet.
Beide sind unter **Zugang & API** änderbar. Der Debian-Installer richtet den Zugang vor dem Serverstart ein. Details und API-Rechte: [Zugangsverwaltung](ACCESS.md).

## WireGuard-Einstellungen

Das separate [WireGuard-Modul](network/README.md) enthält Conf-Import und
LAN-/Tunnel-Zugriff. In der aktuellen Debian-Entwicklungsinstanz ist es nicht
angebunden; der Zugriff erfolgt über SSH-Tunnel. Der bestehende Gateway bleibt unverändert.

## Zielsystem und Entwicklung

Athena Deck läuft vollständig auf einem Debian-Server mit RTX 5080 und RTX 3060.
Oberfläche, API, Router und Hardware-Erfassung laufen dort. Der Arbeitsplatz
benötigt nur Browser und SSH; er ist kein Anwendungsserver. Auch Builds und
Integrationstests werden auf Athena ausgeführt. Chat- und Qwen-Image-Laufzeiten sind am eigenen Endpunkt angebunden.

Die isolierte Entwicklungsinstallation ist in [DEVELOPMENT.md](DEVELOPMENT.md)
beschrieben. Hardware wird direkt über `/proc`, hwmon und nvidia-smi gelesen;
Deck benötigt dafür keinen SSH-Schlüssel. Der eigene Router ist in [ENDPOINT.md](ENDPOINT.md) dokumentiert.

## Interne API v1

Die GUI verwendet eine sitzungsgeschützte Verwaltungs-API. `GET /api/v1/status`
und `GET /api/v1/hardware` sind auch mit dem separaten API-Token lesbar.
Die Übersicht steuert den eigenen OpenAI-kompatiblen API-Listener; Demo-Dienst
und Demo-Routen wurden entfernt. Port, Profilfreigaben, Inferenzrouten,
Betriebsgrenzen und SSH-Tunnel: **[ENDPOINT.md](ENDPOINT.md)**.

Hardware: `available` bezeichnet Erfolg der Hardware-Abfrage, einzelne
Messwerte können trotzdem fehlen (`null`). Ein Ausfall der Erfassung liefert available=false,
leere Daten und eine Fehlermeldung, keine alten Werte als vermeintliches Livebild.
CPU-Auslastung: 250-ms-Differenz aus `/proc/stat` ohne doppelte Guest-Zählung.
RAM: MemTotal minus MemAvailable aus `/proc/meminfo`, Einheit Bytes.
CPU-Temperatur: k10temp/coretemp temp1_input, Grad Celsius.
GPU: nvidia-smi CSV mit Index, UUID, Name, VRAM in MiB, GPU-Auslastung in Prozent,
Temperatur in Grad Celsius. Keine Zuordnung nach vermuteter GPU-Reihenfolge.
Die Anzeige rechnet Speicher in GiB um. Fehlende Werte heißen „Nicht verfügbar“.
Abfrage bedarfsgesteuert mit fünf Sekunden Cache, GUI-Polling alle fünf Sekunden.
Keine Historie und kein Hintergrund-Collector bei geschlossener Hardware-Seite.

## Struktur und Grenzen

- `server.py`: Verwaltungs-API und lesende Hardware-Abfragen.
- `endpoint.py`: separater authentifizierter Inferenz-Listener.
- `inference.py`: native llama.cpp-Prozesse und gemeinsame GPU-Reservierung.
- `image_test.py`: eigene ComfyUI-Aufträge, gemeinsam mit dem Router koordiniert.
- `endpoint-ui.js`: Übersicht, Port und Profilfreigaben.

Sprachmodelle und Qwen-Image-Profile sind ausführbar. Qwen3-TTS CustomVoice ist ebenfalls ausführbar; übrige Audio-/Video-Laufzeiten
bleiben vorbereitet; weitere Docker-Dienste werden nur mit Deck-Labels angezeigt.
Der native systemd-Installer ist noch nicht vollständig; aktuell gilt der isolierte
Docker-Testinstaller. Keine Migration oder Steuerung des bisherigen Routers.

## Verifikation am 28.09.2026

`python3 -m unittest discover -s . -v`: drei Tests erfolgreich.
Zusätzlich GUI-Start → Läuft/Erreichbar → Stopp → Gestoppt/Nicht erreichbar geprüft.
Hardware im Browser mit Ryzen 5 5600, 46,9 GiB RAM, RTX 3060 und RTX 5080 geprüft;
CPU-/GPU-Temperaturen, VRAM und Auslastung vorhanden. Hardware-Ausfall im Test
simuliert, ohne Athena oder SSH zu unterbrechen.
Produktive Router-/Modell-/Bild-/Audio-/Netzwerkdienste nicht verändert.
Vorhandene ungesicherte Änderungen im übergeordneten Repository unangetastet.

### Bildlaufzeit installieren und Profile entfernen

Unter **Einstellungen → Laufzeiten → Bildgenerierung** zeigt Deck die Herkunft
und die festgelegten ComfyUI-/GGUF-Versionen. Fehlt die Umgebung, installiert
**Bildlaufzeit installieren** sie ohne Rootrechte in `state/image-runtime`.
Voraussetzungen: Linux, Python mit venv, Git, Internet und 25 GiB freier Speicher;
ein kompatibler NVIDIA-Treiber muss vom Systeminstaller bereitgestellt sein.
Die Installation ist abbrechbar, startet kein Modell und aktiviert die neue
Umgebung erst nach Paketprüfung. Bereits mitgelieferte Umgebungen werden erkannt;
ein Versionsupdate der Bildlaufzeit ist hier noch nicht vorgesehen.

Profile lassen sich in allen Kategorien löschen. Modell- und Komponentendateien
bleiben erhalten. Die API verhindert das Löschen des gerade ausgeführten
Bildprofils und prüft die Profilrevision gegen zwischenzeitliche Änderungen.

Neue sitzungsgeschützte API-Routen: `GET /api/v1/image-runtime`,
`POST /api/v1/image-runtime/install` und `/cancel` mit `{}` sowie
`POST /api/v1/profiles/delete` mit `{ "id": "…", "revision": 1 }`.
POST benötigt wie die übrigen Verwaltungsaktionen `X-Athena-Deck: 1`.

Die Hardware-Seite zeigt GPU-Rechenlast und VRAM-Belegung mit separaten Balken.
Es sind Host-Gesamtwerte einschließlich anderer Dienste. Der Bild-Textencoder arbeitet auf der RTX 3060, Bildmodell und VAE auf der
RTX 5080. CPU/System-RAM bleiben für Laden und Offload beteiligt. Beide GPUs
müssen frei sein; es gibt keinen stillen CPU-Fallback. GPU-Last kann während
Vorbereitung und Laden null sein. Nach Abschluss beendet Deck den eigenen Worker und gibt dessen VRAM frei.

Unter **Entdecken** steht zusätzlich **Neu hinzugefügt** zur Verfügung. Die
Abfrage sortiert bereits auf Hugging Face nach dem Erstellungsdatum des
Repositories absteigend; sie sortiert nicht nur die beliebtesten 20 Treffer um.
Name A–Z sortiert weiterhin die angezeigte Treffermenge.

Prüfung vorhandener Studios: [Native Anwendungen und Docker](docs/NATIVE_APPLICATION_AUDIT.md).

### Optionale Docker-Anwendungen

Einstellungen → Laufzeiten → Docker zeigt Verbindung, Version und gegebenenfalls
Docker-Erstinstallation. Weitere Dienste zeigt ausschließlich Container mit
`io.athena-deck.managed=true` **und** `io.athena-deck.role=application`.
Bestehende Container werden nicht automatisch übernommen. Details zu Systemhelfer,
Installer und Grenzen: [Docker-Dienste](docs/DOCKER_SERVICES.md).

Unter Entdecken blendet **Nur Basismodelle** anhand von `base_model`,
`base_model_relation` und Hub-Tags gekennzeichnete Ableitungen aus (Finetunes,
Adapter/LoRAs, Merges und separate Quantisierungen). Es werden bis zu 100 nach
der gewählten Sortierung gelieferte Kandidaten geprüft und maximal 20 angezeigt.
Die Einstellung bleibt im Browser über Kategorien hinweg erhalten. Fehlende
Herausgeber-Metadaten können dazu führen, dass Ableitungen sichtbar bleiben;
es handelt sich nicht um eine verifizierte Liste offizieller Herausgeber.
API-Parameter: `GET /api/v1/catalog/search?...&base_only=true`.

Die Suche akzeptiert auch `owner/repository` und direkte Hugging-Face-Repository-
URLs. Eine solche Direktauswahl umgeht Kategorie- und Basismodellfilter mit einem
sichtbaren Hinweis. Bei GGUF-Dateinamen wird die Endung für die Repositorysuche
entfernt. Findet die Chat-Suche nichts, werden zusätzlich als `conversational`
gekennzeichnete GGUF-Repositories ohne `text-generation`-Tag geprüft. Das ist
keine globale Suche nach beliebigen Dateinamen im Hub.

### Hugging-Face-Zugang

Unter **Einstellungen → Zugang → Hugging Face** einen eigenen `hf_…`-Token mit Leserechten speichern, ersetzen oder entfernen. Bei freigabepflichtigen Modellen vorher auf der Modellkarte mit demselben HF-Konto Zugang beantragen. Deck akzeptiert keine Lizenzbedingungen automatisch. Siehe [HF-Zugangsrechte](https://huggingface.co/docs/hub/models-gated) und [Token](https://huggingface.co/docs/hub/security-tokens).

Der Token wird ausschließlich serverseitig unter `models/huggingface.json` im Deck-Zustandsverzeichnis gespeichert (0600, unverschlüsselt); Zustandsbackups entsprechend schützen. Er gilt für Katalogabfragen, Modell- und Komponentendownloads aller Kategorien. HTTP-Weiterleitungen auf andere Hosts erhalten keinen Authorization-Header. Entfernen verhindert neue authentifizierte Anfragen, beendet aber keinen bereits autorisierten Download. Download abbrechen bei Bedarf separat nutzen.

Interne API (nur angemeldete Administratorsitzung): `GET /api/v1/huggingface` liefert ausschließlich `{configured: boolean}`; `POST` mit `{token: "hf_…"}` speichert/ersetzt, mit `{token: null}` entfernt. POST benötigt `X-Athena-Deck: 1`. Kein API-Endpunkt liefert den gespeicherten Token zurück. HTTP 401/403 von HF ergeben Hinweise auf Token, Leserechte und Modellfreigabe; die tatsächliche Freigabe wird beim Download geprüft.

### Video: externe Dienste statt Deck-Profile

Deck verwaltet für Video ausschließlich den aktiven Dienst, Start/Stopp und die GPU-Freigabe. Unter **Video → Aktiver Videodienst** einen administrativ eingerichteten Dienst wählen; unter **Übersicht → Video** starten. **LLM** beendet den Videodienst. Modellauswahl, Komponenten, Auflösung, Dauer, Prompts und Generierung erfolgen ausschließlich über dessen Original-API und Oberfläche. Heute ist LTX Desktop angebunden; weitere containerisierte Videodienste lassen sich mit derselben Dienststeuerung registrieren. Keine Übersetzung zwischen APIs.

Der Video-Bereich ist wieder Teil der KI-Werkzeuge. Generierungsparameter bleiben ausschließlich in der Video-Anwendung. Das frühere Testformular, die eigene Video-Laufzeitinstallation und `/v1/videos`-Generierung sind entfernt. Alte Profil- und Modelldaten bleiben auf Platte erhalten, werden jedoch nicht mehr als aktive Videoprofile angeboten. `/v1/videos…` liefert HTTP 410 mit Verweis auf die Original-API. Der ursprüngliche Deck-Python-Video-Worker wird nicht mehr installiert oder gestartet.

Die Steuerung erfolgt über den beschränkten Docker-Systemhelfer, ohne Docker-Socket in Deck. Root registriert Container-IDs, API-Adresse und Healthcheck in `/var/lib/athena-deck-docker/video-services.json`. Nur registrierte Dienste können gestartet/gestoppt werden; beliebige Docker-Aktionen sind ausgeschlossen. Siehe [Videodienste](docs/DOCKER_SERVICES.md#videodienste).

Vor Videostart beendet Deck seine eigenen GPU-Aufträge, wartet auf Freigabe und verweigert den Start bei fremden GPU-Prozessen. Der alte Router bleibt unberührt. Im Videomodus wird der gemeinsame API-Port vollständig auf die Original-API des aktiven Videodienstes umgeschaltet. Chat/Bild/TTS/STT-Clients können diesen Port erst nach dem Rückwechsel auf LLM wieder verwenden. Beim Deck-Neustart wird ein laufender registrierter Videodienst erkannt und die GPU-Sperre wiederhergestellt; kein automatischer Dienststart und kein Abbruch externer Generierung beim bloßen Deck-Neustart.

LTX auf Athena: originale API am Host `http://127.0.0.1:41955`, bestehender SSH-Zugang über LTX Athena. Alternativer Tunnel vom Mac:

```sh
ssh -N -i /Users/mike_i386/.ssh/athena_key -o BatchMode=yes -o ExitOnForwardFailure=yes -L 41956:127.0.0.1:41955 root@192.168.1.212
```

Dann API unter `http://127.0.0.1:41956`; Authentifizierung mit dem bestehenden LTX-Token, nicht dem Deck-Token. Keine Zugangsdaten in URLs. Der Port stellt eine API bereit, keine Browser-Studio-Oberfläche.

### Gemeinsamer API-Port: Protokollwechsel

Im LLM-Modus bleibt der Deck-Endpunkt OpenAI-kompatibel. Im Videomodus werden HTTP-Pfad, Query, Methode, Inhalt, Antwortstatus und Antwortdaten unverändert an die registrierte Video-API weitergereicht. Es gibt keine Modell-/Parameterübersetzung. Beispiel auf Port 8120: `POST /api/generate`, `GET /api/generation/progress`, `POST /api/generate/cancel`. Kein `/v1`-Präfix für LTX. Während des Moduswechsels HTTP 503.

Am gemeinsamen Port gilt weiterhin der Deck-Bearer-Token. Der root-eigene Helfer setzt intern den separaten LTX-Token; er gibt ihn niemals an Deck oder den Browser zurück. Der interne LTX-Port 41955 bleibt unverändert, sodass der bisherige LTX-Athena-Zugang weiter funktioniert. HTTP GET/POST/PUT/PATCH/DELETE/HEAD/OPTIONS und Range-Header werden transportiert. Request-Bodies benötigen Content-Length (maximal 256 MiB); kein WebSocket-Transport. Die geprüfte LTX-Desktop-API verwendet für Fortschritt HTTP-Polling.

Ein separates LTX-Webfrontend gehört als Docker-Anwendung unter Weitere Dienste, nicht die Video-Laufzeit-Auswahl. Dieses Webfrontend ist noch nicht implementiert. Der vorhandene LTX-Athena-Client benötigt neben API-Zugriff weiterhin seine Dateiübertragung über SSH/SCP; ein Browser-Port muss Electron-Dateifunktionen separat ersetzen. Weiterleitung allein stellt keine neuen Datei-Upload-/Downloadrouten im LTX-Backend bereit.