legal-ai/scripts/SCRIPTS.md

scripts/ — מדריך סקריפטים

כלל: כל עדכון, יצירה, או מחיקה של סקריפט בתיקייה זו מחייב עדכון של קובץ זה.

---

סקריפטים פעילים

Script	Type	Purpose	Scheduled
pc.sh	bash	wrapper לכל קריאות Paperclip API מסוכנים — מוסיף Authorization, X-Paperclip-Run-Id (audit trail), Content-Type, base URL. תחביר: pc.sh <METHOD> <PATH> [BODY_JSON]. אסור curl ישיר ל-$PAPERCLIP_API_URL. ראה HEARTBEAT.md §0. counterpart ב-Python: web/paperclip_api.py.	נקרא ע"י סוכנים
sync_missing_agent_skills.py	python	סקריפט "אל-כשל" להוספת paperclipSkillSync ל-הגהת מסמכים ו-מנתח משפטי שפיספסו את ה-sync ההיסטורי (Gap #28). תומך --verify/--dry-run/--apply. גיבוי אוטומטי ל-agents-pre-skill-sync-*.sql. דורש PAPERCLIP_BOARD_API_KEY (Infisical /paperclip ב-nautilus env). idempotent.	חד-פעמי (בוצע 2026-05-04). שמור לרפרנס
sync_agents_across_companies.py	python	סנכרון סוכנים מ-CMP (1xxx, master) ל-CMPA (8xxx, mirror) — Gap #25. משווה adapter_config (model/timeout/instructions/skills/etc), runtime_config (heartbeat), ושדות top-level (budget/metadata/icon/title/role). מסנן אוטומטית local skills שלא קיימים ב-mirror. לוגיקת subset (mirror יכול להחזיק יותר skills כי ה-API מוסיף required runtime skills). תומך --verify/--dry-run/--apply [--only NAME]. גיבוי אוטומטי. דורש PAPERCLIP_BOARD_API_KEY. להריץ אחרי כל שינוי הגדרות ב-CMP. ⚠ אם adapter_type שונה בין CMP ל-CMPA — --apply מדלג על הסוכן; --verify מדווח אותו רם כ-DRIFT. בעת מעבר adapter (למשל ל-deepseek_local) חובה לעדכן ידנית בשתי החברות. --verify יוצא exit≠0 על כל drift (needs-sync / adapter-mismatch / missing-in-mirror) — שמיש כ-gate ל-cron/CI (GAP-21/FU-8a).	ידני אחרי כל שינוי
fix_paperclipai_skills_drift.py	python	סקריפט חד-פעמי (בוצע 2026-05-04) שניקה drift על paperclipai/* skills בין CMP ל-CMPA. הסיר paperclip-dev מכל 14 הסוכנים, ודאג ש-paperclip-converting-plans-to-tasks קיים רק על CEO ו-analyst. תומך --apply (ברירת מחדל: dry-run). דורש PAPERCLIP_BOARD_API_KEY. נשמר לרפרנס למקרה שhdrift חוזר.	חד-פעמי (בוצע)
test_retrieval_by_name.py	python	בדיקת אחזור-לפי-שם (#52/RC-A) — מאמת שsearch_precedent_library/search_internal_decisions מדרגים את ההחלטה עצמה (אגסי) מעל מי שמצטט אותה, + רגרסיות לשאילתות מהותיות. הרצה: DOTENV_PATH=/home/chaim/.env DATA_DIR=.../data mcp-server/.venv/bin/python scripts/test_retrieval_by_name.py (exit 0 = עבר).	ידני אחרי שינוי שכבת חיפוש
fu2b_reconcile_internal_case_numbers.py	python	FU-2b (GAP-07/08) — תיאום case_number של internal_committee מציטוט-מלא למספר-בסיס קנוני (X1: trim·prefix-strip·/→-, חודש נשמר). דטרמיניסטי (token יחיד; 0/>1 → flag). --dry-run (ברירת-מחדל) מפיק טבלת-תיאום ל-data/audit/fu2b-reconciliation-*.{csv,md} עם flags (DUP_CHECK / PROC_MISMATCH / MISMATCH). --apply --approved <csv> מגבה ואז מעדכן רק שורות שאושרו ע"י היו"ר. scope: internal בלבד (external → #68). FK-safe.	חד-פעמי, chair-gated (apply רק אחרי אישור דפנה)
fu2c_reconcile_external_case_numbers.py	python	FU-2c (GAP-08, #68) — תיאום case_number של פסיקה חיצונית (source_kind <> internal_committee) מציטוט-מלא לצורה קנונית מציין-הליך + docket (החלטת-יו"ר 2026-05-31, Option A: / נשמר, לא -; תואם db.py:369 ו-INV-ID2). דטרמיניסטי (designator+docket; 0/>1 docket → flag). --dry-run (ברירת-מחדל) מפיק data/audit/fu2c-reconciliation-*.{csv,md} עם flags (MISMATCH / NO_CITATION / CIT_NO_DOCKET / DESIG_MISMATCH / DUP_CHECK). --apply --approved <csv> מגבה ואז מעדכן שורות לא-חוסמות (כולל ADVISORY/NO_CITATION). --overrides <csv> (id,proposed_canonical,reason) פותח שורות-חוסמות בהכרעת-יו"ר מפורשת (למשל פס"ד מאוחד — ראה data/audit/fu2c-overrides.csv לרשומת לויתן/קלמנוביץ). לוגיקת-החילוץ + פיצול flags אומתו offline על 24 רשומות. scope: external בלבד (internal = FU-2b). FK-safe.	חד-פעמי, chair-gated (apply רק אחרי אישור דפנה)
eval_gold_bootstrap.py	python	FU-5 (GAP-11) — bootstrap ל-gold-set של הערכת-אחזור ל-data/eval/gold-set.jsonl. שני מקורות: --source citations (cited==relevant מ-search_relevance_feedback; ריק עד שייצברו ציטוטים) ו---source known_item (query=שם-תיק → relevant=עצמו; אות אמיתי היום). Idempotent — שומר שורות source=chair, מחדש bootstrap_*. דורש POSTGRES.	לפני eval; חוזר כשנצבר ground-truth
eval_retrieval.py	python	FU-5 (GAP-11, INV-RET4/G8) — harness הערכת-אחזור — מריץ את מסלול-האחזור בייצור (search_library/search_internal) על ה-gold-set, מחשב precision@k/recall@k/MRR/nDCG@k (k=5,10), מצרף overall+per-corpus+per-PA ל-data/eval/eval-report-<ts>.{json,md} + delta מול data/eval/baseline.json (מתעד retrieval_config). --self-test בודק את המטריקות offline; --update-baseline מאמץ snapshot. שער-CI במשמעת: הרץ לפני/אחרי כל שינוי בשכבת-האחזור באותו קונפיג. דורש POSTGRES+VOYAGE_API_KEY.	לפני/אחרי שינוי RRF/k/embedder/rerank
auto-sync-cases.sh	bash	סנכרון תיקי ערר ל-Gitea — רץ כל דקה	* * * * * (cron)
backup-db.sh	bash	גיבוי PostgreSQL יומי ל-data/backups/ (gzip)	לתזמן: 0 2 * * *
restore-db.sh	bash	שחזור DB מגיבוי (companion ל-backup-db.sh)	ידני
notify.py	python	שליחת מייל התראה מסוכנים via SMTP (Gmail)	נקרא ע"י סוכנים
bidi_table.py	python	יצירת טבלאות box-drawing עם תמיכה ב-BiDi (עברית+אנגלית)	ספריית עזר
convert_decision_template.py	python	המרת data/training/טיוטת החלטה.dotx → skills/docx/decision_template.docx לטעינה ב-python-docx	להריץ כשמתעדכנת התבנית
deploy-track-changes.sh	bash	סנכרון skills CMP↔CMPA + בדיקות + הנחיות deploy לארכיטקטורת Track Changes	ידני
retrofit_case.py	python	retrofit רטרואקטיבי — מזריק bookmarks לקובץ קיים של תיק ספציפי ומגדיר אותו כ-active_draft	ידני (חד-פעמי לתיק)
reembed_voyage.py	python	Re-embed כל הוקטורים ב-DB עם המודל ב-VOYAGE_MODEL (לאחר שינוי מודל). 5 טבלאות, 1024 דמ', batches של 100. ראה docs/voyage-upgrades-plan.md	ידני (אחרי החלפת VOYAGE_MODEL)
voyage_context3_poc.py	python	POC #1 — voyage-3 vs voyage-context-3 על פסיקה אחת קצרה (קלמנוביץ, 63 chunks). הכרעה: context-3 לא מציג שיפור עקבי	בנצ'מרק חד-פעמי, נשמר לרפרנס
voyage_context3_poc_long.py	python	POC #2 — voyage-context-3 על פסיקה ארוכה (אהרון ברק 219 chunks) עם sliding windows. הכרעה: context-3 לא משתפר על פסיקה גדולה	בנצ'מרק חד-פעמי, נשמר לרפרנס
voyage_multimodal_poc.py	python	POC #3 — voyage-multimodal-3 על דוח שמאי (89 עמודים). הכרעה: שיפור משמעותי לטבלאות + 22 עמודי image-only שhttp text-OCR מאבד	בנצ'מרק חד-פעמי, מוכן לשלב C
voyage_rerank_judge_poc.py	python	POC #4 — voyage-3 vs rerank-2 vs context-3 על אהרון ברק, 18 שאילתות, claude-haiku-4-5 כ-judge. הכרעה: rerank-2 ניצח עם +9% mean@3	בנצ'מרק חד-פעמי
voyage_rerank_corpus_poc.py	python	POC #5 — voyage-3 vs rerank-2 על קורפוס מלא (785 docs). הכרעה: +4.5% mean@3 כללי, +11.6% על P queries (practical)	בנצ'מרק חד-פעמי, אישר את שלב B
multimodal_backfill.py	python	Backfill voyage-multimodal-3 page embeddings על מסמכי תיקים קיימים. idempotent (skips by default), forces MULTIMODAL_ENABLED=true ל-run, רץ מהקונטיינר. שלב C — ראה docs/voyage-upgrades-plan.md	ידני per-case (python multimodal_backfill.py 8174-24 8137-24)
backfill_chunk_pages.py	python	Backfill page_number ב-document_chunks קיימים. legacy chunker לא tracked עמודים → page_number=NULL חוסם boost של multimodal hybrid (text+image join על אותו עמוד). re-extracts כל PDF (re-OCR אם צריך, ~$0.0015/page), מחשב page_offsets, ומעדכן chunks. idempotent	ידני per-case (python backfill_chunk_pages.py 8174-24 8137-24)
rechunk_legacy_precedents.py	python	#57 — re-chunk + re-embed פסיקה שהוטמעה לפני תיקון ה-chunker (#55). בוחר כל case_law עם chunk זעיר (length(trim(content))<50 — טביעת-האצבע של ה-chunker הישן) ומריץ ingest.reindex_case_law (re-chunk+re-embed מ-full_text שמור בלבד — ללא re-OCR/LLM, feedback_no_reocr_retrofit; idempotent DELETE-then-INSERT). idempotent ברמת-הבאטץ' (שואב מחדש את הסט המושפע בכל ריצה). דגל --limit N. רץ עם venv של mcp-server (cd mcp-server && .venv/bin/python ../scripts/rechunk_legacy_precedents.py)	חד-פעמי — מיגרציית-נתונים של פסיקה legacy (תוקן 2026-06-03)
audit_corpus_integrity.py	python	בדיקה תקופתית של עקביות הקורפוס — 3 בדיקות SQL read-only על case_law ו-cases: (A) external_upload עם prefix פנימי ערר/בל"מ; (B) internal_committee חסר chair_name/district; (C) cases.practice_area מחוץ ל-{rishuy_uvniya, betterment_levy, compensation_197, ''}. כותב log מצטבר ל-data/logs/corpus_integrity_audit.log ובמצב הפרות שולח wakeup ל-CEO ב-Paperclip (best-effort, רק אם PAPERCLIP_API_URL+PAPERCLIP_API_KEY מוגדרים). דגל: --no-notify. Idempotent, יוצא 0. Cron יומי 07:00: 0 7 * * * /home/chaim/legal-ai/mcp-server/.venv/bin/python /home/chaim/legal-ai/scripts/audit_corpus_integrity.py	0 7 * * * (cron)
backfill_legal_arguments.py	python	Backfill legal_arguments לתיקים עם claims קיימים (TaskMaster #36). מקבץ פרופוזיציות גולמיות לטיעונים משפטיים מובחנים (~6-12 לכל צד) דרך argument_aggregator.aggregate_claims_to_arguments (Claude CLI). תומך --dry-run/--apply/--force/--case <num>.... חייב לרוץ מהמכונה המקומית (לא קונטיינר) — claude_session דורש Claude CLI	ידני per-case (python scripts/backfill_legal_arguments.py --apply --case 1017-03-26)
upload_blam_decisions.py	python	חד-פעמי (2026-05-26) — העלאת 2 החלטות בל"מ ל-case_law (8126/24 סופר נוח, 8047/23 הרנון) דרך ingest_internal_decision ישיר, עוקף MCP server שטרם נטען מחדש אחרי הוספת proceeding_type. לא להריץ שוב	חד-פעמי — להעביר ל-.archive/ בהזדמנות
process_pending_blam.py	python	חד-פעמי (2026-05-26) — הרצת metadata + halacha extraction על 2 החלטות בל"מ שעלו ב-upload_blam_decisions.py. עוקף MCP (אותו טעם). לא להריץ שוב	חד-פעמי — להעביר ל-.archive/ בהזדמנות
ab_halacha_opus48.py	python	A/B לא-הרסני לחילוץ הלכות — מריץ מחדש חילוץ הלכות על פסק-דין בודד דרך מודל/effort נבחרים (AB_MODEL/AB_EFFORT, ברירת-מחדל claude-opus-4-8/xhigh) ומשווה לסטטיסטיקות ההלכות הקיימות ב-DB בלי למחוק/לכתוב כלום. משכפל את halacha_extractor.extract() (אותם פרומפטים, בחירת-צ'אנקים, אימות-ציטוט) ומחליף רק את קריאת ה-LLM ב-claude -p --model --effort. מפיק data/ab_halacha_<case>_<effort>.json. הרצה: DOTENV_PATH=/home/chaim/.env DATA_DIR=.../data .venv/bin/python scripts/ab_halacha_opus48.py <case_law_id>. ממצא 2026-05-31 (שטיין 1128-08-20): Opus 4.8@xhigh חילץ 51 מול 124 בייצור (100% quote-verified מול 96%) אך ביטחון מכויל-נמוך יותר (חציון 0.75 מול 0.82) — ולכן לא מקטין את תור-האישור-הידני תחת sweep אוטו-אישור conf≥0.78 (26 מול 24). שיפור איכות, לא צמצום-תור.	ידני (החלטת מודל-חילוץ)
compute_ndcg.py	python	חישוב nDCG@10 על search_relevance_feedback (TaskMaster #50, Stage C). aggregation לפי search_type ולפי שבוע, כולל top-cited case_law ו-coverage %. דגלים: --k 10, --weeks 12, --pretty. read-only, פלט JSON. משמש גם את GET /api/admin/rag-metrics (מיובא inline) — שינוי חתימה ב-compute() ישבור את ה-endpoint	ידני / cron עתידי לדיווח שבועי
backfill_multimodal_precedents.py	python	Backfill voyage-multimodal-3 page embeddings על רשומות case_law (external_upload + internal_committee) שחסרות precedent_image_embeddings. בונה אינדקס קבצים מ-data/precedent-library/ ו-data/internal-decisions/, מנסה התאמה לפי tokens של מספרי תיק (כולל parts-match לפורמטים שונים של Nevo doc-id). מדלג על רשומות בלי קובץ-מקור או עם MD בלבד (PyMuPDF לא מרנדר MD). תומך --dry-run (default) / --apply / --only external_upload|internal_committee / --limit N. רץ בקונטיינר (יש /data + Voyage env). הופעל 2026-05-26: 70 חסרים → 26 backfilled (503 pages, ~$0.21 voyage tokens), 44 אין-קובץ-מקור. ניתן להריץ שוב אחרי שיועלו עוד PDF/DOCX לספרייה	ידני
monitor_halacha_quality.py	python	מנטר איכות חילוץ הלכות. בודק drift של avg(confidence) בין baseline היסטורי לחלון אחרון. מחזיר JSON מטריקות + alert ב-stderr אם drift > threshold (ברירת מחדל 5%). 2 סדרות: trusted (approved+published) ו-all_extracted. תומך --window N / --threshold X / --min-sample N / --silent / --exit-on-alert. רץ ב-container או מקומית עם mcp-server/.venv (אין תלות ב-LLM, רק SQL). תזמון מומלץ: 0 8 * * 1 (יום ראשון 08:00, שבועי)	0 8 * * 1 (לתזמן)
audit_training_corpus.py	python	audit של style_corpus — לכל החלטה: שדות מטא-דאטה מאוכלסים (summary/outcome/key_principles/appeal_subtype/subject_categories), קישור ל-documents (FK + chunks + embeddings). מפיק data/audit/corpus-YYYY-MM-DD.json + summary בקונסול. דרוש POSTGRES_URL או POSTGRES_*. אין תלויות חיצוניות מלבד asyncpg. רץ מהמכונה המקומית (לא קונטיינר) — חיבור ישיר ל-Postgres :5433	ידני / קדם-עבודה לפני enrichment של מטא-דאטה

תיקיית .archive/ — סקריפטים שהושלמו

סקריפטים חד-פעמיים שהפונקציונליות שלהם הוטמעה ב-MCP server או ב-API. נשמרים ב-git לצורך היסטוריה — אין להריץ אותם.

Script	Original Purpose	Superseded By
backfill_pattern_frequency.py	עדכון תדירות דפוסי סגנון ב-DB	web/app.py::_extract_pattern_variants()
batch_upload_training.py	העלאת קורפוס אימון (16 קבצים)	Web UI: /api/training/upload
benchmark_embeddings.py	השוואת מודלי embeddings (voyage-3 vs voyage-4)	הושלם — voyage-3-large נבחר
benchmark_new_vs_old.py	השוואת Google Vision vs markdown קיים	הושלם — בדיקה חד-פעמית לתיק 1130-25
decompose-decisions.py	פירוק החלטות סופיות ל-12 בלוקים	MCP: write_block(), write_all_blocks()
export-decision-docx.py	ייצוא החלטה ל-DOCX	MCP: export_docx()
extract-citations.py	חילוץ ציטוטי פסיקה מבלוק י	MCP service: references_extractor.py
extract-claims.py	חילוץ טענות מבלוק ז	MCP: extract_claims() + claims_extractor.py
extract_claims_8174.py	חד-פעמי — חילוץ טענות חסרות לתיק 8174-24 אחרי timeout של האנליסט (43 טענות עורר נוספו 30/04/26)	phase 1: claude_session async + 30min timeout + chunking סמנטי
extract_all_google_vision.py	OCR בכמות עם Google Vision	MCP: document_upload() pipeline
extract_originals.py	חילוץ טקסט מ-PDF עם Claude Opus	MCP service: extractor.py
extract_originals_ocr.py	חילוץ OCR מלא מ-PDF	MCP service: extractor.py
generate-embeddings.py	יצירת embeddings לבלוקים ופסיקה	אוטומטי — נוצרים עם יצירת בלוקים
link-claims-to-discussion.py	קישור טענות לפסקאות דיון	MCP service: qa_validator.py
proofread_training_corpus.py	ניקוי Nevo מ-DOCX/PDF ל-Markdown	MCP service: proofreader.py + Web UI
seed-appeals.py	seeding תיקי ערר ראשוניים ל-DB	MCP: case_create()
seed-knowledge.py	seeding לקחים, ביטויי מעבר, פסיקה	MCP: record_chair_feedback(), precedent_attach()
validate-decision.py	ולידציה מול block-schema	MCP: validate_decision() + qa_validator.py
run_curator_deepseek_test.sh	A/B test #1 (2026-05-05) — Hermes Curator על CMP-78 דרך DeepSeek V4-Pro ב-provider:custom, ללא interaction. תוצאה: 6:33 דק׳, 5 ממצאי סגנון/לקסיקון, פי 3 מהיר מ-Sonnet baseline (CMP-80) ופי ~20 זול. הסקריפט נקודתי לתיק 1130-25 — לא להריץ שוב	החלפת Curator לאדפטר DeepSeek מקומי (בתהליך)
run_curator_deepseek_test_v2.sh	A/B test #2 (2026-05-05) — אותו run אבל עם interaction. תוצאה: 9:08 דק׳, 5 ממצאים, היחיד מ-4 הריצות שזיהה תוצאה עובדתית נכונה (קבלה חלקית). interaction נכשל ב-API ("Agent run id required" בריצה ידנית).	החלפת Curator לאדפטר DeepSeek מקומי
run_curator_sonnet_rerun.sh	A/B test #3 (2026-05-05) — ריצה חוזרת של Sonnet 4.5 על אותו CMP-78. תוצאה: 12:52 דק׳ (לעומת 20:13 בריצה המקורית — כי בלי לולאת interaction.json). זיהה תוצאה שגויה ("דחייה") בעקביות עם הריצה המקורית — Sonnet עקבי-בטעות, DeepSeek אקראי.	בדיקה חד-פעמית — לא להריץ שוב

סקריפטים שנמחקו (git history בלבד)

Script	Reason
import-final-decisions.py	מיגרציה הושלמה — כל ההחלטות ב-data/training/
compare_extractions.py	בדיקה חד-פעמית לתיק 1130-25
decompose-decisions-v2.py	כפילות של v1
extract_google_vision.py	hardcoded לתיק בודד
extract_google_vision_single.py	wrapper חד-פעמי
test-search.py	סקריפט דיבאג