Skip to content

Add vectorDB install/setup guidance: a vd-setup-backend skill + refreshed backend metadata #10

@thorwhalen

Description

@thorwhalen

vd's job includes helping users get set up with the vectorDBs it supports. Today that surface is thin.

Current state:

  • _backend_metadata (vd/util.py) carries only a one-line pip_install string per backend. Several are stale / inconsistent:
    • pineconepip install pinecone-client — the PyPI package was renamed to pinecone; pinecone-client is now the deprecated shim.
    • Some entries use vd[...] extras (chromapip install vd[chromadb]), others use raw client package names (pinecone-client, qdrant-client, pymilvus, faiss-cpu). pyproject.toml only defines a chromadb extra.
  • Server-based backends (qdrant, weaviate, milvus) need Docker or a running service — not just pip install. There is no guidance for that anywhere.
  • There is a dev skill (vd-add-backend) and a chooser skill (vd-backend-choose), but no skill that walks a user through downloading / installing / running a vectorDB.
  • compare.py + vd-backend-choose use hardcoded heuristics rooted in 2024-era assumptions.

Plan (depends on the deep-research report "11 — VectorDB Selection & Setup Guide", being commissioned — see the embeddings group docs/research/semantic_search/):

  • New user skill vd-setup-backend (bundled in vd/data/skills/): per-backend install / run playbooks — pip, Docker, docker-compose, embedded mode, cloud signup, and a verification step.
  • Refresh _backend_metadata from the report: correct install commands; add requires_server / install_modes / doc-link fields; define pyproject.toml extras for each implementable backend.
  • Add a vd.check_requirements(backend) helper (per the user's global package-UX guideline) that diagnoses what is missing and prints the next concrete step (with optional permissioned auto-install).
  • Refresh vd-backend-choose + compare.py from the report's decision framework so the recommendation logic reflects the 2026 landscape.

This is the user-facing half of "vd as a vendor-lock-in-avoiding facade": it is not enough to abstract the API — users also need help picking and standing up a backend.

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Type

    No type
    No fields configured for issues without a type.

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions