diff --git a/CHANGELOG.md b/CHANGELOG.md index 1a4d95a..6dac63f 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -2,6 +2,12 @@ ## [Unreleased] +- **Discoverability, Visual Architecture & Desktop/Web UI Workflows (Pfad B, 2026-11-04)**: + - **Verified Badges Synchronization**: Added live CI workflow status badge and verified test count badge (219 passed) to both English `README.md` and German `README_de.md`. + - **Desktop GUI 3-Panel Wireframe & Architecture**: Added comprehensive ASCII layout architecture for the 3-panel PySide6 interface (Directories, Documents, Preview) across both READMEs. + - **Web Viewer Endpoint Topology & Sequence Diagram**: Documented the stdlib HTTP server routes (`/`, `/search`, `/browse`, `/document/`, `/api/status`) and integrated a sequence diagram demonstrating query sanitization, BM25 matching, and HTML generation. + - **Contract Tests & Parity**: Ensured strict compliance with 18-point dual-anchor navigation parity (`` to ``), banner asset guardrail (`test_banner_and_asset_guardrail`), Mermaid syntax verification (`lint_mermaid.py`), version freeze at 0.4.0 (T-20260920-167562623), and 0 whitespace errors. + - **Test Environment & Import Fallback Hygiene (Pfad A, 2026-11-01)**: - **Pytest Conftest Setup**: Added ests/conftest.py ensuring repo root is inserted into sys.path and providing fallback KnowledgeDigest module alias during direct test runs without prior pip install -e .. - **Graceful Import Fallback in est_transit.py**: Added ry...except ImportError fallback for KnowledgeDigest.schema and KnowledgeDigest.transit imports, ensuring standalone execution parity with est_core.py and est_bach_import.py. diff --git a/README.md b/README.md index 71f0f70..c3dcaa8 100644 --- a/README.md +++ b/README.md @@ -8,6 +8,8 @@ [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE) [![Attribution: NOTICE](https://img.shields.io/badge/Attribution-NOTICE-blue.svg)](NOTICE) [![Version: 0.4.0](https://img.shields.io/badge/Version-0.4.0-informational.svg)](CHANGELOG.md) +[![CI](https://github.com/file-bricks/knowledgedigest/actions/workflows/tests.yml/badge.svg)](https://github.com/file-bricks/knowledgedigest/actions/workflows/tests.yml) +[![Tests: 219 passed](https://img.shields.io/badge/Tests-219%20passed-success.svg)](#16-testing-contract-verification) [![Search: SQLite FTS5](https://img.shields.io/badge/Search-SQLite%20FTS5%20BM25-green.svg)](#3-architecture) [![GUI: PySide6](https://img.shields.io/badge/GUI-PySide6-41CD52.svg?logo=qt&logoColor=white)](#9-desktop-gui) [![Web: Stdlib](https://img.shields.io/badge/Web-Stdlib%20Zero--Dep-blue.svg)](#10-web-viewer) @@ -168,16 +170,47 @@ Optional provider and synchronization workflows are not promised to be offline. - **Language**: The desktop GUI has no language selector; its visible strings are German. The English and German README share 18 navigation anchor IDs, not full line-by-line translation parity. -## 8. Scope +## 8. Scope & Search Intent KnowledgeDigest indexes local documents and searches them with FTS5. This path does not require a hosted database or LLM provider. Optional summarization and synchronization are separate workflows and may send data to configured external systems. Check the configured provider, endpoint, selected files, and synchronization targets before using them. -Search phrases: portable document search, SQLite FTS5, local document index, Python knowledge database, optional LLM summarization. +### High-Intent Search Queries & Categorization +- **Local-First Search**: portable document search, SQLite FTS5 full-text engine, BM25 snippet ranking, offline personal knowledge base. +- **Desktop & Ingestion**: PySide6 desktop document indexer, sentence-bounded text chunking, local multi-format document parser (PDF, DOCX, Markdown, HTML, TXT). +- **Privacy & Boundaries**: zero-egress document indexing, local SQLite database, optional LLM summarization (Anthropic Claude, Google GenAI Flash, Ollama). ## 9. Desktop GUI -The PySide6 desktop application has a directory panel, document table, and preview. Its current UI strings are German-only and it has no language selector. The installed package includes the application icon; a package-artifact smoke check verifies that it is loadable. +The PySide6 desktop application provides a responsive 3-panel workspace designed for high-density document management, fast browsing, and immediate snippet inspection. Its current UI strings are German-only and it has no language selector. The installed package includes the application icon; a package-artifact smoke check verifies that it is loadable. + +### 3-Panel Splitter Architecture + +```text ++-----------------------------------------------------------------------------------+ +| KnowledgeDigest — Portable Local Knowledge Database [ - | + | x ] | ++-----------------------------------------------------------------------------------+ +| [📂 Ingest Directory] [🔄 Scan / Re-index] [⚙️ Settings] [🌐 Launch Web Viewer] | ++-----------------------------------------------------------------------------------+ +| 🔍 [ FTS5 Full-Text Search (BM25) ........................................ ] [Go]| ++-----------------------+-----------------------------+-----------------------------+ +| 📁 Directories | 📄 Documents (Indexed) | 📑 Document & Chunk Preview | +| | | | +| • /docs/papers/ (42) | • attention_is_all_you_need | Filename: attention.pdf | +| • /docs/manuals/ (18) | • bert_pretraining.pdf | Chunks: 14 | Words: 4,820 | +| • /research/notes/ (9)| • sqlite_fts5_guide.md | SHA-256: 4a8b...12ef | +| | • architecture_v2.docx | | +| | | Snippet: "...transformer | +| | | architecture with multi- | +| | | head self-attention..." | ++-----------------------+-----------------------------+-----------------------------+ +| Status: 69 documents, 312 chunks indexed | DB: knowledge.db | Ready | ++-----------------------------------------------------------------------------------+ +``` + +- **Directory Panel (Left)**: Tree view showing all monitored filesystem directories and corpus chunk counts. +- **Document List (Center)**: Sortable data table displaying filenames, document types, word counts, and indexing timestamps. +- **Preview Panel (Right)**: Detailed document inspection, keyword tag cloud, and individual chunk segments. Launch: `python -m KnowledgeDigest --gui` @@ -188,6 +221,35 @@ The GUI requires the optional gui dependencies and a desktop display. The standard-library HTTP viewer exposes local index summaries, document browsing, and FTS5 search. Current source binds to 127.0.0.1; state-changing routes require POST and validate request headers. It uses local HTTP without TLS and is not an authenticated remote service. +### Endpoint Topology & Route Map + +| Endpoint | Method | Scope & Behavior | +|---|---|---| +| `/` | `GET` | Corpus summary dashboard, indexing statistics, and quick-search entrypoint. | +| `/search?q=...` | `GET` | FTS5 full-text query with BM25 ranking and highlighted snippet previews. | +| `/browse` | `GET` | Paginated catalog view with document type filtering (PDF, DOCX, MD, etc.). | +| `/document/` | `GET` | In-depth document inspection: metadata, extracted chunks, keywords, summaries. | +| `/api/status` | `GET` | Machine-readable JSON endpoint for corpus metrics and trigger health. | + +### Query & Rendering Lifecycle + +```mermaid +sequenceDiagram + autonumber + actor Browser as "Web Browser (Localhost)" + participant Server as "Stdlib HTTP Server (:8787)" + participant FTS as "SQLite FTS5 Core" + participant DB as "knowledge.db" + + Browser->>Server: "GET /search?q=transformer" + Server->>Server: "Sanitize and escape FTS5 query token" + Server->>FTS: "MATCH 'transformer' ORDER BY bm25(document_fts)" + FTS->>DB: "Fetch matching chunks and highlight snippets" + DB-->>Server: "Ranked hit rows (chunks, doc_id, rank score)" + Server->>Server: "Render self-contained HTML with CSS dark theme" + Server-->>Browser: "HTTP 200 OK (Interactive search results)" +``` + Launch: `python -m KnowledgeDigest --web` Use --db to provide a database path. Select a writable path and do not expose the viewer through a reverse proxy without a separate security review. diff --git a/README_de.md b/README_de.md index e88f67b..b504e23 100644 --- a/README_de.md +++ b/README_de.md @@ -8,6 +8,8 @@ [![Lizenz: MIT](https://img.shields.io/badge/Lizenz-MIT-yellow.svg)](LICENSE) [![Attribution: NOTICE](https://img.shields.io/badge/Attribution-NOTICE-blue.svg)](NOTICE) [![Version: 0.4.0](https://img.shields.io/badge/Version-0.4.0-informational.svg)](CHANGELOG.md) +[![CI: Tests](https://github.com/file-bricks/knowledgedigest/actions/workflows/tests.yml/badge.svg)](https://github.com/file-bricks/knowledgedigest/actions/workflows/tests.yml) +[![Tests: 219 bestanden](https://img.shields.io/badge/Tests-219%20bestanden-success.svg)](#16-testing-contract-verification) [![Suche: SQLite FTS5](https://img.shields.io/badge/Suche-SQLite%20FTS5%20BM25-green.svg)](#3-architecture) [![GUI: PySide6](https://img.shields.io/badge/GUI-PySide6-41CD52.svg?logo=qt&logoColor=white)](#9-desktop-gui) [![Web: Stdlib](https://img.shields.io/badge/Web-Stdlib%20Zero--Dep-blue.svg)](#10-web-viewer) @@ -168,16 +170,47 @@ Für optionale Anbieter- oder Synchronisierungsabläufe wird kein Offline-Betrie - **Sprache**: Die Desktop-GUI hat keinen Sprachumschalter; ihre Oberflächentexte sind deutsch. Die englische und deutsche README teilen 18 Anker-IDs, keine vollständige zeilenweise Übersetzungsparität. -## 8. Umfang +## 8. Umfang & Suchabsichten KnowledgeDigest indexiert lokale Dokumente und durchsucht sie mit FTS5. Dieser Pfad benötigt weder eine gehostete Datenbank noch einen LLM-Anbieter. Optionale Zusammenfassungen und Synchronisierung sind getrennte Abläufe und können Daten an konfigurierte externe Systeme senden. Prüfen Sie vor deren Nutzung Anbieter, Endpunkt, ausgewählte Dateien und Synchronisierungsziele. -Suchbegriffe: lokale Dokumentensuche, SQLite FTS5, Python-Wissensdatenbank, Dokumentenindex, optionale LLM-Zusammenfassung. +### Suchbegriffe & Themenkategorisierung +- **Lokale Dokumentensuche**: portable Volltextsuche, SQLite FTS5 Engine, BM25 Snippet-Ranking, Offline-Wissensdatenbank. +- **Desktop & Dokumentenaufnahme**: PySide6 Desktop-Dokumentenindexer, satzbezogenes Chunking, universelle Formatextraktion (PDF, DOCX, Markdown, HTML, TXT). +- **Datenschutz & Grenzen**: Zero-Egress Dokumentenindexierung, rein lokale SQLite-Datei, optionale LLM-Zusammenfassungen (Anthropic Claude, Google GenAI Flash, Ollama). ## 9. Desktop-GUI -Die PySide6-Desktopanwendung hat eine Verzeichnisleiste, eine Dokumententabelle und eine Vorschau. Ihre aktuellen Oberflächentexte sind deutsch; einen Sprachumschalter gibt es nicht. Das installierte Paket enthält das Anwendungssymbol; ein Paket-Smoke-Check prüft, ob es geladen werden kann. +Die PySide6-Desktopanwendung bietet einen übersichtlichen 3-Spalten-Arbeitsbereich für effiziente Dokumentenverwaltung, schnelles Browsen und unmittelbare Textvorschau. Ihre aktuellen Oberflächentexte sind deutsch; einen Sprachumschalter gibt es nicht. Das installierte Paket enthält das Anwendungssymbol; ein Paket-Smoke-Check prüft, ob es geladen werden kann. + +### 3-Spalten-Splitter-Architektur + +```text ++-----------------------------------------------------------------------------------+ +| KnowledgeDigest — Portable Lokale Wissensdatenbank [ - | + | x ] | ++-----------------------------------------------------------------------------------+ +| [📂 Verzeichnis laden] [🔄 Aktualisieren] [⚙️ Einstellungen] [🌐 Web-Viewer] | ++-----------------------------------------------------------------------------------+ +| 🔍 [ Volltextsuche (SQLite FTS5 + BM25 Ranking) ........................... ] [Go]| ++-----------------------+-----------------------------+-----------------------------+ +| 📁 Verzeichnisse | 📄 Dokumente (Indexiert) | 📑 Vorschau & Chunk-Details | +| | | | +| • /docs/papers/ (42) | • attention_is_all_you_need | Dateiname: attention.pdf | +| • /docs/manuals/ (18) | • bert_pretraining.pdf | Chunks: 14 | Wörter: 4.820 | +| • /research/notizen(9)| • sqlite_fts5_guide.md | SHA-256: 4a8b...12ef | +| | • architektur_v2.docx | | +| | | Textauszug: "...Transformer-| +| | | Architektur mit Multi-Head- | +| | | Self-Attention..." | ++-----------------------+-----------------------------+-----------------------------+ +| Status: 69 Dokumente, 312 Chunks indexiert | DB: knowledge.db | Bereit | ++-----------------------------------------------------------------------------------+ +``` + +- **Verzeichnisleiste (Links)**: Baumansicht aller überwachten Dateisystem-Pfade mit Chunk-Anzahl. +- **Dokumententabelle (Mitte)**: Sortierbare Tabellenansicht nach Dateiname, Typ, Wortanzahl und Indexierungszeitpunkt. +- **Vorschaubereich (Rechts)**: Vollständige Textanzeige, extrahierte Schlüsselwörter und einzelne Chunks. Start: `python -m KnowledgeDigest --gui` @@ -188,6 +221,35 @@ Die GUI benötigt die optionale Gruppe gui und eine grafische Anzeige. Der HTTP-Viewer aus der Standardbibliothek zeigt lokale Indexdaten, Dokumente und FTS5-Suchergebnisse. Der aktuelle Quelltext bindet an 127.0.0.1; schreibende Routen verlangen POST und prüfen Request-Header. Er verwendet lokales HTTP ohne TLS und ist kein authentifizierter Remote-Dienst. +### Endpunkt-Übersicht & Routenplan + +| Endpunkt | Methode | Bereich & Verhalten | +|---|---|---| +| `/` | `GET` | Dashboard mit Korpus-Statistiken, Index-Zählern und Schnellsuche. | +| `/search?q=...` | `GET` | FTS5-Volltextsuche mit BM25-Ranking und hervorgehobenen Textausschnitten. | +| `/browse` | `GET` | Paginierte Katalogansicht mit Dateityp-Filtern (PDF, DOCX, MD usw.). | +| `/document/` | `GET` | Dokumenten-Inspektion: Metadaten, Chunks, Schlüsselwörter und Zusammenfassungen. | +| `/api/status` | `GET` | JSON-Endpunkt für Korpus-Metriken und Trigger-Status für Skripte. | + +### Abfrage- und Render-Ablauf + +```mermaid +sequenceDiagram + autonumber + actor Browser as "Webbrowser (Localhost)" + participant Server as "Stdlib HTTP-Server (:8787)" + participant FTS as "SQLite FTS5 Core" + participant DB as "knowledge.db" + + Browser->>Server: "GET /search?q=transformer" + Server->>Server: "FTS5-Suchbegriff bereinigen und quotieren" + Server->>FTS: "MATCH 'transformer' ORDER BY bm25(document_fts)" + FTS->>DB: "Passende Chunks abfragen und Textauszuege hervorheben" + DB-->>Server: "Rangierte Trefferzeilen (Chunks, doc_id, BM25-Score)" + Server->>Server: "Autarkes HTML mit integriertem Dark-Theme rendern" + Server-->>Browser: "HTTP 200 OK (Interaktive Suchergebnisse)" +``` + Start: `python -m KnowledgeDigest --web` Mit --db lässt sich ein Datenbankpfad angeben. Verwenden Sie einen beschreibbaren Speicherort und stellen Sie den Viewer nicht ohne zusätzliche Sicherheitsprüfung über einen Reverse-Proxy bereit.