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.

### LTX-2.5-Komponentenrezept

Video → Profile → Komponenten unterstützt das offizielle `Lightricks/LTX-2.5`-Modell `diffusion_models/ltx-2.5-22b-distilled-transformer-bf16.safetensors`. Das Herstellerrezept für die zweistufige Distilled-Pipeline mit fester Bildanzahl umfasst Gemma 4 12B inklusive LTX-Projektionen, Video-VAE, Audio-VAE/Vocoder und Spatial-Upsampler. Quelle: https://huggingface.co/Lightricks/LTX-2.5 . Metadaten und Downloads sind an den Commit des Hauptmodells gebunden; Zuordnung anderer Revisionen wird abgelehnt. Der Katalog kann dafür feste historische Commits abrufen. Vorhandene Komponenten werden erkannt, fehlende über die normale Warteschlange geladen und anschließend im Profil gespeichert.

Das Rezept unterstützt keine beliebigen Quantisierungen, Comfy-INT8-Encoder oder andere Modellfamilien. Duration-Head, Temporal-Upsampling und DFR sind optional und nicht enthalten. Die Video-Ausführung bleibt gesperrt, solange kein Video-Worker angebunden ist. Vollständige Dateien sind keine Zusage, dass BF16-Modell und Encoder in RAM/VRAM passen. Komponenten werden nicht als eigenständige Modelle angeboten. Keine automatischen Zusatzdownloads beim Öffnen der Ansicht.

### Exklusiver Video-Modus und Worker

Unter **Video → Profile** genau ein Profil mit **Am API-Endpunkt freigegeben** auswählen, dann in der Übersicht **Video** drücken. Ein neuer Haken ersetzt die vorige Video-Freigabe; Abwählen entfernt sie. Die Übersicht zeigt nur den Profilnamen und die Modusschalter. Änderungen der Video-Freigabe erfordern den LLM-Modus. Deck schließt zuerst die GPU-Auftragsannahme, beendet eigene Chat-/Auto-Test-/Bild-/TTS-Arbeit und entlädt seinen llama.cpp-Prozess. Erst nach Freigabe der Reservierungen und Prüfung **aller** sichtbaren GPUs startet der eigene LTX-Worker. Fremde GPU-Prozesse werden niemals beendet; der Wechsel scheitert dann mit einer sichtbaren Meldung. **LLM** beendet den Video-Prozess einschließlich einer laufenden Generierung und öffnet die GPU-Auftragsannahme wieder. Das nächste Chat-Modell lädt bei Anfrage. Nach Deck-Neustart gilt LLM; es gibt keinen automatischen Videostart.

Die Video-Laufzeit lässt sich unter Einstellungen → Laufzeiten → Video installieren/abbrechen. Sie verwendet eine eigene venv, den in `video_runtime.py` gepinnten offiziellen LTX-Commit sowie `deploy/video-requirements.lock` (PyTorch CUDA 12.8, keine Host-Treiberänderung). Die Module und Lockdatei gehören zu beiden Installationspaketen. Der erste Adapter unterstützt das dokumentierte LTX-2.5-Distilled-BF16-Komponentenrezept. Beide GPUs sind für Deck exklusiv reserviert, die Berechnung erfolgt zunächst auf der RTX 5080 mit Disk-Streaming; die RTX 3060 bleibt frei. „Bereit“ heißt: persistenter Worker, Pipeline und Komponentenmetadaten vorbereitet. BF16-Gewichte werden bedarfsgerecht gestreamt, nicht vollständig im VRAM gehalten. Eine freie GPU garantiert keinen OOM-freien Auftrag.

Eigene Video-API auf demselben API-Port und mit demselben Bearer-Token wie Chat (keine vollständige OpenAI-Videos-Kompatibilitätszusage):

