hermes-erm/polyvault-rag

Purpose and entry points

Poly-vault is a multimodal retrieval-augmented generation (RAG) service: it ingests supported files, converts and semantically chunks content, indexes embeddings, then answers questions only from retrieved context. The FastAPI application starts from src/app/main.py; HTTP routes live in src/app/api.py; its minimal browser client is src/app/static/index.html.

API and application boundary

src/app/main.py creates the FastAPI app, mounts static content, and registers API routing. src/app/api.py exposes upload, document listing/deletion, vector reset, retrieval, and answer-generation endpoints. src/dependencies.py is the composition boundary that creates/reuses pipeline services and database sessions; model selection is centralized here.

Ingestion pipeline

Uploads enter through src/app/api.py and are handled asynchronously by src/rag_system/document_processor.py. The processor persists source/intermediate files under pipeline/staging/ and records lifecycle state—staging, embedding, indexed, or failed—through src/rag_system/model.py. It uses Docling to normalize PDF, DOCX, images, CSV, XLSX, and Markdown into Markdown; BlingFire sentence segmentation and semantic grouping produce chunks.

Persistence and indexing

src/rag_system/model.py owns the SQLAlchemy/SQLite document-pipeline metadata model and repository operations. src/rag_system/retriever.py owns ChromaDB collection operations: chunk embedding, metadata association, similarity lookup, per-document vector deletion, and full reset. The SQLite row and Chroma vectors must remain coordinated: document deletion and reset remove both metadata and embeddings.

Retrieval and answer generation

For /query/search, src/app/api.py delegates query embedding and candidate retrieval to src/rag_system/retriever.py. Retrieved chunks are reranked by Cohere before being passed to src/rag_system/generator.py. The generator calls Gemini with a RAG prompt that constrains answers to supplied context. /query/retrieve exposes the retrieval stage without answer generation.

Runtime dependencies and external services

The Python/FastAPI runtime packages services in Dockerfile and dependencies in requirements.txt. Core local persistence is SQLite plus persistent ChromaDB storage; staging/processed pipeline directories are pipeline/staging/ and pipeline/processed/. External model/service dependencies are Docling, BlingFire, MiniLM embeddings, Cohere reranking, and Gemini generation; Cohere and Gemini credentials come from environment variables.

Deployment control flow

.github/workflows/aws-ecs-deploy.yml runs on pushes to main, builds the Dockerfile image, pushes it to Amazon ECR, renders an ECS task definition, and deploys it to ECS. The deployed task is reached through an AWS Network Load Balancer and stable Elastic IP; deployment routing depends on target health checks. The service currently has no API authentication, so network exposure is the primary protection boundary.