evren-sdk 0.3.0__tar.gz

evren_sdk-0.3.0/.gitignore

@@ -0,0 +1,78 @@
+# Python
+__pycache__/
+*.pyc
+*.pyo
+*.egg-info/
+dist/
+build/
+htmlcov/
+.coverage
+.ruff_cache/
+.mypy_cache/
+.pytest_cache/
+
+# Virtual environments
+.venv/
+venv/
+env/
+
+# Node.js
+node_modules/
+*.tsbuildinfo
+.vite/
+coverage/
+
+# Environment
+.env
+.env.*
+!.env.example
+
+# IDE
+.idea/
+.vscode/
+*.swp
+*.swo
+
+# Cursor / AI
+.cursor/
+AGENTS.md
+agent-transcripts/
+mcps/
+prompts/
+
+# OS
+.DS_Store
+Thumbs.db
+Desktop.ini
+
+# Terminals (cursor IDE)
+terminals/
+
+# SSL / TLS secrets
+ssl/
+infra_scripts/**/certs/*.key
+infra_scripts/**/certs/*.pem
+infra_scripts/elasticsearch/certs/
+
+# Build artifacts
+src/frontend/dist/
+
+# TypeScript compiled .js files (source is .tsx)
+src/frontend/src/**/*.js
+
+# Env file (secrets)
+.env
+
+# Test data / archives
+*.zip
+drones/
+_*.py
+!__init__.py
+!src/backend/**/_*.py
+
+# Internal planning
+tasks/
+altyapi.txt
+*.bundle
+start.bat
+.cursorignore

evren_sdk-0.3.0/PKG-INFO

@@ -0,0 +1,206 @@
+Metadata-Version: 2.4
+Name: evren-sdk
+Version: 0.3.0
+Summary: EVREN MLOps Platform — Python inference SDK for object detection, classification, and segmentation models.
+Project-URL: Homepage, https://evren.ssyz.org.tr
+Project-URL: Documentation, https://docs.ssyz.org.tr/sdk
+Project-URL: Repository, https://gitlab.crudfab.com/ssb/ssyz/evren/platform
+Project-URL: Changelog, https://gitlab.crudfab.com/ssb/ssyz/evren/platform/-/blob/main/sdk/CHANGELOG.md
+Project-URL: Issues, https://gitlab.crudfab.com/ssb/ssyz/evren/platform/-/issues
+Author-email: Serkan Peker <serkan.peker@crudfab.com>
+Maintainer-email: Serkan Peker <serkan.peker@crudfab.com>
+License-Expression: Apache-2.0
+Keywords: computer-vision,deep-learning,evren,inference,mlops,object-detection,sdk,yolo
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: Apache Software License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Classifier: Topic :: Scientific/Engineering :: Image Recognition
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Requires-Dist: httpx>=0.27
+Provides-Extra: dev
+Requires-Dist: mypy; extra == 'dev'
+Requires-Dist: pytest; extra == 'dev'
+Requires-Dist: pytest-asyncio; extra == 'dev'
+Requires-Dist: ruff; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# 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

evren_sdk-0.3.0/README.md

@@ -0,0 +1,171 @@
+# 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

evren_sdk-0.3.0/evren_sdk/__init__.py

@@ -0,0 +1,40 @@
+"""EVREN Python SDK — nesne tespiti ve goruntu cikarim istemcisi."""
+
+from .client import AsyncEvrenClient, EvrenClient
+from .exceptions import (
+    AuthenticationError,
+    EvrenError,
+    InferenceError,
+    NotFoundError,
+    RateLimitError,
+    ValidationError,
+)
+from .models import (
+    BatchResult,
+    ClassInfo,
+    ModelClasses,
+    ModelInfo,
+    ModelVersion,
+    Prediction,
+    PredictResult,
+)
+
+__version__ = "0.3.0"
+
+__all__ = [
+    "EvrenClient",
+    "AsyncEvrenClient",
+    "EvrenError",
+    "AuthenticationError",
+    "NotFoundError",
+    "RateLimitError",
+    "InferenceError",
+    "ValidationError",
+    "Prediction",
+    "PredictResult",
+    "BatchResult",
+    "ClassInfo",
+    "ModelClasses",
+    "ModelInfo",
+    "ModelVersion",
+]

