Der LLM Client ist ein vielseitiges Python-Werkzeug, das eine einheitliche Schnittstelle für den Zugriff auf diverse KI-Anbieter wie OpenAI, Groq, Google Gemini und Ollama bietet. Die Software zeichnet sich durch eine automatische API-Erkennung aus, die bei fehlenden Schlüsseln flexibel auf eine lokale Ollama Instanz zurückgreift. Zu den technischen Highlights gehören präzise Token-Zählung, volle Async-Unterstützung sowie die Fähigkeit, während der Laufzeit dynamisch zwischen verschiedenen Providern zu wechseln. Dank einer sauberen Architektur auf Basis von Entwurfsmustern ermöglicht die Bibliothek zudem erweitertes Tool-Calling und den Upload verschiedenster Dateiformate. Die Bibliothek ermöglicht eine einfache Handhabung im Vergleich zu komplexeren Frameworks und bietet eine nahtlose Integration in Umgebungen wie Google Colab.

graph TD
    subgraph "Ein Code"
        CODE["client = LLMClient()<br/>response = client.chat_completion(messages)"]
    end

    subgraph "Vier APIs"
        OPENAI[OpenAI]
        GROQ[Groq]
        GEMINI[Gemini]
        OLLAMA[Ollama<br/>Lokal/Cloud]
    end

    subgraph "Viele Möglichkeiten"
        SWITCH[🔄 Provider wechseln]
        TOKENS[📊 Kosten überwachen]
        ASYNC[⚡ Async/Await]
        STREAM[🌊 Streaming]
        FILES[📎 Dateien senden]
    end

    CODE --> OPENAI
    CODE --> GROQ
    CODE --> GEMINI
    CODE --> OLLAMA

    GEMINI -.-> ASYNC
    GEMINI -.-> SWITCH
    GEMINI -.-> TOKENS
    GEMINI -.-> STREAM
    GEMINI -.-> FILES

    classDef codeClass fill:#e1f5ff,stroke:#01579b,stroke-width:3px,color:#000
    classDef apiClass fill:#e8f5e9,stroke:#1b5e20,stroke-width:2px,color:#000
    classDef featureClass fill:#fff9c4,stroke:#f57f17,stroke-width:2px,color:#000

    class CODE codeClass
    class OPENAI,GROQ,GEMINI,OLLAMA apiClass
    class SWITCH,TOKENS,ASYNC,STREAM,FILES featureClass

Loading

---

📑 Inhaltsverzeichnis

• Features
• Installation
• Schnellstart
• Verwendung
• Unterstützte APIs
• Dokumentation
• Tests
• Contributing
• Lizenz

🚀 Features

Kern-Features

• 🔍 Automatische API-Erkennung - Nutzt verfügbare API-Keys oder fällt auf Ollama zurück
• ⚙️ Einheitliches Interface - Eine Methode für alle LLM-Backends
• 🔄 Dynamischer Provider-Wechsel - Wechsel zwischen APIs zur Laufzeit ohne neues Objekt
• 🧩 Flexible Konfiguration - Modell, Temperatur, Tokens frei wählbar
• 🔐 Google Colab Support - Automatisches Laden von Secrets aus userdata
• 📦 Zero-Config - Funktioniert out-of-the-box mit Ollama
• 📊 Token-Zählung mit tiktoken - Präzise Token-Zählung für Kostenmanagement
• ⚡ Vollständige Async-Unterstützung - Async/await für alle Provider
• 📁 Konfigurationsdateien - YAML/JSON-Konfiguration für Multi-Provider-Setups

Architektur

• 🏗️ Strategy Pattern - Saubere Architektur mit Provider-Klassen
• 🏭 Factory Pattern - Zentrale Provider-Erstellung und -Verwaltung

---

⚙️ Installation

Schnellinstallation

pip install git+https://github.com/dgaida/llm_client.git

Entwicklungsinstallation

git clone https://github.com/dgaida/llm_client.git
cd llm_client
pip install -e ".[dev]"

Mit llama-index Support

pip install -e ".[llama-index]"

Mit allen Features

pip install -e ".[all]"

---

🚦 Schnellstart

from llm_client import LLMClient

# Automatische API-Erkennung
client = LLMClient()

messages = [
    {"role": "system", "content": "Du bist ein hilfreicher Assistent."},
    {"role": "user", "content": "Erkläre Machine Learning in einem Satz."}
]

response = client.chat_completion(messages)
print(response)

Jupyter Notebook

Für einen umfassenden Überblick teste das Jupyter Notebook llm_client_example.ipynb auf Google Colab.

---

🔧 Konfiguration

API-Keys einrichten

Erstelle secrets.env:

# OpenAI
OPENAI_API_KEY=sk-xxxxxxxx

# Oder Groq
GROQ_API_KEY=gsk-xxxxxxxx

# Oder Google Gemini
GEMINI_API_KEY=AIzaSy-xxxxxxxx

Ohne API-Keys: Verwendet automatisch lokales Ollama (Installation erforderlich).

Google Colab

In Colab werden Keys automatisch aus userdata geladen:

