duocthu/docs-legacy/29-glossary.md

29 — Glossary

Domain (Vietnamese)

Term	Meaning
Dược thư Quốc gia Việt Nam 2018	The Vietnamese National Drug Formulary. The single source document.
chuyên luận	A monograph — one drug's entry. Part 2 has 684 of them.
chỉ định (chi_dinh)	Indications — what the drug is used to treat.
chống chỉ định (chong_chi_dinh)	Contraindications — absolutely must not be used.
thận trọng (than_trong)	Precautions — may be used, with vigilance/monitoring/dose adjustment. Distinct from contraindications, and the distinction is spelled out to the model because it was measured getting it wrong 9/9.
liều lượng và cách dùng (lieu_luong_va_cach_dung)	Dosage and administration.
tương tác thuốc (tuong_tac_thuoc)	Drug interactions.
tương kỵ (tuong_ky)	Incompatibility — what it cannot be mixed with.
tác dụng không mong muốn (tac_dung_khong_mong_muon)	Adverse drug reactions.
hướng dẫn xử trí ADR (huong_dan_xu_tri_adr)	How to manage an ADR.
quá liều và xử trí (qua_lieu_va_xu_tri)	Overdose and management.
dược lý và cơ chế tác dụng (duoc_ly_va_co_che_tac_dung)	Pharmacology and mechanism. The largest section, and the documented false-positive attractor for similarity search.
thời kỳ mang thai / cho con bú	Pregnancy / breastfeeding.
dạng thuốc và hàm lượng	Dosage forms and strengths.
độ ổn định và bảo quản	Stability and storage.
bằng chứng	"Evidence" — the label for the retrieved blocks in every prompt.

Project-specific

Term	Meaning
chunk_id	{drug_id}__{section_key}__{part_index}, or {drug_id}__{section_key}__block__{table_id}. The identifier that threads the whole system.
drug_id	Slugified canonical drug name, e.g. paracetamol_acetaminophen. 684 exist.
section_key	One of the 19 canonical monograph section slugs.
printed page	The folio printed in the book — what a clinician cites.
physical page	PyMuPDF's 0-indexed page in the PDF file. Add 1 for a #page= viewer fragment.
quarantine	A table or 2-D formula whose flattened text would be misleading. Lifted out of prose, never embedded as text, never restated by the model; surfaced as "check the source page".
block descriptor	The chunk that stands in for a quarantined block. Its text is built from metadata only — no cell value ever appears. 151 exist.
VERIFY_PDF	The retrieval decision when any evidence requires visual verification. Blocks generation.
manifest	The sidecar Qdrant point recording corpus sha, model id, dimensions and input kind. Checked at load time and at service startup.
QueryFrame	The structured reading of one user turn produced by the understanding LLM call. Intent only, never medical content.
turn_type	The frame's primary branch: one of 10 values that drives RagAgent._route.
candidate bounding	Restricting the drug ids the understanding LLM may choose from to a deterministically-derived shortlist, before the model runs (finding F-04).
grounding	The deterministic per-citation check that every number and citation traces to the specific block cited. Never a model call.
entailment	The second LLM pass confirming a claim's content is stated by the block it cites.
completeness repair	A regeneration triggered when the entailment judge reports a quote-validated omission.
section route	Deterministic payload-filtered retrieval of one whole section. The primary path.
similarity fallback	Dense/rerank retrieval when no section is named. Explicitly the fallback, not the default.
fail closed / fail open	Fail closed = refuse to answer (anything that could change what is stated). Fail open = degrade quality but still answer (rerank, sufficiency, traces, history).
RequestBudget	Per-turn wall-clock (40 s) and call-count (8) limit, checked between LLM calls.
clarify circuit breaker	Hard stop after four consecutive clarifying turns on one conversation.
F-01 … F-11	Finding numbers from the 2026-08-06 code review, referenced throughout the source comments.
coverage ledger	The per-span record of where every extracted span ended up.
residual ink	Ink on a rendered page that no extracted span accounts for. The verification instrument that needs no ground truth.
gate	A named acceptance check with an explicit numeric target, printed by cli chunk-ready.
back index	The book's own back-of-book index, used as ground truth for monograph recall/precision.

Technical

Term	Meaning
RAG	Retrieval-augmented generation.
BFF	Backend-for-frontend — the Next.js app/api/* route handlers.
bi-encoder / cross-encoder	Embedding similarity vs. joint (query, document) scoring. Cohere rerank-v3.5 is the cross-encoder here.
RRF	Reciprocal-rank fusion. Implemented in rag/fusion.py; not used at runtime.
BM25	A lexical ranking function. Not used here — search_lexical counts distinct matched tokens with no TF/IDF.
hit@1	Fraction of queries whose top result is correct. Measured 0.544 overall / 0.05 on chong_chi_dinh for the similarity route (2026-08-04) — the measurement the section route exists because of.
payload filter	Qdrant's metadata filter, used without a vector for the section route.
scroll vs search	scroll pages through every match; search/query_points returns top-k. The section route must use scroll so a long section is never truncated.
uuid5 point id	Derived point id, so re-loading a corpus overwrites rather than duplicates.
OTLP	OpenTelemetry Protocol. Traces go OTLP/HTTP → collector → OTLP/gRPC → Tempo.
correlation id	Client-or-server-generated request id, regex-validated, stored on the trace and echoed in headers.
traceparent	W3C trace-context header, forwarded by the BFF and extracted by the FastAPI middleware.
fail-open trace	Trace persistence failure does not fail the request; it increments duocthu_trace_write_failed_total and substitutes a local UUID.
Converse API	Bedrock's unified model-invocation operation. It has no server-side response schema, which is why the JSON envelope is asked for in the prompt and isolated in the adapter.
ADR	Architecture decision record — docs/adr/.
GitOps	Cluster state driven by Git, via ArgoCD. Written but unapplied here.

Reason codes

The values of RagQueryResponse.reason, each mapped to a Vietnamese message in apps/web/app/api/chat/route.ts:

Code	Meaning
grounded_evidence_available	Answerable
visual_verification_required	Quarantined content; check the source page
out_of_scope	Non-human subject, or outside the Part-2 monographs
drug_not_in_formulary	A named drug is not in the catalog
no_drug, no_condition, no_indication	Nothing to look up yet
missing_population, missing_pediatric_age_or_weight, missing_attribute	Required dosing/attribute fields
needs_more_info	A general clarifying question
ambiguous_condition	The condition's subtype changes the answer
unsupported_reverse_relation	"Which drug causes/contraindicates X"
clarify_loop_exhausted	Circuit breaker tripped
understanding_provider_unavailable, understanding_malformed_output	The understanding call failed
provider_unavailable, malformed_output, request_budget_exhausted	Generation availability failures
evidence_insufficient	The model judged the evidence insufficient, twice
ungrounded_number, invalid_citation, uncited_claim	Deterministic grounding rejections
unsupported_claim, incomplete_answer	Entailment rejections
unsupported_drug	A generated candidate outside the allowed set
missing_provenance, missing_printed_page_provenance, parent_hydration_failed	Provenance failures
insufficient_retrieval_score, no_indication_match, query_embedding_unavailable	Retrieval failures
no_interaction_evidence	No interaction section content — explicitly not "safe"
generation_unavailable	Fallback when no specific code was set
upstream_error, upstream_unreachable	Synthesised by the web BFF, never by ai-service