# Tau-RAG Hebrew Legal — Runbook

מסמך ייחוס ל-RAG העברי על חוק ופסיקה ישראלית.

## 12 שכבות תיקון — מצב סופי

| # | שכבה | מה | קובץ |
|---|---|---|---|
| 1 | Ingest | סינון chunks קצרים (<120 תווים, <30% non-ws) | `pipeline.py` |
| 2 | Ingest | whitespace normalize + min-doc filter ב-JSONL | `loaders/jsonl.py` |
| 3 | Ingest | per-page normalize + drop empty pages ב-PDF | `loaders/pdf.py` |
| 4 | Data | 64 סעיפים של חוק החוזים | `runtime/uploads/heb_contract_law.jsonl` |
| 5 | Data | Heavy markers על 15 סעיפים יסודיים + enriched key_terms | JSONL |
| 6 | Retrieve | Hebrew-aware filter ב-BM25 (לפי metadata.language) | `retrieve/bm25.py` |
| 7 | Retrieve | Language filter post-fusion (כל ה-retrievers) | `pipeline.py` |
| 8 | Query | Dynamic query rewrite: "סעיף N" → +topic+key_terms מ-metadata | `pipeline.py` |
| 9 | Ingest | Cache invalidation + metadata update-in-place | `pipeline.py` |
| 10 | Data | 14 ערכים משלימים: חוק המכר/שכירות/אחידים + 5 הלכות יסוד | `runtime/uploads/heb_law_supplement.jsonl` |
| 11 | Data | **50,000 פסקי דין של העליון + metadata מלא** (שופטים, תאריכים, צדדים) | `runtime/uploads/heb_caselaw_supreme.jsonl` |
| 12 | Query | **Auto-injection של citation filter** — "בג"ץ 5856/03" → filter אוטומטי | `pipeline.py` |

## מבנה הקורפוס

```
50,156 מסמכים עבריים מוזרמים:
├── 64 סעיפי חוק החוזים (כללי + תרופות)       → heb_contract_law.jsonl
├── 14 חוקים משלימים + 5 הלכות יסוד           → heb_law_supplement.jsonl
└── 50,000 פסקי דין של העליון (91% עם metadata) → heb_caselaw_supreme.jsonl
```

## הפעלה

```bash
cd /Users/avrahambarzel/Library/Mobile\ Documents/com~apple~CloudDocs/TAU_API/photoelectric-real/backend/tau_platform_v4

# קילוי bytecode (חובה אחרי כל עריכת קוד)
find tau_rag -name "__pycache__" -type d -exec rm -rf {} + 2>/dev/null

# התחלה נקייה
pkill -9 -f "uvicorn.*tau_rag" ; sleep 3
TAU_RAG_PRESET=hebrew_legal_prod uvicorn tau_rag.api.fastapi_app:app \
    --port 8000 --workers 1 &
sleep 5

# אפלוד שלושת הקבצים
for f in heb_contract_law heb_law_supplement heb_caselaw_supreme; do
    curl -X POST http://127.0.0.1:8000/v1/data/upload \
        -F "file=@tau_rag/runtime/uploads/${f}.jsonl"
done
```

## דוגמאות שאילתה

### חקיקה
```bash
# "מה אומר סעיף 39?"  — auto-rewrite מוסיף "תום לב קיום בתום לב..."
curl -X POST http://127.0.0.1:8000/v1/query -H "Content-Type: application/json" \
    -d '{"query":"מה אומר סעיף 39 לחוק החוזים?","top_k":3}'
```

### פסיקה לפי citation — Auto-Filter
```bash
# השרת מזהה "בג"ץ 5856/03" ומזריק filters={"citation":"בג\"ץ 5856/03"} אוטומטית
curl -X POST http://127.0.0.1:8000/v1/query -H "Content-Type: application/json" \
    -d '{"query":"בג\"ץ 5856/03","top_k":3}'

# גם ניסוח טבעי עובד
curl -X POST http://127.0.0.1:8000/v1/query -H "Content-Type: application/json" \
    -d '{"query":"מה נאמר בבג\"ץ 5856/03?","top_k":3}'
```

