<!-- status: canonical -->
<!-- lastReviewed: 2026-04-05 -->
<!-- verifiedAgainst: private-llm (codebase review 2026-04-05) -->

# Private LLM -- Architektur

## Überblick

Eigenständiger Service für die Verarbeitung sensitiver Daten mit lokalen AI-Modellen (Ollama). Läuft auf einem dedizierten GPU-Server (Infomaniak Swiss Cloud) und wird vom Gateway als Provider-Plugin (`aicorePluginPrivateLlm.py`) angesprochen. Kein Datenabfluss an externe Cloud-APIs.

## Technologie-Stack

| Layer | Technologie |
|-------|------------|
| Framework | FastAPI (Python) |
| AI Runtime | Ollama (lokale Vision/Text-Modelle) |
| PDF-Support | PyMuPDF (fitz) |
| Hosting | Infomaniak Swiss Cloud (GPU) |
| Deployment | GitHub Actions → `main` Branch |

## Modelle

| Externer Name | Internes Ollama-Modell | Typ |
|--------------|----------------------|-----|
| `poweron-text-general` | `qwen2.5:7b` | Text |
| `poweron-vision-general` | `qwen2.5vl:7b` | Vision |
| `poweron-vision-deep` | `granite3.2-vision` | Vision |

## API-Routen

| Modul | Zweck |
|-------|-------|
| `routeApi.py` | Analyse-API: Bild-/PDF-Analyse mit Prompt, Modellauswahl |
| `routeOpenAi.py` | OpenAI-kompatibles Chat-Completion-API (für Cursor-Integration) |
| `routeWeb.py` | Web-UI für manuelle Tests |

## Integration mit Gateway

Der Gateway nutzt das Private LLM über `aicorePluginPrivateLlm.py` als Provider für:
- **Neutralisierung:** Text-Analyse mit `poweron-text-general`
- **Sensitive Datenverarbeitung:** Vision-Analyse von Dokumenten (Rechnungen, Belege, Handschrift)
- **Keine Billing-Kosten** für mandanteninterne LLM-Calls (eigene Infrastruktur)

## Sicherheit

- API-Key-Authentifizierung (`X-API-Key` Header)
- Separater Cursor-API-Key für OpenAI-kompatible Endpoints (Bearer Token)
- Rate-Limiting per API-Key (Token Bucket, konfigurierbar)
- Konfiguration über `config.ini` + Environment-Variablen (Secrets nie im Code)

## Schlüssel-Dateien

| Datei | Rolle |
|-------|-------|
| `app.py` | FastAPI-Einstieg, Router-Mount |
| `config.py` | Konfiguration, Model-Mapping, Auth, Rate-Limiting, Request/Response-Modelle |
| `routeApi.py` | Analyse-Endpunkte (Bild, PDF) |
| `routeOpenAi.py` | OpenAI-kompatibles Chat-API |
| `routeWeb.py` | Test-UI |

## Regeln / Invarianten

- Alle Daten werden **lokal** verarbeitet -- kein Weiterleiten an externe APIs
- Model-Mapping ist die einzige Stelle für Namensauflösung (`MODEL_MAPPING` in `config.py`)
- API-Keys werden aus `config.ini` oder Environment gelesen, nie hardcoded
- PDF-Verarbeitung rendert Seiten als Bilder für Vision-Modelle (max 5 Seiten)