Published knowledge retrieval and grounded answers
This is a PostgreSQL retrieval-augmented generation flow using the existing Google-hosted Gemma models. It adds no embedding API, vector service or external search daemon. Model generation still uses the existing Google quota, and screenshot grounding can require an additional vision request.
Runtime flow
Section titled “Runtime flow”- Existing sender authorization, scope guards and direct ticket actions run first.
- Search only approved, unexpired knowledge. Exact saved questions retain the direct-answer path with a source and no model call.
- For other questions, normalize common Indonesian/English wording, remove filler words, expand curated synonyms and consider recent user turns for follow-ups. A clear new query is not expanded with an unrelated earlier issue. Unknown application names are not replaced with the previous app automatically.
- PostgreSQL retrieves up to80 candidates using weighted full-text matching and trigram similarity. Generated search columns and GIN indexes update automatically when questions, answers or aliases change. The query uses OR expansion rather than requiring every word of a full conversational sentence.
- Rerank by matches in titles/aliases, answer text, primary query coverage and lighter contextual overlap. Reject weak generic app-only matches and conflicting explicit three-digit error codes. Relevance comes before recency. Keep at most5 complete articles within a14000-character evidence budget; do not cut an article mid-answer. Labels strong/partial are heuristics, not calibrated probabilities.
- Give Gemma structured JSON data: WIB timestamp, search/context terms, a bounded catalog of published topics, and the actual matched articles with IDs, content, source, category, update/expiry timestamps, match coverage and missing terms.
- Fixed grounding instructions distinguish catalog metadata from factual evidence. The model checks whether an article applies to the requested app/error/time/group, prioritizes relevant official content, and chooses an answer basis: knowledge, general or insufficient. Missing P3MDI facts remain an in-scope question; missing information is not a reason to label the user unrelated.
- API structured JSON output constrains the response shape. The backend validates action enums and numeric evidence IDs, then appends sources only for declared articles actually retrieved. Citations are checked again against publication, expiry and update timestamp. Unknown article IDs or invented links are not shown as verified sources. Source attribution is not a complete semantic fact checker; the model can still make mistakes and content curation/evaluation remains important.
The topic catalog contains at most30 recent published titles with an accurate eligible-article count and truncation flag. It helps answer what information is available; titles are explicitly not evidence of an article’s facts. The model receives no private member profiles, staff notes, draft articles or expired entries through retrieval.
The typed answer contract adds answer_basis and knowledge_ids alongside the existing scope/action/answer. A knowledge answer needs nonempty, valid retrieved IDs. General advice, greetings, refusals, ticket actions and insufficient-information replies have no cited IDs. Ticket permissions and consent remain in the backend, and KB text cannot authorize actions. Prompt injection inside articles/images is treated as data.
Screenshots and provider errors
Section titled “Screenshots and provider errors”For a screenshot when published knowledge exists, a small vision extraction call identifies visible application/error keywords. It does not execute image instructions or copy personal fields. Common credentials, emails, long numeric identifiers, reset links and token-like strings are removed from extraction output. The resulting keywords plus caption/relevant history drive the same retrieval engine. The final model call sees the normalized screenshot and selected evidence. Images and extraction data are not newly archived by retrieval.
If no knowledge is published, skip the extra extraction call and keep ordinary screenshot help. If extraction is unavailable, caption/context search still works. If generation is unavailable, a strongly matched article can be returned as a clearly labeled related guide with its source; weak evidence does not become an asserted answer. Google429 responses keep the existing shared cooldown. A Google500/502/503/504 can be retried once with the remaining request timeout and another quota permission check; network timeouts and malformed content are not endlessly retried. WhatsApp sends are not retried.
Google returned intermittent INTERNAL500 responses during live testing. Later checks produced correct text and image answers. This change improves handling of that dependency but cannot guarantee provider availability.
Knowledge authoring and testing
Section titled “Knowledge authoring and testing”Open Pengetahuan. Use a specific title, identify the application/audience, state the answer or steps and important conditions, include the official source, and set category/expiry appropriately. Put alternate questions, abbreviations and common wording into Pertanyaan alternatif & kata kunci, for example:
- Title: Cara mereset kata sandi App Hub
- Aliases: forgot password; lupa password; reset akun; tidak ingat sandi
- Answer: the actual approved steps and conditions, not instructions telling the bot to ignore rules.
- Source: the responsible division or official document/URL.
Publishing means the information may be shared with any admitted WhatsApp requester. Do not publish passwords, OTPs, personal contacts, staff-only notes or signed reset URLs. Common sensitive patterns are sanitized before model use; public URLs remain intact except recognized credential-bearing query parameters/links. Sanitization is not a replacement for reviewing published content.
Uji pencarian pengetahuan shows eligible-article count, matched articles, strong/partial match labels, matched/missing terms, content and source. Supply a previous question to test a follow-up. This tool does not call Google or send messages. Search in the knowledge table also includes aliases.
In Konfigurasi AI → Uji draf, opt into Gunakan pengetahuan terbit pada uji ini to inspect a grounded model reply with actual public KB references. It uses no real conversation history or case FAQ. The test is still a dry run: proposed ticket actions are not executed and WhatsApp is not called. Default tests without that opt-in retain their earlier behavior. Configuration defaults and the full default prompt example remain available; protected grounding instructions also apply to previously saved prompt revisions without overwriting custom editable sections.
Evaluation, limits and rollback
Section titled “Evaluation, limits and rollback”The deterministic regression suite includes a15-query synthetic benchmark for Indonesian/English paraphrases and typos, plus contextual follow-ups, clear topic changes, exact-match precedence, differing error codes, drafts/expiry, citation forgery/revocation/content changes, privacy, screenshot extraction/grounding, provider outage fallback and authenticated curator/testing tools. These synthetic results do not establish real-world accuracy on an unknown corpus. The production KB had only one eligible article at inspection; adding well-written public knowledge is essential.
Live generic Google checks used a separate synthetic database: paraphrased reset help and follow-ups selected the reset article; an unsupported P3MDI fee selected insufficient; catalog questions listed available topics; a synthetic403 screenshot extracted the visible error and selected the matching permissions article. No production articles, tickets or WhatsApp messages were created by those checks. Curator browser checks likewise use synthetic data and a stubbed model for queued test UI; actual Google behavior is validated separately.
This is lexical/synonym/fuzzy retrieval, not general semantic embedding search. Unseen paraphrases and ambiguous queries can still miss articles or need clarification. The bounded candidate/catalog/evidence sizes keep resource use predictable. Larger or more diverse document collections may warrant embeddings, stronger reranking and a representative labeled evaluation set later. Long documents should currently be split into focused curated entries; there is no automatic PDF ingestion.
Schema migration adds pg_trgm, aliases, generated search columns/GIN indexes, and the optional KB-test flag in this project’s database. Existing knowledge and AI settings are preserved. A database backup and source copy at server code-backups/before-retrieval/app precede deployment. Recreate only API, worker and dashboard; leave WAHA, PostgreSQL and the shared proxy running. Rollback source without dropping new columns/indexes or deleting knowledge data.
Draf dari kasus dan uji tersimpan
Section titled “Draf dari kasus dan uji tersimpan”Pada kasus yang sudah ditutup atau memiliki tiket selesai, pilih Buat draf FAQ. Tulis pertanyaan umum dan jawaban yang sudah diverifikasi. Kasus asal tetap terlihat bagi admin selama arsipnya tersedia. Percakapan tidak disalin ke FAQ. Periksa nama, kontak, dan detail pribadi sebelum menerbitkan.
Gunakan PDF publik dan Halaman PDF untuk menautkan acuan. Kutipan bot menyertakan nama file dan halaman. FAQ dengan tautan PDF hanya tersedia untuk bot selama PDF itu masih terbit, publik, dan berlaku. Jika sumber diganti, sunting FAQ untuk menautkan versi baru.
Di Pengetahuan → Uji tersimpan, simpan pertanyaan dengan sumber yang diharapkan. Pilih halaman PDF, FAQ tertentu, atau tidak ada kandidat. Jalankan uji tersimpan membandingkan hasil pencarian dengan harapan tersebut. Pilihan Draf untuk simulasi menambahkan satu draf FAQ ke pencarian privat admin. Mode ini tidak menerbitkan draf.
Simulasikan balasan memakai konfigurasi AI aktif dan kuota model untuk menampilkan balasan di dashboard. Petugas menilai apakah jawaban mengikuti sumber dan meminta klarifikasi saat bukti kurang. Simulasi tidak menjalankan usulan tindakan atau mengirim pesan WhatsApp.
Unified Knowledge Base
Section titled “Unified Knowledge Base”The dashboard groups PDFs and manual articles under Knowledge Base. Koleksi lists source PDFs and manual articles. PDF sections remain available inside each document. Perlu Ditinjau contains drafts, expired sources, extraction issues, overlap candidates, and recorded source decisions. Uji Jawaban retains the retrieval checks and draft reply tests.
Overlap candidates use normalized word similarity across the latest 400 passages. Up to 40 candidate pairs are shown. This is a review aid. Manual comparison searches all passages and can select sources outside the scanned window. The collection lists at most 200 manual articles and 100 PDFs.
An administrator can prefer a passage, record a replacement, retain both with applicability notes, or mark a conflict. Preferences and replacements suppress the other whole passage during retrieval and citation validation. Other sections in the same PDF retain their own eligibility. Applicability notes accompany evidence provided to the model. Clarification is required when the user’s scope is unclear.
Decisions capture fingerprints of source content, publication metadata, and PDF references. A changed fingerprint withholds both affected passages until an administrator reviews or removes the decision. Conflict decisions also withhold both passages. A preferred source must be published and currently valid. Preference cycles are rejected. Decisions and reversals are recorded with the author, timestamp, and reason.
Administrators can cancel decisions and inspect their history. Existing PDF version replacement still retires the previous document after the new version is published.
Verification includes retrieval and source selection tests in test_knowledge_authority.py and the disposable staging browser check in scripts/check_knowledge_base_browser.py. The browser check uses the private staging port 18089 and synthetic fixtures. It makes no Google calls or WhatsApp sends.