feat: extract Embedder and VectorStore interfaces, add mock-based tests

Phase 2 test infrastructure: extract interfaces to decouple business
logic from external services, enabling fast CI tests without live
Qdrant or Ollama.

- Add Embedder interface (embedder.go) satisfied by OllamaClient
- Add VectorStore interface (vectorstore.go) satisfied by QdrantClient
- Update Ingest, IngestFile, Query to accept interfaces
- Add QueryWith, QueryContextWith, IngestDirWith, IngestFileWith helpers
- Add mockEmbedder and mockVectorStore in mock_test.go
- Add 69 new mock-based tests (ingest: 23, query: 12, helpers: 16)
- Coverage: 38.8% -> 69.0% (135 leaf-level tests total)

Co-Authored-By: Charon <developers@lethean.io>

2026-02-20 00:15:54 +00:00

1.8 KiB

Raw Blame History

CLAUDE.md

What This Is

Retrieval-Augmented Generation with vector search. Module: forge.lthn.ai/core/go-rag

Provides document chunking, embedding via Ollama, vector storage/search via Qdrant, and formatted context retrieval for AI prompts.

Commands

go test ./...                    # Run all tests
go test -v -run TestChunk        # Single test

Architecture

File	Purpose
`chunk.go`	Document chunking — splits markdown/text into semantic chunks
`embedder.go`	`Embedder` interface — abstraction for embedding providers
`vectorstore.go`	`VectorStore` interface — abstraction for vector storage backends
`ingest.go`	Ingestion pipeline — reads files, chunks, embeds, stores (accepts interfaces)
`query.go`	Query interface — search vectors, format results as text/JSON/XML (accepts interfaces)
`qdrant.go`	Qdrant vector DB client — implements `VectorStore`
`ollama.go`	Ollama embedding client — implements `Embedder`
`helpers.go`	Convenience wrappers — `*With` variants accept interfaces, defaults construct live clients

Dependencies

forge.lthn.ai/core/go — Logging (pkg/log)
github.com/ollama/ollama — Embedding API client
github.com/qdrant/go-client — Vector DB gRPC client
github.com/stretchr/testify — Tests

Key API

// Ingest documents
rag.IngestFile(ctx, cfg, "/path/to/doc.md")
rag.Ingest(ctx, cfg, reader, "source-name")

// Query for relevant context
results, err := rag.Query(ctx, cfg, "search query")
context := rag.FormatResults(results, "text") // or "json", "xml"

Coding Standards

UK English
Tests: testify assert/require
Conventional commits
Co-Author: Co-Authored-By: Virgil <virgil@lethean.io>
Licence: EUPL-1.2

1.8 KiB Raw Blame History