Build a business glossary retrieval assistant

A business glossary assistant should return the right definition for the requested context, identify its version and ask for clarification when the term is unsupported. Retrieving a similarly worded paragraph is not enough when two versions use different eligibility rules.

Start with a small, inspectable retrieval component before adding a language model or vector database. This tutorial uses exact terms and aliases over four original synthetic glossary records. It does not claim to implement semantic search.

Give each definition a usable contract

The glossary dataset records a document ID, canonical term, aliases, approval flag, effective start, exclusive effective end, metric ID and definition text.

The current completed-order definition includes unmatched customer records. Its historical predecessor excluded them. A third approved record defines the share of eligible orders with a refund in the supplied undated ledger. The fourth record is an explicitly untrusted instruction used for a separate prompt-injection exercise.

Approval is authored teaching metadata here. In a real glossary, control who can approve or edit definitions. An uploaded document must not become authoritative merely because its body says it is approved.

Retrieve by term and effective date

from glossary import retrieve

current = retrieve('  ORDER   AMOUNT  ','2026-01-31')
historical = retrieve('order amount','2025-12-31')
unknown = retrieve('revenue','2026-01-31')
assert current['status']=='found'
assert current['documents'][0]['document_id']=='completed-orders-v1'
assert historical['documents'][0]['document_id']=='completed-orders-v0'
assert unknown=={'status':'needs_clarification','matches':0,'documents':[]}
assert current['calculated_value'] is None
assert len(current['document_sha256'])==64
print({'current_definition':current['documents'][0]['document_id'],
       'historical_definition':historical['documents'][0]['document_id'],
       'unsupported_term_status':unknown['status']})

The function normalizes case and repeated whitespace, matches approved terms or aliases, and filters effective dates. Exactly one match is required. Zero or multiple matches return a clarification state instead of choosing an arbitrary record.

The date argument selects a definition version. It does not filter transaction rows or calculate a period total. Those operations remain the calculator's responsibility.

Handle ambiguous business language

The word “revenue” is intentionally not an alias in this glossary. It might refer to completed-order amount, recognized revenue or cash collection. The assistant should ask which measure the user intends or offer the supported definition with a clear qualification.

Adding “revenue” as an alias merely to increase retrieval hit rate would hide that ambiguity. Retrieval coverage is useful only when the returned definition preserves the intended meaning.

For a larger organization, include the business domain, owner, unit and applicable scope in the definition model. Two teams may legitimately use the same term differently. A context-aware lookup should narrow by those fields before presenting a single answer.

Check retrieval behavior before adding generation

The supplied tests cover current and historical selection, an unsupported term, rejection of an unapproved document and the absence of a calculated value in retrieval output. Add a conflicting active definition and require clarification rather than silently selecting the first row.

If you later add semantic retrieval, retain the same acceptance checks. Similarity scores do not replace approval, effective dates or metric identity. Evaluate whether the relevant definition appears, whether stale records are excluded and whether unsupported questions lead to appropriate clarification.

A language model can explain a selected definition in accessible language, but it should preserve its unit and exclusions. Review the generated explanation against the source rather than assuming retrieval guarantees faithful paraphrasing.

Preserve the source in the answer

A useful answer states the definition, document ID, effective context and any important limitation. For example, the current amount definition uses paise, includes unmatched customer orders and does not establish cash collection or profit.

Keep the retrieved record available for inspection. A document hash identifies the exact record used, while version and approval controls determine whether that record was appropriate.

Exercise: add an alias for “completed sales amount” in a temporary glossary copy. Then add a second active record with the same alias and explain why the assistant should stop returning a single definition until the conflict is resolved.

NeuraPath's Data Analytics with Generative AI course links retrieval with business-metric discipline. A useful glossary assistant helps analysts agree on the question before they calculate the answer.

Continue learning

This article is part of the Generative AI for verified analyst work sequence. Use the neighbouring tasks when you need the prerequisite or the next application.

• Review the prerequisite or neighbouring task in Use AI to propose data checks and verify them independently.
• Continue with Evaluate citations in an AI-generated analytical answer.