LiteLLM Auto-Synch-Manager

Ein CLI-Werkzeug, das eine LiteLLM-Instanz deklarativ synchronisiert. Statt Modelle, Credentials, Access-Groups und Virtual-Keys per Hand in der Admin-UI zu pflegen, beschreibt man den gewünschten Zustand in Dateien und lässt das Script die Differenz zum Ist-Zustand ausführen.

• Idempotent – beliebig oft ausführbar, gleiches Ergebnis.
• Dry-Run als Standard – ohne --apply wird nichts geschrieben.
• Versionierbar – der Soll-Zustand liegt als YAML im Repository.
• Abgesichert – fünf Validierungsphasen, Error-Reports, Master-Key-Schutz.

Aufbau

litellm_auto_synch/
├── litellm_auto_synch_manager.py   # Das Hauptscript
├── config/                         # Einstellungen des Skripts
│   ├── .env                        #   Geheimnisse (nicht in Git)
│   ├── _beispiel.env               #   Vorlage fuer .env (vom Merge ausgeschlossen)
│   ├── config.yaml                 #   settings + server_definition
│   └── README.md                   #   Vollständige Einstellungsreferenz
├── data/                           # Inhalte für LiteLLM
│   ├── _data.yaml                  #   Konsolidierte Gesamtfassung (ausgeschlossen)
│   ├── app.vkeys.yaml              #   Virtual-Keys + Access-Groups
│   ├── embedding.gemini.yaml
│   ├── hermes.data.yaml
│   ├── opencode.data.yaml
│   ├── voice.data.yaml
│   └── README.md                   #   Referenz aller Entitäten
├── virtual_keys/                   # Key-Generator + lokale Spiegelung
│   ├── virtual_key_generator.py
│   ├── keygen.json                 #   Kürzel je Access-Group
│   ├── vkeys.env                   #   KEY_ALIAS=KEY_VALUE (automatisch)
│   └── vkeys.json                  #   Server-Antwort je Alias (automatisch)
├── scripts/                        # Hilfsskripte
├── docs/                           # Ausführliche Dokumentation
├── tests/                          # Offline-Testsuite
├── test_all_modes.py               # Szenario-Tests aller Modi
└── logs/                           # Logs, Snapshots, Error-Reports
    └── autogenerated/              #   Gemergte Gesamtfassungen je wirksamem Lauf

Die zwei Datenordner

Beide Ordner werden nach demselben Prinzip gelesen: alle Dateien direkt im Ordner werden alphabetisch gemergt, Dateien mit _-Präfix bleiben ausgeschlossen. Statt eines Ordners kann auch eine einzelne Datei oder eine Liste angegeben werden.

Wichtige Stellen im Projekt

Installation

Ab v1.9.1 werden Releases als Windows-EXE, Python-Wheel und PyPI-Package bereitgestellt.

pip install litellm-auto-synch-manager
lasm --help

Nach der Installation stehen mehrere gleichwertige CLI-Namen zur Verfügung:

lasm
litellm-auto
litellm-sync
litellm-auto-synch
litellm-auto-synch-manager

Bei Wheel-Installationen werden config/, data/, virtual_keys/ und logs/ relativ zum aktuellen Arbeitsverzeichnis verwendet. Die Windows-EXE verwendet den Ordner der EXE, wenn dort die bestehende V1-Projektstruktur liegt, andernfalls ebenfalls das aktuelle Arbeitsverzeichnis. Es werden dabei keine Config- oder Data-Dateien automatisch erzeugt.

Die Windows-EXE enthält zwei eingebettete Windows-Icon-Ressourcen: das kompakte LASM-Symbol als primäres Programm-/Fenster-Icon und das vollständige LASM-Logo als zusätzliche Icon-Ressource für Windows-Verknüpfungen.

Der automatisierte Build- und Release-Prozess ist in docs/releasing.md dokumentiert.

Schnellstart

1. Voraussetzungen

pip install -r requirements.txt

Python 3.11 oder neuer; als externe Abhängigkeit wird nur PyYAML benötigt.

2. Geheimnisse hinterlegen

config/.env aus der mitgelieferten Vorlage anlegen (die echte Datei ist über .gitignore ausgeschlossen; die Vorlage ist durch ihren _-Präfix vom Merge ausgenommen und deshalb im Repository):

cp config/_beispiel.env config/.env      # Linux / macOS
copy config\_beispiel.env config\.env    # Windows

Anschließend die Platzhalter ersetzen:

LITELLM_API_KEY=sk-dein-admin-key
LITELLM_MASTER_KEY=sk-dein-admin-key

OPENCODE_API_KEY=sk-…
HERMES_API_KEY=…

3. Server-Profil prüfen

In config/config.yaml:

settings:
  server: local

server_definition:
  local:
    litellm_base_url: https://litellm.example.com
    litellm_api_key: ${LITELLM_API_KEY}

4. Erster Lauf

python litellm_auto_synch_manager.py

