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/](../backend/pipeline/) mà [../backend/main.py](../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/](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/](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](test/mvp_eval_output/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](test/mvp_eval_output/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](test/mvp_eval_output/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](test/mvp_eval_output/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](test/mvp_eval_output/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](test/mvp_eval_output/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](test/mvp_eval_output/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](test/docling_output/49.pdf.json) (39.060 ký tự) →
  **Output:** [test/mvp_eval_output/49.json](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](test/docling_output/323.pdf.json) (33.602 ký tự) →
  **Output:** [test/mvp_eval_output/323.json](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](test/docling_output/355.pdf.json) (28.903 ký tự) →
  **Output:** [test/mvp_eval_output/355.json](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](test/docling_output/435.pdf.json) (34.715 ký tự) →
  **Output:** [test/mvp_eval_output/435.json](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](test/docling_output/768.pdf.json) (30.985 ký tự) →
  **Output:** [test/mvp_eval_output/768.json](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](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](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)

```powershell
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](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](../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](../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.