Metadata-Version: 2.4
Name: vecsai
Version: 0.1.3
Summary: Vecsai: vector db for everyone
Author: Vecsai Team
Requires-Python: >=3.7
Description-Content-Type: text/markdown
Requires-Dist: requests>=2.25.1
Dynamic: author
Dynamic: description
Dynamic: description-content-type
Dynamic: requires-dist
Dynamic: requires-python
Dynamic: summary

# vecsai

**vecsai-db** sunucusu için Python istemci kütüphanesi. Full-text arama, vektör araması, doküman CRUD, toplu import/export ve daha fazlasını destekler.

## Kurulum

```bash
pip install vecsai
```

## Hızlı Başlangıç

```python
import vecsai

# İstemci oluştur
client = vecsai.client("localhost", 8137)

# Sağlık kontrolü
print(client.health())
```

## Koleksiyon Oluşturma

### Dict ile

```python
schema = {
    "name": "movies",
    "vector_index_impl": "hnsw",
    "fields": [
        {"name": "title", "type": "string", "locale": "tr"},
        {"name": "genres", "type": "string", "facet": True},
        {"name": "rating", "type": "float", "sort": True},
        {"name": "overview", "type": "string"},
        {
            "name": "embedding",
            "type": "vector",
            "vector_dim": 768,
            "vector_model": "nomic-embed-text-v2-moe",
            "index": True,
            "vector_source_fields": ["title", "overview"],
        },
    ],
    "default_sorting_field": "rating",
}

client.create_collection(schema)
```

### SchemaBuilder ile

```python
from vecsai import SchemaBuilder

schema = (
    SchemaBuilder("movies")
    .field("title", "string", locale="tr")
    .field("genres", "string", facet=True)
    .field("rating", "float", sort=True)
    .field("overview", "string")
    .vector_field("embedding", dim=768, model="nomic-embed-text-v2-moe",
                  source_fields=["title", "overview"])
    .sorting_field("rating")
    .vector_index("hnsw")
    .build()
)

client.create_collection(schema)
```

## Koleksiyon İşlemleri

```python
# Koleksiyonları listele
collections = client.list_collections()

# Koleksiyon detayı
info = client.get_collection("movies")

# Koleksiyon sil
client.delete_collection("movies")
```

## Doküman İşlemleri

```python
# Tekil doküman ekle
doc = client.create_document("movies", {
    "title": "Inception",
    "genres": "Sci-Fi",
    "rating": 8.8,
    "overview": "A thief who steals corporate secrets..."
})

# Doküman getir
doc = client.get_document("movies", "doc_id_123")

# Doküman güncelle (kısmi)
client.update_document("movies", "doc_id_123", {"rating": 9.0})

# Tekil doküman sil
client.delete_document("movies", "doc_id_123")

# Filtreyle topluca sil
client.delete_documents_by_filter("movies", "rating:<5.0")
```

## Toplu Import

```python
# Python listesi ile
docs = [
    {"title": "Film 1", "rating": 7.5},
    {"title": "Film 2", "rating": 8.1},
]
results = client.import_documents("movies", docs, action="create")

# JSONL string ile
jsonl = '{"title":"Film 1","rating":7.5}\n{"title":"Film 2","rating":8.1}'
results = client.import_jsonl("movies", jsonl, action="upsert")
```

## Dosya Yükleme (CSV/JSON/JSONL/Excel)

```python
# CSV yükle (arka planda çalışır)
job = client.upload_documents("movies", "data/movies.csv", action="create", format="csv")
print(job)  # {"message": "...", "job_id": "abc123"}

# Excel yükle (belirli sayfa)
job = client.upload_documents("movies", "data/movies.xlsx", format="excel", sheet="Sheet1")

# İş durumunu takip et
status = client.get_job(job["job_id"])
print(status)  # {"status": "completed", "imported": 1000, ...}
```

## Export

```python
# Tüm dokümanları JSONL olarak al
jsonl_data = client.export_documents("movies")
```

## Arama

### Full-text Arama

```python
results = client.search(
    "movies",
    q="inception",
    query_by="title,overview",
    filter_by="rating:>7.0",
    sort_by="rating:desc",
    facet_by="genres",
    page=1,
    per_page=10,
)

for hit in results["Hits"]:
    print(hit["Document"]["title"], hit["TextMatch"])
```

### Vektör Araması (Embedding ile)

```python
# Sunucu sorguyu otomatik embedding'e çevirir
results = client.vector_search(
    "movies",
    q="bilim kurgu uzay macerası",
    model="nomic-embed-text-v2-moe",
    k=5,
    filter_by="rating:>6.0",
)
```

### Vektör Araması (Doğrudan vektör ile)

```python
results = client.vector_search(
    "movies",
    vector=[0.1, 0.2, 0.3, ...],  # 768 boyutlu vektör
    k=10,
)
```

## Collection Nesnesi (Zincirleme Kullanım)

```python
movies = client.collection("movies")

# Doküman ekle
movies.add({"title": "Interstellar", "rating": 8.7})

# Arama
results = movies.search(q="interstellar", query_by="title")

# Vektör araması
results = movies.vector_search(q="uzay yolculuğu", k=5)

# Dosya yükle
job = movies.upload("data/movies.csv")

# Export
data = movies.export()

# Toplu import
movies.import_documents([{"title": "Film 1"}, {"title": "Film 2"}])
```

## Hata Yönetimi

```python
from vecsai import VecsaiError

try:
    client.get_collection("olmayan_koleksiyon")
except VecsaiError as e:
    print(e.status_code)  # 404
    print(e.message)      # hata mesajı
```

## Metrikler

```python
metrics = client.metrics()
print(metrics)  # Motor metrikleri (koleksiyon sayıları vb.)
```

## API Referansı

| Metod | Açıklama |
|-------|----------|
| `health()` | Sunucu sağlık kontrolü |
| `metrics()` | Motor metrikleri |
| `create_collection(schema)` | Koleksiyon oluştur |
| `list_collections()` | Koleksiyonları listele |
| `get_collection(name)` | Koleksiyon detayı |
| `delete_collection(name)` | Koleksiyon sil |
| `collection(name)` | Collection nesnesi al |
| `create_document(col, doc)` | Doküman oluştur |
| `get_document(col, id)` | Doküman getir |
| `update_document(col, id, updates)` | Doküman güncelle |
| `delete_document(col, id)` | Doküman sil |
| `delete_documents_by_filter(col, filter)` | Filtre ile toplu sil |
| `import_documents(col, docs, action)` | Toplu import (list) |
| `import_jsonl(col, jsonl, action)` | Toplu import (JSONL) |
| `upload_documents(col, path, ...)` | Dosya yükle |
| `export_documents(col)` | Dokümanları JSONL export |
| `search(col, q, query_by, ...)` | Full-text arama |
| `vector_search(col, q, vector, ...)` | Vektör araması |
| `get_job(job_id)` | İş durumu sorgula |
