Metadata-Version: 2.4
Name: litellm-auto-synch-manager
Version: 1.9.1
Summary: Declarative synchronization CLI for LiteLLM models, credentials, access groups and virtual keys.
Author: Marco Sudau
Project-URL: Homepage, https://github.com/marcosudau-vps/litellm_auto_synch_manager
Project-URL: Repository, https://github.com/marcosudau-vps/litellm_auto_synch_manager
Project-URL: Issues, https://github.com/marcosudau-vps/litellm_auto_synch_manager/issues
Keywords: litellm,cli,configuration,sync,automation
Classifier: Development Status :: 5 - Production/Stable
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Software Development :: Build Tools
Classifier: Topic :: System :: Systems Administration
Requires-Python: >=3.11
Description-Content-Type: text/markdown
Requires-Dist: PyYAML>=6.0
Provides-Extra: dev
Requires-Dist: build>=1.2; extra == "dev"
Requires-Dist: pytest>=8.0; extra == "dev"
Requires-Dist: twine>=6.0; extra == "dev"
Requires-Dist: pyinstaller>=6.0; extra == "dev"

# 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

| Ordner | Inhalt | Beispiel |
|---|---|---|
| `config/` | Einstellungen, die **das Skript** betreffen | Base-URL, API-Key, `managed_by`, Timeout, Server-Profile |
| `data/` | Inhalte, die **auf LiteLLM** angelegt werden | `providers`, `endpoint_types`, `credentials`, `access_groups`, `models`, `keys` |

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

| Ich will … | … dann hierhin |
|---|---|
| eine Einstellung ändern (URL, Key, Timeout, `managed_by`) | [`config/README.md`](config/README.md) |
| ein Modell, Credential oder einen Key anlegen | [`data/README.md`](data/README.md) |
| verstehen, wie gemergt und priorisiert wird | [`docs/config-loading.md`](docs/config-loading.md) |
| zwischen LiteLLM-Instanzen wechseln | [`docs/server-profile.md`](docs/server-profile.md) |
| alle CLI-Flags nachschlagen | [`docs/cli-argumente.md`](docs/cli-argumente.md) |
| wissen, was ein Lauf genau tut | [`docs/ablauf-sync.md`](docs/ablauf-sync.md) |
| einen Fehler einordnen | [`docs/fehlerbehebung.md`](docs/fehlerbehebung.md) |
| die Validierungen verstehen (Valid1–Valid5) | [`docs/validations.md`](docs/validations.md) |
| mit Geheimnissen richtig umgehen | [`docs/sicherheit.md`](docs/sicherheit.md) |
| die gesamte Dokumentation durchblättern | [`docs/index.md`](docs/index.md) |

---

## Installation

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

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

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

```text
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`](docs/releasing.md) dokumentiert.

---

## Schnellstart

### 1. Voraussetzungen

```bash
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):

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

Anschließend die Platzhalter ersetzen:

```dotenv
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`:

```yaml
settings:
  server: local

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

### 4. Erster Lauf

```bash
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:

```bash
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)

```bash
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`

```bash
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`

```bash
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`

```bash
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`

```bash
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`

```bash
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`

```bash
# 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

| Flag | Wirkung |
|---|---|
| `--force-credentials` | Patcht jedes Credential ohne Feldvergleich (nach Key-Rotation) |
| `--create-credentials` / `--no-create-credentials` | Überschreibt `settings.create_credentials` |
| `--detailed-outputs` / `--no-detailed-outputs` | Ausführliche bzw. knappe Konsolenausgabe |
| `--managed-by <name>` | Überschreibt den Marker für verwaltete Objekte |
| `--timeout <sek>` | HTTP-Timeout je Aufruf |

Vollständige Referenz: [`docs/cli-argumente.md`](docs/cli-argumente.md).

---

## Empfohlener Ablauf

```bash
# 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

| Pfad | Inhalt |
|---|---|
| `logs/sync_<Zeitstempel>.log` | Vollständiges Protokoll eines Laufs inkl. Begründung je Operation |
| `logs/autogenerated/<Zeitstempel>_config.yaml` | Gemergte Konfiguration des Laufs (Geheimnisse maskiert) |
| `logs/autogenerated/<Zeitstempel>_data.yaml` | Gemergte Daten des Laufs |
| `logs/litellm_snapshot.yaml` | Ist-Zustand vor den Änderungen (Key-Werte maskiert) |
| `logs/error_report_<Zeitstempel>.txt` | Bei Abbruch: Validierungsphasen, Plan, bereits Ausgeführtes, Fehler |
| `virtual_keys/vkeys.env` / `vkeys.json` | Die erzeugten Virtual-Keys |

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

---

## Tests

```bash
# 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`](docs/sicherheit.md).
