Knowledge base & RAG

A knowledge base is a collection of text chunks the agent can pull from during a call. Voxy supports three item types — URLs, files, and raw text — ingested into the same chunked, embedded format.

Item types

• URL — we fetch the page, strip boilerplate, and chunk the readable body.
• File — PDF, DOCX, TXT, MD. Extracted with pdfkit/mammoth/raw read.
• Text — paste content directly into the Monaco editor at /workspace/knowledge-base.

Ingest pipeline

1. Extract — clean text from the source.
2. Chunk — ~700-char sentences with 100-char overlap so context bleeds across boundaries.
3. Embed — each chunk runs through Voxy AI's embedding model at concurrency 4 to stay polite with the quota.
4. Store — chunks land in kb_chunks with FULLTEXT index on content and the embedding as JSON.

Hybrid retrieval at call time

When the voice-bridge starts a session, it seeds the agent prompt with the top-K chunks for the agent's opening greeting. During the call, tool calls (or mid-call lookups) hit the same retrieval path with the user's utterance.

The ranker combines two signals 50/50 after normalising:

• BM25 — MySQL MATCH ... AGAINST on FULLTEXT.
• Cosine — embed the query, score against each candidate's embedding.

Why hybrid: BM25 alone fails on synonyms (“billing” vs “invoice”); cosine alone fails on rare proper nouns (“Dairvi”, “DG Khan”).

Re-ingest

URLs and files can be re-ingested in place — the chunks are replaced atomically. Useful when your help-centre page changes.