{"id":45990806,"url":"https://github.com/feberdin/paperless-kiplus","last_synced_at":"2026-04-26T16:01:00.649Z","repository":{"id":341249493,"uuid":"1169356452","full_name":"Feberdin/Paperless-KIplus","owner":"Feberdin","description":"KI-gestützte Dokumentklassifizierung für Paperless-ngx mit YAML-Regeln, Debug-Reports und Home-Assistant HACS-Integration","archived":false,"fork":false,"pushed_at":"2026-04-26T13:34:37.000Z","size":951,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-04-26T14:04:12.456Z","etag":null,"topics":["automation","hacs","home-assistant","paperless","paperless-ngx","python"],"latest_commit_sha":null,"homepage":null,"language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Feberdin.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-02-28T15:08:43.000Z","updated_at":"2026-04-26T13:34:40.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/Feberdin/Paperless-KIplus","commit_stats":null,"previous_names":["feberdin/paperless-kiplus"],"tags_count":54,"template":false,"template_full_name":null,"purl":"pkg:github/Feberdin/Paperless-KIplus","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Feberdin%2FPaperless-KIplus","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Feberdin%2FPaperless-KIplus/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Feberdin%2FPaperless-KIplus/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Feberdin%2FPaperless-KIplus/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Feberdin","download_url":"https://codeload.github.com/Feberdin/Paperless-KIplus/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Feberdin%2FPaperless-KIplus/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":32303177,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-26T09:34:17.070Z","status":"ssl_error","status_checked_at":"2026-04-26T09:34:00.993Z","response_time":129,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["automation","hacs","home-assistant","paperless","paperless-ngx","python"],"created_at":"2026-02-28T20:17:49.456Z","updated_at":"2026-04-26T16:01:00.609Z","avatar_url":"https://github.com/Feberdin.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Paperless KIplus Home Assistant Integration\n\nDie Integration verbindet Home Assistant mit deinem Paperless-ngx-Workflow und klassifiziert Dokumente per KI automatisiert.\n\n## Was macht die Integration?\n\nDie Integration startet den KI-Sorter direkt aus Home Assistant, schreibt Ergebnisse zurück nach Paperless-ngx und stellt Laufstatus, Kosten und Logs als Entitäten/Buttons bereit.\n\nZusätzlich kann die Integration optional ein steuerorientiertes `Tax Enrichment`\npro Dokument erzeugen. Diese Erweiterung richtet Dokumente auf private deutsche\nEinkommensteuerfälle aus, bewertet Nachweisqualität vorsichtig und erzeugt\narbeitbare JSON-/CSV-Exporte für die manuelle Übernahme nach WISO Steuer.\nWenn du diese Funktion nicht möchtest, bleibt sie mit `enable_tax_enrichment: false`\nkomplett ausgeschaltet.\n\n### Bilder\n\n#### Geräteansicht in Home Assistant\n![Home Assistant Geräteansicht](./docs/images/ha-geraeteansicht.png)\n\n#### Dokument mit KI-Notiz in Paperless-ngx\n![Paperless Dokumentansicht mit KI-Notiz](./docs/images/paperless-ki-notiz.png)\n\n#### Optionen in Home Assistant (Teil 1)\n![Home Assistant Optionen Teil 1](./docs/images/ha-optionen-teil1.png)\n\n#### Optionen in Home Assistant (Teil 2)\n![Home Assistant Optionen Teil 2](./docs/images/ha-optionen-teil2.png)\n\n## Wie installiere ich die Integration?\n\n1. HACS öffnen -\u003e `Integrationen` -\u003e `Custom repositories`.\n2. Repository hinzufügen:\n   - URL: `https://github.com/Feberdin/Paperless-KIplus`\n   - Kategorie: `Integration`\n3. `Paperless KIplus Runner` installieren.\n4. Home Assistant neu starten.\n5. Unter `Einstellungen -\u003e Geräte \u0026 Dienste` die Integration hinzufügen.\n6. In den Optionen deine YAML-Konfiguration vollständig im YAML-Feld pflegen.\n   Alternative mit ChatGPT:\n   - Nutze den folgenden Prompt, um dir eine vollständige YAML erstellen zu lassen.\n   - Ergebnis 1:1 in das YAML-Feld der Integration kopieren.\n\n```text\nErstelle mir eine vollständige YAML-Konfiguration für die Home-Assistant Integration\n\"Paperless KIplus Runner\" (Paperless-ngx KI-Sorter).\n\nZiel:\n- Dokumente in Paperless-ngx per KI klassifizieren (Dokumenttyp, Korrespondent,\n  Speicherpfad, Tags, Datum, Notiz).\n- Sicherer Betrieb in Home Assistant mit Fokus auf stabile Automationen.\n\nWichtige Anforderungen:\n1) Gib nur gültiges YAML aus (ohne Markdown, ohne Erklärtext).\n2) Gib alle unten genannten Felder vollständig aus, auch wenn du Defaultwerte nutzt.\n3) Setze process_only_tag auf \"#NEU\".\n4) Setze dry_run auf false.\n5) Setze reprocess_ki_tagged_documents auf false.\n6) Konfiguriere bereits klassifizierte Dokumente so, dass sie zuverlässig übersprungen werden.\n7) Aktiviere Quarantäne- und Duplicate-Prechecks.\n8) Aktiviere parallele KI-Verarbeitung moderat (3 bis 5 Jobs).\n9) Nutze sinnvolle produktive Defaultwerte.\n\nPflicht-Platzhalter:\n- paperless_url: \u003cPAPERLESS_URL\u003e\n- paperless_token: \u003cPAPERLESS_TOKEN\u003e\n- ai_api_key: \u003cAI_API_KEY\u003e\n- ai_model: \u003cAI_MODEL\u003e\n- ai_base_url: \u003cAI_BASE_URL\u003e\n\nDie YAML muss diese Felder enthalten:\n- paperless_url\n- paperless_token\n- ai_api_key\n- ai_model\n- ai_base_url\n- max_documents\n- dry_run\n- create_missing_entities\n- confidence_threshold\n- request_timeout_seconds\n- log_level\n- enable_token_precheck\n- min_remaining_tokens\n- custom_prompt_instructions\n- basis_config\n- process_only_tag\n- include_existing_entities_in_prompt\n- enable_ai_notes\n- ai_notes_max_chars\n- enable_ai_note_summary\n- ai_note_summary_max_chars\n- enable_custom_field_enrichment\n- create_missing_custom_fields\n- enable_secondbrain_custom_fields\n- secondbrain_custom_fields_overwrite_existing\n- secondbrain_custom_fields_attach_empty_when_unknown\n- secondbrain_custom_fields_confidence_threshold\n- secondbrain_custom_fields_log_missing_fields\n- metrics_file\n- input_cost_per_1k_tokens_eur\n- output_cost_per_1k_tokens_eur\n- quarantine_failed_documents\n- failed_document_cooldown_hours\n- failed_documents_file\n- failed_tags_only_cooldown_hours\n- failed_patch_cache_file\n- enable_tag_bypass_on_tags_500\n- tag_bypass_file\n- already_classified_skip\n- already_classified_require_ki_tag\n- precheck_min_content_chars\n- precheck_min_word_count\n- precheck_min_alnum_ratio\n- precheck_blocked_filename_patterns\n- precheck_image_only_gate\n- precheck_duplicate_hash_gate\n- precheck_duplicate_apply_metadata\n- reprocess_ki_tagged_documents\n- enable_parallel_ai\n- max_parallel_ai_jobs\n\nDie `basis_config` muss mindestens diese Struktur enthalten (Feldnamen exakt so verwenden):\n\nbasis_config:\n  people:\n    owner:\n      full_name: \"Max Mustermann\"\n      aliases: []\n      address:\n        street: \"Musterstraße 1\"\n        postal_code: \"12345\"\n        city: \"Musterstadt\"\n      contact:\n        mobile: \"0123456789\"\n      tax:\n        tax_number: \"\"\n    household:\n      children: []\n      relatives: []\n    contacts: []\n  organizations:\n    employer_current:\n      name: \"\"\n      preferred_storage_path: \"\"\n    employer_former:\n      name: \"\"\n      locations: []\n      preferred_storage_path: \"\"\n      only_if_clear_business_context: true\n    clubs: []\n  identifiers:\n    meters: []\n  classification_rules:\n    document_type:\n      invoice_addressed_to_owner: \"Rechnung\"\n      legal_documents_force_type:\n        type: \"Rechtsanwalt\"\n        trigger_terms: [\"Rechtsanwalt\", \"Gericht\", \"Klage\", \"Beschluss\", \"Einspruch\", \"Aktenzeichen\"]\n    correspondent:\n      normalize:\n        - if_contains_any: [\"Hotel\", \"Pension\", \"Unterkunft\", \"Übernachtung\"]\n          set_to: \"Hotel\"\n    storage_path:\n      mappings: []\n      default: \"Privat\"\n    tags:\n      add_year_tag_for_invoices: true\n      add_customer_number_tag_for_contracts: true\n      legal_case_tag_prefers_case_reference: true\n      keep_sparse: true\n    date:\n      prefer_document_date_over_upload_date: true\n  guardrails:\n    forbidden_path_assignments: []\n\nRahmendaten:\n- Paperless URL: \u003cPAPERLESS_URL\u003e\n- Paperless Token: \u003cPAPERLESS_TOKEN\u003e\n- AI API Key: \u003cAI_API_KEY\u003e\n- AI Modell: \u003cAI_MODEL\u003e\n- AI Base URL (optional): \u003cAI_BASE_URL\u003e\n\nErzeuge jetzt die vollständige YAML.\n```\n\n## Welche Features hat die Integration?\n\n- Native Home-Assistant Integration mit Config Flow und Options-UI\n- KI-gestützte Dokumentklassifizierung für:\n  - Dokumenttyp\n  - Korrespondent\n  - Speicherpfad\n  - Tags\n  - Dokumentdatum\n- Optionales Auto-Anlegen fehlender Entitäten (Korrespondent, Dokumenttyp, Tags)\n- Dry-Run Modus ohne Schreibzugriffe in Paperless\n- Vollscan-Modus (`Alle Dokumente`) für Bestandsläufe\n- Precheck-/Skip-Logik zur Token-Einsparung\n- Doppelte Dokumente per Checksum erkennen (optional Metadatenübernahme)\n- Fehler-Quarantäne und Tag-Bypass für robuste Dauerläufe\n- KI-Notizen inkl. Begründung/Kurz-Zusammenfassung\n- Optionales Custom-Field-Enrichment für strukturierte Vertrags- und Lohnfelder\n- Token-/Kosten-Tracking (letzter Lauf + Gesamtwerte)\n- Services:\n  - `paperless_kiplus.run`\n  - `paperless_kiplus.stop`\n  - `paperless_kiplus.stop_now`\n  - `paperless_kiplus.resume`\n- Geräte-Buttons für:\n  - Bestandsdaten neu anreichern\n  - Lauf pausieren\n  - Lauf sofort stoppen\n  - Pausierten Lauf fortsetzen\n  - Letztes Protokoll anzeigen\n  - Letztes Protokoll exportieren\n  - Statistiken zurücksetzen\n  - Fehlgeschlagene Dokumente zurücksetzen\n- Parallele KI-Verarbeitung (konfigurierbar)\n- KI-Tag-Vorfilter: KI-getaggte Dokumente können standardmäßig komplett ausgeschlossen werden\n- Echte Live-Fortschrittsanzeige:\n  - Prozent-Fortschritt\n  - aktueller Dokumenttitel\n  - laufende Zähler für Gescannt / Aktualisiert / Übersprungen / Fehler\n- Kontrolliertes Pausieren und Fortsetzen:\n  - manuell per Button oder Service\n  - automatisch bei Provider-Wartezeiten (`429`, `Retry-After`, `insufficient_quota`)\n- Optionales Tax Enrichment für Einkommensteuer-Vorbereitung:\n  - feste Steuer-Taxonomie\n  - semantischer WISO-Mapping-Layer\n  - Review-Flags und Confidence-Werte\n  - formale Nachweisprüfung\n  - Exporte als `tax_export.json` und `tax_review.csv`\n  - steuerliche Ergebnis-Tags in Paperless\n  - eigene UI-Optionen für Steuer-Kontext und Tax-only-Nachlauf\n\n## Custom Field Enrichment\n\n### Ziel\n\nZusätzlich zur normalen Klassifikation kann die Integration strukturierte\nPaperless-Custom-Fields befüllen. Es gibt dafür jetzt zwei getrennte Wege:\n\n- `enable_custom_field_enrichment` für den kleinen festen Standard-Katalog\n  (Vertrag / Lohnabrechnung)\n- `enable_secondbrain_custom_fields` für bereits in Paperless angelegte\n  `sb_`-Felder, die von `SecondBrain` später strukturiert ausgelesen werden\n- automatischer Tag `SB`, sobald ein Dokument als SecondBrain-vorbereitet gilt\n\n### SecondBrain `sb_`-Felder\n\nDie vollständige technische Consumer-Schnittstelle für `SecondBrain` steht in:\n\n- [docs/secondbrain-interface.md](./docs/secondbrain-interface.md)\n\n#### Aktivierung\n\n```yaml\nenable_secondbrain_custom_fields: true\nsecondbrain_custom_fields_overwrite_existing: false\nsecondbrain_custom_fields_attach_empty_when_unknown: false\nsecondbrain_custom_fields_confidence_threshold: 0.70\nsecondbrain_custom_fields_log_missing_fields: true\n```\n\nAlternativ gruppiert:\n\n```yaml\nsecondbrain_custom_fields:\n  enabled: true\n  overwrite_existing: false\n  attach_empty_when_unknown: false\n  confidence_threshold: 0.70\n  log_missing_fields: true\n```\n\n#### Voraussetzungen\n\n- Paperless-ngx mit Custom-Field-Support\n- die `sb_`-Felder müssen bereits in Paperless existieren\n- ein API-Benutzer mit Rechten auf `CustomField` und `Document`\n\nWichtig:\n\n- Fehlende `sb_`-Felder brechen den Lauf nicht ab. Sie werden geloggt und\n  übersprungen.\n- Select-Felder werden nicht über hart codierte IDs beschrieben. Die\n  sichtbaren Labels aus der KI-Ausgabe werden zur Laufzeit gegen die in\n  Paperless hinterlegten Select-Optionen aufgelöst.\n- Bestehende Werte werden standardmäßig nicht überschrieben.\n- Im Dry-Run wird nur angezeigt, was geschrieben würde.\n- Dokumente mit sinnvoll befüllten `sb_`-Feldern gelten als vorbereitet und\n  bekommen zusätzlich den Tag `SB`.\n\n#### Unterstützte `sb_`-Felder\n\nKlassifizierung:\n\n- `sb_document_category`\n- `sb_life_area`\n\nReferenzen:\n\n- `sb_case_reference`\n- `sb_contract_number`\n- `sb_customer_number`\n- `sb_invoice_number`\n- `sb_policy_number`\n- `sb_meter_number`\n- `sb_provider_name`\n- `sb_person_involved`\n- `sb_object_reference`\n- `sb_bank_account_hint`\n\nBeträge:\n\n- `sb_amount_total`\n- `sb_amount_net`\n- `sb_amount_tax`\n\nDatumsfelder:\n\n- `sb_due_date`\n- `sb_document_date`\n- `sb_period_start`\n- `sb_period_end`\n- `sb_effective_from`\n- `sb_effective_until`\n\nAufgaben / Status:\n\n- `sb_requires_action`\n- `sb_action_status`\n- `sb_action_owner`\n- `sb_next_action`\n\nRecht / Finanzen / Steuer:\n\n- `sb_legal_relevance`\n- `sb_financial_relevance`\n- `sb_tax_year`\n- `sb_tax_type`\n\nEnergie / Fahrzeug:\n\n- `sb_energy_type`\n- `sb_vehicle`\n\nQualität / SecondBrain-Steuerung:\n\n- `sb_confidence`\n- `sb_source_quality`\n- `sb_sensitive`\n- `sb_export_to_secondbrain`\n- `sb_ignore_by_secondbrain`\n\nVerknüpfungen:\n\n- `sb_related_documents`\n- `sb_external_url`\n\n#### Verhalten\n\n- Die KI kann optional ein strukturiertes Objekt `secondbrain_custom_fields`\n  liefern. Jeder Feldvorschlag besteht aus `value`, `confidence` und `reason`.\n- Werte unterhalb `secondbrain_custom_fields_confidence_threshold` werden nicht\n  nach Paperless geschrieben.\n- Datumswerte werden auf `YYYY-MM-DD` normalisiert.\n- Monetäre Werte werden intern tolerant gelesen und für Paperless auf das\n  dokumentierte Format `EUR12.34` gebracht.\n- Wenn `enable_tax_enrichment` aktiv ist, werden vorhandene Steuerdaten wie\n  `tax_year`, `document_date`, `service_period_from`, `service_period_to`,\n  `issuer` und `total_amount` als `sb_`-Fallbacks wiederverwendet.\n- In der KI-Notiz erscheint ein eigener Abschnitt `SecondBrain-Felder`, sobald\n  tatsächlich `sb_`-Werte erkannt oder gesetzt wurden.\n\n#### Bestandsdaten-Backfill\n\nFür bereits eingelesene Paperless-Datenbanken gibt es einen eigenen\nBackfill-Durchlauf. Er ist für genau den Fall gedacht, dass neue Funktionen wie\nTax Enrichment, `sb_`-Custom-Fields oder weitere Zusatzfelder nachträglich auf\nalte Dokumente angewendet werden sollen.\n\nWichtig dabei:\n\n- Der Backfill ignoriert den normalen `#NEU`-Tag-Filter.\n- Bereits KI-getaggte Dokumente werden noch einmal analysiert, aber nur\n  anreichernd aktualisiert.\n- Standard-Metadaten wie Dokumenttyp, Korrespondent, Speicherpfad, Tags und\n  Dokumentdatum werden bei bereits KI-getaggten Dokumenten dabei nicht\n  überschrieben.\n- Wenn du bestehende KI-Dokumente absichtlich komplett neu klassifizieren\n  möchtest, nutze weiterhin den normalen Reprocess-Weg über\n  `reprocess_ki_tagged_documents: true` und nicht den Backfill-Modus.\n- Die kostenoptimierenden Standard-Prechecks werden im Backfill bewusst\n  ausgesetzt, damit die Bestandsdaten wirklich vollständig erneut geprüft\n  werden können.\n\nCLI-Beispiel für den kompletten Backfill:\n\n```bash\npython3 /config/custom_components/paperless_kiplus/paperless_ai_sorter.py \\\n  --config config.yaml \\\n  --backfill-existing-documents\n```\n\nWenn du den Gesamtdurchlauf in Chargen aufteilen möchtest:\n\n```bash\npython3 /config/custom_components/paperless_kiplus/paperless_ai_sorter.py \\\n  --config config.yaml \\\n  --backfill-existing-documents \\\n  --max-documents 200\n```\n\nIn Home Assistant kannst du den Backfill auf zwei Wegen starten:\n\n- Button `Paperless KIplus Bestandsdaten neu anreichern`\n- Service `paperless_kiplus.run` mit `backfill_existing_documents: true`\n\nBeispiel-Service-Call:\n\n```yaml\nservice: paperless_kiplus.run\ndata:\n  backfill_existing_documents: true\n```\n\nIm Backfill gilt zusätzlich:\n\n- Bereits befüllte SecondBrain-Dokumente werden vor dem KI-Aufruf erkannt.\n- Wenn schon sinnvolle `sb_`-Felder vorhanden sind, wird das Dokument ohne neue\n  KI-Tokens übersprungen.\n- Solche Dokumente bekommen, falls noch nicht vorhanden, automatisch den Tag\n  `SB`.\n\n#### Live-Fortschritt, Pause und Resume\n\nWährend eines Laufs schreibt der Sorter jetzt maschinenlesbare Runtime-Events.\nDadurch kann Home Assistant echten Fortschritt anzeigen, statt nur auf das\nLaufende zu warten.\n\nSichtbar sind unter anderem:\n\n- `Paperless KIplus Fortschritt` als Prozent-Sensor\n- `progress_current_document_title` im Statussensor\n- `progress_last_event_at`, damit man sofort sieht, wann der letzte echte Fortschritt ankam\n- eigener Sensor `Paperless KIplus Aktuelles Dokument`\n- eigener Sensor `Paperless KIplus Letztes fertiges Dokument`\n- `progress_scanned`, `progress_updated`, `progress_skipped`, `progress_failed`\n- `resume_available`, `pause_reason` und `auto_resume_at`\n\nZusätzlich gibt es jetzt klickbare Hilfs-Buttons:\n\n- `Paperless KIplus Aktuelles Dokument öffnen`\n- `Paperless KIplus Letztes fertiges Dokument öffnen`\n- `Paperless KIplus Letztes Protokoll herunterladen`\n- `Paperless KIplus Lauf neu starten`\n\nDie Dokument-Buttons erzeugen in Home Assistant eine anklickbare\nBenachrichtigung mit direktem Paperless-Link zum jeweiligen Dokument. Der\nLog-Download-Button exportiert das letzte Protokoll nach `/config/www` und\nzeigt direkt einen anklickbaren Download-Link an.\n\n#### Frischer Neustart statt Resume\n\nWenn du bewusst **nicht** an einem pausierten Stand weiterlaufen willst, sondern\nmit neuer Konfiguration komplett frisch neu beginnen möchtest, nutze jetzt:\n\n- Button: `Paperless KIplus Lauf neu starten`\n- Service: `paperless_kiplus.restart`\n\nDer Neustart:\n\n- stoppt einen laufenden Prozess bei Bedarf sofort,\n- verwirft den alten Resume-Stand,\n- startet den Lauf frisch von vorne,\n- übernimmt ohne explizite Angabe den zuletzt bekannten Modus, z. B.\n  `Bestandsdaten-Backfill`.\n\n#### Fertiges Dashboard zum Einfügen\n\nEs gibt jetzt eine große Lovelace-YAML-Vorlage unter:\n\n- [dashboards/paperless_kiplus_dashboard.yaml](/Users/joachim.stiegler/Paperless-KIplus/dashboards/paperless_kiplus_dashboard.yaml)\n\nDamit bekommst du auf einen Blick:\n\n- Status\n- Fortschritt\n- aktuelles Dokument\n- letztes fertiges Dokument\n- Neustart / Pause / Stop / Resume\n- Log-Download und Support-Hilfen\n\nNeuer Service zum sicheren Pausieren:\n\n```yaml\nservice: paperless_kiplus.stop\ndata: {}\n```\n\nNeuer Service für einen echten Sofort-Stopp:\n\n```yaml\nservice: paperless_kiplus.stop_now\ndata: {}\n```\n\nNeuer Service zum Fortsetzen eines pausierten Laufs:\n\n```yaml\nservice: paperless_kiplus.resume\ndata:\n  wait: false\n```\n\nWichtige Regeln:\n\n- `stop` ist bewusst ein kontrollierter Stop nach aktuellem Dokument oder\n  aktuellem KI-Batch. Der Prozess wird nicht blind hart beendet.\n- `stop_now` beendet den laufenden Prozess sofort. Wenn bereits ein\n  Fortschrittszustand geschrieben wurde, kann der Lauf später trotzdem wieder\n  aufgenommen werden.\n- Ein pausierter Lauf speichert seinen Zustand in einer Resume-Datei und setzt\n  später genau dort fort.\n- Bei kurzen Rate-Limits mit kleinem `Retry-After` wartet der Lauf direkt im\n  selben Prozess.\n- Bei längeren Provider-Wartezeiten oder `insufficient_quota` pausiert der Lauf\n  kontrolliert und plant die Wiederaufnahme, statt Dokumente unnötig in die\n  Fehlerquarantäne zu schicken.\n- Für manuelle CLI-Läufe gibt es zusätzlich:\n  - `--resume-run`\n  - `--request-stop`\n  - `--run-state-file`\n  - `--stop-request-file`\n\n#### Beispiel\n\nBeispiel einer KI-Antwort mit zusätzlichen SecondBrain-Feldern:\n\n```json\n{\n  \"document_type\": \"Rechnung\",\n  \"correspondent\": \"Muster GmbH\",\n  \"storage_path\": \"Privat\",\n  \"tags\": [\"Finanzen\"],\n  \"document_date\": \"2026-05-01\",\n  \"summary\": \"Rechnung über Speichererweiterung.\",\n  \"confidence\": 0.91,\n  \"rationale\": \"Rechnungsnummer, Betrag und Zahlungsziel klar erkannt.\",\n  \"secondbrain_custom_fields\": {\n    \"sb_document_category\": {\n      \"value\": \"Rechnung\",\n      \"confidence\": 0.95,\n      \"reason\": \"Rechnungsnummer und Gesamtbetrag klar erkennbar.\"\n    },\n    \"sb_amount_total\": {\n      \"value\": \"123.45\",\n      \"confidence\": 0.88,\n      \"reason\": \"Gesamtbetrag inkl. MwSt. erkannt.\"\n    },\n    \"sb_due_date\": {\n      \"value\": \"2026-05-15\",\n      \"confidence\": 0.84,\n      \"reason\": \"Zahlungsziel im Dokument erkannt.\"\n    }\n  }\n}\n```\n\nNach der Auflösung gegen Paperless können daraus zum Beispiel diese Werte\nentstehen:\n\n- `sb_document_category` -\u003e Select-Option-ID aus Paperless\n- `sb_amount_total` -\u003e `EUR123.45`\n- `sb_due_date` -\u003e `2026-05-15`\n\n### Standard-Katalog (Vertrag / Lohnabrechnung)\n\nZusätzlich gibt es weiterhin den kleineren festen Katalog:\n\n```yaml\nenable_custom_field_enrichment: true\ncreate_missing_custom_fields: true\n```\n\nVerträge:\n\n- `Vertragsnummer`\n- `Kundennummer`\n- `Vertragsbeginn`\n- `Vertragsende`\n- `Kündigen bis`\n- `Monatliche Aufwendungen`\n\nLohnabrechnungen:\n\n- `Brutto`\n- `Netto`\n- `Boni`\n- `Sonstige Bezüge`\n- `Steuern/Sozialabgaben`\n- `Sonstige Abzüge`\n- `Abgaben gesamt`\n\n### Grenzen\n\n- Die Extraktion bleibt KI-gestützt und ist daher ein Vorschlagssystem.\n- Das Feature ist bewusst auf einen festen Feldkatalog begrenzt, damit keine\n  unkontrollierte Feldflut in Paperless entsteht.\n- Wenn `SecondBrain` diese Felder als First-Class-Datenmodell nutzen soll,\n  muss dessen Importpfad die Paperless-Custom-Fields ebenfalls aktiv auslesen.\n\n## Tax Enrichment\n\n### Ziel\n\nDie Tax-Enrichment-Funktion ergänzt die normale Dokumentklassifikation um eine\nsteuerorientierte Sicht pro Dokument. Sie ist als Vorschlagssystem gebaut und\ntrifft keine endgültigen Rechtsentscheidungen.\n\n### Architekturüberblick\n\n- Die bestehende Paperless-Klassifikation bleibt unverändert und läuft weiter wie bisher.\n- Optional wird danach ein separates, versioniertes `tax_enrichment` pro Dokument erzeugt.\n- Das Steuerobjekt nutzt:\n  - eine feste interne Taxonomie\n  - einen semantischen WISO-Zielbereich\n  - eine formale Nachweis-/Validierungslogik\n  - Review-Flags für menschliche Nacharbeit\n- Es wird bewusst kein proprietäres WISO-Dateiformat erzeugt.\n\n### Datenmodell\n\nDas Steuerobjekt enthält unter anderem:\n\n- `tax_year`\n- `document_date`\n- `service_period_from`\n- `service_period_to`\n- `document_type`\n- `issuer`\n- `recipient`\n- `total_amount`\n- `currency`\n- `payment_method`\n- `payment_verified`\n- `evidence_type`\n- `tax_category`\n- `tax_subcategory`\n- `deduction_domain`\n- `wiso_target_area`\n- `classification_confidence`\n- `eligibility_confidence`\n- `reasoning_summary`\n- `flags`\n- optional zusätzlich `person_reference`, `child_reference`, `household_reference`, `extracted_evidence`, `missing_requirements`, `recommended_follow_up`, `formal_validity`\n\n### Steuerkategorien\n\nHauptkategorien:\n\n- `werbungskosten`\n- `sonderausgaben`\n- `aussergewoehnliche_belastungen`\n- `kinderbetreuungskosten`\n- `haushaltsnahe_dienstleistungen`\n- `handwerkerleistungen`\n- `unterhalt`\n- `pflege`\n- `kapitalvermoegen`\n- `vermietung`\n- `selbststaendigkeit`\n- `nicht_steuerrelevant`\n- `unklar`\n\nBeispiel-Unterkategorien:\n\n- `arbeitsmittel`\n- `homeoffice`\n- `weiterbildung`\n- `fahrtkosten`\n- `kita`\n- `tagesmutter`\n- `babysitter`\n- `reinigung`\n- `gartenpflege`\n- `winterdienst`\n- `handwerker_lohnkosten`\n- `medikamente`\n- `apotheke`\n- `pflegedienst`\n- `pflegeheim`\n\n### Review-Flags\n\nMindestens diese Review-Flags werden unterstützt:\n\n- `needs_review`\n- `needs_payment_proof`\n- `needs_person_assignment`\n- `needs_year_assignment`\n- `high_audit_relevance`\n- `possible_finanzamt_query`\n- `not_tax_relevant`\n- `mixed_private_and_tax_relevant`\n- `missing_labor_split`\n- `cash_payment_not_eligible`\n\n### Exportformate\n\nBei aktivierter Funktion werden pro Steuerjahr Dateien erzeugt:\n\n- `tax_exports/\u003cjahr\u003e/tax_export.json`\n- `tax_exports/\u003cjahr\u003e/tax_review.csv`\n\n`tax_export.json` enthält:\n\n- `taxpayer`\n- `tax_year`\n- `documents`\n- `category_totals`\n- `review_items`\n- `missing_evidence`\n- `notes_for_wiso`\n\n`tax_review.csv` enthält pro Dokument mindestens:\n\n- `document_id`\n- `title`\n- `document_date`\n- `issuer`\n- `total_amount`\n- `tax_year`\n- `tax_category`\n- `tax_subcategory`\n- `wiso_target_area`\n- `formal_validity`\n- `classification_confidence`\n- `eligibility_confidence`\n- `flags`\n- `reasoning_summary`\n\n### Grenzen der Automatisierung\n\n- Die Steueranalyse ist ein Vorschlagssystem, keine Rechtsberatung.\n- WISO wird nur semantisch vorbereitet, nicht über ein proprietäres Dateiformat angesteuert.\n- Fehlende Zahlungsnachweise, fehlende Personenzuordnung oder unklare Jahre werden bewusst als Review-Fall markiert.\n- Bei haushaltsnahen Dienstleistungen und Handwerkerleistungen werden Barzahlung und fehlende Lohn-/Materialtrennung explizit markiert.\n\n### Beispielkonfiguration\n\nZusätzliche Konfigurationsfelder:\n\n```yaml\nenable_tax_enrichment: true\ntax_export_dir: \"tax_exports\"\ntax_export_years:\n  - 2025\ntax_process_ki_tagged_documents: false\ntax_personal_context: |\n  Steuerpflichtiger: Max Mustermann\n  Familienstand:\n  Kinder:\n  Betreuungsmodell:\n  Sonstige steuerlich wichtige Hinweise:\n```\n\n### Steuer-Tags in Paperless\n\nWenn Tax Enrichment aktiv ist, werden steuerliche Ergebnis-Tags best effort nach\nPaperless gespiegelt:\n\n- `KI Steuerrelevant \u003cJahr\u003e` bei steuerlich relevantem Dokument mit erkanntem Steuerjahr\n- `KI nicht Steuerrelevant` bei klar nicht steuerrelevanten Dokumenten\n\nSo kannst du spaeter direkt nach Steuerjahr oder Nicht-Relevanz filtern.\n\n### Alte KI-Dokumente einmal steuerlich nachziehen\n\nWenn du bereits viele Dokumente mit KI-Tag hast und diese nicht neu klassifizieren,\naber einmal steuerlich prüfen lassen willst, nutze:\n\n```yaml\nenable_tax_enrichment: true\ntax_process_ki_tagged_documents: true\nreprocess_ki_tagged_documents: false\n```\n\nDann werden bestehende KI-Dokumente nur fuer Tax Enrichment erneut betrachtet,\nohne die normale Dokument-Klassifikation noch einmal durchzuschicken.\n\n### Prompt fuer deinen privaten Steuerkontext\n\nDu kannst dir einen guten Freitext fuer `tax_personal_context` mit ChatGPT erzeugen\nlassen und dann in Home Assistant direkt in dein YAML-Feld einfügen.\n\n```text\nErstelle mir einen kompakten, gut strukturierten Freitext fuer die YAML-Einstellung\n\"tax_personal_context\" meiner Home-Assistant Integration \"Paperless KIplus Runner\".\n\nZiel:\n- Die Information soll einer Steuer-KI helfen, private deutsche Dokumente fuer die\n  Einkommensteuer sinnvoller zu bewerten.\n- Es geht nur um Kontext, nicht um eine Steuererklaerung.\n- Gib nur klaren, kopierbaren Text aus, kein Markdown, keine Erklaerungen.\n\nBitte frage bzw. strukturiere die Antwort nach diesen Punkten:\n- Steuerpflichtige Hauptperson mit Name\n- Ehe-/Partnerschaftsstatus\n- Zusammenveranlagung oder Trennung, falls bekannt\n- Kinder mit Name, Geburtsjahr/Alter und Wohn-/Betreuungssituation\n- Bei getrennten Eltern: Verteilung der Kinderbetreuung und wer welche Kosten traegt\n- Weitere haushaltszugehoerige oder unterstuetzte Personen\n- Pflegefaelle, Unterhalt, Behinderung, Krankheitskosten oder andere besondere Belastungen\n- Berufliche Situation, soweit fuer Werbungskosten wichtig\n- Vermietung, Selbststaendigkeit, Kapitalertraege oder sonstige steuerlich relevante Lebensbereiche\n- Sonstige Hinweise, wonach eine Steuer-KI besonders schauen soll\n\nAnforderungen:\n- Formuliere neutral, knapp und sachlich.\n- Verwende Abschnitte mit klaren Ueberschriften.\n- Erfinde nichts und lasse unbekannte Punkte als \"unbekannt\" stehen.\n- Optimiere den Text fuer spaeteres maschinelles Mitlesen.\n```\n\n## Versionsverlauf (antichronologisch)\n\n- `v1.3.5` (2026-04-26)\n  - Neuer Service und Button `Lauf neu starten`: verwirft bewusst den alten Resume-Stand und startet frisch von vorne.\n  - Neustart übernimmt standardmäßig den zuletzt bekannten Modus, zum Beispiel Backfill.\n  - Großes Lovelace-Dashboard als direkt einfügbare YAML-Vorlage ergänzt.\n\n- `v1.3.4` (2026-04-26)\n  - Neue Sensoren für `Aktuelles Dokument` und `Letztes fertiges Dokument` ergänzt.\n  - Neue Buttons ergänzt, die anklickbare Paperless-Links für aktuelles und zuletzt abgeschlossenes Dokument bereitstellen.\n  - Log-Download-Button verbessert: Export erzeugt jetzt direkt eine anklickbare Home-Assistant-Benachrichtigung mit Download-Link.\n  - Statussensor enthält jetzt zusätzlich URLs für aktuelles und letztes fertiges Dokument.\n\n- `v1.3.3` (2026-04-26)\n  - Live-Fortschritts-Events deutlich verschlankt, damit Home Assistant nicht mehr komplette OCR-Inhalte als Fortschritt mitschleppen muss.\n  - Resume-State bleibt weiterhin vollständig auf Disk erhalten, während der Live-Status nur noch schlanke Pending-Metadaten überträgt.\n  - Neuer Zeitstempel `progress_last_event_at` ergänzt, damit hängende oder stille Läufe sofort erkennbar sind.\n  - Sofort-Stopp bevorzugt jetzt die vollständige Run-State-Datei für Resume, statt einen eventuell abgespeckten Live-Status zu konservieren.\n\n- `v1.3.2` (2026-04-26)\n  - Backfill prüft jetzt vor dem KI-Aufruf, ob ein Dokument bereits sinnvolle `sb_`-Felder besitzt.\n  - Bereits vorbereitete SecondBrain-Dokumente werden im Backfill ohne neue KI-Tokens übersprungen.\n  - Dokumente mit vorhandenen oder frisch gesetzten SecondBrain-Feldern bekommen automatisch den Tag `SB`.\n\n- `v1.3.1` (2026-04-26)\n  - Echten Sofort-Stopp per Home-Assistant-Service `paperless_kiplus.stop_now` ergänzt.\n  - Neuen Geräte-Button `Paperless KIplus Lauf sofort stoppen` ergänzt.\n  - Runner bewahrt beim Sofort-Stopp den letzten bekannten Fortschrittszustand, damit ein späteres Resume möglich bleibt.\n  - Statussensor zeigt jetzt zusätzlich `force_stop_requested`.\n\n- `v1.3.0` (2026-04-26)\n  - Echte Live-Fortschrittsanzeige mit Prozent, aktuellem Dokument und laufenden Zählern ergänzt.\n  - Kontrolliertes Pausieren und Fortsetzen für manuelle Läufe eingebaut.\n  - Resume-State-Datei eingeführt, damit pausierte Läufe später exakt weiterlaufen können.\n  - Neue Home-Assistant-Services `paperless_kiplus.stop` und `paperless_kiplus.resume` ergänzt.\n  - Neue Geräte-Buttons für Pause und Fortsetzen ergänzt.\n  - Provider-429/Quota-Fälle werden jetzt als Pause statt als Dokumentfehler behandelt.\n  - Automatische Wiederaufnahme nach `Retry-After` bzw. Provider-Backoff ergänzt.\n\n- `v1.2.0` (2026-04-26)\n  - SecondBrain-Custom-Field-Sync für bestehende `sb_`-Felder in Paperless ergänzt.\n  - Strukturierte KI-Ausgabe für `sb_`-Felder mit Confidence und Begründung hinzugefügt.\n  - Bestehende Paperless-Custom-Fields werden dynamisch per Name und Select-Option-ID aufgelöst.\n  - Neuer Bestandsdaten-Backfill für bereits eingelesene Paperless-Datenbanken ergänzt.\n  - KI-getaggte Dokumente können im Backfill gezielt nur für neue Zusatzfunktionen erneut angereichert werden.\n  - Home-Assistant-Service und Geräte-Button für den Backfill ergänzt.\n\n- `v1.1.1` (2026-03-29)\n  - UI-Optionen für Steuerfunktion ergänzt.\n  - Privater Steuerkontext direkt in Home Assistant pflegbar.\n  - Bereits KI-getaggte Dokumente können einmalig nur steuerlich nachgeprüft werden.\n  - Steuer-Tags `KI Steuerrelevant \u003cJahr\u003e` und `KI nicht Steuerrelevant` ergänzt.\n\n- `v1.1.0` (2026-03-28)\n  - Erste produktiv nutzbare Tax-Enrichment-Erweiterung hinzugefügt.\n  - Feste Steuer-Taxonomie, WISO-Mapping-Layer, Review-Flags und Nachweisprüfung ergänzt.\n  - Export pro Steuerjahr als `tax_export.json` und `tax_review.csv` eingeführt.\n\n- `v1.0.0` (2026-03-08)\n  - Erstes stabiles Release für HACS.\n\n- `v0.1.49` (2026-03-08)\n  - KI-Tag-Vorfilter vor der Abarbeitung ergänzt.\n  - Performance-Metriken im Log ergänzt (KI-Batches/Zeiten).\n\n- `v0.1.48` (2026-03-06)\n  - `max_documents` zählt übersprungene Dokumente nicht mehr als Verarbeitungsbudget.\n\n- `v0.1.47` (2026-03-06)\n  - Option `reprocess_ki_tagged_documents` eingeführt (Default AUS).\n\n- `v0.1.46` (2026-03-03)\n  - `already_classified_skip` im All-Documents-Verhalten nachgeschärft.\n\n- `v0.1.45` (2026-03-03)\n  - Tag-Sanitizer, KI-Retry-Backoff und robustere PATCH-Fallbacks.\n\n- `v0.1.44` (2026-03-03)\n  - Parallele KI-Verarbeitung mit konfigurierbarer Worker-Anzahl.\n\n- Ältere Releases\n  - Weitere Tags vorhanden: `v0.1.43` bis `v0.1.2`.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffeberdin%2Fpaperless-kiplus","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ffeberdin%2Fpaperless-kiplus","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffeberdin%2Fpaperless-kiplus/lists"}