evren_sdk-0.3.0/evren_sdk/client.py

@@ -0,0 +1,412 @@
+from __future__ import annotations
+
+import io
+import uuid
+from pathlib import Path
+from typing import Any
+
+import httpx
+
+from .exceptions import (
+    AuthenticationError,
+    InferenceError,
+    NotFoundError,
+    RateLimitError,
+    ValidationError,
+)
+from .models import (
+    BatchResult,
+    ClassInfo,
+    ModelClasses,
+    ModelInfo,
+    ModelVersion,
+    Prediction,
+    PredictResult,
+)
+
+_API_BASE = "https://api.ssyz.org.tr/api/v1"
+_BATCH_TIMEOUT = 120.0
+
+
+def _auth_headers(key: str) -> dict[str, str]:
+    if key.startswith("evren_"):
+        return {"X-API-Key": key}
+    return {"Authorization": f"Bearer {key}"}
+
+
+def _raise_for(resp: httpx.Response) -> None:
+    code = resp.status_code
+    try:
+        msg = resp.json().get("detail", resp.text[:300])
+    except Exception:
+        msg = resp.text[:300]
+
+    if code in (401, 403):
+        raise AuthenticationError(msg, code)
+    if code == 404:
+        raise NotFoundError(msg, code)
+    if code == 422:
+        raise ValidationError(msg, code)
+    if code == 429:
+        wait = int(resp.headers.get("Retry-After", "5"))
+        raise RateLimitError(msg, wait)
+    if code >= 500:
+        raise InferenceError(msg, code)
+    resp.raise_for_status()
+
+
+def _read_img(source: str | Path | bytes) -> tuple[bytes, str]:
+    if isinstance(source, bytes):
+        return source, "image.jpg"
+    p = Path(source)
+    return p.read_bytes(), p.name
+
+
+def _is_uuid(val: str) -> bool:
+    try:
+        uuid.UUID(val)
+        return True
+    except (ValueError, AttributeError):
+        return False
+
+
+def _unwrap(data: Any) -> Any:
+    if isinstance(data, dict) and "data" in data:
+        return data["data"]
+    return data
+
+
+def _build_form(version_id: str, confidence: float,
+                iou: float, imgsz: int,
+                classes: list[str] | None) -> dict[str, str]:
+    d: dict[str, str] = {
+        "model_version_id": version_id,
+        "confidence_threshold": str(confidence),
+        "iou_threshold": str(iou),
+        "image_size": str(imgsz),
+    }
+    if classes:
+        d["classes"] = ",".join(classes)
+    return d
+
+
+def _to_prediction(raw: dict) -> Prediction:
+    return Prediction(
+        class_name=raw.get("class_name", ""),
+        confidence=raw.get("confidence", 0.0),
+        bbox=raw.get("bbox", []),
+        color=raw.get("color"),
+        keypoints=raw.get("keypoints"),
+        mask=raw.get("mask"),
+        obb=raw.get("obb"),
+        task=raw.get("task"),
+        probs=raw.get("probs"),
+    )
+
+
+def _to_result(body: dict) -> PredictResult:
+    return PredictResult(
+        predictions=[_to_prediction(p) for p in body.get("predictions", [])],
+        inference_ms=body.get("inference_ms", 0),
+        image_width=body.get("image_width"),
+        image_height=body.get("image_height"),
+        model_version_id=body.get("model_version_id"),
+    )
+
+
+def _to_model_info(m: dict) -> ModelInfo:
+    return ModelInfo(
+        id=m["id"], name=m["name"], slug=m.get("slug", ""),
+        architecture=m.get("architecture"),
+        owner_username=m.get("owner_username"),
+    )
+
+
+def _to_model_ver(v: dict) -> ModelVersion:
+    return ModelVersion(
+        id=v["id"], version_tag=v.get("version_tag", ""),
+        weights_url=v.get("weights_url"),
+        framework=v.get("framework", "pytorch"),
+        metrics=v.get("metrics", {}),
+    )
+
+
+def _resolve_versions(body: Any) -> list[dict]:
+    data = _unwrap(body)
+    if isinstance(data, list):
+        return data
+    return data.get("items", data.get("data", []))
+
+
+def _pick_version(versions: list[dict], tag: str | None, slug: str) -> str:
+    if not versions:
+        raise NotFoundError(f"'{slug}' icin versiyon yok", 404)
+
+    if tag is None:
+        return versions[0]["id"]
+
+    for v in versions:
+        if v.get("version_tag") == tag:
+            return v["id"]
+    raise NotFoundError(f"'{slug}' icin '{tag}' versiyonu yok", 404)
+
+
+# ---------------------------------------------------------------
+# sync
+# ---------------------------------------------------------------
+
+
+class EvrenClient:
+    """EVREN inference API senkron istemcisi.
+
+    >>> with EvrenClient(api_key="evren_xxx") as c:
+    ...     r = c.predict("owner/slug", "foto.jpg")
+    ...     print(r.predictions)
+    """
+
+    def __init__(self, api_key: str, *,
+                 base_url: str = _API_BASE,
+                 timeout: float = 60.0) -> None:
+        self._http = httpx.Client(
+            base_url=base_url.rstrip("/"),
+            headers=_auth_headers(api_key),
+            timeout=timeout,
+        )
+        self._vcache: dict[str, str] = {}
+
+    def resolve(self, slug: str) -> str:
+        """``owner/slug`` veya ``owner/slug:tag`` -> version UUID."""
+        if slug in self._vcache:
+            return self._vcache[slug]
+
+        slug_part, _, tag = slug.partition(":")
+        tag = tag or None
+
+        r = self._http.get(f"/models/{slug_part}")
+        if r.status_code != 200:
+            _raise_for(r)
+        mid = _unwrap(r.json())["id"]
+
+        r2 = self._http.get(f"/models/{mid}/versions")
+        if r2.status_code != 200:
+            _raise_for(r2)
+
+        vid = _pick_version(_resolve_versions(r2.json()), tag, slug)
+        self._vcache[slug] = vid
+        return vid
+
+    def _vid(self, model: str) -> str:
+        return model if _is_uuid(model) else self.resolve(model)
+
+    def predict(self, model: str, image: str | Path | bytes, *,
+                confidence: float = 0.25, iou: float = 0.45,
+                image_size: int = 640,
+                classes: list[str] | None = None) -> PredictResult:
+        raw, name = _read_img(image)
+        r = self._http.post(
+            "/inference/predict",
+            data=_build_form(self._vid(model), confidence, iou, image_size, classes),
+            files={"file": (name, io.BytesIO(raw), "image/jpeg")},
+        )
+        if r.status_code != 200:
+            _raise_for(r)
+        return _to_result(_unwrap(r.json()))
+
+    def predict_batch(self, model: str, images: list[str | Path | bytes], *,
+                      confidence: float = 0.25, iou: float = 0.45,
+                      image_size: int = 640,
+                      classes: list[str] | None = None) -> BatchResult:
+        vid = self._vid(model)
+        parts = []
+        for i, img in enumerate(images):
+            raw, fname = _read_img(img)
+            n = fname if fname != "image.jpg" else f"img_{i}.jpg"
+            parts.append(("files", (n, io.BytesIO(raw), "image/jpeg")))
+
+        r = self._http.post(
+            "/inference/predict/batch",
+            data=_build_form(vid, confidence, iou, image_size, classes),
+            files=parts, timeout=_BATCH_TIMEOUT,
+        )
+        if r.status_code != 200:
+            _raise_for(r)
+
+        body = _unwrap(r.json())
+        items = [_to_result(x) for x in body.get("results", [])]
+        return BatchResult(results=items,
+                           total_ms=body.get("total_ms", 0),
+                           count=body.get("count", len(items)))
+
+    def model_classes(self, model: str) -> ModelClasses:
+        vid = self._vid(model)
+        r = self._http.get(f"/inference/model-classes/{vid}")
+        if r.status_code != 200:
+            _raise_for(r)
+        b = _unwrap(r.json())
+        return ModelClasses(
+            model_version_id=b.get("model_version_id", vid),
+            classes=[ClassInfo(name=c["name"], color=c["color"])
+                     for c in b.get("classes", [])],
+            model_name=b.get("model_name"),
+            architecture=b.get("architecture"),
+            total=b.get("total", 0),
+            imgsz=b.get("imgsz", 640),
+        )
+
+    def warmup(self, models: list[str]) -> dict:
+        ids = [self._vid(m) for m in models]
+        r = self._http.post("/inference/warmup", json=ids,
+                            timeout=_BATCH_TIMEOUT)
+        if r.status_code != 200:
+            _raise_for(r)
+        return _unwrap(r.json())
+
+    def list_models(self, limit: int = 50) -> list[ModelInfo]:
+        r = self._http.get("/models",
+                           params={"limit": limit, "include_public": "true"})
+        if r.status_code != 200:
+            _raise_for(r)
+        body = _unwrap(r.json())
+        rows = body if isinstance(body, list) else body.get("items", [])
+        return [_to_model_info(m) for m in rows]
+
+    def list_versions(self, model_id: str) -> list[ModelVersion]:
+        r = self._http.get(f"/models/{model_id}/versions")
+        if r.status_code != 200:
+            _raise_for(r)
+        return [_to_model_ver(v) for v in _resolve_versions(r.json())]
+
+    def close(self) -> None:
+        self._http.close()
+
+    def __enter__(self) -> EvrenClient:
+        return self
+
+    def __exit__(self, *exc: Any) -> None:
+        self.close()
+
+
+# ---------------------------------------------------------------
+# async
+# ---------------------------------------------------------------
+
+
+class AsyncEvrenClient:
+    """EVREN inference API asenkron istemcisi.
+
+    >>> async with AsyncEvrenClient(api_key="evren_xxx") as c:
+    ...     r = await c.predict("owner/slug", "foto.jpg")
+    """
+
+    def __init__(self, api_key: str, *,
+                 base_url: str = _API_BASE,
+                 timeout: float = 60.0) -> None:
+        self._http = httpx.AsyncClient(
+            base_url=base_url.rstrip("/"),
+            headers=_auth_headers(api_key),
+            timeout=timeout,
+        )
+        self._vcache: dict[str, str] = {}
+
+    async def resolve(self, slug: str) -> str:
+        if slug in self._vcache:
+            return self._vcache[slug]
+
+        slug_part, _, tag = slug.partition(":")
+        tag = tag or None
+
+        r = await self._http.get(f"/models/{slug_part}")
+        if r.status_code != 200:
+            _raise_for(r)
+        mid = _unwrap(r.json())["id"]
+
+        r2 = await self._http.get(f"/models/{mid}/versions")
+        if r2.status_code != 200:
+            _raise_for(r2)
+
+        vid = _pick_version(_resolve_versions(r2.json()), tag, slug)
+        self._vcache[slug] = vid
+        return vid
+
+    async def _vid(self, model: str) -> str:
+        return model if _is_uuid(model) else await self.resolve(model)
+
+    async def predict(self, model: str, image: str | Path | bytes, *,
+                      confidence: float = 0.25, iou: float = 0.45,
+                      image_size: int = 640,
+                      classes: list[str] | None = None) -> PredictResult:
+        raw, name = _read_img(image)
+        r = await self._http.post(
+            "/inference/predict",
+            data=_build_form(await self._vid(model), confidence, iou, image_size, classes),
+            files={"file": (name, io.BytesIO(raw), "image/jpeg")},
+        )
+        if r.status_code != 200:
+            _raise_for(r)
+        return _to_result(_unwrap(r.json()))
+
+    async def predict_batch(self, model: str, images: list[str | Path | bytes], *,
+                            confidence: float = 0.25, iou: float = 0.45,
+                            image_size: int = 640,
+                            classes: list[str] | None = None) -> BatchResult:
+        vid = await self._vid(model)
+        parts = []
+        for i, img in enumerate(images):
+            raw, fname = _read_img(img)
+            n = fname if fname != "image.jpg" else f"img_{i}.jpg"
+            parts.append(("files", (n, io.BytesIO(raw), "image/jpeg")))
+
+        r = await self._http.post(
+            "/inference/predict/batch",
+            data=_build_form(vid, confidence, iou, image_size, classes),
+            files=parts, timeout=_BATCH_TIMEOUT,
+        )
+        if r.status_code != 200:
+            _raise_for(r)
+        body = _unwrap(r.json())
+        items = [_to_result(x) for x in body.get("results", [])]
+        return BatchResult(results=items,
+                           total_ms=body.get("total_ms", 0),
+                           count=body.get("count", len(items)))
+
+    async def model_classes(self, model: str) -> ModelClasses:
+        vid = await self._vid(model)
+        r = await self._http.get(f"/inference/model-classes/{vid}")
+        if r.status_code != 200:
+            _raise_for(r)
+        b = _unwrap(r.json())
+        return ModelClasses(
+            model_version_id=b.get("model_version_id", vid),
+            classes=[ClassInfo(name=c["name"], color=c["color"])
+                     for c in b.get("classes", [])],
+            model_name=b.get("model_name"),
+            architecture=b.get("architecture"),
+            total=b.get("total", 0),
+            imgsz=b.get("imgsz", 640),
+        )
+
+    async def warmup(self, models: list[str]) -> dict:
+        ids = [await self._vid(m) for m in models]
+        r = await self._http.post("/inference/warmup", json=ids,
+                                  timeout=_BATCH_TIMEOUT)
+        if r.status_code != 200:
+            _raise_for(r)
+        return _unwrap(r.json())
+
+    async def list_models(self, limit: int = 50) -> list[ModelInfo]:
+        r = await self._http.get("/models",
+                                 params={"limit": limit, "include_public": "true"})
+        if r.status_code != 200:
+            _raise_for(r)
+        body = _unwrap(r.json())
+        rows = body if isinstance(body, list) else body.get("items", [])
+        return [_to_model_info(m) for m in rows]
+
+    async def close(self) -> None:
+        await self._http.aclose()
+
+    async def __aenter__(self) -> AsyncEvrenClient:
+        return self
+
+    async def __aexit__(self, *exc: Any) -> None:
+        await self.close()

