VNU BookMind Socratic Agent v42

VNU BookMind Socratic
Hệ thống gợi ý đọc sách chủ động — 6 tác nhân AI, 4 nguồn VNU LIC xác thực

"AI gợi ý và đặt câu hỏi, con người đọc và trả lời."

BookMind Socratic không phải chatbot. Không tóm tóm sách. Không trả lời sẵn. Mục đích duy nhất — buộc độc giả tư duy sâu khi đọc sách.

Ba nguyên tắc không thỏa hiệp

#	Nguyên tắc	Ý nghĩa
1	Không bịa sách	Mọi tài liệu đều từ 4 nguồn VNU LIC xác thực. Không Google Books, không DOI, không URL giả.
2	Không tóm tóm hộ	AI đặt câu hỏi Socrates, độc giả tự tìm câu trả lời trong sách.
3	Không trích dẫn suy nghĩ	AI suy nghĩ sâu 1000+ câu, nhưng nhật ký tư duy chỉ hiện trong console. Báo cáo cuối là LaTeX học thuật sạch.

Kiến trúc 6 Tác Nhân

Guardrail → Profiler → Recommender → Questioner → Critic → Reporter
  (Phòng Vệ)   (Hồ Sơ)    (Tìm Kiếm)   (Socrates)   (Phản Biện)   (Báo Cáo)

#	Tác Nhân	Chức Năng	Mô Hình Ollama
1	Lớp Phòng Vệ	Kiểm tra câu hỏi có hợp lệ (tư vấn sách) hay không	`gemma4:31b`
2	Phân Tích Hồ Sơ	Phân tích chân dung độc giả 5 chiều từ câu hỏi	`nemotron-3-ultra`
3	Tìm Kiếm Thư Viện VNU	Tìm kiếm 4 nguồn VNU LIC + RRF Fusion scoring + RAG v5	`nemotron-3-ultra`
4	Câu Hỏi Socrates	3 câu hỏi phản biện gắn sách cụ thể từ VNU LIC	`gemma4:31b`
5	Phản Biện	Phát hiện thiên kiến, 3 checkpoint tư duy	`gpt-oss:120b`
6	Biên Soạn Báo Cáo	Báo cáo LaTeX 7 section, sơ đồ Mermaid	`nemotron-3-ultra`

4 Nguồn VNU LIC (API công khai)

Nguồn	Loại	Mô tả
Bookworm (vnu.edu.vn)	Số hóa Kỹ thuật số	⭐ PRIMARY — 9 kết quả, 7 có PDF
Repository DSpace	Luận văn, bài báo khoa học	Bổ sung thông tin
OPAC Koha	Catalog thư viện vật lý	Tìm kiếm sách vật lý
LIC Portal / Primo	Cổng hợp tìm kiếm	Tìm kiếm mở rộng

🚀 Quick Start

1. Clone và cấu hình

git clone <repo-url>
cd bookmind-socratic-agent
cp .env.example .env
# Sửa OLLAMA_API_KEY trong .env
pip install -r requirements.txt

2. Chạy server

python main.py --server
# Server chạy tại http://localhost:8000

3. Sử dụng

Mở trình duy → nhập chủ đề sách → bấm Chạy Phân Tích → xem 6 tác nhân AI chạy tuần tự.

📊 Cấu trúc Project

bookmind-socratic-agent/
├── config.py                    # Model configs, timeouts, fallback chains
├── server.py                   # FastAPI backend + SSE streaming
├── main.py                     # CLI entry point
├── requirements.txt             # Python dependencies
├── render.yaml                  # Render deployment config
├── vercel.json                  # Vercel deployment config
├── frontend/
│   ├── index.html             # Single-page app
│   ├── app.js                # Frontend JS (SSE handling)
│   ├── style.css             # Styles
│   └── lib/                   # Static assets (FontAwesome, marked.js, mermaid.js)
├── src/
│   ├── state.py              # ResearchState TypedDict
│   ├── graph.py              # LangGraph pipeline definitions
│   ├── agents/
│   │   ├── guardrail_agent.py    # Kiểm tra câu hỏi
│   │   ├── profiler_agent.py     # Phân tích hồ sơ
│   │   ├── recommender_agent.py # Tìm kiếm VNU LIC + RRF
│   │   ├── questioner_agent.py  # Câu hỏi Socrates
│   │   ├── critic_agent.py     # Phản biện
│   │   └── reporter_agent.py   # Biên soạn báo cáo LaTeX
│   ├── utils/
│   │   ├── llm_factory.py      # LLM factory + fallback chain
│   │   ├── cleaner.py          # URL whitelist, CJK clean, artifact removal
│   │   ├── display.py          # Rich console display
│   │   ├── link_validator.py   # HTTP link validation
│   │   └── vnu_lic_links.py   # VNU LIC link helpers
│   ├── tools/
│   │   ├── vnu_lic_api.py       # 4-source VNU library API
│   │   └── rag_tools.py         # RAG v5 (15 algorithms)
│   ├── rag/                     # RAG algorithms (BM25, TF-IDF, Dense, MMR, etc.)
│   │   ├── adaptive_retriever.py
│   │   ├── cross_encoder.py
│   │   └── ...
│   ├── middleware/
│   │   ├── error_handler.py     # Structured error responses
│   │   ├── rate_limiter.py      # Rate limiting
│   │   └── request_logger.py     # Request logging
│   └── data/raw/                 # VNU LIC knowledge base (markdown)

