> ## Documentation Index
> Fetch the complete documentation index at: https://docs.goguava.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Vector Stores

> Ready-made vector store backends for DocumentQA local mode

Guava provides four ready-made `VectorStore` implementations that can be passed directly to [`DocumentQA`](/sdk-reference/document-qa) as the `store` argument. Each wraps a popular vector database and handles embedding, indexing, and similarity search.

<Note>
  **Python only:** Vector store backends are currently available in Python only. TypeScript equivalents are not yet available.
</Note>

## 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`. |

<Note>
  LanceDB silently drops tables that predate the current schema version. This triggers a full re-index the next time `DocumentQA` ingests documents.
</Note>

## 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.

<Info>
  **Managed Postgres:** Managed services (Cloud SQL, AlloyDB, RDS) are untested but expected to work since the implementation uses standard `psycopg`.
</Info>

## 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. |

<Info>
  **Cold start:** Pinecone index creation can take 30–60 seconds on first use. Subsequent instantiations with the same `index_name` skip creation and connect immediately.
</Info>

## 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. |

<Warning>
  **thinking\_budget compatibility:** The default `thinking_budget=0` works with `gemini-2.5-flash`. If you switch to a non-thinking model like `gemini-1.5-flash`, pass `thinking_budget=None` — that model raises an error when it receives a `thinking_config`.
</Warning>

## 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.

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

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

```python vector_store_examples.py theme={null}
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?")
```


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.