API Reference

This reference lists the public APIs implemented in the current PyAIStack RAG slice. Import RAG and its primary result types directly from pyaistack. Import feature-specific APIs from their matching module.

RAG runtime

Import	Purpose
`pyaistack.RAG`	Indexes documents, retrieves relevant chunks, and generates grounded answers.
`pyaistack.RAGConfig`	Configures retrieval, reranking candidates, relevance boundaries, context limits, and output display.
`pyaistack.Document`	Immutable indexed text with metadata.
`pyaistack.SearchResult`	A retrieved `Document` with cosine, optional fusion, and optional reranker scores.
`pyaistack.Citation`	Verified provenance for one context excerpt supplied to the model.
`pyaistack.RAGAnswer`	Generated answer text, retrieved sources, context excerpts, and citations.
`pyaistack.Reranker`	Protocol for an application-provided candidate scoring implementation.

`RAG` constructor

Parameter	Purpose
`embedding_model="embeddinggemma"`	Ollama embedding model used when no embedding provider is injected.
`llm_model="gemma3:4b"`	Ollama chat model used when no chat provider is injected.
`ollama_host="http://localhost:11434"`	Local or remote Ollama endpoint for default providers.
`embedding_provider`	Optional implementation of `EmbeddingProvider`.
`chat_provider`	Optional implementation of `ChatProvider`.
`vector_store`	Optional `InMemoryVectorStore`, `SQLiteVectorStore`, `PgVectorStore`, or compatible store.
`config`	Optional `RAGConfig` instance.
`chunker`	Optional `TextChunker` applied by `add_documents()`.
`reranker`	Optional `Reranker` that returns one score for each retrieved candidate.
`observers`	Optional provider-neutral observers for sanitized completed-operation events.
`system_prompt_suffix`	Optional application instruction appended to the grounded system prompt.

`RAG` methods

Method	Returns	Purpose
`add(texts, metadatas=None)`	`tuple[Document, ...]`	Embeds and indexes one string or a sequence of strings.
`add_documents(documents)`	`tuple[Document, ...]`	Indexes `LoadedDocument` objects, applying the configured chunker first.
`search(query, top_k=None, metadata_filter=None)`	`tuple[SearchResult, ...]`	Retrieves scored chunks without calling the LLM.
`ask(question, top_k=None, metadata_filter=None)`	`RAGAnswer`	Retrieves context and generates a grounded answer.
`clear()`	`None`	Removes all indexed documents from the configured store.
`document_count`	`int`	Number of indexed documents or chunks.

metadata_filter is an optional dictionary. Every specified entry must match: a scalar matches a scalar field exactly or one value in a metadata list, while a list against stored array metadata requires every requested value; against a stored scalar it matches any listed value. Filtering occurs before cosine scoring.

`RAGConfig` fields

Field	Default	Purpose
`top_k`	`3`	Maximum number of retrieved chunks.
`min_score`	`None`	Optional minimum cosine similarity score.
`max_context_chars`	`12000`	Maximum retrieved-context characters sent to the chat provider.
`include_sources`	`False`	Whether verified source details are appended to `RAGAnswer.text`.
`include_citations`	`False`	Whether exact-context citations are appended to `RAGAnswer.text`.
`insufficient_context_response`	Default grounded response	Returned without an LLM call when retrieved context is insufficient.
`min_context_results`	`1`	Minimum excerpts that must fit in context before generation.
`retrieval_mode`	`"vector"`	Select `"hybrid"` for keyword/vector rank fusion with a hybrid-capable store.
`candidate_k`	`20`	Candidate count per hybrid branch, at least the effective `top_k`.
`rerank_candidate_k`	`20`	Maximum candidates retrieved before a configured reranker selects `top_k`.
`observability_metadata_keys`	`()`	Optional allowlist of metadata keys included in indexing event details.

For hybrid retrieval, SearchResult.ranking_score holds an optional fusion score; score remains cosine similarity. When a reranker is configured, SearchResult.rerank_score holds its score. RAGAnswer.context_sources contains exact context excerpts, while sources remains the retrieved chunks. RAGAnswer.citations is deterministic provenance for those excerpts. See reranking and verified citations.