🔧 Cấu hình Môi trường

Biến bắt buộc (`.env`)

Biến	Mô tả	Giá trị mẫu
`OLLAMA_API_KEY`	API key Ollama Cloud	Từ ollama.com
`OLLAMA_BASE_URL`	Base URL API	`https://ollama.com/v1`
`DISABLE_SSL_VERIFY`	Tắt SSL verify (deploy cloud)	`true`
`VNU_COOKIE_*`	Cookies VNU LIC (tuỳ chọn)	Xem `.env.example`

Mô hình AI (Free trên Ollama Cloud)

Agent	Mô hình chính	Fallback
Guardrail	`gemma4:31b` (1.4s)	`gpt-oss:120b`, `nemotron-3-nano:30b`
Profiler	`nemotron-3-ultra` (2.8s)	`gemma4:31b`, `gpt-oss:120b`
Recommender	`nemotron-3-ultra` (2.8s)	`gemma4:31b`, `gpt-oss:120b`
Questioner	`gemma4:31b` (1.4s)	`gpt-oss:120b`, `nemotron-3-nano:30b`
Critic	`gpt-oss:120b` (1.8s)	`gemma4:31b`, `nemotron-3-nano:30b`
Reporter	`nemotron-3-ultra` (2.8s)	`gemma4:31b`, `gpt-oss:120b`

Tất cả 7 mô hình đã được verify hoạt động (2026-07-19). API key Ollama Cloud miễn phí hỗ trợ nhiều model hơn (minimax-m3, gpt-oss:20b, v.v.).

🛡️ Chống Phòng Chống Lỗi (Anti-Fabrication)

1. URL Whitelist Post-Processing

Mọi URL trong báo cáo được kiểm tra chống domain VNU LIC. URL không hợp lệ → xóa hoặc thay bằng link tìm kiếm an toàn.

2. LLM Hallucination Defense

Nhiều class để phát hiện thiên kiến xác nhận
Post-hoc URL injection từ dữ liệu API thực (LLM-proof)
Safety clean: strip thinking/console leakage, fix malformed URLs, remove forbidden sources

3. Kiểm tra chéo nguồn

Citation verifier (RAG) kiểm tra trích dẫn trong báo cáo
Table query-title remover: xóa hàng bảng có tiêu đề là câu hỏi
CJK character stripping (tiếng Nhật, Trung)

4. Error Classification

Loại	Mã	Xử lý
Model not found	404	Fallback chain tự động
Timeout	408	Thử model khác
Rate limit	429	Chờ và thử lại
Auth	401/403	Báo lỗi rõ ràng
Network	-	Báo lỗi thân thiện

🔀 RAG v5 — 15 Thuật Toán

Hệ thống RAG nâng cao với 15 thuật toán:

BM25 — Vietnamese-optimized Okapi BM25
TF-IDF Cosine — Normalized TF với cosine similarity
Dense Semantic — TF-IDF → dense vectors (random projection, JL lemma)
RRF — Weighted multi-signal fusion
Query Expansion — Vietnamese synonym + English cross-lingual
Query Decomposition — Complex query → sub-queries
Intent Classification — Intent-aware strategy routing
Cross-Encoder — Heuristic pair scoring
Contextual Compression — Sentence-level relevance
MMR Reranking — Diversity-aware selection
Relevance Feedback — Rocchio query expansion
Citation Verification — Claim-level source verification
Adaptive Retrieval v4 — Complexity × intent strategy
Smart Chunking — Section-boundary-aware splitting
API-RAG Bridge — Real-time API results → RAG knowledge base

📊 Đánh Giá Hiệu Suất (Tested 2026-07-19)

Pipeline Test (Flash Mode, 5/6 agents, không có Recommender VNU search)

guardrail:   3.8s  ✅  (was 13.2s — 3.5x faster)
profiler:    19.8s ✅  (profile: 751 chars)
questioner:  3.5s  ✅  (was 19.7s — 5.6x faster)
critic:      25.5s ✅  (analysis: 6899 chars)
reporter:    29.7s ✅  (report: 12,081 chars, has \section LaTeX, has VNU links)
────────────────────────
TOTAL:       ~82s  ✅ (was timeout)

API Health Check

{"status": "alive", "version": "42.0", "architecture": "6-agent", "rss_mb": 0}

Ollama Cloud Model Test (All 7 models)

OK  guardrail    model=gemma4:31b          0.8s
OK  profiler     model=nemotron-3-ultra          1.3s
OK  recommender  model=gpt-oss:120b              1.6s
OK  questioner   model=gemma4:31b                0.7s
OK  critic       model=gpt-oss:120b              0.9s
OK  reporter     model=nemotron-3-ultra          1.6s
OK  chat         model=gemma4:31b                0.9s

