Fix migration workflow: upload as artifact instead of scp to practice EC2
This commit is contained in:
@@ -0,0 +1,102 @@
|
||||
# 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 |
|
||||
Reference in New Issue
Block a user