Skip to content

README_de.md

Latest commit

 

History

History
416 lines (314 loc) · 23.8 KB

README_de.md

File metadata and controls

416 lines (314 loc) · 23.8 KB
Raw

KnowledgeDigest Banner

KnowledgeDigest — Portable Lokale Wissensdatenbank

English | 🌐 Deutsch

Python 3.10+ Lizenz: MIT Attribution: NOTICE SBOM: Level 1 Auditiert Version: 0.4.0 Tests: 163 Bestanden Suche: SQLite FTS5 Datenschutz: Zero-Egress Ausführung: RunAsInvoker Sicherheits-SLA: 48h GUI: PySide6 Web: Stdlib LLM-Ready Geprüft: 2026-09-22 Organisation: file-bricks Dach: open-bricks

Portable, in sich geschlossene Wissensdatenbank — indexiert lokale Dokumente, führt satzkonformes semantisches Chunking durch und ermöglicht blitzschnelle SQLite FTS5-Volltextsuche mit BM25-Relevanzranking. Enthält eine native PySide6 Desktop-GUI und einen abhängigkeitsfreien Web-Viewer.

Note

KI- / LLM-Integration & Maschinenlesbarer Kontext
Automatisierte KI-Agenten, LLM-Assistenten und Code-Analyse-Werkzeuge können llms.txt für Projektarchitektur, Sicherheitsgrenzen, Suchbegriffe und Verifikationseinstiege heranziehen.

🧭 Schnellnavigation

1. Übersicht • 2. Kernfunktionen • 3. Architektur • 4. Lebenszyklus • 5. Ziel-Personas • 6. Vergleichsmatrix • 7. Governance-Invarianten • 8. Begriffsklärung • 9. Desktop-GUI • 10. Web-Viewer • 11. CLI-Werkzeuge • 12. Python-API • 13. Konfiguration & Pfade • 14. Ökosystem & Verwandtes • 15. Installation • 16. Tests & Vertragssicherheit • 17. Level 1 SBOM • 18. Haftungsausschluss & SLA

1. Übersicht

KnowledgeDigest ist eine lokale, offline-fähige Wissensdatenbank und Dokumenten-Suchmaschine in Python. Sie wandelt unstrukturierte Verzeichnisse mit Dokumenten (PDF, Microsoft Word DOCX, HTML, Markdown und TXT) in eine relationale SQLite-Datenbank um, die mit einem FTS5-Volltextindex und BM25-Relevanzranking ausgestattet ist.

Im Gegensatz zu Cloud-Wissenssystemen, bei denen vertrauliche Unterlagen an externe Server übertragen werden, arbeitet KnowledgeDigest zu 100 % lokal auf Ihrer Arbeitsstation. Der gesamte Datenbestand wird in einer einzigen portablen SQLite-Datei (data/knowledge.db) gespeichert. Es werden weder Hintergrunddienste noch externe Datenbankserver oder Docker-Container benötigt.