VNU LIC Bookworm Search

Bookworm: 9 kết quả (public API), 7/9 có PDF link
Repository: timeout (public fallback)
OPAC Koha: 0 kết quả (public)
LIC Portal: timeout (public fallback)

🏗️ API Endpoints

Endpoint	Method	Mô tả
`/`	GET	Frontend SPA
`/api/health`	GET	Health check
`/api/run`	POST	Main pipeline — SSE streaming
`/api/run_sync`	POST	Pipeline sync (fallback)
`/api/chat`	POST	Chat follow-up
`/api/unlock`	POST	Force unlock pipeline
`/api/logs`	GET	Recent request logs

SSE Event Types (POST /api/run)

Event	Mô tả
`node_start`	Agent bắt đầu
`agent_thinking`	Nhật ký tư duy (real-time)
`agent_end`	Agent hoàn thành + stats
`pipeline_complete`	Pipeline hoàn tất + report + books + questions
`error`	Lỗi (thân thiện tiếng Việt)
`ping`	Heartbeat (elapsed time)
`done_sentinel`	Kết thúc stream

🚢 Deployment

Render (Backend)

Kết nối GitHub repo → Render
Build Command: pip install -r requirements.txt
Start Command: python main.py --server
Environment Variables: OLLAMA_API_KEY, OLLAMA_BASE_URL
Health Check: /api/health

Vercel (Frontend)

Kết nối GitHub repo → Vercel
Root Directory: frontend/
Framework Preset: Node.js (static export)
Environment Variables: none needed (frontend calls backend API)

🔄 Cập Nhật Gần Đây (v42 — 2026-07-19)

Performance Optimization

Guardrail 3.8s (was 13.2s): Giảm thinking từ 25-35 câu → 3-5 câu (flash mode)
Questioner 3.5s (was 19.7s): Tương tự — thinking giảm 10x
Reporter hoàn thành (was timeout): Tăng max_tokens 2500→4000
Tổng pipeline ~82s (5 agents) — trước đó timeout ở 300s

Bug Fixes

ainvoke_with_streaming_fallback: Fix double timeout wrapper
QueueCallbackHandler: Fix deprecated get_event_loop() → get_running_loop()
Reporter parse_agent_json: Fix empty detailed_report fallback
VNU API timeouts: Giảm public HTTP timeout 15→10s, futures 20→12s
httpx resource management: Document follow_redirects=True for ollama.com
AGENT_DISPLAY: Thêm "recommender" (trước chỉ có "retriever")

Code Quality

URL whitelist post-processing (anti-fabrication)
CJK character stripping
Markdown artifact cleaning
LLM artifact removal ("As an AI", etc.)
Structured error responses (ErrorCode enum)
Rate limiting (per-endpoint)
Pipeline lock with stale detection
Graceful degradation (every agent has fallback)

📄 License

MIT

Name		Name	Last commit message	Last commit date
Latest commit History 31 Commits
.github		.github
data/raw		data/raw
frontend		frontend
src		src
.env.example		.env.example
.gitignore		.gitignore
BUILD_STAMP		BUILD_STAMP
LICENSE		LICENSE
README.md		README.md
config.py		config.py
main.py		main.py
render.yaml		render.yaml
requirements.txt		requirements.txt
runtime.txt		runtime.txt
server.py		server.py
setup_deploy.sh		setup_deploy.sh
vercel.json		vercel.json
worklog.md		worklog.md

Folders and files

Latest commit

History

Repository files navigation

VNU BookMind Socratic Agent v42

"AI gợi ý và đặt câu hỏi, con người đọc và trả lời."

Ba nguyên tắc không thỏa hiệp

Kiến trúc 6 Tác Nhân

4 Nguồn VNU LIC (API công khai)

🚀 Quick Start

1. Clone và cấu hình

2. Chạy server

3. Sử dụng

📊 Cấu trúc Project

🔧 Cấu hình Môi trường

Biến bắt buộc (.env)

Mô hình AI (Free trên Ollama Cloud)

🛡️ Chống Phòng Chống Lỗi (Anti-Fabrication)

1. URL Whitelist Post-Processing

2. LLM Hallucination Defense

3. Kiểm tra chéo nguồn

4. Error Classification

🔀 RAG v5 — 15 Thuật Toán

📊 Đánh Giá Hiệu Suất (Tested 2026-07-19)

Pipeline Test (Flash Mode, 5/6 agents, không có Recommender VNU search)

API Health Check

Ollama Cloud Model Test (All 7 models)

VNU LIC Bookworm Search

🏗️ API Endpoints

SSE Event Types (POST /api/run)

🚢 Deployment

Render (Backend)

Vercel (Frontend)

🔄 Cập Nhật Gần Đây (v42 — 2026-07-19)

Performance Optimization

Bug Fixes

Code Quality

📄 License

About

Resources

License

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

Biến bắt buộc (`.env`)

Packages