m/mDMS
1
0
Fork 0
Code Issues 5 Pull Requests Actions Packages Projects Releases Wiki Activity

paperless-AI prompt: intra-scan correspondent dedup + better fuzzy match for short-brand forms #4

New Issue
Open
opened 2026-05-21 09:23:41 +00:00 by mAi · 1 comment
mAi commented 2026-05-21 09:23:41 +00:00
Collaborator
Copy Link

Bundled follow-ups surfaced by hermes during #3.

(a) Intra-scan correspondent dedup

Observed: paperless-AI processed a single multi-doc scan and created three separate aliases for the same sender (Praxis-Irle cluster). Each doc in the same scan batch triggered a fresh "new correspondent" creation because the AI sees each doc independently — there's no state-sharing across the batch.

Fix: prompt rule along the lines of "Bevor du einen neuen Correspondent anlegst, pruefe ob du in dieser Sitzung bereits einen Correspondent mit aehnlichem Namen angelegt hast — verwende dann den existierenden." The paperless-AI worker doesn't natively pass batch context, so this is best-effort, but adding the rule + reinforcing the fuzzy-match catalogue should catch most cases.

(b) Short-brand fuzzy match

Observed: existing correspondent Hogan Lovells International LLP was not matched when a new doc came in from "Hogan Lovells" — AI created Hogan Lovells as a separate correspondent.

Fix: extend the fuzzy-match rule in SYSTEM_PROMPT to explicitly cover the case where the OCR form is a strict prefix of the existing correspondent (and vice-versa), or where the brand-token overlaps. Concretely add to the existing fuzzy-match-criteria block: "Beim Vergleich gilt: Ist der OCR-Name ein striktes Praefix eines existierenden Correspondents (oder umgekehrt), und stimmen die ersten 2 Brand-Tokens ueberein, verwende den existierenden Correspondent."

Approach

