הוספת תיעוד מפורט לגישה החדשה SQL-based

SQL_APPROACH_README.md

@@ -0,0 +1,172 @@
+# SQL-Based Approach - מדריך
+
+## סקירה כללית
+
+גישה חדשה לניתוח משובי משתמשים המבוססת על SQL queries שנוצרות אוטומטית על ידי LLM.
+
+## ארכיטקטורה
+
+### 1. ניתוח שאילתת המשתמש
+- המשתמש שואל שאלה בעברית או באנגלית
+- השאלה נשלחת ל-LLM לניתוח
+
+### 2. יצירת שאילתות SQL (1-5 שאילתות)
+**מיקום:** `app/sql_service.py` - `_generate_sql_queries()`
+
+המערכת משתמשת ב-LLM (Gemini או OpenAI) כדי ליצור 1-5 שאילתות SQL שיעזרו לענות על השאלה.
+
+**הפרומפט כולל:**
+- מידע על מבנה הטבלה (ID, ServiceName, Level, Text)
+- סטטיסטיקות כלליות
+- כללי SQLite
+- הוראות ליצירת שאילתות תקפות
+
+**דוגמאות לשאילתות שנוצרות:**
+```sql
+SELECT ServiceName, COUNT(*) as count, AVG(Level) as avg_level 
+FROM feedback 
+GROUP BY ServiceName 
+ORDER BY count DESC 
+LIMIT 10;
+
+SELECT Level, COUNT(*) as count 
+FROM feedback 
+WHERE Level < 3 
+GROUP BY Level;
+```
+
+### 3. הרצת השאילתות
+**מיקום:** `app/sql_service.py` - `_execute_sql_queries()`
+
+- יוצר SQLite in-memory database
+- טוען את ה-DataFrame לטבלה `feedback`
+- מריץ כל שאילתה ומחזיר תוצאות או שגיאות
+
+### 4. יצירת תשובה מסכמת
+**מיקום:** `app/sql_service.py` - `_synthesize_answer()`
+
+המערכת משתמשת ב-LLM (בתפקיד אנליסט עסקי במשרד הפנים) כדי ליצור תשובה מסכמת.
+
+**הפרומפט כולל:**
+- שאלת המשתמש
+- השאילתות שבוצעו
+- התוצאות של כל שאילתה
+- הוראות לכתיבת תשובה מפורטת ומקצועית
+
+**דרישות לתשובה:**
+- 5-7 פסקאות, 400-600 מילים
+- מספרים מדויקים מהתוצאות
+- תובנות עסקיות והמלצות מעשיות
+- מבנה ברור: פתיחה, ניתוח, תובנות, סיכום
+
+### 5. יצירת ויזואליזציות (אופציונלי)
+**מיקום:** `app/sql_service.py` - `_generate_visualizations()`
+
+המערכת מנתחת את תוצאות השאילתות ויוצרת מפרטי ויזואליזציות:
+
+**סוגי גרפיקות נתמכים:**
+- **Bar Chart** - לנתונים קטגוריאליים עם ערכים מספריים
+- **Line Chart** - לנתוני זמן או מגמות
+- **Scatter Plot** - לשני משתנים מספריים
+- **Histogram** - להפצת ערכים מספריים
+
+**Frontend:** משתמש ב-Chart.js להצגת הגרפיקות
+
+## שימוש
+
+### דרך API
+
+```bash
+POST /query-sql
+Content-Type: application/json
+
+{
+  "query": "איך המשתמשים מרגישים כלפי השירות?",
+  "top_k": 5
+}
+```
+
+**תגובה:**
+```json
+{
+  "query": "איך המשתמשים מרגישים כלפי השירות?",
+  "summary": "תשובה מסכמת מפורטת...",
+  "sql_queries": [
+    "SELECT Level, COUNT(*) FROM feedback GROUP BY Level",
+    "..."
+  ],
+  "query_results": [
+    {
+      "query": "SELECT ...",
+      "result": [...],
+      "error": null,
+      "row_count": 10
+    }
+  ],
+  "visualizations": [
+    {
+      "type": "bar",
+      "title": "תוצאה של שאילתה 1",
+      "x": "Level",
+      "y": "count",
+      "data": [...]
+    }
+  ]
+}
+```
+
+### דרך Frontend
+
+1. פתח את הדפדפן: `http://127.0.0.1:8000`
+2. בחר "SQL-based (מומלץ - חדש)"
+3. הזן שאלה
+4. לחץ על "שאל"
+5. התוצאות יוצגו עם:
+   - תשובה מסכמת
+   - שאילתות SQL שבוצעו (אם מסומן "הצג דוגמאות מהנתונים")
+   - תוצאות השאילתות
+   - גרפיקות אוטומטיות
+
+## יתרונות הגישה החדשה
+
+1. **דיוק גבוה** - שאילתות SQL מדויקות יותר מ-RAG
+2. **שקיפות** - המשתמש רואה בדיוק אילו שאילתות בוצעו
+3. **גמישות** - יכול לענות על שאלות מורכבות עם מספר שאילתות
+4. **ויזואליזציות** - גרפיקות אוטומטיות של התוצאות
+5. **מהירות** - שאילתות SQL מהירות יותר מ-RAG
+
+## השוואה לגישה הישנה (RAG)
+
+| תכונה | RAG | SQL-based |
+|------|-----|-----------|
+| דיוק | בינוני | גבוה |
+| שקיפות | נמוכה | גבוהה |
+| מהירות | איטית יותר | מהירה יותר |
+| גמישות | מוגבלת | גבוהה |
+| ויזואליזציות | לא | כן |
+
+## הגדרות LLM
+
+### יצירת שאילתות SQL
+- **Temperature:** 0.3 (נמוך לדיוק)
+- **Model:** Gemini 1.5 Flash או GPT-4o-mini
+
+### יצירת תשובה מסכמת
+- **Temperature:** 0.8 (גבוה ליצירתיות)
+- **Top_p:** 0.95
+- **Max tokens:** 4000 (Gemini) / 3000 (OpenAI)
+
+## קבצים רלוונטי��ם
+
+- `app/sql_service.py` - הלוגיקה הראשית
+- `app/api.py` - endpoint `/query-sql`
+- `app/static/app.js` - תמיכה frontend בגרפיקות
+- `app/static/index.html` - ממשק משתמש
+
+## הערות טכניות
+
+- המערכת משתמשת ב-SQLite in-memory database
+- הנתונים נטענים פעם אחת בתחילת הפעלה
+- השאילתות רצות על DataFrame דרך SQLite
+- הגרפיקות נוצרות אוטומטית על בסיס מבנה התוצאות
+