astra-vision/README.md

astra-vision

Fork von astra-local-voice. Gleicher lokaler Sprachagent, plus Bilderzeugung (ComfyUI) und Bild/PDF-Upload mit Vision (siehe unten). Die schlanke Basisversion ohne diese Werkzeuge lebt im Hauptrepo — dorthin zurück, falls du nur den reinen Sprachagenten willst.

Ein lokaler deutscher Sprachagent für Apple Silicon. Kein Cloud-Anruf, kein Tracking, kein gespeichertes Audio — Spracherkennung, Sprachmodell und Sprachausgabe laufen alle auf deinem Mac.

Wie es funktioniert

Drei lokale Modelle, verbunden über eine Pipecat-Pipeline:

Stufe	Modell	Wo
Spracherkennung	Nemotron ASR (streaming)	MLX, on-device
Sprachmodell	Qwen 3.5	über natives Ollama /api/chat
Sprachausgabe	Pocket TTS, 26 deutsche Stimmen wählbar	MLX, on-device

Der Browser spricht per WebRTC direkt mit einem FastAPI-Server auf localhost:7860. Der Server ist bewusst nur lokal erreichbar: Host- und Origin-Prüfung auf jedem Request, strikte Content-Security-Policy, keine offenen Ports nach außen.

Die Stimme lässt sich im UI per Dropdown wählen (/api/voices listet alle 26, Auswahl wird im Browser gemerkt). Jede Stimme wird beim ersten Gebrauch lazy geladen und danach für die Laufzeit des Prozesses gecacht.

Architektur

Jede Fähigkeit ist ein eigenständiges, gegenseitig unabhängiges Modul — verifiziert am Import-Graphen, nicht nur behauptet:

astra/comfyui.py     — nur httpx, kein astra-Import
astra/rss.py         — nur feedparser+httpx, importiert astra.feeds (Daten)
astra/articles.py    — nur httpx+trafilatura, kein astra-Import
astra/documents.py   — nur pypdf, kein astra-Import
astra/feeds.py       — reine Daten, kein einziger Import

Keines dieser fünf Module kennt Pipecat, LLM-Tools oder ein anderes der fünf. astra/tools.py ist die einzige Stelle, die sie zu LLM-aufrufbaren FunctionSchemas verdrahtet (Beschreibung + Handler + UI-Benachrichtigungen). astra/triggers.py ruft dieselben Handler bei Bedarf direkt auf — per Introspektion über context.tools, ohne tools.py zu importieren — wenn ein einfacher Keyword-Treffer zuverlässiger ist als die LLM-Entscheidung (siehe unten).

Werkzeuge im Überblick

Werkzeug	Macht	Ausgelöst durch	Live gemessene Zuverlässigkeit
generate_image	Bild via ComfyUI erzeugen	LLM-Entscheidung	~100 %
read_news	Schlagzeilen aus konfiguriertem RSS-Thema	Keyword-Trigger (triggers.py)	~100 % (Trigger) / ~15–20 % (reine LLM-Entscheidung)
read_article	Vollen Artikeltext zu einer Nummer/URL laden	Keyword-Trigger + LLM-Fallback	Trigger 2/2 live; LLM-Fallback ~65 %

Bilder erzeugen und Dokumente lesen

Zwei zusätzliche, sauber getrennte Fähigkeiten, unabhängig von STT/LLM/TTS:

• astra/comfyui.py — reiner async HTTP-Client für einen lokalen ComfyUI-Server (z-image-turbo-Workflow). Kennt nichts von Pipecat.
• astra/documents.py — PDF-Textextraktion (pypdf), keine Netzwerkzugriffe.
• astra/tools.py — verdrahtet generate_image als natives Ollama-Tool. Qwen 3.5 entscheidet selbst, wann es aufgerufen wird (ollama show qwen3.5 listet tools als unterstützte Fähigkeit); das generierte Bild landet im laufenden Gespräch als /api/media/<id> und wird per WebRTC-Datenkanal ans UI gemeldet.

Bilder (PNG/JPEG/WebP) und PDFs lassen sich während eines laufenden Gesprächs über den Button „Bild oder PDF hinzufügen“ hochladen (POST /api/upload). Ein PDF wird als Text in den Gesprächskontext eingefügt, ein Bild als Base64 mit Qwens nativer Vision-Fähigkeit — beides nur für die Dauer der Session, nichts wird auf Disk geschrieben.

Nachrichten aus deutschen RSS-Feeds

• astra/feeds.py — kuratierte Feed-Liste, nach Thema gruppiert (tech, nachrichten, wirtschaft, hilden — lokal für Hilden via RP ONLINE). Reine Daten, editierbar: neues Thema = neuer Dict-Key mit {"name": ..., "url": ...}-Tupeln, neuer Feed = eine Zeile in einem bestehenden Thema. TOPICS wird automatisch aus den Keys abgeleitet, taucht dadurch sofort im read_news-Schema (enum) und in triggers.py's Themen-Erkennung auf — keine weitere Codeänderung nötig, solange der neue Themenname selbsterklärend ist (sonst zusätzlich einen Alias in _TOPIC_ALIASES in astra/triggers.py ergänzen).
• astra/rss.py — async Feed-Client (feedparser), holt konfigurierte Feeds eines Themas parallel ab, überspringt nicht erreichbare Feeds statt komplett zu scheitern.
• Tool read_news in astra/tools.py: Astra ruft es auf, wenn nach aktuellen Nachrichten gefragt wird, und fasst die Schlagzeilen mündlich zusammen statt sie roh vorzulesen.
• astra/articles.py — lädt eine Artikel-URL und extrahiert den reinen Fließtext (trafilatura), ohne Navigation/Werbung/Boilerplate.
• Tool read_article in astra/tools.py: Astra ruft es auf, wenn der Nutzer zu einer schon genannten Schlagzeile mehr wissen will, und liest den vollen Artikeltext statt nur der RSS-Kurzbeschreibung.

