README.md

---
title: AI Chatbot Site
emoji: 🤖
colorFrom: blue
colorTo: purple
sdk: docker
pinned: false
---

# 🤖 Zephyr-7B Chatbot für Hugging Face Spaces

Ein vollständiges React-Frontend mit Python-Backend für KI-Inferenz auf Hugging Face Spaces. Mit integriertem Plugin-System für einfache Erweiterbarkeit.

## 🎯 Features

- **Zephyr-7B-Beta Modell** - Schnell, optimiert, auf VRAM-Limited Spaces
- **React + Vite Frontend** - Modernes, responsives UI
- **Gradio Backend** - Einfaches Deployment auf HF Spaces
- **Plugin-System** - Einfach neue JS-Dateien in `/plugins` packen und sie werden automatisch geladen
- **Live Streaming** - Token-by-Token Responses (optional ausbaubar)
- **Mehrsprachig** - DE/EN ready

## 🚀 Quick Start

### Lokal testen

1. **Requirements installieren:**
```bash
pip install -r requirements.txt
```

2. **Backend starten:**
```bash
python app.py
```
Das Backend läuft dann auf `http://localhost:7860`

3. **React Frontend (neuer Terminal):**
```bash
npm install
npm run dev
```
Frontend läuft auf `http://localhost:5173`

### 📦 Build für HF Spaces

1. **React Build:**
```bash
npm run build
```
Erzeugt `dist/` Ordner

2. **Hochladen zu HF Spaces:**
```bash
# Space erstellen auf huggingface.co/spaces
# Dann:
git clone https://huggingface.co/spaces/USERNAME/SPACE-NAME
cd SPACE-NAME

# Dateien kopieren:
cp app.py .
cp requirements.txt .
cp -r plugins/ .
cp -r dist/ .  # (optional, wenn du static files servieren willst)
```

3. **Commit & Push:**
```bash
git add .
git commit -m "Initial commit"
git push
```

Die Spaces wird automatisch deployt!

## 📂 Projektstruktur

```
AI_Chatbot_Site/
├── app.py                    # Gradio Backend (HF Spaces Einstiegspunkt)
├── requirements.txt          # Python Dependencies
├── package.json              # Node Dependencies
├── vite.config.js           # Vite Konfiguration
│
├── src/
│   ├── main.jsx             # React Entry Point
│   ├── App.jsx              # Main App Component
│   ├── App.css              # App Styles
│   ├── index.css            # Global Styles
│   │
│   ├── components/
│   │   ├── ChatBox.jsx      # Chat UI Component
│   │   ├── ChatBox.css
│   │   ├── PluginLoader.jsx # Plugin System
│   │   └── plugins/         # Plugins Ordner
│   │
│   └── utils/
│       ├── api.js           # API Client
│       └── pluginManager.js # Plugin Management
│
├── public/
│   └── index.html
│
└── plugins/
    └── example-logger.js    # Example Plugin
```

## 🔌 Plugin-System

### Ein neues Plugin erstellen

Erstelle eine neue Datei in `plugins/myplugin.js`:

```javascript
// plugins/myplugin.js

export function onPluginInit(context) {
  context.log('My plugin initialized!')
}

export function onMessageSent(context, { message, systemPrompt }) {
  context.log(`User sent: ${message}`)
  
  // Hier kannst du:
  // - Analytics tracken
  // - Daten speichern
  // - API calls machen
  // - Etc.
}

export function onResponseReceived(context, { content, stats }) {
  context.log(`Response: ${content.substring(0, 50)}...`)
  context.log(`Stats: ${JSON.stringify(stats)}`)
}
```

Das Plugin wird **automatisch geladen** wenn die App startet!

### Plugin Hooks

| Hook | Wann | Parameter |
|------|------|-----------|
| `onPluginInit` | Plugin wird geladen | `context` |
| `onMessageSent` | Benutzer sendet Nachricht | `context, { message, systemPrompt }` |
| `onResponseReceived` | Response vom Model | `context, { content, stats }` |

### Plugin Context API

```javascript
context.log(msg)    // Konsolenlog mit Plugin-Name
context.warn(msg)   // Warning
context.error(msg)  // Error
```

## ⚙️ Konfiguration

### Backend (app.py)

```python
MODEL_NAME = "HuggingFaceH4/zephyr-7b-beta"  # Modell wechseln
MAX_TOKENS = 512                             # Max Output länge
TEMPERATURE = 0.7                            # Kreativität (0-2)
TOP_P = 0.9                                  # Nucleus sampling
```

### Frontend Einstellungen

Im UI kannst du direkt:
- System Prompt anpassen
- Temperatur & Top-P live ändern
- Antwortzeit und Token-Count sehen

## 📊 Performance Optimierungen

### Für Hugging Face Spaces (limitierte VRAM):

1. **Model Quantization** (optional):
```python
from transformers import AutoModelForCausalLM

model = AutoModelForCausalLM.from_pretrained(
    MODEL_NAME,
    load_in_8bit=True,  # 8-bit quantization
    device_map="auto",
)
```

2. **Kleineres Modell**:
```python
MODEL_NAME = "HuggingFaceH4/zephyr-7b-alpha"  # Schneller
# oder
MODEL_NAME = "mistralai/Mistral-7B-v0.1"     # Alternative
```

3. **Caching**:
```python
# Model wird gecacht nach erstem Load
```

## 🎨 Styling

- **CSS Variables** in `src/index.css` für einfache Anpassung
- Responsive Design (Mobile, Tablet, Desktop)
- Dunkel/Hell Mode Support (buildbar)

## 🔐 Security

- Backend validiert alle Inputs
- CORS ist für HF Spaces automatisch configured
- Sensitive data (API Keys) sollten in `.env` gehen (nicht committed)

## 🐛 Troubleshooting

### "Module not found" bei Plugins

Stelle sicher:
- Datei ist im `/plugins` Ordner
- Exports sind korrekt: `export function onPluginInit(context) { }`

### Backend startet nicht

```bash
# Teste wenn Python funktioniert:
python -c "import torch; print(torch.cuda.is_available())"

# Stelle sicher transformers installiert:
pip install -r requirements.txt --upgrade
```

### React startet nicht

```bash
rm -rf node_modules package-lock.json
npm install
npm run dev
```

## 📝 Lizenz

MIT - Du kannst das frei nutzen, modifizieren und deployen!

## 🤝 Contributing

Feel free to add more plugins, components, or optimizations!

## 🎓 Nächste Schritte

- [ ] Streaming Responses (token-by-token)
- [ ] Dark Mode Toggle
- [ ] Chat History speichern
- [ ] Export Chats als PDF
- [ ] Multi-Model Support (einfach zu Model-Select erweitern)
- [ ] Voice Input (Whisper Integration)
- [ ] Analytics Dashboard

---

**Happy Coding! 🚀**