Nôm 喃

Open-source Python toolkit for building Vietnamese AI applications.

Named after chữ Nôm — the script Vietnam wrote in for a millennium.

A local-first toolkit. No data leaves your machine. Use any LLM (Ollama by default), any embedder, any document type — Nôm wires them into a Vietnamese-aware RAG pipeline you can ship as either a Python library or a deployable chat web app.

Every default is benched on real Vietnamese data. Where a public Apache/MIT model beats a multilingual one, we use it. See docs/benchmark.md for the receipts.

---

The 3-line demo

pip install "nom-vn[chat]"     # FastAPI + React UI + parsers + embeddings
nom serve                       # opens http://localhost:8080
# upload PDFs/Word/Excel/PowerPoint/images, ask questions in Vietnamese

The web app is built into the wheel — there's nothing else to install. As of v0.2.30 it's a full playground: chat-with-RAG plus stateless tool pages for diacritic restore (rule / HF seq2seq / LLM backends), word + sentence segmentation, NFC normalize + VN detect, strip-diacritics, and a reproducible noise generator for training. Cmd/Ctrl + Enter runs from anywhere.

---

Recommended stack — measured 2026-05-02

Every recommendation has a measured number from a script in benchmarks/ that runs on a clean clone. No projected numbers. No "based on the model card." Numbers came out of our hardware, on real Vietnamese corpora, this week.

The decision in plain English:

• Want VN diacritics fixed? Install nom-vn[diacritic-hf] and use the default — nrl-ai/vn-diacritic-vit5-base. Wins on formal + conversational + business + literary against the public landscape; the -small variant trades 4 pp for ~3× speed.
• Want spell correction (typos + accents + OCR errors in one pass)? Same install, swap the model id to nrl-ai/vn-spell-correction-base. Beats bmd1905/vietnamese-correction-v2 by 11-25 pp.
• Care about real-world (not just synthetic) accuracy? Read the out-of-distribution OOD bench — 175 real Vietnamese error samples across 6 registers, with bootstrap 95 % CI. Headline (v0.2.29): synthetic 98.32 % light avg, OOD aggregate 89.54 %, against Toshiiiii1 87.29 % and bmd1905 57.86 %.
• Want local RAG over Vietnamese documents? Install nom-vn[chat,embeddings,nlp], swap the default embedder to BKaiEmbedder. +41 pp R@1.
• Need OCR on Vietnamese scans? Two answers depending on what you have: Tesseract vie is the right call for printed lines (0.00 % CER on clean printed). VietOCR is the right call for handwriting (31.82 % CER vs Tesseract 69.34 % — the 37.5 pp gap is the biggest single OCR finding in the repo). PaddleOCR PP-OCRv5 ranks 3rd everywhere because it ships no VN-specific recognizer; lang='vi' loads generic latin_PP-OCRv5_mobile_rec which strips diacritics. Don't reach for VLM OCR on tight line crops — VLMs hallucinate at line scale (use a VLM only when you have full-document context like forms or invoices).
• Need PDF text extraction in a license-clean way? Use pypdfium2 (we ship it). Skip PyMuPDF — its AGPL forces every downstream into AGPL.

Enterprise edition

The OSS core is enough to ship an internal RAG pipeline. The enterprise edition adds the things a regulated deployment needs — and nothing else. Open core, one-way: every EE feature plugs into the OSS code through nom.platform Protocols (Authenticator / RBAC / PIIDetector / Redactor / AuditForwarder), so the core stays auditable and replaceable.

Built for self-host / private cloud / air-gap deployments — see the enterprise page for the security posture, deployment modes, and contact form. Email [email protected] for a 30-minute scoping call.

What ships today

---

Multi-task playground web app (since v0.2.30)

Left rail switches between chat (RAG over your docs) and stateless tools — diacritic restore, tokenize, normalize/detect, strip diacritics, noise generator — plus a Settings page (server health, bearer-token auth, LLM backend picker, default top_k) and an API & Setup page (cURL examples + setup commands for Ollama / llama.cpp / HuggingFace / OpenAI / Anthropic). Editorial palette, sharp corners, full keyboard navigation (Cmd/Ctrl + Enter runs the active tool, gear icon top-right opens Settings).

Chat with citations grounded in indexed Vietnamese documents:

Diacritic-restore tool with backend picker (rule / HF seq2seq / LLM) and per-word change highlighting:

Word + sentence segmentation with compound highlighting:

NFC normalize + Vietnamese detection:

Reproducible noise generator for training (noisy → clean pairs) — pick a preset, set a seed, run:

Settings page — server health, authentication toggle, LLM backend picker that emits a copy-paste launch command:

API & Setup page — Vietnamese-language install/run guide and cURL examples for every endpoint:

---

Browser viewers for every supported format

Click any material in the right panel — Original tab renders the file natively, Extracted tab shows what the chunker + embedder saw. PDFs / images use the browser's native viewer; Office formats render as structured HTML so the browser can show them without LibreOffice.

---

Library use (no web app)

from nom.rag import RAG
from nom.llm import Ollama

