We just shipped a reference implementation of a real RAG pipeline—local LLMs with Ollama, Postgres with pgvector, and end-to-end tests you can actually run in CI.
Designed like infrastructure. Tested like infrastructure. Because that's what it is.
Why We Built This
AI features deserve the same engineering rigor as everything else. Clear separation between database transactions and model calls. Composable components. Tests that exercise real systems.
ollama-test-suite is a complete RAG pipeline built on this foundation. Local LLMs. Real embeddings. Semantic search backed by Postgres and pgvector.
This is AI you can reason about.
What's Inside
Ollama Integration — A TypeScript client for interacting with Ollama's API. Generate embeddings with nomic-embed-text, run inference with mistral, and stream responses when you need them. Everything runs locally—full control, full transparency.
Vector Database with pgvector — Postgres schema using pgvector for storing and querying document embeddings. Documents are automatically chunked with configurable overlap, and similarity search uses cosine distance for semantic retrieval. Your vectors live where your data lives.
RAG Service — A complete RAGService class that orchestrates the entire pipeline: document ingestion, embedding generation, semantic search, and LLM-powered response generation. Clear separation between database transactions and model calls.
CI/CD Pipeline — GitHub Actions workflow that provisions pgvector-enabled Postgres and Ollama services, pulls the required models, and runs integration tests automatically. Tests you can actually trust.
The Architecture
The system uses a document chunking strategy where content is split into overlapping segments for better retrieval accuracy. Each chunk is embedded using Ollama's nomic-embed-text model (768 dimensions) and stored in Postgres with pgvector. Queries are embedded and matched against chunks using cosine similarity, with the most relevant context passed to the LLM for response generation.
Simple primitives. Composable systems. Each component does one thing well, and they snap together cleanly.
Why This Matters
Local LLMs Change Everything
When your AI runs locally, you own the behavior. Pinned model versions. Predictable costs. Data stays on your infrastructure. You can test deterministically because the model is exactly what you expect it to be.
This is AI infrastructure you can actually reason about.
Postgres as the Foundation
Postgres is the most expressive, most powerful, most under-leveraged platform in engineering. With pgvector, it becomes a first-class vector database too.
Your embeddings live alongside your relational data—same transactions, same backups, same tooling you already know. Just Postgres doing what Postgres does best.
End-to-End LLM Test Suite
The test suite exercises the full pipeline with real models and real databases. Real Postgres with pgvector extensions. Real Ollama with actual model weights.
When these tests pass in CI, you know the system works—because it's running the same infrastructure you'll deploy.
Built on pgpm
This project is structured as a pgpm workspace—our TypeScript-native SQL migration engine for modular Postgres development. The database schema is versioned, testable, and deployable with the same rigor as application code.
Pure SQL. No ORM. Composable modules. The database is a first-class citizen, not an afterthought.
Who This Is For
If you're building AI features on Postgres, this gives you a solid foundation:
- Teams integrating LLMs who want clear architecture patterns
- Developers building semantic search who need vector storage that scales
- Engineers who value testable, composable systems
Fork it, extend it, ship it. The architecture is designed to grow with your needs.
Get Started
Ready to build AI features you can trust?
-
ollama-test-suite on GitHub — Clone it, run the tests, explore the architecture
-
pgpm on npm — The foundation for modular Postgres development
-
Ollama — Run LLMs locally with a simple API
AI infrastructure should be something you can understand, test, and trust.