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 - תוצאה מלאה של ניתוח

תהליך העבודה:

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:

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:

model = genai.GenerativeModel("gemini-2.0-flash")  # שנה כאן

שינוי סף איכות

ערוך ב-app/sql_service.py:

if score < 80:  # שנה כאן (0-100)

הוספת עמודות חדשות

ערוך ב-app/sql_service.py → _get_schema_info():

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: [לעדכן]
• קורות חיים: [לעדכן]