https://github.com/gravitee-io/gravitee-resource-ai-vector-store-api
Gravitee Base API of AI Vector Store resources
https://github.com/gravitee-io/gravitee-resource-ai-vector-store-api
security-scan
Last synced: about 1 month ago
JSON representation
Gravitee Base API of AI Vector Store resources
- Host: GitHub
- URL: https://github.com/gravitee-io/gravitee-resource-ai-vector-store-api
- Owner: gravitee-io
- License: apache-2.0
- Created: 2025-07-03T15:41:45.000Z (about 1 year ago)
- Default Branch: main
- Last Pushed: 2026-05-26T13:58:08.000Z (about 1 month ago)
- Last Synced: 2026-05-26T15:34:49.061Z (about 1 month ago)
- Topics: security-scan
- Language: Java
- Size: 39.1 KB
- Stars: 0
- Watchers: 0
- Forks: 0
- Open Issues: 3
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: LICENSE
- Codeowners: .github/CODEOWNERS
Awesome Lists containing this project
README
# Gravitee AI Vector Store Resource API
API definition for AI vector store resources in the Gravitee ecosystem. This module provides interfaces and contracts for implementing vector database resources that enable semantic search and similarity-based retrieval.
## Overview
This is an **API-only module** that defines the contract for vector store implementations. Concrete implementations (e.g., for Pinecone, Weaviate, Milvus, etc.) should be created in separate modules.
## Features
- Reactive API using RxJava3 for non-blocking operations
- Support for multiple similarity metrics (Euclidean, Cosine, Dot Product)
- Multiple index types (Flat, IVF, HNSW)
- Configurable eviction policies
- Metadata support for vector entities
- Spring-aware resource management
## Building
```bash
# Compile
mvn clean compile
# Package
mvn clean package
# Install to local repository
mvn clean install
```
## Core Interfaces
### VectorStore
Main interface for vector store operations:
```java
public interface VectorStore extends ApplicationContextAware {
Completable add(VectorEntity vectorEntity);
Flowable findRelevant(VectorEntity vectorEntity);
void remove(VectorEntity vectorEntity);
default Completable rxRemove(VectorEntity vectorEntity) { ... }
}
```
### AiVectorStoreResource
Abstract base class for implementations:
```java
public abstract class AiVectorStoreResource
extends AbstractConfigurableResource
implements VectorStore {
public T getBean(Class clazz) { ... }
}
```
## Data Models
### VectorEntity
Represents a vector with associated data:
```java
public record VectorEntity(
String id,
String text,
float[] vector,
Map metadata,
long timestamp
)
```
### VectorResult
Search result with similarity score:
```java
public record VectorResult(VectorEntity entity, float score)
```
### AiVectorStoreProperties
Configuration for vector store behavior:
```java
public record AiVectorStoreProperties(
int embeddingSize, // Dimension of vectors
int maxResults, // Max similarity search results
Similarity similarity, // Distance metric
float threshold, // Minimum similarity score
IndexType indexType, // Index structure
boolean readOnly, // Read-only mode
boolean allowEviction, // Enable eviction
long evictTime, // Eviction time
TimeUnit evictTimeUnit // Time unit for eviction
)
```
## Enums
### Similarity
Distance metrics with normalization:
- `EUCLIDEAN`: Euclidean distance with normalization formula `2 / (2 + max(0, distance))`
- `COSINE`: Cosine similarity
- `DOT`: Dot product similarity
Each provides a `normalizeDistance(float distance)` method to convert distances to [0, 1] scores.
### IndexType
Vector index structures:
- `FLAT`: Brute-force search (accurate but slow for large datasets)
- `IVF`: Inverted File Index (balanced speed/accuracy)
- `HNSW`: Hierarchical Navigable Small World (fast approximate search)
## Implementing a Vector Store
1. **Create a new module** for your implementation
2. **Add dependency** on this API module:
```xml
io.gravitee.resource.ai.vector.store
gravitee-resource-ai-vector-store-api
1.0.0
```
3. **Extend AiVectorStoreResource**:
```java
public class MyVectorStoreResource
extends AiVectorStoreResource {
@Override
public Completable add(VectorEntity vectorEntity) {
// Implement adding vector to your store
}
@Override
public Flowable findRelevant(VectorEntity vectorEntity) {
// Implement similarity search
}
@Override
public void remove(VectorEntity vectorEntity) {
// Implement vector removal
}
}
```
4. **Create configuration class**:
```java
public class MyVectorStoreConfiguration implements ResourceConfiguration {
private AiVectorStoreProperties properties;
// Additional config fields
}
```