0_preprocessing/ARCHITECTURE.md

# ארכיטקטורת המערכת - Feedback Analysis Agent

## סקירה כללית

המערכת היא **SQL-based Feedback Analysis Agent** שמאפשרת לשאול שאלות בשפה טבעית על משובי משתמשים ולקבל תשובות מפורטות ומבוססות נתונים.

## עקרונות הארכיטקטורה

המערכת מבוססת על **4 שלבים עיקריים**:

1. **ניתוח שאילתה** - LLM מנתח את שאלת המשתמש
2. **יצירת שאילתות SQL** - LLM יוצר 1-5 שאילתות SQL רלוונטיות
3. **ביצוע שאילתות** - שאילתות SQL מבוצעות על הנתונים
4. **סינתזה ותשובה** - LLM יוצר תשובה מפורטת מהתוצאות, כולל בדיקת איכות אוטומטית

## רכיבי המערכת

### 1. Backend (Python/FastAPI)

#### `app/api.py`
- **תפקיד**: FastAPI application - נקודת הכניסה הראשית
- **Endpoints**:
  - `POST /query-sql` - שאילתות עיקריות (הגישה היחידה)
  - `POST /health` - בדיקת תקינות השרת
  - `GET /history` - היסטוריית שאלות
  - `POST /history/clear` - ניקוי היסטוריה
  - `GET /` - ממשק משתמש (frontend)

#### `app/sql_service.py`
- **תפקיד**: הליבה של המערכת - מטפל בכל תהליך הניתוח
- **מחלקות**:
  - `SQLFeedbackService` - השירות הראשי
  - `SQLQueryResult` - תוצאה של שאילתת SQL אחת
  - `AnalysisResult` - תוצאה מלאה של ניתוח

**תהליך העבודה**:
```python
analyze_query(query) 
  → _generate_sql_queries()      # שלב 1: יצירת שאילתות SQL
  → _execute_sql_queries()       # שלב 2: ביצוע שאילתות
  → _synthesize_answer()         # שלב 3: יצירת תשובה
    → _evaluate_answer_quality() # בדיקת איכות (אם < 80, שיפור אוטומטי)
  → _generate_visualizations()   # שלב 4: יצירת גרפים
```

**פונקציות מפתח**:
- `_generate_sql_queries()` - משתמש ב-LLM ליצירת שאילתות SQL
- `_execute_sql_queries()` - מריץ שאילתות על SQLite in-memory
- `_synthesize_answer()` - יוצר תשובה מפורטת מהתוצאות
- `_evaluate_answer_quality()` - בודק איכות תשובה (0-100)
- `_generate_visualizations()` - יוצר מפרטי גרפים

#### `app/data_loader.py`
- **תפקיד**: טעינת נתונים מ-CSV
- **פונקציה**: `load_feedback()` - טוען ומנקה את קובץ ה-CSV

#### `app/config.py`
- **תפקיד**: הגדרות מערכת
- **מכיל**: API keys, נתיבי קבצים, שמות עמודות

### 2. Frontend (HTML/CSS/JavaScript)

#### `app/static/index.html`
- **תפקיד**: ממשק משתמש
- **תכונות**:
  - שדה שאילתה
  - הצגת תשובות
  - הצגת שאילתות SQL ותוצאות
  - גרפים ויזואליים
  - היסטוריית שאלות

#### `app/static/app.js`
- **תפקיד**: לוגיקת frontend
- **פונקציות מפתח**:
  - `sendQuery()` - שליחת שאילתה לשרת
  - `showVisualizations()` - הצגת גרפים
  - `getChartConfig()` - הגדרת גרפים (Chart.js)
  - `formatSQLResults()` - עיצוב תוצאות SQL

## זרימת נתונים

```
משתמש → Frontend → API (/query-sql) → SQLFeedbackService
                                              ↓
                                    [1] _generate_sql_queries()
                                              ↓
                                    [2] _execute_sql_queries()
                                              ↓
                                    [3] _synthesize_answer()
                                              ↓
                                    [4] _evaluate_answer_quality()
                                              ↓ (אם < 80)
                                    [5] שיפור אוטומטי
                                              ↓
                                    [6] _generate_visualizations()
                                              ↓
                                    ← AnalysisResult
                                              ↓
                                    ← JSON Response
                                              ↓
                                    Frontend → משתמש
```

## LLM Integration

המערכת תומכת ב-2 LLM providers:

1. **Google Gemini** (מועדף)
   - מודל: `gemini-2.0-flash`
   - Fallback אוטומטי ל-OpenAI אם לא זמין

