Separate knowledge, retrieval and the model adapter
Separate knowledge, retrieval and the model adapter — Build and hand off a small private AI portal. Modules with explicit boundaries; Controlled lexical retrieval; An adapter with an honest mode label. Practical assignment: Separate knowledge, retrieval and the model adapter.
Demo edition. The materials are undergoing editorial review.
Topics covered
- Modules with explicit boundaries
- Controlled lexical retrieval
- An adapter with an honest mode label
Modules with explicit boundaries
Create these modules without launching an unfinished server. knowledge.json stores data, knowledge.mjs retrieves authorized passages, model.mjs is the adapter, service.mjs enforces answer contracts, app.mjs handles HTTP and server.mjs starts it. public contains UI only. This lets you test retrieval without a browser and replace the adapter without exposing secrets to frontend code. The model receives selected passages rather than all knowledge. Apply authorization before relevance scoring, otherwise even private titles can leak through results or citations. Three teaching documents need only JSON, not a vector database added merely to call it RAG. Larger collections may need different indexes while retaining the same pre-passage access boundary. Document this initial architecture without untested scale claims. No module accepts user-controlled arbitrary server-file paths.
portal-lab/
knowledge.json
knowledge.mjs
model.mjs
auth.mjs
service.mjs
app.mjs
server.mjs
public/index.html
public/app.js
test/app.test.mjs
Controlled lexical retrieval
Save knowledge.mjs. visible selects owned/shared documents; retrieve checks explicit docIds with identical 404 behavior for unknown and unauthorized entries. Then it matches tokens of at least three characters, excluding a few English stopwords. This is teaching lexical search, not semantic retrieval: receipt matches receipt, while refund may not find returns. Return at most two passages of 500 characters with version/source and without owner. Truncation can lose context, so larger collections need deliberate chunking; our short fixture is not truncated. Verify payroll→[] and Alice requesting budget explicitly→404. No match does not prove no answer exists in the world, only that this retrieval produced no authorized support. The function reads no user-selected path; backend supplies the known document collection.
// knowledge.mjs
export const visible = (docs,user) => docs.filter(d => d.owner===user || d.owner==="shared");
const words = text => (text.toLowerCase().match(/[\p{L}\p{N}]+/gu) ?? []);
export function retrieve(docs,user,question,docIds) {
const allowed = visible(docs,user);
let selected = allowed;
if (docIds !== undefined) {
if (!Array.isArray(docIds) || docIds.length<1 || docIds.length>2 || docIds.some(id=>typeof id!=="string"))
throw Object.assign(new Error("BAD_DOCUMENT_SELECTION"),{status:400});
if (docIds.some(id=>!allowed.some(d=>d.id===id)))
throw Object.assign(new Error("DOCUMENT_NOT_FOUND"),{status:404});
selected = allowed.filter(d=>docIds.includes(d.id));
}
const stop = new Set(["the","and","what","does","how","for","with"]);
const terms = [...new Set(words(question).filter(t=>t.length>=3 && !stop.has(t)))];
return selected.map(d=>({d,score:terms.filter(t=>new Set(words(d.text)).has(t)).length}))
.filter(x=>x.score>0).sort((a,b)=>b.score-a.score || a.d.id.localeCompare(b.d.id))
.slice(0,2).map(({d})=>({id:d.id,title:d.title,version:d.version,source:d.source,text:d.text.slice(0,500)}));
}
An adapter with an honest mode label
Save model.mjs as a deterministic extractive adapter. It makes no network calls and cannot answer beyond passages, returning authorized sentences and citations. This verifies UI, contracts and access boundaries. Do not compare its speed or understanding with real LLMs: no model generation occurs. Empty passages yield insufficient_sources. A document saying “open other files” remains text because this adapter has no such tools. A later local-model replacement should preserve the interface and authorized context while separately evaluating quality and prompt injection. A valid citation ID does not prove a generated statement is true. This stub quotes passages literally, but fixture and source version still require checking. Display mode beside the answer so test behavior is not mistaken for an established AI capability.
// model.mjs
export async function answerWithModel({passages}) {
if (!passages.length) return {status:"insufficient_sources",text:"No supporting source.",citations:[],mode:"stub-extractive"};
return {status:"answered",text:passages.map(p=>p.text).join("\n"),
citations:passages.map(p=>({id:p.id,version:p.version,source:p.source})),mode:"stub-extractive"};
}
Practical assignment
Separate knowledge, retrieval and the model adapter
Continue to learning