Mitarbeit am KIVA LLM Gateway

Das KIVA LLM Gateway ist ein Fork von LiteLLM v1.74.4 und wurde als schlanke Referenzimplementierung für souveräne KI-Gateway-Lösungen entwickelt. Wir orientieren uns an den bewährten LiteLLM Contributing Guidelines und Code-Standards.

Vielen Dank für Ihr Interesse an der Mitarbeit! Wir freuen uns über Beiträge aller Art - von Fehlerbehebungen und Dokumentationsverbesserungen bis hin zu neuen Funktionen.

Voraussetzungen

• Python 3.10, 3.11 oder 3.12
• Poetry für Dependency Management
• PostgreSQL (lokal oder via Docker)
• Node.js & npm (für Web-Dashboard)
• Docker & Docker Compose (optional, aber empfohlen)

---

Entwicklungsumgebung einrichten

1. Repository und Virtual Environment

# Repository klonen
git clone https://gitlab.opencode.de/baden-wuerttemberg/innenministerium/kiva.apps/kiva-llm-gateway
cd kiva-llm-gateway

# Python Virtual Environment erstellen
python -m venv .venv

# Virtual Environment aktivieren
# Linux/macOS:
source .venv/bin/activate
# Windows:
.venv\Scripts\activate

# Python Version prüfen (sollte 3.10, 3.11 oder 3.12 sein)
python --version

2. Dependencies installieren

# Proxy-Entwicklungsabhängigkeiten installieren (inkl. aiohttp)
make install-proxy-dev

# Prisma Client generieren
poetry run prisma generate

3. Umgebungskonfiguration

# .env Datei erstellen
cp .env.example .env

# .env bearbeiten (siehe Abschnitt unten)
# Mindestens DATABASE_URL und LITELLM_MASTER_KEY konfigurieren

Minimale .env Konfiguration für Entwicklung

# Core Configuration
LITELLM_MASTER_KEY="sk-dev-key-1234"
DATABASE_URL="postgresql://llmproxy:dbpassword9090@localhost:5432/litellm"
STORE_MODEL_IN_DB="True"

# Optional: API Keys für Testing (leer lassen wenn nicht benötigt)
AZURE_API_KEY=""
OPENAI_API_KEY=""

4. Datenbank starten

Option A: Docker Compose (empfohlen)

# PostgreSQL mit Docker starten
docker-compose up -d db

# Datenbank-Schema erstellen
poetry run prisma migrate dev --name init

Option B: Lokale PostgreSQL

# PostgreSQL lokal installieren und Datenbank erstellen
createdb litellm

# Datenbank-Schema erstellen
poetry run prisma migrate dev --name init

5. Services starten

# Backend starten (Terminal 1)
poetry run uvicorn litellm.proxy.proxy_server:app --host localhost --port 4000 --reload

# Web-Dashboard starten (Terminal 2)
cd ui/litellm-dashboard
npm install
npm run dev

Erfolgreich eingerichtet wenn:

• Backend läuft auf http://localhost:4000
• Web-Dashboard läuft auf http://localhost:3000
• Keine Prisma-Fehler oder Module-Not-Found-Errors

---

Entwicklungsworkflow

Feature-Branch erstellen

# Aktuellen Stand holen
git checkout main
git pull origin main

# Feature-Branch erstellen
git checkout -b feature/ihr-feature-name
# oder
git checkout -b fix/bug-beschreibung

Code-Änderungen implementieren

# Änderungen vornehmen...

# Code automatisch formatieren
make format

# Linting-Prüfungen ausführen
make lint

# Unit-Tests ausführen
make test-unit

# Spezifische Tests ausführen
poetry run pytest tests/test_litellm/test_ihre_datei.py -v

Änderungen committen

Conventional Commits Standard

Wir folgen dem Conventional Commits Standard für konsistente und aussagekräftige Commit-Nachrichten:

Format:

<type>[optional scope]: <description>

[optional body]

[optional footer(s)]

Gängige Commit-Typen:

