Vector Stores

Guava provides four ready-made VectorStore implementations that can be passed directly to DocumentQA as the store argument. Each wraps a popular vector database and handles embedding, indexing, and similarity search.

Installation

Install only the backend(s) you need:

• pip install 'guava-sdk[chromadb]'
• pip install 'guava-sdk[lancedb]'
• pip install 'guava-sdk[pgvector]'
• pip install 'guava-sdk[pinecone]'

Embedding and generation provider extras:

• pip install 'guava-sdk[genai]' — Google Gemini (backs GenAIEmbedding / GenAIGeneration)
• pip install 'guava-sdk[openai]' — OpenAI (backs OpenAIEmbedding / OpenAIGeneration)

Importing a backend class without the corresponding extra installed raises ImportError with an install hint.

ChromaVectorStore

from guava.helpers.chromadb import ChromaVectorStore

LanceDBStore

from guava.helpers.lancedb import LanceDBStore

PgVectorStore

from guava.helpers.pgvector import PgVectorStore

PgVectorStore creates the vector extension, chunks table, and HNSW cosine index automatically on first connect. If the connecting user lacks CREATE EXTENSION privileges, initialization will fail.

PineconeVectorStore

from guava.helpers.pinecone import PineconeVectorStore

PineconeInferenceEmbedding

from guava.helpers.pinecone import PineconeInferenceEmbedding

GenAIEmbedding / GenAIGeneration

from guava.helpers.genai import GenAIEmbedding, GenAIGeneration

Install: pip install 'guava-sdk[genai]'

GenAIEmbedding — EmbeddingModel backed by Google Gemini. Works with either a Vertex AI client (genai.Client(vertexai=True, project=..., location=...)) or an AI Studio client (genai.Client(api_key=...)).

Uses different task types under the hood: RETRIEVAL_DOCUMENT for embed_documents and QUESTION_ANSWERING for embed_query, which improves retrieval quality versus a single generic embedding.

GenAIGeneration — GenerationModel backed by Google Gemini.

OpenAIEmbedding / OpenAIGeneration

from guava.helpers.openai import OpenAIEmbedding, OpenAIGeneration

Install: pip install 'guava-sdk[openai]'

The caller supplies a configured openai.OpenAI instance. The same wrappers work against Azure OpenAI or any OpenAI-compatible base URL — the client object decides where requests go.

OpenAIEmbedding — EmbeddingModel backed by the OpenAI Embeddings API.

OpenAIGeneration — GenerationModel backed by OpenAI chat.completions.

The system_instruction argument to generate() is mapped to a {"role": "system", ...} message prepended to the user prompt.

GenerationModel

Any implementation of the guava.helpers.rag.GenerationModel interface works with DocumentQA in local mode. The examples on this page use GenAIGeneration, but OpenAIGeneration (above) or any custom GenerationModel subclass works equally well.

Examples

from guava.helpers.rag import DocumentQA
from guava.helpers.genai import GenAIEmbedding, GenAIGeneration
from google import genai

client = genai.Client(vertexai=True, project="my-project", location="us-central1")
embedding = GenAIEmbedding(client=client)   # gemini-embedding-001, 768-dim
generation = GenAIGeneration(client=client)  # gemini-2.5-flash


# ChromaDB — no external embedding API required; persists to disk by default
from guava.helpers.chromadb import ChromaVectorStore

store = ChromaVectorStore()                     # path="./chroma_data" by default
store = ChromaVectorStore(path=None)            # in-memory/ephemeral

qa = DocumentQA(store=store, generation_model=generation, documents=[doc1, doc2])
answer = qa.ask("What is the deductible?")


# LanceDB — local path or GCS URI; requires an embedding model
from guava.helpers.lancedb import LanceDBStore

store = LanceDBStore("./lancedb_data", embedding_model=embedding)
store = LanceDBStore("gs://my-bucket/lancedb", embedding_model=embedding)  # GCS

qa = DocumentQA(store=store, generation_model=generation, documents=[doc1, doc2])
answer = qa.ask("What is the deductible?")


# pgvector — Postgres connection string; table and indexes created automatically
from guava.helpers.pgvector import PgVectorStore

store = PgVectorStore(
    db_url="postgresql://user:password@localhost:5432/mydb",
    embedding_model=embedding,
)
qa = DocumentQA(store=store, generation_model=generation, documents=[doc1, doc2])
answer = qa.ask("What is the deductible?")


# Pinecone — set PINECONE_API_KEY; index and embeddings are fully managed
from guava.helpers.pinecone import PineconeVectorStore

store = PineconeVectorStore()                   # index_name="guava-chunks" by default

qa = DocumentQA(store=store, generation_model=generation, documents=[doc1, doc2])
answer = qa.ask("What is the deductible?")