tmquan/congbobanan-toaan-gov-vn

---
language:
- vi
license: cc-by-4.0
pretty_name: "Công bố bản án — Vietnamese Court Judgments"
size_categories:
- 1M<n<10M
task_categories:
- text-classification
- text-retrieval
- sentence-similarity
- feature-extraction
tags:
- legal
- vietnamese
- court-judgment
- ban-an
- quyet-dinh
- supreme-court
configs:
- config_name: parse
data_files: "data/parse-*.parquet"
- config_name: extract
data_files: "data/extract-*.parquet"
- config_name: embed
data_files: "data/embed-*.parquet"
- config_name: reduce
data_files: "data/reduce-*.parquet"
---

# Công bố bản án — Vietnamese Court Judgments

Document-level mirror of the Vietnamese **Cổng công bố bản án** portal
at [`congbobanan.toaan.gov.vn`](https://congbobanan.toaan.gov.vn) (Tòa
án nhân dân tối cao — Supreme People's Court of Vietnam). Each case is
provided as a **raw PDF**, **parsed markdown**, a **structured JSON
record** (sidebar metadata + generic NER + statute references), a
**2 048-dim dense embedding**, and a 2-D projection
(**PCA / t-SNE / UMAP + HDBSCAN cluster id**).

The corpus is produced end-to-end by the
[`packages/datasites/congbobanan`](https://github.com/) NeMo Curator
pipeline:

```
download → parse → extract → embed → reduce
```

The corpus is a sibling of [`tmquan/anle-toaan-gov-vn`](https://huggingface.co/datasets/tmquan/anle-toaan-gov-vn):
same pipeline, same shard convention, same field schema for the
shared columns (`doc_name`, `text`, `text_hash`, `embedding`, ...);
congbobanan adds the portal-specific sidebar columns
(`doc_type`, `ban_an_so`, `ngay`, `toa_an_xet_xu`, `loai_vu_viec`,
`cap_xet_xu`, `quan_he_phap_luat`, ...) and skips the án-lệ-only
precedent fields. Consumers wanting both corpora can union the two on
the shared subset of columns without any column-by-column
reconciliation.

## Quick start

The four configurations mirror the four pipeline stages 1-to-1; pick
the one matching the granularity you need:

```python
from datasets import load_dataset

# parse — markdown body of every judgment under field `text`
parse = load_dataset("tmquan/congbobanan-toaan-gov-vn", "parse", split="train")
# extract — `text` + sidebar metadata + structured legal extraction (entities, statute refs)
extract = load_dataset("tmquan/congbobanan-toaan-gov-vn", "extract", split="train")
# embed — 2 048-dim dense vectors
embed = load_dataset("tmquan/congbobanan-toaan-gov-vn", "embed", split="train")
# reduce — pre-computed PCA / t-SNE / UMAP coordinates + HDBSCAN cluster id
reduce = load_dataset("tmquan/congbobanan-toaan-gov-vn", "reduce", split="train")

print(parse[0]["doc_name"], parse[0]["text"][:80]) # '1000023' '## Page 1\n\n…'
print(extract[0]["loai_vu_viec"], extract[0]["cap_xet_xu"])
print(len(embed[0]["embedding"])) # 2048
print(reduce[0]) # pca_x/y, tsne_x/y, umap_x/y, cluster_id
```

To download a slice of the raw artefacts:

```python
from huggingface_hub import snapshot_download

# Just the parsed markdown
snapshot_download(
repo_id="tmquan/congbobanan-toaan-gov-vn", repo_type="dataset",
allow_patterns=["raw/md/*"], local_dir="congbobanan/md",
)

# Specific case ids
snapshot_download(
repo_id="tmquan/congbobanan-toaan-gov-vn", repo_type="dataset",
allow_patterns=[f"raw/pdf/{cid}.*" for cid in (1000023, 1000034)],
local_dir="congbobanan/pdf",
)
```

## Configurations

Each config below is a **sharded parquet bundle** with at most
**10 000 rows per shard**, named
`<stage>-<NNNNN>-of-<KKKKK>.parquet`. Sharding is deterministic on
`doc_name` (the zero-padded `case_id`) so re-publishes don't shuffle
documents across shards. The convention matches
[`tmquan/anle-toaan-gov-vn`](https://huggingface.co/datasets/tmquan/anle-toaan-gov-vn).

| Config | Stage | Key columns |
|--- |--- |--- |
| `parse` | parse | `doc_name`, `case_id`, `source`, `detail_url`, `pdf_path`, **`text`**, `num_pages`, `char_len`, `confidence`, `parser_model`, `parsed_at`, `text_hash` |
| `extract` | extract | `doc_name`, `case_id`, `text_hash`, **`text`**, `entities`, `relations`, `statute_refs`, `doc_type`, `ban_an_so`, `ngay`, `ten_ban_an`, `ngay_cong_bo`, `quan_he_phap_luat`, `cap_xet_xu`, `loai_vu_viec`, `toa_an_xet_xu`, `ap_dung_an_le`, `dinh_chinh`, `thong_tin_vu_viec`, `tong_binh_chon`, `luot_xem`, `luot_tai`, `pdf_filename` |
| `embed` | embed | `doc_name`, `case_id`, `text_hash`, `embedding` (2 048-d float), `embedding_dim`, `embedding_model_id`, `embedding_chunks_used`, `embedding_chunking` |
| `reduce` | reduce | `doc_name`, `case_id`, `text_hash`, `pca_x/y`, `tsne_x/y`, `umap_x/y`, `cluster_id` |

`text` is the markdown body produced by the `parse` stage and copied
verbatim into the `extract` stage. `text_hash` is a deterministic
content hash that joins every config back to the per-doc shards under
`raw/`.

### Sidebar columns (extract config)

Promoted from the portal's right-side panel and parsed by
`CongbobananDocumentExtractor`:

| Field | Type | Description |
|--- |--- |--- |
| `doc_type` | string | `"ban-an"` (Bản án / judgment) or `"quyet-dinh"` (Quyết định / decision). |
| `ban_an_so` | string | Case number, e.g. `03/2022/DSST`. |
| `ngay` | string | Judgment date in site format (`dd/mm/yyyy`). |
| `ten_ban_an` | string | Human-readable case title. |
| `ngay_cong_bo` | string | Publication date (`dd.mm.yyyy`). |
| `quan_he_phap_luat` | string | Legal relationship / subject-matter label. |
| `cap_xet_xu` | string | Procedural level (`Sơ thẩm` / `Phúc thẩm` / `Giám đốc thẩm` / ...). |
| `loai_vu_viec` | string | Case type (`Dân sự` / `Hình sự` / `Hành chính` / ...). |
| `toa_an_xet_xu` | string | Issuing court name (full Vietnamese form). |
| `ap_dung_an_le` | string | Applied precedent, if any. |
| `dinh_chinh` | string | Corrections (`đính chính`). |
| `thong_tin_vu_viec` | string | Case info / summary blurb. |
| `tong_binh_chon` | string | Precedent-vote count (raw site string). |
| `luot_xem` | int64 | View counter. |
| `luot_tai` | int64 | Download counter. |
| `pdf_filename` | string | Original server-side PDF filename. |

## Repo layout

```
README.md this dataset card
notebook.ipynb end-to-end EDA notebook (Plotly, LaTeX-style theme)
data/
parse-<NNNNN>-of-<KKKKK>.parquet `text` + parse metadata
extract-<NNNNN>-of-<KKKKK>.parquet `text` + sidebar + generic NER
embed-<NNNNN>-of-<KKKKK>.parquet 2 048-d dense vectors
reduce-<NNNNN>-of-<KKKKK>.parquet PCA / t-SNE / UMAP + cluster id
assets/ static PNGs embedded in this README
raw/
pdf/<case_id>.pdf original scraped PDF
pdf/<case_id>.html cached detail HTML (iterator input)
pdf/<case_id>.url source detail URL
md/<case_id>.md parsed markdown body
md/<case_id>.meta.json parser metadata sidecar
jsonl/<task_id>.jsonl Extractor output (mirror of pipeline)
```

## Pipeline summary

| Stage | Reads | Writes | Tooling |
|--- |--- |--- |--- |
| `download` | integer IDs `[start_id..end_id]` | `pdf/<case_id>.pdf` + `.html` / `.url` | aiohttp scraper (`CongbobananDocumentDownloader`) |
| `parse` | `pdf/*.pdf` | `md/<case_id>.md` + `<case_id>.meta.json` | `nvidia/nemoretriever-parse` |
| `extract` | `md/*.md` | `jsonl/<task_id>.jsonl` | rule + LLM extractor (sidebar parser + generic NER) |
| `embed` | `jsonl/*.jsonl` | `parquet/embeddings/<task_id>.parquet` | `nvidia/llama-nemotron-embed-1b-v2` (2 048-d, sliding window) |
| `reduce` | `parquet/embeddings/*.parquet` | `parquet/reduced/<task_id>.parquet` | scikit-learn PCA + t-SNE, umap-learn UMAP, HDBSCAN |

## Access caveat: VN egress required

`congbobanan.toaan.gov.vn` refuses TLS handshakes from non-Vietnamese
source IPs with `ERR_CONNECTION_CLOSED`. Reproducing the `download`
stage requires a Vietnamese VPS or a VN SOCKS5 / HTTPS proxy
(`cfg.scraper.proxy` or `HTTPS_PROXY`). Reading the published parquet
bundle from the Hub has no such restriction.

## How to reproduce

```bash
# from the monorepo root
pip install -r packages/datasites/congbobanan/requirements.txt
python data/congbobanan.toaan.gov.vn/_to_hf.py \
--repo tmquan/congbobanan-toaan-gov-vn
```

`_to_hf.py` does three things in order:

1. **Consolidate** every per-doc shard under `parquet/embeddings/`,
`parquet/reduced/` and `jsonl/` into the four ZSTD parquet bundles
in `data/`, each capped at **10 000 rows per shard** and named
`<stage>-<NNNNN>-of-<KKKKK>.parquet`. Rows are deterministically
sorted on `doc_name` before sharding so re-runs produce
byte-identical shard membership. DuckDB drives the `embed` /
`reduce` consolidation because PyArrow ≥ 17 occasionally fails on
the per-doc embedding shards with
`Repetition level histogram size mismatch`.
2. **Render** the static plot PNGs in `assets/` and the `_stats.json`
snapshot embedded in this card (delegates to `_render_assets.py`).
3. **Upload** every artefact to the Hub at the right path. Importantly
it uses `HfApi.upload_folder(path_in_repo=...)` — never
`hf upload-large-folder`, which silently puts everything at the
repo root because it has no `--path-in-repo` flag.

Sub-steps can be skipped with `--skip-consolidate`, `--skip-assets`,
`--no-upload`. The heavy `raw/pdf/` bucket can be skipped with
`--skip-raw-pdf` during iteration (only the `data/` parquets and the
`raw/jsonl` + `raw/md` mirrors are needed for the
`load_dataset(...)` path).

## Source & license

The judgments are public legal documents published by the Supreme
People's Court of Vietnam at <https://congbobanan.toaan.gov.vn>.
Litigant identifiers in the source are already abbreviated by the
publisher (e.g. *Nguyễn Thị T*). This redistribution is offered under
**CC-BY 4.0** with attribution to `congbobanan.toaan.gov.vn`. Users
are responsible for complying with the original publisher's terms
when reusing the raw PDFs.

## Citation

If you use this dataset, please cite both the original portal and
this redistribution:

```bibtex
@misc{congbobanan_toaan_2026,
title = {Vietnamese Court Judgments (congbobanan.toaan.gov.vn)},
author = {TMQuan},
year = {2026},
howpublished = {\url{https://huggingface.co/datasets/tmquan/congbobanan-toaan-gov-vn}},
note = {Document-level mirror of the Vietnamese court-judgment portal, with sidebar metadata, hierarchical structure layer, and 2 048-d dense embeddings.}
}

@misc{congbobanan_toaan_source_2026,
title = {Vietnamese Court Judgments},
author = {{Công bố bản án — Tòa án nhân dân tối cao}},
year = {2026},
howpublished = {\url{https://congbobanan.toaan.gov.vn/}},
note = {Official portal for Vietnamese court judgments (bản án) + decisions (quyết định), published by the Supreme People's Court (Tòa án nhân dân tối cao).}
}
```