Skip to main content

EVREN

evren-sdk

EVREN Yapay Zeka Platformu — Resmi Python SDK

PyPI Python License Tests GPU

Türkçe · English · Examples · Changelog



🇹🇷 Türkçe

EVREN Yapay Zeka Platformu'nun resmi Python SDK'sı: platformda eğitilmiş bilgisayarlı görü modelleriyle çıkarım ve EVREN LLM geçidi (sohbet, akış, embedding, rerank).

Nesne tespiti · Sınıflandırma · Segmentasyon · OBB · Keypoint · Edge Inference · LLM Geçidi


Mimari

EVREN SDK mimarisi

Tek bir predict() çağrısının arkasında 8× NVIDIA A6000 GPU çalışır. Kullanıcı altyapı yönetmez — pip install ve 3 satır kod yeter.

Kurulum

pip install evren-sdk            # temel SDK
pip install evren-sdk[edge]      # + OpenCV (kamera/video)

Hızlı Başlangıç

from evren_sdk import EvrenClient

client = EvrenClient(api_key="evren_xxxxx")
result = client.predict("kullanici/model-adi", "foto.jpg", confidence=0.3)

for det in result.predictions:
    print(f"{det.class_name}: {det.confidence:.0%}  bbox={det.bbox}")

Daha fazla örnek için examples/ dizinine bakın.

Kimlik Doğrulama

Platformda Ayarlar → API Anahtarları sayfasından anahtar oluşturun. Anahtar evren_ ön eki ile başlar.

client = EvrenClient(api_key="evren_xxxxx")    # API anahtarı (önerilen)
client = EvrenClient(api_key="eyJhbGci...")    # JWT token

Çıkarım Akışı

Çıkarım akışı

Tekil Çıkarım

result = client.predict(
    model="kullanici/model-adi",        # slug, slug:tag veya UUID
    image="resim.jpg",                  # dosya yolu, Path veya bytes
    confidence=0.25,
    iou=0.45,
    image_size=640,
    classes=["araba", "insan"],         # isteğe bağlı
)
model Formatı Açıklama
"owner/slug" Son versiyonu otomatik çözer
"owner/slug:v2.0" Belirli versiyon etiketi
"019cec..." (UUID) Doğrudan versiyon ID

Toplu Çıkarım (Batch)

batch = client.predict_batch(
    model="kullanici/model-adi",
    images=["img1.jpg", "img2.jpg", "img3.jpg"],
    confidence=0.3,
)

for r in batch:
    print(f"{r.count} tespit, {r.inference_ms:.0f} ms")

Bkz. examples/02_batch_inference.py

Sonuç İşleme & Export

result = client.predict("kullanici/model", "sahne.jpg")

# filtrele
filtre = result.filter(min_confidence=0.5, classes=["araba"])

# export
result.to_yolo()          # YOLO txt format
result.to_coco()          # COCO dict list
result.to_csv()           # CSV string

# dosyaya kaydet (format uzantıdan anlaşılır)
result.save("sonuc.json")
result.save("sonuc.csv")
result.save("labels.txt")

Detay: examples/03_result_export.py

Model Bilgileri & Warmup

# sınıfları listele
info = client.model_classes("kullanici/model-adi")
for cls in info.classes:
    print(f"  {cls.name}: {cls.color}")

# mevcut modelleri listele
for m in client.list_models():
    print(f"{m.full_slug} — {m.architecture}")

# GPU'ya ön-yükleme (cold-start elimine)
client.warmup(["kullanici/model-adi"])

Performans Testi

bench = client.benchmark("kullanici/model", "test.jpg", rounds=20)

print(f"Avg: {bench.avg_ms:.1f}ms  |  p95: {bench.p95_ms:.1f}ms")
print(f"Min: {bench.min_ms:.1f}ms  |  Max: {bench.max_ms:.1f}ms")
print(f"Throughput: {bench.throughput_fps:.1f} FPS")

→ examples/04_benchmark.py

Model İndirme

path = client.download_model("kullanici/model", output="weights/", fmt="onnx")
print(f"Kaydedildi: {path}")   # weights/best.onnx

Veri Setine Görsel Yükleme

SDK üzerinden yeni bir veri seti açıp doğrudan görsel yükleyebilirsiniz.

ds = client.create_dataset("sahne-verisi")   # varsayılan: private, VISION
resp = client.upload_to_dataset(dataset_id=ds["id"], image="yeni_gorsel.jpg")

Metin ve Ses Veri Setlerini Yükleme

Kayıtlar etiketleri (labels), NER aralıkları (entities) ve hücre düzeltmeleriyle birlikte gelir. Ses setlerinde ses sütunu HF Audio düzenindedir ({"bytes", "path"}). Gerekli ek: pip install "evren-sdk[datasets]".