rag = RAG.from_documents(
    ["contract.pdf", "letter.docx", "Hợp đồng số HD-001..."],
    llm=Ollama(model="qwen3:8b"),
)

answer = rag.ask("Có bao nhiêu hợp đồng có phạt vi phạm?")
print(answer.text)         # the LLM's response
print(answer.citations)    # [(doc_idx, chunk_idx, score, text), ...]

Document extraction without RAG:

from nom.doc import extract
from nom.llm import Ollama

result = extract(
    "hop_dong.pdf",
    schema={"so_hop_dong": str, "ngay_ky": "date", "tong_gia_tri": "amount_vnd"},
    llm=Ollama(model="qwen3:8b"),
)

Text utilities without the rest:

from nom.text import normalize, fix_diacritics, word_tokenize

clean = normalize("Hợp đồng số 02/HĐ/2025")

# Three diacritic backends — pick by your accuracy / dependency budget:

# (1) zero-dep rule path — 41 % word acc, < 1 ms
fixed_rule = fix_diacritics("Hop dong nay duoc lap")

# (2) public Apache T5 (recommended) — 97.81 % word acc, ~150 ms on GPU
#     pip install "nom-vn[diacritic-hf]"
from nom.text.diacritic_models import HFDiacriticModel
fixed = fix_diacritics("Hop dong nay duoc lap", model=HFDiacriticModel())

# (3) pass any LLM adapter — 87-95 % depending on model
from nom.llm import Ollama
fixed_llm = fix_diacritics("Hop dong nay duoc lap", llm=Ollama("gemma3:4b"))

toks  = word_tokenize("Thành phố Hồ Chí Minh")    # ["Thành phố", "Hồ Chí Minh"]

---

Install

pip install nom-vn                            # text + chunking + retrieve + rag (no I/O deps)
pip install "nom-vn[doc]"                     # + PDF / Office / OCR parsers
pip install "nom-vn[embeddings]"              # + sentence-transformers
pip install "nom-vn[llm]"                     # + httpx for Ollama / OpenAI-compat
pip install "nom-vn[chat]"                    # + FastAPI / uvicorn + everything above
pip install "nom-vn[all]"                     # the lot

OCR (image / scanned PDF) needs Tesseract installed system-wide:

# Debian/Ubuntu
sudo apt install tesseract-ocr tesseract-ocr-vie
# Conda
conda install -c conda-forge tesseract
# macOS
brew install tesseract tesseract-lang

nom serve auto-detects the Tesseract binary + finds vie.traineddata; if absent, image uploads index as zero chunks rather than failing.

---

Architecture in one line

7 layers (Primitives / Models / Retrieval / RAG / Storage / Application / Deployment), every meaningful boundary is a typing.Protocol. Local single-process today; the cloud path replaces three Protocol implementations and changes nothing in the application layer.

See docs/architecture.md for the full layered model, Protocol seam table, and scaling-path reference.

---

Models & datasets we publish

Apache-2.0-friendly artifacts on Hugging Face Hub (cite Viet-Anh Nguyen and Neural Research Lab per the repo's citation block):

• 🤗 nrl-ai/vn-diacritic-vit5-base — register-balanced ViT5 fine-tune for diacritic restoration
• 🤗 nrl-ai/vn-diacritic-eval — 4-register diacritic evaluation grid (1,227 sentence pairs)
• 🤗 nrl-ai/vn-diacritic-train — 500K Wikipedia + 150K NFC-fixed VN news training pairs

Full per-task detail: docs/tasks/diacritic-restoration.md.

---

Documentation

• docs/readme.md — docs index pointing at all per-task pages
• docs/tasks/ — one page per task (public landscape + our pipeline + trained models + datasets + results)
• docs/architecture.md — the 7-layer model, Protocol seams, scaling path, anti-architecture rules
• docs/pipeline.md — the document-extraction pipeline end-to-end with per-stage picks
• docs/benchmark.md — measured numbers per module (the receipts behind every "Recommended stack" row above)
• docs/recipes.md — task-oriented "I want X, do Y" cookbook with copy-paste code
• docs/release.md — how to cut a PyPI release (Trusted Publishing via GitHub Actions, no tokens)
• docs/training_plan_2026q2.md — when to fine-tune vs adopt off-the-shelf, per component, with cost estimates
• docs/sota_vn_2026q2.md — SOTA local LLM / embedding / OCR for Vietnamese (April 2026 snapshot, every claim cited)
• docs/oss_landscape_2026q2.md — OSS local-AI / RAG landscape: patterns to steal, traps to avoid
• benchmarks/ — reproducible measurement scripts (perf + retrieval + accuracy)
• CONTRIBUTING.md — dev setup, PR rules
• CHANGELOG.md — version history

---

License

Apache 2.0. Fine-tune, redistribute, commercialize freely. Please keep attribution.

Citation

@software{nom2026,
  title  = {Nôm: an open Python toolkit for Vietnamese AI applications},
  author = {Nguyen, Viet-Anh and {Neural Research Lab}},
  year   = {2026},
  url    = {https://nrl.ai/nom},
  note   = {Apache 2.0}
}

Built by

Neural Research Lab — open-source AI tooling. Edge inference, private assistants, training, labeling.