Vector Store

Vector Store is a GenLayer feature for Intelligent Contracts that stores text as vector embeddings, retrieves entries, and calculates text similarity efficiently. Developers can use Vector Store for natural language processing (NLP) tasks such as context-aware applications and indexing text data for semantic search.

Key Features of Vector Store

The Vector Store provides several powerful features for managing text data:

1. Text Embedding Storage

You can store text data as vector embeddings, which are mathematical representations of the text, allowing for efficient similarity comparisons. Each stored text is associated with a vector and metadata.

2. Similarity Calculation

The Vector Store lets you find the nearest neighbors of a query vector via knn(), using a configurable distance metric (Euclidean by default). This is useful for finding the most semantically similar texts, enabling applications like recommendation systems or text-based search.

3. Metadata Management

Along with the text and vectors, you can store additional metadata (any data type) associated with each text entry. This allows developers to link additional information (e.g., IDs or tags) to the text for retrieval.

4. CRUD Operations

The Vector Store provides standard CRUD (Create, Read, Update, Delete) operations, allowing developers to add, update, retrieve, and delete text and vector entries efficiently.

How to Use Vector Store in Your Contracts

To use the Vector Store in your Intelligent Contracts, you will interact with its methods to add and retrieve text data, calculate similarities, and manage vector storage. Below are the details of how to use this feature.

Importing Vector Store

VecDB and the embedding generators live in the genlayer_embeddings package (the py-lib-genlayer-embeddings runner). Import it as a whole module — the individual class names are not re-exported from the top-level genlayer package:

import genlayer_embeddings as gle

VecDB also needs numpy imported before you import genlayer (whichever form you use — import genlayer as gl or from genlayer import *), per its own docstring:

import numpy as np
import genlayer as gl
from genlayer.types import *
from genlayer.storage import TreeMap
import genlayer_embeddings as gle

VecDB[T, S, V, D] type parameters

VecDB takes four type parameters:

genlayer_embeddings ships three ready-made metrics — gle.EuclideanDistance, gle.ManhattanDistance, gle.ChebyshevDistance — all true metrics safe for the cover-tree pruning knn() relies on.

VecDBElement reference

VecDB.knn() yields VecDBElement instances, and VecDB.get_by_id() returns one directly. VecDBElement isn't constructed by contract code — you always get one back from a VecDB method — but here's what's on it:

Creating a Contract with Vector Store

Here's a complete, verified example — the same LogIndexer contract used in GenLayer's own test suite — indexing and searching text logs by semantic similarity:

# v0.3.0
# {
#   "Seq": [
#     { "Depends": "py-lib-genlayer-embeddings:kr2rb2dcp01mw9khpg3tg2jasx4f82mcsy3eg08rjj1zdcm9q350" },
#     { "Depends": "py-genlayer:9b8kjyda2ycxyq4ea6g4yfpnydxhd52gqba5rb8dw7krkh5mn9p0" }
#   ]
# }
 
import numpy as np
import genlayer as gl
from genlayer.types import *
from genlayer.storage import TreeMap
import genlayer_embeddings as gle
 
from dataclasses import dataclass
import typing
 
 
@gl.storage.allow
@dataclass
class StoreValue:
    log_id: u256
    text: str
 
 
# contract class
class LogIndexer(gl.contract.Contract):
    # The v0.3 embeddings runner's VecDB takes an explicit metric type.
    vector_store: gle.VecDB[
        np.float32, typing.Literal[384], StoreValue, gle.EuclideanDistance
    ]
    log_vector_ids: TreeMap[u256, u32]
    removed_log_ids: TreeMap[u256, bool]
 
    def __init__(self):
        pass
 
    def get_embedding_generator(self):
        return gle.SentenceTransformer("all-MiniLM-L6-v2")
 
    def get_embedding(
        self, txt: str
    ) -> np.ndarray[tuple[typing.Literal[384]], np.dtypes.Float32DType]:
        return self.get_embedding_generator()(txt)
 
    @gl.public.view
    def get_closest_vector(self, text: str) -> dict | None:
        emb = self.get_embedding(text)
        for result in self.vector_store.knn(emb, len(self.vector_store)):
            log_id = result.value.log_id
            if log_id in self.removed_log_ids and self.removed_log_ids[log_id]:
                continue
            if log_id not in self.log_vector_ids:
                continue
            if self.log_vector_ids[log_id] != result.id:
                continue
            return {
                "vector": list(str(x) for x in result.key),
                "similarity": str(1 - result.distance),
                "id": result.value.log_id,
                "text": result.value.text,
            }
        return None
 
    @gl.public.write
    def add_log(self, log: str, log_id: int) -> None:
        key = log_id
        if key in self.log_vector_ids:
            self.vector_store.get_by_id(self.log_vector_ids[key]).value = StoreValue(
                text=log, log_id=key
            )
            return
 
        emb = self.get_embedding(log)
        vector_id = self.vector_store.insert(emb, StoreValue(text=log, log_id=key))
        self.log_vector_ids[key] = vector_id
 
    @gl.public.write
    def update_log(self, log_id: int, log: str) -> None:
        key = log_id
        if key in self.log_vector_ids:
            self.vector_store.get_by_id(self.log_vector_ids[key]).value = StoreValue(
                text=log, log_id=key
            )
            return
 
        emb = self.get_embedding(log)
        vector_id = self.vector_store.insert(emb, StoreValue(text=log, log_id=key))
        self.log_vector_ids[key] = vector_id
 
    @gl.public.write
    def remove_log(self, id: int) -> None:
        key = id
        if key in self.log_vector_ids:
            self.removed_log_ids[key] = True

SentenceTransformer(model_name) returns a plain callable (str -> np.ndarray), not a class instance — call it directly as self.get_embedding_generator()(txt) like the example above. It caches the loaded model internally, so repeated calls with the same model name are cheap.

Debugging a Could not load contract schema error

GenLayer Studio currently shows a generic "Could not load contract schema" banner with no further detail when the constructor-parameters step fails — this covers import errors, wrong VecDB type parameters, and any other exception the contract raises while GenVM introspects it, not just Vector Store issues.

The real Python traceback isn't lost — it's captured server-side and logged at INFO level (GenVM execution failures are treated as contract errors, not infrastructure errors, so they don't show up as ERROR-level logs). To see it:

docker compose logs jsonrpc -f

Look for the log line immediately after your deploy/schema-load attempt — it includes the captured stdout and GenVM execution log, which for an import or type error will show the underlying Python exception and stack trace.