2. Kernfunktionen

  • Lokale Dokumentenextraktion: Tiefgehende Text- und Metadaten-Extraktion aus PDF (pdfplumber), DOCX (python-docx), HTML (beautifulsoup4), Markdown und reinem Text.
  • Satzkonformes semantisches Chunking: Unterteilt Texte in ~350 Wörter umfassende Abschnitte entlang natürlicher Satzzeichen und Absätze — verhindert sinnentstellende Schnitte mitten im Satz für LLM-Prompts.
  • SQLite FTS5 Volltextsuche: Sofortige BM25-gerankte Volltextsuche mit Trigger-basiertem automatischem Indexabgleich und Snippet-Hervorhebung.
  • Zwei Bedienoberflächen:
    • Native PySide6 Desktop-GUI: 3-Spalten-Layout mit Verzeichnis-Explorer, sortierbarer Dokumententabelle und integrierter Dokumentenvorschau (inkl. nativer PDF-Anzeige via pypdfium2).
    • Stdlib Web-Viewer: Abhängigkeitsfreie Browser-Oberfläche (http://localhost:8787), betrieben rein über das Python-Standardmodul http.server.
  • Optionale asynchrone LLM-Zusammenfassungen: Optionale Batch-Verarbeitung für Chunks mittels Gemini Flash (--flash) oder Anthropic Claude Haiku (--haiku) zur Erzeugung strukturierter Kernaussagen und Tags.
  • Kryptografische Deduplizierung: SHA-256 Hash-Erkennung von Duplikaten mit zerstörungsfreier physischer Quarantäne in einen dynamischen _Papierkorb-Ordner.
  • Permissive Zero-Copyleft-Architektur: Unter der MIT-Lizenz stehend, frei von AGPL/GPL-Viren (Entscheidung E08: pypdfium2 gewählt anstelle von PyMuPDF).
  • Nicht-privilegierte Ausführung (RunAsInvoker): Läuft vollständig im Standard-Benutzerkontext ohne Administratorrechte.

3. Architektur & Systemtopologie

Die Architektur trennt Datenaufnahme, Textverarbeitung, lokale Speicherung und Präsentation in klar entkoppelte Schichten:

flowchart TD
    subgraph Input["Dokumenten-Eingabe"]
        DOCS["Lokale Dateien (PDF, DOCX, HTML, TXT, MD)"]
    end

    subgraph CoreEngine["KnowledgeDigest Kern-Engine"]
        EXT["Text-Extraktion (pdfplumber, docx, html)"]
        CHUNK["Satzkonformes Chunking (~350 Wörter)"]
        DEDUPE["SHA-256 Hash & Deduplizierung"]
        FTS["SQLite FTS5 Volltextindex (BM25)"]
        SUMM["Optionale LLM-Zusammenfassung (Flash / Haiku)"]
    end

    subgraph Storage["Lokaler Speicher"]
        DB[("knowledge.db (SQLite FTS5 + Trigger)")]
    end

    subgraph Interfaces["Schnittstellen-Ebene"]
        GUI["PySide6 Desktop-GUI (3-Spalten-Layout)"]
        WEB["Stdlib Web-Viewer (http://localhost:8787)"]
        CLI["CLI Command Suite (python -m KnowledgeDigest)"]
        API["Python-API (from KnowledgeDigest import KnowledgeDigest)"]
    end

    DOCS --> EXT
    EXT --> CHUNK
    CHUNK --> DEDUPE
    DEDUPE --> DB
    DB --> FTS
    CHUNK -.->|"Opt-in Warteschlange"| SUMM
    SUMM -.->|"Zusammenfassungen & Tags"| DB
    DB --> GUI
    DB --> WEB
    DB --> CLI
    DB --> API
Loading

4. Ingestion & Retrieval Lebenszyklus

sequenceDiagram
    autonumber
    actor User as "Nutzer / KI-Agent"
    participant CLI as "CLI / GUI / Web"
    participant Core as "Digest Core"
    participant Ingest as "Ingestor & Chunker"
    participant DB as "SQLite (FTS5 & Triggers)"
    participant LLM as "Optionale LLM-Zusammenfassung"

    Note over User,DB: Phase 1 - Ingestion & Indexierung
    User->>CLI: "Verzeichnis indexieren (/pfad/zu/docs)"
    CLI->>Core: "scan_directory(pfad)"
    Core->>Ingest: "Text extrahieren & chunken (~350 Wörter)"
    Ingest->>DB: "Metadaten, Chunks & Keywords speichern"
    DB-->>DB: "Auto-Sync des BM25 FTS5-Index via Trigger"
    opt "Optionale Zusammenfassung"
        Core->>LLM: "Chunks in Warteschlange (Gemini Flash / Haiku)"
        LLM-->>DB: "Strukturierte Summaries & Tags ablegen"
    end
    Core-->>CLI: "Indexierung erfolgreich abgeschlossen"

    Note over User,DB: Phase 2 - Schnelles Retrieval
    User->>CLI: "Suchbegriff eingeben ('neuronale Netze')"
    CLI->>DB: "FTS5 MATCH mit BM25-Relevanzranking"
    DB-->>CLI: "Sortierte Treffer mit hervorgehobenen Snippets"
    CLI-->>User: "Trefferliste & Dateivorschau anzeigen"
Loading

5. Ziel-Personas & Suchintention

KnowledgeDigest richtet sich an vier zentrale Zielgruppen:

Persona-ID & Profil Primärer Einsatzzweck & Bedarf Suchphrasen (High-Intent) KnowledgeDigest Lösung
[PERSONA-01] KI-Ingenieure & Lokale LLM-Entwickler RAG-Vorverarbeitung, sauberes Satz-Chunking und lokale Kontextabfragen für autonome Agenten. local RAG document database python, sentence bounded text chunker sqlite, offline LLM context retrieval Satzkonformes Chunking (~350 Wörter), sofortiger FTS5 BM25-Index und optionale Gemini Flash / Haiku Pipelines.
[PERSONA-02] Wissenschaftler & Wissensarbeiter Verwaltung und Recherche in umfangreichen Sammlungen von Fach-PDFs, Aufsätzen und Notizen. offline pdf full text search python, portable knowledge base sqlite, pyside6 document search desktop Integrierte PDF-Vorschau via pypdfium2, Unterstützung gängiger Formate, präzise Suche und Desktop-GUI mit Dark-Theme.
[PERSONA-03] Datenschutzbeauftragte & Compliance-Teams Durchsuchung vertraulicher Verträge und Berichte bei vollständigem Verzicht auf Cloud-Dienste. zero egress document indexing, air gapped full text search desktop, privacy first document database 100 % lokale Ausführung; null Telemetrie; portable SQLite-Datei; unprivilegierter RunAsInvoker-Betrieb.
[PERSONA-04] Python-Entwickler & Automatisierer Einbettung lokaler Dokumentensuche in Skripte, Desktop-Apps oder bestehende Workflows. python fts5 document search library, file-bricks knowledgedigest, lightweight local document search engine Keine externen DB-Server nötig; schlanke Python-API; vollständige CLI; standardmäßiger Web-Viewer.

6. Umfassende Vergleichsmatrix

Architektonischer Vergleich mit etablierten Dokumenten- und Wissensmanagement-Ansätzen:

Kriterium / Invariante KnowledgeDigest Cloud-SaaS (Notion AI, Glean, NotebookLM) Schwere Vektor-DBs (Pinecone, Chroma, Milvus) OS-Desktopsuche (Everything, Spotlight) Ad-hoc Grep / Bash-Skripte
INV-LOCAL-01 Local-First & Zero Egress ✅ 100% Lokale SQLite ❌ Vollständige Cloud-Übertragung ⚠️ Oft Cloud-/Remote-Dienst ✅ Lokale Arbeitsstation ✅ Lokale Arbeitsstation
INV-SQLITE-02 SQLite FTS5 Volltext ✅ ACID FTS5 + BM25 ❌ Proprietärer Cloud-Index ❌ Nur Vektor-Embeddings ⚠️ Dateinamen / Basis-Inhalt ❌ Kein Index / Linearer Scan
INV-CHUNK-03 Satzkonformes Chunking ✅ ~350 Wörter (Satzgrenzen) ⚠️ Intransparente Server-Logik ⚠️ Manuelles Chunking nötig ❌ Keine Chunks (Ganze Datei) ❌ Rohe Zeilentreffer
INV-COPYLEFT-04 Zero-Copyleft MIT ✅ MIT (pypdfium2 / BSD) ❌ Proprietäre geschlossene SaaS ⚠️ Teils AGPL / SSPL Lizenzen ❌ Proprietäre OS-Werkzeuge ⚠️ Nicht lizenziert
INV-RUNAS-05 Unprivilegierter Betrieb ✅ RunAsInvoker (Kein Root) ❌ Multi-Tenant Cloud ⚠️ Benötigt Server / Docker ⚠️ Oft System-Indexdienst ✅ Benutzerkontext
INV-DUAL-06 Zwei Oberflächen (GUI + Web) ✅ PySide6 + Stdlib Web ❌ Nur Webbrowser ❌ Nur CLI / API ⚠️ Nur Betriebssystem-Fenster ❌ Nur Terminal
INV-OPTLLM-07 Optionale LLM-Grenze ✅ Funktioniert 100% Offline ❌ LLM zwingend erforderlich ⚠️ Benötigt Vektor-Modelle ❌ Keine LLM-Funktionen ❌ Keine LLM-Funktionen
INV-DEDUPE-08 Deduplizierung ✅ SHA-256 + _Papierkorb ❌ Nur Cloud-Versionierung ❌ Keine ⚠️ Nur Dateinamenduplikate ❌ Manuelle Skript-Pipeline
INV-DOCS-09 100% Zweisprachige Parität ✅ 18-Punkte-Dual-Anker ⚠️ Teils lückenhafte Übersetzung ❌ Nur Englisch ⚠️ Nach Systemsprache ❌ Keine
INV-SLA-10 48h SLA & § 521 BGB ✅ Garantierte 48h Antwort ⚠️ Standard Cloud-Ticket ⚠️ Nur Community-Foren ❌ Nur OS-Supportkanäle ❌ Keine

7. Governance- & Laufzeit-Invarianten

KnowledgeDigest garantiert die Einhaltung von zehn architektonischen Invarianten:

Invariante Kategorie Prinzip & Technische Umsetzung Verifikation
INV-LOCAL-01 Datenschutz Local-First & Zero Egress: Sämtliche Parsings, Indexierungen und Suchanfragen laufen lokal ab. Null Telemetrie. SECURITY.md, tests/test_core.py
INV-SQLITE-02 Datenbank SQLite FTS5 Volltext-Engine: Robuste Persistenz in data/knowledge.db mit BM25-Ranking und Triggern. KnowledgeDigest/schema.py
INV-CHUNK-03 NLP Satzkonformes semantisches Chunking: Segmentierung in ~350 Wörter ohne Zerschneiden von Sätzen. KnowledgeDigest/chunker.py
INV-COPYLEFT-04 Lizenzierung Zero-Copyleft-Garantie: Freie MIT-Lizenz. pypdfium2 anstelle von PyMuPDF (fitz) gemäß Beschluss E08. tests/test_no_agpl.py
INV-RUNAS-05 Sicherheit Unprivilegierter Modus (RunAsInvoker): Arbeitet ausschließlich mit gewöhnlichen Benutzerrechten. SECURITY.md
INV-DUAL-06 Schnittstelle Zwei Oberflächen: PySide6 Desktop-GUI + Python-Stdlib Web-Viewer (localhost:8787). KnowledgeDigest/gui/, web_viewer.py
INV-OPTLLM-07 Autonomie Optionale LLM-Grenze: Vollständig offline nutzbar; optionale Gemini Flash / Haiku Queues. KnowledgeDigest/summarizer.py
INV-DEDUPE-08 Datenintegrität Kryptografische Deduplizierung: SHA-256 Hashprüfung mit sicherer _Papierkorb-Quarantäne. KnowledgeDigest/digest.py
INV-DOCS-09 Dokumentation 18-Punkte-Parität: Identische Struktur und gegenseitige Ankerverweise zwischen Deutsch und Englisch. tests/test_metadata.py
INV-SLA-10 Governance Haftungsausschluss & 48h-SLA: Schenkungsrecht nach § 521 BGB mit garantierter 48-Stunden-Sicherheitsreaktion. SECURITY.md, README_de.md

8. Begriffsklärung & Abgrenzung

KnowledgeDigest ist eine lokale, portable Wissensdatenbank und FTS5-Volltextsitzung. Es grenzt sich klar ab von:

  • Cloud-Team-Wikis: Wir sind kein Notion, Confluence oder Google Workspace. Daten verlassen niemals Ihre Festplatte.
  • Gehostete Vektordatenbanken: Wir erfordern keine Vektoreinbettungen, kein Cloud-Abo (Pinecone etc.) und keine GPU-Cluster.
  • Invasive OS-Hintergrund-Indexer: Wir indexieren keine Systemverzeichnisse oder Registry-Schlüssel im Hintergrund.
  • Format-Konverter oder DRM-Entferner: Der Fokus liegt rein auf Text- und Metadatenextraktion für Durchsuchbarkeit.

Relevante Suchphrasen:

KnowledgeDigest file-bricks
portable Wissensdatenbank Python
lokale Dokumentensuche FTS5 SQLite
PySide6 Dokumentensuche Desktop App
satzkonformes Text Chunking Python
offline Dokumentensuche Werkzeug
Datenschutz Dokumentenindexierung
sqlite fts5 bm25 volltextsuche

9. Desktop-GUI

KnowledgeDigest verfügt über eine moderne, native PySide6 Desktop-Oberfläche mit dunklem Farbschema und 3-Spalten-Layout:

Spalte Inhalte & Funktionen
Linke Spalte Verzeichnis-Explorer mit Anzeige der indexierten Dokumente und Sofort-Scan-Schaltfläche.
Mittlere Spalte Dokumententabelle mit sortierbaren Spalten (Dateiname, Format, Größe, Chunks, Indexdatum) und Schnellfilter.
Rechte Spalte Dokumentenvorschau mit Unterstützung für Text, Markdown und nativer PDF-Darstellung via pypdfium2.

Desktop-GUI starten:

python -m KnowledgeDigest --gui

10. Web-Viewer

KnowledgeDigest bietet eine leichtgewichtige Browser-Oberfläche, die ausschließlich auf der Python-Standardbibliothek basiert (http.server):

  • Dashboard: Statistiken über Dokumente, Chunks und Indexierungsfortschritt.
  • Dokumentenübersicht: Übersicht aller Dateien mit Paginierung und Verzeichnisfilter.
  • FTS5-Volltextsuche: Schnelle Suche mit BM25-Relevanz und hervorgehobenen Textabschnitten.
  • Zusammenfassungen: Katalog der optionalen LLM-Zusammenfassungen und Fachbegriffe.
  • Gehärtete Sicherheit: POST-Zwang für schreibende Endpunkte, Origin-/Referer-Prüfung und Host-Header-Validierung.

Web-Viewer starten (http://localhost:8787):

python -m KnowledgeDigest --web

11. Multi-Interface Zugriff & CLI

KnowledgeDigest bringt ein vollständiges Kommandozeilen-Interface mit:

# Status der Datenbank, Dokumentenzahl und Chunks anzeigen
python -m KnowledgeDigest status

# Neues Verzeichnis zum Index hinzufügen
python -m KnowledgeDigest add /pfad/zu/dokumenten

# Alle registrierten Verzeichnisse scannen und neu indexieren
python -m KnowledgeDigest scan

# Volltextsuche über alle Dokumente durchführen
python -m KnowledgeDigest search "maschinelles lernen" --limit 10

# Nach kryptografischen Duplikaten suchen und in Quarantäne verschieben
python -m KnowledgeDigest deduplicate --quarantine

# Optionale LLM-Zusammenfassung für offene Chunks starten
python -m KnowledgeDigest summarize --flash

12. Python-API

KnowledgeDigest kann als Bibliothek direkt in Python-Projekte eingebunden werden:

from KnowledgeDigest import KnowledgeDigest
from KnowledgeDigest.config import get_config

# Initialisierung mit Konfiguration
kd = KnowledgeDigest(config=get_config())

# Verzeichnis hinzufügen und einlesen
kd.add_directory("/pfad/zu/docs")
kd.scan_directory("/pfad/zu/docs", recursive=True)

# Volltextsuche via FTS5 und BM25
results = kd.search_all("transformer architektur", limit=5)
for hit in results:
    print(f"[{hit['filename']}] Relevanz: {hit.get('rank', 'N/A')}")
    print(f"Auszug: {hit['snippet']}\n")

# Systemstatus abfragen
status = kd.get_status()
print(f"Dokumente: {status['documents']['total_documents']}")
print(f"Chunks: {status['documents']['total_chunks']}")

13. Konfiguration & Pfade

Die Konfiguration erfolgt über die JSON-Datei knowledgedigest.json. Suchreihenfolge:

  1. CLI-Parameter --config <pfad>
  2. Aktuelles Arbeitsverzeichnis (./knowledgedigest.json)
  3. Neben der aktiven Datenbankdatei
  4. Benutzerbezogener Konfigurationsordner:
    • Windows: %APPDATA%\KnowledgeDigest\knowledgedigest.json
    • Linux / macOS: ~/.config/knowledgedigest/knowledgedigest.json
  5. Eingebaute Standardwerte

Wichtige Einstellungen:

Parameter Typ Standardwert Beschreibung
db_path str "data/knowledge.db" Speicherort der SQLite-Datenbank.
indexed_directories list[str] [] Liste der überwachten Ordner.
chunk_size int 350 Zielgröße in Wörtern pro Textsegment.
web_port int 8787 Port für den Web-Viewer.
bach_enabled bool false Optionale Anbindung an das BACH-Framework.

14. Optionale Integrationen & Ökosystem

  • Ökosystem: KnowledgeDigest wird von der Organisation file-bricks betreut und ist Teil des übergeordneten open-bricks Open-Source-Verbunds.
  • Schwesterprojekt ProFiler: Für erweiterte Dateiverwaltung, PDF-Schwärzung, OCR und Zwischenablageschutz siehe ProFiler (AGPL-3.0).
  • Test-Korpus WikiStub-Seed: 630 mehrsprachige Kurzeinträge aus 12 Fachbereichen als strukturierter Test-Datensatz für Ingestion-Pipelines.
  • Optionale BACH-Brücke: Bei aktiviertem bach_enabled: true können Skills und Wissensartikel aus dem BACH Agenten-Framework mitindexiert werden.

15. Setup & Installation

Option A: Editierbarer lokaler Klon (Empfohlen)

git clone https://github.com/file-bricks/knowledgedigest.git
cd knowledgedigest
python -m pip install --upgrade pip
python -m pip install -e ".[all]"

Option B: Direkte Installation via Git

pip install "knowledgedigest[gui] @ git+https://github.com/file-bricks/knowledgedigest.git"

16. Tests & Vertragssicherheit

KnowledgeDigest enthält eine umfassende Test-Suite für Chunking-Integrität, SQLite FTS5-Persistenz, Transit-Synchronisation, Zero-Copyleft-Schutz und PEP-621-Vertragstests:

# Komplette Test-Suite ausführen
pytest

# Detaillierte Testausgabe
pytest -v

# Lizenz- und Copyleft-Vertragstest ausführen
pytest tests/test_no_agpl.py

# Metadaten- und Dokumentationsverträge prüfen
pytest tests/test_metadata.py

17. Level 1 SBOM & Drittanbieter-Lizenzen

Alle direkten Laufzeit-Abhängigkeiten sind im Level 1 Software Bill of Materials (THIRD_PARTY_LICENSES.md) erfasst.

  • 100 % Freie Open-Source-Lizenzen: MIT, Apache-2.0, BSD-3-Clause, PSFL-2.0, LGPL-3.0 (dynamisch eingebunden).
  • Keine Copyleft-Kontamination: Gemäß Entscheidung E08 (2026-08-18) wird für PDF-Vorschauen pypdfium2 eingesetzt, um AGPL-Risiken auszuschließen.
  • Kanonische Urheber-Angaben: Siehe NOTICE für Autoren und Copyright.

18. Haftungsausschluss, § 521 BGB & Sicherheits-SLA

⚠️ Kein Rechts-, Steuer- oder Anlage-Rat

KnowledgeDigest ist ein technisches Werkzeug zur Dokumentenindexierung und Volltextsuche. Es stellt keine Rechts-, Steuer- oder Finanzberatung dar. Bei entsprechenden Fachfragen ziehen Sie bitte qualifizierte Experten heran.

⚖️ Gesetzlicher Haftungsausschluss (§ 521 BGB)

Dieses Projekt ist eine unentgeltliche Open-Source-Schenkung im Sinne der §§ 516 ff. BGB. Die Haftung des Urhebers ist gemäß § 521 BGB (Gefälligkeitsrecht) auf Vorsatz und grobe Fahrlässigkeit beschränkt. Ergänzend gelten die Haftungsausschlüsse der MIT-Lizenz.

🛡️ Sicherheits-Reaktionszeiten (SLA)

Sicherheitsrelevante Schwachstellen melden Sie bitte vertraulich über GitHub Private Vulnerability Reporting.

  • Erste Rückmeldung: Innerhalb von 48 Stunden.
  • Evaluierung & Einstufung: Innerhalb von 5 Werktagen.
  • Weitere Details in SECURITY.md.

Urheber & Copyright

Copyright (c) 2026 Lukas Geiger (github.com/lukisch).
Teil der Organisation file-bricks und des open-bricks Ökosystems.