2. **OpenAI**
   - מודל: `gpt-4o-mini`
   - Fallback אם Gemini לא זמין

**שימוש ב-LLM ב-3 מקומות**:
1. יצירת שאילתות SQL (`_generate_sql_queries`)
2. סינתזה של תשובה (`_synthesize_answer`)
3. הערכת איכות תשובה (`_evaluate_answer_quality`)

## Quality Assurance

### בדיקת איכות אוטומטית

המערכת כוללת **מערכת בדיקת איכות אוטומטית**:

1. כל תשובה מקבלת ציון 0-100
2. קריטריונים:
   - האם התשובה עונה ישירות על השאלה? (0-30 נקודות)
   - האם התשובה מבוססת על הנתונים? (0-25 נקודות)
   - האם התשובה מפורטת ומקיפה? (0-20 נקודות)
   - האם התשובה ברורה ומובנת? (0-15 נקודות)
   - האם התשובה כוללת תובנות עסקיות? (0-10 נקודות)

3. אם הציון < 80:
   - המערכת מנסה לשפר את התשובה אוטומטית
   - התשובה המשופרת נבדקת שוב
   - אם הציון השתפר, התשובה המשופרת מוחזרת

## Visualizations

המערכת יוצרת **גרפים אוטומטיים** בהתבסס על תוצאות השאילתות:

- **Bar Chart** - להשוואות בין קטגוריות
- **Line Chart** - למגמות לאורך זמן
- **Scatter Plot** - לקשרים בין משתנים
- **Histogram** - להתפלגות נתונים

כל גרף כולל:
- הסבר על סוג הגרף
- צבעים מגוונים
- Tooltips אינטראקטיביים

## Database Schema

המערכת עובדת עם טבלת `Feedback_transformed`:

```sql
CREATE TABLE Feedback_transformed (
    ID INTEGER PRIMARY KEY,
    ServiceName TEXT,      -- שם השירות
    Level INTEGER,         -- דירוג 1-5
    Text TEXT,             -- טקסט המשוב
    Year INTEGER,          -- שנה
    Month INTEGER,         -- חודש
    DayInMonth INTEGER,    -- יום בחודש
    DayOfWeek TEXT,        -- יום בשבוע
    Hour INTEGER,          -- שעה
    DayOrNight TEXT        -- יום/לילה
);
```

## Security & Configuration

- **API Keys**: נטענים מ-`.env` (git-ignored)
- **Data**: קובץ CSV נטען מהדיסק
- **History**: נשמר ב-`.query_history.json` (git-ignored)

## Deployment

המערכת יכולה לרוץ:
- **Locally**: `python run.py`
- **Docker**: `docker build && docker run`
- **Runpod**: באמצעות Dockerfile

## הרחבות עתידיות

1. **Caching** - שמירת תוצאות שאילתות נפוצות
2. **Multi-language** - תמיכה בשפות נוספות
3. **Advanced Analytics** - ניתוחים סטטיסטיים מתקדמים
4. **Real-time Updates** - עדכונים בזמן אמת
5. **Export** - ייצוא תוצאות ל-PDF/Excel

## שינויים והתאמות

### שינוי מודל LLM
ערוך ב-`app/sql_service.py`:
```python
model = genai.GenerativeModel("gemini-2.0-flash")  # שנה כאן
```

### שינוי סף איכות
ערוך ב-`app/sql_service.py`:
```python
if score < 80:  # שנה כאן (0-100)
```

### הוספת עמודות חדשות
ערוך ב-`app/sql_service.py` → `_get_schema_info()`:
```python
schema_info = f"""
טבלת Feedback מכילה את השדות הבאים:
- ID: ...
- NewColumn: ...  # הוסף כאן
"""
```

### שינוי עיצוב Frontend
ערוך ב-`app/static/index.html` (CSS) ו-`app/static/app.js` (JavaScript)

## Troubleshooting

### שגיאת "No feedback data available"
- ודא שקובץ `Feedback.csv` קיים
- ודא שהעמודות הנדרשות קיימות: ID, ServiceName, Level, Text

### שגיאת API Key
- ודא שקובץ `.env` קיים עם `GEMINI_API_KEY` או `OPENAI_API_KEY`

### תשובות לא איכותיות
- בדוק את הלוגים - המערכת מדפיסה ציוני איכות
- נסה לשנות את ה-prompt ב-`_synthesize_answer()`

## קישורים

- GitHub: [לעדכן]
- קורות חיים: [לעדכן]