Custom stores may implement HybridVectorStore and ModelBoundStore from pyaistack.rag.protocols. These are optional capabilities; the basic VectorStore contract remains unchanged. SQLite and PostgreSQL stores support context-manager cleanup and idempotent close().

Observability

Import	Purpose
`pyaistack.observability.Observer`	Protocol defining `on_event(event)`.
`pyaistack.observability.RAGEvent`	Immutable sanitized operation event with `to_dict()`.
`pyaistack.observability.InMemoryObserver`	Keeps event snapshots in process memory.
`pyaistack.observability.LoggingObserver`	Emits sanitized JSON through standard logging.
`pyaistack.observability.JsonlObserver`	Appends sanitized JSON Lines to an application-selected file.
`pyaistack.evaluation.evaluate_retrieval_report`	Returns aggregate metrics and per-query retrieval outcomes.

See observability and evaluation.

Loaders

Import	Purpose
`pyaistack.loaders.TextLoader`	Loads one UTF-8 `.txt` file.
`pyaistack.loaders.DirectoryLoader`	Recursively loads UTF-8 `.txt` files; `file_type="text"` is required.
`pyaistack.loaders.LoadedDocument`	Immutable pre-index document containing `text` and `metadata`.
`pyaistack.loaders.FileType`	Enumerates supported types; currently only `FileType.TEXT`.
`pyaistack.loaders.MetadataFactory`	Protocol for a `create(path, text)` metadata generator.
`pyaistack.loaders.FolderMetadataFactory`	Creates deterministic fields from folders relative to a configured root.
`pyaistack.loaders.CSVMetadataFactory`	Reads JSON metadata from `source` and `metadata_json` CSV columns.
`pyaistack.loaders.LLMMetadataFactory`	Uses a `ChatProvider` to generate validated normalized JSON list metadata from a bounded sample.

Both loaders return tuple[LoadedDocument, ...]. TextLoader adds the source path to document metadata. DirectoryLoader.iter_load() yields one document at a time for sequential ingestion.

Chunking

Import	Purpose
`pyaistack.chunking.TextChunker`	Splits loaded documents into overlapping, separator-aware character chunks.

TextChunker preserves metadata and adds chunk metadata such as chunk_index, chunk_start, and chunk_end.

Vector stores

Import	Purpose
`pyaistack.vectorstores.InMemoryVectorStore`	Thread-safe, process-local exact cosine store for local development.
`pyaistack.vectorstores.SQLiteVectorStore`	Persistent local exact cosine store for small-to-medium indexes.
`pyaistack.vectorstores.PgVectorStore`	Collection-scoped PostgreSQL store with pgvector, JSONB filtering, full-text hybrid retrieval, and exact or ANN search.
`pyaistack.vectorstores.PgVectorSchema`	Immutable mapping from required vector-store semantics to compatible PostgreSQL table and column names.

All stores support search(query_vector, top_k, min_score=None, metadata_filter=None). SQLiteVectorStore(path) stores data in one database file. PgVectorStore requires the optional pyaistack[postgres] dependency.

`PgVectorStore` constructor

Supply exactly one connection style: dsn or connection_factory.

Parameter	Default	Purpose
`dimensions`	Required	Exact embedding-vector dimension and PostgreSQL `vector(n)` dimension.
`dsn`	`None`	PostgreSQL URI or libpq connection string; the store opens and closes each connection.
`connection_factory`	`None`	Application callback returning a bare connection or connection context manager.
`collection`	`"default"`	Fixed namespace applied to reads, writes, counts, and clear operations.
`schema`	`PgVectorSchema()`	Managed or application-owned compatible schema mapping.
`initialize`	`False`	Explicitly create missing managed schema objects and indexes.
`search_mode`	`"approximate"`	Use `"exact"` or require a compatible cosine ANN index for `"approximate"`.
`create_hnsw_index`	`True`	Create a cosine HNSW index during managed initialization.
`hnsw_m`	`16`	HNSW graph connectivity used when creating the managed index.
`hnsw_ef_construction`	`64`	HNSW construction candidate bound.
`hnsw_ef_search`	`40`	Per-operation HNSW search candidate bound.
`batch_size`	`500`	Maximum rows sent in each cursor batch inside one atomic `add()`.
`max_candidates`	`1000`	Maximum accepted `top_k` or hybrid `candidate_k`.
`max_query_chars`	`4096`	Maximum hybrid lexical query length.
`statement_timeout_ms`	`30000`	Transaction-local PostgreSQL statement timeout.
`connect_timeout_seconds`	`5`	Connection timeout used in DSN-owned mode.

