SDK Migrations-Leitfaden (v0.7 → v1.0)¶

Aktualisieren Sie Ihren elluminate SDK-Code auf die neue v1.0 API

SDK v1.0 führt wesentliche Verbesserungen für die Entwicklererfahrung ein:

Separate sync/async Clients - Keine a-Präfixe mehr bei async-Methoden
Rich Models mit Methoden - collection.add_many() statt client.template_variables.add_many(collection=...)
Top-Level Convenience-Methoden - client.create_collection() statt client.collections.create()
Sauberere API - Konsistente Muster, bessere Auffindbarkeit

Schnellreferenz¶

v0.7	v1.0
`client.experiments.get(name)`	`client.get_experiment(name=...)`
`client.experiments.get_by_id(id)`	`client.get_experiment(id=...)`
`client.experiments.aget(name)`	`await async_client.get_experiment(name=...)`
`client.collections.create(name="x")`	`client.create_collection("x")`
`client.template_variables.add_many(collection=c, ...)`	`collection.add_many(...)`
`client.experiments.run(experiment)`	`client.run_experiment(...)`
`response.messages[-1].content`	`response.response_str`
`rating.rating.value == "yes"`	`rating.rating == RatingValue.YES`

Schritt 1: Imports aktualisieren¶

Sync-Verwendung (unverändert)¶

from elluminate import Client

Async-Verwendung (neues Muster)¶

# Async-Verwendung erfordert jetzt AsyncClient
from elluminate import AsyncClient

Schritt 2: Client-Verwendung aktualisieren¶

Sync Client (unverändert)¶

# v0.7
client = Client(api_key="...", project_id=123)

# v1.0 - Gleich!
client = Client(api_key="...", project_id=123)

Async Client (neues Muster)¶

# v0.7 - Verwendete denselben Client mit a-präfixierten Methoden
client = Client()
template = await client.prompt_templates.aget_or_create(...)
experiment = await client.experiments.acreate(...)

# v1.0 - Verwenden Sie separaten AsyncClient, gleiche Methodennamen
async_client = AsyncClient()
template, _ = await async_client.get_or_create_prompt_template(...)
experiment = await async_client.create_experiment(...)

Schritt 3: Ressourcen-Operationen aktualisieren¶

Collections¶

# v0.7
collection = client.collections.create(name="Test Cases")
client.template_variables.add_many(
    collection=collection,
    variables=[{"topic": "KI"}, {"topic": "ML"}]
)

# v1.0
collection = client.create_collection("Test Cases")
collection.add_many(variables=[
    {"topic": "KI"},
    {"topic": "ML"},
])

Get or Create Muster¶

Die get_or_create-Methoden verwenden jetzt ein defaults-Dict für Parameter, die nur bei der Erstellung verwendet werden:

# v0.7
collection, created = client.collections.get_or_create(name="Test Cases")

# v1.0 - Verwendet defaults Dict für Erstellungs-Parameter
collection, created = client.get_or_create_collection(
    name="Test Cases",
    defaults={"description": "Meine Testfälle"},
)

Prompt Templates¶

# v0.7
template, created = client.prompt_templates.get_or_create(
    name="Mein Template",
    template="Schreibe über {{topic}}",
)

# v1.0 - messages ist Teil der Suche
# Wenn Name+Inhalt übereinstimmen: gibt existierende Version zurück
# Wenn Name existiert aber Inhalt abweicht: erstellt NEUE Version
template, created = client.get_or_create_prompt_template(
    name="Mein Template",
    messages=[{"role": "user", "content": "Schreibe über {{topic}}"}],
)

Criterion Sets¶

# v0.7
criterion_set = client.criterionsets.create(name="Qualität")
client.criteria.create(
    criterion_set=criterion_set,
    name="Klarheit",
    description="Ist es klar?"
)

# v1.0
criterion_set = client.create_criterion_set("Qualität")
criterion_set.add_criteria([
    "Ist es klar?",
    "Ist es korrekt?",
])

Schritt 4: Experiment-Workflow aktualisieren¶

Experimente erstellen und ausführen¶

