ractogateway.rag.stores

RAG vector stores.

class ractogateway.rag.stores.BaseVectorStore[source]

Bases: ABC

Persist and search embedding vectors.

All vector stores share the same interface: add(), search(), delete(), clear(), and count(). The underlying storage backend is determined by the concrete subclass.

abstractmethod add(chunks)[source]

Add chunks (with embeddings) to the store.

Parameters:: chunks (list[Chunk]) – Chunks to index. Each chunk must have a non-None embedding.
Raises:: ValueError – If any chunk has embedding=None.
Return type:: None

abstractmethod search(embedding, top_k=5, filters=None)[source]

Search for the top_k most similar chunks.

Parameters:

embedding (list[float]) – Query embedding vector.
top_k (int) – Number of results to return.
filters (dict[str, Any] | None) – Optional metadata filters (store-specific format).

Return type:

list[RetrievalResult]

Returns:

list[RetrievalResult] – Ranked list of results (rank 1 = most similar).

abstractmethod delete(chunk_ids)[source]

Remove chunks with the given IDs from the store.

Return type:: None

abstractmethod clear()[source]

Remove all chunks from the store.

Return type:: None

abstractmethod count()[source]

Return the total number of indexed chunks.

Return type:: int

class ractogateway.rag.stores.ChromaStore(collection='ractogateway', *, path=None, host=None, port=8000, distance_function='cosine')[source]

Bases: BaseVectorStore

Vector store backed by ChromaDB.

Supports both in-process (path or None for ephemeral) and HTTP-client modes (host + port).

Parameters:

collection (str) – Name of the ChromaDB collection.
path (str | None) – Persist directory for a local persistent client. None = ephemeral.
host (str | None) – ChromaDB server host (enables HTTP client mode).
port (int) – ChromaDB server port (default 8000).
distance_function (str) – "cosine", "l2", or "ip" (inner product).

add(chunks)[source]

Add chunks (with embeddings) to the store.

Parameters:: chunks (list[Chunk]) – Chunks to index. Each chunk must have a non-None embedding.
Raises:: ValueError – If any chunk has embedding=None.
Return type:: None

search(embedding, top_k=5, filters=None)[source]

Search for the top_k most similar chunks.

Parameters:

embedding (list[float]) – Query embedding vector.
top_k (int) – Number of results to return.
filters (dict[str, Any] | None) – Optional metadata filters (store-specific format).

Return type:

list[RetrievalResult]

Returns:

list[RetrievalResult] – Ranked list of results (rank 1 = most similar).

delete(chunk_ids)[source]

Remove chunks with the given IDs from the store.

Return type:: None

clear()[source]

Remove all chunks from the store.

Return type:: None

count()[source]

Return the total number of indexed chunks.

Return type:: int

class ractogateway.rag.stores.FAISSStore(dimension=None, index_type='flat_ip')[source]

Bases: BaseVectorStore

Vector store backed by Facebook AI Similarity Search (FAISS).

Stores embeddings in a flat L2 or cosine (Inner Product) index. All data is in-memory; call save() / load() to persist.

Parameters:

dimension (int | None) – Embedding dimension. Inferred from the first add() call if None.
index_type (str) – "flat_l2" or "flat_ip" (inner product / cosine when normalised).

add(chunks)[source]

Add chunks (with embeddings) to the store.

Parameters:: chunks (list[Chunk]) – Chunks to index. Each chunk must have a non-None embedding.
Raises:: ValueError – If any chunk has embedding=None.
Return type:: None

search(embedding, top_k=5, filters=None)[source]

Search for the top_k most similar chunks.

Parameters:

embedding (list[float]) – Query embedding vector.
top_k (int) – Number of results to return.
filters (dict[str, Any] | None) – Optional metadata filters (store-specific format).

Return type:

list[RetrievalResult]

Returns:

list[RetrievalResult] – Ranked list of results (rank 1 = most similar).

delete(chunk_ids)[source]

Remove chunks with the given IDs from the store.

Return type:: None

clear()[source]

Remove all chunks from the store.

Return type:: None

count()[source]

Return the total number of indexed chunks.

Return type:: int

save(path)[source]

Persist the FAISS index to path.index and chunks to path.chunks.

Return type:: None

load(path)[source]

Load a previously saved index from path.

Return type:: None

class ractogateway.rag.stores.InMemoryVectorStore(similarity='cosine')[source]

