{"id":50529169,"url":"https://github.com/gravitee-io/gravitee-resource-ai-vector-store-api","last_synced_at":"2026-06-03T11:01:55.722Z","repository":{"id":314095160,"uuid":"1013254588","full_name":"gravitee-io/gravitee-resource-ai-vector-store-api","owner":"gravitee-io","description":"Gravitee Base API of AI Vector Store resources","archived":false,"fork":false,"pushed_at":"2026-05-26T13:58:08.000Z","size":40,"stargazers_count":0,"open_issues_count":3,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-05-26T15:34:49.061Z","etag":null,"topics":["security-scan"],"latest_commit_sha":null,"homepage":null,"language":"Java","has_issues":false,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/gravitee-io.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":".github/CODEOWNERS","security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-07-03T15:41:45.000Z","updated_at":"2026-05-18T16:12:33.000Z","dependencies_parsed_at":"2026-03-23T20:03:21.875Z","dependency_job_id":null,"html_url":"https://github.com/gravitee-io/gravitee-resource-ai-vector-store-api","commit_stats":null,"previous_names":["gravitee-io/gravitee-resource-ai-vector-store-api"],"tags_count":4,"template":false,"template_full_name":null,"purl":"pkg:github/gravitee-io/gravitee-resource-ai-vector-store-api","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/gravitee-io%2Fgravitee-resource-ai-vector-store-api","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/gravitee-io%2Fgravitee-resource-ai-vector-store-api/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/gravitee-io%2Fgravitee-resource-ai-vector-store-api/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/gravitee-io%2Fgravitee-resource-ai-vector-store-api/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/gravitee-io","download_url":"https://codeload.github.com/gravitee-io/gravitee-resource-ai-vector-store-api/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/gravitee-io%2Fgravitee-resource-ai-vector-store-api/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":33860971,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-03T02:00:06.370Z","response_time":59,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["security-scan"],"created_at":"2026-06-03T11:01:54.876Z","updated_at":"2026-06-03T11:01:55.716Z","avatar_url":"https://github.com/gravitee-io.png","language":"Java","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Gravitee AI Vector Store Resource API\n\nAPI 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.\n\n## Overview\n\nThis 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.\n\n## Features\n\n- Reactive API using RxJava3 for non-blocking operations\n- Support for multiple similarity metrics (Euclidean, Cosine, Dot Product)\n- Multiple index types (Flat, IVF, HNSW)\n- Configurable eviction policies\n- Metadata support for vector entities\n- Spring-aware resource management\n\n## Building\n\n```bash\n# Compile\nmvn clean compile\n\n# Package\nmvn clean package\n\n# Install to local repository\nmvn clean install\n```\n\n## Core Interfaces\n\n### VectorStore\n\nMain interface for vector store operations:\n\n```java\npublic interface VectorStore extends ApplicationContextAware {\n  Completable add(VectorEntity vectorEntity);\n  Flowable\u003cVectorResult\u003e findRelevant(VectorEntity vectorEntity);\n  void remove(VectorEntity vectorEntity);\n  default Completable rxRemove(VectorEntity vectorEntity) { ... }\n}\n```\n\n### AiVectorStoreResource\n\nAbstract base class for implementations:\n\n```java\npublic abstract class AiVectorStoreResource\u003cC extends ResourceConfiguration\u003e\n  extends AbstractConfigurableResource\u003cC\u003e\n  implements VectorStore {\n\n  public \u003cT\u003e T getBean(Class\u003cT\u003e clazz) { ... }\n}\n```\n\n## Data Models\n\n### VectorEntity\n\nRepresents a vector with associated data:\n\n```java\npublic record VectorEntity(\n  String id,\n  String text,\n  float[] vector,\n  Map\u003cString, Object\u003e metadata,\n  long timestamp\n)\n```\n\n### VectorResult\n\nSearch result with similarity score:\n\n```java\npublic record VectorResult(VectorEntity entity, float score)\n```\n\n### AiVectorStoreProperties\n\nConfiguration for vector store behavior:\n\n```java\npublic record AiVectorStoreProperties(\n  int embeddingSize,        // Dimension of vectors\n  int maxResults,           // Max similarity search results\n  Similarity similarity,    // Distance metric\n  float threshold,          // Minimum similarity score\n  IndexType indexType,      // Index structure\n  boolean readOnly,         // Read-only mode\n  boolean allowEviction,    // Enable eviction\n  long evictTime,          // Eviction time\n  TimeUnit evictTimeUnit   // Time unit for eviction\n)\n```\n\n## Enums\n\n### Similarity\n\nDistance metrics with normalization:\n\n- `EUCLIDEAN`: Euclidean distance with normalization formula `2 / (2 + max(0, distance))`\n- `COSINE`: Cosine similarity\n- `DOT`: Dot product similarity\n\nEach provides a `normalizeDistance(float distance)` method to convert distances to [0, 1] scores.\n\n### IndexType\n\nVector index structures:\n\n- `FLAT`: Brute-force search (accurate but slow for large datasets)\n- `IVF`: Inverted File Index (balanced speed/accuracy)\n- `HNSW`: Hierarchical Navigable Small World (fast approximate search)\n\n## Implementing a Vector Store\n\n1. **Create a new module** for your implementation\n2. **Add dependency** on this API module:\n\n```xml\n\u003cdependency\u003e\n  \u003cgroupId\u003eio.gravitee.resource.ai.vector.store\u003c/groupId\u003e\n  \u003cartifactId\u003egravitee-resource-ai-vector-store-api\u003c/artifactId\u003e\n  \u003cversion\u003e1.0.0\u003c/version\u003e\n\u003c/dependency\u003e\n```\n\n3. **Extend AiVectorStoreResource**:\n\n```java\npublic class MyVectorStoreResource\n  extends AiVectorStoreResource\u003cMyVectorStoreConfiguration\u003e {\n\n  @Override\n  public Completable add(VectorEntity vectorEntity) {\n    // Implement adding vector to your store\n  }\n\n  @Override\n  public Flowable\u003cVectorResult\u003e findRelevant(VectorEntity vectorEntity) {\n    // Implement similarity search\n  }\n\n  @Override\n  public void remove(VectorEntity vectorEntity) {\n    // Implement vector removal\n  }\n}\n```\n\n4. **Create configuration class**:\n\n```java\npublic class MyVectorStoreConfiguration implements ResourceConfiguration {\n  private AiVectorStoreProperties properties;\n  // Additional config fields\n}\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgravitee-io%2Fgravitee-resource-ai-vector-store-api","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fgravitee-io%2Fgravitee-resource-ai-vector-store-api","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgravitee-io%2Fgravitee-resource-ai-vector-store-api/lists"}