Tool-Verhalten steht bewusst ausschließlich in der jeweiligen FunctionSchema.description (siehe astra/tools.py), nicht im SYSTEM_PROMPT — eine Quelle der Wahrheit pro Werkzeug statt duplizierter Regeln in einem wachsenden globalen Prompt. Gemessener Preis davon: mit drei gleichzeitig verfügbaren Tools (Bild + Nachrichten + Artikel) ruft das lokale 9,7B-Modell read_news nur noch in ca. 15–20 % der Fälle tatsächlich auf (vorher mit zwei Tools ca. 20–50 %, mit Tool-Regeln zusätzlich im System-Prompt ca. 60–75 %) und erfindet sonst Schlagzeilen. read_article ist bei einer konkreten Nachfrage zu einer schon genannten Schlagzeile brauchbarer (~65 %, vermutlich weil der Kontext dort weniger mehrdeutig ist). Bildgenerierung bleibt bei ~100 % zuverlässig. Bekannte Grenze eines kleinen lokalen Modells bei Tool-Konkurrenz, kein Bug — die saubere Trennung war eine bewusste Architekturentscheidung.

astra/triggers.py umgeht diese Grenze gezielt für read_news: ein einfacher Keyword-Check (nachrichten/news + optional ein Themen-Alias wie hilden/technik/wirtschaft) im transkribierten Nutzertext ruft den read_news-Handler direkt auf — derselbe Handler, dieselbe UI, nur ohne die unzuverlässige LLM-Entscheidung dazwischen. Das Ergebnis landet als Tool-Roundtrip im Kontext, damit die nächste LLM-Antwort es kennt. Live getestet: 2/2 zuverlässig, wo die reine LLM-Entscheidung nur ~15–20 % erreichte.

Schlagzeilen werden nummeriert angezeigt (1., 2., 3. …), und derselbe Mechanismus kennt einen zweiten Trigger: detect_article_reference() erkennt Formulierungen wie "Artikel 2", "Artikel Nummer drei" oder "zweiter Artikel" im Nutzertext, löst die Nummer gegen die zuletzt gezeigte Liste auf und ruft read_article direkt mit dem passenden Link auf — ganz ohne dass das Modell selbst den richtigen Link kennen oder sich für das Werkzeug entscheiden muss. Live getestet über einen echten Zwei-Turn-Dialog ("News Hilden" → "Hole mir Detail zu Artikel zwei"): korrekt aufgelöst, echter Artikeltext abgerufen.

generate_image bleibt bewusst ein reines LLM-Tool, weil ein Bildwunsch zu variabel für ein Keyword-Muster ist und ohnehin zuverlässig funktioniert.

Starten

uv sync
uv run python -m astra.prepare   # lädt & prüft alle drei Modelle einmalig
uv run python -m astra.server    # startet auf http://localhost:7860

Ollama muss separat laufen (ollama serve) und qwen3.5:latest muss gezogen sein. Die Seite öffnen, Mikrofon erlauben, sprechen.

Konfiguration

Über Umgebungsvariablen, siehe astra/core.py::Settings:

Variable	Default
ASTRA_MODEL	qwen3.5:latest
ASTRA_OLLAMA_URL	http://127.0.0.1:11434
ASTRA_STT_MODEL	mlx-community/nemotron-3.5-asr-streaming-0.6b-8bit
ASTRA_TTS_LANGUAGE	german
ASTRA_VOICE	alba
ASTRA_PORT	7860
ASTRA_TAILNET_HOST	(leer) — z. B. minim4-1.tail0f2cb2.ts.net
ASTRA_COMFYUI_URL	http://100.125.107.123:8000

Tests

uv run pytest
uv run ruff check .

Im Tailnet freigeben

Standardmäßig nur localhost erreichbar. Für Zugriff von einem anderen Gerät im selben Tailscale-Netz:

tailscale serve --bg 7860
ASTRA_TAILNET_HOST="$(tailscale status --json | python3 -c 'import json,sys;print(json.load(sys.stdin)["Self"]["DNSName"].rstrip("."))')" \
  uv run python -m astra.server

Danach ist die Seite unter https://<tailnet-host>/ erreichbar (Port 443, implizit — Tailscale terminiert TLS und proxyt auf 7860). Host- und Origin-Prüfung lassen dann zusätzlich diesen einen Hostnamen durch.

Sicherheit

• Nur localhost/127.0.0.1 (bzw. der optionale Tailnet-Host) erreichbar, alle anderen Hosts bekommen 403
• POST-Requests werden gegen den erwarteten Origin geprüft
• think ist im Ollama-Request hart auf false gesetzt — die Pipeline wirft, falls das Modell trotzdem Denkausgabe liefert
• Kein Audio, keine Transkripte werden auf Disk geschrieben; der Gesprächsverlauf lebt nur im Speicher der laufenden Session
• Anders als die Basisversion macht dieser Fork bewusst ausgehende Verbindungen: zu ComfyUI (ASTRA_COMFYUI_URL), zu den konfigurierten RSS-Feeds (astra/feeds.py) und zu beliebigen Artikel-URLs, die read_article aufruft (aus einem read_news-Ergebnis oder — bei LLM-Tool-Aufruf statt Trigger — theoretisch vom Modell selbst vorgeschlagen). Alle drei sind auf ihre jeweilige eigene HTTP-Anfrage begrenzt, keins davon hat sonstigen Datei- oder Netzwerkzugriff.

---

Erstellt von Astra (Grunddeploy), gecheckt, dokumentiert und bewertet durch Claude.