Das ist ein Dry-Run: Es wird nichts geschrieben, aber der vollständige Plan ausgegeben.

Die Betriebs-Modi

Ohne Flag läuft immer ein Dry-Run. --apply ist der Schalter, der aus einem Plan tatsächliche Änderungen macht.

Bei einer Installation über Wheel/PyPI können die bestehenden V1-Modi zusätzlich als kurze Commands geschrieben werden. Sie sind reine Aliase und ändern die Semantik der bisherigen Flags nicht:

lasm apply          # exakt wie: lasm --apply
lasm add            # exakt wie: lasm --add (Dry-Run)
lasm add --apply    # exakt wie: lasm --add --apply
lasm prune          # exakt wie: lasm --prune (Dry-Run)
lasm prune --apply  # exakt wie: lasm --prune --apply
lasm reset          # exakt wie: lasm --reset

Die bisherigen Flag-Aufrufe und der direkte Start über python litellm_auto_synch_manager.py ... bleiben unverändert gültig.

Dry-Run (Standard)

python litellm_auto_synch_manager.py

Liest config/ und data/, holt den Ist-Zustand aus LiteLLM und zeigt, was passieren würde. Keine schreibenden Aufrufe. Der vollständige Plan mit Begründung je Operation steht in logs/sync_*.log.

Sync anwenden – --apply

python litellm_auto_synch_manager.py --apply

Führt den Plan aus: Credentials, Modelle, Access-Groups und Virtual-Keys werden angelegt oder aktualisiert. Verwaltete Access-Groups und Virtual-Keys, die nicht mehr in data/ stehen, werden gelöscht. Anschließend laufen die Post-Execute-Validierungen (Valid3–Valid5).

Zusätzlich wird die gemergte Gesamtfassung nach logs/autogenerated/ geschrieben.

Additiv – --add

python litellm_auto_synch_manager.py --add          # Dry-Run
python litellm_auto_synch_manager.py --add --apply  # anwenden

Nur Hinzufügen und Aktualisieren, niemals Löschen – auch nicht bei verwalteten Objekten und auch nicht mit prune_model_name_prefixes. Der richtige Modus für produktive Instanzen, auf denen fremde Objekte existieren, und für CI/CD.

Aufräumen – --prune

python litellm_auto_synch_manager.py --prune          # Dry-Run: was würde gelöscht?
python litellm_auto_synch_manager.py --apply --prune  # anwenden

Löscht zusätzlich Modelle, die vom Script verwaltet werden (managed_by stimmt) oder deren Name mit einem der prune_model_name_prefixes beginnt, und die nicht mehr in data/ stehen.

Destruktiv. Immer erst ohne --apply prüfen.

Zurücksetzen – --reset

python litellm_auto_synch_manager.py --reset

Leert die Instanz: Credentials, Modelle, Access-Groups und Virtual-Keys werden gelöscht, vkeys.env und vkeys.json geleert.

Sofort destruktiv, kein Dry-Run. Der Master-Key (LITELLM_API_KEY) wird anhand seines Werts erkannt und ausgenommen. Nur gegen Test-Instanzen verwenden. Schließt sich mit --apply gegenseitig aus.

Instanz wechseln – --server

python litellm_auto_synch_manager.py --server vps --apply

Wählt ein Profil aus server_definition. Profile können eigene Einstellungen mitbringen, nicht nur eine eigene URL.

Quelle wechseln – --config / --data

# Nur eine Datendatei
python litellm_auto_synch_manager.py --data data/opencode.data.yaml

# Die konsolidierte Gesamtfassung (trotz '_', weil explizit angegeben)
python litellm_auto_synch_manager.py --data data/_data.yaml

# Mehrere Quellen
python litellm_auto_synch_manager.py --data "data/opencode.data.yaml, data/app.vkeys.yaml"

Weitere Schalter

Vollständige Referenz: docs/cli-argumente.md.

Empfohlener Ablauf

# 1. Plan prüfen
python litellm_auto_synch_manager.py

# 2. Anwenden
python litellm_auto_synch_manager.py --apply

# 3. Gegenprobe: sollte überall SKIP zeigen
python litellm_auto_synch_manager.py

# 4. config/config.yaml und data/*.yaml committen (config/.env bleibt außen vor)

Ausgaben und Nachvollziehbarkeit

Der gesamte logs/-Ordner ist über .gitignore ausgeschlossen.

Tests

# Unit- und Integrationstests (offline, ohne Netzwerk)
python tests/test_litellm_auto_synch_manager.py

# Szenario-Tests für alle Modi
python test_all_modes.py

Sicherheit in drei Sätzen

Geheimnisse gehören ausschließlich in config/.env (oder in echte Umgebungsvariablen) und werden in yaml-Dateien nur als ${NAME} referenziert. In Konsole, Logs und Merge-Dumps erscheinen sie maskiert. config/.env, logs/ und virtual_keys/vkeys.* sind über .gitignore ausgeschlossen.

Details: docs/sicherheit.md.