Most RAG demos on GitHub do the same thing: embed some chunks, cosine-similarity search, stuff the top-k into a prompt, done. I built one of those first too. Then I actually tried to use it on messy real-world docs and it fell apart in three specific ways. So I rebuilt it as an event-driven pipeline instead of a linear script, and that's what became Project Aether.
The three things that broke my first RAG attempt
1. Semantic cache that returned stale garbage. Caching LLM responses by exact query string is useless, nobody types the same question twice. I needed similarity-based caching (is this new query "close enough" to a cached one?), but that opens a nastier problem: what threshold counts as "close enough" without returning a wrong-but-plausible cached answer for a subtly different question? I ended up tuning this against a small eval set instead of guessing a cosine threshold and hoping.
2. Naive vector search missing exact-match terms. Pure dense embeddings are bad at exact keywords, part numbers, error codes, that kind of thing. Someone searches for a specific SKU and dense-only search returns five semantically-similar-but-wrong products. Fixed this with hybrid dense+sparse retrieval instead of dense-only.