# v0.7
experiment = client.experiments.create(
    name="Test v1",
    prompt_template=template,
    collection=collection,
    criterion_set=criterion_set,
    llm_config="gpt-4",
)
result = client.experiments.run(experiment)

# v1.0 - Verwenden Sie run_experiment() Shortcut (erstellt + führt in einem Aufruf aus)
from elluminate.schemas import RatingMode

result = client.run_experiment(
    name="Test v1",
    prompt_template=template,
    collection=collection,
    criterion_set=criterion_set,
    llm_config="gpt-4",
    rating_mode=RatingMode.DETAILED,  # FAST oder DETAILED (mit Begründung)
)

Schritt 5: Async-Methodenaufrufe aktualisieren¶

Alle a-präfixierten Methoden werden durch normale Methodennamen auf AsyncClient ersetzt:

# v0.7
client = Client()
template = await client.prompt_templates.aget(name)
experiments = await client.experiments.alist()
collection = await client.collections.acreate(name="Test")

# v1.0
async_client = AsyncClient()
template = await async_client.get_prompt_template(name)
experiments = await async_client.list_experiments()
collection = await async_client.create_collection("Test")

v0.7	v1.0
`client.X.aget(...)`	`await async_client.get_X(...)`
`client.X.alist(...)`	`await async_client.list_X()`
`client.X.acreate(...)`	`await async_client.create_X(...)`
`client.X.aget_or_create(...)`	`await async_client.get_or_create_X(...)`

Schritt 6: Response- und Rating-Zugriff aktualisieren¶

Response-Inhalt abrufen¶

# v0.7 - Manuelle Nachrichten-Extraktion
for response in experiment.rated_responses:
    content = response.messages[-1].content

# v1.0 - Verwenden Sie die response_str Property
for response in experiment.responses():
    content = response.response_str  # Sauberer, behandelt Randfälle

Rating-Vergleiche¶

# v0.7 - String-Vergleich (fehleranfällig)
for rating in response.ratings:
    if rating.rating.value == "yes":  # Groß-/Kleinschreibung beachten!
        passed += 1

# v1.0 - Verwenden Sie RatingValue Enum (typsicher)
from elluminate.schemas import RatingValue

for rating in response.ratings:
    if rating.rating == RatingValue.YES:  # IDE-Autovervollständigung, erkennt Tippfehler
        passed += 1

Vollständiges Vorher/Nachher-Beispiel¶

Vorher (v0.7)¶

from elluminate import Client

client = Client()

# Ressourcen abrufen oder erstellen
template, _ = client.prompt_templates.get_or_create(
    name="Zusammenfasser",
    template="Fasse zusammen: {{text}}",
)

collection, _ = client.collections.get_or_create(name="Testtexte")
client.template_variables.add_many(
    collection=collection,
    variables=[
        {"text": "Langer Artikel über KI..."},
        {"text": "Technische Dokumentation..."},
    ]
)

criterion_set, _ = client.criterionsets.get_or_create(name="Zusammenfassungs-Qualität")
client.criteria.create(
    criterion_set=criterion_set,
    description="Ist die Zusammenfassung prägnant?",
)

# Experiment erstellen und ausführen
experiment = client.experiments.create(
    name="Zusammenfassungs-Test",
    prompt_template=template,
    collection=collection,
    criterion_set=criterion_set,
    llm_config="gpt-4",
)
result = client.experiments.run(experiment)

print(f"Durchschnitt: {result.average_rating:.2%}")

Nachher (v1.0)¶

from elluminate import Client

client = Client()

# Ressourcen abrufen oder erstellen
template, _ = client.get_or_create_prompt_template(
    name="Zusammenfasser",
    messages=[{"role": "user", "content": "Fasse zusammen: {{text}}"}],
)

collection, _ = client.get_or_create_collection(
    name="Testtexte",
    defaults={"description": "Testtexte für Zusammenfassungen"},
)
collection.add_many(variables=[
    {"text": "Langer Artikel über KI..."},
    {"text": "Technische Dokumentation..."},
])