Both fixes are prompt-only — no paperless-AI code changes. Update infra/paperless/SYSTEM_PROMPT.txt (single source of truth now, per #3), push to live via infra/paperless/push_system_prompt.py, restart container, verify with a fresh test doc.

Test plan

  1. Dedup: drop a 4-page Praxis-Irle scan (with patch-T separators producing 2+ docs). Check Paperless after AI runs: only one correspondent created, not multiple. If there's no Praxis-Irle doc handy, simulate with another sender — pick one not yet in the correspondent list, scan a 2-doc stack.
  2. Short-brand: drop a doc from "Hogan Lovells" (without the LLP suffix). Check that AI assigns it to existing Hogan Lovells International LLP, doesn't create a new correspondent.

Out of scope

  • Adding batch-context state to paperless-AI itself (that's a code change in the paperless-AI repo, not here).
  • Other prompt improvements not surfaced concretely yet.

Context

  • #3 (already shipped): live SYSTEM_PROMPT reconciled with repo, Empfaenger-Regel added, soften-existing rule, push_system_prompt.py automates sync.
  • Worker should mirror hermes' #3 approach: edit repo file, run push script, restart container, verify, commit, comment.

Role: gitster.

Bundled follow-ups surfaced by hermes during #3. ## (a) Intra-scan correspondent dedup Observed: paperless-AI processed a single multi-doc scan and created **three separate aliases** for the same sender (`Praxis-Irle` cluster). Each doc in the same scan batch triggered a fresh "new correspondent" creation because the AI sees each doc independently — there's no state-sharing across the batch. Fix: prompt rule along the lines of "Bevor du einen neuen Correspondent anlegst, pruefe ob du in dieser Sitzung bereits einen Correspondent mit aehnlichem Namen angelegt hast — verwende dann den existierenden." The paperless-AI worker doesn't natively pass batch context, so this is best-effort, but adding the rule + reinforcing the fuzzy-match catalogue should catch most cases. ## (b) Short-brand fuzzy match Observed: existing correspondent `Hogan Lovells International LLP` was not matched when a new doc came in from "Hogan Lovells" — AI created `Hogan Lovells` as a separate correspondent. Fix: extend the fuzzy-match rule in SYSTEM_PROMPT to explicitly cover the case where the OCR form is a strict prefix of the existing correspondent (and vice-versa), or where the brand-token overlaps. Concretely add to the existing fuzzy-match-criteria block: "Beim Vergleich gilt: Ist der OCR-Name ein striktes Praefix eines existierenden Correspondents (oder umgekehrt), und stimmen die ersten 2 Brand-Tokens ueberein, verwende den existierenden Correspondent." ## Approach Both fixes are prompt-only — no paperless-AI code changes. Update `infra/paperless/SYSTEM_PROMPT.txt` (single source of truth now, per #3), push to live via `infra/paperless/push_system_prompt.py`, restart container, verify with a fresh test doc. ## Test plan 1. **Dedup:** drop a 4-page Praxis-Irle scan (with patch-T separators producing 2+ docs). Check Paperless after AI runs: only one correspondent created, not multiple. If there's no Praxis-Irle doc handy, simulate with another sender — pick one not yet in the correspondent list, scan a 2-doc stack. 2. **Short-brand:** drop a doc from "Hogan Lovells" (without the LLP suffix). Check that AI assigns it to existing `Hogan Lovells International LLP`, doesn't create a new correspondent. ## Out of scope - Adding batch-context state to paperless-AI itself (that's a code change in the paperless-AI repo, not here). - Other prompt improvements not surfaced concretely yet. ## Context - #3 (already shipped): live SYSTEM_PROMPT reconciled with repo, Empfaenger-Regel added, soften-existing rule, push_system_prompt.py automates sync. - Worker should mirror hermes' #3 approach: edit repo file, run push script, restart container, verify, commit, comment. Role: gitster.
mAi self-assigned this 2026-05-21 09:23:41 +00:00
mAi commented 2026-05-21 09:27:25 +00:00
Author
Collaborator
Copy Link

Done — beide Prompt-Regeln deployed

Beide Fixes als reine Prompt-Aenderung in infra/paperless/SYSTEM_PROMPT.txt umgesetzt (keine paperless-AI Code-Aenderung). Via push_system_prompt.py --apply auf den Live-Container gepusht, Container restartet (healthy).

(a) Intra-Scan Dedup — neue Regel 4 in Correspondents-Sektion

Direkt nach der Fuzzy-Match-Vorbereitung eingefuegt:

  1. INTRA-SCAN DEDUP: Bevor du einen neuen Correspondent anlegst, pruefe ob du in dieser Sitzung (gleicher Scan-Batch, gleicher Verarbeitungslauf) bereits einen Correspondent mit aehnlichem Namen angelegt hast — verwende dann den existierenden (denselben Namen unveraendert), statt eine weitere Variante anzulegen. Konkret: kommen in einem Scan mehrere Dokumente vom gleichen Sender vor (z.B. zwei Rechnungen derselben Arztpraxis, mehrere Schreiben desselben Versorgers), MUSS der Correspondent-Name bei jedem dieser Dokumente identisch sein. Im Zweifel waehle die laengste / vollstaendigste Form, die du in diesem Scan gesehen hast.

Plus konkretes Beispiel im Examples-Block:

Drei Dokumente einer neuen Praxis im selben Scan: erstes Dokument legt Correspondent "Praxis Dr. Mustermann" an, zweites und drittes Dokument verwenden GENAU diesen Namen, auch wenn der OCR "Dr. Mustermann" oder "Praxis fuer XYZ" liest (siehe Regel 4).

Caveat (auch im commit message und memory festgehalten): paperless-AI gibt der LLM bei jedem Dokument nur den initial gefetchten Correspondents-Snapshot — es gibt keinen nativen Batch-Kontext zwischen Docs. Die Regel ist also best-effort durch das Modell: bei einem strict-stateless Aufruf weiss das LLM nicht, was es eine Anfrage vorher entschieden hat. Die Regel hilft am ehesten, wenn das LLM aus dem Doc-Kontext selbst erschliessen kann, dass es ein Multi-Doc-Batch vom gleichen Sender ist (Format, Layout, Briefkopf). Eine echte deterministische Loesung braeuchte einen Upstream-Patch in paperless-AI (Stateful Batch-Cache).

(b) Short-Brand Prefix Match — Erweiterung der Fuzzy-Regel

Neuer Absatz direkt nach dem Fuzzy-Regel-Block:

Beim Vergleich gilt: Ist der OCR-Name ein striktes Praefix eines existierenden Correspondents (oder umgekehrt), und stimmen die ersten 2 Brand-Tokens ueberein (Token = Wort, das nicht Rechtsform-Suffix, Adresse oder Anrede ist), verwende den existierenden Correspondent. Das gilt sowohl fuer Kurzformen ohne Rechtsform-Suffix ("Hogan Lovells" -> "Hogan Lovells International LLP") als auch fuer den umgekehrten Fall, wenn die existierende Form kuerzer ist als die OCR-Form.

Plus konkretes Beispiel:

"Hogan Lovells" (Kurzform ohne Rechtsform) -> "Hogan Lovells International LLP" (existiert; OCR-Name ist Praefix, erste 2 Brand-Tokens stimmen)

Verification

$ ssh mdock "docker exec paperless-ai grep -c 'INTRA-SCAN DEDUP' /app/data/.env"
1
$ ssh mdock "docker exec paperless-ai grep -c 'striktes Praefix' /app/data/.env"
1
$ ssh mdock "docker ps --filter name=paperless-ai --format '{{.Names}}\t{{.Status}}'"
paperless-ai\tUp 9 seconds (healthy)

Backup vom alten .env liegt im Container unter /app/data/.env.bak.20260521T092606. 79 Correspondents im Snapshot (Siebels-Namen wie immer gefiltert).

End-to-End Test Plan

Die eigentliche Wirksamkeit zeigt sich erst im Live-Betrieb mit neuen Scans:

  1. Dedup: beim naechsten Multi-Doc-Scan eines neuen Senders (z.B. zwei Rechnungen einer neuen Arztpraxis durch Patch-T getrennt) pruefen, dass nur ein Correspondent angelegt wurde. Falls trotzdem mehrere Aliase entstehen: Caveat oben — dann braucht es den Upstream-Patch.
  2. Short-Brand: beim naechsten Hogan-Lovells-Dokument (oder einem anderen vergleichbar verkuerzten Markennamen) pruefen, dass auf den existierenden Correspondent gemappt wird, nicht ein neuer angelegt.

Wenn (1) sich als nicht ausreichend erweist, separates Issue fuer Upstream-Patch in paperless-AI aufmachen (Batch-Kontext-Cache im Worker).

Commit: a2fa76a41a
Branch: mai/hermes/issue-4-paperless-ai

## Done — beide Prompt-Regeln deployed Beide Fixes als reine Prompt-Aenderung in `infra/paperless/SYSTEM_PROMPT.txt` umgesetzt (keine paperless-AI Code-Aenderung). Via `push_system_prompt.py --apply` auf den Live-Container gepusht, Container restartet (healthy). ### (a) Intra-Scan Dedup — neue Regel 4 in Correspondents-Sektion Direkt nach der Fuzzy-Match-Vorbereitung eingefuegt: > 4. INTRA-SCAN DEDUP: Bevor du einen neuen Correspondent anlegst, pruefe ob du in dieser Sitzung (gleicher Scan-Batch, gleicher Verarbeitungslauf) bereits einen Correspondent mit aehnlichem Namen angelegt hast — verwende dann den existierenden (denselben Namen unveraendert), statt eine weitere Variante anzulegen. Konkret: kommen in einem Scan mehrere Dokumente vom gleichen Sender vor (z.B. zwei Rechnungen derselben Arztpraxis, mehrere Schreiben desselben Versorgers), MUSS der Correspondent-Name bei jedem dieser Dokumente identisch sein. Im Zweifel waehle die laengste / vollstaendigste Form, die du in diesem Scan gesehen hast. Plus konkretes Beispiel im Examples-Block: > Drei Dokumente einer neuen Praxis im selben Scan: erstes Dokument legt Correspondent "Praxis Dr. Mustermann" an, zweites und drittes Dokument verwenden GENAU diesen Namen, auch wenn der OCR "Dr. Mustermann" oder "Praxis fuer XYZ" liest (siehe Regel 4). Caveat (auch im commit message und memory festgehalten): paperless-AI gibt der LLM bei jedem Dokument nur den initial gefetchten Correspondents-Snapshot — es gibt keinen nativen Batch-Kontext zwischen Docs. Die Regel ist also **best-effort durch das Modell**: bei einem strict-stateless Aufruf weiss das LLM nicht, was es eine Anfrage vorher entschieden hat. Die Regel hilft am ehesten, wenn das LLM aus dem Doc-Kontext selbst erschliessen kann, dass es ein Multi-Doc-Batch vom gleichen Sender ist (Format, Layout, Briefkopf). Eine echte deterministische Loesung braeuchte einen Upstream-Patch in paperless-AI (Stateful Batch-Cache). ### (b) Short-Brand Prefix Match — Erweiterung der Fuzzy-Regel Neuer Absatz direkt nach dem Fuzzy-Regel-Block: > Beim Vergleich gilt: Ist der OCR-Name ein striktes Praefix eines existierenden Correspondents (oder umgekehrt), und stimmen die ersten 2 Brand-Tokens ueberein (Token = Wort, das nicht Rechtsform-Suffix, Adresse oder Anrede ist), verwende den existierenden Correspondent. Das gilt sowohl fuer Kurzformen ohne Rechtsform-Suffix ("Hogan Lovells" -> "Hogan Lovells International LLP") als auch fuer den umgekehrten Fall, wenn die existierende Form kuerzer ist als die OCR-Form. Plus konkretes Beispiel: > "Hogan Lovells" (Kurzform ohne Rechtsform) -> "Hogan Lovells International LLP" (existiert; OCR-Name ist Praefix, erste 2 Brand-Tokens stimmen) ### Verification ``` $ ssh mdock "docker exec paperless-ai grep -c 'INTRA-SCAN DEDUP' /app/data/.env" 1 $ ssh mdock "docker exec paperless-ai grep -c 'striktes Praefix' /app/data/.env" 1 $ ssh mdock "docker ps --filter name=paperless-ai --format '{{.Names}}\t{{.Status}}'" paperless-ai\tUp 9 seconds (healthy) ``` Backup vom alten `.env` liegt im Container unter `/app/data/.env.bak.20260521T092606`. 79 Correspondents im Snapshot (Siebels-Namen wie immer gefiltert). ### End-to-End Test Plan Die eigentliche Wirksamkeit zeigt sich erst im Live-Betrieb mit neuen Scans: 1. **Dedup:** beim naechsten Multi-Doc-Scan eines neuen Senders (z.B. zwei Rechnungen einer neuen Arztpraxis durch Patch-T getrennt) pruefen, dass nur ein Correspondent angelegt wurde. Falls trotzdem mehrere Aliase entstehen: Caveat oben — dann braucht es den Upstream-Patch. 2. **Short-Brand:** beim naechsten Hogan-Lovells-Dokument (oder einem anderen vergleichbar verkuerzten Markennamen) pruefen, dass auf den existierenden Correspondent gemappt wird, nicht ein neuer angelegt. Wenn (1) sich als nicht ausreichend erweist, separates Issue fuer Upstream-Patch in paperless-AI aufmachen (Batch-Kontext-Cache im Worker). Commit: https://mgit.msbls.de/m/mDMS/commit/a2fa76a41a842b34fa3256924cc91ba5e162b635 Branch: `mai/hermes/issue-4-paperless-ai`
mAi added the
done
 label 2026-05-21 09:27:47 +00:00
Sign in to join this conversation.
No Branch/Tag Specified
Branches Tags
Labels
Clear labels
done
Work finished by mAi — m closes the issue
No Label
done
Milestone
No items
No Milestone
Projects
Clear projects
No project
Assignees
Clear assignees
mAi m
No Assignees mAi
1 Participants
Notifications
Due Date
No due date set.
Dependencies

No dependencies set.

Reference: m/mDMS#4
No description provided.
Delete Branch "%!s()"

Deleting a branch is permanent. Although the deleted branch may continue to exist for a short time before it actually gets removed, it CANNOT be undone in most cases. Continue?