Bases: BaseVectorStore

Pure-Python brute-force vector store — no extra dependencies.

This store keeps all chunks and their embeddings in memory. It is not suitable for production-scale corpora but requires no installation.

Parameters:: similarity (str) – Similarity function to use. Currently only "cosine" is supported.

add(chunks)[source]

Add chunks (with embeddings) to the store.

Parameters:: chunks (list[Chunk]) – Chunks to index. Each chunk must have a non-None embedding.
Raises:: ValueError – If any chunk has embedding=None.
Return type:: None

search(embedding, top_k=5, filters=None)[source]

Search for the top_k most similar chunks.

Parameters:

embedding (list[float]) – Query embedding vector.
top_k (int) – Number of results to return.
filters (dict[str, Any] | None) – Optional metadata filters (store-specific format).

Return type:

list[RetrievalResult]

Returns:

list[RetrievalResult] – Ranked list of results (rank 1 = most similar).

delete(chunk_ids)[source]

Remove chunks with the given IDs from the store.

Return type:: None

clear()[source]

Remove all chunks from the store.

Return type:: None

count()[source]

Return the total number of indexed chunks.

Return type:: int

class ractogateway.rag.stores.MilvusStore(collection='ractogateway', *, host='localhost', port=19530, uri=None, token=None, dimension=None, metric_type='IP', batch_size=100)[source]

Bases: BaseVectorStore

Vector store backed by Milvus or Zilliz Cloud.

Parameters:

collection (str) – Milvus collection name.
host (str) – Milvus server host (default "localhost").
port (int) – Milvus server port (default 19530).
uri (str | None) – Zilliz Cloud URI (overrides host/port when set).
token (str | None) – Zilliz Cloud API token.
dimension (int | None) – Embedding dimension. Inferred on first add.
metric_type (str) – "IP" (inner product / cosine) or "L2".
batch_size (int) – Vectors per insert batch.

add(chunks)[source]

Add chunks (with embeddings) to the store.

Parameters:: chunks (list[Chunk]) – Chunks to index. Each chunk must have a non-None embedding.
Raises:: ValueError – If any chunk has embedding=None.
Return type:: None

search(embedding, top_k=5, filters=None)[source]

Search for the top_k most similar chunks.

Parameters:

embedding (list[float]) – Query embedding vector.
top_k (int) – Number of results to return.
filters (dict[str, Any] | None) – Optional metadata filters (store-specific format).

Return type:

list[RetrievalResult]

Returns:

list[RetrievalResult] – Ranked list of results (rank 1 = most similar).

delete(chunk_ids)[source]

Remove chunks with the given IDs from the store.

Return type:: None

clear()[source]

Remove all chunks from the store.

Return type:: None

count()[source]

Return the total number of indexed chunks.

Return type:: int

class ractogateway.rag.stores.PGVectorStore(dsn, *, table='rag_chunks', dimension=None, distance='cosine', batch_size=100)[source]

Bases: BaseVectorStore

Vector store backed by PostgreSQL with the pgvector extension.

Parameters:

dsn (str) – PostgreSQL connection string (e.g. "postgresql://user:pass@localhost/mydb").
table (str) – Table name (default "rag_chunks").
dimension (int | None) – Embedding dimension. Inferred on first add.
distance (str) – "cosine", "l2", or "inner".
batch_size (int) – Rows per INSERT batch.

add(chunks)[source]

Add chunks (with embeddings) to the store.

Parameters:: chunks (list[Chunk]) – Chunks to index. Each chunk must have a non-None embedding.
Raises:: ValueError – If any chunk has embedding=None.
Return type:: None

search(embedding, top_k=5, filters=None)[source]

Search for the top_k most similar chunks.

Parameters:

embedding (list[float]) – Query embedding vector.
top_k (int) – Number of results to return.
filters (dict[str, Any] | None) – Optional metadata filters (store-specific format).

Return type:

list[RetrievalResult]

Returns:

list[RetrievalResult] – Ranked list of results (rank 1 = most similar).

delete(chunk_ids)[source]

Remove chunks with the given IDs from the store.

Return type:: None

clear()[source]

Remove all chunks from the store.

Return type:: None

count()[source]

Return the total number of indexed chunks.

Return type:: int

class ractogateway.rag.stores.PineconeStore(index_name, *, api_key=None, namespace='', batch_size=100)[source]

Bases: BaseVectorStore