criterion_set, _ = client.get_or_create_criterion_set(
    name="Zusammenfassungs-Qualität",
    defaults={"description": "Qualitätskriterien für Zusammenfassungen"},
)
criterion_set.add_criteria(["Ist die Zusammenfassung prägnant?"])

# Experiment ausführen (Shortcut)
result = client.run_experiment(
    name="Zusammenfassungs-Test",
    prompt_template=template,
    collection=collection,
    criterion_set=criterion_set,
    llm_config="gpt-4",
)

print(f"Durchschnitt: {result.average_rating:.2%}")

Migrations-Checkliste¶

Imports¶

[ ] from elluminate import AsyncClient hinzufügen, wenn async verwendet wird
[ ] from elluminate.schemas import RatingValue für Rating-Vergleiche hinzufügen

Client-Verwendung¶

[ ] Sync Client() Verwendung beibehalten (unverändert)
[ ] Async-Methodenaufrufe durch AsyncClient() ersetzen

Collections¶

[ ] client.collections.create(name="X") → client.create_collection("X")
[ ] client.collections.get_or_create(name="X") → client.get_or_create_collection("X", defaults={...})
[ ] client.template_variables.add_many(collection=c, ...) → collection.add_many(...)

Prompt Templates¶

[ ] client.prompt_templates.get_or_create(...) → client.get_or_create_prompt_template(...)
[ ] client.prompt_templates.get(name=X) → client.get_prompt_template(X)

Criterion Sets¶

[ ] client.criterionsets.create(name="X") → client.create_criterion_set("X")
[ ] client.criteria.create(criterion_set=cs, ...) → criterion_set.add_criteria([...])

Experimente¶

[ ] client.experiments.create(...) → client.create_experiment(...)
[ ] client.experiments.run(exp) → client.run_experiment(...)

Async-Methoden¶

[ ] Alle a-präfixierten Methoden durch AsyncClient + normale Methoden ersetzen
[ ] client.X.aget(...) → await async_client.get_X(...)
[ ] client.X.acreate(...) → await async_client.create_X(...)

Response- und Rating-Zugriff¶

[ ] response.messages[-1].content → response.response_str
[ ] rating.rating.value == "yes" → rating.rating == RatingValue.YES

Exception-Handling (Sicherheit)¶

[ ] exception.response → exception.response_info
[ ] exception.response.status_code → exception.response_info.status_code
[ ] exception.response.json() → exception.response_info.body
[ ] Entfernen Sie Code, der auf exception.response.request.headers zugreift
[ ] Aktualisieren Sie Error-Logging zur Verwendung von bereinigtem response_info

FAQ¶

Muss ich sofort migrieren?¶

Nein. v0.7.x erhält Sicherheitsupdates für 6 Monate nach dem v1.0-Release.

Was, wenn ich nur sync-Methoden verwende?¶

Die Migration ist einfacher - hauptsächlich Änderung von ressourcenbasierten zu Top-Level-Methoden:

client.collections.create() → client.create_collection()
client.experiments.run(e) → client.run_experiment(...)

Gibt es Breaking Changes im Verhalten?¶

Ja, einige:

get_or_create_*()-Methoden verwenden jetzt defaults-Dict für Erstellungs-Parameter
get_or_create_prompt_template() erstellt eine neue Version, wenn der Messages-Inhalt abweicht
Verwenden Sie run_experiment(), um Experimente in einem Aufruf zu erstellen und auszuführen
Exception-Handling geändert (siehe unten)

Schritt 7: Exception-Handling aktualisieren¶

Breaking Change: Exceptions exponieren aus Sicherheitsgründen nicht mehr das vollständige HTTP-Response-Objekt.

# v0.7
try:
    client.get_experiment(id=999)
except APIError as e:
    print(e.response.status_code)

# v1.0
try:
    client.get_experiment(id=999)
except APIError as e:
    print(e.response_info.status_code)  # Verwenden Sie response_info

Was hat sich geändert:

v0.7	v1.0
`e.response.status_code`	`e.response_info.status_code`
`e.response.json()`	`e.response_info.body`
`e.response.request.headers`	❌ Nicht verfügbar

Dies verhindert versehentliches Leaken von API-Keys in Logs und Error-Tracking-Services.