Skip to content

Latest commit

 

History

History
257 lines (209 loc) · 21.1 KB

CLAUDE.md

File metadata and controls

257 lines (209 loc) · 21.1 KB

otzaria-library — מה באמת נכנס לשחרור

מוסיפים ספר חדש? קראו קודם את ADDING_BOOKS.md — רשימת המלכודות שנשברות בשקט (ספר הערות נלווה, פורמט שלושת המרשמים, הוולידטורים שקוראים git ולא את עץ העבודה).

מאגר זה מכיל הרבה יותר קבצים ממה שמגיע למשתמשים. לפני כל בדיקה או תיקון של מיקום ספר, שם ספר או קישורים — ודאו קודם שהקובץ שאתם נוגעים בו הוא זה שנארז. עותקים מקבילים באותו שם קיימים כמעט תמיד, ורובם לא נארזים.

נכסי השחרור

הכל נבנה ב־.github/workflows/update-library.yml (job package, מצב links_sync_mode):

נכס נבנה על ידי מה בפנים
otzaria_latest.zip create_release_archives.sh → manual_links_packaging.py package הספרייה עצמה: מיזוג BOOK_ROOTS לעץ אחד בשם אוצריא/, links/, files_manifest.json, metadata.json, manual_links_sync.json, manual_links_lineage.json, packaging_toolchain.json
otzaria_dicta_latest.zip create_auxiliary_archives.sh DictaToOtzaria/לא ערוך/ספרים בלבד (חומר גלם, לא הספרייה)
talmud_bavli_latest.tar.zst create_auxiliary_archives.sh קובצי ה־PDF שתחת MoreBooks/ספרים/אוצריא/תלמוד בבלי, משוטחים
fordb_latest.zip .github/workflows/update-fordb.yml תיקיית ForDB/ (ה־CSV־ים)

הספרים: BOOK_ROOTS

מוגדר ב־manual_links_packaging.py:34-50. כל שורש מועתק אל תוך אותו עץ יעד אוצריא/, לפי הסדר, עם overwrite=True — שורש מאוחר יותר דורס קובץ באותו נתיב יחסי:

Ben-YehudaToOtzaria/ספרים/אוצריא
DictaToOtzaria/ערוך/ספרים/אוצריא
OnYourWayToOtzaria/ספרים/אוצריא
OraytaToOtzaria/ספרים/אוצריא
tashmaToOtzaria/ספרים/אוצריא
sefariaToOtzaria/sefaria_export/ספרים/אוצריא
sefariaToOtzaria/sefaria_api/ספרים/אוצריא
MoreBooks/ספרים/אוצריא
KSK/ספרים/אוצריא
wikiJewishBooksToOtzaria/ספרים/אוצריא
wikisourceToOtzaria/ספרים/אוצריא
ToratEmetToOtzaria/ספרים/אוצריא
pninimToOtzaria/ספרים/אוצריא
National-LibraryToOtzaria/ספרים/אוצריא
yam-HaHachmaToOtzaria/ספרים/אוצריא
BeitAharonVeYisraelToOtzaria/ספרים/אוצריא

אותה רשימה משוכפלת כ־PACKAGED_PREFIXES ב־validate_fordb_book_names.py:186 (שם היא כוללת גם את DictaToOtzaria/לא ערוך/, שנכנס רק ל־zip הדיקטה). אם משנים אחת — צריך לעדכן את השנייה.

יש עוד עותק בשלב ה־prepare: folders + mapping ב־sync_and_merge_folders.py (SourcesBooks.csv). מקור שחסר שם נארז כרגיל, אבל ספריו לא מופיעים ב־SourcesBooks.csv. test_source_lists_contract.py אוכף שהרשימה שווה ל־BOOK_ROOTS, חוץ משני שורשי ספריא הריקים.

מה לא נארז

  • MoreBooks/ספרים/ שאינו תחת אוצריא/
  • תבנית Word וכלי תיקון שכבת הטקסט של PDF עברו ל־book-sources; קובצי הספרים נשארים כאן
  • כל <source>/ספרים/<משהו שאינו אוצריא>/ — למשל OraytaToOtzaria/ספרים/לא רלוונטי/
  • DictaToOtzaria/לא ערוך/ — נכנס רק ל־otzaria_dicta_latest.zip, לא לספרייה
  • BeitAharonVeYisraelToOtzaria/ספרים/בהמתנה/ — ספרים ממתינים של מכון בית אהרן וישראל (לא רשומים במטא־דאטה)
  • כלי עבודה: linker/, linker-eval/, metadata/. הסקריפטים של סקריפטים שונות/ עברו ל־book-sources; נשארו בה רק הודעות העברה

