PR - M10 — Knowledge Base (RAG)

[ByteStreams-AI]

feat(rag): implement rag knowledge base

Closes #13

Greptile Summary

This PR ships the complete M10 RAG Knowledge Base pipeline: two SECURITY DEFINER SQL RPCs (knowledge_replace_chunks, knowledge_lookup), three Edge Functions (knowledge_reindex, vapi_lookup_knowledge, knowledge_preview), shared chunking/embedding/threshold modules, the admin /settings/knowledge CRUD page, seed data, and 60 new tests. The implementation is well-structured, with per-candidate threshold filtering, a deterministic content-aware mock embedding for CI, and cross-tenant scoping enforced in SQL.

Confidence Score: 5/5

Safe to merge — all findings are P2 style/UX suggestions; no logic errors or security issues found

No P0 or P1 issues found. The single new inline comment is a UX polish suggestion (silent poll timeout). Previously-flagged P2s (silent empty list on query error, category_hint not forwarded to SQL, topSimilarity fallback category mismatch) don't affect correctness on the happy path. Tests are comprehensive and the security model is consistent with the established codebase pattern.

apps/admin/src/pages/settings/knowledge-page.tsx (poll timeout UX), supabase/functions/vapi_lookup_knowledge/index.ts (p_category forwarding, previously flagged)

Important Files Changed

Filename	Overview
apps/admin/src/pages/settings/knowledge-page.tsx	New admin Knowledge Base page — CRUD, fire-and-poll reindex, and Q&A preview; error handling is mostly solid but the 60-second polling cap exits silently when indexing is still in-progress
supabase/functions/knowledge_reindex/index.ts	JWT-gated reindex pipeline — chunks body, embeds via OpenAI (with mock fallback), atomically replaces chunks via RPC; error handling and auth checks are thorough
supabase/functions/vapi_lookup_knowledge/index.ts	RAG retrieval Edge Function — p_category is not forwarded to knowledge_lookup SQL even when category_hint is set (already flagged), so hinted-category chunks ranking outside the top-5 globally are invisible to the filter
packages/shared/src/voice/knowledge.ts	Per-category threshold policy and applyThresholds — solid per-candidate filtering; when categoryHint is set but no candidates match, topSimilarity falls back to the best score from a different category (already flagged)
packages/shared/src/voice/embedding.ts	OpenAI embeddings wrapper with deterministic sparse-activation mock — content-aware cosine signal for tests, OPENAI_MOCK_MODE=never production guard, correct L2-normalization
supabase/migrations/0012_m10_knowledge_rpcs.sql	Adds knowledge_replace_chunks (atomic delete+insert, flips status to ready) and knowledge_lookup (kNN cosine via pgvector, scoped to restaurant+active+ready); both correctly restricted to service_role
packages/shared/src/voice/chunk.ts	Paragraph-first / sentence-fallback chunker with overlap — approx token counting, clean boundary logic, well-tested
packages/shared/src/voice/tools.ts	Adds lookup_knowledge tool schema with clear verbatim-question instruction; gated on knowledge_base_enabled in selectTools, ordered correctly before end_call

Comments Outside Diff (3)

1. packages/shared/src/voice/knowledge.ts, line 1503-1517 (link)

   topSimilarity can report a non-hint-category score when hint filters to empty

   When categoryHint is set but no candidates in the kNN result match that category, filtered is empty and topSimilarity falls back to candidates[0]?.similarity — the best score from a different category. The debug panel then shows, for example, top_similarity=0.43, threshold=0.55 (dietary), making it look as if a dietary chunk nearly cleared the threshold when no dietary chunk was even in the top-K. A more accurate fallback would be 0 (or omitted) when the hinted-category result set is empty.

   const topSimilarity = filtered.length > 0
     ? filtered[0]!.similarity
     : (categoryHint ? 0 : (candidates[0]?.similarity ?? 0));

2. supabase/functions/vapi_lookup_knowledge/index.ts, line 2870-2875 (link)

   category_hint not pushed to SQL — hint-category chunks can be missed

   When args.category_hint is set, applyThresholds narrows the kNN result to only candidates in the hinted category. But the SQL knowledge_lookup is called without p_category, so it fetches the top RAW_FETCH_K (5) rows across all categories. If those 5 rows are dominated by non-hint categories, relevant chunks in the hinted category that rank below position 5 globally will never be seen by the filter. The SQL function already accepts p_category precisely for this case — passing it here guarantees the top-K is drawn from the right category pool.

   const { data: rawData, error: rawErr } = await client.rpc('knowledge_lookup', {
     p_restaurant_id: state.restaurant_id,
     p_query_embedding: embeddingStr,
     p_category: args.category_hint ?? undefined,
     p_limit: RAW_FETCH_K,
   });

   The same pattern applies to knowledge_preview/index.ts.

3. supabase/seed.sql, line 3143-3150 (link)

   Catering source seeded as 'pending' but comment says 'ready'

   The block comment directly above these inserts states "Sources are seeded with index_status='ready'", but the catering source is seeded as 'pending'. All other Sui's Sushi sources are 'ready', so knowledge_base_enabled is unaffected in practice — but the inconsistency between the comment and the actual value could confuse future maintainers who rely on the comment to understand the seed state.

_{Reviews (2): Last reviewed commit: "fix(rag): sparse mock embedding so CI in..." | Re-trigger Greptile}

[greptile-apps]

Supabase query failures in fetchRows produce a silent empty list

Neither the knowledge_sources select nor the knowledge_chunks select checks for an error return value. If either query fails (network blip, RLS violation), sources and chunks are null, setRows([]) is called, and the UI renders an empty "No knowledge sources yet" state with no indication of the problem. Setting an error state on failure here would give operators a clear signal rather than a misleading empty view.

[greptile-apps]

Want your agent to iterate on Greptile's feedback? Try greploops.