Typ	Beschreibung	Beispiel
feat	Neues Feature	feat(auth): add JWT authentication
fix	Bugfix	fix(api): handle null response values
docs	Dokumentation	docs(readme): update setup instructions
style	Code-Formatierung	style: fix indentation in utils.py
refactor	Code-Refactoring	refactor(proxy): simplify request handling
perf	Performance-Verbesserung	perf(db): optimize query performance
test	Tests	test(auth): add unit tests for login
chore	Wartungsarbeiten	chore(deps): update poetry dependencies
ci	CI/CD Änderungen	ci: add pre-commit hooks
build	Build-System	build: update Docker configuration

Scopes (Optional):

Gängige Scopes für das KIVA LLM Gateway:

• auth - Authentifizierung/Autorisierung
• api - API-Endpunkte
• ui - Web-Dashboard
• proxy - Proxy-Server
• db - Datenbank-Änderungen
• docker - Docker/Deployment
• docs - Dokumentation

Breaking Changes:

Für inkompatible Änderungen:

git commit -m "feat(api): change user ID format

BREAKING CHANGE: User IDs are now UUIDs instead of integers.
This affects all API endpoints that return or accept user IDs."

Praktische Commit-Beispiele:

# Feature hinzufügen
git commit -m "feat(auth): implement OAuth2 integration

- Add OAuth2 provider configuration
- Support Google and Microsoft SSO
- Include user role mapping"

# Bugfix
git commit -m "fix(proxy): resolve timeout handling

Fixes #123 where long-running requests would fail
after 30 seconds instead of configured timeout."

# Dokumentation
git commit -m "docs(api): add rate limiting examples

- Include curl examples for rate limits
- Document error response formats
- Add troubleshooting section"

# Wartungsarbeiten
git commit -m "chore(deps): update Python dependencies

- Update FastAPI to v0.104.1
- Update PostgreSQL driver to v3.1.8
- Fix security vulnerabilities in dependencies"

Commit-Workflow:

# Änderungen staged hinzufügen
git add .

# Conventional Commit erstellen
git commit -m "feat(ui): add dark mode toggle

- Implement theme switcher in dashboard
- Store user preference in localStorage
- Add CSS variables for theme colors

Closes #456"

# Branch pushen
git push origin feature/ihr-feature-name

---

Tests hinzufügen

Mindestens 1 Test hinzuzufügen ist eine harte Anforderung für alle PRs.

Test-Struktur

Tests gehören in das tests/test_litellm/ Verzeichnis:

• Folgt der Struktur des litellm/ Verzeichnisses
• Nur gemockte Tests - keine echten LLM API-Aufrufe
• Beispiel: litellm/utils.py → tests/test_litellm/test_utils.py

Beispiel-Test

import pytest
from unittest.mock import Mock, patch
from litellm import completion

def test_completion_with_mock():
    """Test completion function with mocked response."""
    # Arrange
    mock_response = {
        "choices": [{"message": {"content": "Test response"}}]
    }

    # Act & Assert
    with patch('litellm.main.completion') as mock_completion:
        mock_completion.return_value = mock_response
        response = completion(
            model="gpt-4",
            messages=[{"role": "user", "content": "Hello"}]
        )
        assert response["choices"][0]["message"]["content"] == "Test response"

Tests ausführen

# Alle Unit-Tests
make test-unit

# Spezifische Testdatei
poetry run pytest tests/test_litellm/test_ihre_datei.py -v

# Tests mit Coverage
poetry run pytest tests/test_litellm/ --cov=litellm

---

Code-Qualitätsstandards

Wir folgen den LiteLLM Code-Standards:

Automatisierte Checks

# Alle Qualitätsprüfungen (entspricht CI)
make lint

# Einzelne Checks:
make format           # Black Code-Formatierung anwenden
make lint-ruff       # Ruff Linting
make lint-mypy       # MyPy Typprüfung
make check-circular-imports  # Zirkuläre Imports prüfen
make check-import-safety     # Import-Sicherheit prüfen

