ARCHITECTURE_HUGGINGFACE.md

# 🏗️ PixelForge Architektur mit HuggingFace Spaces

## Übersicht

PixelForge wird als **Orchestrator** fungieren, der externe AI-Services via REST API orchestriert. Die Heavy-Lifting (GPU-intensive Image Generation) läuft auf HuggingFace Spaces.

```
┌─────────────────────────────────────────────────────────┐
│            PixelForge Frontend (React/Vite)             │
│                   http://127.0.0.1:5173                │
└────────────────────┬────────────────────────────────────┘
                     │
                     │ HTTP Requests
                     ↓
┌─────────────────────────────────────────────────────────┐
│          PixelForge Backend (FastAPI)                   │
│           http://127.0.0.1:8008                        │
│  ┌──────────────────────────────────────────────────┐  │
│  │  Provider Factory & Job Manager                 │  │
│  └────┬─────────────────────────────────────────────┘  │
└────┼──────────────────────────────────────────────────────┘
     │
     ├─ Lokale Provider (CPU):
     │  ├─ dummy: Dummy bilder
     │  ├─ localai: LocalAI Engine
     │  └─ diffusion: Stable Diffusion (lokal)
     │
     └─ Remote Provider (API/GPU):
        ├─ zimageturbo: Cloud API (Colab/RunPod) [ÜBERGANGSLÖSUNG]
        ├─ huggingface: HuggingFace Space API [ZUKÜNFTIG]
        │  ├─ Heartsync/Adult Space (erwachsene Inhalte)
        │  ├─ weitere HF Spaces...
        │  └─ Authentifizierung via HF API Token
        │
        └─ a1111: AUTOMATIC1111 API (lokal falls vorhanden)
```

---

## Phase 1: Aktuelle State (Übergangslösung)

**Colab + Z-Image Turbo** als schneller Remote-Provider:
- ✅ Funktioniert sofort
- ⚠️ Session-basiert (max 12 Stunden)
- ⚠️ Colab kann jeden Moment beenden
- ✅ Kostenlos

**Implementation**: `zimageturbo_provider.py` (HTTP API Wrapper)

### Zu tun jetzt:
1. Frontend testen (Modellauswahl wurde gefixt)
2. Colab Notebook hochladen & API URL setzen
3. Z-Image Turbo Provider testen

---

## Phase 2: HuggingFace Space Integration (Zukünftig)

**Adult_repo** bleibt als eigenständige Einheit auf HuggingFace Spaces:

```bash
# Adult_repo läuft auf:
https://huggingface.co/spaces/Heartsync/Adult
# → Hat eigene GPU/Inference Engine
# → Verfügbar 24/7 (solange Space online)
```

### Architektur:

1. **Adult_repo auf HF Space** (remote)
   - Gradio Interface (aber nicht für PixelForge relevant)
   - Inference Endpoint für API-Calls
   - Nutzt Z-Image Turbo Model intern

2. **HuggingFace Space API Provider** (neu in PixelForge)
   ```python
   # Backend Provider
   class HuggingFaceSpaceProvider(IImageProvider):
       def __init__(self, space_name: str, token: str):
           self.space_name = "Heartsync/Adult"  # oder andere Spaces
           self.api_token = os.getenv("HF_API_TOKEN")
           
       def generate(self, request: ProviderRequest) -> ProviderResult:
           # POST zu HF Inference API
           # https://api-inference.huggingface.co/models/{space}
           ...
   ```

3. **PixelForge kennt mehrere Spaces**:
   - `heartsync/adult` → Erwachsene Inhalte
   - `heartsync/anime` → Anime-Style
   - `custom/space` → Beliebige andere Spaces

---

## Vergleich: Colab vs HuggingFace Space

| Aspekt | Colab | HF Space | Lokal |
|--------|-------|----------|-------|
| **Setup** | Jupyter Notebook | Einmal deployen | Python Virtual Env |
| **Kosten** | Kostenlos | Kostenlos (mit Limits) | Nur Hardware |
| **Persistenz** | 12h max | 24/7 (solange online) | 24/7 |
| **GPU** | T4/A100 (kostenlos) | Space-spezifisch | Deine Hardware |
| **API-Zugriff** | über Ngrok-Tunnel | HF Inference API | localhost:PORT |
| **Startzeit** | ~2 min (Kernel) | instant | instant |
| **Geeignet für** | Schnelle Tests | Production | Development |

