README.md

---
title: Feedback Analysis Agent
emoji: 📊
colorFrom: blue
colorTo: blue
sdk: docker
pinned: false
license: mit
---

# Feedback Analysis Agent

מערכת ניתוח משובי משתמשים מבוססת SQL ו-LLM.

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

המערכת מאפשרת לשאול שאלות בשפה טבעית על משובי משתמשים ולקבל תשובות מפורטות ומבוססות נתונים. המערכת משתמשת בגישה מבוססת SQL - LLM יוצר שאילתות SQL, הן מבוצעות על הנתונים, ו-LLM נוסף יוצר תשובה מפורטת מהתוצאות.

## תכונות עיקריות

- ✅ **שאילתות בשפה טבעית** - שאל שאלות בעברית על המשובים
- ✅ **ניתוח אוטומטי** - המערכת יוצרת שאילתות SQL אוטומטית
- ✅ **בדיקת איכות אוטומטית** - תשובות נבדקות אוטומטית ומשופרות אם נדרש
- ✅ **ויזואליזציות** - גרפים אוטומטיים של התוצאות
- ✅ **ממשק משתמש מודרני** - UI צבעוני ואינטואיטיבי

## התקנה והרצה

### דרישות מקדימות

- Python 3.10+
- קובץ `feedback_transformed_2.csv` עם העמודות: ID, ServiceName, Level, Text, ReferenceNumber, RequestID, ProcessID, Year, Month, DayInMonth, DayOfWeek, Hour, DayOrNight

המערכת משתמשת ב-`feedback_transformed_2.csv` כברירת מחדל.

**הערה**: אם יש לך תאריכים אמיתיים, עדכן את `CSV_PATH` ב-`.env` או העלה את הקובץ עם התאריכים הנכונים.

### התקנה

```bash
# יצירת סביבה וירטואלית
python -m venv .venv
source .venv/bin/activate  # ב-Windows: .venv\Scripts\activate

# התקנת תלויות
pip install -r requirements.txt
```

### הגדרת API Keys

צור קובץ `.env` בשורש הפרויקט:

```env
GEMINI_API_KEY=your_gemini_key_here
# או
OPENAI_API_KEY=your_openai_key_here
```

**הערה**: לפחות אחד מה-API keys חייב להיות מוגדר.

### הרצה

```bash
python run.py
```

השרת יעלה על `http://127.0.0.1:8000`

פתח את הדפדפן וגש ל-`http://127.0.0.1:8000`

## ארכיטקטורה

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

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

לקריאה מפורטת יותר, ראה [ARCHITECTURE.md](ARCHITECTURE.md)

## מבנה הפרויקט

```
.
├── 0_preprocessing/        # עיבוד מקדים וקבצים משלימים
│   ├── scripts/            # סקריפטים לעיבוד נתונים
│   ├── tests/              # בדיקות
│   ├── feedback_transformed_2.csv  # נתוני המשובים המעובדים (לא ב-git)
│   └── *.md, *.pdf         # מסמכי תכנון ותיעוד
├── 1_frontend/             # האפליקציה והחלק הפרונטי
│   ├── index.html          # ממשק משתמש
│   └── app.js              # לוגיקת frontend
├── 2_backend_llm/          # הלוגיקה והארכיטקטורה ה-LLM
│   ├── app/
│   │   ├── api.py          # FastAPI endpoints
│   │   ├── sql_service.py  # לוגיקת SQL ו-LLM
│   │   ├── config.py       # הגדרות
│   │   └── data_loader.py  # טעינת נתונים מ-CSV
│   ├── run.py              # נקודת כניסה
│   └── app.py              # wrapper
├── .env                    # API keys (לא ב-git)
└── requirements.txt        # תלויות Python
```

## שימוש

### דרך הממשק

1. פתח `http://127.0.0.1:8000` בדפדפן
2. הזן שאלה בשדה הטקסט
3. לחץ על "🔍 שאל"
4. צפה בתשובה, שאילתות SQL, תוצאות, וגרפים

### דרך API

```bash
curl -X POST http://127.0.0.1:8000/query-sql \
  -H "Content-Type: application/json" \
  -d '{"query": "כמה משתמשים כתבו תודה?", "top_k": 5}'
```

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

- "כמה משתמשים כתבו תודה?"
- "מה הנושא המרכזי של המשובים שקיבלו ציון נמוך מ-3?"
- "חלק את המשובים ל-5 נושאים מרכזיים"
- "כמה משובים התקבלו בחודש האחרון?"
- "איך המשתמשים מרגישים כלפי השירות?"

## Quality Assurance

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

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

## Visualizations

המערכת יוצרת **גרפים אוטומטיים**:
- Bar Charts - להשוואות
- Line Charts - למגמות לאורך זמן
- Scatter Plots - לקשרים בין משתנים
- Histograms - להתפלגות נתונים

## Deployment

### Docker

```bash
docker build -t feedback-analysis .
docker run -p 8000:8000 feedback-analysis
```

### Runpod

ראה [DEPLOYMENT_GUIDE.md](DEPLOYMENT_GUIDE.md) לפרטים.

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

### שינוי מודל 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 מכילה את השדות הבאים:
- NewColumn: ...  # הוסף כאן
"""
```

## Troubleshooting

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

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

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

## קישורים

- **GitHub**: [https://github.com/galbendavids/Feedback_Analysis_RAG_Agent_runpod](https://github.com/galbendavids/Feedback_Analysis_RAG_Agent_runpod)
- **קורות חיים**: [https://github.com/galbendavids/Feedback_Analysis_RAG_Agent_runpod/blob/main/0_preprocessing/Gal%20Shlomo%20Ben%20David%20Ohayone_e-1.pdf](https://github.com/galbendavids/Feedback_Analysis_RAG_Agent_runpod/blob/main/0_preprocessing/Gal%20Shlomo%20Ben%20David%20Ohayone_e-1.pdf)

## רישיון

[לעדכן]