Vector Store / embeddings API docs are incomplete and inconsistent (VecDBElement fields undocumented, conflicting import paths)

[JspIIV]

Summary

Tried to write an intelligent contract using the Vector Store / embeddings feature (py-lib-genlayer-embeddings runner) for semantic duplicate detection, following the "Vector Store" advanced feature page. Deployment repeatedly failed on GenLayer Studio with a generic Could not load contract schema error and no visible traceback, making it impossible to debug without a fully worked, verified example.

Specific documentation gaps found

1. Conflicting import paths for the embedding generator. Different sources describe the embedding model wrapper under two different module names:

   • from genlayer_embeddings import VecDB, SentenceTransformer (matches the sdk.genlayer.com/main/api/genlayer_embeddings.html API reference, which lists SentenceTransformer, SentenceTransformerFromPath, and VecDB all under the genlayer_embeddings package)
   • import genlayermodelwrappers then genlayermodelwrappers.SentenceTransformer(...) (matches the LogIndexer example referenced from the Vector Store docs page)

   It's unclear from the docs which module actually provides SentenceTransformer at runtime, or whether both work, or whether VecDB and SentenceTransformer are meant to come from two different packages simultaneously.

2. VecDBElement is never documented. The API reference states VecDB.knn() returns Iterator[VecDBElement[T, S, V, T]] and VecDB.get_by_id() returns VecDBElement[T, S, V, None], but there is no page documenting the VecDBElement class itself — no constructor, no attribute list. Contract authors have to guess field names like .value, .distance, .key with no way to confirm them before a live deploy attempt.

3. No complete, runnable example contract. The Vector Store page and related LogIndexer example are described in prose/summary form (e.g. "a get_closest_vector() method that uses self.vector_store.knn()") but a full, copy-pasteable contract source file (imports, Depends/Seq header, storage field declarations, dataclass usage with @allow_storage, and a working method body) does not appear to be published anywhere reachable from the docs site.

4. No guidance on debugging schema-load failures. When VecDB/embeddings-based contracts fail to deploy due to an import or API mismatch, GenLayer Studio surfaces only Could not load contract schema with no underlying Python traceback, and there's no doc page describing how to get more detail (e.g. a CLI command, log location, or local dry-run flag) for this specific failure mode.

Environment

• Attempted via GenLayer Studio (studionet), py-lib-genlayer-embeddings runner pinned as documented via the Seq dependency block pattern from other advanced-feature docs.

Ask

• Publish a complete, verified, copy-pasteable example contract using VecDB + an embedding generator (ideally the exact LogIndexer example referenced from the Vector Store page, in full).
• Add a dedicated VecDBElement reference page (or section) listing its exact attributes/types.
• Reconcile the genlayer_embeddings vs genlayermodelwrappers naming — state clearly which one contract authors should import from for SentenceTransformer.
• If possible, document any way to see the real Python traceback behind a "Could not load contract schema" error in Studio, since right now it's a dead end for debugging this category of failure.