# evren-sdk

EVREN platformu üzerinde eğitilmiş bilgisayarlı görü modellerine
Python'dan çıkarım (inference) yapmanızı sağlayan resmi SDK.

Desteklenen görevler: **nesne tespiti**, **sınıflandırma**, **segmentasyon**,
**döndürülmüş kutu (OBB)**, **anahtar nokta (keypoint)**.

```bash
pip install evren-sdk
```

## Hızlı Başlangıç

```python
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}")

print(f"Çıkarım süresi: {result.inference_ms:.0f} ms")
```

## Kimlik Doğrulama

Platformda **Ayarlar → API Anahtarları** sayfasından anahtar oluşturun.
Anahtar `evren_` ön eki ile başlar ve `X-API-Key` başlığı üzerinden
otomatik gönderilir.

```python
# API anahtarı ile (önerilen)
client = EvrenClient(api_key="evren_xxxxx")

# JWT token ile de çalışır (Authorization: Bearer)
client = EvrenClient(api_key="eyJhbGci...")
```

## Tekil Çıkarım

```python
result = client.predict(
    model="kullanici/model-adi",        # slug veya UUID
    image="resim.jpg",                  # dosya yolu, Path veya bytes
    confidence=0.25,                    # minimum güven eşiği
    iou=0.45,                           # NMS IoU eşiği
    image_size=640,                     # giriş boyutu
    classes=["araba", "insan"],         # isteğe bağlı sınıf filtresi
)
```

`model` parametresi üç format kabul eder:

| Format | Açıklama |
|---|---|
| `"owner/slug"` | Son versiyonu otomatik çözer |
| `"owner/slug:v2.0"` | Belirli versiyon etiketi |
| `"019cec..."` (UUID) | Doğrudan versiyon kimliği |

## Toplu Çıkarım (Batch)

Birden fazla görseli tek istekte GPU batch çıkarımı ile işleyin.
Tekil çağrılardan önemli ölçüde hızlıdır.

```python
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")

print(f"Toplam: {batch.total_ms:.0f} ms, {batch.count} görsel")
```

## Model Bilgileri

```python
# Sınıf listesi ve renkleri
info = client.model_classes("kullanici/model-adi")
print(info.architecture)  # "yolo26x"
for cls in info.classes:
    print(f"  {cls.name}: {cls.color}")

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

## Ön Yükleme (Warmup)

İlk çıkarım gecikmesini ortadan kaldırmak için modelleri
önceden GPU'ya yükleyin.

```python
client.warmup(["kullanici/model-adi", "diger/model"])
```

## Asenkron Kullanım

Aynı API, `async/await` ile:

```python
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-adi", "foto.jpg")
        batch = await client.predict_batch(
            "kullanici/model-adi",
            ["a.jpg", "b.jpg"],
        )
        print(result.predictions, batch.count)

asyncio.run(main())
```

## Hata Yönetimi

```python
from evren_sdk import (
    EvrenClient, NotFoundError,
    RateLimitError, InferenceError,
)
import time

client = EvrenClient(api_key="evren_xxxxx")

try:
    result = client.predict("kullanici/model", "test.jpg")
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 |
| `NotFoundError` | 404 | Model veya versiyon bulunamadı |
| `ValidationError` | 422 | Hatalı parametre |
| `RateLimitError` | 429 | İstek limiti aşıldı |
| `InferenceError` | 502, 503 | GPU sunucusu hatası |

## Veri Modelleri

| Sınıf | Temel Alanlar |
|---|---|
| `PredictResult` | `predictions`, `inference_ms`, `image_width`, `image_height`, `count` |
| `Prediction` | `class_name`, `confidence`, `bbox`, `color`, `mask`, `keypoints`, `obb` |
| `BatchResult` | `results`, `total_ms`, `count` — iterable |
| `ModelClasses` | `classes`, `architecture`, `model_name`, `imgsz` — `in` operatörü destekler |
| `ModelInfo` | `id`, `name`, `slug`, `architecture`, `full_slug` |
| `ModelVersion` | `id`, `version_tag`, `framework`, `metrics` |

## Gereksinimler

- Python ≥ 3.10
- httpx ≥ 0.27

## Lisans

Apache License 2.0
