vector stores.md

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

Parameter	Type	Required	Default	Description
`path`	`str \| None`	No	`"./chroma_data"`	Directory for persistent storage. Pass `None` for an in-memory ephemeral store.
`collection_name`	`str`	No	`"chunks"`	ChromaDB collection name.
`embedding_model`	`EmbeddingModel \| None`	No	`None`	External embedding model. When omitted, ChromaDB's built-in `all-MiniLM-L6-v2` model is used — no external API needed.

LanceDBStore

from guava.helpers.lancedb import LanceDBStore

Parameter	Type	Required	Default	Description
`path`	`str`	No	`"./lancedb_data"`	Local path or GCS URI (e.g. `"gs://bucket/lancedb"`) for storage.
`table_name`	`str`	No	`"chunks"`	LanceDB table name.
`embedding_model`	`EmbeddingModel`	Yes	—	Embedding model to use. Pass a configured instance such as `GenAIEmbedding` or `OpenAIEmbedding`.

PgVectorStore

from guava.helpers.pgvector import PgVectorStore

Parameter	Type	Required	Default	Description
`db_url`	`str`	Yes	—	PostgreSQL connection string (e.g. `"postgresql://user:pass@host/db"`).
`table_name`	`str`	No	`"guava_chunks"`	Table name for stored chunks.
`embedding_model`	`EmbeddingModel`	Yes	—	Embedding model to use. Pass a configured instance such as `GenAIEmbedding` or `OpenAIEmbedding`.

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

Parameter	Type	Required	Default	Description
`api_key`	`str \| None`	No	env `PINECONE_API_KEY`	Pinecone API key. If omitted, reads from the environment.
`index_name`	`str`	No	`"guava-chunks"`	Pinecone index name. Created automatically if it does not exist.
`cloud`	`str`	No	`"aws"`	Serverless cloud provider for index creation. Ignored if the index already exists.
`region`	`str`	No	`"us-east-1"`	Serverless region for index creation. Ignored if the index already exists.
`embedding_model`	`EmbeddingModel \| None`	No	`PineconeInferenceEmbedding`	Defaults to `multilingual-e5-large` (1024-dim) via Pinecone's hosted Inference API.

PineconeInferenceEmbedding

from guava.helpers.pinecone import PineconeInferenceEmbedding

Parameter	Type	Required	Default	Description
`pc`	`Pinecone`	Yes	—	A configured `Pinecone` client instance.
`model`	`str`	No	`"multilingual-e5-large"`	Pinecone inference model name.
`dimensionality`	`int`	No	`1024`	Output vector size.

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=...)).

Parameter	Type	Required	Default	Description
`client`	`google.genai.Client`	Yes	—	Configured Gemini client.
`model`	`str`	No	`"gemini-embedding-001"`	Gemini embedding model name.
`dimensionality`	`int`	No	`768`	Output vector size.

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.

Parameter	Type	Required	Default	Description
`client`	`google.genai.Client`	Yes	—	Configured Gemini client.
`model`	`str`	No	`"gemini-2.5-flash"`	Gemini chat model name.
`thinking_budget`	`int \| None`	No	`0`	Token budget for the model's internal thinking step. Default `0` disables thinking on `gemini-2.5-flash` for faster responses. Pass `None` for non-thinking models (e.g. `gemini-1.5-flash`). Pass a positive integer (e.g. `8192`) to enable extended thinking.

OpenAIEmbedding / OpenAIGeneration

from guava.helpers.openai import OpenAIEmbedding, OpenAIGeneration

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

OpenAIEmbedding — EmbeddingModel backed by the OpenAI Embeddings API.

Parameter	Type	Required	Default	Description
`client`	`openai.OpenAI`	Yes	—	Configured OpenAI client.
`model`	`str`	No	`"text-embedding-3-small"`	OpenAI embedding model name.
`dimensionality`	`int`	No	`1536`	Output vector size.

OpenAIGeneration — GenerationModel backed by OpenAI chat.completions.

Parameter	Type	Required	Default	Description
`client`	`openai.OpenAI`	Yes	—	Configured OpenAI client.
`model`	`str`	No	`"gpt-5-mini"`	OpenAI chat model name.

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?")