- `GET /v1/videos/models`: `athena-video`, wenn das ausgewählte Profil ausführbar ist.
- `POST /v1/videos`: `{model:"athena-video",prompt:"…",width:512,height:320,frames:9,fps:24,seed:42}` → HTTP 202 mit Auftrags-ID. Der Video-Modus muss bereits bereit sein. Ein Auftrag gleichzeitig, kein automatischer Moduswechsel.
- `GET /v1/videos/{id}`: Zustand/Phase und Fehler des letzten Auftrags, ohne Prompt.
- `GET /v1/videos/{id}/content`: fertige MP4 einschließlich Audiospur.

Anfragewerte überschreiben Profilstandards. Breite/Höhe sind Vielfache von 64, 256–1920 bzw. 256–1088; Bildanzahl 9–241 in der Form 8n+1, FPS 1–60. Distilled hat eine feste Schrittfolge; das bisherige allgemeine Schritte-Profilfeld wird von diesem Adapter nicht verwendet. Resultate liegen im Deck-Zustandsverzeichnis `video/`; der erste Adapter bietet jeweils den letzten Auftrag an. Kein Prompt wird auf Platte geschrieben. Eigener Video-Test mit Vorschau/Download unter Video → Testen. Bild-/Audio-Upload, automatische Video-Tool-Aufträge aus Hermes, Abfragehistorie und automatische Ergebnisbereinigung sind noch nicht umgesetzt.

Während Video/Moduswechsel erhalten neue Chat-, Bild- und TTS-API-Aufträge HTTP 503 mit `video_mode_active`. CPU-STT bleibt verfügbar. Ein Wechsel wird nur über die angemeldete Verwaltungsoberfläche ausgelöst; API-Clients dürfen den Modus nicht heimlich zurückschalten. Die interne Verwaltungs-API verwendet `GET /api/v1/video`, `POST /api/v1/video/profile` mit `{id}`, `POST /api/v1/video/mode` mit `{mode:"llm"|"video"}`, `/api/v1/video/generate` und `/api/v1/video-runtime/install|cancel`; jeweils bestehender Sitzungsschutz und POST-Header `X-Athena-Deck: 1`.

Video-Build-Voraussetzung: Python-Entwicklungsheader passend zur verwendeten Python-Version sowie ein C-Compiler (Debian: `python3-dev`, `build-essential`). Das Docker-Installationspaket bringt diese mit. Triton kompiliert seinen CUDA-Helfer beim ersten Auftrag; dafür werden keine Host-Treiber installiert.

Verifiziert auf Athena am 29.09.2026: offizielles LTX-2.5-Distilled-BF16-Profil mit zugeordneten Komponenten vorbereitet; exklusiver Modus sperrt Chat mit HTTP 503 / `video_mode_active`; synthetischer POST-Videoauftrag liefert HTTP 202, Statusabfrage und MP4-Download funktionieren. Ergebnis: 256×256, 9 dekodierbare Bilder, 24 FPS und Audiospur (12.802 Bytes). Nach Rückwechsel auf LLM war der Video-Prozess beendet und der GPU-Speicher wieder auf Treibergrundbelegung (3060: 1 MiB, 5080: 6 MiB). Der anfängliche Triton-Kompilierfehler wurde durch Python-Entwicklungsheader im Deck-Image behoben. Kein Produktivdienst wurde für diese Prüfung verändert. Dieser kleine Funktionstest ist keine Speicher- oder Geschwindigkeitsgarantie für größere Auflösungen/Längen.

Video-Oberfläche: Moduswechsel erfolgen ausschließlich in der Übersicht. Eine laufende Ladeanzeige zeigt Phase und verstrichene Zeit. Video → Testen meldet einen falschen Modus mit Link zur Übersicht und bestätigt das Absenden sofort. Video → Laufend zeigt ausschließlich Worker, aktuellen Auftrag und Ergebnis. Installationsaktionen liegen unter Einstellungen → Laufzeiten → Video. Die Auftragsanzeige wird alle 1,5 Sekunden aktualisiert; der Worker liefert Phasen, jedoch keine belastbaren Prozentwerte.