ezer-mishpati/legal-ai
1
0
Fork 0
Code Issues Pull Requests 2 Actions Packages Projects Releases Wiki Activity

Add Paperclip agent activity mirror to case detail page
All checks were successful
Build & Deploy / build-and-deploy (push) Successful in 3m16s
Details

Browse Source 
New "Agents" tab in case detail shows all Paperclip agent comments,
issue status, and agent status for each case — eliminating the need
to switch between Legal-AI and Paperclip UIs.

Backend: 4 new DB query functions in paperclip_client.py (issues,
comments, agents, post_comment) + 2 new API endpoints (GET/POST
/api/cases/{case_number}/agents). Comment posting uses Board API
with DB+wakeup fallback to ensure CEO routing.

Frontend: agents.ts hooks (10s polling), AgentActivityFeed component
(markdown timeline + comment input), AgentStatusWidget (sidebar),
4th tab in case detail page.

Also includes new-company-setup-guide.md documenting the process
for setting up the betterment levy (CMPA) company.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
This commit is contained in:
Chaim
2026-04-15 10:44:42 +00:00
parent 2e2d2d42b6
commit 1e4c5c1518
7 changed files with 1051 additions and 1 deletions
Download Patch File Download Diff File Expand all files Collapse all files

403
docs/new-company-setup-guide.md Normal file
View File

