Metadata-Version: 2.4
Name: brsxcloud
Version: 0.7.0
Summary: BRSX-Cloud için resmi Python client — chat edilebilir modellere API key ile erişim
Author: BRSX Labs
License: MIT
Project-URL: Homepage, https://cloud.brsxlabs.com
Project-URL: Documentation, https://help.brsxlabs.com
Project-URL: Repository, https://brsxlabs.com
Keywords: brsx,brsx-cloud,ai,chat,api-client
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
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
Requires-Python: >=3.8
Description-Content-Type: text/markdown

# brsxcloud

[BRSX-Cloud](https://cloud.brsxlabs.com) için resmi Python client. Chat edilebilir olarak paylaşılmış modellere kendi API key'inle, kod içinden erişmeni sağlar.

## Kurulum

```bash
pip install brsxcloud
```

## API Key Alma

1. [cloud.brsxlabs.com](https://cloud.brsxlabs.com) adresinde giriş yap.
2. Sol menüden **Kullanıcı Paneli**'ni aç.
3. **API Anahtarların** bölümünden **+ Yeni Key** ile bir key oluştur.
4. Key sadece o an gösterilir, hemen kopyala — bir daha görüntülenmez.

Her key için günlük istek limiti vardır (panelde görebilirsin).

## En Hızlı Başlangıç: `api.run()`

Hiç kod yazmadan, tek satırla bir modelle sohbete başla:

```python
from brsxcloud import api

api.run()
```

İlk çalıştırmada mod, (gerekiyorsa) model ID ve API key sorulur; cevaplar çalışma dizinindeki `brsxcloud.json` dosyasına kaydedilir. Sonraki her çalıştırmada (aynı klasörden) hiç soru sormadan o dosyadan okunur. Çıkmak için `q` yaz.

**Modlar:**

| Mod | Ne yapar |
|---|---|
| Normal | Seçtiğin modelle konuşursun, cevap kelime kelime akar |
| Maestro | Sorunun türü belirlenir, o alanda benchmark'ta en iyi puanı almış modele gider |
| Maestro Hyper | Soru parçalara ayrılır, her parça kendi alanının en iyi modeline gider, cevaplar birleştirilir |

Maestro modları benchmark sonuçlarına dayanır: matematik sorusu Matematik kategorisinde en yüksek puanı almış modele, kod sorusu Kod'da en iyisine yönlendirilir. Skor sorunun diline göre seçilir — bir model Türkçede zayıf, İngilizcede güçlü olabilir.

## Maestro'yu Koddan Kullanma

```python
from brsxcloud import Client

client = Client("brsxk_...")

# Tek kategori — en iyi modele yönlendirir
sonuc = client.maestro("Bir havuzu A musluğu 6 saatte dolduruyor...")
print(sonuc["reply"])
print(sonuc["maestro"]["kategori"], "->", sonuc["maestro"]["model_adi"])

# Karışık soru — parçalara ayırıp her parçayı uzmanına gönderir
sonuc = client.maestro_hyper("Bileşik faiz hesaplayan bir Python fonksiyonu yaz, formülü açıkla ve uygulamaya isim öner.")
print(sonuc["reply"])
for p in sonuc["maestro_hyper"]["parcalar"]:
    print(p["kategori"], "->", p["model_adi"])
```

## Manuel Kullanım: `Client`

Kendi uygulamana entegre etmek istersen `Client` sınıfını doğrudan kullan:

```python
from brsxcloud import Client

client = Client("brsxk_...")  # kendi API key'in

reply = client.chat(model_id=1, message="Merhaba, nasılsın?")
print(reply)
```

`model_id`'yi, BRSX-Cloud'daki **Modeller** sekmesinde ya da **Kullanıcı Paneli**'ndeki model kartının üzerindeki ID etiketinden öğrenebilirsin (tıklayınca kopyalanır).

## Streaming: Kelime Kelime Akan Cevap

Cevabın tamamı üretilene kadar beklemek yerine, model ürettikçe parça parça almak için `chat_stream()` kullan:

```python
from brsxcloud import Client

client = Client("brsxk_...")

for chunk in client.chat_stream(model_id=1, message="Merhaba, nasılsın?"):
    print(chunk, end="", flush=True)
print()
```

`chat()` ile birebir aynı kota ve erişim kurallarına tabi, sadece cevabı bir generator olarak döner. Model sahibinin `chat.py`'sinde `yield` kullanıp kullanmamasına bağlı olarak gerçek token-token akış ya da tek parça halinde gelebilir — ikisinde de `chat_stream()` çalışır.

## Hata Yönetimi

```python
from brsxcloud import Client, BrsxCloudError

client = Client("brsxk_...")

try:
    reply = client.chat(model_id=1, message="Selam")
    print(reply)
except BrsxCloudError as e:
    print(f"Hata: {e.message} (durum kodu: {e.status_code})")
```

`chat_stream()` ile de aynı şekilde çalışır — hata akış sırasında da fırlatılabilir:

```python
try:
    for chunk in client.chat_stream(model_id=1, message="Selam"):
        print(chunk, end="", flush=True)
    print()
except BrsxCloudError as e:
    print(f"\nHata: {e.message} (durum kodu: {e.status_code})")
```

Olası hatalar: geçersiz/iptal edilmiş API key, günlük kota aşımı, model bulunamadı, model chat için paylaşılmamış, model çalıştırılırken hata.

## Yükleme

En kolay yol interaktif akış — hiçbir parametre ezberlemene gerek yok:

```python
from brsxcloud import api

api.upload()
```

Ne yükleyeceğini (model klasörü / GGUF / Fast Answers), yolu ve ayarları adım adım sorar. GGUF seçersen temperature ve context uzunluğunu da sorar, boş bırakırsan varsayılanı kullanır. Yükleme sırasında ilerleme çubuğu gösterir.

API key'i `brsxcloud.json`'dan okur; yoksa bir kez sorup kaydeder.

### Koddan yükleme

Otomasyon için doğrudan da çağırabilirsin:

```python
from brsxcloud import Client

client = Client("brsxk_...")

# SafeTensors/PT klasörü (içinde chat.py olmalı)
client.upload_model("./modelim", name="Modelim", description="Denemeler")

# GGUF dosyası — Ollama akışı, Modelfile parametreleri burada verilir
client.upload_model("./model.gguf", name="Qwen 0.5B",
                    temperature=0.8, num_ctx=4096,
                    system_prompt="Sen yardımsever bir asistansın.")
```

Hangi akışın kullanılacağı uzantıdan anlaşılır: `.gguf` ise Ollama, klasör ise SafeTensors/PT.

İlerlemeyi izlemek istersen:

```python
def ilerleme(gonderilen, toplam):
    print(f"\r{gonderilen * 100 // toplam}%", end="")

client.upload_model("./modelim", name="Modelim", on_progress=ilerleme)
```

Diğer parametreler: `chat_enabled` (varsayılan `True`), `open_source` (`False`), `use_gpu` (`True`).

## Fast Answers

Hazır soru-cevap çiftleri yükleyebilirsin. Bir soru havuzda varsa cevap **anında** döner — model hiç çalışmaz, bu hem hızlı hem GPU'yu meşgul etmez.

```python
client.upload_fast_answers("./sorular.json")
```

Desteklenen biçimler: `.json`, `.jsonl`, `.csv`, `.parquet`, `.txt`

```json
[
  {"soru": "Türkiye'nin başkenti neresidir?", "cevap": "Ankara"},
  {"soru": "2+2 kaç eder?", "cevap": "4"}
]
```

Alan adları esnek: `soru`/`question`/`q`/`prompt`, `cevap`/`answer`/`a`/`response`. CSV'de başlık satırı zorunlu, düz metinde `S:` / `C:` biçimi kullanılır.

Yüklenen her çift bir hakem modelden geçer; hatalı, alakasız ya da anlamsız olanlar elenir. İnceleme arka planda yapılır, sonucu sitedeki Fast Answers sekmesinden görebilirsin.

Eşleştirme yapılırken noktalama ve fazla boşluk yok sayılır — "2+2 kaç eder?" ile "2+2 kaç eder" aynı soru sayılır. Sohbette hazır cevap kullanıldığında yanıtın altında ⚡ işareti çıkar.

## Lisans

MIT
