laravel-llm-gateway/README.md

# Laravel LLM Gateway

Ein umfassendes Laravel-basiertes LLM Gateway System mit Multi-Provider-Support, Kosten-Tracking, Budget-Management und Admin-Interface.

## 🎯 Hauptfeatures

- **Multi-Provider Support**: OpenAI, Anthropic, DeepSeek, Google Gemini, Mistral AI
- **Per-User API Keys**: Verschlüsselte Speicherung von Provider-Credentials pro Benutzer
- **Kosten-Tracking**: Detaillierte Verfolgung von Token-Nutzung und Kosten
- **Budget-Management**: Flexible Budget-Limits und Benachrichtigungen
- **Rate Limiting**: Schutz vor Überlastung
- **Admin-Interface**: Umfassende Verwaltungsoberfläche mit Laravel/Livewire
- **OpenAI-kompatible API**: Standard-konforme Endpoints

---

## 🚀 Quick Start

### Voraussetzungen
- Docker & Docker Compose installiert
- Port 80 und 8081 verfügbar

### Installation

```bash
cd /opt/laravel-llm
docker compose up -d
```

Das System startet automatisch:
- Laravel Anwendung auf Port 80
- MariaDB 11.4 Datenbank
- phpMyAdmin auf Port 8081

---

## 🌐 URLs & Zugangsdaten

### Services

| Service | URL | Beschreibung |
|---------|-----|--------------|
| **Laravel Admin** | http://localhost:80 | Admin-Interface |
| **phpMyAdmin** | http://localhost:8081 | Datenbank-Management |

### Login-Daten

#### Laravel Admin
```
Email:    admin@laravel-llm.local
Password: [Dein Admin-Passwort]
```

#### phpMyAdmin (MariaDB)
```
Server:   mariadb
Username: root
Password: rootpass
Database: gateway
```

---

## 📁 Projekt-Struktur

```
/opt/laravel-llm/
├── docker-compose.yml          # Docker Services Definition
├── backup_*.sql                # Datenbank-Backups
│
├── laravel/                    # Laravel Docker Config
│   ├── Dockerfile              # PHP 8.3 + Nginx
│   ├── nginx.conf              # Webserver Config
│   ├── supervisord.conf        # Process Manager
│   └── php.ini                 # PHP Einstellungen
│
└── laravel-app/                # Laravel Anwendung
    ├── app/
    │   ├── Http/Controllers/   # Admin Controllers
    │   ├── Models/             # Eloquent Models
    │   ├── Services/LLM/       # Provider Services
    │   └── ...
    ├── database/
    │   └── migrations/         # Datenbank Schema
    ├── resources/
    │   └── views/              # Blade Templates
    └── routes/
        └── web.php             # Admin Routes
```

---

## 🗄️ Datenbank-Schema

### Haupttabellen

| Tabelle | Beschreibung |
|---------|--------------|
| `admins` | Admin-Benutzer für das Interface |
| `users` | Gateway-Benutzer (API-Nutzer) |
| `user_provider_keys` | Verschlüsselte Provider API-Keys |
| `usage_logs` | Request-Tracking und Kosten |
| `budgets` | Budget-Definitionen |
| `budget_reset_logs` | Budget-Historie |
| `model_pricing` | Modell-Kosten-Konfiguration |

### Datenbank-Zugriff

**Via phpMyAdmin:**
```
http://localhost:8081
Server: mariadb
User: root
Password: rootpass
```

**Via CLI:**
```bash
docker compose exec mariadb mysql -u gateway -pgateway gateway

# Beispiel-Queries
SELECT * FROM users;
SELECT * FROM usage_logs ORDER BY created_at DESC LIMIT 10;
```

---

## 🔧 Docker Commands

### Container Management

```bash
# Container starten
docker compose up -d

# Container stoppen
docker compose down

# Logs anzeigen
docker compose logs -f laravel

# Container neu bauen
docker compose up -d --build

# In Laravel Container einloggen
docker compose exec laravel bash
```

### Laravel Artisan Commands

```bash
# Migrationen
docker compose exec laravel php artisan migrate

# Cache leeren
docker compose exec laravel php artisan cache:clear
docker compose exec laravel php artisan config:clear

# Queue Worker starten
docker compose exec laravel php artisan queue:work

# Tinker (Laravel REPL)
docker compose exec laravel php artisan tinker
```

### Asset Compilation

```bash
# Development (mit Hot Reload)
docker compose exec laravel npm run dev

# Production Build
docker compose exec laravel npm run build
```

---

## 🛠️ Entwicklung

### Admin-Interface Features

Das Admin-Interface unter http://localhost:80 bietet:

1. **Dashboard**
   - Übersicht über Nutzungsstatistiken
   - Kosten-Trends (Chart.js)
   - Provider-Verteilung
   - Aktive Benutzer