train = client.load_dataset("sahip/veri-seti", split="train")   # pyarrow.Table
df = train.to_pandas()

for row in client.iter_dataset("sahip/veri-seti", split="test"):  # indirmeden akışla
    print(row["item_id"], row["labels"])

client.download_dataset("sahip/veri-seti", "veri/", format="jsonl")  # parquet, jsonl, csv

from evren_sdk.datasets import to_hf
ds = to_hf(client.load_dataset("sahip/veri-seti", version="v1"))  # HF DatasetDict

İlk çağrıda platform dışa aktarımı hazırlar (görsel setlerle aynı dışa aktarım kredisi); aynı içerik sonraki çağrılarda ücretsiz ve yerel önbellekten gelir. Dosyalar SHA-256 ile doğrulanır.

Asenkron Kullanım

import asyncio
from evren_sdk import AsyncEvrenClient

async def main():
    async with AsyncEvrenClient(api_key="evren_xxxxx") as client:
        result = await client.predict("kullanici/model", "foto.jpg")
        batch  = await client.predict_batch("kullanici/model", ["a.jpg", "b.jpg"])

asyncio.run(main())

Paralel pipeline için examples/07_async_pipeline.py

LLM Geçidi (Sohbet, Akış, Embedding, Rerank, Karar, OCR, Ses)

EvrenLLMClient, EVREN LLM geçidine (evren-llmapi.ssyz.org.tr) bağlanır. Görü istemcisinden ayrıdır ve evren_llm_... ile başlayan LLM anahtarı kullanır. Anahtar verilmezse EVREN_LLM_API_KEY ortam değişkeninden okunur.

from evren_sdk import EvrenLLMClient

with EvrenLLMClient() as llm:                       # EVREN_LLM_API_KEY
    print(llm.list_models())

    r = llm.chat("glm-5.3", [{"role": "user", "content": "Merhaba"}], max_tokens=512)
    print(r.content)          # yanıt metni (hiçbir zaman None değildir)
    print(r.reasoning)        # düşünen modellerde düşünme metni
    print(r.usage)            # token kullanımı
    print(r.request_id)       # destek talebinde paylaşın

    # akış — yalnızca metin
    for parca in llm.chat_stream("deepseek-v4.1-flash", [{"role": "user", "content": "Bir şiir yaz"}]):
        print(parca, end="", flush=True)

    # akış — ayrıntılı: düşünme metni, araç çağrıları, son parçada kullanım
    for d in llm.stream("glm-5.3", [{"role": "user", "content": "2+2?"}]):
        if d.reasoning: ...
        if d.content: print(d.content, end="")
        if d.usage: print("\n", d.usage)

    vektorler = llm.embed("qwen3-embedding-8b", ["merhaba", "dünya"])
    sirali = llm.rerank("qwen3-reranker-8b", "Türkiye'nin başkenti",
                        ["Paris Fransa'dadır", "Ankara başkenttir"], top_n=1)

Araç çağrısı (function calling) OpenAI biçimiyle çalışır; sonuç r.tool_calls alanındadır:

tools = [{"type": "function", "function": {"name": "hava", "parameters": {
    "type": "object", "properties": {"sehir": {"type": "string"}}, "required": ["sehir"]}}}]
r = llm.chat("glm-5.3", [{"role": "user", "content": "Ankara'da hava nasıl?"}], tools=tools)
for call in r.tool_calls:
    print(call["function"]["name"], call["function"]["arguments"])