@@ -0,0 +1,403 @@
# מדריך הקמת חברה חדשה — היטלי השבחה (CMPA)
> נוצר: 2026-04-15
> מטרה: תיעוד מפורט של התהליך להקמת קורפוס אימון והגדרת חברה בשתי המערכות
---
## רקע
המערכת שלנו בנויה מ-**2 חברות** (boards) ב-Paperclip, שמייצגות את שני תחומי העבודה העיקריים:
| # | חברה | קוד | Prefix | סוגי תיקים | סטטוס קורפוס |
|---|-------|------|--------|------------|---------------|
| 1 | רישוי ובנייה | CMP | `42a7acd0...` | 1xxx | 24 החלטות אימון, ניתוח סגנון מלא |
| 2 | היטלי השבחה + פיצויים | CMPA | `8639e837...` | 8xxx, 9xxx | **ריק — אין אף החלטת אימון** |
**המצב היום**: חברת CMPA כבר קיימת ב-Paperclip ומופתה בקוד (ניתוב אוטומטי לפי מספר תיק). אבל אין לה **קורפוס אימון** — המערכת לא מכירה את הסגנון של דפנה בהחלטות היטל השבחה ולא יכולה לחפש תקדימים.
**מה שצריך לעשות**: להעלות את ההחלטות, לעבד אותן, ולהריץ ניתוח סגנון — בדיוק כמו שנעשה עם 24 ההחלטות של רישוי ובנייה.
---
## שתי המערכות — הגדרת תפקידים
### מערכת 1: עוזר משפטי (Legal-AI)
**תפקיד**: מערכת הידע, הניתוח והניסוח — מחזיקה את כל התוכן המשפטי ומספקת כלים לכתיבת החלטות.
**מה חי רק במערכת הזו**:
| רכיב | תיאור | טבלת DB |
|-------|--------|---------|
| תיקים (Cases) | מספר תיק, כותרת, סטטוס, צדדים | `cases` |
| מסמכי מקור | כתבי ערר, תגובות, פרוטוקולים (PDF/DOCX) | `documents` + filesystem |
| חלקים סמנטיים (Chunks) | embeddings לחיפוש RAG (Voyage AI, 1024 ממדים) | `document_chunks` + pgvector |
| קורפוס אימון | החלטות קודמות של דפנה — גרסאות מנוקות | `style_corpus` |
| דפוסי סגנון | ביטויי מעבר, נוסחאות פתיחה/סיום, מבנה ניתוח | `style_patterns` |
| בלוקי החלטה | 12 בלוקים (מבנה ההחלטה) + פסקאות | `decision_blocks`, `decision_paragraphs` |
| טענות צדדים | טענות שחולצו מכתבי טענות | `claims` |
| תקדימים (פסיקה) | ספריית case law + embeddings | `case_law`, `case_law_embeddings` |
| חקיקה | סעיפי חוק שאוזכרו | `statutory_provisions` |
| הערות יו"ר | feedback של דפנה על טיוטות | `chair_feedback` |
| לקחים | תובנות שחולצו מ-feedback | `lessons_learned` |
| צ'קליסטים | רשימות בדיקה לבלוק דיון (לפי סוג ערר) | hardcoded ב-`lessons.py` |
| מיפוי חברות | קישור appeal_subtype ← company_id | `tag_company_mappings` |
**שירותי הליבה**:
- **RAG** — חיפוש סמנטי בתקדימים ובמסמכי מקור, מסונן לפי `appeal_subtype`
- **Proofreading** — ניקוי מסמכי נבו מ-artifacts
- **Style Analysis** — ניתוח קורפוס וחילוץ דפוסי כתיבה
- **Decision Drafting** — ייצור טיוטות לפי ארכיטקטורת 12 בלוקים
- **DOCX Export** — מסמך מעוצב מוכן להגשה
---
### מערכת 2: Paperclip
**תפקיד**: מערכת התזמור והסוכנים — מנהלת את תהליך העבודה, מפעילה סוכני AI, ומספקת ממשק Kanban.
**מה חי רק במערכת הזו**:
| רכיב | תיאור | טבלת DB |
|-------|--------|---------|
| חברות (Companies) | CMP (רישוי), CMPA (היטלי השבחה) — boards נפרדים | `companies` |
| פרויקטים | כרטיס Kanban לכל תיק | `projects` |
| Issues | משימות עבודה (CMP-123, CMPA-456) | `issues` |
| תגובות | דיון בין סוכנים ומשתמשים | `issue_comments` |
| סוכנים (Agents) | CEO, Researcher, Writer — Claude Code agents | מערכת agents |
| SOUL.md | הנחיות לכל סוכן | קונפיגורציית agent |
| Skills | workflows לשימוש חוזר (SKILL.md) | `company_skills` + filesystem |
| Plugin state | נתוני plugin (case_number ← issue) | `plugin_state` |
**תפקידי הליבה**:
- **תזמור** — CEO agent מקבל בקשות, מנתב לסוכן המתאים
- **ניהול משימות** — Kanban board עם issues, מעקב סטטוס
- **הפעלת סוכנים** — wakeup mechanism, heartbeat cycle
- **ממשק דיון** — comments על issues (משתמש ← agent ← agent)
---
### תהליכי גומלין — מי מדבר עם מי
```
┌──────────────────────────────────────────────────────────────────────────┐
│ תהליכי גומלין │
│ │
│ LEGAL-AI PAPERCLIP │
│ ════════ ═════════ │
│ │
│ ┌─────────┐ יצירת project+issue ┌─────────┐ │
│ │ Cases │ ─────── DB insert ──────→ │Projects │ │
│ │ │ ─────── DB insert ──────→ │ Issues │ │
│ └─────────┘ └─────────┘ │
│ │
│ ┌─────────┐ wakeup signal ┌─────────┐ │
│ │Workflow │ ─────── HTTP POST ───────→ │ CEO │ │
│ │ Start │ (issueId + mutation) │ Agent │ │
│ └─────────┘ └─────────┘ │
│ │
│ ┌─────────┐ קריאת case_number ┌─────────┐ │
│ │ Data │ ←──── plugin_state ────── │ Plugin │ │
│ │ (API) │ ←──── HTTP GET/POST ───── │legal-ai │ │
│ └─────────┘ (תקדימים, טענות, סגנון) └─────────┘ │
│ │
│ ┌─────────┐ skill sync ┌─────────┐ │
│ │ Skills │ ──── DB + filesystem ────→ │company_ │ │
│ │ (disk) │ │ skills │ │
│ └─────────┘ └─────────┘ │
│ │
│ ┌─────────┐ שאילתת חברות ┌─────────┐ │
│ │Settings │ ←──── DB query ────────── │companies│ │
│ │ UI │ │ table │ │
│ └─────────┘ └─────────┘ │
└──────────────────────────────────────────────────────────────────────────┘
```
#### כיוון 1: Legal-AI → Paperclip (יצירה ושליטה)
| פעולה | מנגנון | מתי |
|-------|--------|-----|
| יצירת Project | DB insert ישיר ב-Paperclip | יצירת תיק חדש |
| יצירת Issue | DB insert ישיר ב-Paperclip | יצירת תיק / התחלת workflow |
| קישור case ← issue | DB insert ב-`plugin_state` | יצירת project |
| הערת אימות | DB insert ב-`issue_comments` | אחרי יצירת project |
| הפעלת CEO | **HTTP POST** ל-`/api/agents/{id}/wakeup` | התחלת workflow |
| סנכרון skill | DB insert/update ב-`company_skills` | התקנת/עדכון skill |
#### כיוון 2: Paperclip → Legal-AI (שאילתות וקריאות חזרה)
| פעולה | מנגנון | מתי |
|-------|--------|-----|
| קריאת case_number | plugin קורא `plugin_state` | סוכן מקבל issue |
| שליפת מסמכים | HTTP GET/POST ל-API של legal-ai | סוכן עובד על תיק |
| חיפוש תקדימים | HTTP ל-`/api/precedents/search` | researcher מחפש |
| קריאת style guide | HTTP ל-MCP / API | writer כותב טיוטה |
| רשימת חברות | DB query ישיר מ-`companies` | UI הגדרות |
#### החוליה המקשרת: `plugin_state`
```
plugin_state:
plugin_id = "53461b5a..." (marcusgroup.legal-ai)
scope_kind = "issue"
scope_id = "{issue-uuid}"
state_key = "legal-case-number"
value_json = "\"1234\""
```
זו ה"כתובת" שמאפשרת לסוכן Paperclip לדעת איזה תיק ב-Legal-AI שייך ל-issue שהוא עובד עליו.
---
### מצב קיים לכל חברה
#### CMP — רישוי ובנייה (מוכן לעבודה)
**ב-Legal-AI**:
- 24 החלטות אימון בקורפוס
- ניתוח סגנון מלא (דפוסים, ביטויים, יחסי אורך)
- content checklists ל-3 סוגי משנה (substantive, threshold, property)
- RAG פעיל עם chunks + embeddings
**ב-Paperclip**:
- חברה CMP פעילה
- סוכנים מוגדרים ופעילים
- Plugin פעיל
- Skills מותקנים
#### CMPA — היטלי השבחה (דורש הקמה)
**ב-Legal-AI**:
- appeal_subtype `betterment_levy` מוגדר בקוד
- ניתוב אוטומטי (8xxx → CMPA) עובד
- **חסר**: 0 החלטות אימון, 0 style patterns, 0 chunks, אין content checklist
**ב-Paperclip**:
- חברה CMPA קיימת
- **לוודא**: סוכנים מקושרים, plugin פעיל, skills מותקנים
---
## התהליך המלא — צעד אחר צעד
### שלב 1: הכנת הקבצים
**מיקום**: הנח את כל קבצי ה-DOCX בתיקייה נגישה (למשל `~/Downloads/hitlei-hashbacha/`)
**בדיקות מקדימות**:
1. וודא שכל הקבצים בפורמט DOCX או PDF
2. וודא שהשמות כוללים מספר תיק (לצורך metadata)
3. ספור כמה החלטות יש — זה ישפיע על זמן העיבוד
**דגשים**:
- ההחלטות מגיעות מנבו — יש להן watermarks, headers, footnotes שצריך לנקות
- מערכת ה-proofreading שלנו מטפלת בזה אוטומטית
---
### שלב 2: העלאה — 3 נתיבים אפשריים
#### נתיב א: ממשק Web (מומלץ להעלאה המונית)
```
כתובת: https://legal-ai.nautilus.marcusgroup.org
נתיב: /api/training/upload
```
**מה קורה מאחורי הקלעים**:
1. הקובץ נשמר כ-temp file
2. **Proofreading** — ניקוי אוטומטי של תוספות נבו:
- הסרת watermarks ("ספרות:", "חקיקה שאוזכרה:")
- הסרת headers/footers של עמודים
- הסרת קודי נבו inline
- הסרת URLs וזכויות יוצרים
3. **שמירת גרסה מנוקה** → `data/training/proofread/{filename}.md`
4. **שמירת מקור** → `data/training/{filename}.docx`
5. **הוספה ל-DB** → טבלת `style_corpus` עם metadata
6. **חיתוך לחלקים** → chunks סמנטיים
7. **יצירת embeddings** → Voyage AI → וקטורים 1024 ממדים
8. **שמירה ב-RAG** → טבלת `document_chunks` (עם practice_area + appeal_subtype)
#### נתיב ב: MCP Tool (מ-Claude Code)
```
tool: document_upload_training
params:
file_path: "/path/to/file.docx"
decision_number: "ARAR-24-8001"
decision_date: "2024-06-15"
subject_categories: ["היטל השבחה"]
title: "שם ההחלטה"
practice_area: "appeals_committee"
appeal_subtype: "betterment_levy"
```
#### נתיב ג: Skill Command (אינטראקטיבי)
```
/upload-training
```
עונים על שאלות: נתיב קובץ, מספר החלטה, תאריך, קטגוריות.
---
### שלב 3: ביקורת (Proofreading QA)
**קריטי**: לפני שממשיכים לניתוח — **לבדוק כל החלטה שהועלתה**.
**מה לבדוק**:
- [ ] הטקסט המנוקה (`data/training/proofread/`) קריא ושלם
- [ ] לא נחתכו חלקים מהותיים
- [ ] ה-metadata נכון (מספר תיק, תאריך, קטגוריה)
- [ ] אין שאריות של artifacts מנבו
- [ ] appeal_subtype = `betterment_levy` (ולא `building_permit`)
**כלי בדיקה**:
```
GET /api/training/status — סטטוס העלאה ועיבוד
```
---
### שלב 4: ניתוח סגנון (Style Analysis)
אחרי שכל ההחלטות הועלו ונבדקו, מריצים ניתוח סגנון:
```
POST /api/training/analyze-style
```
**מה קורה**:
1. שליפת כל ההחלטות מ-`style_corpus` (לפי practice_area/subtype)
2. בדיקת תקציב tokens:
- עד 900K tokens → pass יחיד (הכל ל-Claude בבת אחת)
- מעל 900K → multi-pass (כל החלטה בנפרד + סינתזה)
3. **חילוץ דפוסים** באמצעות Claude:
- נוסחאות פתיחה
- ביטויי מעבר
- סגנון ציטוט פסיקה
- מבנה ניתוח
- נוסחאות סיום
- ביטויים אופייניים
- זרימת טיעון
- טיפול בראיות
4. שמירה בטבלת `style_patterns` עם תדירות, הקשר, ודוגמאות
**תוצר**: מדריך סגנון מבוסס-נתונים ספציפי להיטלי השבחה.
---
### שלב 5: ניתוח קורפוס (Corpus Analysis)
בדומה ל-`docs/corpus-analysis.md` שנבנה עבור רישוי ובנייה, צריך ליצור ניתוח מקביל:
**מה לנתח**:
- הרכב הקורפוס: כמה החלטות, תוצאות (קבלה/דחייה/חלקית)
- אורך פרק דיון טיפוסי
- נושאים ייחודיים להיטלי השבחה:
- שומות (שומה מוסכמת, שומה אחרת, שמאי מכריע)
- תכנית משביחה — זיהוי, פרשנות
- מועד השבחה / "מועד אישור התכנית"
- חישוב עליית ערך (לפני/אחרי)
- פטורים (ס' 19 לתוספת השלישית)
- שיעור היטל
- דיני ראיות שמאיים
- ביטויי מעבר ייחודיים
- סגנון דיון — "קר ומקצועי" (לפי CLAUDE.md)
- השוואה לרישוי ובנייה (מה שונה)
**תוצר**: מסמך `docs/corpus-analysis-betterment.md`
---
### שלב 6: עדכון Content Checklists
הקובץ `lessons.py` מכיל צ'קליסטים לבלוק י (דיון) לפי סוג ערר.
**מה צריך**:
- ליצור `CONTENT_CHECKLISTS["betterment_levy"]` עם נושאים ייחודיים
- נושאים צפויים: שומות, תכנית משביחה, מועד, חישוב, פטורים, ראיות שמאיות
- הצ'קליסט ייבנה מתוך ניתוח הקורפוס (שלב 5)
---
### שלב 7: אימות Paperclip
לוודא שחברת CMPA מוגדרת נכון:
**בדיקות**:
- [ ] חברה CMPA קיימת ופעילה ב-Paperclip DB
- [ ] Issue prefix = CMPA
- [ ] Plugin `legal-ai` פעיל בחברה
- [ ] סוכנים (CEO, researcher, writer) מוגדרים
- [ ] tag_company_mappings נכון ב-legal-ai DB:
- `betterment_levy` → `8639e837...`
- `compensation_197` → `8639e837...`
- [ ] יצירת תיק 8xxx מנותבת נכון
**כלי בדיקה**:
```
GET /api/settings/tag-mappings
GET /api/paperclip/companies
```
---
## סיכום — סדר פעולות
| # | שלב | מה | כלי | זמן משוער |
|---|------|----|------|-----------|
| 1 | הכנה | איסוף קבצי DOCX, בדיקת פורמט | ידני | — |
| 2 | העלאה | העלאת כל ההחלטות + proofreading אוטומטי | Web API / MCP | דקות לכל החלטה |
| 3 | ביקורת | בדיקת כל טקסט מנוקה + metadata | ידני / Claude | כמה שעות |
| 4 | ניתוח סגנון | חילוץ דפוסים מהקורפוס | API analyze-style | ~30 דק |
| 5 | ניתוח קורפוס | מפת תוכן + נושאים + השוואה | Claude + מסמך | כמה שעות |
| 6 | צ'קליסט | יצירת content checklist להיטלי השבחה | עדכון קוד | — |
| 7 | אימות Paperclip | בדיקת הגדרות חברה + ניתוב | API / DB | — |
---
## הערות חשובות
### ההבדל בין רישוי ובנייה להיטלי השבחה (מ-CLAUDE.md)
| מאפיין | רישוי ובנייה (1xxx) | היטלי השבחה (8xxx) |
|---------|---------------------|-------------------|
| טון | חם יחסית | קר ומקצועי |
| תוכן | הקשר תכנוני רחב, אלמנטים אנושיים | יבש, ללא רגשות |
| נושאי דיון | תכניות, חניה, קווי בניין, שכנים | שומות, חישובי השבחה, פטורים |
| פסיקה | ס' 152, הלכת שפר, דיני הקלה | ס' 196-198, תוספת שלישית, שמאי מכריע |
### סינון RAG לפי סוג
כל ה-chunks נשמרים עם `appeal_subtype`, כך שחיפוש סמנטי בתיק היטל השבחה ימצא רק תקדימים רלוונטיים מהתחום — לא יערבב עם רישוי ובנייה.
### ניתוח סגנון נפרד
ייתכן שנצטרך **מדריך סגנון נפרד** להיטלי השבחה, כי הטון שונה מהותית. הניתוח בשלב 4 יחשוף את ההבדלים.
---
## סוכנים — שיתוף בין החברות
### עיקרון: אותם סוכנים, הקשר שונה
**אין צורך בסוכנים נפרדים** לכל חברה. הסוכנים (CEO, researcher, writer) עובדים לפי **מתודולוגיה** — ארכיטקטורת 12 בלוקים, CREAC, מבחן השופט — שחלה על כל סוגי העררים.
**מה שמשתנה אוטומטית לפי `appeal_subtype`**:
| רכיב | מקור | מנגנון הפרדה |
|-------|------|--------------|
| Style patterns | טבלת `style_patterns` | ניתוח סגנון נפרד per-subtype |
| Content checklists | `lessons.py` | key שונה: `building_permit` vs `betterment_levy` |
| תקדימים (RAG) | טבלת `document_chunks` | סינון לפי `appeal_subtype` בחיפוש |
| טון | style guide + patterns | דפוסים שונים מהקורפוס |
**למה שיתוף סוכנים עדיף**:
1. שיפור במתודולוגיה חל אוטומטית על שני התחומים
2. אין כפילות בתחזוקת סוכנים
3. ההפרדה היא **ברמת הנתונים**, לא ברמת הלוגיקה
**מה כן צריך לוודא**:
- [ ] הסוכנים ב-Paperclip מקושרים לשתי החברות (CMP + CMPA)
- [ ] כש-issue נפתח ב-CMPA, הסוכנים מופעלים באותו אופן
- [ ] ה-context שהסוכן מקבל כולל את ה-`appeal_subtype` הנכון