# just-vbpe

A lightweight Python library implementing a Vietnamese Byte Pair Encoding (BPE) tokenizer.
`just-vbpe` allows you to train a BPE vocabulary and encode Vietnamese text efficiently, with simple APIs and no external ML dependencies.

---

## Introduction

`just-vbpe` is a small and easy-to-use library based on the idea of **Byte Pair Encoding (BPE)**.
It focuses on Vietnamese text tokenization, helping you:

* Build a BPE vocabulary from scratch
* Encode text into subword tokens
* Save and load vocabulary
* Integrate tokenizer into NLP pipelines

This library is designed for developers, researchers, or anyone working with Vietnamese NLP.

---

## Features

* Train a BPE vocabulary from raw Vietnamese text
* Encode sentences using your custom-trained vocab
* Save & load vocab using JSON or pickle
* Efficient implementation using Counter, defaultdict, and toolz
* Minimal dependencies

---

## Installation

Install via pip:

```bash
pip install just-vbpe
```

Or install from source:

```bash
git clone https://github.com/justinnguyendsa/just-vbpe.git
cd just-vbpe
pip install .
```

---

## Quick Start

### **1. Train a BPE vocabulary**

```python
from just_vbpe import VBPE

sample_train_texts = """Trong thời đại công nghệ 4.0, việc học lập trình và xử lý dữ liệu trở nên quan trọng hơn bao giờ hết. Các nhà phát triển cần nắm vững kiến thức về ngôn ngữ lập trình, thuật toán và trí tuệ nhân tạo để tạo ra những sản phẩm chất lượng và hữu ích cho người dùng.
Ngôn ngữ tự nhiên là một lĩnh vực phức tạp trong trí tuệ nhân tạo. Việc phân tích văn bản tiếng Việt đòi hỏi các phương pháp xử lý từ vựng, tách từ và chuẩn hóa dữ liệu để mô hình học máy có thể hiểu và xử lý thông tin một cách chính xác.
Mỗi ngày, hàng triệu người sử dụng các ứng dụng điện thoại và web để trao đổi thông tin, học tập và giải trí. Những dữ liệu này cung cấp nguồn thông tin phong phú giúp các nhà nghiên cứu phát triển các mô hình dự đoán, phân loại và gợi ý nội dung phù hợp.
Học máy là công cụ mạnh mẽ để giải quyết nhiều vấn đề thực tiễn trong đời sống, từ dự đoán thời tiết, nhận diện hình ảnh, đến dịch máy và chatbot hỗ trợ khách hàng. Việc xây dựng bộ dữ liệu chất lượng cao đóng vai trò quan trọng trong thành công của các mô hình này.
Thư viện just-vbpe giúp bạn tạo vocab từ văn bản tiếng Việt và encode các câu một cách hiệu quả. Bằng cách áp dụng thuật toán Byte Pair Encoding, thư viện này có thể giảm số lượng token nhưng vẫn giữ nguyên ý nghĩa của văn bản, giúp tiết kiệm bộ nhớ và tăng tốc độ xử lý."""

vbpe = VBPE(word_vocab_size=800, bpe_vocab_size=200)
vbpe.fit(sample_train_texts)

vbpe.save()
```

---

### **2. Encode Vietnamese text**

```python
from just_vbpe import VBPE

vbpe = VBPE.load()

sample_test_text = """Just-vbpe là một thư viện Python giúp encode văn bản tiếng Việt bằng thuật toán Byte Pair Encoding (BPE)
Bạn có thể sử dụng nó để tokenize các câu, xây dựng vocab, và thử nghiệm với các mô hình NLP."""

tokens = vbpe.tokenize(sample_test_text)
encoded = vbpe.encode(sample_test_text)
decoded = vbpe.decode(encoded)

print(f'Tokens: {tokens}')
print(f'Encoded: {encoded}')
print(f'Decoded: {decoded}')
```

---

## License

This project is released under the **MIT License**.
See the `LICENSE` file for details.

---

## Author

**Justin Nguyen**
Maintainer of `just-vbpe`.

---

## Contribute

Issues and pull requests are welcome!
Feel free to open PRs to improve
