hisamdb 1.0.0__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (61) hide show
  1. hisamdb-1.0.0/LICENSE +21 -0
  2. hisamdb-1.0.0/PKG-INFO +458 -0
  3. hisamdb-1.0.0/README.md +405 -0
  4. hisamdb-1.0.0/hisamdb/__init__.py +151 -0
  5. hisamdb-1.0.0/hisamdb/api/__init__.py +42 -0
  6. hisamdb-1.0.0/hisamdb/api/client.py +551 -0
  7. hisamdb-1.0.0/hisamdb/api/metrics.py +134 -0
  8. hisamdb-1.0.0/hisamdb/api/schemas.py +192 -0
  9. hisamdb-1.0.0/hisamdb/api/security.py +221 -0
  10. hisamdb-1.0.0/hisamdb/api/server.py +774 -0
  11. hisamdb-1.0.0/hisamdb/client.py +282 -0
  12. hisamdb-1.0.0/hisamdb/collection.py +2694 -0
  13. hisamdb-1.0.0/hisamdb/concurrency/__init__.py +15 -0
  14. hisamdb-1.0.0/hisamdb/concurrency/async_client.py +451 -0
  15. hisamdb-1.0.0/hisamdb/concurrency/executor.py +175 -0
  16. hisamdb-1.0.0/hisamdb/concurrency/rwlock.py +67 -0
  17. hisamdb-1.0.0/hisamdb/distance.py +30 -0
  18. hisamdb-1.0.0/hisamdb/filtering/__init__.py +5 -0
  19. hisamdb-1.0.0/hisamdb/filtering/metadata_index.py +627 -0
  20. hisamdb-1.0.0/hisamdb/indexes/__init__.py +17 -0
  21. hisamdb-1.0.0/hisamdb/indexes/disk_index.py +536 -0
  22. hisamdb-1.0.0/hisamdb/indexes/hnsw.py +351 -0
  23. hisamdb-1.0.0/hisamdb/indexes/ivf.py +656 -0
  24. hisamdb-1.0.0/hisamdb/indexes/ivf_pq.py +608 -0
  25. hisamdb-1.0.0/hisamdb/indexes/optimizer.py +290 -0
  26. hisamdb-1.0.0/hisamdb/ivf_index.py +10 -0
  27. hisamdb-1.0.0/hisamdb/metrics/__init__.py +33 -0
  28. hisamdb-1.0.0/hisamdb/metrics/kernels.py +215 -0
  29. hisamdb-1.0.0/hisamdb/metrics/native_simd.py +196 -0
  30. hisamdb-1.0.0/hisamdb/quantization/__init__.py +13 -0
  31. hisamdb-1.0.0/hisamdb/quantization/binary.py +134 -0
  32. hisamdb-1.0.0/hisamdb/quantization/float16.py +62 -0
  33. hisamdb-1.0.0/hisamdb/quantization/product.py +407 -0
  34. hisamdb-1.0.0/hisamdb/quantization/scalar.py +299 -0
  35. hisamdb-1.0.0/hisamdb/search/__init__.py +31 -0
  36. hisamdb-1.0.0/hisamdb/search/hybrid.py +109 -0
  37. hisamdb-1.0.0/hisamdb/search/rag.py +348 -0
  38. hisamdb-1.0.0/hisamdb/search/sparse.py +355 -0
  39. hisamdb-1.0.0/hisamdb/storage/__init__.py +42 -0
  40. hisamdb-1.0.0/hisamdb/storage/binary_format.py +274 -0
  41. hisamdb-1.0.0/hisamdb/storage/engine.py +1075 -0
  42. hisamdb-1.0.0/hisamdb/storage/vector_buffer.py +256 -0
  43. hisamdb-1.0.0/hisamdb/storage/wal.py +193 -0
  44. hisamdb-1.0.0/hisamdb/types.py +141 -0
  45. hisamdb-1.0.0/hisamdb.egg-info/PKG-INFO +458 -0
  46. hisamdb-1.0.0/hisamdb.egg-info/SOURCES.txt +59 -0
  47. hisamdb-1.0.0/hisamdb.egg-info/dependency_links.txt +1 -0
  48. hisamdb-1.0.0/hisamdb.egg-info/entry_points.txt +2 -0
  49. hisamdb-1.0.0/hisamdb.egg-info/requires.txt +28 -0
  50. hisamdb-1.0.0/hisamdb.egg-info/top_level.txt +1 -0
  51. hisamdb-1.0.0/pyproject.toml +78 -0
  52. hisamdb-1.0.0/setup.cfg +4 -0
  53. hisamdb-1.0.0/setup.py +5 -0
  54. hisamdb-1.0.0/tests/test_hisamdb.py +225 -0
  55. hisamdb-1.0.0/tests/test_optimizations.py +318 -0
  56. hisamdb-1.0.0/tests/test_phase1_core.py +582 -0
  57. hisamdb-1.0.0/tests/test_phase2_indexing.py +357 -0
  58. hisamdb-1.0.0/tests/test_phase3_hybrid_wal.py +388 -0
  59. hisamdb-1.0.0/tests/test_phase4_concurrency_async.py +346 -0
  60. hisamdb-1.0.0/tests/test_phase5_api_server.py +395 -0
  61. hisamdb-1.0.0/tests/test_phase6_scale_simd.py +219 -0
