Skip to content

PyAIStack

PyAIStack is a lightweight, modular microframework for building AI applications.

  1. Set up PyAIStack
  2. Run a ready example
  3. Build a basic RAG application
  4. Load and chunk local text files
  5. Use the SQLite store
  6. Use PostgreSQL + pgvector
  7. Improve retrieval with reranking
  8. Measure RAG runs

Implemented feature modules

RAG runtime

  • RAG — indexes documents, retrieves relevant chunks, builds bounded context, and generates grounded answers.
  • RAGConfig — controls top_k, score threshold, context size, and optional source display.
  • Reranking and verified citations — injects a custom reranker, returns source provenance, and controls insufficient-context responses.
  • Observability and evaluation — optional sanitized events and retrieval evaluation reports.
  • RAG.search() — returns retrieved chunks, metadata, and similarity scores without an LLM call.
  • RAG.ask() — retrieves context and generates an answer with the configured chat provider.

Loaders

  • TextLoader — loads one UTF-8 .txt file and keeps its source metadata.
  • DirectoryLoader — recursively loads UTF-8 .txt files from a directory; file_type="text" is required.
  • LoadedDocument — holds text and metadata before chunking and indexing.
  • FolderMetadataFactory — derives deterministic metadata from directory names and file names.
  • CSVMetadataFactory — reads validated metadata from a portable CSV manifest keyed by source path.
  • LLMMetadataFactory — uses an injected chat provider to generate validated metadata from a bounded file sample.

Chunking

  • TextChunker — splits loaded text into overlapping, separator-aware character chunks and preserves metadata.

Vector stores

  • Hybrid retrieval — opt-in keyword + vector ranking with separate similarity and fusion scores.

  • InMemoryVectorStore — thread-safe, process-local exact cosine retrieval for development.

  • SQLiteVectorStore — persistent local exact cosine retrieval for small-to-medium indexes.
  • PgVectorStore — PostgreSQL persistence with exact or HNSW cosine retrieval, JSONB filters, full-text hybrid search, and safe schema mapping.
  • PgVectorSchema — maps required collection, document, metadata, and vector fields onto a compatible application schema.
  • Metadata filtering — search() and ask() filter scalar values or values contained in metadata lists before vector scoring.
  • SQLite storage capacity — practical index-size guidance and scaling limits.

Providers

  • OllamaEmbeddingProvider — local Ollama embeddings; embeddinggemma is the default model.
  • OllamaChatProvider — local Ollama chat; gemma3:4b is the default model.

Error handling

  • format_error — formats package errors with the relevant application traceback frame.
  • Package-specific errors — make loader, chunking, provider, vector-store, and empty-index failures explicit.

Reference

Current scope

PyAIStack currently supports UTF-8 text files, local Ollama models, in-memory retrieval, persistent SQLite retrieval, and PostgreSQL + pgvector storage. PDF, DOCX, Markdown, web loaders, additional distributed vector databases, tools, and agents are under development.