---

## Implementierungs-Roadmap

### ✅ Heute (Phase 1)
- [x] Frontend Model-Picker repariert
- [x] Colab Notebook erstellt
- [x] zimageturbo_provider.py ✓
- [ ] Testen mit Colab

### 📅 Später (Phase 2)
- [ ] HuggingFaceSpaceProvider erstellen
- [ ] HF API Token Authentication
- [ ] Adult_repo auf HF Space deployen
- [ ] Provider registrieren & testen
- [ ] Colab durch HF Space ersetzen

### 🎯 Langfristig (Phase 3)
- [ ] Multi-Space Support (verschiedene Spaces wählen)
- [ ] Space Health Monitoring
- [ ] Fallback-Strategie (wenn Space down ist)
- [ ] Queue Management für lange Jobs

---

## HuggingFace API Details (für später)

### Space Deployment (Adult_repo)
```bash
# HF CLI installieren
pip install huggingface-hub

# Private Space erstellen (Adult content)
huggingface-cli repo create --type space Adult_repo --private

# Adult_repo hochladen
git push huggingface main
```

### PixelForge Provider (HTTP API Call)
```python
import requests

# HF Inference API Endpoint
url = "https://api-inference.huggingface.co/models/Heartsync/Adult"

payload = {
    "inputs": "A beautiful sunset over mountains",
}

headers = {
    "Authorization": f"Bearer {HF_API_TOKEN}"
}

response = requests.post(url, json=payload, headers=headers)
image_data = response.content  # PIL Image bytes
```

### Alternative: Space API (wenn Gradio genutzt)
```python
# Falls Adult_repo Gradio API exponiert
from gradio_client import Client

client = Client("https://huggingface.co/spaces/Heartsync/Adult")
result = client.predict(
    prompt="A girl in a school uniform",
    seed=42,
    api_name="/predict"
)
```

---

## Umgebungsvariablen (Phase 2)

```powershell
# HuggingFace Integration
$env:HF_API_TOKEN = "hf_xxxxxxxxxxxxxxxxxxxxx"
$env:HF_SPACE_ADULT = "Heartsync/Adult"
$env:HF_SPACE_DEFAULT = "Heartsync/Adult"
$env:HF_REQUEST_TIMEOUT = "300"  # Sekunden

# Colab (Phase 1 - temporär)
$env:ZIMAGETURBO_API_URL = "https://abc123.ngrok.io"
$env:ZIMAGETURBO_TIMEOUT = "300"
```

---

## Adult_repo Struktur (vor Ort)

```
d:/VSC Codes/Bild/Adult_repo/
├── app.py                 # Gradio Interface (wird auf HF Space laufen)
├── requirements.txt       # Dependencies
├── README.md
└── .git                   # Git Repo
```

**Wichtig**: Adult_repo ist momentan nicht in PixelForge integriert!
- Es läuft später als eigenständiger Service auf HF Space
- PixelForge ruft es via HF API auf
- Keine lokale Abhängigkeit → Clean Architecture ✨

---

## Nächste Schritte

### Sofort (Phase 1):
```powershell
# 1. Frontend aktualisieren (Done ✓)
# 2. Browser aktualisieren (F5)
# 3. Modellauswahl testen
# 4. Colab konfigurieren & testen
```

### Später (Phase 2):
```powershell
# 1. Adult_repo zu HF Space pushen
# 2. HF API Token besorgen
# 3. HuggingFaceSpaceProvider schreiben
# 4. In Factory registrieren
# 5. Testen & Colab deaktivieren
```

---

## Fragen für Phase 2?

- Welche anderen Spaces möchtest du anbinden?
- Benötigst du Content Moderation (Safety Filter)?
- Wie sollen lange Jobs (>5min) gehandhabt werden?
- Fallback-Strategie wenn Space down ist?

---

**Status**: 🟢 Phase 1 bereitet sich vor
**Phase 2 Start**: Nach Colab-Test & HF Space Deployment