hisamdb-1.0.0/LICENSE ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 Ahmet GÜN
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
hisamdb-1.0.0/PKG-INFO ADDED
@@ -0,0 +1,458 @@
1
+ Metadata-Version: 2.4
2
+ Name: hisamdb
3
+ Version: 1.0.0
4
+ Summary: HisamDB — Cutting-edge, ultra-low-memory, hybrid-search & RAG vector database for Python (NumPy-only core)
5
+ Author: Ahmet GÜN
6
+ Maintainer: Ahmet GÜN
7
+ License-Expression: MIT
8
+ Project-URL: Homepage, https://github.com/Ahmet003-cod/HisamDB
9
+ Project-URL: Repository, https://github.com/Ahmet003-cod/HisamDB
10
+ Project-URL: Documentation, https://github.com/Ahmet003-cod/HisamDB#readme
11
+ Project-URL: Changelog, https://github.com/Ahmet003-cod/HisamDB/blob/main/CHANGELOG.md
12
+ Project-URL: Issues, https://github.com/Ahmet003-cod/HisamDB/issues
13
+ Keywords: hisamdb,vector-database,vectordb,rag,semantic-search,hybrid-search,bm25,hnsw,ivf,quantization,embeddings,numpy,llm,ai
14
+ Classifier: Development Status :: 5 - Production/Stable
15
+ Classifier: Intended Audience :: Developers
16
+ Classifier: Intended Audience :: Science/Research
17
+ Classifier: Operating System :: OS Independent
18
+ Classifier: Programming Language :: Python :: 3
19
+ Classifier: Programming Language :: Python :: 3.8
20
+ Classifier: Programming Language :: Python :: 3.9
21
+ Classifier: Programming Language :: Python :: 3.10
22
+ Classifier: Programming Language :: Python :: 3.11
23
+ Classifier: Programming Language :: Python :: 3.12
24
+ Classifier: Topic :: Database :: Database Engines/Servers
25
+ Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
26
+ Classifier: Topic :: Text Processing :: Indexing
27
+ Requires-Python: >=3.8
28
+ Description-Content-Type: text/markdown
29
+ License-File: LICENSE
30
+ Requires-Dist: numpy>=1.20.0
31
+ Provides-Extra: hnsw
32
+ Requires-Dist: hnswlib>=0.7.0; extra == "hnsw"
33
+ Provides-Extra: fast
34
+ Requires-Dist: orjson>=3.9.0; extra == "fast"
35
+ Provides-Extra: server
36
+ Requires-Dist: fastapi>=0.110.0; extra == "server"
37
+ Requires-Dist: uvicorn>=0.27.0; extra == "server"
38
+ Requires-Dist: pydantic>=2.0.0; extra == "server"
39
+ Provides-Extra: all
40
+ Requires-Dist: hnswlib>=0.7.0; extra == "all"
41
+ Requires-Dist: orjson>=3.9.0; extra == "all"
42
+ Requires-Dist: fastapi>=0.110.0; extra == "all"
43
+ Requires-Dist: uvicorn>=0.27.0; extra == "all"
44
+ Requires-Dist: pydantic>=2.0.0; extra == "all"
45
+ Provides-Extra: bench
46
+ Requires-Dist: psutil>=5.9.0; extra == "bench"
47
+ Requires-Dist: faiss-cpu>=1.7.4; extra == "bench"
48
+ Provides-Extra: dev
49
+ Requires-Dist: pytest>=7.0.0; extra == "dev"
50
+ Requires-Dist: psutil>=5.9.0; extra == "dev"
51
+ Requires-Dist: httpx>=0.27.0; extra == "dev"
52
+ Dynamic: license-file
53
+
54
+ # HisamDB ⚔️
55
+
56
+ [![Version](https://img.shields.io/badge/version-1.0.0-blue.svg)](https://github.com/Ahmet003-cod/HisamDB/blob/main/CHANGELOG.md)
57
+ [![PyPI](https://img.shields.io/pypi/v/hisamdb.svg)](https://pypi.org/project/hisamdb/)
58
+ [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://github.com/Ahmet003-cod/HisamDB/blob/main/LICENSE)
59
+ [![Python 3.8+](https://img.shields.io/badge/python-3.8+-brightgreen.svg)](https://www.python.org/)
60
+ [![Core Dependencies: NumPy](https://img.shields.io/badge/core%20dependencies-NumPy%20only-blueviolet.svg)](https://github.com/Ahmet003-cod/HisamDB/blob/main/requirements.txt)
61
+ [![Tests: 90/90 Passing](https://img.shields.io/badge/tests-90%2F90%20passing-success.svg)](https://github.com/Ahmet003-cod/HisamDB/tree/main/tests)
62
+
63
+ **HisamDB** *(**H**ybrid **I**ndexed **S**IMD **A**NN **M**emory **DB** — "Hisâm": keskin kılıç / cutting-edge)*, yapay zekâ uygulamaları (RAG, anlamsal arama, sohbet botları, öneri sistemleri) için geliştirilmiş; **yüksek performanslı**, **ultra düşük bellek (RAM) tüketimli**, **hibrit arama (Vektör + Metin)** destekli, **çökme korumalı (WAL)** ve çekirdeğinde **yalnızca `numpy`** gerektiren açık kaynaklı bir Python Vektör Veritabanıdır.
64
+
65
+ Gömülü Python kütüphanesi olarak tek satırda başlayabilir, `asyncio` ile binlerce eşzamanlı sorgu çalıştırabilir veya yerleşik **FastAPI + Docker REST sunucusu** ile üretim ortamına çıkabilirsiniz.
66
+
67
+ > **Felsefe:** *Cutting-Edge Performance + Ultra-Low Memory + Fast Retrieval + Reliable Storage + Developer Friendly*
68
+
69
+ ![HisamDB v1.0.0 Katmanlı Sistem Mimarisi](https://raw.githubusercontent.com/Ahmet003-cod/HisamDB/main/docs/assets/architecture_overview.png)
70
+
71
+ ---
72
+
73
+ ## 🧠 Teknik Kavramlar Sözlüğü (Herkes İçin Basit Anlatım)
74
+
75
+ Vektör veritabanlarına yeni başlıyorsanız aşağıdaki kısa sözlük, bu README'deki tüm grafikleri ve ayarları **hiç ön bilgi gerektirmeden** anlamanızı sağlar:
76
+
77
+ ### 1. Vektör (Embedding) Nedir?
78
+ Bilgisayarlar *"kedi"* ile *"yavru kedi"* kelimelerinin anlamca yakın olduğunu doğrudan bilemez. Yapay zekâ modelleri (OpenAI, BGE, MiniLM vb.) her metni, resmi veya belgeyi örneğin **384, 768 veya 1536 sayıdan oluşan bir koordinata** (vektöre) çevirir. Tıpkı bir şehir haritasındaki GPS koordinatları gibi, **anlamı benzer cümlelerin koordinatları birbirine yakın** olur. HisamDB bu milyonlarca koordinat içinde en yakınları milisaniyeler içinde bulur.
79
+
80
+ ### 2. Benzerlik Metrikleri (`Cosine`, `Euclidean`, `Dot Product`) Ne Demek?
81
+ İki vektörün ne kadar benzediğini ölçmenin 3 yolu vardır:
82
+ - **`cosine` (Kosinüs Benzerliği):** İki okun arasındaki **açıya** bakar (uzunluktan bağımsızdır). Metin ve RAG aramalarında en yaygın standarttır.
83
+ - **`euclidean` (Öklid / L2 Mesafesi):** Haritadaki **kuş uçuşu düz çizgi mesafesidir**. Görüntü ve sensör verilerinde sık kullanılır.
84
+ - **`dot_product` (İç Çarpım):** Hem yönü hem büyüklüğü birlikte ölçer. Öneri sistemleri ve önceden normalize edilmiş OpenAI/BGE vektörlerinde çok hızlıdır.
85
+
86
+ ### 3. İndeks Türleri (`Flat`, `IVF`, `IVF-PQ`, `HNSW`, `DiskIndex`) Arasındaki Fark Nedir?
87
+ 1 milyon kitaplık bir kütüphanede aradığınız kitabı nasıl bulursunuz?
88
+ - **`flat` (Tam Tarama):** Her rafa tek tek bakar. **%100 kesindir**, 10–50 bin kayda kadar çok hızlıdır; milyonlarca kayıtta yavaşlar.
89
+ - **`ivf` (Kümeleme / Inverted File):** Kitapları önce konularına göre örneğin 256 bölüme (kümeye) ayırır. Sorgu gelince tüm kütüphaneyi değil, yalnızca en ilgili 8–16 bölümü tarar.
90
+ - **`ivf_pq` (Kümeleme + Product Quantization):** Hem konulara ayırır hem de her vektörü parçalayıp **16–32 kat sıkıştırılmış özet kodlara** dönüştürür. 1 milyon vektör yalnızca ~43 MB RAM'e sığar!
91
+ - **`hnsw` (Çok Katlı Graf Ağı):** Tıpkı otoyol → ana cadde → sokak haritası gibi çok katmanlı bir kısayol ağı kurar. **1 milyon vektörde bile 0.60 milisaniyede** (saniyede 1.600+ sorgu) sonuç verir!
92
+ - **`disk` (`DiskIndex` + `MMap`):** Vektörleri RAM'e yüklemek yerine küme sırasına göre diskte düzenli tutar ve işletim sisteminin bellek eşleme (`mmap`) teknolojisiyle yalnızca ilgili parçayı okur. **1 milyon vektörde yalnızca 15.5 MB RAM** harcar ve **%100 doğruluk** verir!
93
+
94
+ ### 4. Kuantizasyon / Sıkıştırma (`Float32`, `Float16`, `INT8`, `Binary + Rescore`) Nedir?
95
+ Vektörlerdeki her sayı normalde 32 bit (`float32` = 4 bayt) yer kaplar. Tıpkı RAW fotoğrafı JPEG'e çevirmek gibi:
96
+ - **`float16`:** Sayıları yarı hassasiyete indirir → **2 kat daha az RAM**, neredeyse %100 doğruluk.
97
+ - **`int8` (`ScalarQuantizer`):** Her sayıyı `-128..+127` arası tek bayta sıkıştırır → **4 kat daha az RAM**, **%97–%99 doğruluk**.
98
+ - **`binary` + `rescore`:** Her sayıyı yalnızca `0` veya `1` (tek bit!) yapar → **32 kat daha az RAM**! Önce 1 bitlik parmak iziyle en yakın 200 adayı milisaniye altında süzer, ardından bu 200 adayı gerçek `float32` vektörlerle yeniden puanlayarak (`rescore`) doğruluğu (örneğin OpenAI 1536D'de) **%88+'e** çıkarır.
99
+
100
+ ### 5. Hibrit Arama (`Dense + BM25 + Sparse`) ve `RRF` Nedir?
101
+ - **Yalnızca Vektör (Dense):** *"Sunucu çöktü"* deyince *"sistem kesintisi"* belgesini harika bulur, ama **`ERR-9042`** gibi kesin bir hata kodunu veya fatura numarasını kaçırabilir.
102
+ - **Yalnızca Metin (`Okapi BM25`):** `ERR-9042` kodunu tam bulur, ama eş anlamlı cümleleri anlayamaz.
103
+ - **Hibrit Arama + `RRF` (Reciprocal Rank Fusion):** İki motoru aynı anda çalıştırır ve sonuç listelerini **sıralamalarına göre adil biçimde birleştirir** (`1 / (k + sıra)`). Sonuç: Aşağıdaki grafikte göreceğiniz gibi doğruluk **%53'ten %100'e** fırlar!
104
+ - **Sparse Vektör:** SPLADE veya BGE-M3 gibi modern yapay zekâ modellerinin ürettiği ağırlıklı kelime vektörleridir (`{kelime_id: ağırlık}`).
105
+
106
+ ### 6. RAG ve Parent-Child Bağlam Penceresi Nedir?
107
+ **RAG (Retrieval-Augmented Generation)**, ChatGPT/Claude/Gemini gibi bir LLM'e cevap vermeden önce kendi belgelerinizden ilgili parçaları bulup vermektir. HisamDB uzun PDF/Word dokümanlarını örtüşmeli parçalara (`chunk_text`) böler; arama bir cümleyi bulduğunda `retrieve_with_context(window=1)` ile o parçanın **bir önceki ve bir sonraki komşu parçalarını da** otomatik getirerek LLM'in bağlamı kaybetmesini önler.
108
+
109
+ ### 7. Güvenilirlik: `WAL`, `Tombstone`, `Compaction` ve `SHA-256 Snapshot` Nedir?
110
+ - **`WAL` (Write-Ahead Log):** Uçağın kara kutusu gibidir. Bir ekleme veya silme işlemi ana dosyalara işlenmeden önce CRC32 korumalı günlüğe yazılır; elektrik kesilse veya program çökse bile açılışta yarım kalan kayıtlar temizlenip veri kurtarılır.
111
+ - **`Tombstone` Silme & `Compaction`:** 100.000 vektörlü bir dosyadan 1 kayıt silmek için tüm dosyayı yeniden yazmak yerine (182 ms), o satıra bellekte *"silindi"* işareti (tombstone) konur (**0.40 ms — 451x daha hızlı!**). Silinenlerin oranı %25'i geçince `Compaction` arka planda boşlukları temizleyip dosyayı sıkıştırır.
112
+ - **`SHA-256 Snapshot`:** Veritabanının o anki tutarlı yedeğini alır ve her dosyanın kriptografik parmak izini (`SHA-256`) kaydeder. Geri yüklerken tek bir bit bile bozulmuşsa bunu yakalayıp uyarır.
113
+
114
+ ### 8. Grafiklerdeki Ölçüm Birimleri (`Recall@10`, `P50`, `P95`, `QPS`, `SIMD`) Ne Demek?
115
+ - **`Recall@10` / `Hit@10`:** Sistemin bulduğu ilk 10 sonucun, gerçekten en yakın olan 10 sonuçla ne kadar örtüştüğüdür (`1.00` = **%100 kusursuz**, `0.98` = 10 sonuçtan ortalama 9.8'i doğru).
116
+ - **`P50 (Medyan)` ve `P95` (ms):** Sorguların yarısının tamamlandığı tipik süre (`P50`) ve en yavaş %5'lik dilimin sınırı (`P95`). **Düşük olan daha iyidir** (`1 ms` = saniyenin binde biri!).
117
+ - **`QPS` (Queries Per Second):** Saniyede cevaplanan sorgu sayısıdır. **Yüksek olan daha iyidir.**
118
+ - **`SIMD` (`AVX2` / `FMA` / `POPCNT`):** Modern işlemcilerin tek bir komutta 1 sayı yerine **8 sayıyı aynı anda** çarpıp toplayabilmesi (`AVX2`) veya 64 bit içindeki `1` sayısını tek saat çevriminde sayabilmesidir (`POPCNT`). HisamDB'deki opsiyonel **Rust Native SIMD** çekirdeği tam olarak bu donanım gücünü kullanır.
119
+
120
+ ---
121
+
122
+ ## 🧭 Hangi Ayarı Seçmeliyim? (Hızlı Karar Rehberi)
123
+
124
+ | Kullanım Senaryosu | Önerilen Ayar | Beklenen Performans (Ölçülmüş) |
125
+ |---|---|---|
126
+ | **Küçük/Orta Proje (< 50K vektör)** | `index_type="flat"` *(varsayılan)* | `%100` kesin doğruluk, `0.2–3.5 ms` |
127
+ | **En Yüksek Hız & 100K–1M+ Vektör** | `index_type="hnsw"` (`pip install "hisamdb[hnsw]"`) | `1M` vektörde **`0.60 ms` (1,640 QPS)**, paralel batch **`18,765 QPS`** |
128
+ | **Çok Düşük RAM (1M Vektör veya 1536D OpenAI)** | `index_type="disk", use_mmap=True` | `1M` vektör → **`15.5 MB RAM`**, `25K×1536D` → **`0.95 MB RAM`**, **`%100` Recall!** |
129
+ | **Aşırı Sıkıştırılmış RAM İçi Arama** | `index_type="ivf_pq", keep_raw_vectors=False` | `1M` vektör → **`42.7 MB RAM` (-%91)**, **`2.36 ms`** *(Rust SIMD ile)* |
130
+ | **Kurumsal RAG / Doküman & Hata Kodu Arama** | `index_type="hnsw"` + `hybrid_search(fusion="rrf")` | **`0.94 ms` (1,033 QPS)**, **`Hit@10 = %100`** (Dense-Only `%53` idi!) |
131
+ | **Çok Kullanıcılı SaaS / Mikroservis** | `hisamdb-server` + `RemoteHisamDB` | `POST /search` **`3.94 ms`**, `/batch_search(64)` **`1,610 QPS`**, SHA-256 Tenant İzolasyonu |
132
+
133
+ ---
134
+
135
+ ## 📊 Doğrulanmış Performans Sonuçları ve Grafikler (`v1.0.0`)
136
+
137
+ *Tüm grafikler ve tablolar kanıtlanmamış tahmini rakam içermez; doğrudan bu depodaki [`benchmarks/results/`](https://github.com/Ahmet003-cod/HisamDB/tree/main/benchmarks/results) JSON kayıtlarından üretilmiştir. Donanım: Windows x86-64, 12 mantıksal Intel çekirdeği (AVX2/FMA/POPCNT), 15.73 GB RAM, Python 3.11.9, NumPy 2.0.2 (OpenBLAS), `rustc 1.96.0`, FAISS 1.13.2. Tam bilimsel rapor: [`BENCHMARK_REPORT.md`](https://github.com/Ahmet003-cod/HisamDB/blob/main/BENCHMARK_REPORT.md).*
138
+
139
+ ### 1. Mühendislik Evrimi Özeti (Gerçek Hızlanma Çarpanları)
140
+
141
+ ![HisamDB Evrimi v0.2.0 - v1.0.0 Hızlanma Grafiği](https://raw.githubusercontent.com/Ahmet003-cod/HisamDB/main/docs/assets/evolution_speedup.png)
142
+
143
+ | Optimizasyon Alanı | Eski Durum | HisamDB `v1.0.0` | Kazanım |
144
+ |---|---|---|---|
145
+ | **Tekil Kalıcı Silme (10K / 100K)** | `181.90 ms` *(v0.3)* | **`0.403 ms` / `0.382 ms`** *(Tombstone+WAL)* | **451.4x daha hızlı** |
146
+ | **Arka Plan İndeks İnşası Okuyucu Kesintisi** | `1,048 ms` tam bloklama | **P50=`0.363 ms` · Max=`3.99 ms`** *(2,212 canlı okuma)* | **262.6x düşük kesinti** |
147
+ | **100K %10 Filtreli Kosinüs Arama** | `59.32 ms` *(v0.2)* | **`0.479 ms`** *(HNSW + QueryOptimizer)* | **123.8x daha hızlı** |
148
+ | **Yoğun Silme Kuyruk Gecikmesi** | `49.89 ms` *(senkron)* | **`0.821 ms`** *(`auto_compact_async=True`)* | **60.8x düşük gecikme** |
149
+ | **50K × 768D Flat Öklid & Kosinüs RAM** | `116.3 ms` / `+297 MB` | **`7.99 ms` / `146.9 MB`** | **14.6x hızlı / -%50.6 RAM** |
150
+ | **100K Paralel Toplu Arama (HNSW, `w=8`)** | `7,659 QPS` *(1 işçi)* | **`18,765 QPS`** *(13.64 ms / 256 sorgu)* | **2.45x çok çekirdekli hız** |
151
+
152
+ ---
153
+
154
+ ### 2. Büyük Ölçek Performansı: `10.000 → 1.000.000` Vektör (128D vs C++ FAISS)
155
+
156
+ ![10K'dan 1 Milyon Vektöre Ölçek ve RAM Karşılaştırması](https://raw.githubusercontent.com/Ahmet003-cod/HisamDB/main/docs/assets/scale_1m_benchmark.png)
157
+
158
+ - **1.000.000 Vektörde `DiskIndex (MMap)`:** Ham veri `488.3 MB` iken yalnızca **`15.52 MB RAM` (-%96.8 tasarruf)** kullanarak **`9.56 ms`** gecikmeyle **`%100.0` (`1.000`) Recall@10** sağlar!
159
+ - **1.000.000 Vektörde `HNSW`:** **`0.605 ms` (`1,640 QPS`)** ile milisaniye-altı arama yapar ve `FAISS IndexHNSWFlat`'ten daha yüksek Recall@10 (`0.744` vs `0.736`) elde eder.
160
+ - **500.000 Vektörde `IVF-PQ (Rust SIMD)`:** **`1.548 ms` (`638 QPS`, Recall `0.192`)** ile C++ `FAISS IndexIVFPQ`'yu (`1.667 ms`, `604 QPS`, Recall `0.186`) hem hız hem doğrulukta geride bırakır!
161
+
162
+ ---
163
+
164
+ ### 3. Yüksek Boyutlu LLM Embedding'leri (`384D MiniLM`, `768D BGE/E5`, `1536D OpenAI`)
165
+
166
+ ![Yüksek Boyutlu LLM Embedding Performansı: RAM, Gecikme ve Doğruluk](https://raw.githubusercontent.com/Ahmet003-cod/HisamDB/main/docs/assets/memory_vs_recall.png)
167
+
168
+ - **OpenAI `1536D` (`25K` vektör, ham `146.5 MB`):**
169
+ - **`DiskIndex (MMap)`:** Yalnızca **`0.95 MB RAM` (-%99.4 tasarruf!)** ile **`1.50 ms` (`526 QPS`)** ve **`%100.0` Recall@10** — RAM'deki Flat Float32'den (`6.30 ms`) **4.2x daha hızlı!**
170
+ - **`Binary + Rescore (20x)`:** İkili indeks yalnızca **`4.58 MB RAM`** kaplar; **`0.98 ms` (`933 QPS`)** sürede **`%88.4` Recall@10** verir.
171
+ - **`INT8 (Rust SIMD)`:** **`36.8 MB RAM`** (4x tasarruf) ile **`%98.6` Recall@10** (`14.10 ms`, saf NumPy'dan `1.85x` hızlı).
172
+ - **`HNSW`:** **`0.405 ms` (`2,193 QPS`)** ve **`%99.2` Recall@10**.
173
+
174
+ ---
175
+
176
+ ### 4. Opsiyonel Rust Native SIMD (`AVX2 + FMA3 + POPCNT`) vs Saf NumPy vs C++ FAISS
177
+
178
+ ![Rust Native SIMD vs Saf NumPy vs C++ FAISS Karşılaştırması](https://raw.githubusercontent.com/Ahmet003-cod/HisamDB/main/docs/assets/simd_vs_numpy_vs_faiss.png)
179
+
180
+ Çekirdekte hiçbir zorunlu C/Rust derleyicisi olmadan %100 saf NumPy ile çalışan HisamDB, isteyen kullanıcılar için tek komutla derlenen sıfır-bağımlılıklı Rust SIMD çekirdeği (`kernels_experimental/hisam_simd.rs`) sunar:
181
+ - **Flat PQ (`100K × 128D`):** `9.41 ms → 1.95 ms` (**4.83x hızlanma**, P95 `2.18 ms` < FAISS `2.22 ms`).
182
+ - **Binary 64-bit POPCNT (`100K × 768D`):** `13.10 ms → 3.02 ms` (**4.33x hızlanma**, yalnızca `9.16 MB RAM`).
183
+ - **IVF-PQ (`100K × 128D`):** `1.18 ms → 0.62 ms` (**2.04x QPS**, P95 `0.77 ms` < FAISS `0.94 ms` ve **+%49.5 daha yüksek Recall@10**!).
184
+ - **INT8 Scalar (`128D / 768D / 1536D`):** **1.71x – 1.91x hızlanma** (`Recall@10 = %96.8 – %98.6`).
185
+
186
+ ---
187
+
188
+ ### 5. Neden Hibrit Arama? — Kurumsal RAG Doğruluk & Hız Kıyaslaması
189
+
190
+ ![Dense vs BM25 vs Hibrit RAG Doğruluk ve Hız Grafiği](https://raw.githubusercontent.com/Ahmet003-cod/HisamDB/main/docs/assets/hybrid_rag_accuracy.png)
191
+
192
+ 10.000 kurumsal dokümanda (hem anlamsal sorular hem kesin `ERR-XXXX` hata kodu / terim sorguları):
193
+ - Yalnızca vektör (`Dense-Only`) kesin kodları kaçırarak **%53 Hit@10**, yalnızca metin (`BM25-Only`) eş anlamlı ifadeleri kaçırarak **%50 Hit@10** alırken;
194
+ - **HisamDB Hibrit Arama (`Dense + BM25, RRF`)** yalnızca **`0.94 ms` (`1,033 QPS`)** sürede **`%100` (`1.000`) Hit@10** doğruluğuna ulaşır!
195
+
196
+ ---
197
+
198
+ ## 📦 Kurulum
199
+
200
+ ```bash
201
+ # 1. PyPI'dan temel kurulum (yalnızca numpy — sıfır ağır bağımlılık!):
202
+ pip install hisamdb
203
+
204
+ # 2. Opsiyonel HNSW graf indeksi desteği ile:
205
+ pip install "hisamdb[hnsw]"
206
+
207
+ # 3. Opsiyonel hızlı orjson metadata yükleyici ile:
208
+ pip install "hisamdb[fast]"
209
+
210
+ # 4. Opsiyonel üretim FastAPI REST sunucusu (FastAPI + Uvicorn + Pydantic):
211
+ pip install "hisamdb[server]"
212
+
213
+ # 5. Tüm performans ve sunucu eklentileri (hnswlib + orjson + server):
214
+ pip install "hisamdb[all]"
215
+
216
+ # 6. Kaynak koddan geliştirme ve benchmark araçlarıyla kurulum:
217
+ pip install -e ".[all,dev,bench]"
218
+ ```
219
+
220
+ ### Opsiyonel: Rust Native SIMD (`AVX2 + FMA3 + POPCNT`) Hızlandırması (İsteğe Bağlı)
221
+
222
+ Bilgisayarınızda Rust (`rustc`) varsa tek komutla yerel SIMD hızlandırıcısını derleyebilirsiniz — HisamDB bunu açılışta otomatik algılar (derlemezseniz hiçbir hata vermeden saf NumPy ile çalışır):
223
+
224
+ ```bash
225
+ # Windows (PowerShell):
226
+ rustc --crate-type cdylib -C opt-level=3 -C target-cpu=native kernels_experimental/hisam_simd.rs -o kernels_experimental/hisam_simd.dll
227
+
228
+ # Linux:
229
+ rustc --crate-type cdylib -C opt-level=3 -C target-cpu=native kernels_experimental/hisam_simd.rs -o kernels_experimental/libhisam_simd.so
230
+
231
+ # macOS:
232
+ rustc --crate-type cdylib -C opt-level=3 -C target-cpu=native kernels_experimental/hisam_simd.rs -o kernels_experimental/libhisam_simd.dylib
233
+ ```
234
+
235
+ ---
236
+
237
+ ## ⚡ Hızlı Başlangıç
238
+
239
+ ### 1. Hibrit Arama (Dense + BM25 + RRF) ve RAG Bağlam Penceresi
240
+
241
+ ```python
242
+ from hisamdb import HisamDB
243
+
244
+ with HisamDB("./rag_db") as db:
245
+ coll = db.get_or_create_collection(
246
+ name="knowledge_base",
247
+ dimension=4,
248
+ metric="cosine",
249
+ index_type="flat", # "flat", "ivf", "ivf_pq", "hnsw", "disk", "auto"
250
+ quantization="none", # "none", "float16", "int8", "binary", "pq"
251
+ )
252
+
253
+ # Dokümanları otomatik _doc_id / _parent_id / _chunk_index ile ekle
254
+ coll.add_documents(
255
+ documents=[
256
+ "İstanbul veri merkezi HNSW vektör veritabanı kurulum rehberi.",
257
+ "Sunucu bağlantı hatası ERR-9042 için WAL kurtarma ve checkpoint prosedürü.",
258
+ "Yedekleme sonrası SHA-256 doğrulamalı snapshot geri yükleme adımları.",
259
+ ],
260
+ embeddings=[
261
+ [0.95, 0.10, 0.05, 0.00],
262
+ [0.45, 0.88, 0.05, 0.00],
263
+ [0.10, 0.15, 0.96, 0.00],
264
+ ],
265
+ doc_ids=["ops_manual", "ops_manual", "ops_manual"],
266
+ metadatas=[{"category": "ops", "year": 2026}] * 3,
267
+ )
268
+
269
+ # Dense + Türkçe Okapi BM25 Hibrit Arama (RRF füzyon + tekilleştirme + filtre)
270
+ hits = coll.hybrid_search(
271
+ query_vector=[0.80, 0.50, 0.05, 0.00],
272
+ query_text="ERR-9042 WAL kurtarma",
273
+ limit=3,
274
+ alpha=0.5,
275
+ beta=0.5,
276
+ fusion="rrf", # "rrf", "weighted", "z_score"
277
+ deduplicate=True,
278
+ group_by="_doc_id",
279
+ max_per_group=2,
280
+ filter={"year": {"$gte": 2025}},
281
+ )
282
+ for item in hits:
283
+ print(item.id, round(item.score, 4), item.document)
284
+
285
+ # Parent-Child Bağlam Penceresi (önceki/sonraki komşu parçaları da getirir)
286
+ ctx = coll.retrieve_with_context(
287
+ query_vector=[0.45, 0.88, 0.05, 0.00],
288
+ query_text="ERR-9042",
289
+ limit=1,
290
+ window=1,
291
+ )
292
+ print("Birleştirilmiş Bağlam:", ctx[0]["context"])
293
+ ```
294
+
295
+ ### 2. Ultra Düşük RAM (`DiskIndex` / `MMap`), Multi-Tenant ve SHA-256 Snapshot
296
+
297
+ ```python
298
+ from hisamdb import HisamDB
299
+
300
+ with HisamDB("./prod_db", use_mmap=True) as db:
301
+ # 1M vektörde ~15.5 MB RAM ile %100 Recall:
302
+ db.get_or_create_collection("docs_large", dimension=1536, metric="cosine", index_type="disk", use_mmap=True)
303
+
304
+ # Katı Multi-Tenant İzolasyonu (SaaS uygulamaları için):
305
+ db.get_or_create_collection("saas", dimension=4, metric="cosine")
306
+ acme = db.get_tenant_collection("saas", "acme_corp")
307
+ beta = db.get_tenant_collection("saas", "beta_ltd")
308
+
309
+ acme.add(ids=["a1", "a2"], vectors=[[1, 0, 0, 0], [0.9, 0.1, 0, 0]], documents=["ACME gizli", "ACME rapor"])
310
+ beta.add(ids=["b1"], vectors=[[1, 0, 0, 0]], documents=["Beta gizli"])
311
+
312
+ # Beta, ACME'nin verisini ne görebilir ne de silebilir:
313
+ assert beta.delete(ids=["a1"]) == 0
314
+
315
+ # <1 ms Tombstone silme (WAL korumalı) + SHA-256 doğrulamalı yedekleme:
316
+ acme.delete(ids=["a2"])
317
+ db.create_snapshot("./backups/snap_v1")
318
+
319
+ # Tek bir bit bile bozulsa DataCorruptionError fırlatarak güvenli geri yükleme:
320
+ HisamDB.restore_snapshot("./backups/snap_v1", "./restored_db")
321
+ ```
322
+
323
+ ### 3. Asenkron İstemci (`AsyncHisamDB`), Paralel Batch & Bloklamayan Arka Plan Bakım
324
+
325
+ ```python
326
+ import asyncio
327
+ from hisamdb import AsyncHisamDB
328
+
329
+ async def main():
330
+ async with AsyncHisamDB("./async_db", max_workers=8) as db:
331
+ coll = await db.get_or_create_collection(
332
+ "docs", dimension=4, metric="cosine", index_type="hnsw",
333
+ index_params={"auto_compact_async": True},
334
+ )
335
+ await coll.add(ids=["1", "2"], vectors=[[1, 0, 0, 0], [0, 1, 0, 0]], documents=["İstanbul", "Ankara"])
336
+
337
+ # Eşzamanlı asyncio.gather() + çok çekirdekli batch_search()
338
+ hits = await asyncio.gather(
339
+ coll.hybrid_search(query_vector=[1, 0, 0, 0], query_text="İstanbul", limit=2),
340
+ coll.batch_search([[1, 0, 0, 0], [0, 1, 0, 0]], limit=2),
341
+ )
342
+ # Okuyucuları bloklamadan arka planda indeks yenileme (Snapshot-and-Swap)
343
+ await coll.rebuild_index_async()
344
+
345
+ asyncio.run(main())
346
+ ```
347
+
348
+ ### 4. Üretim FastAPI REST Sunucusu, Docker ve Sıfır-Bağımlılıklı Python SDK
349
+
350
+ ```bash
351
+ # Sunucuyu başlat (veya: docker compose up -d --build):
352
+ HISAM_API_KEYS="hisam_admin_key:admin:read,write,admin" hisamdb-server --host 0.0.0.0 --port 8000
353
+ ```
354
+
355
+ ```python
356
+ from hisamdb import RemoteHisamDB
357
+
358
+ # Harici requests/httpx gerektirmez — standart kütüphane Keep-Alive HTTP/1.1 SDK!
359
+ with RemoteHisamDB("http://127.0.0.1:8000", api_key="hisam_admin_key") as db:
360
+ coll = db.get_or_create_collection("docs", dimension=4, metric="cosine")
361
+ coll.add(ids=["1"], vectors=[[1, 0, 0, 0]], documents=["İstanbul sunucu kılavuzu"])
362
+ hits = coll.hybrid_search(query_vector=[1, 0, 0, 0], query_text="İstanbul", limit=3)
363
+ print(hits[0].id, round(hits[0].score, 4))
364
+ ```
365
+
366
+ ### 5. ChromaDB Stili Klasik API
367
+
368
+ ```python
369
+ import hisamdb
370
+
371
+ client = hisamdb.PersistentClient(path="./my_hisamdb", use_mmap=False)
372
+ collection = client.get_or_create_collection(name="makaleler", metric="cosine")
373
+ collection.add(ids=["doc1"], embeddings=[[0.9, 0.1, 0.0]], documents=["Merhaba"], metadatas=[{"tag": "v1"}])
374
+ res = collection.query(query_embeddings=[[0.9, 0.1, 0.0]], n_results=1, where={"tag": "v1"})
375
+ client.close()
376
+ ```
377
+
378
+ ---
379
+
380
+ ## 📁 Proje Mimarisi
381
+
382
+ ```text
383
+ HisamDB/
384
+ ├── hisamdb/
385
+ │ ├── __init__.py # Ana paket arayüzü (v1.0.0)
386
+ │ ├── client.py # HisamDB, PersistentClient, EphemeralClient, Snapshot & Multi-Tenant
387
+ │ ├── collection.py # Collection koordinatörü (RWLock, Optimizer, Hybrid/RAG, Tombstone, WAL, BG)
388
+ │ ├── types.py # QueryPlan, QueryResult, SearchResultItem ve özel hatalar
389
+ │ ├── metrics/ # inv_norms Kosinüs, sq_norms Öklid, Dot + opsiyonel native_simd yükleyici
390
+ │ ├── storage/ # VectorBuffer (lazy mmap), .mvdbvec, .items.mvdbcol, ikili WAL, SQLite + Snapshot
391
+ │ ├── filtering/ # Tembel ters metadata indeksi ($eq..$nin, $and/$or/$not, nested)
392
+ │ ├── quantization/ # Scalar (INT8), Float16, Binary (POPCNT), ProductQuantizer (PQ)
393
+ │ ├── indexes/ # IVF, Precomputed IVF-PQ, DiskIndex + Streaming, HNSW, QueryOptimizer
394
+ │ ├── search/ # Vektörize Okapi BM25, SparseVectorIndex, RRF/Weighted Füzyon, RAG & Multi-Tenant
395
+ │ ├── concurrency/ # RWLock, BatchQueryExecutor, BackgroundTaskManager, AsyncHisamDB
396
+ │ ├── api/ # FastAPI REST sunucusu, SHA-256 Auth/Tenant, Rate Limiter, Prometheus /metrics, HTTP SDK
397
+ │ ├── distance.py # Klasik mesafe uyumluluk cephesi -> metrics/
398
+ │ └── ivf_index.py # Klasik IVF uyumluluk cephesi -> indexes/ivf.py
399
+ ├── kernels_experimental/
400
+ │ ├── hisam_simd.rs # Opsiyonel sıfır-bağımlılıklı Rust AVX2+FMA3+POPCNT çekirdeği
401
+ │ ├── avx2_dot_product.c # Referans C/AVX2 SIMD örneği
402
+ │ └── README.md # Tek komutla derleme & Python kullanımı
403
+ ├── benchmarks/
404
+ │ ├── run_benchmarks*.py # Faz 1..6 (10K → 1M, 384D–1536D, Hybrid, Async, HTTP REST, Native SIMD)
405
+ │ ├── generate_charts.py # Gerçek JSON sonuçlarından 6 görsel PNG üreticisi
406
+ │ └── results/ # Ham JSON ve CSV ölçüm kayıtları
407
+ ├── docs/
408
+ │ ├── assets/ # README ve rapor görselleri (6 yüksek çözünürlüklü PNG)
409
+ │ ├── API_SERVER.md # REST API, güvenlik, Prometheus, SDK ve Docker dağıtım rehberi
410
+ │ ├── RELIABILITY.md # Açık ACID garanti matrisi, WAL ve eşzamanlılık sözleşmesi
411
+ │ └── ARCHITECTURE_SCALE_RESEARCH.md # Native SIMD, GPU/CUDA ve v2.x Dağıtık Mimari araştırma raporu
412
+ ├── tests/ # 90/90 birim, bütünlük, WAL, hibrit/RAG, async, stres, REST ve SIMD parite testi
413
+ ├── examples/ # 7 çalışan örnek (quickstart..async..REST sunucu + SDK)
414
+ ├── Dockerfile # Çok aşamalı non-root üretim imajı (HEALTHCHECK dahil)
415
+ ├── docker-compose.yml # Kalıcı hacimli ve ortam yapılandırmalı Compose tanımı
416
+ ├── ARCHITECTURE_AUDIT.md # Başlangıç mimari ve performans denetimi
417
+ ├── BENCHMARK_REPORT.md # Tam bilimsel benchmark raporu (Faz 1..6)
418
+ ├── ROADMAP.md # 6/6 fazı tamamlanmış mühendislik yol haritası
419
+ └── CHANGELOG.md # Sürüm geçmişi
420
+ ```
421
+
422
+ ---
423
+
424
+ ## 🗺️ Dokümantasyon
425
+
426
+ - [`BENCHMARK_REPORT.md`](https://github.com/Ahmet003-cod/HisamDB/blob/main/BENCHMARK_REPORT.md) — Tüm fazların tam ölçüm tabloları (`10K → 1M`, `128D–1536D`, SIMD, Hibrit RAG, Async, HTTP REST)
427
+ - [`docs/ARCHITECTURE_SCALE_RESEARCH.md`](https://github.com/Ahmet003-cod/HisamDB/blob/main/docs/ARCHITECTURE_SCALE_RESEARCH.md) — Native Rust SIMD analizi, GPU/CUDA fizibilitesi ve `v2.x` dağıtık sharding/Raft/gRPC taslağı
428
+ - [`docs/API_SERVER.md`](https://github.com/Ahmet003-cod/HisamDB/blob/main/docs/API_SERVER.md) — FastAPI REST sunucusu, SHA-256 Auth/Tenant güvenliği, Prometheus `/metrics`, Python SDK ve Docker
429
+ - [`docs/RELIABILITY.md`](https://github.com/Ahmet003-cod/HisamDB/blob/main/docs/RELIABILITY.md) — Açık ACID garanti matrisi, `wal_sync` modları, çökme kurtarma ve eşzamanlılık sözleşmesi
430
+ - [`ARCHITECTURE_AUDIT.md`](https://github.com/Ahmet003-cod/HisamDB/blob/main/ARCHITECTURE_AUDIT.md) — Başlangıç denetimi ve çözülen darboğazların kökeni
431
+ - [`ROADMAP.md`](https://github.com/Ahmet003-cod/HisamDB/blob/main/ROADMAP.md) & [`CHANGELOG.md`](https://github.com/Ahmet003-cod/HisamDB/blob/main/CHANGELOG.md) — Tamamlanan 6 fazın yol haritası ve sürüm notları
432
+
433
+ ---
434
+
435
+ ## 🧪 Test, Benchmark ve Grafik Üretimi
436
+
437
+ ```bash
438
+ # Tüm testler (90/90):
439
+ python -m unittest discover -s tests -v
440
+
441
+ # Faz 6 1M / 1536D / Native SIMD benchmark paketi:
442
+ python benchmarks/run_benchmarks_v10.py
443
+
444
+ # Gerçek JSON sonuçlarından tüm grafikleri yeniden üret:
445
+ python benchmarks/generate_charts.py
446
+
447
+ # Uçtan uca demolar:
448
+ python examples/05_hybrid_rag_and_reliability.py
449
+ python examples/06_async_and_parallel.py
450
+ python examples/07_rest_server_and_sdk.py
451
+ ```
452
+
453
+ ---
454
+
455
+ ## 👨‍💻 Geliştirici & Lisans
456
+
457
+ **Ahmet GÜN** · GitHub: [@Ahmet003-cod](https://github.com/Ahmet003-cod)
458
+ Bu proje **[MIT Lisansı](https://github.com/Ahmet003-cod/HisamDB/blob/main/LICENSE)** ile lisanslanmıştır.