Tools im Detail

• Black: Konsistente Code-Formatierung
• Ruff: Linting und Code-Qualität (ersetzt Flake8, isort, etc.)
• MyPy: Statische Typprüfung
• Circular Import Detection: Verhindert problematische Abhängigkeiten
• Import Safety: Überprüft sichere Package-Imports

Code-Style Guidelines

# ✅ Gut: Type Hints verwenden
def process_request(data: dict) -> str:
    return data.get("message", "")

# ❌ Schlecht: Keine Type Hints
def process_request(data):
    return data.get("message", "")

# ✅ Gut: Descriptive Namen
user_api_key = "sk-123"
model_response = completion(...)

# ❌ Schlecht: Vage Namen
key = "sk-123"
resp = completion(...)

---

Dokumentation

Die Dokumentation ist ebenso wichtig wie der Code:

# Dokumentation lokal bearbeiten
cd kiva-impl-docs/kiva-impl-docs
mkdocs serve

# Änderungen in docs/ vornehmen
# Browser aktualisiert automatisch

Dokumentations-Beiträge

• Fehlerbehebungen und Klarstellungen
• Neue Tutorials und How-Tos
• Übersetzungen (aktuell DE, geplant: EN)
• Beispiel-Konfigurationen und Use Cases

---

Issue Management & Feature Requests

Issue erstellen

1. Issue öffnen mit entsprechendem Template
2. Klar beschreiben: Verbesserung, Fehler oder Feature-Anfrage
3. Details und Kontext bereitstellen
4. Reproduktionsschritte bei Bugs
5. Lösungsvorschläge wenn möglich

Issue-Kategorien

• 🐛 Bug Reports: Beschreiben Sie das Problem und Reproduktionsschritte
• 🚀 Feature Requests: Erklären Sie den Anwendungsfall und erwarteten Nutzen
• 📚 Documentation: Schlagen Sie Verbesserungen oder Klarstellungen vor
• 🧪 Testing: Erhöhen Sie die Testabdeckung
• 🔧 Maintenance: Code-Refactoring, Performance-Verbesserungen

Feature-Entwicklung Koordination

• Asynchron: Issue-Kommentare für Diskussionen
• Synchron: Regelmäßige Check-ins bei größeren Features
• Kanban-Board: Verfolgen Sie den Issue- und PR-Status

---

Pull Request einreichen

Checkliste vor Einreichen

Hier sind die Kernvoraussetzungen für jeden PR:

• Code-Qualitätsprüfungen bestanden:
• Unit Tests - make test-unit
• Linting / Formatierung - make lint
• Tests hinzugefügt - Mindestens 1 Test ist erforderlich
• Bereich abgegrenzt - Änderungen sollten 1 spezifisches Problem behandeln
• .env konfiguriert - Lokale Entwicklungsumgebung funktioniert
• Branch ist aktuell: git rebase main ausgeführt
• Funktionalität getestet: Lokales Setup funktioniert
• Dokumentation aktualisiert: README/Docs angepasst wenn nötig

PR erstellen

1. Branch pushen: git push origin ihr-feature-branch
2. PR auf GitHub/GitLab erstellen

