agentik/vector-index-api

: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 "бесплатно".

Что внутри

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).