add final docs

Signed-off-by: Alex Jenkins <kjenkins60@gatech.edu>

docs/tech-specs/universal-decoder.he.md

@@ -2,195 +2,395 @@
 
 ## כותרת
 
-מפענח מסמכים אוניברסלי המופעל על ידי `unstructured` — קבלת פורמטים נפוצים של מסמכים באמצעות שירות יחיד, עם תיעוד מלא של מקור הנתונים ושילוב עם ספריית ניהול מסמכים, תוך רישום מיקומי המקור כמטא-דאטה של גרף ידע למעקב מקצה לקצה.
+מפענח מסמכים אוניברסלי המופעל על ידי `unstructured` - קליטת כל פורמט מסמך נפוץ
+דרך שירות יחיד עם תיעוד מלא ושילוב עם ספרייה, תוך רישום מיקומי המקור כמטא-נתונים של גרף ידע
+למעקב מקצה לקצה.
 
 ## בעיה
 
-ל-TrustGraph כיום יש מפענח ספציפי ל-PDF. תמיכה בפורמטים נוספים (DOCX, XLSX, HTML, Markdown, טקסט רגיל, PPTX וכו') דורשת או כתיבת מפענח חדש לכל פורמט או אימוץ ספריית חילוץ אוניברסלית. לכל פורמט יש מבנה שונה — חלקם מבוססי דפים, חלקם לא — ושרשרת התיעוד חייבת לתעד היכן בכל המסמך המקורי הגיע כל חלק של הטקסט שחולץ.
+
+כיום, ל-TrustGraph יש מפענח ספציפי ל-PDF. תמיכה בפורמטים נוספים (DOCX, XLSX, HTML, Markdown, טקסט רגיל, PPTX וכו') דורשת
+או כתיבת מפענח חדש לכל פורמט או אימוץ ספריית חילוץ אוניברסלית. לכל פורמט יש מבנה שונה - חלקם מבוססי דפים, וחלקם לא -
+ושרשרת התיעוד חייבת לתעד מאיפה בכל מסמך המקורי הגיע כל פיסת טקסט שחולצה.
+
+## גישה
+לתעד כל פיסת טקסט שחולצה ולציין את מקורה.
 
 ## גישה
 
-### ספרייה: `unstructured`
+### ספריה: `unstructured`
 
-יש להשתמש ב-`unstructured.partition.auto.partition()` שמזהה באופן אוטומטי את הפורמט מסוג MIME או סיומת הקובץ ומחלצת אלמנטים מובנים (כותרת, טקסט, טבלה, פריט רשימה וכו'). כל אלמנט מכיל מטא-דאטה, כולל:
+השתמשו ב-`unstructured.partition.auto.partition()` שמזהה אוטומטית את הפורמט
+מחלק סוג MIME או סיומת קובץ ומחלץ אלמנטים מובנים
+(כותרת, טקסט, טבלה, פריט רשימה, וכו'). כל אלמנט נושא
+מטא-דאטה, כולל:
 
-- `page_number` (לפורמטים מבוססי דפים כמו PDF, PPTX)
-- `element_id` (ייחודי לכל אלמנט)
-- `coordinates` (מלבן תחום עבור PDF)
-- `text` (תוכן הטקסט שחולץ)
-- `category` (סוג אלמנט: כותרת, טקסט, טבלה וכו')
+`page_number` (עבור פורמטים מבוססי דפים כמו PDF, PPTX)
+`element_id` (ייחודי לכל אלמנט)
+`coordinates` (מלבן תוחם עבור קבצי PDF)
+`text` (תוכן הטקסט שנחלץ)
+`category` (סוג האלמנט: כותרת, טקסט, טבלה, וכו')
 
 ### סוגי אלמנטים
 
-`unstructured` מחלץ אלמנטים מסוגים שונים ממסמכים. לכל אלמנט יש קטגוריה ומטא-דאטה נלווים:
+`unstructured` מחלץ אלמנטים מסוגים שונים ממסמכים. לכל אלמנט יש
+קטגוריה ומטא-דאטה נלווים:
 
 **אלמנטים טקסטואליים:**
-- `Title` — כותרות סעיפים
-- `NarrativeText` — פסקאות גוף
-- `ListItem` — פריטי רשימה/רשימות ממוספרות
-- `Header`, `Footer` — כותרות/כותרות שוליים של עמודים
-- `FigureCaption` — כיתובים עבור תמונות/גרפיקה
-- `Formula` — ביטויים מתמטיים
-- `Address`, `EmailAddress` — פרטי התקשרות
-- `CodeSnippet` — בלוקי קוד (מ-Markdown)
+`Title` — כותרות סעיפים
+`NarrativeText` — פסקאות גוף הטקסט
+`ListItem` — פריטי רשימות (ממוספרות או עם נקודות)
+`Header`, `Footer` — כותרות/שוליים של עמודים
+`FigureCaption` — כיתובים עבור תמונות/איורים
+`Formula` — ביטויים מתמטיים
+`Address`, `EmailAddress` — פרטי יצירת קשר
+`CodeSnippet` — בלוקי קוד (מתוך markdown)
 
 **טבלאות:**
-- `Table` — נתונים טבלאיים מובנים. `unstructured` מספק גם `element.text` (טקסט רגיל) וגם `element.metadata.text_as_html` (תגית HTML מלאה של `<table>` עם שורות, עמודות וכותרות). עבור פורמטים עם מבנה טבלה מוגדר (DOCX, XLSX, HTML), החילוץ אמין מאוד. עבור PDF, זיהוי טבלאות תלוי באסטרטגיית `hi_res` עם ניתוח פריסה.
+`Table` - נתונים טבלאיים מובנים. `unstructured` מספק גם
+  `element.text` (טקסט רגיל) וגם `element.metadata.text_as_html`
+  (HTML מלא `<table>` עם שורות, עמודות וכותרות שמורות).
+  עבור פורמטים עם מבנה טבלה מפורש (DOCX, XLSX, HTML), החילוץ אמין מאוד. עבור קבצי PDF, זיהוי טבלאות תלוי ב
+  ⟦CODE_0⟧. For PDFs, table detection depends on ⟦CODE_0⟧.
+  האסטרטגיה של `hi_res` עם ניתוח פריסה.
 
 **תמונות:**
-- `Image` — תמונות מוטמעות שזוהו באמצעות ניתוח פריסה (דורש אסטרטגיית `hi_res`). עם `extract_image_block_to_payload=True`, מחזיר את נתוני התמונה כ-base64 ב-`element.metadata.image_base64`. טקסט OCR מהתמונה זמין ב-`element.text`.
+`Image` — זיהוי תמונות מוטמעות באמצעות ניתוח פריסה (דורש
+  `hi_res` אסטרטגיה). עם `extract_image_block_to_payload=True`,
+  מחזיר את נתוני התמונה כ-base64 ב-`element.metadata.image_base64`.
+  טקסט OCR מהתמונה זמין ב-`element.text`.
 
 ### טיפול בטבלאות
 
-טבלאות הן פלט ברמה ראשונה. כאשר המפענח נתקל באלמנט `Table`, הוא שומר על מבנה ה-HTML במקום לפשט לטקסט רגיל. זה נותן למחלץ ה-LLM במעלה הזרם קלט טוב יותר לשליפה של ידע מובנה מנתונים טבלאיים.
+טבלאות הן פלט ברמה ראשונה. כאשר המפענח נתקל באלמנט `Table`,
+הוא שומר על מבנה ה-HTML במקום לשטח לטקסט
+רגיל. זה מספק למחלץ ה-LLM במורד קלט טוב בהרבה
+לשליפת ידע מובנה מנתונים טבלאיים.
 
-הטקסט של העמוד/הסעיף מורכב באופן הבא:
-- אלמנטים טקסטואליים: טקסט רגיל, המחוברים עם שורות חדשות.
-- אלמנטים של טבלאות: תגית טבלה HTML מ-`text_as_html`, עטופה בתגית `<table>` כך שה-LLM יכול להבחין בין טבלאות לבין טקסט רגיל.
+הטקסט של העמוד/הקטע מורכב באופן הבא:
+אלמנטי טקסט: טקסט רגיל, המחוברים בשורות חדשות
+אלמנטי טבלה: תגי HTML של טבלה מ-`text_as_html`, עטופים ב-
+  `<table>` סימון כך שה-LLM יכול להבחין בין טבלאות לבין טקסט
 
 לדוגמה, עמוד עם כותרת, פסקה וטבלה מייצר:
 
 ```
-סקירה פיננסית
+Financial Overview
 
-ההכנסות גדלו ב-15% שנה אחר שנה, הודות לאימוץ ארגוני.
+Revenue grew 15% year-over-year driven by enterprise adoption.
 
 <table>
-<tr><th>רבעון</th><th>הכנסות</th><th>צמיחה</th></tr>
-<tr<td>רבעון 1</td><td>$12 מיליון</td><td>12%</td></tr>
-<tr<td>רבעון 2</td><td>$14 מיליון</td><td>17%</td></tr>
+<tr><th>Quarter</th><th>Revenue</th><th>Growth</th></tr>
+<tr><td>Q1</td><td>$12M</td><td>12%</td></tr>
+<tr><td>Q2</td><td>$14M</td><td>17%</td></tr>
 </table>
 ```
 
-זה שומר על מבנה הטבלה במהלך חלוקה לחלקים ולתוך צינור החילוץ, שבו ה-LLM יכול לחלץ קשרים ישירות מתאים מובנים ולא לנחש על התאמת עמודות מרווח לבן.
+זה שומר על מבנה הטבלאות באמצעות חלוקה לחלקים וליחידת העיבוד
+(pipeline), כאשר מודל השפה הגדול (LLM) יכול לחלץ קשרים ישירות מתוך
+תאים מובנים, ולא לנחש את יישור העמודות על סמך
+רווחים.
 
 ### טיפול בתמונות
 
-תמונות מחולצות ומאוחסנות בספריית הניהול כמסמכים משניים עם `document_type="image"` ו-ID `urn:image:{uuid}`. הם מקבלים משולשים של תיעוד מסוג `tg:Image`, המקושרים לעמוד/סעיף האב שלהם באמצעות `prov:wasDerivedFrom`. מטא-דאטה של תמונה (קואורדינטות, מימדים, `element_id`) נרשמים בתיעוד.
+תמונות מחולצות ונשמרות בספרייה כמסמכים משניים
+עם `document_type="image"` ו-`urn:image:{uuid}` מזהה. הן מקבלות
+טריפלים של מקור (provenance) מסוג `tg:Image`, המקושרים לעמוד/קטע
+הראשי שלהן דרך `prov:wasDerivedFrom`. מטא-נתונים של תמונה (קואורדינטות,
+מידות, element_id) נרשמים במקור.
 
-**חשוב, תמונות אינן מופצות כפלט של `TextDocument`.** הן מאוחסנות בלבד — אינן נשלחות במעלה הזרם למחלק או לכל צינור עיבוד טקסט. זה מכוון:
+**חשוב מאוד: תמונות אינן משודרות כפלט של מסמך טקסט (TextDocument).** הן
+נשמרות בלבד - אינן נשלחות כלפי מטה ליחידת החלוקה (chunker) או לכל
+תהליך עיבוד טקסט. זה נעשה בכוונה:
 
-1. אין עדיין צינור לעיבוד תמונות (שילוב מודל ראייה הוא עבודה עתידית)
-2. העברת נתוני תמונה ב-base64 או פיסות OCR לצינור חילוץ הטקסט תיצור משולשים של גרף ידע "זבל".
+1. אין עדיין תהליך עיבוד תמונות (שילוב מודל ראייה הוא עבודה
+   עתידית)
+2. העברת נתוני תמונה בפורמט base64 או פיסות OCR ליחידת החילוץ
+   של טקסט תייצר טריפלים של גרף ידע (KG) לא מועילים.
 
-תמונות גם אינן נכללות בטקסט העמוד המורכב — כל אלמנטי `Image` מושמטים בשקט כאשר מחברים טקסט של אלמנטים עבור עמוד/סעיף. שרשרת התיעוד רושמת שתמונות קיימות ואיפה שהן הופיעו במסמך, כך שניתן יהיה לשלוף אותן על ידי צינור עיבוד תמונות עתידי מבלי לטעון מחדש את המסמך.
+תמונות גם אינן נכללות בטקסט המורכב של העמוד - כל `Image`
+אלמנטים מתעלמים כאשר מחברים טקסט של אלמנטים עבור
+עמוד/קטע. שרשרת המקור (provenance) רושמת שתמונות קיימות ואיפה
+הן הופיעו במסמך, כך שניתן יהיה לאסוף אותן על ידי תהליך
+עיבוד תמונות עתידי מבלי להכניס מחדש את המסמך.
 
 #### עבודה עתידית
 
-- הכוונת ישויות `tg:Image` למודל ראייה לתיאור, פרשנות דיאגרמות או חילוץ נתוני תרשימים.
-- אחסון תיאורי תמונה כמסמכים טקסטואליים שמוזנים לצינור החלוקה/חילוץ הסטנדרטי.
-- קישור ידע שנחצה חזרה לתמונות מקור באמצעות תיעוד.
+להעביר `tg:Image` ישויות למודל ראייה לצורך תיאור,
+  פרשנות דיאגרמות או חילוץ נתוני טבלה.
+לשמור תיאורי תמונה כמסמכי טקסט משניים שמוזנים
+  לתוך תהליך החלוקה/חילוץ הסטנדרטי.
+לקשר ידע מחולץ בחזרה לתמונות המקוריות דרך מקור.
 
 ### אסטרטגיות סעיפים
 
-לפורמטים מבוססי דפים (PDF, PPTX, XLSX), אלמנטים תמיד מקובצים לפי עמוד/שקופית/גיליון תחילה. עבור פורמטים שאינם מבוססי דפים (DOCX, HTML, Markdown וכו'), למפענח יש אסטרטגיה לחלוקת המסמך לסעיפים. זה מוגדר בזמן ריצה באמצעות `--section-strategy`.
+עבור פורמטים מבוססי עמודים (PDF, PPTX, XLSX), אלמנטים תמיד מקובצים
+לפי עמוד/שקופית/גיליון. עבור פורמטים שאינם מבוססי עמודים (DOCX, HTML, Markdown,
+וכו'), למפענח יש אסטרטגיה לחלוקת המסמך לקטעים.
+זה מוגדר בזמן ריצה באמצעות `--section-strategy`.
 
-כל אסטרטגיה היא פונקציית קיבוץ על רשימת האלמנטים של `unstructured`. הפלט הוא רשימת קבוצות אלמנטים; שאר הצינור (הרכבת טקסט, אחסון בספריית הניהול, תיעוד, פליטת `TextDocument`) זהים ללא קשר לאסטרטגיה.
+כל אסטרטגיה היא פונקציית קיבוץ על רשימת `unstructured`
+אלמנטים. הפלט הוא רשימה של קבוצות אלמנטים; שאר
+התהליך (הרכבת טקסט, אחסון בספרייה, מקור, פלט של מסמך טקסט
+(TextDocument)) זהים ללא קשר לאסטרטגיה.
 
 #### `whole-document` (ברירת מחדל)
 
-פליטת כל המסמך כסעיף יחיד. תן למחלק במעלה הזרם לטפל בכל החלוקה.
+להוציא את כל המסמך כקטע יחיד. לאפשר ליחידת החלוקה
+(chunker) לטפל בכל החלוקה.
 
-- גישה פשוטה, נקודת התחלה טובה.
-- עשויה ליצור `TextDocument` גדול מאוד עבור קבצים גדולים, אך המחלק מטפל בכך.
-- הטוב ביותר כאשר אתה רוצה הקשר מרבי לכל סעיף.
+גישה פשוטה, קו בסיס טוב
+עלול לייצר מסמך טקסט גדול מאוד עבור קבצים גדולים, אך יחידת החלוקה
+  מטפלת בכך
+הטוב ביותר כאשר רוצים הקשר מקסימלי לכל קטע
 
 #### `heading`
 
-פיצול בכותרות (`Title`). כל סעיף הוא כותרת וכל התוכן עד לכותרת ברמה שווה או גבוהה יותר. כותרות מקוננות יוצרות סעיפים מקוננים.
+לחלק בנקודות כותרת (`Title`). כל קטע הוא כותרת וכל
+התוכן עד הכותרת הבאה באותו רמה או ברמה גבוהה יותר.
+כותרות מקוננות יוצרות קטעים מקוננים.
 
-- מייצר יחידות מגובשות מבחינה נושאית.
-- עובד היטב עבור מסמכים מובנים (דוחות, מדריכים, מפרטים).
-- נותן למחלץ ה-LLM הקשר של כותרת יחד עם התוכן.
-- חוזר ל-`whole-document` אם לא נמצאות כותרות.
+מייצר יחידות בעלות קוהרנטיות נושאית
+עובד היטב עבור מסמכים מובנים (דוחות, מדריכים, מפרטים)
+מספק למודל השפה הגדול (LLM) שמבצע חילוץ הקשר של כותרת יחד עם תוכן
+חוזר ל-`whole-document` אם לא נמצאות כותרות
 
 #### `element-type`
 
-פיצול כאשר סוג האלמנט משתנה באופן משמעותי — במיוחד, התחלה של סעיף חדש במעברים בין טקסט נרטיבי לטבלאות. אלמנטים עוקבים מאותה קטגוריה רחבה (טקסט, טקסט, טקסט או טבלה, טבלה) נשארים מקובצים.
+לחלק כאשר סוג האלמנט משתנה באופן משמעותי - ספציפית,
+להתחיל קטע חדש במעברים בין טקסט נרטיבי לטבלאות.
+אלמנטים עוקבים מאותה קטגוריה רחבה (טקסט, טקסט, טקסט או
+טבלה, טבלה) נשארים מקובצים.
 
-- שומר על טבלאות כסעיפים עצמאיים.
-- טוב למסמכים עם תוכן מעורב (דוחות עם טבלאות נתונים).
-- לטבלאות יש תשומת לב חילוץ ייעודית.
+שומר על טבלאות כקטעים עצמאיים
+טוב עבור מסמכים עם תוכן מעורב (דוחות עם טבלאות נתונים)
+לטבלאות ניתנת תשומת לב ייעודית לחילוץ
 
 #### `count`
 
-קיבוץ מספר קבוע של אלמנטים לכל סעיף. ניתן להגדרה באמצעות `--section-element-count` (ברירת מחדל: 20).
+לקבץ מספר קבוע של אלמנטים לכל קטע. ניתן להגדרה באמצעות
+`--section-element-count` (ברירת מחדל: 20).
 
-- פשוט וצפוי.
-- לא מכבד את מבנה המסמך.
-- שימושי כברירת מחדל או לניסויים.
+פשוט וצפוי
+אינו מכבד את מבנה המסמך
+שימושי כברירת מחדל או לניסויים
 
 #### `size`
 
-צבירת אלמנטים עד שמגיעים לגבול תווים, ואז התחלת סעיף חדש. מכבד את גבולות האלמנטים — לעולם לא מפצל באמצע אלמנט. ניתן להגדרה באמצעות `--section-max-size` (ברירת מחדל: 4000 תווים).
+צבירה של אלמנטים עד להגעה למגבלת תווים, ולאחר מכן התחלה של
+סעיף חדש. מכבד גבולות של אלמנטים - לעולם לא מפצל באמצע אלמנט.
+ניתן להגדיר באמצעות `--section-max-size` (ברירת מחדל: 4000 תווים).
 
-- מייצר גדלים בערך אחידים של סעיפים.
-- מכבד את גבולות האלמנטים (בניגוד למחלק במעלה הזרם).
-- פשרה טובה בין שליטה במבנה ובגודל.
-- אם אלמנט יחיד חורג מהגבול, הוא הופך לסעיף משלו.
+מייצר גדלי חלקים אחידים בערך.
+מכבד גבולות של אלמנטים (בניגוד למחלק החלקים הבא).
+פשרה טובה בין מבנה לשליטה בגודל.
+אם אלמנט בודד חורג מהמגבלה, הוא הופך לחלק בפני עצמו.
 
-#### אינטראקציה עם פורמטים מבוססי דפים
+#### פורמט מבוסס עמודים - אינטראקציה
 
-עבור פורמטים מבוססי דפים, הקיבוץ לפי עמוד תמיד מקבל עדיפות. אסטרטגיות סעיפים יכולות באופן אופציונלי להחיל *בתוך* עמוד אם הוא גדול מאוד (לדוגמה, עמוד PDF עם טבלה עצומה), דבר ששולט על ידי `--section-within-pages` (ברירת מחדל: false). כאשר זה כוזב, כל עמוד תמיד סעיף אחד ללא קשר לגודל.
+עבור פורמטים מבוססי עמודים, קיבוץ העמודים תמיד מקבל עדיפות.
+ניתן ליישם אסטרטגיות סעיפים באופן אופציונלי *בתוך* עמוד אם הוא גדול מאוד
+(לדוגמה, עמוד PDF עם טבלה עצומה), תוך שליטה באמצעות
+`--section-within-pages` (ברירת מחדל: false). כאשר הערך הוא false, כל עמוד הוא
+תמיד סעיף אחד ללא קשר לגודלו.
 
 ### זיהוי פורמט
 
-למפענח יש צורך לדעת את סוג MIME של המסמך כדי להעביר ל-`partition()` של `unstructured`. שתי אפשרויות:
+ה-דקודר צריך לדעת את סוג ה-mime של המסמך כדי להעביר ל-
+`unstructured`'s `partition()`. שני מסלולים:
 
-- **נתיב ספריית הניהול** (`document_id` מוגדר): אחסון מטא-דאטה של מסמך מהספרייה תחילה — זה נותן לנו את `kind` (סוג MIME) שנרשם בזמן ההעלאה. ואז אחסון תוכן מסמך. שתי קריאות לספריית הניהול, אך אחזור המטא-דאטה קל משקל.
-- **נתיב מקומי** (תאימות לאחור, `data` מוגדר): אין מטא-דאטה זמין על ההודעה. השתמש ב-`python-magic` כדי לזהות את הפורמט מתוך בתים של תוכן כגיבוי.
+**נתיב הספרן** (הגדרת `document_id`): אחזור מטא-דאטה של המסמך
+  מהספרן תחילה - זה נותן לנו את ה-`kind` (סוג ה-mime)
+  שנרשם בזמן ההעלאה. לאחר מכן, אחזור תוכן המסמך.
+  שני שימושים בספרן, אך אחזור המטא-דאטה קל משקל.
+**נתיב מקוון** (תאימות לאחור, הגדרת `data`): אין מטא-דאטה
+  זמין בהודעה. השתמש ב-`python-magic` כדי לזהות את הפורמט
+  מתוך בייטי התוכן כפתרון חלופי.
+
+אין צורך בשינויים בסכימה של `Document` - הספרן כבר מאחסן את סוג ה-mime.
 
-אין צורך בשינויים בסכימת `Document` — ספריית הניהול כבר מאחסנת את סוג ה-MIME.
 
 ### ארכיטקטורה
 
-שירות `universal-decoder` יחיד שמבצע את הפעולות הבאות:
+שירות `universal-decoder` יחיד שמבצע:
 
-1. מקבל הודעת `Document` (מקומית או באמצעות הפניה לספריית הניהול).
-2. אם נתיב ספריית הניהול: אחסון מטא-דאטה של מסמך (קבלת סוג MIME), ואז אחסון תוכן. אם נתיב מקומי: זיהוי פורמט מתוך בתים של תוכן.
-3. קריאה ל-`partition()` כדי לחלץ אלמנטים.
-4. קיבוץ אלמנטים: לפי עמוד עבור פורמטים מבוססי דפים, לפי אסטרטגיית סעיף מוגדרת עבור פורמטים שאינם מבוססי דפים.
-5. עבור כל עמוד/סעיף:
-   - יצירת ID `urn:page:{uuid}` או `urn:section:{uuid}`.
-   - הרכבת טקסט עמוד: טקסט רגיל, טבלאות כ-HTML, תמונות מושמטות.
-   - חישוב ההיסט מוחלט של כל אלמנט בתוך טקסט העמוד.
-   - שמירה בספריית הניהול כתיעוד משני.
-   - יצירת משולשים של תיעוד עם מטא-דאטה מיקומי.
-   - שליחת `TextDocument` במעלה הזרם לחלוקה.
+1. מקבל הודעה `Document` (בשורת הטקסט או דרך הפניה לספרייה).
+2. אם הנתיב הוא דרך הספרייה: שולף מטא-דאטה של המסמך (מקבל את סוג ה-mime), ואז
+   שולף את התוכן. אם הנתיב הוא בתוך הטקסט: מזהה את הפורמט מהבייטים של התוכן.
+3. קורא לפונקציה `partition()` כדי לחלץ אלמנטים.
+4. קיבוץ אלמנטים: לפי עמוד עבור פורמטים מבוססי עמוד, לפי אסטרטגיית סעיפים מוגדרת עבור פורמטים שאינם מבוססי עמוד.
+   סעיף.
+5. עבור כל עמוד/קטע:
+   מייצר מזהה `urn:page:{uuid}` או `urn:section:{uuid}`
+   מרכיב את תוכן העמוד: טקסט נרטיבי כטקסט רגיל, טבלאות כ-HTML,
+     תמונות מדלגות
+   מחשב את ההיסטים של כל תו בתוך הטקסט של העמוד.
+   שומר ל-librarian כמסמך משני.
+   משדר משולשי מוצא עם מטא-נתונים מיקומיים.
+   שולח `TextDocument` במורד הזרם לצורך חלוקה.
 6. עבור כל אלמנט תמונה:
-   - יצירת ID `urn:image:{uuid}`.
-   - שמירת נתוני תמונה בספריית הניהול כתיעוד משני.
-   - יצירת משולשים של תיעוד (מאוחסנים בלבד, אינם נשלחים במעלה הזרם).
+   מייצר מזהה `urn:image:{uuid}`.
+   שומר את נתוני התמונה ל-librarian כמסמך משני.
+   משדר משולשי מוצא (נשמרים בלבד, לא נשלחים במורד הזרם).
 
 ### טיפול בפורמטים
 
-| פורמט | סוג MIME | מבוסס עמוד | הערות |
-|---|---|---|---|
-| PDF | application/pdf | כן | קיבוץ לפי עמוד |
-| DOCX | application/vnd.openxmlformats... | לא | משתמש באסטרטגיית סעיף |
-| PPTX | application/vnd.openxmlformats... | כן | קיבוץ לפי שקופית |
-| XLSX/XLS | application/vnd.openxmlformats... | כן | קיבוץ לפי גיליון |
-| HTML | text/html | לא | משתמש באסטרטגיית סעיף |
-| Markdown | text/markdown | לא | משתמש באסטרטגיית סעיף |
-| רגיל | text/plain | לא | משתמש באסטרטגיית סעיף |
-| CSV | text/csv | לא | משתמש באסטרטגיית סעיף |
-| RST | text/x-rst | לא | משתמש באסטרטגיית סעיף |
-| RTF | application/rtf | לא | משתמש באסטרטגיית סעיף |
-| ODT | application/vnd.oasis... | לא | משתמש באסטרטגיית סעיף |
-| TSV | text/tab-separated-values | לא | משתמש באסטרטגיית סעיף |
+| פורמט   | סוג MIME                          | מבוסס דפים | הערות                          |
+|----------|------------------------------------|------------|--------------------------------|
+| PDF      | application/pdf                    | כן        | קיבוץ לפי דף              |
+| DOCX     | application/vnd.openxmlformats...  | לא         | משתמש באסטרטגיית סעיפים          |
+| PPTX     | application/vnd.openxmlformats...  | כן        | קיבוץ לפי שקופית             |
+| XLSX/XLS | application/vnd.openxmlformats...  | כן        | קיבוץ לפי גיליון             |
+| HTML     | text/html                          | לא         | משתמש באסטרטגיית סעיפים          |
+| Markdown | text/markdown                      | לא         | משתמש באסטרטגיית סעיפים          |
+| Plain    | text/plain                         | לא         | משתמש באסטרטגיית סעיפים          |
+| CSV      | text/csv                           | לא         | משתמש באסטרטגיית סעיפים          |
+| RST      | text/x-rst                         | לא         | משתמש באסטרטגיית סעיפים          |
+| RTF      | application/rtf                    | לא         | משתמש באסטרטגיית סעיפים          |
+| ODT      | application/vnd.oasis...           | לא         | משתמש באסטרטגיית סעיפים          |
+| TSV      | text/tab-separated-values          | לא         | משתמש באסטרטגיית סעיפים          |
 
-### מטא-דאטה של תיעוד
+### מטא-דאטה של מקור
 
-כל ישות עמוד/סעיף רושמת מטא-דאטה מיקומי כמשולשים של תיעוד בגרף `GRAPH_SOURCE`, ומאפשרת מעקב מלא מהמשולשים של גרף ידע חזרה למיקומי המסמך המקוריים.
+כל ישות דף/סעיף מתעדת מטא-דאטה מיקום כמשולשים של מקור
+ב-`GRAPH_SOURCE`, המאפשר מעקב מלא ממשולשים של גרף ידע
+חזרה למיקומי המסמך המקורי.
 
 #### שדות קיימים (כבר ב-`derived_entity_triples`)
 
-- `page_number` — מספר עמוד/גיליון/שקופית (מוגדר מ-1, רק עבור פורמטים מבוססי עמודים)
-- `char_offset` — היסט מוחלט של תווים של עמוד/סעיף זה בתוך הטקסט המלא של המסמך.
-- `char_length` — אורך התווים של הטקסט של עמוד/סעיף זה.
+`page_number` — מספר דף/גיליון/שקופית (מתחיל מ-1, רק עבור פורמטים מבוססי דפים)
+`char_offset` — ההיסט של התווים של דף/סעיף זה בתוך
+  הטקסט המלא של המסמך
+`char_length` — אורך התווים של הטקסט של דף/סעיף זה
 
-#### שדות חדשים (הרחבת `derived_entity_triples`)
+#### שדות חדשים (הרחבה של `derived_entity_triples`)
 
-- `mime_type` — פורמט מסמך מקורי (לדוגמה, `application/pdf`)
-- `element_types` — רשימה מופרדת בפסיקים של קטגוריות `unstructured` של אלמנטים (לדוגמה, `title, paragraph, table`).
-- `provenance` — מידע על מקור הנתונים.
+`mime_type` — פורמט המסמך המקורי (לדוגמה, `application/pdf`)
+`element_types` — רשימה מופרדת בפסיקים של קטגוריות `unstructured`
+  שנמצאו בדף/סעיף זה (לדוגמה, "כותרת,טקסט נרטיבי,טבלה")
+`table_count` — מספר הטבלאות בדף/סעיף זה
+`image_count` — מספר התמונות בדף/סעיף זה
+
+אלה דורשים טווח שמות של טריגרים חדשים:
+
+```
+TG_SECTION_TYPE  = "https://trustgraph.ai/ns/Section"
+TG_IMAGE_TYPE    = "https://trustgraph.ai/ns/Image"
+TG_ELEMENT_TYPES = "https://trustgraph.ai/ns/elementTypes"
+TG_TABLE_COUNT   = "https://trustgraph.ai/ns/tableCount"
+TG_IMAGE_COUNT   = "https://trustgraph.ai/ns/imageCount"
+```
+
+סכימת URN לתמונות: `urn:image:{uuid}`
+
+(`TG_MIME_TYPE` כבר קיים.)
+
+#### סוג ישות חדש
+
+עבור פורמטים שאינם דפי אינטרנט (DOCX, HTML, Markdown, וכו') שבהם
+ה-דקודר משדר את כל המסמך כיחידה אחת ולא מחלק אותו לדפים,
+הישות מקבלת סוג חדש:
+
+```
+TG_SECTION_TYPE = "https://trustgraph.ai/ns/Section"
+```
+
+זה מבחין בין חלקים לדפים בעת שאילתת מקור:
+
+| ישות | סוג | מתי משמש |
+|----------|-----------------------------|----------------------------------------|
+| מסמך | `tg:Document` | קובץ שהועלה במקור |
+| דף | `tg:Page` | פורמטים מבוססי דפים (PDF, PPTX, XLSX) |
+| חלק | `tg:Section` | פורמטים שאינם מבוססי דפים (DOCX, HTML, MD, וכו') |
+| תמונה | `tg:Image` | תמונות מוטמעות (מאוחסנות, לא מעובדות) |
+| מקטע | `tg:Chunk` | פלט של מפריד מקטעים |
+| תת-גרף | `tg:Subgraph` | פלט של חילוץ גרף ידע |
+
+הסוג נקבע על ידי ה-decoder בהתאם לשאלה האם הוא מקבץ לפי עמוד
+או פולט חלק שלם מהמסמך. `derived_entity_triples` מקבל
+פרמטר בוליאני אופציונלי `section` — כאשר הוא מוגדר כ-true, היישות היא
+הוקלד כ-`tg:Section` במקום `tg:Page`.
+
+#### שרשרת מקור מלאה
+
+```
+KG triple
+  → subgraph (extraction provenance)
+    → chunk (char_offset, char_length within page)
+      → page/section (page_number, char_offset, char_length within doc, mime_type, element_types)
+        → document (original file in librarian)
+```
+
+כל קישור הוא קבוצה של שלשות בגרף המכונה `GRAPH_SOURCE`.
+
+### תצורת שירות
+
+ארגומנטים של שורת הפקודה:
+
+```
+--strategy              Partitioning strategy: auto, hi_res, fast (default: auto)
+--languages             Comma-separated OCR language codes (default: eng)
+--section-strategy      Section grouping: whole-document, heading, element-type,
+                        count, size (default: whole-document)
+--section-element-count Elements per section for 'count' strategy (default: 20)
+--section-max-size      Max chars per section for 'size' strategy (default: 4000)
+--section-within-pages  Apply section strategy within pages too (default: false)
+```
+
+בנוסף ל-`FlowProcessor` הסטנדרטי ולטיעוני תור המאפשרים גישה לספרייה.
+
+### אינטגרציה של זרימת העבודה
+
+ה-דקודר האוניברסלי תופס את אותו מיקום בזרימת העיבוד
+כמו ה-דקודר של PDF הנוכחי:
+
+```
+Document → [universal-decoder] → TextDocument → [chunker] → Chunk → ...
+```
+
+זה רושם:
+`input` צרכן (סכימת מסמכים)
+`output` מפיק (סכימת TextDocument)
+`triples` מפיק (סכימת Triples)
+בקשה/תגובה של ספרן (לשליפה ואחסון של מסמכים משניים)
+
+### פריסה
+
+קונטיינר חדש: `trustgraph-flow-universal-decoder`
+תלות: `unstructured[all-docs]` (כולל PDF, DOCX, PPTX, וכו')
+ניתן להפעיל לצד או להחליף את מפענח ה-PDF הקיים, בהתאם
+  לתצורת זרימת העבודה
+מפענח ה-PDF הקיים נשאר זמין עבור סביבות שבהן
+  התלויות של `unstructured` כבדות מדי
+
+### מה משתנה
+
+| רכיב | שינוי |
+|------------------------------|-------------------------------------------------|
+| `provenance/namespaces.py`   | הוספת `TG_SECTION_TYPE`, `TG_IMAGE_TYPE`, `TG_ELEMENT_TYPES`, `TG_TABLE_COUNT`, `TG_IMAGE_COUNT` |
+| `provenance/triples.py`      | הוספת ארגומנטים `mime_type`, `element_types`, `table_count`, `image_count` (kwargs) |
+| `provenance/__init__.py`     | ייצוא קבועים חדשים |
+| חדש: `decoding/universal/`   | מודול שירות פענוח חדש |
+| `setup.cfg` / `pyproject`    | הוספת תלות `unstructured[all-docs]` |
+| Docker                       | תמונת קונטיינר חדשה |
+| הגדרות זרימה | חיבור universal-decoder כקלט מסמך |
+
+### מה שלא משתנה
+
+Chunker (מקבל TextDocument, פועל כרגיל)
+מודולים לחילוץ מידע (מקבלים Chunk, ללא שינוי)
+Librarian (מאחסן מסמכים משניים, ללא שינוי)
+Schema (Document, TextDocument, Chunk ללא שינוי)
+מקור מידע בזמן שאילתה (ללא שינוי)
+
+## סיכונים
+
+ל-`unstructured[all-docs]` יש תלות רבה (poppler, tesseract,
+  libreoffice עבור פורמטים מסוימים). תמונת המכולה תהיה גדולה יותר.
+  פתרון אפשרי: להציע גרסה של `[light]` ללא תלות ב-OCR/office.
+פורמטים מסוימים עשויים לייצר חילוץ טקסט באיכות ירודה (קבצי PDF מסרוקים ללא
+  OCR, פריסות מורכבות של קבצי XLSX). אמצעי מניעה: פרמטר הניתן להגדרה `strategy`.
+  ומפענח ה-OCR של Mistral הקיים זמין
+  עבור OCR באיכות גבוהה של קבצי PDF.
+עדכוני גרסה של `unstructured` עשויים לשנות מטא-נתונים של אלמנטים.
+  אמצעי מניעה: קביעת גרסה, בדיקת איכות החילוץ עבור כל פורמט.