3. PR-Template ausfüllen mit:

   • Klarer Beschreibung der Änderungen
   • Issue-Referenzen (#123)
   • Screenshots/Logs bei UI-Änderungen
   • Breaking Changes kennzeichnen

4. Review abwarten und Feedback umsetzen

5. Nach Freigabe wird automatisch gemergt

PR-Titel Format

PR-Titel folgen dem gleichen Conventional Commits Format:

feat(scope): Kurze Beschreibung der Änderung
fix(api): Behebung von timeout Problem
docs(readme): Aktualisierung der Installation
test(auth): Zusätzliche Tests für JWT
refactor(proxy): Code-Vereinfachung in Router
chore(deps): Update dependencies to latest versions

Beispiele für gute PR-Titel:

• feat(ui): implement dark mode for dashboard
• fix(db): resolve connection pool exhaustion
• docs(contributing): add conventional commits guidelines
• perf(proxy): optimize request routing performance

---

Häufige Probleme & Lösungen

Setup-Probleme

❌ ModuleNotFoundError: No module named 'aiohttp'

# Lösung: Proxy-Dependencies installieren
make install-proxy-dev
poetry run prisma generate

❌ Prisma client not generated

# Lösung: Prisma Client neu generieren
poetry run prisma generate
poetry run prisma migrate dev

❌ Permission denied bei Prisma Cache

# Lösung: Cache-Ordner löschen
rm -rf ~/.cache/prisma-python
poetry run prisma generate

Code-Qualität Probleme

❌ Linting-Fehler

1. make format ausführen (behebt automatisch viele Probleme)
2. Ruff-Fehler manuell beheben
3. MyPy Type-Hints hinzufügen

❌ Test-Fehler

• Mocks verwenden, keine echten API-Aufrufe
• Test-Isolierung sicherstellen
• Fixtures für Testdaten verwenden

❌ Import-Probleme

• Relative Imports vermeiden
• Zirkuläre Dependencies auflösen
• Type-Hints korrekt importieren

---

Architektur-Entscheidungen

Für größere Änderungen:

Architecture Decision Records (ADR)

Erstellen Sie ein ADR für:

• Neue Komponenten oder Services
• Änderungen an bestehenden Schnittstellen
• Performance-relevante Entscheidungen
• Sicherheits-relevante Änderungen

ADR Template

# ADR-XXX: Titel der Entscheidung

## Status
[Proposed | Accepted | Deprecated]

## Kontext
Welches Problem wird gelöst?

## Entscheidung
Was wurde entschieden?

## Konsequenzen
Welche Auswirkungen hat die Entscheidung?

## Alternativen
Welche Alternativen wurden betrachtet?

---

Release Prozess

Versionierung

Wir folgen Semantic Versioning:

• MAJOR: Breaking Changes
• MINOR: Neue Features (rückwärtskompatibel)
• PATCH: Bugfixes

Release Cycle

• Patch Releases: Nach Bedarf für kritische Bugfixes
• Minor Releases: Monatlich (geplant)
• Major Releases: Halbjährlich (geplant)

---

Hilfe & Support

Community Support

• 🐛 Issues: GitHub Issues für Bugs und Features
• 💬 Diskussionen: Issue-Kommentare für fachlichen Austausch
• 📧 Kontakt: Entwicklungsteam über Issues erreichen
• 🤝 Anderen helfen:
  • Teilen Sie Ihre Erfahrungen und Use Cases
  • Verbessern Sie FAQ und Troubleshooting-Guides

Nützliche Ressourcen

• 📚 LiteLLM Docs: https://docs.litellm.ai/
• 🐍 Poetry Docs: https://python-poetry.org/docs/
• 🔧 Make Commands: make help für verfügbare Befehle
• 🧪 Pytest Docs: https://docs.pytest.org/

Community Kanäle

GitHub

https://gitlab.opencode.de/baden-wuerttemberg/innenministerium

Meetings (geplant)

• Office Hours: Monatlich, für Community-Fragen
• Contributors Meeting: Quartalsweise, für Roadmap-Diskussionen

Lizenz

Alle Beiträge unterliegen der MIT Lizenz. Mit Ihrem Pull Request bestätigen Sie:

• Sie haben das Recht, den Code beizutragen
• Der Code unterliegt der MIT Lizenz
• Sie stimmen dem Developer Certificate of Origin (DCO) zu

Fragen?

Bei Fragen zum Contributing-Prozess:

1. Lesen Sie die FAQ
2. Kontaktieren Sie die Maintainer (siehe Kontakt)

---

Vielen Dank für Ihren Beitrag zum KIVA LLM Gateway! 🚀

Als souveräne KI-Gateway-Lösung lebt dieses Projekt von der Gemeinschaft. Ihre Beiträge helfen dabei, eine moderne, transparente und kooperative Verwaltungsdigitalisierung voranzutreiben.