# Secrets → OPENAI_API_KEY, GROQ_API_KEY oder GEMINI_API_KEY hinzufügen
from llm_client import LLMClient
client = LLMClient()  # Lädt automatisch aus userdata

---

📚 Verwendung

📊 Token-Zählung

Zähle Tokens präzise für Kostenmanagement und Context-Limits. → Details

token_count = client.count_tokens(messages)
print(f"Nachrichten enthalten {token_count} Tokens")

---

⚡ Async-Unterstützung

Nutze async/await für nicht-blockierende Operationen. → Details

async_client = LLMClient(use_async=True)
response = await async_client.achat_completion(messages)

---

📁 Konfigurationsdateien

Verwalte mehrere Provider-Konfigurationen einfach via YAML/JSON. → Details

client = LLMClient.from_config("llm_config.yaml")

---

🌊 Response-Streaming

Streame Antworten in Echtzeit für bessere UX. → Details

for chunk in client.chat_completion_stream(messages):
    print(chunk, end="", flush=True)

---

🔄 Provider-Wechsel

Wechsle zwischen APIs zur Laufzeit. → Details

client.switch_provider("gemini", llm="gemini-2.5-flash")

---

🧰 Tool-Calling

Nutze Function/Tool Calling für alle Provider. → Details

result = client.chat_completion_with_tools(messages, tools)

---

📎 Datei-Upload

Sende Bilder, PDFs und andere Dateien mit Chat-Anfragen. → Details

response = client.chat_completion_with_files(
    messages,
    files=["image.jpg", "document.pdf"]
)

---

☁️ Ollama Cloud

Nutze leistungsstarke Cloud-Modelle ohne lokale GPU. → Details

client = LLMClient(llm="gpt-oss:120b-cloud")

---

🧩 Unterstützte APIs & Default-Modelle

API	Default-Modell	Bemerkung
OpenAI	gpt-4o-mini	Schnell, zuverlässig
Groq	moonshotai/kimi-k2-instruct-0905	Sehr effizient auf GroqCloud
Gemini	gemini-2.0-flash-exp	Googles neuestes Modell (Dez 2024)
Ollama	llama3.2:1b	Läuft lokal, kein API-Key nötig

Ollama Installation

# macOS/Linux
curl -fsSL https://ollama.ai/install.sh | sh

# Windows
# Download von https://ollama.ai/download

# Modell herunterladen
ollama pull llama3.2:1b

---

📖 Dokumentation

Getting Started

• Installation & Setup
• Schnellstart-Guide
• API-Referenz

Features

• Token-Zählung
• Async-Unterstützung
• Konfigurationsdateien
• Response-Streaming
• Provider-Wechsel
• Tool-Calling
• Datei-Upload

Provider-Guides

• OpenAI
• Groq
• Google Gemini
• Ollama (lokal)
• Ollama Cloud

Weitere Ressourcen

• CLI-Nutzung
• Troubleshooting
• CHANGELOG
• Contributing Guidelines

---

🏗️ Projekt-Architektur

Das Projekt verwendet ein Strategy Pattern mit klarer Trennung von Verantwortlichkeiten:

llm_client/
├── base_provider.py      # Abstract Base Class für alle Provider
├── providers.py          # Konkrete Provider-Implementierungen
│   ├── OpenAIProvider
│   ├── GroqProvider
│   ├── GeminiProvider
│   └── OllamaProvider
├── async_providers.py    # Async Provider-Implementierungen
│   ├── AsyncOpenAIProvider
│   ├── AsyncGroqProvider
│   └── AsyncGeminiProvider
├── provider_factory.py   # Factory für Provider-Erstellung
├── llm_client.py        # Hauptklasse (verwendet Strategy Pattern)
├── adapter.py           # llama-index Integration
├── token_counter.py     # Token-Zähl-Utilities
├── config.py            # Konfigurationsdatei-Unterstützung
└── exceptions.py        # Custom Exception-Klassen

Design Principles

1. Strategy Pattern: Verschiedene LLM-APIs als austauschbare Strategien
2. Factory Pattern: Zentrale Provider-Erstellung und -Konfiguration
3. Single Responsibility: Jede Klasse hat eine klar definierte Aufgabe
4. Dependency Injection: Provider werden in LLMClient injiziert
5. Extensibility: Neue APIs können leicht hinzugefügt werden

---

🧪 Tests ausführen

# Alle Tests
pytest

# Mit Coverage
pytest --cov=llm_client --cov-report=html

# Einzelne Test-Datei
pytest tests/test_llm_client.py -v

Siehe docs/TESTING.md für Details.

---

👥 Contributing

Beiträge sind willkommen! Siehe CONTRIBUTING.md für Details.

---

📄 Lizenz

MIT License - siehe LICENSE

© 2026 Daniel Gaida, Technische Hochschule Köln

---

🔗 Weiterführende Links

• Ollama Dokumentation
• OpenAI API Reference
• Groq Cloud
• Google Gemini API
• Gemini OpenAI Compatibility
• llama-index Docs
• Andrew Ng's AISuite

---

⭐ Support

Wenn Ihnen dieses Projekt gefällt, geben Sie ihm einen Stern auf GitHub!

Fragen? Öffnen Sie ein Issue.