Skip to content

Usage Guide

This guide provides examples for both the CLI scripts and the Web UI.

Initial Setup

Before using the tool, you must create an index of your backup drive:

python scripts/build_index.py --path /media/external_backup

This command will: 1. Scan the drive and create data/backup_index.md. 2. Generate embeddings and store them in the vector database.

Web Interface

Start the Gradio app:

python -m semantic_backup_explorer.cli.ui.gradio_app

Navigate to http://localhost:7860 in your browser.

  • One-Click Sync:
    1. Klicke auf "Ordner wählen" und suche den lokalen Ordner aus, den du abgleichen möchtest.
    2. Klicke auf "Vergleichen". Die App vergleicht deinen lokalen Ordner mit den Daten aus der backup_index.md.
    3. Die App sucht automatisch das passende Gegenstück auf deinem Backup-Laufwerk (basierend auf dem Namen oder via KI-Suche falls installiert).
    4. In der Liste "Nur Lokal" siehst du alle Dateien, die noch nicht im Backup sind oder lokal neuer sind.
    5. Klicke auf Synchronisieren, um die fehlenden Dateien direkt auf die externe Festplatte zu kopieren.

🛡️ Sicherheit & Mehrere Laufwerke

Die App nutzt den Volume Namen (Label) deiner Festplatte zur Identifizierung. Dies ist besonders wichtig, wenn du mehrere externe Platten hast, die sich unter demselben Laufwerksbuchstaben (z.B. J:\) anmelden.

  • Verifikation vor Sync: Vor jeder Synchronisation prüft die App, ob das aktuell angeschlossene Laufwerk denselben Namen hat wie das Laufwerk, für das der Index erstellt wurde. Bei einem Konflikt bricht die App ab, um Fehlkopien zu vermeiden.
  • Index-Aktualität: Der Abgleich erfolgt blitzschnell gegen den gespeicherten Index. Wenn der Index älter als 7 Tage ist, gibt die App eine Warnung aus. Aktualisiere den Index im Tab Index Viewer, wenn du Dateien manuell auf der Festplatte geändert hast.
  • Index Viewer: Verwalte hier deine Backup-Indizes. Du kannst ein Laufwerk scannen, um eine kompakte Liste aller Dateien zu erstellen.
  • Semantic Search (Optional): Nutze natürliche Sprache. Frage z.B. "Wo liegen meine alten Steuererklärungen?". Die KI durchsucht den Index und nennt dir die wahrscheinlichsten Ordner.

Schritt-für-Schritt für Einsteiger

1. Vorbereitung

Schließe dein Backup-Laufwerk (z.B. eine USB-Festplatte) an deinen Computer an.

2. Den Index erstellen (Einmalig pro Laufwerk)

Gehe zum Tab Index Viewer. Wähle über den Button "Ordner wählen" dein Backup-Laufwerk aus (z.B. E:\). Klicke auf Index erstellen. Die App scannt nun alle Dateien. Das kann je nach Größe der Festplatte ein paar Minuten dauern.

3. Sichern mit One-Click Sync

Gehe zum Tab One-Click Sync. Wähle deinen lokalen Ordner (den du sichern willst) aus und klicke auf Vergleichen. Die App zeigt dir, was gesichert werden muss. Klicke dann auf Synchronisieren.

4. KI-Suche aktivieren (Optional)

Falls du die semantischen Features installiert hast, gehe zum Tab Semantic Search. Klicke auf den Button Embeddings erstellen. Dies muss nur einmal nach dem Erstellen eines neuen Index gemacht werden, damit die KI die Ordnerstruktur "verstehen" kann.

Automated Sync

To sync all folders defined in your backup_config.md:

python scripts/auto_sync.py --backup_path /media/external_backup

This script will: 1. Re-scan the backup drive to ensure the index is up-to-date. 2. Iterate through each source folder. 3. Compare and copy missing files. 4. Print a summary protocol at the end.

Troubleshooting

  • No matching folder found: Ensure the local folder name is reasonably similar to the folder name in the backup.
  • RAG Errors: Check your GROQ_API_KEY in the .env file.
  • Stale Embeddings: If you manually edited files on the backup, rebuild the index via the UI or build_index.py.