Develop v0.4.0

[ldaidone]

RAG pipeline, search filter DSL, embedder interface + HNSW ANN index

Summary

This PR adds the retrieval layer on top of the existing vector stores: a pure-Go HNSW approximate nearest neighbor index, a RAG pipeline with token-budget prompt assembly, a composable metadata filter DSL, and an embedder abstraction with an offline dummy implementation. It also ships a SQLite-backed store and updates docs/tooling.

What's new

🧠 pkg/ann — HNSW index (new)

• Pure-Go, CGo-free approximate nearest neighbor search (Malkov & Yashunin, 2016), cosine distance
• Configurable M, EfConstruction, EfSearch, seed-deterministic builds for reproducible tests/demos
• Recall@10 measured against exact brute force: 0.95–0.998 at n=2,000 / dim=64 depending on data distribution and ef
• Perf fix included: node norms are cached instead of recomputed per comparison → search ~2x faster, build ~2.4x faster, results bit-identical
• Regression floors in CI (recall_test.go) so a recall drop fails the build; benchmarks for build, search (ef=50/100/200) and brute-force baseline

📚 pkg/rag — Retrieval-Augmented Generation building blocks (new)

• Retriever: query → embedding → store search → scored text chunks, with per-call TopK and metadata filtering
• FormatContext with token-budget trimming and citation-friendly [n] numbering; BuildPrompt scaffolding
• End-to-end retrieve over 1k docs runs in ~172µs; prompt assembly is nanosecond-scale (benchmarks included)

🔌 pkg/embedder (new) — Embedder interface + deterministic offline Dummy (FNV-hash, unit-norm) so pipelines are testable without model downloads

🔍 pkg/embedx — Search config + Filter DSL (new) — Searcher interface, WithK/WithFilter options, composable filters (Eq/In/Exists/And/Or/Not)

📦 Storage

• New public pkg/store facade: single Store interface over all bundled backends
• New internal SQLite store (~300 LOC + tests) alongside memory/Badger

🛠️ Tooling & docs

• scripts/ascii-banner (portable, NO_COLOR-aware) + make install-banner
• README rewritten for v0.4.0 features; ROADMAP updated (v0.2/v0.3 done)

Notes for reviewers

• ⚠️ models/get-small.gtemodel adds a ~21MB binary asset to the repo — flagging in case we'd rather use Git LFS or a download script
• ANN results are approximate by design; see pkg/ann/recall_test.go for the accuracy envelope
• No breaking API changes to existing store/vector packages

Testing

• go vet ./... clean; full suite passes under -race (12 packages)
• New coverage: recall regression tests (ANN), RAG unit tests, filter DSL tests, SQLite store tests
• Benchmarks: go test -bench . ./pkg/ann ./pkg/rag

[codecov]

Codecov Report

❌ Patch coverage is 84.85857% with 91 lines in your changes missing coverage. Please review.

Files with missing lines	Patch %	Lines
internal/store/sqlite/sqlite.go	68.96%	24 Missing and 21 partials ⚠️
pkg/ann/ann.go	91.57%	9 Missing and 7 partials ⚠️
pkg/store/memory.go	80.82%	11 Missing and 3 partials ⚠️
pkg/rag/rag.go	92.20%	3 Missing and 3 partials ⚠️
pkg/store/badger.go	63.63%	2 Missing and 2 partials ⚠️
pkg/store/sqlite.go	63.63%	2 Missing and 2 partials ⚠️
pkg/embedder/embedder.go	94.73%	1 Missing and 1 partial ⚠️

📢 Thoughts on this report? Let us know!