Güvenilirlik. 429, 502, 503, 504 ve bağlantı hatalarında istemci Retry-After başlığına uyarak otomatik tekrar dener (max_retries=2). Akışsız her çağrıya bir Idempotency-Key eklenir; tekrar denenen istek geçitte tekilleştirilir, çift çalıştırılmaz ve çift ücretlendirilmez. Akışlar yalnızca istek modele ulaşmadan reddedildiyse (429/503) tekrar denenir. Akış yarıda kesilirse LLMServiceError (code="stream_interrupted") fırlatılır; eksik yanıt tamamlanmış gibi dönmez. Günlük kota dolduğunda geçit Retry-After değerini gün sonuna kadar verir; bu durumda (30 sn'den uzun bekleme) tekrar denenmez, LLMRateLimitError hemen döner.

from evren_sdk import EvrenLLMError, LLMRateLimitError

try:
    llm.chat("glm-5.3", mesajlar)
except LLMRateLimitError as e:
    print(e.retry_after, e.evren.get("resets_at"))
except EvrenLLMError as e:
    print(e.status_code, e.code, e.request_id, e.evren)

Asenkron kullanım için AsyncEvrenLLMClient aynı yüzeyi sunar (await llm.chat(...), async for parca in llm.chat_stream(...)).

Tipli Karar, OCR, Ses ve Kota

Karar modelleri (laya, clef) metin üretmez; bir metin (ve clef'te görsel) için tanımladığınız choice, score ve noul (evet/hayır) sorularını tek geçişte olasılıklarıyla yanıtlar. Hangi modelin hangi işi yaptığı llm.models() içindeki task alanında yazar (decision, ocr, audio_transcription ...). Laya her soruda instructions ister; iki modelde de çalışması için her soruya yazın.

from evren_sdk import EvrenLLMClient, encode_image

with EvrenLLMClient() as llm:
    r = llm.decide("clef", "Faturamdan iki kez ücret çekildi, iade etmezseniz iptal edeceğim.", {
        "birim": {"type": "choice", "instructions": "Hangi birim?",
                  "criteria": {"fatura": "ödeme, iade", "teknik": "hata, kesinti"}},
        "aciliyet": {"type": "score", "instructions": "Ne kadar acil?",
                     "criteria": ["acil değil", "yakında", "kritik"]},
        "iptal": {"type": "noul", "instructions": "İptal tehdidi var mı?"},
    })
    print(r.choice("birim"), r.score("aciliyet"), r.noul("iptal"), r.probabilities("birim"))

    # clef görsel de okur (en fazla 4). Görsel küçültülmeden okunur: 32×32 piksellik
    # her karo 1 token (1024 px ≈ 1.000, 4000 px ≈ 15.600) — büyük fotoğrafı küçültün:
    belge = encode_image("fatura.jpg", max_side=1024)   # pip install evren-sdk[images]
    r = llm.decide("clef", "Ekteki belgeyi incele.", {
        "okunakli": {"type": "noul", "instructions": "Toplam tutar okunaklı mı?"},
    }, images=[belge])

    # laya: aynı soruları 64 metne tek çağrıda (clef'te toplu uç yok)
    toplu = llm.decide_batch("laya", ["Şifremi unuttum", "Fiyat teklifi istiyorum"], {
        "birim": {"type": "choice", "instructions": "Hangi birim?",
                  "criteria": {"teknik": "giriş, hata", "satis": "fiyat, paket"}},
    })
    print([x.choice("birim") for x in toplu.results])

    print(llm.ocr("dots-ocr", "fis.png").text)                       # görselden metin
    print(llm.transcribe("qwen3-asr-1.7b", "toplanti.wav", language="tr").text)
    altyazi = llm.transcribe("qwen3-asr-1.7b", "video.mp3", response_format="srt").text

    ses = llm.speak("voxcpm2", "Raporunuz hazır. Doğruluk oranı yüzde 94,7.",
                    voice="deniz")   # hazır sesler: deniz, ece, emre, kaan - ayrı isteklerde de aynı ses
    ses.save("rapor.mp3")  # mp3 (varsayılan), wav, flac, opus, pcm

    q = llm.quota()        # 5 dk pencere, günlük tavan, kredi
    qm = llm.quota(model="glm-5.3")   # + o modeldeki kullanım ve pay
    print(q.level, q.daily_remaining_tokens, q.concurrency_limit, qm.model_concurrent_requests)

    n = llm.response_input_tokens("glm-5.3", "Uzun belge özeti", instructions="Kısa yanıt ver.")
    print(n.input_tokens)  # ücretsiz uç — göndermeden önce girdi token sayısı

    yanit = llm.respond("glm-5.3", "Türkiye'nin başkenti?")          # Responses API
    devam = llm.respond("glm-5.3", "Nüfusu?", previous_response_id=yanit.id)
    print(devam.output_text)

    m = llm.moderate("Denetlenecek metin")                          # ücretsiz uç
    print(m.flagged, m.categories)
    toplu = llm.moderate(["birinci metin", "ikinci metin"])          # metin başına bir karar
    print([r.flagged for r in toplu.results])

Kullanım Şartları Kapısı

Geçit, hesap başına bir kez kullanım şartlarının onaylanmasını ister; onaysızken her çağrı 403 terms_not_accepted döner. SDK bu akışı yönetir:

with EvrenLLMClient() as llm:
    durum = llm.terms_status()          # kabul durumu + güncel sürüm
    if durum.needs_accept:
        print(llm.terms_text())         # kabul etmeden önce okuyun
        llm.accept_terms(durum.current_version)

SDK şartları sizin adınıza kendiliğinden onaylamaz; sürüm numarası bu yüzden zorunludur. Onaysız çağrılar LLMTermsNotAcceptedError fırlatır. Bu sınıf LLMAuthenticationError'dan türer, 403'ü yakalayan eski except blokları değişmeden çalışır. Yeni esaslı bir sürüm yayınlandığında geçit tekrar onay ister; terms_status().needs_accept ile kontrol edin.

Ses ucunda geçit Idempotency-Key desteklemediği için transcribe() yalnızca bağlantı hiç kurulamadıysa tekrar denenir. speak() için de aynısı geçerlidir; 4.096 karaktere kadar metni geçit cümle sınırlarından bölüp tek dosya döndürür. voice dört hazır sesten birini seçer (deniz, ece, emre, kaan; varsayılan default = deniz); aynı sesle yapılan ayrı çağrılar aynı konuşmacıyla okunur. instructions (İngilizce tarif) verilirse ses tarife göre üretilir ve çağrılar arasında birebir aynı ses garanti edilmez.

Edge Modu (GPU'suz Cihazlar)

GPU olmayan cihazlarda (Raspberry Pi, laptop, endüstriyel PC) gerçek zamanlı çıkarım. Çıkarım EVREN GPU'larında çalışır — lokal deneyim hissi verir.

Edge modu akışı

pip install evren-sdk[edge]
from evren_sdk import EvrenCamera

cam = EvrenCamera("evren_...", "kullanici/model", confidence=0.3)

cam.run(0)                                      # webcam, ESC ile kapat
cam.record("input.mp4", "output.mp4")           # video işle + kaydet

for frame, result in cam.stream(0):             # kendi loop'unuz
    print(f"{result.count} tespit")

for path, result in cam.scan("images/"):        # klasör tarama
    print(f"{path.name}: {result.count} nesne")
Parametre Varsayılan Açıklama
max_fps 15.0 Bant genişliği koruma limiti
jpeg_quality 70 Sıkıştırma kalitesi (20-95)
draw True Tahminleri frame üzerine çiz
confidence 0.25 Minimum güven eşiği

Bkz. examples/05_edge_camera.py

Hata Yönetimi

from evren_sdk import (
    EvrenClient, InsufficientCreditsError,
    NotFoundError, RateLimitError, InferenceError,
)

client = EvrenClient(api_key="evren_xxxxx")

try:
    result = client.predict("kullanici/model", "test.jpg")
except InsufficientCreditsError as e:
    print(f"Kredi yetersiz — gerekli: {e.required}, bakiye: {e.available}")
except NotFoundError:
    print("Model bulunamadı")
except RateLimitError as e:
    time.sleep(e.retry_after)
except InferenceError:
    print("GPU sunucusu geçici olarak kullanılamıyor")
Exception HTTP Açıklama
AuthenticationError 401, 403 Geçersiz veya süresi dolmuş anahtar
InsufficientCreditsError 402 Kredi bakiyesi yetersiz
NotFoundError 404 Model veya versiyon bulunamadı
ValidationError 422 Hatalı parametre
RateLimitError 429 İstek limiti aşıldı
InferenceError 502, 503 GPU sunucusu hatası

Her çıkarım kredi tüketir. Bakiye yetersizse SDK InsufficientCreditsError fırlatır — e.required ve e.available alanları bakiye bilgisini taşır.

API Referansı

Veri Modelleri
Sınıf Alanlar / Metotlar
PredictResult predictions, inference_ms, count, image_width, image_height
↳ metotlar filter(), to_yolo(), to_coco(), to_csv(), save()
Prediction class_name, confidence, bbox, color, mask, keypoints, obb
↳ metotlar to_dict()
BatchResult results, total_ms, count — iterable, len() destekler
BenchmarkResult model, rounds, avg_ms, min_ms, max_ms, p95_ms, throughput_fps
ModelClasses classes, architecture, model_name, total, imgsz — in operatörü
↳ metotlar names()
ModelInfo id, name, slug, architecture, owner_username, full_slug
ModelVersion id, version_tag, framework, metrics, weights_url
ClassInfo name, color
EvrenCamera stream(), run(), scan(), record(), stats
Client Metotları
Metot Açıklama
predict(model, image, **kw) Tekil çıkarım
predict_batch(model, images, **kw) GPU batch çıkarım
model_classes(model) Model sınıfları, mimari, imgsz
warmup(models) GPU ön-yükleme
list_models(limit) Mevcut modelleri listele
list_versions(model_id) Model versiyonlarını listele
resolve(slug) Slug → version UUID çözümle
benchmark(model, image, **kw) Performans testi
download_model(model, output, fmt) Ağırlık dosyası indir
create_dataset(name, visibility=, license=, tags=) Yeni veri seti oluştur
upload_to_dataset(dataset_id, image) Veri setine görsel yükle

AsyncEvrenClient aynı API'yi async/await ile sunar.

LLM İstemcisi Metotları
Metot Uç Dönüş
chat(model, messages, **kw) /v1/chat/completions ChatCompletionResult
stream() / chat_stream() /v1/chat/completions (SSE) ChatDelta / str
embed(model, texts) /v1/embeddings list[list[float]]
rerank(model, query, documents, top_n) /v1/rerank list[RerankResult]
decide(model, state, questions, images=) /v1/systemone DecisionResult
decide_batch(model, states, questions) /v1/systemone/batch DecisionBatchResult
ocr(model, image) /v1/ocr OcrResult
transcribe(model, audio, response_format=) /v1/audio/transcriptions Transcription
speak(model, text, voice=, response_format=, instructions=) /v1/audio/speech SpeechResult
respond(model, input, **kw) / get_response(id) /v1/responses ResponseResult
delete_response(id) / response_input_items(id, limit=, order=, after=) /v1/responses/{id} None / ResponseInputItems
moderate(input, model=None) /v1/moderations ModerationResult
terms_status() / terms_text() / accept_terms(version) /v1/terms/* TermsStatus / str / TermsAcceptance
response_input_tokens(model, input, **kw) /v1/responses/input_tokens InputTokensResult
models() / list_models() /v1/models list[LLMModel] / list[str]
get_model(model) /v1/models/{model} LLMModel
quota(model=None) /v1/quota QuotaStatus
request_status(request_id) /v1/requests/{id} RequestStatus

encode_image(kaynak, max_side=None) yol, bayt ya da data: URL'yi geçidin kabul ettiği gömülü biçime çevirir.

LLMModel artık context_length, default_max_output_tokens, precision ve tipli capabilities (tools, thinking, reasoning_effort, reasoning_effort_values, reasoning_effort_aliases, vision, max_images_per_request, response_format, seed, top_k, stop) alanlarını taşır — bir istek göndermeden önce modelin hangi parametreyi desteklediğini denetlemek için. Eski geçit yanıtlarında bu alanlar yoksa None kalır.


🇬🇧 English

Official Python SDK of the EVREN AI Platform: inference on computer vision models trained on EVREN and access to the EVREN LLM gateway (chat, streaming, embeddings, rerank).

Object Detection · Classification · Segmentation · OBB · Keypoint · Edge Inference · LLM Gateway

Architecture

EVREN SDK architecture

A single predict() call leverages 8× NVIDIA A6000 GPUs. No infrastructure management — pip install and 3 lines of code.

Installation

pip install evren-sdk            # core SDK
pip install evren-sdk[edge]      # + OpenCV (camera/video support)

Quick Start

from evren_sdk import EvrenClient

client = EvrenClient(api_key="evren_xxxxx")
result = client.predict("owner/model-name", "photo.jpg", confidence=0.3)

for det in result.predictions:
    print(f"{det.class_name}: {det.confidence:.0%}  bbox={det.bbox}")

See examples/ for runnable scripts covering every feature.

Authentication

Create an API key from Settings → API Keys on the platform. Keys start with the evren_ prefix.

client = EvrenClient(api_key="evren_xxxxx")    # API key (recommended)
client = EvrenClient(api_key="eyJhbGci...")    # JWT token

Inference Pipeline

Inference flow

Single Prediction

result = client.predict(
    model="owner/model-name",           # slug, slug:tag, or UUID
    image="image.jpg",                  # file path, Path, or bytes
    confidence=0.25,
    iou=0.45,
    image_size=640,
    classes=["car", "person"],          # optional
)
model Format Description
"owner/slug" Resolves to latest version
"owner/slug:v2.0" Specific version tag
"019cec..." (UUID) Direct version ID

Batch Prediction

batch = client.predict_batch(
    model="owner/model-name",
    images=["img1.jpg", "img2.jpg", "img3.jpg"],
    confidence=0.3,
)

for r in batch:
    print(f"{r.count} detections, {r.inference_ms:.0f} ms")

See examples/02_batch_inference.py

Result Processing & Export

result = client.predict("owner/model", "scene.jpg")

filtered = result.filter(min_confidence=0.5, classes=["car"])

result.to_yolo()          # YOLO txt
result.to_coco()          # COCO dict list
result.to_csv()           # CSV string

result.save("result.json")
result.save("result.csv")
result.save("labels.txt")

Full example: examples/03_result_export.py

Model Info & Warmup

info = client.model_classes("owner/model-name")
for cls in info.classes:
    print(f"  {cls.name}: {cls.color}")

for m in client.list_models():
    print(f"{m.full_slug} — {m.architecture}")

client.warmup(["owner/model-name"])   # eliminate cold-start

Benchmarking

bench = client.benchmark("owner/model", "test.jpg", rounds=20)

print(f"Avg: {bench.avg_ms:.1f}ms  |  p95: {bench.p95_ms:.1f}ms")
print(f"Throughput: {bench.throughput_fps:.1f} FPS")

→ examples/04_benchmark.py

Model Download

path = client.download_model("owner/model", output="weights/", fmt="onnx")
print(f"Saved to: {path}")   # weights/best.onnx

Upload to Dataset

Create a dataset and upload images to it directly from the SDK.

ds = client.create_dataset("scene-data")   # default: private, VISION
resp = client.upload_to_dataset(dataset_id=ds["id"], image="new_image.jpg")

Text and Audio Datasets

Records come with their labels (labels), NER spans (entities) and cell corrections. Audio columns use the HF Audio layout ({"bytes", "path"}). Requires pip install "evren-sdk[datasets]".

train = client.load_dataset("owner/dataset", split="train")   # pyarrow.Table
for row in client.iter_dataset("owner/dataset", split="test"):  # streaming, no download
    ...
client.download_dataset("owner/dataset", "data/", format="jsonl")

from evren_sdk.datasets import to_hf
ds = to_hf(client.load_dataset("owner/dataset", version="v1"))  # HF DatasetDict

The first call prepares an export on the platform (same export credit as image datasets); the same content is free afterwards and served from the local cache. Files are verified with SHA-256.

Async Usage

import asyncio
from evren_sdk import AsyncEvrenClient

async def main():
    async with AsyncEvrenClient(api_key="evren_xxxxx") as client:
        result = await client.predict("owner/model", "photo.jpg")
        batch  = await client.predict_batch("owner/model", ["a.jpg", "b.jpg"])

asyncio.run(main())

Parallel pipeline: examples/07_async_pipeline.py

LLM Gateway (Chat, Streaming, Embeddings, Rerank, Decisions, OCR, Speech)

EvrenLLMClient talks to the EVREN LLM gateway (evren-llmapi.ssyz.org.tr). It is separate from the vision client and uses an LLM key starting with evren_llm_. If no key is passed, EVREN_LLM_API_KEY is used.

from evren_sdk import EvrenLLMClient

with EvrenLLMClient() as llm:
    r = llm.chat("glm-5.3", [{"role": "user", "content": "Hello"}], max_tokens=512)
    print(r.content, r.reasoning, r.usage, r.request_id)

    for chunk in llm.chat_stream("deepseek-v4.1-flash", [{"role": "user", "content": "Write a poem"}]):
        print(chunk, end="", flush=True)

    for d in llm.stream("glm-5.3", [{"role": "user", "content": "2+2?"}]):
        ...  # d.content, d.reasoning, d.tool_calls, d.finish_reason, d.usage

    vectors = llm.embed("qwen3-embedding-8b", ["hello", "world"])
    ranked = llm.rerank("qwen3-reranker-8b", "capital of Türkiye",
                        ["Paris is in France", "Ankara is the capital"], top_n=1)

Tool calls use the OpenAI format and are returned in r.tool_calls.

Reliability. On 429, 502, 503, 504 and connection errors the client retries automatically (max_retries=2), honouring Retry-After. Every non-streaming call carries an Idempotency-Key, so a retried request is de-duplicated by the gateway and never executed or billed twice. Streams are retried only when the gateway rejected them before reaching the model (429/503). An interrupted stream raises LLMServiceError (code="stream_interrupted") instead of silently returning a truncated answer. Errors expose status_code, code, param, request_id, retry_after and the EVREN-specific evren payload (resets_at, suggested_models, …). When the daily quota is exhausted the gateway sets Retry-After to the end of the day; such responses (wait longer than 30 s) are not retried and LLMRateLimitError is raised immediately.

AsyncEvrenLLMClient offers the same API with await / async for.

Typed Decisions, OCR, Speech-to-Text and Quota

Decision models (laya, clef) do not generate text: they answer typed choice, score and noul (yes/no) questions about a text (and, with clef, images) in a single pass, with probabilities. llm.models() reports each model's task (decision, ocr, audio_transcription, …). Laya requires instructions on every question; include it so the same questions work on both models.

from evren_sdk import EvrenLLMClient, encode_image

with EvrenLLMClient() as llm:
    r = llm.decide("clef", "I was charged twice; refund it or I will cancel.", {
        "team": {"type": "choice", "instructions": "Which team?",
                 "criteria": {"billing": "payments, refunds", "tech": "bugs, outages"}},
        "urgency": {"type": "score", "instructions": "How urgent?", "criteria": ["can wait", "soon", "critical"]},
        "churn": {"type": "noul", "instructions": "Does the customer threaten to cancel?"},
    })
    print(r.choice("team"), r.score("urgency"), r.noul("churn"))

    # clef reads up to 4 images, without downscaling: every 32×32 px tile is one
    # token (1024 px ≈ 1,000, 4000 px ≈ 15,600) — shrink large photos first:
    doc = encode_image("invoice.jpg", max_side=1024)    # pip install evren-sdk[images]
    r = llm.decide("clef", "Inspect the attached document.", {
        "legible": {"type": "noul", "instructions": "Is the total legible?"},
    }, images=[doc])

    batch = llm.decide_batch("laya", ["I forgot my password", "Send me a quote"], {
        "team": {"type": "choice", "instructions": "Which team?", "criteria": {"tech": "login", "sales": "pricing"}},
    })                                                  # laya only; clef has no batch endpoint

    print(llm.ocr("dots-ocr", "receipt.png").text)
    print(llm.transcribe("qwen3-asr-1.7b", "meeting.wav", language="tr").text)
    llm.speak("voxcpm2", "Your report is ready.", voice="kaan", response_format="wav").save("report.wav")  # text-to-speech
    print(llm.quota().daily_remaining_tokens)
    print(llm.quota(model="glm-5.3").model_concurrent_requests)   # your requests in flight on that model
    print(llm.response_input_tokens("glm-5.3", "Long document").input_tokens)  # free pre-send token count
    first = llm.respond("glm-5.3", "Capital of Türkiye?")             # Responses API
    print(llm.respond("glm-5.3", "Population?", previous_response_id=first.id).output_text)
    mod = llm.moderate("Text to screen")                              # free endpoint
    print(mod.flagged, mod.categories)
    print([r.flagged for r in llm.moderate(["first", "second"]).results])  # one verdict per text

Terms of Service Gate

The gateway requires a one-time acceptance of the terms of use per account; until accepted, every call returns 403 terms_not_accepted. The SDK manages this flow:

with EvrenLLMClient() as llm:
    status = llm.terms_status()          # acceptance state + current version
    if status.needs_accept:
        print(llm.terms_text())          # read before accepting
        llm.accept_terms(status.current_version)

The SDK never accepts the terms on your behalf, which is why the version is required. Calls made before acceptance raise LLMTermsNotAcceptedError, a subclass of LLMAuthenticationError, so existing except blocks that catch 403 keep working. When a new material version is published the gate asks for acceptance again — check terms_status().needs_accept.

The gateway does not accept Idempotency-Key on the audio endpoints, so transcribe() and speak() are retried only when the connection could not be established. speak() accepts up to 4,096 characters; the gateway splits long text at sentence boundaries and returns a single file. voice picks one of four preset voices (deniz, ece, emre, kaan; default = deniz), and separate calls with the same voice keep the same speaker. With instructions (an English voice description) the voice follows the description and is not guaranteed to be identical across calls.

Edge Mode (GPU-free Devices)

Real-time inference on devices without a GPU (Raspberry Pi, laptops, industrial PCs). Inference runs on EVREN cloud GPUs — the UX feels local.

Edge mode flow

pip install evren-sdk[edge]
from evren_sdk import EvrenCamera

cam = EvrenCamera("evren_...", "owner/model", confidence=0.3)

cam.run(0)                                      # webcam, ESC to quit
cam.record("input.mp4", "output.mp4")           # process + save
for frame, result in cam.stream(0):             # custom loop
    print(f"{result.count} detections")
for path, result in cam.scan("images/"):        # folder scan
    print(f"{path.name}: {result.count} objects")
Parameter Default Description
max_fps 15.0 FPS cap to conserve bandwidth
jpeg_quality 70 JPEG compression quality (20-95)
draw True Render predictions on frame
confidence 0.25 Minimum confidence threshold

→ examples/05_edge_camera.py

Error Handling

from evren_sdk import (
    EvrenClient, InsufficientCreditsError,
    NotFoundError, RateLimitError, InferenceError,
)

try:
    result = client.predict("owner/model", "test.jpg")
except InsufficientCreditsError as e:
    print(f"Not enough credits — need: {e.required}, have: {e.available}")
except NotFoundError:
    print("Model not found")
except RateLimitError as e:
    time.sleep(e.retry_after)
except InferenceError:
    print("GPU server temporarily unavailable")
Exception HTTP Description
AuthenticationError 401, 403 Invalid or expired key
InsufficientCreditsError 402 Insufficient credits
NotFoundError 404 Model or version not found
ValidationError 422 Invalid parameter
RateLimitError 429 Rate limit exceeded
InferenceError 502, 503 GPU server error

Every inference call consumes credits. When balance is too low, the SDK raises InsufficientCreditsError with e.required and e.available fields.

API Reference

Data Models
Class Fields / Methods
PredictResult predictions, inference_ms, count, image_width, image_height
↳ methods filter(), to_yolo(), to_coco(), to_csv(), save()
Prediction class_name, confidence, bbox, color, mask, keypoints, obb
↳ methods to_dict()
BatchResult results, total_ms, count — iterable, supports len()
BenchmarkResult model, rounds, avg_ms, min_ms, max_ms, p95_ms, throughput_fps
ModelClasses classes, architecture, model_name, total, imgsz — supports in
↳ methods names()
ModelInfo id, name, slug, architecture, owner_username, full_slug
ModelVersion id, version_tag, framework, metrics, weights_url
ClassInfo name, color
EvrenCamera stream(), run(), scan(), record(), stats
Client Methods
Method Description
predict(model, image, **kw) Single inference
predict_batch(model, images, **kw) GPU batch inference
model_classes(model) Model classes, architecture, imgsz
warmup(models) GPU pre-load
list_models(limit) List available models
list_versions(model_id) List model versions
resolve(slug) Slug → version UUID
benchmark(model, image, **kw) Performance test
download_model(model, output, fmt) Download weights
create_dataset(name, visibility=, license=, tags=) Create a dataset
upload_to_dataset(dataset_id, image) Upload image to dataset

AsyncEvrenClient provides the same API with async/await.

LLM Client Methods
Method Endpoint Returns
chat(model, messages, **kw) /v1/chat/completions ChatCompletionResult
stream() / chat_stream() /v1/chat/completions (SSE) ChatDelta / str
embed(model, texts) /v1/embeddings list[list[float]]
rerank(model, query, documents, top_n) /v1/rerank list[RerankResult]
decide(model, state, questions, images=) /v1/systemone DecisionResult
decide_batch(model, states, questions) /v1/systemone/batch DecisionBatchResult
ocr(model, image) /v1/ocr OcrResult
transcribe(model, audio, response_format=) /v1/audio/transcriptions Transcription
speak(model, text, voice=, response_format=, instructions=) /v1/audio/speech SpeechResult
respond(model, input, **kw) / get_response(id) /v1/responses ResponseResult
delete_response(id) / response_input_items(id, limit=, order=, after=) /v1/responses/{id} None / ResponseInputItems
moderate(input, model=None) /v1/moderations ModerationResult
terms_status() / terms_text() / accept_terms(version) /v1/terms/* TermsStatus / str / TermsAcceptance
response_input_tokens(model, input, **kw) /v1/responses/input_tokens InputTokensResult
models() / list_models() /v1/models list[LLMModel] / list[str]
get_model(model) /v1/models/{model} LLMModel
quota(model=None) /v1/quota QuotaStatus
request_status(request_id) /v1/requests/{id} RequestStatus

encode_image(source, max_side=None) turns a path, bytes or data: URL into the embedded form the gateway accepts.

LLMModel now carries context_length, default_max_output_tokens, precision and a typed capabilities (tools, thinking, reasoning_effort, reasoning_effort_values, reasoning_effort_aliases, vision, max_images_per_request, response_format, seed, top_k, stop) — check what a model supports before sending a request that would otherwise 400. Fields stay None when an older gateway response doesn't include them.


Examples

# File Description
1 01_quickstart.py Temel tekil çıkarım / Basic single prediction
2 02_batch_inference.py Toplu GPU çıkarım / Batch GPU inference
3 03_result_export.py Filtreleme & export (YOLO, COCO, CSV, JSON)
4 04_benchmark.py Performans testi / Latency & throughput
5 05_edge_camera.py Edge cihaz kamera / GPU-free real-time
6 06_upload_to_dataset.py Veri setine görsel yükleme / Upload images to dataset
7 07_async_pipeline.py Asenkron paralel çıkarım / Async pipeline

Requirements

  • Python >= 3.10
  • httpx >= 0.27
  • opencv-python >= 4.8 (only for evren-sdk[edge])
  • Pillow >= 10 (only for encode_image(max_side=...), evren-sdk[images])

License

Apache License 2.0

Metadata

Release files for evren-sdk 0.14.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for evren-sdk 0.14.0
File Size Uploaded Provenance Actions
evren_sdk-0.14.0.tar.gz 83.1 kB With provenance Details for evren_sdk-0.14.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for evren-sdk 0.14.0
File Interpreter ABI Platform Actions
evren_sdk-0.14.0-py3-none-any.whl Python 3 none any Details for evren_sdk-0.14.0-py3-none-any.whl

Total release size: 149.7 kB

Release files / evren_sdk-0.14.0.tar.gz

Download URL evren_sdk-0.14.0.tar.gz
Size 83.1 kB
Tags Source
SHA-256 checksum
How to use checksums
d66a62f2a178d8ef68eeb2d8dc9e784ce980deaea9936240388baf554803eb2c
BLAKE2b-256 checksum
How to use checksums
f165dac0fc3df55f10f519eb5f3317dd188d5e50af11490c42def4b8243eb1de
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 14, 2026.

Transparency log

Release files / evren_sdk-0.14.0-py3-none-any.whl

Download URL evren_sdk-0.14.0-py3-none-any.whl
Size 66.6 kB
Tags Python 3
SHA-256 checksum
How to use checksums
7f3cc1e015a484dced8dafadca021fbfe3148a54800732a2a3077ff224da82c3
BLAKE2b-256 checksum
How to use checksums
a5475a23db3462c6347fca0b7c72bbcbebc608083783bdf51a500673e98f51cc
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 14, 2026.

Transparency log

Security for evren-sdk 0.14.0

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Full provenance

Both files in this release have been uploaded with provenance metadata.

Select from 2 files

Attestation for evren_sdk-0.14.0.tar.gz

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 14, 2026.

Transparency log

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page