BOC Allocation Review Agent

Vấn đề: quy trình rà soát kế toán không scale tốt trên spreadsheet

Rà soát kế toán thường bắt đầu từ một workbook. Nhìn bề ngoài, các dòng ledger có vẻ lặp lại — nhưng mỗi giao dịch có thể ẩn rủi ro review ở nhiều chiều: địa điểm phát sinh chi phí, điều kiện đủ để nhận tax credit, danh mục allocation, tỉnh/bang, vendor, mô tả giao dịch có đủ rõ không, và chứng từ hỗ trợ có tồn tại không.

Nếu làm thủ công, quy trình này chậm, khó audit, và rất dễ áp dụng không nhất quán khi cùng một bộ luật phải được “dịch” lại từ đầu cho hàng trăm dòng. Vấn đề cốt lõi không phải là reviewer hay mắc lỗi — mà là quy trình không có khung hỗ trợ có cấu trúc: không có phân loại sơ bộ tự động, không tách được case rõ khỏi case ngoại lệ, không có hàng chờ rõ ràng cho những gì thật sự cần người quyết định.

Câu hỏi dự án này muốn trả lời là: liệu một data workflow có thể xử lý phần rà soát có luật rõ ràng — và chỉ đẩy những case thật sự chưa chắc chắn sang cho người review?

Vai trò: một mình từ đầu đến cuối

Đây là project solo, được nộp cho Kaggle 5-Day AI Agents Intensive Vibe Coding Capstone with Google, track Agents for Business. Toàn bộ hệ thống được thiết kế và xây dựng độc lập:

• Thiết kế tổng thể data workflow và kiến trúc hệ thống
• Xác định và implement bộ luật kiểm tra xác định (deterministic rule engine)
• Xây dựng pipeline ingestion, validation, cleaning và transformation
• Thiết kế hàng chờ Human-in-the-Loop và cơ chế ghi nhận quyết định của reviewer
• Xây dựng Streamlit dashboard và chức năng export
• Implement local TF-IDF RAG cho câu hỏi về tài liệu và workflow
• Thiết kế ADK-inspired runtime (Planner, Executor, Tool Registry, RuntimeTrace)
• Viết test suite (307 automated tests) và toàn bộ tài liệu dự án
• Viết migration blueprint cho hướng chuyển sang native ADK trong tương lai
• Chuẩn bị Docker packaging và tài liệu Cloud Run readiness

Quá trình: data workflow trước, agent sau

Quyết định định hình toàn bộ thiết kế là một lựa chọn về thứ tự: xem đây là bài toán data workflow trước khi xem nó là bài toán AI.

Điều đó có nghĩa là thứ được thiết kế đầu tiên không phải là agent hay LLM layer — mà là business rules. Giao dịch nào đủ điều kiện? Điều kiện nào kích hoạt allocation flag? Tổ hợp location code và province nào đưa giao dịch vào hàng chờ Quebec review? Những luật đó được encode thành deterministic logic trong allocation_tool.py và được giữ nguyên không đổi suốt dự án. Không một cập nhật tài liệu, không một lần polish portfolio, không một thay đổi kiến trúc nào được phép làm thay đổi allocation logic. Sau mỗi giai đoạn, đều kiểm tra lại để xác nhận business rules không bị ảnh hưởng — vì cải thiện phần trình bày không nên vô tình làm thay đổi thứ hệ thống thực sự làm.

Khi rule engine ổn định, phần còn lại của workflow được lắp vào xung quanh: ingestion và schema validation, cleaning và transformation, classification và đánh giá eligibility, dashboard metrics, hàng chờ Human-in-the-Loop, export, và cuối cùng là lớp conversational assistant dùng local TF-IDF RAG.

ADK-inspired runtime được xây để tổ chức workflow này mà không dùng native Google ADK. Các thành phần giống agent (Planner, Executor, Tool Registry), RuntimeTrace records cho observability nội bộ, và conversational orchestration đều được implement cục bộ. Sau đó, một migration blueprint đầy đủ được viết để giải thích cách kiến trúc này có thể chuyển sang native Google ADK trong tương lai — được viết cẩn thận để nói rõ con đường phía trước mà không claim rằng tích hợp đó đã tồn tại.

Hệ thống làm được gì

• Đọc synthetic GL workbook với 201 giao dịch
• Kiểm tra schema đầu vào trước khi xử lý bất kỳ bước nào phía sau
• Làm sạch và chuyển đổi các dòng giao dịch thành record sẵn sàng review
• Phân loại từng giao dịch qua bộ luật xác định
• Đánh giá eligibility và rủi ro cần review
• Gợi ý allocation khi luật đủ rõ ràng
• Đưa các trường hợp chưa chắc chắn hoặc có rủi ro vào hàng chờ Human-in-the-Loop
• Cho phép reviewer ghi nhận quyết định cho các case trong queue
• Xuất reviewed workbook và review queue
• Tính dashboard metrics tách rõ case chắc chắn khỏi case ngoại lệ
• Cung cấp read-only conversational assistant cho tài liệu và câu hỏi về workflow
• Có Docker packaging và tài liệu Cloud Run readiness
• Có native ADK migration blueprint