Vector store backed by Pinecone cloud.

Parameters:

index_name (str) – Name of the Pinecone index (must already exist).
api_key (str | None) – Pinecone API key. Falls back to PINECONE_API_KEY env var.
namespace (str) – Pinecone namespace for logical data isolation.
environment – Deprecated Pinecone environment string (for legacy pod-based indexes).
batch_size (int) – Number of vectors per upsert batch.

add(chunks)[source]

Add chunks (with embeddings) to the store.

Parameters:: chunks (list[Chunk]) – Chunks to index. Each chunk must have a non-None embedding.
Raises:: ValueError – If any chunk has embedding=None.
Return type:: None

search(embedding, top_k=5, filters=None)[source]

Search for the top_k most similar chunks.

Parameters:

embedding (list[float]) – Query embedding vector.
top_k (int) – Number of results to return.
filters (dict[str, Any] | None) – Optional metadata filters (store-specific format).

Return type:

list[RetrievalResult]

Returns:

list[RetrievalResult] – Ranked list of results (rank 1 = most similar).

delete(chunk_ids)[source]

Remove chunks with the given IDs from the store.

Return type:: None

clear()[source]

Remove all chunks from the store.

Return type:: None

count()[source]

Return the total number of indexed chunks.

Return type:: int

class ractogateway.rag.stores.QdrantStore(collection='ractogateway', *, url=None, api_key=None, distance='cosine', dimension=None, batch_size=100)[source]

Bases: BaseVectorStore

Vector store backed by Qdrant.

Parameters:

collection (str) – Qdrant collection name.
url (str | None) – Qdrant server URL. None = in-memory.
api_key (str | None) – Qdrant cloud API key (optional).
distance (str) – "cosine", "euclid", or "dot".
dimension (int | None) – Vector dimension. Inferred on first add if None.
batch_size (int) – Points per upsert batch.

add(chunks)[source]

Add chunks (with embeddings) to the store.

Parameters:: chunks (list[Chunk]) – Chunks to index. Each chunk must have a non-None embedding.
Raises:: ValueError – If any chunk has embedding=None.
Return type:: None

search(embedding, top_k=5, filters=None)[source]

Search for the top_k most similar chunks.

Parameters:

embedding (list[float]) – Query embedding vector.
top_k (int) – Number of results to return.
filters (dict[str, Any] | None) – Optional metadata filters (store-specific format).

Return type:

list[RetrievalResult]

Returns:

list[RetrievalResult] – Ranked list of results (rank 1 = most similar).

delete(chunk_ids)[source]

Remove chunks with the given IDs from the store.

Return type:: None

clear()[source]

Remove all chunks from the store.

Return type:: None

count()[source]

Return the total number of indexed chunks.

Return type:: int

class ractogateway.rag.stores.WeaviateStore(class_name='RactoChunk', *, url=None, api_key=None, additional_headers=None, distance_metric='cosine', batch_size=100)[source]

Bases: BaseVectorStore

Vector store backed by Weaviate.

Supports embedded (local, no server needed), local server, and Weaviate Cloud (WCS) connections.

Parameters:

class_name (str) – Weaviate class (collection) name.
url (str | None) – Weaviate server URL. None = use embedded Weaviate.
api_key (str | None) – Weaviate Cloud API key.
additional_headers (dict[str, str] | None) – Extra HTTP headers (e.g. for OpenAI API key pass-through to Weaviate).
distance_metric (str) – "cosine" or "l2-squared".
batch_size (int) – Objects per batch import.

add(chunks)[source]

Add chunks (with embeddings) to the store.

Parameters:: chunks (list[Chunk]) – Chunks to index. Each chunk must have a non-None embedding.
Raises:: ValueError – If any chunk has embedding=None.
Return type:: None

search(embedding, top_k=5, filters=None)[source]

Search for the top_k most similar chunks.

Parameters:

embedding (list[float]) – Query embedding vector.
top_k (int) – Number of results to return.
filters (dict[str, Any] | None) – Optional metadata filters (store-specific format).

Return type:

list[RetrievalResult]

Returns:

list[RetrievalResult] – Ranked list of results (rank 1 = most similar).

delete(chunk_ids)[source]

Remove chunks with the given IDs from the store.

Return type:: None

clear()[source]

Remove all chunks from the store.

Return type:: None

count()[source]

Return the total number of indexed chunks.

Return type:: int