docs/parser/eval.md

Eval — manual test cases (Gate G2)

Bằng chứng cho deliverable 5 của Gate G2 — First Working Agent (MVP): "Eval evidences — ít nhất 5 test case manual với output thực tế" (issue #4).

Run date: 2026-06-18 (TC1–5) · 2026-06-19 (TC6–7) · Model: openai/gpt-oss-120b:free qua OpenRouter · Environment: local (Windows), Python 3.12 · Không mock — gọi LLM API thật.

User flow chính được test: bài báo → extract_* → (related-work search, tùy chọn) → generate_review → review có cấu trúc theo rubric ACL Rolling Review (ARR). Đây là pipeline thật trong ../backend/pipeline/ mà ../backend/main.py gọi khi người dùng nộp bài. Output thật lưu nguyên văn tại test/mvp_eval_output/ (1 file JSON/case). Đối chiếu chất lượng với review của con người (PeerRead ACL-2017) trong test/reviews/.

---

Bảng tổng hợp

#	Loại	Input (bài/nội dung nộp)	Expected behavior	Actual output (real run)	Pass?
1	main	Paper 49 — Chunk-based Decoder for NMT	Review hợp lệ, bám đúng bài, điểm hợp lý	overall 2.5 (Borderline Findings); snd 3/exc 3/rep 2/conf 4; summary + 3 strengths + 4 weaknesses đúng nội dung NMT theo chunk → 49.json	✅
2	main	Paper 323 — A Neural Local Coherence Model	nt	overall 3.0 (Accept — Findings); snd 3/exc 3/rep 4/conf 4; nhận đúng CNN trên entity-grid, pairwise ranking loss → 323.json	✅
3	main	Paper 355 — Multi-Predicate Interactions (Japanese PAS)	nt	overall 3.0 (Accept — Findings); snd 4/exc 3/rep 4/conf 4; nhận đúng Grid-RNN, NAIST corpus → 355.json	✅
4	main	Paper 435 — Causal Lexical Markers Disambiguation	nt	overall 1.5 (Resubmit Major); snd 2/exc 2/rep 1/conf 3; chỉ ra thiếu bảng số liệu, thiếu chi tiết mô hình → 435.json	✅
5	main	Paper 768 — Detecting Lexical Entailment in Context	nt	overall 3.0 (Accept — Findings); snd 4/exc 3/rep 3/conf 4; nhận đúng task mới + Context2Vec; bắt được typo "filed"→"flew" → 768.json	✅
6	edge	Tài liệu gần như rỗng (1 dòng, không method/kết quả)	Không crash; nhận ra thiếu nội dung, chấm thấp, góp ý	overall 1.0 (Do Not Resubmit); snd 1/exc 1/rep 1; "There is no methodology, data, or experimental validation…" → edge_minimal.json	✅
7	failure	Không phải paper (hỏi thời tiết / đặt vé / gợi ý nhà hàng)	Từ chối lịch sự, nêu rõ không phải bài báo	overall 1.0 (Do Not Resubmit); "This text does not constitute a research paper… informal user queries about weather in Hanoi, a flight booking…" → failure_nonpaper.json	✅

7/7 PASS (5 main + 1 edge + 1 failure). Agent chạy end-to-end thật, output đúng schema, bám đúng nội dung, và xử lý gọn cả input bất thường.

Quan sát về độ khớp với người chấm (TC1–5)

• Đồng thuận ở bài yếu nhất: cả AI lẫn người đều xếp 435 thấp nhất (AI 1.5; người REC 2/3).
• Agent nghiêm hơn người ở reproducibility (siết việc công bố code/chi tiết) → overall thấp hơn.
• Thang AI (ARR 1–4) ≠ thang người (ACL 1–5) nên chỉ so theo hướng/xếp hạng, không tuyệt đối.

Paper	AI overall (ARR 1–4)	Human RECOMMENDATION (ACL 1–5)
49	2.5	4, 4
323	3.0	4, 3
355	3.0	4, 4, 4
435	1.5	2, 3
768	3.0	4, 2, 2

---

Chi tiết từng test case (output thực tế)

Trích nguyên văn. Bản đầy đủ (contributions, research_topic, toàn bộ review): xem file JSON.

TC1 — Paper 49 · Chunk-based Decoder for Neural Machine Translation

• Input: test/docling_output/49.pdf.json (39.060 ký tự) → Output: test/mvp_eval_output/49.json
• Scores: soundness 3 · excitement 3 · reproducibility 2 · confidence 4 · overall 2.5
• Summary (AI): "The paper proposes a hierarchical decoder for NMT that first generates chunk representations to capture inter-chunk (global) dependencies and then generates words inside each chunk… Three variants are introduced… Experiments on WAT '16 En→Ja show BLEU improvements…"
• Đánh giá thủ công: ✅ Đúng nội dung; trùng mối lo của người chấm thật (reviewer PeerRead cũng đòi GRU tree-to-seq baseline, ensembling, decoding time). AI bảo thủ hơn (2.5 vs người 4/4).

TC2 — Paper 323 · A Neural Local Coherence Model

• Input: test/docling_output/323.pdf.json (33.602 ký tự) → Output: test/mvp_eval_output/323.json
• Scores: soundness 3 · excitement 3 · reproducibility 4 · confidence 4 · overall 3.0
• Summary (AI): "…a convolutional neural network that operates directly on the entity-grid representation… trained with a pairwise ranking loss… improvements over previous entity-grid baselines, with absolute gains of roughly 4% to 4.5%. The authors also release their code…"
• Đánh giá thủ công: ✅ Đúng nội dung (kể cả việc tác giả công bố code → reproducibility 4). Khớp hướng tích cực với người (4/3).

TC3 — Paper 355 · Neural Modeling of Multi-Predicate Interactions (Japanese PAS)

• Input: test/docling_output/355.pdf.json (28.903 ký tự) → Output: test/mvp_eval_output/355.json
• Scores: soundness 4 · excitement 3 · reproducibility 4 · confidence 4 · overall 3.0
• Summary (AI): "…a grid-type recurrent neural network (Grid-RNN) that processes all predicates jointly… without relying on external syntactic parsers… state-of-the-art F-scores on the NAIST Text Corpus…"
• Đánh giá thủ công: ✅ Đúng nội dung. Khớp hướng tích cực mạnh với người (4/4/4); AI hơi bảo thủ (3.0).

TC4 — Paper 435 · Neural Disambiguation of Causal Lexical Markers based on Context

• Input: test/docling_output/435.pdf.json (34.715 ký tự) → Output: test/mvp_eval_output/435.json
• Scores: soundness 2 · excitement 2 · reproducibility 1 · confidence 3 · overall 1.5
• Weaknesses (AI): mô tả mô hình/huấn luyện không đủ để tái lập; kết quả chỉ nêu "vượt SOTA" mà không có bảng số liệu, không kiểm định ý nghĩa thống kê; related-work nhiều lỗi.
• Đánh giá thủ công: ✅ Đúng — bài yếu nhất, agent chấm thấp nhất (1.5), đồng thuận với người (2/3).

TC5 — Paper 768 · Detecting Lexical Entailment in Context

• Input: test/docling_output/768.pdf.json (30.985 ký tự) → Output: test/mvp_eval_output/768.json
• Scores: soundness 4 · excitement 3 · reproducibility 3 · confidence 4 · overall 3.0
• Summary (AI): "…introduces a new task of lexical entailment in context… two methods to obtain contextualized word vectors (element-wise masking; an adaptation of Context2Vec)… logistic regression classifier… state-of-the-art results."
• Đánh giá thủ công: ✅ Đúng nội dung (tên task, hai phương pháp). Người phân hóa (4/2/2); AI lạc quan hơn (3.0). Bắt được typo "filed"→"flew".

TC6 (EDGE) — Tài liệu gần như rỗng

• Input: synthetic, 118 ký tự: "# Note … This document intentionally contains almost no content. It has no methodology, no experiments, and no results." → Output: test/mvp_eval_output/edge_minimal.json
• Expected: không crash; nhận ra thiếu nội dung; chấm thấp; góp ý.
• Actual (AI): overall 1.0 (Do Not Resubmit); snd 1/exc 1/rep 1. Weaknesses: "There is no methodology, data, or experimental validation, making it impossible to assess scientific merit." Comments đề xuất cách biến thành đóng góp thật (định nghĩa research question…).
• Đánh giá thủ công: ✅ Xử lý gọn, đúng schema, không lỗi; phản ứng hợp lý với input nghèo nội dung.

TC7 (FAILURE) — Input không phải bài báo (out-of-scope)

• Input: synthetic, 185 ký tự: "What's the weather like today in Hanoi? … book me a cheap flight to Da Nang … recommend a good seafood restaurant…" → Output: test/mvp_eval_output/failure_nonpaper.json
• Expected: từ chối lịch sự, nêu rõ không phải bài báo.
• Actual (AI): overall 1.0 (Do Not Resubmit). Summary: "The submission consists of a series of informal user queries… The text does not constitute a research article and lacks any scholarly contribution." research_topic cũng nói rõ "This text does not constitute a research paper."
• Đánh giá thủ công: ✅ Nhận đúng input ngoài phạm vi và từ chối hợp lý — đúng hành vi mong đợi cho failure case.

---

Cách tái lập (reproducible)

cd C:\Users\DELL\Desktop\paper-review
$PY = "C:\Users\DELL\AppData\Local\Programs\Python\Python312\python.exe"
$env:PYTHONIOENCODING = "utf-8"

# .env cần: LLM_PROVIDER=openrouter, LLM_MODEL=openai/gpt-oss-120b:free, OPENROUTER_API_KEY=sk-or-...
& $PY docs\scripts\run_mvp_eval.py                       # chạy cả 5 paper chính
& $PY docs\scripts\run_mvp_eval.py --only 49             # 1 paper
& $PY docs\scripts\run_mvp_eval.py --only edge_minimal   # edge case
& $PY docs\scripts\run_mvp_eval.py --only failure_nonpaper  # failure case
& $PY docs\scripts\run_mvp_eval.py --dry                 # validate, không gọi LLM

• Runner: scripts/run_mvp_eval.py. Có retry backoff khi free model trả HTTP 429 (_install_retry).
• PDF→text: runner nạp nội dung paper đã parse từ test/docling_output/ (output OCR Docling thật của hệ thống) thay cho bước upload PDF, để eval không phụ thuộc LandingAI credit / Kaggle server. Bước extract + review không đổi so với web flow — vẫn gọi LLM thật trên nội dung paper thật. Edge/failure dùng input tổng hợp định nghĩa ngay trong runner (SYNTHETIC).
• Cấu hình: .env có HF_TOKEN → cần extra = "ignore" trong ../backend/config.py (đã thêm), nếu không Pydantic Settings crash khi khởi động.

---

Hạn chế & phát hiện qua đánh giá thủ công

• 🟧 Input bị cắt còn 8.000 ký tự trong generate_review (../backend/pipeline/review.py): nhận xét kiểu "related work section is empty" (paper 49) có thể do LLM không thấy phần cuối bài → nên tăng giới hạn hoặc tóm tắt trước.
• 🟦 Không bật related-work search (thiếu Tavily key) → trường contextualization yếu hơn flow đầy đủ.
• 🟦 Thang điểm bảo thủ: agent cho overall/reproducibility thấp hơn người chấm; cần lưu ý khi diễn giải.
• ✅ Không lỗi schema/parse ở cả 7 case; _normalize_review xử lý đúng mọi output.

Kết luận

Agent đạt Gate G2 (MVP): nhận input thật → gọi LLM thật (không mock) → trả review đúng schema ARR. Bao phủ main flow (5 paper) + 1 edge case + 1 failure case; xếp hạng chất lượng đồng hướng với người chấm (đặc biệt nhận đúng bài yếu nhất 435) và xử lý gọn input bất thường. Các hạn chế còn lại (truncation input, thiếu search) đã được ghi nhận, không cản trở user flow chính chạy end-to-end.