Remove :storage-inmemory module, tests, and related code.

2026-09-23 03:48:38 +03:00
parent 84f5fd84f3
commit e447525059
105 changed files with 2732 additions and 1978 deletions
@@ -0,0 +1,74 @@
+# `:vector-index-api` — общий интерфейс ANN-индекса
+
+## Что это
+
+Pure-API модуль: интерфейсы и data-классы, общие для любых бэкендов
+ANN-поиска (approximate nearest neighbor). Никаких реализаций и
+платформенных зависимостей — только контракт.
+
+Используется как стабильный API-фасад между кодом, который хочет
+искать по embeddings, и реализациями (JVector, ksqlite, sqlite-vec,
+inmemory, ...). При замене бэкенда вызывающий код не меняется.
+
+## Где используется
+
+Реализации:
+
+- `:vector-index-jvector` — JVM-only ANN поверх JVector (Datadog).
+  RAM-only. Самый быстрый для больших датасетов.
+- `:vector-index-ksqlite` — KMP brute-force cosine в SQLite. Подходит
+  для ≤10K записей, имеет persistence "бесплатно".
+
+## Что внутри
+
+```kotlin
+interface VectorIndexStore : AutoCloseable {
+    val dimension: Int
+    suspend fun getSize(): Long
+    suspend fun search(embedding: FloatArray, limit: Int): List<VectorSearchResult>
+}
+
+interface MutableVectorIndexStore : VectorIndexStore {
+    suspend fun add(id: String?, embedding: FloatArray, payload: String?): VectorIndex
+    suspend fun delete(id: String): Boolean
+    suspend fun clear(): Long
+}
+
+class VectorIndex(val id: String, val embedding: FloatArray, val payload: String?)
+// equals/hashCode/toString переопределены руками (FloatArray не работает
+// корректно в data class).
+
+data class VectorSearchResult(val index: VectorIndex, val score: Float)
+
+class VectorIndexAlreadyExistsException : Exception()
+```
+
+**Конвенции:**
+- `id: String?` в `add()` — если `null`, реализация генерирует сама
+  (формат на усмотрении реализации).
+- `payload: String?` — opaque строка, реализация хранит как есть и не
+  интерпретирует.
+- `dimension` фиксируется на уровне индекса и проверяется при `add()` /
+  `search()`.
+- Все мутации и чтения — `suspend` для совместимости с нативной
+  блокировкой в JNI/JVector и I/O в ksqlite.
+- `search()` возвращает топ-K, отсортированный по убыванию score.
+- `close()` обязателен (наследуется от `AutoCloseable`).
+
+## Цели сборки
+
+KMP (все 9): jvm + linuxX64/Arm64 + macosX64/Arm64 + iosX64/Arm64/
+SimulatorArm64 + mingwX64. Pure-Kotlin stdlib + `kotlinx-coroutines-core`,
+никаких нативных зависимостей — поэтому собирается везде.
+
+## Текущий статус
+
+API стабилизирован. Реализации покрывают JVM и KMP-without-Apple.
+
+## Чего здесь НЕТ
+
+- Никакой сериализации (`@Serializable`) — типы транспортируются
+  через интерфейсы, не через JSON.
+- Никаких auto-generated id правил — реализации решают сами.
+- Никаких фильтров на `search()` — чистый ANN без predicate push-down
+  (если нужен фильтр, делать на стороне вызывающего кода после `search`).