Reference build · Grounded AI & retrieval
A knowledge assistant that shows its evidence—or declines to answer.
A working bilingual RAG reference that retrieves from a reviewed corpus, returns inspectable citations, exposes its trace, and withholds unsupported answers.
- Proof type
- Reference build
- Audience
- Agencies and product teams evaluating grounded knowledge assistants
- Timeline
- Reference build reviewed in July 2026; no client engagement or production rollout is claimed.
- Last reviewed
01 / Buyer and problem
The system had one clear job—and explicit limits.
A fluent answer is not enough when the system is expected to explain policies, procedures, or product knowledge. The interface needs a verifiable support contract and a safe response when the available material does not cover the question.
Who this helps
The build is useful when an answer must remain connected to reviewed source material and uncertainty must be visible to the person using it.
Exact role
Designed and implemented as a repository-backed reference build, including the Astro interface, same-origin API contract, retrieval and answer service, safe error states, and automated tests.
Constraints
- Use only the reviewed project corpus as evidence; general model knowledge is not treated as a source.
- Return no more than two citations and expose the retrieval trace used to support or decline the answer.
- Reject unsafe citation URLs, contradictory support flags, malformed payloads, and incomplete citation contracts.
- Bound question length, conversation context, request time, and temporary request volume.
Scope
- Reviewed bilingual source corpus
- Lexical retrieval and bounded context
- Constrained answer selection
- Citation validation and safe URL handling
- Explicit abstention and failure states
- Source inspector and diagnostic trace
02 / Architecture
A visible path from input to controlled result.
- 01
Reviewed corpus
Bilingual project and service notes remain the source of record.
- 02
Retriever
Lexical matching returns a bounded set of candidate passages and records its diagnostic trace.
- 03
Constrained selector
The model selects support from allowed source IDs or abstains; it does not create a new source.
- 04
Grounding validator
Citation identity, URL safety, response flags, and source coverage are checked before release.
- 05
Inspectable interface
The answer, exact excerpt, source destination, and reason for abstention remain visible.
03 / Delivery process
The work, in the order it became verifiable.
- 01
Review the corpus
Only selected source material enters the knowledge set, with a title, section, URL, and bilingual text where available.
- 02
Retrieve bounded passages
The question is matched against the reviewed corpus and only the strongest limited set continues.
- 03
Constrain the answer
The selector may use the retrieved sources, but it cannot turn an unsupported claim into approved evidence.
- 04
Validate the contract
Server and interface checks require safe, allowed citations for a supported response and replace conflicts with a safe abstention.
- 05
Expose the trace
The interface keeps cited excerpts, match details, context use, and the abstention reason available for review.
04 / Decisions and tradeoffs
The useful part is why the boundary exists.
Fail closed when the support contract conflicts
A positive answer without a valid citation should not be presented as grounded.
- Tradeoff
- The system declines more often than an unconstrained general-purpose chatbot.
Expose diagnostic trace without treating it as certainty
Reviewers need to see what was retrieved and why the path ended in support or abstention.
- Tradeoff
- The interface has more operational detail than a minimal chat surface.
Carry only bounded verified conversation context
A short follow-up can resolve a supported prior topic without allowing unsupported history to become evidence.
- Tradeoff
- Long or ambiguous conversations may require the person to restate context.
05 / Evidence
What can be inspected—and what cannot be claimed.
- Source release
- Maximum 2 citations
The service contract limits citations and validates each returned source before the interface presents a supported answer.
- Retrieval context
- Maximum 3 matched sources
The reviewed knowledge source documents the bounded candidate set sent to the constrained selector.
- Failure behavior
- Explicit abstention
Out-of-scope questions, unsafe URLs, contradictory flags, and incomplete citation contracts are covered by repository tests.
- Commercial result
- Not claimed
This is a reference build, not a client deployment or evidence of support-cost, accuracy, or revenue improvement.
06 / Outcome and handoff
A working reference interface that makes supported answers, cited evidence, retrieval trace, abstention, and error recovery inspectable.
Services connected to this work
Technologies used
- Astro
- TypeScript
- Node.js
- OpenAI API
- Zod
- Playwright
- Retrieval-augmented generation
Evaluating a grounded assistant?
Start with the evidence boundary, not the chat box.
Bring one knowledge source, one high-value question, and one failure the system must handle safely.
Book a 20-minute fit call