Hezar: one Model.load for Persian sentiment, OCR, speech and captions

The same three lines across eight different tasks

Hezar means thousand in Persian, and the library's pitch is breadth: bring together the best available work on AI for Persian and make it callable in a couple of lines. The name of the class doing the work is `Model`, and the pattern is always the same three steps. Load a checkpoint by Hub identifier, pass inputs, print the output.

The models span more than text. The Hub identifiers in the README cover sentiment analysis with `hezarai/bert-fa-sentiment-dksf`, part of speech tagging with `hezarai/bert-fa-pos-lscp-500k`, named entity recognition with `hezarai/bert-fa-ner-arman`, mask filling with `hezarai/roberta-fa-mask-filling`, speech recognition with `hezarai/whisper-small-fa`, pre-OCR text detection with `hezarai/CRAFT`, Persian OCR with `hezarai/crnn-base-fa-v2`, licence plate recognition with `hezarai/crnn-fa-license-plate-recognition-v2`, and image captioning with `hezarai/vit-roberta-fa-image-captioning-flickr30k`.

A text example returns a label and a score. An audio example takes a file path. An image example takes an image path, and for text detection the utilities load the image, run prediction, draw the boxes and show the result. The point is that you do not write a different pipeline per task, which is the problem this library exists to remove.

uv, pip or a clone, with extras that actually matter

The library is on PyPI and supports Python 3.10 and later according to the README.

pip install hezar
uv add hezar

Because Hezar is a collection of models and tools rather than one thing, the install variants are the interesting part. The extras are named `all`, `nlp`, `vision`, `audio` and `embeddings`, and `all` is how you get the lot.

pip install hezar[all]

There is a documented path from source too, which is the one to use if you intend to read the code rather than just call it.

git clone https://github.com/hezarai/hezar.git
cd hezar

From there the README offers `uv sync` or `pip install .`.

One inconsistency is worth flagging before you plan a deployment. The README says Python 3.10 and later, while `pyproject.toml` sets `requires-python = ">=3.11.0"`. Trust the packaging metadata over the prose, and expect 3.11 as the floor.

What the extras pull in, and why torch is not optional

The base dependency list in `pyproject.toml` is short and heavy at once: `torch>=2.1.0`, `omegaconf>=2.3.0`, `transformers>=4.30.0`, `tokenizers>=0.13.0` and `huggingface_hub`. PyTorch is not behind an extra. A project that only wants to run a CRNN OCR model still installs the framework the training story needs, which is the main practical cost of the unified interface.

The extras are where the modality-specific libraries live. `nlp` adds `seqeval`, `jiwer`, `nltk` and `rouge_score` for sequence labelling and metric computation. `audio` adds `soundfile` and `librosa` alongside `jiwer`. `vision` adds `pillow`, `torchvision` and `opencv-python`. `trainer` adds `accelerate`, `pandas` and `tensorboard`, which is the group you want if you are fine-tuning rather than inferring. `embeddings` adds `gensim` below version 5 and `scipy`, and `dev` adds pytest, ruff and the Sphinx documentation stack with `myst-parser`, `furo` and `sphinx-copybutton`.

So the practical rule is this: if you are only running inference, install the single extra for your modality and accept the base layer. If you are training, the `trainer` group plus the base dependencies is the whole cost. The README's own list of supplementary tooling for deployment, benchmarking and optimisation sits on top of these.

Speech and vision through the same interface

Two examples show how much variety hides behind the uniform call. Speech recognition loads `hezarai/whisper-small-fa` and passes an mp3 path.

from hezar.models import Model

model = Model.load("hezarai/whisper-small-fa")
transcripts = model.predict("examples/assets/speech_example.mp3")
print(transcripts)

Image captioning loads `hezarai/vit-roberta-fa-image-captioning-flickr30k` and passes a jpg path to the same `predict` method, and licence plate recognition loads `hezarai/crnn-fa-license-plate-recognition-v2` with a printed note that Persian digits and letters may not render correctly in a terminal. That caveat is small but real: the library returns the text correctly and the console may not display it.

Text detection is the one example that shows the surrounding helpers, importing `load_image`, `draw_boxes` and `show_image` from `hezar.utils` alongside `Model`. The model is `hezarai/CRAFT`, which detects regions rather than reading them, and the pipeline is load image, predict, draw the returned boxes, show.

The README's task list also mentions word embeddings, tokenizers and feature extractors as included tools, which matters if you are building a preprocessing pipeline rather than a single prediction. Everything is organised around the Hub organisation `hezarai`, so the checkpoints can be loaded with plain Transformers tooling too if Hezar itself turns out to be the wrong shape for your problem.

A 1.0.0 release, then a quiet patch of history

Hezar reached 1.0.0, and the release history shows exactly how: 1.0.0b0 on 2026-03-06, 1.0.0b1 on 2026-03-07, and 1.0.0 on 2026-03-09, all within four days. `pyproject.toml` carries the same version, 1.0.0, and a development status classifier of Production/Stable. None of the three release notes has any body text, so there is no changelog to read on GitHub for what changed between betas.

The last push to the repository was on 2026-03-09, the same day as the final release. That is worth stating plainly rather than glossing: the package is a recent 1.0 rather than a project with a long public history, and the release feed will not tell you how it is progressing. For anything you intend to depend on, the practical check is the Hugging Face side, where the checkpoints live and where model updates can land independently of the library.

The positive side of a small history is that the API is not carrying decades of compatibility baggage. There is no deprecation shim to read past.

Hezar next to plain Transformers

The honest comparison is with loading a checkpoint yourself. With `transformers` you would pick the right class for the architecture, build the tokenizer, write the post-processing for the model's output format, and handle the Persian specifics such as normalising text or mapping character offsets yourself. Hezar moves all of that behind `Model.load` and `predict`, and hosts the checkpoints so the weights are one identifier away.

What you give up is control over the internals. If you need to change the tokenizer, swap in a different checkpoint, apply a domain fine-tune, or squeeze out the last increment of inference speed, you are inside the library rather than beside it. The README does describe a task-based model interface as more convenient for general users, which is an honest statement of the trade: convenience for the common case in exchange for a ceiling on the unusual one.

The documentation is split between the repository and the hosted site. `docs/` builds the Getting Started, Quick Tour, Tutorials, Developer Guides, Contribution and Reference API pages, and the README links each one, including a Developer Guides entry on the library's own architecture. `examples/` is organised by purpose, with separate directories for embedding, inference, preprocessing and training, plus `notebooks/` at the root. Between those and the models on the Hub, you can answer most questions without reverse engineering anything.

Editorial conclusion

Hezar earns its place when you need a working Persian baseline in under ten lines and would rather not assemble a tokenizer, a checkpoint and a post-processing path yourself. The interface is genuinely small, the checkpoints are on Hugging Face under the hezarai organisation, and the licence is permissive. Two things decide whether it fits. First, PyTorch and Transformers are base dependencies rather than extras, so an OCR-only project still installs the training stack, and the extras list does not include an inference-only variant. Second, the release history is quiet: 1.0.0 shipped on 2026-03-09 after two betas that week, and the last push to the repository was on 2026-03-09 as well. For a library you plan to depend on, check whether the checkpoints you need are still current on the Hub, and start from the Quick Tour page to see which task you would actually be calling.

Frequently asked questions

Official sources

1. hezarai/hezar on GitHub
2. License: Apache-2.0
3. Project website
4. README
5. Releases