imageforge/README.md

# ImageForge

ImageForge ist eine lokal laufende Desktop-App zur Bild-Erstellung per Prompt. Die App nutzt ein Python-Backend (FastAPI + Job-Queue) und ein Electron+React-Frontend.

## Features

- Prompt + Negative Prompt
- Modellauswahl (`dummy`, `localai`, `diffusion`)
- Bildtyp-Presets und Stil-Presets
- Image-to-Image (Startbild + Strength)
- Dashboard (Queue, Status, Retry/Cancel, Compare)
- Preset-System (CRUD)
- Export (PNG/JPG/WEBP)
- Prompt-Versionierung (`config_hash` in `meta.json`)
- API-Key + Rollenmodell (`viewer`, `operator`, `admin`)
- Rate-Limit pro Client
- Health + Readiness + Metrics
- Recovery von Job-Status nach Neustart
- Storage-Governance (Retention-Cleanup)

## Setup

```powershell
cd imageforge
python -m venv .venv
.\.venv\Scripts\Activate.ps1
pip install -r requirements.txt
npm --prefix frontend install
```

## Start

```powershell
npm run dev
```

Für den kompletten lokalen Stack (Backend + Frontend, inkl. Healthcheck):

```powershell
npm run dev:stack
```

## Serverbetrieb

```powershell
$env:IMAGEFORGE_HOST="0.0.0.0"
$env:IMAGEFORGE_PORT="8008"
$env:IMAGEFORGE_CORS_ORIGINS="http://localhost:5173"
$env:IMAGEFORGE_API_KEYS="viewerKey:viewer,opsKey:operator,adminKey:admin"
$env:IMAGEFORGE_RATE_LIMIT_PER_MIN="120"
$env:IMAGEFORGE_CONTENT_PROFILE="internal-relaxed"
$env:IMAGEFORGE_ADMIN_TOKEN="change-me"
python -m backend.app.main
```

## Wichtige Endpunkte

- `GET /health`
- `GET /ready`
- `GET /metrics`
- `GET /metrics/prometheus`
- `POST /generate`
- `GET /jobs`
- `POST /jobs/{id}/retry`
- `POST /jobs/{id}/cancel`
- `GET /dashboard/stats`
- `GET/POST/DELETE /presets`
- `POST /export`
- `GET/PUT /admin/settings`
- `POST /admin/cleanup`

## Security und Policy

- API-Key Header: `X-ImageForge-Api-Key`
- Admin Override Header: `X-ImageForge-Admin-Token`
- Policy Profile:
  - `strict`
  - `internal-relaxed`
- Audit-Logs:
  - `policy_audit.log`
  - `admin_audit.log`

## Backup / Restore

```powershell
npm run backup
npm run restore -- -Source backups\imageforge_backup_YYYYMMDD_HHMMSS
```

## Tests

```powershell
npm run test
npm run test:e2e
```

## CI

GitHub Actions Workflow liegt in `.github/workflows/ci.yml`.

## Optional LocalAI / Diffusion

```powershell
pip install diffusers torch transformers accelerate
$env:IMAGEFORGE_LOCALAI_MODEL="stabilityai/sd-turbo"
$env:IMAGEFORGE_LOCALAI_IMAGE_TIMEOUT_SECONDS="180"
$env:IMAGEFORGE_LOCALAI_LOCAL_ONLY="1"
$env:IMAGEFORGE_ENABLE_ATTENTION_SLICING="1"
```

Wenn `torch.cuda.is_available()` auf `False` bleibt, ist oft eine CPU-only Torch-Build installiert.
Für NVIDIA-GPU unter Windows kann eine CUDA-Build so installiert werden:

```powershell
python -m pip install --upgrade --index-url https://download.pytorch.org/whl/cu121 torch torchvision torchaudio
```

## Optional AUTOMATIC1111 Integration

ImageForge kann AUTOMATIC1111 als Provider nutzen (`model = a1111`).

### Empfohlener Produktionspfad (Stability Matrix)

Für stabilen Betrieb auf Windows wird eine **saubere, manager-gesteuerte Installation** empfohlen (statt manuell gepatchter `stable-diffusion-webui`-Klone):

1. Stability Matrix installieren und dort eine frische WebUI-Instanz mit aktivierter API starten.
2. API-Endpunkt prüfen:

```powershell
Invoke-RestMethod http://127.0.0.1:7860/sdapi/v1/sd-models
```

3. ImageForge auf diese Instanz zeigen (Default ist bereits `127.0.0.1:7860`):

```powershell
$env:IMAGEFORGE_A1111_BASE_URL="http://127.0.0.1:7860"
```

1. AUTOMATIC1111 lokal starten (mit API), z. B.:

```powershell
webui-user.bat --api
```

2. Optional URL/Timeout konfigurieren:

```powershell
$env:IMAGEFORGE_A1111_BASE_URL="http://127.0.0.1:7860"
$env:IMAGEFORGE_A1111_TIMEOUT_SECONDS="180"
$env:IMAGEFORGE_A1111_HEALTH_ENDPOINT="/sdapi/v1/sd-models"
$env:IMAGEFORGE_A1111_RETRY_COUNT="2"
$env:IMAGEFORGE_A1111_RETRY_BACKOFF_SECONDS="1.0"
```

Falls A1111 mit `--api-auth user:password` läuft:

```powershell
$env:IMAGEFORGE_A1111_API_USER="user"
$env:IMAGEFORGE_A1111_API_PASSWORD="password"
```

Alternativ als ein String:

```powershell
$env:IMAGEFORGE_A1111_API_AUTH="user:password"
```

Danach erscheint `AUTOMATIC1111` in `/models` als verfügbar, sobald der A1111-Server erreichbar ist.

### Robuster Betrieb bei A1111-Ausfällen

Wenn A1111 nicht erreichbar ist oder Fehler liefert, kann ImageForge automatisch auf andere Provider wechseln (z. B. `localai`, `diffusion`, `dummy`) statt den Job direkt abzubrechen.

```powershell
$env:IMAGEFORGE_ENABLE_AUTO_FALLBACK="1"
$env:IMAGEFORGE_FALLBACK_MODELS="a1111,localai,diffusion,dummy"
$env:IMAGEFORGE_FALLBACK_TIMEOUT_SECONDS="90"
$env:IMAGEFORGE_FALLBACK_MAX_STEPS="24"
```

- `IMAGEFORGE_ENABLE_AUTO_FALLBACK`: `1` aktiviert automatische Umschaltung.
- `IMAGEFORGE_FALLBACK_MODELS`: Priorisierte Reihenfolge der Fallback-Provider.
- `IMAGEFORGE_FALLBACK_TIMEOUT_SECONDS`: Kürzerer Timeout pro Fallback-Versuch.
- `IMAGEFORGE_FALLBACK_MAX_STEPS`: Deckel für Steps bei Fallback, um Laufzeit zu reduzieren.

### Stack-Readiness prüfen

Nach dem Start von Backend und A1111:

```powershell
./scripts/healthcheck-stack.ps1 -RequireA1111
```

Das Skript validiert `/health`, `/ready`, `/models` und optional die A1111-API selbst.

## Troubleshooting

- Falls Desktop-Build auf Windows an Symlink-Rechten scheitert: Entwickler-Modus oder Admin-Rechte aktivieren.
- Logs: `app.log`, `policy_audit.log`, `admin_audit.log`.