ShieldPoint / Under the hood
How a question becomes a cited answer.
ShieldPoint was a sales knowledge assistant built around fictional insurance training documents. The text experience helped a new adviser study product differences and inspect where an answer came from.
The central design choice: retrieve relevant passages before asking a model to explain them, then keep the source visible.
Deployed MVP · Demo currently offlineThe path at a glance
The documents are prepared ahead of time. Each question then takes a shorter path from search to a checked response.
- 01 / PrepareSplit documentsKeep headings and source filenames with each passage.
- 02 / IndexMake passages searchableCreate embeddings and a keyword index.
- 03 / RetrieveFind evidenceRank passages with semantic and exact-term signals.
- 04 / ExplainAsk DeepSeekGive the model the question and retrieved context.
- 05 / CheckReturn a sourceApply answer guards and attach verified filenames.
Before anyone asks
ShieldPoint uses a small synthetic Markdown corpus. Preparing its retrieval index in advance keeps document processing out of the live question path.
- 01
Read and chunk
The build reads Markdown product guides and splits them at level-two headings. It skips very short sections, keeps the heading text, and stores up to 2,000 characters per chunk with its source filename.
Heading-based chunksFilename retained2,000-character cap - 02
Represent the text
Every chunk receives a 768-dimension embedding, a numerical representation used for meaning-based matching. The project uses nomic-embed-text through local Ollama during local development, or text-embedding-3-small through OpenRouter in the deployed setup.
- 03
Build the keyword index
A BM25 index records terms in the same chunks. This helps when a question uses exact product names, rider terms, or policy language that a semantic match might blur.
- 04
Save a versioned index
The build stores chunks, embeddings and keyword data together. On startup, ShieldPoint checks the index against the selected corpus, embedding model, dimensions and checksums before it serves questions.
When a question arrives
The live request searches the prepared index, decides whether there is enough evidence, and only then forms an answer.
- 05
Search both ways
The question is embedded and compared with each passage using cosine similarity. BM25 scores the question’s exact terms. The two signals are normalised and combined for ranking: 70% embedding similarity and 30% BM25.
- 06
Select the context
The app takes up to 10 top-ranked chunks. It also checks the top raw embedding similarity; if it falls below the configured confidence threshold, the assistant says it could not find a confident match instead of composing an answer.
Top 10 chunks0.35 similarity threshold - 07
Generate an explanation
For questions without a matching fast response, ShieldPoint sends the selected passages and question to DeepSeek V4 Flash through OpenRouter. Its instruction is to answer from those passages, preserve important policy wording, and say when the documents do not verify an answer.
- 08
Guard and cite
Before returning the result, the app screens for recommendation language, runs its configured grounding check, and accepts citation filenames only if they belong to chunks retrieved for that request. A cached answer can serve a repeated question after that answer has passed the checks.
Question
“What is the difference between a stand-alone critical illness policy and a rider?”
The question is matched against the fictional guides, not sent to the model alone.
What comes back
A plain-language explanation with the relevant source filenames, so the adviser can open the underlying material and check the distinction.
Example flow; no live query runs on this page.
The trust boundary
ShieldPoint was designed as study support. The source documents are fictional, and the assistant is not a product recommender or a tool for a live client decision.
Show where an answer came from
Sources are shown at the document filename level. The public demo’s default grounding check tests for overlap with retrieved evidence and validates citation membership; it is not a proof that every individual claim is correct.
Know when to stop
The assistant is instructed to abstain when the documents do not support an answer. It also rejects low-confidence retrieval matches and refuses personalised product recommendations.
The RAG flow above describes the text assistant. Earlier voice and coaching experiments were separate explorations; the demo is currently offline.