2. **Gateway Users**
   - Benutzerverwaltung
   - API-Key Management
   - Pro-User Provider-Credentials

3. **API Keys**
   - Virtual Keys erstellen/löschen
   - Key-Testing
   - Nutzungsstatistiken

4. **Budgets**
   - Budget-Limits definieren
   - Reset-Zeiträume (täglich/wöchentlich/monatlich)
   - Benachrichtigungen

5. **Usage Logs**
   - Request-Historie
   - Filter & Export (CSV)
   - Kosten-Analyse

6. **Model Pricing**
   - Preis-Konfiguration
   - Dynamische Model-Liste
   - Kosten-Rechner

### LLM Provider Services

Das System unterstützt folgende Provider mit dynamischer Model-Discovery:

- **OpenAI**: GPT-3.5, GPT-4, GPT-4 Turbo
- **Anthropic**: Claude 3 (Haiku, Sonnet, Opus)
- **DeepSeek**: DeepSeek Chat Modelle
- **Google Gemini**: Gemini Pro, Flash
- **Mistral AI**: Mistral Large, Medium, Small

Alle Provider-Services befinden sich in `app/Services/LLM/`.

---

## 🔐 Sicherheit

### Production Checklist

Vor dem Production-Einsatz:

1. ✅ `.env` Konfiguration:
   ```env
   APP_ENV=production
   APP_DEBUG=false
   APP_KEY=... (sicher generieren!)
   ```

2. ✅ Admin-Passwort ändern

3. ✅ MariaDB Root-Passwort ändern

4. ✅ phpMyAdmin deaktivieren oder absichern

5. ✅ SSL/TLS einrichten

6. ✅ Laravel Caches aktivieren:
   ```bash
   php artisan config:cache
   php artisan route:cache
   php artisan view:cache
   php artisan optimize
   ```

### API-Key Verschlüsselung

Provider API-Keys werden verschlüsselt in der Datenbank gespeichert:
- Verwendung von Laravel's Encryption
- Basiert auf APP_KEY
- Automatische Ver-/Entschlüsselung

---

## 📊 Monitoring & Analytics

### Dashboard Metriken

- Gesamte Requests
- Token-Nutzung (Input/Output)
- Gesamtkosten
- Requests pro Provider
- Top-Nutzer
- Kosten-Trends (Chart.js Visualisierung)

### Export Funktionen

Usage Logs können als CSV exportiert werden mit:
- Zeitraum-Filter
- Provider-Filter
- Benutzer-Filter
- Kosten-Zusammenfassung

---

## 🐛 Troubleshooting

### Container startet nicht

```bash
# Logs prüfen
docker compose logs laravel
docker compose logs mariadb

# Container neu bauen
docker compose down
docker compose up -d --build
```

### Datenbank Connection Fehler

```bash
# MariaDB Status prüfen
docker compose ps mariadb

# Connection testen
docker compose exec laravel php artisan migrate:status
```

### Permissions Fehler

```bash
# Storage Permissions setzen
docker compose exec laravel chmod -R 777 storage bootstrap/cache
```

### Assets werden nicht geladen

```bash
# Assets neu kompilieren
docker compose exec laravel npm run build

# Storage Link neu erstellen
docker compose exec laravel php artisan storage:link
```

---

## 📚 Technologie-Stack

- **Framework**: Laravel 11.x
- **Frontend**: Livewire 3.x + Tailwind CSS 3.x
- **Datenbank**: MariaDB 11.4
- **Webserver**: Nginx + PHP-FPM 8.3
- **Charts**: Chart.js
- **Container**: Docker + Docker Compose

---

## 🔗 Nützliche Links

- **Laravel Docs**: https://laravel.com/docs
- **Livewire Docs**: https://livewire.laravel.com
- **Tailwind CSS**: https://tailwindcss.com
- **Chart.js**: https://www.chartjs.org

---

## 📝 System-Status

### ✅ Implementiert

- [x] Docker-Setup (Laravel + MariaDB + phpMyAdmin)
- [x] Admin-Authentifizierung
- [x] Gateway User Management
- [x] API Key Management mit Testing
- [x] Budget-System mit Limits
- [x] Usage Logs mit CSV Export
- [x] Model Pricing Management
- [x] Dashboard mit Statistiken
- [x] Multi-Provider Support (5 Provider)
- [x] Verschlüsselte Credential-Speicherung
- [x] Dynamische Model-Discovery

### 🚧 Geplant

- [ ] API Gateway Endpoints (OpenAI-kompatibel)
- [ ] Rate Limiting Implementation
- [ ] Email-Benachrichtigungen
- [ ] Erweiterte Analytics
- [ ] API-Dokumentation

---

**Entwickelt von Wilfried Trinkl | Laravel LLM Gateway** 🚀