### פסיקה לפי נושא/שופט
```bash
curl -X POST http://127.0.0.1:8000/v1/query -H "Content-Type: application/json" \
    -d '{"query":"השופטת דורנר תום לב","top_k":3}'
```

### פילטרים ידניים (אם רוצים לעקוף auto-detect)
```bash
# רק פסיקה של העליון
curl -X POST http://127.0.0.1:8000/v1/query -H "Content-Type: application/json" \
    -d '{"query":"חובת תום לב","filters":{"court":"בית המשפט העליון"},"top_k":5}'

# רק עברית (יעוקף אוטומטית, אבל אפשר להכריח)
curl -X POST http://127.0.0.1:8000/v1/query -H "Content-Type: application/json" \
    -d '{"query":"good faith","filters":{"language":"he"},"top_k":5}'
```

## הוספת סעיפים חדשים

1. ערוך את `heb_contract_law.jsonl` או קובץ חדש.
2. מבנה:
   ```json
   {
     "id": "heb_law/<law>/<section_name>",
     "text": "[<LAW>§N] [סעיף N] [סעיףN] <text>",
     "metadata": {
       "law": "...", "section": "N",
       "topic": "<נושא לבוסטינג בquery rewrite>",
       "language": "he", "verbatim": true,
       "key_terms": ["<מילת מפתח ייחודית>", "..."]
     }
   }
   ```
3. אפלוד → ה-pipeline יעדכן את ה-metadata בזיכרון אוטומטית.

## הוספת פסיקה חדשה

יש סקריפט ב-`/tmp` שבונה JSONL מ-parquet. ל-rebuild/expand:
- `rag/chunks.parquet` — 537K chunks כבר מוכנים
- `data/cases_all.parquet` — metadata (שופטים, תאריכים) ל-90K תיקים
- מיפוי לפי citation → שלב אוטומטי
- `TARGET = 50000` — ניתן להגדיל עד 200K+

## פתרון התנגשות בין שני סעיפים

ערוך `key_terms` בקובץ ה-JSONL — הוסף מילים ייחודיות לסעיף שאתה רוצה להבליט. אפלוד → עובד מיד (ללא שינוי קוד).

## פריטי תחזוקה

- **אמת את ה-verbatim**: 15 מתוך 64 סעיפי חוק החוזים מסומנים `"verbatim": false`. אמת מול נבו/אתר הכנסת לפני שימוש משפטי.
- **פסיקה**: הטקסט מ-`rag/chunks.parquet` איכותי יותר מ-`698f9b2b`, אבל עדיין עם סלסולי HTML. לניקוי נוסף — צריך להבחין סעיפים (עובדות/דיון/מסקנה).
- **Dense retriever עברי**: הקונפיג מגדיר `onlplab/alephbert-base`. הרץ `pip install sentence-transformers` כדי להפעילו — ישפר את האחזור על שאילתות עם פרפרזות.

## Auto-safety Layers

- ה-chunk filter דוחה הכל → לוג `_last_ingest_dropped`.
- ה-language filter מסנן הכל → fallback לרשימה לא מסוננת.
- Query rewrite עטוף ב-try/except — כשל לא מפיל את השאילתה.
- Citation auto-filter: פועל רק כש-`query.filters` ריק, ולא חופף לפילטר שהמשתמש שלח.

## סקריפטים לעבודה עתידית

- `scripts/test_hebrew_rag.sh` — regression test, 15 בדיקות, exit 0/1 ל-CI.
- אפשר להריץ אחרי כל שינוי קוד/דאטה.

## הפניות לקוד

- `Pipeline._chunk_is_usable` — סינון chunks
- `Pipeline._run_impl` — pipeline ראשי עם query rewrite + language filter + citation auto-filter
- `BM25Retriever.search` — retrieval עם Hebrew auto-filter + metadata filter
- `tau_rag/runtime/uploads/*.jsonl` — שלושת קבצי הדאטה

---

_הסשן המקורי: מעבר מ-`"in good faith."` (14 תווים של פסולת) ל-§39 לחוק החוזים + 50,000 פסקי דין של העליון עם auto-citation-detection._