Metadata-Version: 2.4
Name: vionaai
Version: 3.0.0
Summary: Official Python SDK for the Viona Developer API 3.0 by Orvix Games.
Author-email: Orvix Games <destek@orvixgames.com>
License-Expression: MIT
Project-URL: Homepage, https://dev.vionaai.site/
Project-URL: Documentation, https://dev.vionaai.site/docs/
Project-URL: API Keys, https://dev.vionaai.site/#keys
Keywords: viona,vionaai,viona ai,orvix games,ai,api,sdk,chat,python
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
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: Programming Language :: Python :: 3.14
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Typing :: Typed
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: httpx<1.0,>=0.27.0
Dynamic: license-file

# VionaAI Python SDK 3.0

[![PyPI](https://img.shields.io/pypi/v/vionaai.svg)](https://pypi.org/project/vionaai/)
[![Python](https://img.shields.io/pypi/pyversions/vionaai.svg)](https://pypi.org/project/vionaai/)
[![License](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)

**VionaAI Python SDK**, Orvix Games tarafından geliştirilen **Viona Developer API 3.0** için resmi Python istemcisidir. Viona AI modellerini backend, bot, otomasyon, masaüstü uygulaması ve sunucu projelerine bağlamak için hazırlanmıştır.

- **API Base URL:** https://dev.vionaai.site/api/v1
- **Dokümantasyon:** https://dev.vionaai.site/docs/
- **API key oluştur:** https://dev.vionaai.site/#keys
- **SDK sürümü:** 3.0.0
- **Varsayılan model:** `viona-ti-3.0`

> API anahtarınızı frontend JavaScript'e, mobil uygulama kaynaklarına veya herkese açık depolara gömmeyin. Üretimde anahtarı sunucu tarafında ve ortam değişkeninde saklayın.

---

## Kurulum

PyPI üzerinden:

```bash
python -m pip install -U vionaai
```

Belirli sürüm:

```bash
python -m pip install vionaai==3.0.0
```

Wheel dosyasından:

```bash
python -m pip install vionaai-3.0.0-py3-none-any.whl
```

Kurulumu kontrol et:

```bash
python -c "from Viona.api import Vionaai; print(Vionaai.SDK_VERSION)"
```

---

## Önerilen import

Yeni projelerde önerilen kullanım:

```python
from Viona.api import Vionaai
```

Model sabitleriyle birlikte:

```python
from Viona.api import Vionaai, Models
```

Hata sınıfları:

```python
from Viona.api import Vionaai
from Viona.exceptions import VionaError, AuthenticationError, InsufficientCreditError
```

Kısa import da desteklenir:

```python
from Viona import Vionaai, Models
```

> Python'da `import Vionaai from Viona.api` geçerli bir sözdizimi değildir. Doğru kullanım `from Viona.api import Vionaai` biçimindedir.

Eski kodları kırmamak için `Viona` ve `VionaAI` isimleri geriye uyumluluk alias'ı olarak tutulmuştur, ancak yeni projelerde `Vionaai` kullanılması önerilir.

---

## API key alma

API anahtarını Viona Developer panelinden oluştur:

https://dev.vionaai.site/#keys

Önerilen yöntem anahtarı ortam değişkeninde saklamaktır.

### Windows PowerShell

```powershell
$env:VIONA_API_KEY="viona_live_YENI_API_KEYIN"
```

Kalıcı kullanıcı değişkeni:

```powershell
setx VIONA_API_KEY "viona_live_YENI_API_KEYIN"
```

### Windows CMD

```bat
set VIONA_API_KEY=viona_live_YENI_API_KEYIN
```

### Linux / macOS

```bash
export VIONA_API_KEY="viona_live_YENI_API_KEYIN"
```

Python tarafında:

```python
from Viona.api import Vionaai

client = Vionaai()
```

İstersen anahtarı doğrudan da verebilirsin:

```python
from Viona.api import Vionaai

client = Vionaai(api_key="viona_live_YENI_API_KEYIN")
```

---

## 30 saniyelik başlangıç

```python
from Viona.api import Vionaai

client = Vionaai(api_key="viona_live_YENI_API_KEYIN")

cevap = client.sor("Viona API hakkında kısa bir tanıtım yaz.")
print(cevap)

client.close()
```

Context manager kullanımı daha temizdir:

```python
from Viona.api import Vionaai

with Vionaai(api_key="viona_live_YENI_API_KEYIN") as client:
    print(client.sor("Merhaba Viona!"))
```

SDK varsayılan olarak şu endpointi kullanır:

```text
POST https://dev.vionaai.site/api/v1/chat
```

ve Bearer authentication gönderir:

```text
Authorization: Bearer viona_live_YENI_API_KEYIN
```

---

## Chat completion

Tam API yanıtını almak için `chat()` kullan:

```python
from Viona.api import Vionaai, Models

with Vionaai(api_key="viona_live_YENI_API_KEYIN") as client:
    response = client.chat(
        messages=[
            {"role": "system", "content": "Kısa ve net cevap ver."},
            {"role": "user", "content": "REST API nedir?"},
        ],
        model=Models.TI_3_0,
        temperature=0.7,
        max_tokens=1024,
    )

    print(response["choices"][0]["message"]["content"])
```

### Parametreler

| Alan | Tür | Varsayılan | Açıklama |
|---|---|---|---|
| `messages` | `list` | zorunlu | `system`, `user`, `assistant` mesaj dizisi |
| `model` | `str` | `viona-ti-3.0` | Kullanılacak model |
| `temperature` | `float` | `0.7` | 0 ile 2 arasında üretim çeşitliliği |
| `max_tokens` | `int` | `1024` | 64 ile 8192 arasında yanıt sınırı |

---

## Sadece cevap metnini alma

```python
from Viona.api import Vionaai

client = Vionaai(api_key="viona_live_YENI_API_KEYIN")

text = client.chat_text([
    {"role": "user", "content": "Bana kısa bir oyun fikri üret."}
])

print(text)
client.close()
```

Daha kısa kullanım:

```python
from Viona.api import Vionaai

client = Vionaai(api_key="viona_live_YENI_API_KEYIN")
print(client.sor("Python nedir?"))
client.close()
```

İngilizce alias:

```python
print(client.ask("Explain Python decorators briefly."))
```

---

## Çok turlu sohbet

Konuşma geçmişini `messages` dizisinde tut:

```python
from Viona.api import Vionaai

messages = [
    {"role": "system", "content": "Yardımcı bir yazılım asistanısın."},
    {"role": "user", "content": "Python ile HTTP sunucusu nasıl açılır?"},
]

with Vionaai() as client:
    first = client.chat(messages)
    first_text = first["choices"][0]["message"]["content"]
    print(first_text)

    messages.append({"role": "assistant", "content": first_text})
    messages.append({"role": "user", "content": "8080 portunda çalıştır."})

    second = client.chat(messages)
    print(second["choices"][0]["message"]["content"])
```

---

## Modeller

Viona Developer API 3.0 model kimlikleri:

| Model | Kullanım |
|---|---|
| `viona-ti-3.0` | Genel amaçlı akıl yürütme, analiz ve üretken görevler |
| `viona-mythrion` | Yaratıcı üretim, strateji ve uzun içerik |
| `viona-chat-1.5` | Hızlı ve doğal çok turlu sohbet |
| `viona-codix-1.6` | Kod, hata ayıklama, mimari ve teknik dokümantasyon |

Sabitlerle kullanım:

```python
from Viona.api import Vionaai, Models

client = Vionaai(
    api_key="viona_live_YENI_API_KEYIN",
    model=Models.CODIX_1_6,
)

print(client.sor("Bu Python kodunu optimize et."))
client.close()
```

Tüm sabitler:

```python
print(Models.all())
```

Canlı model kataloğu:

```python
from Viona.api import Vionaai

with Vionaai() as client:
    print(client.models())
```

Bu çağrı:

```text
GET https://dev.vionaai.site/api/v1/models
```

endpointini kullanır.

---

## Async kullanım

FastAPI, botlar ve eşzamanlı işler için async metotlar bulunur.

```python
import asyncio
from Viona.api import Vionaai, Models


async def main():
    async with Vionaai(api_key="viona_live_YENI_API_KEYIN") as client:
        cevap = await client.sor_async(
            "Async programlama nedir?",
            model=Models.TI_3_0,
        )
        print(cevap)


asyncio.run(main())
```

Tam async yanıt:

```python
response = await client.chat_async([
    {"role": "user", "content": "Merhaba"}
])
```

Sadece metin:

```python
text = await client.chat_text_async([
    {"role": "user", "content": "Merhaba"}
])
```

İngilizce helper:

```python
text = await client.ask_async("Hello Viona")
```

---

## Kimlik doğrulama seçenekleri

Varsayılan ve önerilen yöntem Bearer authentication'dır:

```python
from Viona.api import Vionaai

client = Vionaai(
    api_key="viona_live_YENI_API_KEYIN",
    auth_mode="bearer",
)
```

Alternatif `X-API-Key` başlığı:

```python
client = Vionaai(
    api_key="viona_live_YENI_API_KEYIN",
    auth_mode="x-api-key",
)
```

---

## Origin kısıtlaması

API key üzerinde origin kısıtlaması kullanıyorsan gerektiğinde `origin` gönderilebilir:

```python
from Viona.api import Vionaai

client = Vionaai(
    api_key="viona_live_YENI_API_KEYIN",
    origin="https://ornek.com",
)
```

Origin izinlerini Viona Developer panelinden yapılandır.

---

## Kredi bilgileri

Dokümantasyona göre başarılı istekler ortak `dev_kredi` bakiyesinden düşer. Son HTTP yanıtının kredi başlıklarına SDK üzerinden erişebilirsin:

```python
from Viona.api import Vionaai

with Vionaai() as client:
    print(client.sor("Merhaba"))
    print("İstek maliyeti:", client.credit_cost)
    print("Kalan kredi:", client.credit_balance)
```

Desteklenen yardımcı alanlar:

```python
print(client.credit_cost)
print(client.credit_balance)
print(client.request_id)
print(client.rate_limit_remaining)
print(client.last_status_code)
```

---

## Hata yönetimi

```python
from Viona.api import Vionaai
from Viona.exceptions import (
    AuthenticationError,
    InsufficientCreditError,
    OriginNotAllowedError,
    RateLimitError,
    VionaError,
)

try:
    with Vionaai() as client:
        print(client.sor("Merhaba"))

except AuthenticationError:
    print("API key eksik veya geçersiz.")

except InsufficientCreditError:
    print("dev_kredi bakiyesi yetersiz.")

except OriginNotAllowedError:
    print("Bu origin API key için izinli değil.")

except RateLimitError:
    print("İstek hız sınırı aşıldı.")

except VionaError as exc:
    print("Viona API hatası:", exc)
    print("HTTP:", exc.status_code)
    print("Tür:", exc.error_type)
    print("Request ID:", exc.request_id)
```

### HTTP hata eşlemesi

| HTTP | Exception | API hata türü |
|---:|---|---|
| 400 | `InvalidRequestError` | `invalid_request_error` |
| 401 | `AuthenticationError` | `authentication_error` |
| 402 | `InsufficientCreditError` | `insufficient_credit` |
| 403 | `OriginNotAllowedError` | `origin_not_allowed` |
| 413 | `RequestTooLargeError` | `request_too_large` |
| 422 | `InvalidModelError` | `invalid_model` |
| 429 | `RateLimitError` | `rate_limit_exceeded` |
| 502 | `UpstreamUnavailableError` | `upstream_unavailable` |
| 503 | `ServiceUnavailableError` | `service_unavailable` |

Ağ ve timeout hataları:

```python
from Viona.exceptions import APIConnectionError, APITimeoutError
```

SDK `429`, `502`, `503`, timeout ve geçici bağlantı hatalarında yapılandırılmış retry uygular.

---

## Retry ve timeout

```python
from Viona.api import Vionaai

client = Vionaai(
    timeout=45,
    max_retries=3,
    retry_delay=1.0,
)
```

`Retry-After` saniye başlığı varsa SDK onu kullanır; yoksa exponential backoff uygular.

---

## Flask entegrasyonu

API key'i tarayıcıya vermek yerine kendi backend endpointinden Viona'ya bağlan:

```python
import os
from flask import Flask, jsonify, request
from Viona.api import Vionaai
from Viona.exceptions import VionaError

app = Flask(__name__)
client = Vionaai(api_key=os.environ["VIONA_API_KEY"])


@app.post("/api/chat")
def chat():
    data = request.get_json(silent=True) or {}
    message = str(data.get("message", "")).strip()

    if not message:
        return jsonify({"error": "message gerekli"}), 400

    try:
        answer = client.sor(message)
        return jsonify({"answer": answer})
    except VionaError as exc:
        return jsonify({
            "error": exc.error_type or "viona_error",
            "message": exc.message,
        }), exc.status_code or 500


if __name__ == "__main__":
    app.run(debug=True)
```

Frontend artık yalnızca kendi `/api/chat` endpointine istek gönderir; Viona API key backend'de kalır.

---

## FastAPI entegrasyonu

```python
import os
from fastapi import FastAPI, HTTPException
from pydantic import BaseModel
from Viona.api import Vionaai
from Viona.exceptions import VionaError

app = FastAPI()
client = Vionaai(api_key=os.environ["VIONA_API_KEY"])


class ChatBody(BaseModel):
    message: str


@app.post("/api/chat")
async def chat(body: ChatBody):
    try:
        answer = await client.sor_async(body.message)
        return {"answer": answer}
    except VionaError as exc:
        raise HTTPException(
            status_code=exc.status_code or 500,
            detail=exc.message,
        )


@app.on_event("shutdown")
async def shutdown_event():
    await client.aclose()
```

---

## CLI

Paket kurulduktan sonra:

```bash
vionaai --help
```

Tek mesaj:

```bash
vionaai ask "Viona API nedir?"
```

Model seç:

```bash
vionaai ask "Python kodu yaz" --model viona-codix-1.6
```

Ham JSON yanıtı:

```bash
vionaai ask "Merhaba" --json
```

Model listesi:

```bash
vionaai models
```

SDK bilgisi:

```bash
vionaai info
```

Geriye uyumluluk için `viona` CLI adı da aynı komuta yönlendirilmiştir.

---

## Client bilgisi

API key'i göstermeden yapılandırmayı görebilirsin:

```python
from Viona.api import Vionaai

client = Vionaai()
print(client.bilgi())
client.close()
```

Örnek yapı:

```python
{
    "sdk_version": "3.0.0",
    "api_version": "v1",
    "base_url": "https://dev.vionaai.site/api/v1",
    "default_model": "viona-ti-3.0",
    "timeout": 30.0,
    "max_retries": 2,
    "auth_mode": "bearer",
    "origin": None,
}
```

---

## Viona 3.0 API yapısı

### Chat

```text
POST /api/v1/chat
```

Örnek gövde:

```json
{
  "model": "viona-ti-3.0",
  "messages": [
    {"role": "user", "content": "Merhaba"}
  ],
  "temperature": 0.7,
  "max_tokens": 1024
}
```

### Models

```text
GET /api/v1/models
```

Tüm endpoint, authentication, kredi ve hata ayrıntıları için resmi dokümantasyon:

https://dev.vionaai.site/docs/

---

## Eski importtan geçiş

Eski kullanım:

```python
from Viona import Viona

client = Viona()
```

Yeni önerilen kullanım:

```python
from Viona.api import Vionaai

client = Vionaai()
```

Geriye uyumluluk alias'ları nedeniyle eski `Viona` sınıf adı 3.0.0'da çalışmaya devam eder.

---

## PyPI'de farklı hesaptan yayınlama

Bu dağıtımın PyPI proje adı artık:

```text
vionaai
```

Bu, eski `viona` dağıtımından bağımsız bir PyPI projesidir.

Build:

```bash
python -m pip install -U build twine
python -m build
```

Kontrol:

```bash
python -m twine check --strict dist/*
```

Yayın:

```bash
python -m twine upload -u __token__ dist/*
```

Yayınlandıktan sonra kurulum:

```bash
pip install vionaai
```

Import adı ise:

```python
from Viona.api import Vionaai
```

> PyPI proje adı ile Python import paketi aynı olmak zorunda değildir. Bu projede dağıtım adı `vionaai`, import namespace'i `Viona` olarak tasarlanmıştır.

---

## Güvenlik önerileri

- API key'i kaynak koda gömme.
- `.env` veya sunucu secret sistemi kullan.
- `.env` dosyasını Git'e ekleme.
- Sızıntı şüphesinde API key'i yenile veya iptal et.
- Tarayıcıdan doğrudan Viona API'ye bağlanmak yerine backend proxy kullan.
- Origin kısıtlamasını mimarine uygun yapılandır.
- `429`, `502`, `503` hatalarını uygulama seviyesinde kullanıcıya düzgün göster.

---

## Bağlantılar

- **Developer Panel:** https://dev.vionaai.site/
- **API Dokümantasyonu:** https://dev.vionaai.site/docs/
- **API Key Oluştur:** https://dev.vionaai.site/#keys

---

## Lisans

MIT License. Ayrıntılar için [LICENSE](LICENSE) dosyasına bakın.

© 2026 Viona AI · Orvix Games
