duocthu/docs/api-reference.md

HTTP API và decision reference

Loại chính: Reference
Backend local thường dùng: http://localhost:8079

System endpoints

Method	Path	Mục đích
GET	/health	process health
GET	/ready	runtime readiness
GET	/metrics	Prometheus metrics; có thể yêu cầu Bearer token

POST /v1/rag/query

Request:

Field	Kiểu	Ràng buộc
query	string	bắt buộc, 1–4000 ký tự
subject_scope	enum	human, non_human, unknown
intent	enum	fact_lookup, recommendation, unknown
conversation_id	string/null	tối đa 128 ký tự
response_mode	enum	ai (mặc định, trả lời tổng hợp có generation) hoặc monograph (duyệt chuyên luận thô, xem GET /v1/rag/sections + /section-text)

Response:

Field	Ý nghĩa
trace_id, correlation_id, otel_trace_id	các định danh quan sát
decision, reason	kết quả policy và mã nguyên nhân
answer, resolved_drug_id	nội dung và thuốc đã resolve
citations	provenance evidence
generated	có dùng generator hay không
quick_replies, blocks	cấu trúc UI/claim
answer_mode, answer_plan	metadata trình bày
candidate_assessments	đánh giá candidate
disclaimer	cảnh báo cố định từ backend

Citation có chunk_id, printed-page range, physical_page, block_id, bbox, source_crop, attachment, evidence_text, drug, section và source document.

GET /v1/rag/history

Feature-List #25. conversation_id bắt buộc (tối đa 128 ký tự) — không có auth trong hệ thống nên endpoint chỉ trả về đúng conversation được truyền vào, không có nghĩa "list toàn bộ"; rỗng/không truyền → trả items: []. Tối đa 50 dòng, mới nhất trước. Mỗi dòng là một truy vấn cũ (trace_id, query, decision, reason, resolved_drug_id, created_at) để UI cho người dùng bấm lại — không replay lại answer prose, vì answer không được lưu, chỉ lưu trace.

GET /v1/rag/sections?drug_id=...

Feature-List #4. Danh sách section thật có của một thuốc (không phải danh sách cố định — đo trên corpus dao động 7–19 section/thuốc), mỗi phần tử có section_key + section_title. Không LLM, đọc thẳng payload đã index; drug_id không resolve được trả sections: [], không phải 404.

GET /v1/rag/section-text?drug_id=...&section_key=...

Feature-List #23. Text verbatim của một section, dùng cho response_mode: "monograph" — không generation/entailment nên không cần validate. Trả parts[] theo đúng thứ tự sách gốc; mỗi phần có is_quarantined — true nghĩa là phần đó là bảng/công thức bị quarantine, text khi đó là câu mô tả của chunker ("bảng, trang N...") chứ không phải nội dung bảng, và UI không được hiển thị như một trích dẫn verbatim thật.

Endpoint khác

• GET /v1/rag/suggest?q=...: trả suggestions autocomplete.
• POST /v1/rag/feedback: nhận UUID trace_id, rating helpful hoặc not_helpful, comment tối đa 2000 ký tự và conversation_id tối đa 128 ký tự.

Browser gọi BFF /api/chat. BFF dùng API_GATEWAY_URL, fallback AI_SERVICE_URL, sau đó http://localhost:8000, và map snake_case backend sang shared TypeScript DTO.

Decision và reason

Decision	Hành vi
answerable	hiển thị answer đã kiểm chứng
clarify	hỏi thêm thông tin, dùng quick replies nếu có
verify_pdf	hiển thị nguồn và yêu cầu đối chiếu PDF
abstain	không phát hành answer chuyên môn

Nhóm reason	Ví dụ
resolve/input	drug_not_resolved, drug_resolution_ambiguous, missing_query_or_drug, missing_indication
scope/intent	recommendation_out_of_scope, out_of_scope_non_human, subject_scope_unknown, query_intent_unknown, out_of_scope
clarify	no_drug, missing_attribute, missing_population, missing_pediatric_age_or_weight, needs_more_info, ambiguous_condition
retrieval	query_embedding_unavailable, insufficient_retrieval_score, no_indication_match, no_interaction_evidence, parent_hydration_failed
provenance	missing_provenance, missing_printed_page_provenance
provider/budget	provider_unavailable, understanding_provider_unavailable, request_budget_exhausted, malformed_output
grounding	evidence_insufficient, ungrounded_number, invalid_citation, uncited_claim, unsupported_claim, unsupported_drug, incomplete_answer
circuit/relation	clarify_loop_exhausted, unsupported_reverse_relation
fallback	generation_unavailable

Reason code là contract giữa backend, BFF và metric. Không collapse provider hoặc grounding error thành “không có dữ liệu”.