Knowledge Assistant

This is a RAG chatbot (Retrieval-Augmented Generation): it only answers from real technical documentation — it doesn't make things up. It finds the most relevant passages in the docs — the "retrieval" step — and uses them to generate an answer. If the answer isn't in the docs, it says so instead of guessing.

• Heading-based (structural) chunkingThe corpus is Markdown docs already split into semantically coherent sections, so chunks are cut on headings rather than fixed length with overlap: no length heuristic, no LLM call to decide the splits. Accepted trade-off: highly variable chunk size. Parsing is fence-aware — a # inside a code block is never mistaken for a heading.
• Hybrid retrieval (vector + full-text, RRF)Cosine similarity on pgvector fused with Postgres full-text search via Reciprocal Rank Fusion, in SQL, one round-trip. Vector similarity alone misses exact term and identifier matches: the query "Idempotency" isn't in the top 100 vector results, yet ranks second with hybrid. Top-k = 5, set in one place.
• Strict groundingThe system prompt (English, XML-tag structure) constrains the model to the retrieved chunks only, requires source citation, and forces an explicit refusal when the answer isn't there. A prompt is not a hard guarantee, so it's hardened at several levels against prompt injection and attempts to leak the instructions.
• Rate limiting (sliding window)Redis on Upstash, 10 requests / 10 minutes per IP. Sliding window rather than fixed window to avoid the double-traffic spike at the boundary between two windows; not a token bucket, since there's no legitimate burst to allow here — just a cost ceiling on a public endpoint.
• Input validation (Zod)Every request goes through a Zod schema before retrieval and generation: role, per-message length (4,000 chars), message count (40), and total sum (12,000 chars). That last bound closes the worst case of the first two — 4,000 × 40 = 160,000 chars from a client calling the endpoint directly.