Kết quả trên bộ dữ liệu demo

Trên synthetic workbook nộp cho capstone verification:

• 201 giao dịch được xử lý
• 113 auto-approved
• 88 đưa vào human review
• 18 chi phí không đủ điều kiện
• 70 trường hợp cần review eligibility
• 10 trường hợp out-of-Canada
• 33 trường hợp cần review Quebec
• 307 automated tests pass

Các con số này mô tả workbook demo và test suite của dự án — không phải benchmark kế toán tổng quát hay cam kết hiệu quả production.

Phản tư kỹ thuật: phần nào thực sự tốn thời gian nhất

Phần khó nhất của dự án này không phải là Python logic hay data pipeline. Mà là chất lượng tài liệu và tính toàn vẹn của repository — và những bài toán kỹ thuật thật sự ẩn bên trong đó.

Về việc không để AI quyết định kết quả kế toán. Quyết định kiến trúc có chủ ý nhất là không để LLM quyết định allocation hay eligibility cho mục đích tax credit. Những quyết định đó cần explainable và reproducible: reviewer phải thấy được vì sao một giao dịch được phân loại theo cách đó, trace về đúng một luật cụ thể, và tin rằng cùng input chạy lại sẽ cho cùng output. LLM không đảm bảo điều đó một cách đáng tin cậy. Vì vậy rule engine giữ nguyên deterministic, còn AI layer chỉ được dùng để tổ chức workflow, sinh giải thích và xử lý document retrieval — không phải để đưa ra quyết định quan trọng.

Về việc xây ADK-inspired runtime mà không dùng native ADK. Thiết kế các thành phần giống agent cục bộ — Planner, Executor, Tool Registry, RuntimeTrace — thú vị về mặt kỹ thuật, nhưng phần khó hơn là tài liệu hóa nó một cách trung thực. Kiến trúc này lấy cảm hứng rõ ràng từ ADK patterns mà không implement Google ADK runtime thực sự. Sự phân biệt đó phải được viết cẩn thận ở khắp nơi: README, phần kiến trúc, migration blueprint. Làm cho ngôn ngữ chính xác — không undersell thiết kế, cũng không overclaim implementation — tốn nhiều lần chỉnh sửa hơn dự kiến.

Về false claim detection như một bài toán xử lý văn bản. Test suite cuối cùng có cả các validator kiểm tra tài liệu cho các claim gây hiểu lầm — phát biểu deployment sai, claim ADK/Vertex AI implementation không đúng, test count cũ, broken link. Các phiên bản đầu của detector này quá thô: một câu như “Cloud Run deployment readiness is documented, but the app is deployed to Cloud Run” vẫn pass vì safe words ở chỗ khác trong câu triệt tiêu unsafe claim. Các detector phải được thiết kế lại để hoạt động ở cấp độ câu và cấp độ match — normalize text, tách thành câu, detect unsafe phrase, rồi kiểm tra xem mỗi match có được một qualifying safe phrase cover trực tiếp không, thay vì để safe wording không liên quan cancels một vấn đề thật. Cái bắt đầu như là hygiene task tài liệu trở thành một bài toán xử lý văn bản thật sự thú vị.

Về việc tách concerns khi áp lực tăng cao. Mỗi review cycle giai đoạn cuối đều phải kháng lại cám dỗ “chỉ sửa một thứ nhỏ” trong business logic trong khi đang cập nhật tài liệu. Giữ allocation_tool.py được đánh dấu rõ là frozen và re-verify sau mỗi giai đoạn củng cố một điều đáng mang theo: trong bất kỳ hệ thống nào mà rules là nguồn sự thật, kỷ luật không động vào chúng quan trọng ngang với việc viết chúng đúng ngay từ đầu.

Bài học rõ nhất khi kết thúc dự án: xây một hệ thống dữ liệu đáng tin — loại mà reviewer thực sự có thể dựa vào — đòi hỏi nỗ lực kỹ thuật ở testing, traceability, tài liệu và giao tiếp trung thực ngang với phần logic.

Giới hạn

• Chỉ dùng dữ liệu tổng hợp/synthetic
• Không đưa ra kết luận thuế, pháp lý hoặc compliance chính thức
• Không kết nối cơ sở dữ liệu chính phủ live
• Không tạo CAVCO Form 6 chính thức
• Không tích hợp native Google ADK, Vertex AI hoặc Gemini runtime
• Cloud Run-ready theo tài liệu và đóng gói; không claim live production deployment
• Hỗ trợ quy trình review và quyết định của con người; không thay thế kế toán viên hoặc auditor

Nếu làm lại

• Bắt đầu test suite và documentation validator sớm hơn, không phải là hoạt động giai đoạn cuối
• Khám phá lightweight sentence-level classification cho false-claim detector thay vì hand-coded phrase matching
• Prototype Human-in-the-Loop queue UX với reviewer thật trước khi finalize giao diện
• Xây ADK migration blueprint song song với local runtime thay vì làm retrospectively

Liên kết

• GitHub
• GitHub Release
• Kaggle Writeup
• YouTube Demo