TramAI - governed AI workflows for Java and Kotlin

tramai-vectorstore-spi

Version: 0.6.0
Status: Preview (published)
Role: Contract layer for Vector Database operations.

Purpose

This module provides the core VectorStore contract required by tramai-rag and implemented by the concrete store adapters (ChromaVectorStore, PgVectorStore). By keeping this layer separate from the implementations, you can switch vector databases without changing your RAG orchestration code — or write your own store against the same seam.

Core Concepts

  • VectorStore — the SPI contract:
    • suspend upsert(collection, vectors: List<VectorEntry>) — insert or replace a batch of vectors
    • suspend search(collection, query: FloatArray, topK: Int, filter: Map<String, String>? = null): List<SearchResult>
    • suspend delete(collection, ids: List<String>)
    • suspend listCollections(): List<String>
    • storeId(): String — implementation identifier ("chroma", "pgvector", …), defaulting to the class name
  • VectorEntry — id, vector (FloatArray), content, and metadata (string key/value pairs)
  • SearchResult — id, content, metadata, and the similarity score (range depends on the store's distance metric)

Embeddings are computed by tramai-embedding; the store only persists and searches the vectors you hand it.

Dependencies

// build.gradle.kts
dependencies {
    implementation(platform("dev.tramai:tramai-bom:0.6.0"))
    implementation("dev.tramai:tramai-vectorstore-spi")
}

When to use this module

  • You are building a custom vector database adapter.
  • You want to compile against the store contract without pulling in a specific backend client.

When NOT to use this module

  • You just want a working store — depend on tramai-vectorstore-chroma or tramai-vectorstore-pgvector instead (both export this SPI transitively).
Previous
Next