evren_sdk-0.3.0/evren_sdk/exceptions.py

@@ -0,0 +1,35 @@
+from __future__ import annotations
+
+
+class EvrenError(Exception):
+
+    def __init__(self, message: str, status_code: int | None = None) -> None:
+        self.status_code = status_code
+        super().__init__(message)
+
+
+class AuthenticationError(EvrenError):
+    """Gecersiz veya suresi dolmus API anahtari (HTTP 401/403)."""
+
+
+class NotFoundError(EvrenError):
+    """Belirtilen model veya versiyon bulunamadi (HTTP 404)."""
+
+
+class RateLimitError(EvrenError):
+    """Istek limiti asildi (HTTP 429).
+
+    ``retry_after`` saniye bekleyip tekrar deneyin.
+    """
+
+    def __init__(self, message: str, retry_after: int = 5) -> None:
+        self.retry_after = retry_after
+        super().__init__(message, 429)
+
+
+class InferenceError(EvrenError):
+    """GPU cikarim sunucusu gecici olarak kullanilamiyor (HTTP 502/503)."""
+
+
+class ValidationError(EvrenError):
+    """Istek parametrelerinde dogrulama hatasi (HTTP 422)."""

evren_sdk-0.3.0/evren_sdk/models.py

@@ -0,0 +1,91 @@
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+
+
+@dataclass(slots=True)
+class Prediction:
+    class_name: str = ""
+    confidence: float = 0.0
+    bbox: list[float] = field(default_factory=list)
+    color: str | None = None
+    keypoints: list[list[float]] | None = None
+    mask: list[list[float]] | None = None
+    obb: dict | None = None
+    task: str | None = None
+    probs: list[dict] | None = None
+
+    def __repr__(self) -> str:
+        return f"<Prediction {self.class_name} conf={self.confidence:.3f}>"
+
+
+@dataclass(slots=True)
+class PredictResult:
+    predictions: list[Prediction] = field(default_factory=list)
+    inference_ms: float = 0.0
+    image_width: int | None = None
+    image_height: int | None = None
+    model_version_id: str | None = None
+
+    @property
+    def count(self) -> int:
+        return len(self.predictions)
+
+
+@dataclass(slots=True)
+class BatchResult:
+    results: list[PredictResult] = field(default_factory=list)
+    total_ms: float = 0.0
+    count: int = 0
+
+    def __iter__(self):
+        return iter(self.results)
+
+    def __len__(self) -> int:
+        return self.count
+
+
+@dataclass(slots=True, frozen=True)
+class ClassInfo:
+    name: str
+    color: str
+
+
+@dataclass(slots=True)
+class ModelClasses:
+    model_version_id: str
+    classes: list[ClassInfo] = field(default_factory=list)
+    model_name: str | None = None
+    architecture: str | None = None
+    total: int = 0
+    imgsz: int = 640
+
+    def __contains__(self, name: str) -> bool:
+        return any(c.name == name for c in self.classes)
+
+    def names(self) -> list[str]:
+        return [c.name for c in self.classes]
+
+
+@dataclass(slots=True)
+class ModelInfo:
+    id: str
+    name: str
+    slug: str
+    architecture: str | None = None
+    owner_username: str | None = None
+
+    @property
+    def full_slug(self) -> str:
+        if self.owner_username:
+            return f"{self.owner_username}/{self.slug}"
+        return self.slug
+
+
+@dataclass(slots=True)
+class ModelVersion:
+    id: str
+    version_tag: str
+    weights_url: str | None = None
+    framework: str = "pytorch"
+    metrics: dict = field(default_factory=dict)