`PgVectorStore` methods

Method	Purpose
`add(documents, vectors)`	Validate and insert documents in bounded batches within one transaction.
`search(query_vector, ...)`	Run collection-scoped cosine retrieval with JSONB metadata predicates.
`hybrid_search(query, query_vector, ...)`	Fuse PostgreSQL full-text and vector candidate rankings.
`set_embedding_model(model_name)`	Durably bind or validate the collection's embedding model.
`validate_schema()`	Validate pgvector, mapped types, nullability, uniqueness, vector dimensions, and the required ANN index.
`health_check()`	Verify connectivity and structural schema compatibility without writing documents.
`clear()`	Delete only the selected collection's documents while retaining model binding.
`close()`	Mark the store closed without closing application-owned pools or bare factory connections.
`len(store)`	Count documents in the selected collection.

`PgVectorSchema` fields

Field	Default
`schema_name`	`"pyaistack"`
`table_name`	`"documents"`
`collection_table_name`	`"collections"`
`collection_column`	`"collection_name"`
`id_column`	`"document_id"`
`text_column`	`"text"`
`metadata_column`	`"metadata"`
`vector_column`	`"embedding"`
`created_at_column`	`"created_at"`
`updated_at_column`	`"updated_at"`
`collection_created_at_column`	`"created_at"`
`model_column`	`"embedding_model"`
`dimensions_column`	`"dimensions"`
`schema_version_column`	`"schema_version"`

The three timestamp mappings may be set to None for compatible custom tables that intentionally omit those optional fields.

See PostgreSQL + pgvector for the compatible schema contract, connection ownership, security boundary, and operational requirements.

Providers

Import	Purpose
`pyaistack.providers.OllamaEmbeddingProvider`	Default Ollama embedding implementation; accepts `model` and optional `host`.
`pyaistack.providers.OllamaChatProvider`	Default Ollama chat implementation; accepts `model` and optional `host`.
`pyaistack.providers.EmbeddingProvider`	Protocol requiring `model_name` and `embed(texts)`.
`pyaistack.providers.ChatProvider`	Protocol requiring `model_name` and `chat(messages)`.

Pass custom provider instances through RAG(embedding_provider=..., chat_provider=...).

Errors

Import	Purpose
`pyaistack.format_error(error)`	Formats a PyAIStack error with the relevant application traceback frame.
`pyaistack.exceptions.AIStackError`	Base class for package-specific errors.
`pyaistack.exceptions.ProviderError`	Raised when an embedding or chat provider fails.
`pyaistack.exceptions.RerankerError`	Raised when reranking fails or returns invalid scores.
`pyaistack.exceptions.VectorStoreError`	Raised for vector-store validation or execution failures.
`pyaistack.exceptions.VectorStoreSchemaError`	Raised when PostgreSQL/pgvector schema requirements are incompatible.
`pyaistack.exceptions.VectorStoreConnectionError`	Raised when PostgreSQL connection acquisition fails.
`pyaistack.exceptions.VectorStoreTimeoutError`	Raised when PostgreSQL cancels an operation after its statement timeout.
`pyaistack.exceptions.VectorStoreConstraintError`	Raised when a PostgreSQL write violates a database constraint.
`pyaistack.exceptions.EmptyIndexError`	Raised when retrieval is requested before indexing.
`pyaistack.exceptions.LoaderError`	Raised when a document cannot be loaded.
`pyaistack.exceptions.MetadataFactoryError`	Raised when generated metadata is invalid or cannot be produced.
`pyaistack.exceptions.ChunkingError`	Raised for invalid chunking configuration or input.

LLMProviders

Name	State
Ollama	Local