{"id":39761182,"url":"https://github.com/constructive-io/ollama-test-suite","last_synced_at":"2026-01-18T11:38:08.804Z","repository":{"id":330685936,"uuid":"1123502235","full_name":"constructive-io/ollama-test-suite","owner":"constructive-io","description":null,"archived":false,"fork":false,"pushed_at":"2025-12-27T09:12:46.000Z","size":124,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-12-28T23:45:06.707Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/constructive-io.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-12-27T02:33:44.000Z","updated_at":"2025-12-27T09:12:51.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/constructive-io/ollama-test-suite","commit_stats":null,"previous_names":["constructive-io/ollama-test-suite"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/constructive-io/ollama-test-suite","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/constructive-io%2Follama-test-suite","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/constructive-io%2Follama-test-suite/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/constructive-io%2Follama-test-suite/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/constructive-io%2Follama-test-suite/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/constructive-io","download_url":"https://codeload.github.com/constructive-io/ollama-test-suite/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/constructive-io%2Follama-test-suite/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28535169,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-01-18T10:13:46.436Z","status":"ssl_error","status_checked_at":"2026-01-18T10:13:11.045Z","response_time":98,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.6:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2026-01-18T11:38:08.055Z","updated_at":"2026-01-18T11:38:08.789Z","avatar_url":"https://github.com/constructive-io.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# ollama-test-suite\n\n\u003cp align=\"center\" width=\"100%\"\u003e\n  \u003cimg height=\"250\" src=\"https://raw.githubusercontent.com/constructive-io/.github/refs/heads/main/assets/outline-logo.svg\" /\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\" width=\"100%\"\u003e\n  \u003ca href=\"https://github.com/constructive-io/ollama-test-suite/actions/workflows/ci.yaml\"\u003e\n    \u003cimg height=\"20\" src=\"https://github.com/constructive-io/ollama-test-suite/actions/workflows/ci.yaml/badge.svg\" /\u003e\n  \u003c/a\u003e\n\u003c/p\u003e\n\nA reference implementation demonstrating Ollama integration with PostgreSQL and pgvector for building Retrieval-Augmented Generation (RAG) pipelines. This project showcases how to combine local LLMs with vector databases for semantic search and AI-powered document retrieval.\n\n```mermaid\nflowchart LR\n    subgraph Ingestion\n        A[Document] --\u003e B[Chunking]\n        B --\u003e C[Ollama Embedding]\n        C --\u003e D[(pgvector)]\n    end\n    \n    subgraph Query\n        E[User Question] --\u003e F[Ollama Embedding]\n        F --\u003e G[Similarity Search]\n        D --\u003e G\n        G --\u003e H[Context Retrieval]\n        H --\u003e I[Ollama LLM]\n        I --\u003e J[Response]\n    end\n```\n\n## What's Included\n\nThis test suite demonstrates a complete RAG pipeline with the following components:\n\n**Ollama Integration**: A TypeScript client (`OllamaClient`) for interacting with Ollama's API, supporting embedding generation with `nomic-embed-text` and text generation with `mistral`. Includes both synchronous and streaming response modes.\n\n**Vector Database with pgvector**: PostgreSQL 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.\n\n**RAG Service**: A complete `RAGService` class that orchestrates document ingestion, embedding generation, semantic search, and LLM-powered response generation with chat history tracking.\n\n**CI/CD Pipeline**: GitHub Actions workflow that provisions pgvector-enabled PostgreSQL and Ollama services, pulls required models, and runs integration tests automatically.\n\n## Architecture\n\nThe 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 PostgreSQL with pgvector. Queries are embedded and matched against chunks using cosine similarity, with the most relevant context passed to the LLM for response generation.\n\n```\nDocument → Chunking → Embedding → pgvector Storage\n                                        ↓\nQuery → Embedding → Similarity Search → Context Retrieval → LLM Response\n```\n\n## Getting Started\n\n### Prerequisites\n\n- Node.js 20+\n- pnpm\n- Docker\n- PostgreSQL client tools (`psql`)\n- pgpm (`npm install -g pgpm`)\n- Ollama (for local development)\n\n### Quick Start\n\n```sh\n# Install dependencies\npnpm install\n\n# Start PostgreSQL with pgvector (requires Docker)\npgpm docker start\n\n# Load environment variables\neval \"$(pgpm env)\"\n\n# Start Ollama and pull required models\nollama serve \u0026\nollama pull nomic-embed-text\nollama pull mistral\n\n# Run tests\ncd packages/ollama\npnpm test\n```\n\n### Environment Variables\n\n| Variable | Description | Default |\n|----------|-------------|---------|\n| `OLLAMA_HOST` | Ollama API endpoint | `http://localhost:11434` |\n| `PGHOST` | PostgreSQL host | `localhost` |\n| `PGPORT` | PostgreSQL port | `5432` |\n| `PGUSER` | PostgreSQL user | `postgres` |\n| `PGPASSWORD` | PostgreSQL password | - |\n\n## Package Structure\n\n```\npackages/ollama/\n├── src/\n│   ├── utils/ollama.ts      # Ollama API client\n│   └── services/rag.service.ts  # RAG orchestration service\n├── deploy/\n│   └── migration.sql        # pgvector schema (documents, chunks, similarity search)\n└── __tests__/\n    ├── pgvector.test.ts     # Vector search integration tests\n    └── rag.test.ts          # Full RAG pipeline tests with performance logging\n```\n\n## Usage Example\n\n```typescript\nimport { Pool } from 'pg';\nimport { RAGService } from 'ollama';\n\nconst pool = new Pool();\nconst rag = new RAGService(pool);\n\n// Add a document (automatically chunks and embeds)\nconst docId = await rag.addDocument(\n  'My Document Title',\n  'Long document content...',\n  { source: 'manual' }\n);\n\n// Query with RAG\nconst response = await rag.query(\n  'What does the document say about X?',\n  'session-123'\n);\n```\n\n## Note on Embeddings\n\nEmbeddings are generated at the application layer rather than via database triggers. This design choice avoids coupling database transactions to external HTTP calls, which can cause performance issues and transaction failures. For production use cases requiring automatic embedding updates, consider implementing an async job queue that processes new/updated documents outside the transaction boundary.\n\n## Credits\n\n**🛠 Built by the [Constructive](https://constructive.io) team — creators of modular Postgres tooling for secure, composable backends. If you like our work, contribute on [GitHub](https://github.com/constructive-io).**\n\n## Disclaimer\n\nAS DESCRIBED IN THE LICENSES, THE SOFTWARE IS PROVIDED \"AS IS\", AT YOUR OWN RISK, AND WITHOUT WARRANTIES OF ANY KIND.\n\nNo developer or entity involved in creating this software will be liable for any claims or damages whatsoever associated with your use, inability to use, or your interaction with other users of the code, including any direct, indirect, incidental, special, exemplary, punitive or consequential damages, or loss of profits, cryptocurrencies, tokens, or anything else of value.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fconstructive-io%2Follama-test-suite","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fconstructive-io%2Follama-test-suite","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fconstructive-io%2Follama-test-suite/lists"}