הקישורים: links_roots

מוגדר ב־manual_links_sync.json (links_roots), עם expected_state של present/absent לכל שורש — סטייה מהמצב המוצהר מפילה את האריזה. קבצים שטוחים בלבד: תת־תיקייה מתחת לשורש links היא שגיאה קשה. כל הקבצים ממוזגים לתיקייה links/ אחת ב־zip, וללא דריסה (התנגשות = שגיאה).

איפה מתקנים מיקום של ספר

תלוי במקור הספר (עמודת source ב־seforim.db):

  • ספר של המאגר הזה (Dicta / MoreBooks / OnYourWay / Orayta / ToratEmet / pninim / Ben-Yehuda / wikisource / tashma / wikiJewishBooks / National-Library / yam-HaHachma / KSK / BeitAharonVeYisrael): הקטגוריה נגזרת מנתיב התיקייה הפיזי בתוך BOOK_ROOTS. מזיזים את הקובץ ב־git. ForDB/book_moves.csv לא מיועד לספרים אלה.
  • ספר של ספריא (source.name='Sefaria'): אין קובץ מקומי, הוא נוצר בזמן הבנייה מה־API. מזיזים רק דרך ForDB/book_moves.csv. הצרכן הוא SeforimLibrary/generator/sefariasqlite/.../RenameCategoriesPostProcess.kt; ההתאמה מדויקת בבתים (שימו לב לגרשיים ״ U+05F4 מול ").

עץ ספריא שצריך להתמזג עם תיקיית אוצריא בשם אחר (למשל «מילונים וספרי יעץ» של ספריא עם «ספרות עזר» של אוצריא, שהפכו לשתי תיקיות «דקדוק», «אנציקלופדיות» ו«מילונים» נפרדות): מספיק כלל שינוי שם אחד על הקטגוריה העליונה ב־ForDB/category_renames.csv (מילונים וספרי יעץ,ספרות עזר). renameCategories רץ לפני שלב אוצריא, ושלב אוצריא מכניס תיקייה לקטגוריה קיימת באותו שם (Generator.findExistingCategory), ולכן גם תתי־הקטגוריות מתמזגות לבדן. לא מוסיפים כלל לכל תת־קטגוריה: category_moves.csv אינו ממזג, וכלל שינוי שם מתאים לפי כותרת בכל העץ. שורות sefaria_category_changes.csv עוברות לנתיב החדש, שורה אחת לכל נתיב (SeedAllMetadata נכשל על נתיב שנעלם ועל נתיב כפול), ו־validate_fordb_book_names.py נכשל על נתיב בשם הישן.

איפה מתקנים שם של מחבר

author.name הוא המפתח הייחודי — שתי צורות כתיב של אותו אדם הן שני מחברים, ומאז שנוסף חיפוש לפי מחבר זה אומר שחצי מספריו לא נמצאים. התיקון תלוי במקור:

  • ספר של המאגר הזה: השם מגיע משדה author (או authors[]) ב־metadata.json שבשורש המאגר — לא מ־heAuthors ב־ForDB/all_metadata.json, שאינו נצרך בבניית טבלת המחברים. עורכים את metadata.json; את all_metadata.json מעדכנים במקביל רק לשם עקביות — אבל לא רק לשם עקביות: קיים נוהג של סנכרון ידני heAuthors → metadata.json (ר' a5a627d6, יולי 2026), שמסיר תארי כבוד בדרך. סנכרון כזה בעתיד יוריד את ה־"רבי" מ־רבי יעקב בן יעקב משה לורברבוים מליסא ויפצל אותו שוב מצד ספריא, ששם ה־CSV כן שומר אותו. לפני סנכרון כזה — לבדוק מול ForDB/sefaria_author_changes.csv.
  • ספר של ספריא: השם מגיע מה־schema של ספריא, ואי אפשר לערוך אותו כאן. מוסיפים שורה ל־ForDB/sefaria_author_changes.csv (שם בספריא,שם קנוני), שנצרך ב־SefariaDirectImporter בזמן הייבוא — לפני ש־upsertAuthor מקצה מזהה, כדי שלא ייווצרו שתי שורות שצריך למזג אחר כך.

ניקוד, טעמים, תווי BIDI בלתי־נראים ורווחים כפולים אינם צריכים שורה ב־CSV: normalizeAuthorName ב־SeforimLibrary מסיר אותם משני הצדדים. גרשיים וגרש נשמרים. ה־CSV שמור למקרים שרק אדם יכול להכריע בהם — ושם צריך זהירות: אברהם שמואל בנימין סופר ו־סופר, שמעון בן אברהם שמואל בנימין דומים הרבה יותר זה לזה מאשר שתי הצורות של יעקב מליסא, והם אב ובן.

ערכים נעולים

חלק מהערכים תוקנו ונבדקו ביד; הם רשומים ב־.github/data/locked_metadata.tsv: author ב־metadata.json, שורה 2 בקובץ הספר, שם קנוני ב־ForDB/sefaria_author_changes.csv, heShortDesc ו־heDescNew ב־ForDB/sefaria_metadata_changes.csv. ערך נעול קודם לכל סנכרון גורף — heAuthors → metadata.json, הרצה ידנית של sefaria-export, המרה חוזרת או שינוי מפתח בספריא. .github/scripts/check_locked_metadata.py רץ ב־validate-fordb-book-names.yml ונכשל כשערך נעול השתנה או כשהמפתח שלו נעלם (ספר שנמחק, שורת CSV שנמחקה), ו־update-fordb.yml לא מפרסם ForDB שערך נעול בו נדרס. שינוי מכוון: מעדכנים את השורה באותו קומיט — python3 .github/scripts/update_locked_metadata.py --key KIND:KEY, או --all-changed-vs origin/main --add-new לכל מה שהענף שינה (מול נקודת הפיצול, לא מול קצה main) — או עורכים אותה ביד. PR של עורך הקטלוג (Bshlomecha) נושא את עדכון הנעילה בקומיט משלו, «עדכון קובץ הנעילה לערכים החדשים». שינוי שם של ספר שה־CI מיישר (fordb_book_renames.py) והעברה/שינוי שם של קובץ בלי שינוי תוכן (git R100) — שורות הנעילה עוברות לבד ב־push ל־main (follow_lock_renames.py). ב־CI שורה 2 נקראת מ־git: כל נתיב נעול חייב להתקיים, והתוכן מושווה בספרים שהשתנו מאז הריצה המוצלחת האחרונה; בדיקה מלאה של כל הספרים — הרצה מקומית בלי --git-rev. בספרי ממירים שורה 2 נשמרת גם ב־post_convert_fixes.tsv של המקור.

באנר והגנה לספר

שני קבצי חובה ב־ForDB/, שהמחולל ב־SeforimLibrary הופך לטבלאות banner, book_banner ו־book_protection ב־seforim.db. קובץ חסר מפיל את הבנייה (ואת שער ה־ForDB): הגנה שנעלמת בשקט גרועה מבנייה שנכשלת. אין שורות = כותרת בלבד. CSV לפי RFC-4180 ב־UTF-8, עם שורת כותרת:

קובץ כותרת ערך
book_banners.csv id,sourceName,bookName,text טקסט הבאנר שמעל תחילת הספר. ירידת שורה = שורה חדשה בתוך שדה במירכאות. הסימון היחיד: קישור [תווית](url), ו־{title} מוחלף בשם הספר (באפליקציה)
book_protection.csv sourceName,bookName,level 1 = בלי ייצוא לעריכה והגבלת העתקה; 2 = גם בלי ייצוא PDF והגבלת הדפסה

sourceName הוא שם תיקיית המקור העליונה (KSK, National-LibraryToOtzaria), כמו source.name ב־DB. bookName ריק = ברירת מחדל לכל ספרי המקור; שורה עם bookName גוברת עליה. bookName הוא שם הספר הסופי ב־DB: איות book.title של שם קובץ ה־.txt, אחרי book_renames.csv.

id בבאנר הוא מספר קבוע (1 ומעלה) שהטקסט נשמר תחתיו ב־DB פעם אחת: ספרים עם אותו נוסח חולקים id, ושורות עם אותו id חייבות לשאת אותו טקסט בדיוק (אחרת המחולל והבדיקה נכשלים). שינוי נוסח נשאר באותו id — בכל השורות שלו — ונוסח חדש מקבל מספר שלא היה בשימוש. לא ממספרים מחדש ולא ממחזרים מספר של נוסח שנמחק.

זכויות יוצרים וקרדיט נכתבים כאן ולא בקובץ הספר (.claude/skills/otzaria-book-format/references/book-file.md, "זכויות יוצרים וקרדיט"). בספר קיים מוחקים את שורת הזכויות ומורידים באחת את מספרי השורות שאחריה בכל הקישורים (של הספר ואליו).

validate_fordb_book_names.py בודק כל שורה מול ספרי אותו מקור: בהגנה שורה שלא נמצאה מפילה את הבדיקה (וגם המחולל נכשל), בבאנר היא רק אזהרה. sourceName שאינו מקור במאגר הזה הוא רק אזהרה, כי מקור ממאגר פרטי מצטרף רק בזמן הבנייה (והמחולל נכשל על מקור שלא נמצא). שינוי שם של קובץ ספר מתעדכן בשני הקבצים אוטומטית, רק בשורות של אותו מקור.

הערות על X עשוי להישאר ספר עצמאי ב־DB: המחולל ממזג קובץ הערות (גם הערות על חברותא…) רק כשהקישורים מלאים והתוכן בטוח למיזוג. בדיקת השמות המוקדמת אינה מסיקה מיזוג מהכותרת. seedBookNotices מתאים את השורות לספרים ב־DB הסופי, אחרי המיזוג ושינויי השמות: שורת הגנה ללא ספר מפילה את הבנייה, ושורת באנר ללא ספר היא אזהרה. אם קובץ ההערות מוזג, יש להפנות את השורה לספר הבסיס בפועל; ההגנה עליו חלה גם על ההערות שבתוכו.

ספרים ממאגר פרטי: saga-continue.yml מעביר ל־manual-generate-release את משתני המאגר PRIVATE_BOOKS_REPO, PRIVATE_BOOKS_TAG ו־PRIVATE_BOOKS_ASSET_SHA256 (כולם או אף אחד). הם נקראים בזמן שלב S1 ואינם מקובעים ב־saga-state, כך שהרצה חוזרת של S1 לוקחת את ערכיהם העדכניים.

קודש וחול בשמות שבתנ"ך

ForDB/divine_name_overrides.csv (חובה; קובץ חסר מפיל את הבנייה ואת שער ה־ForDB) הוא רשימת פסוקים שהמחולל ב־SeforimLibrary (buildLineDivineNameIndex) משתמש בה לטבלה line_divine_name. היא חלה רק על שורות ספרי הבסיס של התנ"ך. CSV לפי RFC-4180 ב־UTF-8, עם הכותרת ref,kind,decision,source,note:

עמודה ערך
ref <שם ספר בתנ"ך> פרק:פסוק, טווח פרק:פסוק-פסוק או פרק:פסוק-פרק:פסוק (שופטים 17:1-18:31). שם הספר כמו ב־DB (שמואל א, דברי הימים ב)
kind ADNUT, EL, ELOAH, ELOHIM, EHYEH, SHADDAI, TZEVAOT, או * = כל הסוגים. HVYH ו־YAH לא נקבעים ברשימה
decision profane = חול, גובר על כל כלל. sacred = קודש, לפסוק אחד ולסוג אחד, וגובר על טווח profane (בראשית 19:18 בתוך פרשת לוט)
source המקור ההלכתי; מותר ריק
note חובה. כל שורה ממתינה לאישור רבני, וההערה אומרת זאת

שורה אחת שהמחולל אינו מבין גורמת לו להתעלם מהרשימה כולה, ואז בתנ"ך מסומן כקודש רק שם הוי"ה. לכן validate_fordb_book_names.py בודק כל שורה כמו המחולל ונכשל על כל בעיה. פסוק שאינו קיים ב־DB נבדק רק במחולל, כאזהרה. שמות ספרי התנ"ך אינם שמות קבצים, ולכן הקובץ אינו משתתף במעקב שינויי השם.

שינוי שם של קובץ ספר קיים

שם ספר אוצריא ב־DB הוא שם הקובץ, ולכן שינוי שם מנתק אותו מכל שורה שמזהה אותו לפי שם. ב־push ל־main ה־CI (validate-fordb-book-names.yml, fordb_book_renames.py) עוקב אחרי זה בעצמו: לכל קובץ .txt נארז ששונה בשמו מאז הריצה המוצלחת האחרונה, הוא מחליף את השם הישן בחדש ב־book_info.csv (כל השורות של הספר), book_moves.csv, commentator_collective_titles.csv, sefaria_metadata_changes.csv, book_banners.csv ו־book_protection.csv (רק באותו מקור), ForDB/all_metadata.json, metadata.json, all_metadata_with_file_paths.json, ובשורשי ה־links הנארזים (שם קובץ ה־_links.json, path_2, ו־heRef_2 כשהוא מתחיל בשם). שינוי שמשנה רק גרשיים (הבח → הב”ח) מתוקן באיות ה־DB.

מה הוא לא עושה: פיצול ספר לכמה קבצים, או הוצאה מהספרייה (לריפו הפרטי extra_books), אינם שינוי שם, ולכן השורות נמחקות כיתומות כמו קודם. שם ישן שהוביל לשני יעדים, שמופיע ב־book_renames.csv, או שקובץ הקישורים החדש שלו כבר קיים, אינו מיושר וגם אינו נמחק, והריצה נכשלת. הקישורים האוטומטיים אינם שמורים במאגר: הם נוצרים מחדש ב־LinkerToOtzaria בכל בנייה (תיקיות linker_links/ הישנות נמחקו בספטמבר 2026, ואין לבדוק או לשחזר אותן).

תיקון ידני של שגיאה שבמקור עצמו

שגיאת הקלדה או סריקה שנמצאת במקור חוזרת בכל המרה מחדש. מלבד התיקון בספר, מוסיפים שורה ל־<מקור>/post_convert_fixes.tsv (ספר, טקסט שגוי עם הקשר ייחודי, טקסט מתוקן, הערה). הממירים של המקורות במאגר מחילים את הקובץ דרך post_convert_fixes.py על כל ספר שהם כותבים, ונעצרים כשעוגן חסר או כפול. בדיקה מול הספרים שבמאגר: python post_convert_fixes.py --check <מקור>.

בדיקה מהירה: עץ הזיפ מול ה־DB הבנוי

הקטגוריה שמופיעה באפליקציה נקבעת ב־SeforimLibrary, לא כאן. כשמדווחים על ספר "במקום הלא נכון", בדקו את שניהם — הנתיב במאגר יכול להיות תקין וה־DB עדיין שגוי:

python3 - <<'PY'
import sqlite3, os
db = os.path.expanduser('~/Downloads/seforim.db')   # DB בנוי כלשהו
c = sqlite3.connect(db)
cats = {r[0]: (r[1], r[2]) for r in c.execute("select id,parentId,title from category")}
def path(cid):
    p = []
    while cid:
        par, t = cats[cid]; p.append(t); cid = par
    return "/".join(reversed(p))
for t, cid, s in c.execute(
        "select b.title,b.categoryId,s.name from book b left join source s on s.id=b.sourceId "
        "where b.title like ? order by b.title", ('%אור הישר%',)):
    print(f"{t}\t| {path(cid)}\t| {s}")
PY

תקלה ידועה: ספרים שנופלים לקטגוריה זרה לגמרי

ב־db_version=19 (אוגוסט 2026) 26 ספרים נחתו בתיקיות לא קשורות — למשל אור הישר על נדה תחת מחשבת ישראל/אחרונים/רמחל, אור הישר/סדר נזיקין תחת מורה נבוכים, אור הישר/מסכתות קטנות תחת תנא דבי אליהו, ושני ספרי אודות התוכנה תחת שות מהרשם. קובצי המקור כאן היו תקינים.

הסיבה: התיקיות שנוצרות אוטומטית עבור יעדי book_moves.csv נכתבות עם rowid משתמע, בעוד שלב אוצריא מקצה מזהי קטגוריה מ־InMemoryIdAllocator מתמיד. מאחר ש־ renameCategories רץ כעת לפני appendOtzaria, התיקיות החדשות חטפו את המזהים השמורים, וה־INSERT OR IGNORE של שלב אוצריא נבלע בשקט — בעוד הספרים עדיין נכתבו עם אותו categoryId. תוקן ב־SeforimLibrary (ensureCounterAtLeast(CATEGORY, …) ב־GenerateLines.kt + אימות־אחרי־הכנסה ב־IdAllocatorBindings.upsertCategory). הסימן המזהה: הקטגוריה ה"נכונה" פשוט לא קיימת ב־DB, והמזהה שלה תפוס בידי תיקייה שנוצרה מ־book_moves.csv.