evren_sdk-0.3.0/pyproject.toml

@@ -0,0 +1,60 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "evren-sdk"
+version = "0.3.0"
+description = "EVREN MLOps Platform — Python inference SDK for object detection, classification, and segmentation models."
+readme = "README.md"
+requires-python = ">=3.10"
+license = "Apache-2.0"
+authors = [
+    { name = "Serkan Peker", email = "serkan.peker@crudfab.com" },
+]
+maintainers = [
+    { name = "Serkan Peker", email = "serkan.peker@crudfab.com" },
+]
+keywords = [
+    "evren", "mlops", "inference", "object-detection",
+    "yolo", "computer-vision", "sdk", "deep-learning",
+]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "Intended Audience :: Science/Research",
+    "License :: OSI Approved :: Apache Software License",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Scientific/Engineering :: Artificial Intelligence",
+    "Topic :: Scientific/Engineering :: Image Recognition",
+    "Typing :: Typed",
+]
+dependencies = [
+    "httpx>=0.27",
+]
+
+[project.optional-dependencies]
+dev = ["pytest", "pytest-asyncio", "ruff", "mypy"]
+
+[project.urls]
+Homepage = "https://evren.ssyz.org.tr"
+Documentation = "https://docs.ssyz.org.tr/sdk"
+Repository = "https://gitlab.crudfab.com/ssb/ssyz/evren/platform"
+Changelog = "https://gitlab.crudfab.com/ssb/ssyz/evren/platform/-/blob/main/sdk/CHANGELOG.md"
+Issues = "https://gitlab.crudfab.com/ssb/ssyz/evren/platform/-/issues"
+
+[tool.hatch.build.targets.wheel]
+packages = ["evren_sdk"]
+
+[tool.ruff]
+target-version = "py310"
+line-length = 100
+
+[tool.mypy]
+python_version = "3.10"
+strict = true