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 count, score filtering, context limits, and source display.
`pyaistack.Document`	Immutable indexed text with metadata.
`pyaistack.SearchResult`	A retrieved `Document` with its cosine similarity score.
`pyaistack.RAGAnswer`	Generated answer text and its exact retrieved sources.

`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`, or compatible store.
`config`	Optional `RAGConfig` instance.
`chunker`	Optional `TextChunker` applied by `add_documents()`.
`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 requires every requested value to be present. 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`.

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.

Both stores support search(query_vector, top_k, min_score=None, metadata_filter=None). SQLiteVectorStore(path) stores data in one database file and provides close() when the connection is no longer needed.

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.VectorStoreError`	Raised for vector-store validation or execution failures.
`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.