
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`](https://github.com/constructive-io/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

```text
Document → Chunking → Embedding → pgvector Storage
                                        ↓
Query → Embedding → Similarity Search → Context Retrieval → LLM Response
```

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](https://www.npmjs.com/package/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](https://github.com/constructive-io/ollama-test-suite)** — Clone it, run the tests, explore the architecture

- **[pgpm on npm](https://www.npmjs.com/package/pgpm)** — The foundation for modular Postgres development

- **[Ollama](https://ollama.com/)** — Run LLMs locally with a simple API

AI infrastructure should be something you can understand, test, and trust.


A reference implementation for building Retrieval-Augmented Generation (RAG) pipelines using local LLMs, Postgres, and pgvector. Real embeddings, semantic search, and end-to-end tests you can trust—all in a pgpm workspace.

Trusted LLM RAG Pipeline: Ollama & Postgres