Rishe (ریشه)

Fast Persian NLP and morphology for Python. Prebuilt wheels, no Python dependencies, and the base pipeline needs no model downloads.

Install

pip install rishe

Python 3.9+. Linux (glibc and musl), macOS and Windows wheels are published.

Quickstart

from rishe import Pipeline

pipe = Pipeline()
doc = pipe("اون داره تو خونه کتاب میخونه، چیه؟")

doc.tokens       # ['آن', 'دارد', 'تو', 'خانه', 'کتاب', 'می‌خواند', '،', 'چیست', '؟']
doc.lemmas       # ['آن', 'داشت', 'تو', 'خانه', 'کتاب', 'خواند', '،', 'چیست', '؟']
doc.formal_text  # 'آن دارد تو خانه کتاب می‌خواند، چیست؟'

pipe.normalize, word_tokenize, sent_tokenize, lemmatize, stem, conjugate, spell_correct and the rest are methods on the same object. pipe(text) rewrites colloquial forms; word_tokenize tokenizes the surface text without rewriting.

Class-based API

The same engine is available as small, reusable classes:

from rishe import (
    Lemmatizer,
    Normalizer,
    SentenceTokenizer,
    Stemmer,
    TokenSplitter,
    WordTokenizer,
    sent_tokenize,
    word_tokenize,
)

Normalizer().normalize("مي كنم")             # 'می‌کنم'
WordTokenizer().tokenize("رفته است")         # ['رفته_است']
SentenceTokenizer().tokenize("یک. دو.")
Lemmatizer().lemmatize("می‌روم")              # 'رفت#رو'
Stemmer().stem("کتاب‌ها")                    # 'کتاب'
TokenSplitter().split_token_words("بهش")     # [('به', 'او')]

word_tokenize("رفته است")                    # ['رفته_است']
sent_tokenize("یک. دو.")

No lexicon paths are needed: the classes use Rishe's compiled-in lexicons. WordTokenizer accepts the same options as the pipeline tokenizer (join_verb_parts, replace_emails, replace_links, and so on).

Features

• Normalization, tokenization, sentence splitting and lemmatization.
• Stemming, conjugation, inflection, clitic splitting, spell correction, stopwords and ezafe detection.
• Static fastText/word2vec embeddings with sentence pooling.
• Optional POS, NER and learned ezafe model packs.

Feature tour

Morphology and utilities

pipe.stem("کتاب‌ها")                      # 'کتاب'
pipe.conjugate("رفت")["present"][:3]      # ['می‌روم', 'می‌روی', 'می‌رود']
pipe.comparative("بزرگ")                  # 'بزرگ‌تر'
pipe.superlative("بزرگ")                  # 'بزرگ‌ترین'
pipe.plural("کتاب")                       # 'کتاب‌ها'
pipe.possessive("خانه", 0)                # 'خانه‌ام'
pipe.split_token("بهش")                   # ['به', 'او']
pipe.spell_correct("سسلام بر ششما")       # 'سلام بر شما'
pipe.tokenize_spans("سلام دنیا")          # [('سلام', 0, 4), ('دنیا', 5, 9)]

Normalization and masking

normalize_stages applies individual operators in the order you list them; mask_stages removes or masks URLs, emails, mentions, hashtags, HTML, digits, diacritics, punctuation, stopwords, offensive words and non-Persian text.

pipe.normalize_stages("﷽ 1𝟮3٤٥⓺", ["arabic_unicode", "digits"])
# 'بسم الله الرحمن الرحیم ۱۲۳۴۵۶'

pipe.mask_stages("سلام @user، به https://rishe.dev یا info@rishe.dev بنویس.",
                 ["url", "email", "mention"])
# 'سلام   به <URL> یا <EMAIL> بنویس.'

Utilities, keywords and transliteration

pipe.number_to_words(1404)                 # 'یک هزار و چهارصد و چهار'
pipe.ngrams("این یک متن", 1, 2)             # ['این', 'یک', 'متن', 'این یک', 'یک متن']
pipe.persianize("فایل را با کامپیوتر باز کن")  # 'پرونده را با رایانه باز کن'
pipe.rake(text, top_n=5)
pipe.textrank(text, top_n=5)
pipe.to_tajik("خانه")                      # 'хона'
pipe.to_persian("хона")                    # 'خانه'

keyboard_noise, ocr_noise and whitespace_noise add reproducible typing, OCR and spacing noise; pass seed= for deterministic output.

Tokenizer options

pipe.word_tokenize_with("رفته است", join_verb_parts=True)   # ['رفته_است']
pipe.word_tokenize_with("info@a.co", replace_emails=True)   # ['EMAIL']

Options include join_verb_parts, join_abbreviations, separate_emoji, replace_links, replace_ids, replace_emails, replace_numbers and replace_hashtags.

Corpora

from rishe import ConlluReader, PeymaReader, PlainTextReader

for sentence in ConlluReader("data/corpora/fa_perdt-ud-test.conllu"):
    print(sentence.text, sentence.tokens[0].lemma)

ConlluReader handles CoNLL-U, PeymaReader reads the PEYMA format and PlainTextReader reads one sentence per line.

Model packs

POS, NER and ezafe are separate, checksum-verified downloads. They run inside the package without ONNX Runtime or a Python ML stack.

rishe hub pull pos-compact
rishe hub pull ner-compact
rishe hub pull ezafe-compact

from rishe import Pipeline, hub

pipe = Pipeline(
    pos_pack=str(hub.path_pack("pos-compact")),
    ner_pack=str(hub.path_pack("ner-compact")),
    ezafe_pack=str(hub.path_pack("ezafe-compact")),
)

for token in pipe.pos("کتاب‌های خوب را به دوستانم می‌دهم."):
    print(token.text, token.tag, token.start, token.end)

for entity in pipe.ner("سرلشگر فیروزآبادی به پادشاه عربستان گفت."):
    print(entity.text, entity.label, entity.start, entity.end)

for token in pipe.ezafe("کتابخانه مرکزی دانشگاه شریف"):
    print(token.text, token.tag, token.start, token.end)

pipe.pos_batch(["کتاب‌های خوب", "خوب است"])
pipe.ner_batch(["فیروزآبادی گفت.", "عربستان جای خوبی است."])
pipe.ezafe_batch(["کتابخانه مرکزی", "دانشگاه شریف"])

TaggedToken has text, tag, start and end; Entity has text, label, start and end. Start/end are character offsets. The lower-level ModelPack class is still available when you want one task:

from rishe import ModelPack

pack = ModelPack(str(hub.path_pack("pos-compact")))
pack.tag_tokens("کتاب‌های خوب")   # typed TaggedToken list
pack.tag_words(["کتاب‌های", "خوب"])  # tuple output

Embeddings

rishe hub pull hazm-fasttext-300   # optional 2.3 GB static embedding file

from rishe import Embeddings, hub

emb = Embeddings(str(hub.path("hazm-fasttext-300")))
emb.dim, len(emb)                      # vector size, vocabulary size
emb.vector("کتاب")                     # list[float] or None
emb.sentence_vector("این کتاب خوب است") # mean of in-vocab token vectors
emb.most_similar("کتاب", 5)            # [(word, cosine), ...]

CLI

rishe normalize "مي كنم"
rishe tokenize "سلام دنیا" --json
rishe pos "کتاب‌های خوب را به دوستانم می‌دهم."
rishe ner --json "سرلشگر فیروزآبادی به پادشاه عربستان گفت."
rishe ezafe "کتابخانه مرکزی دانشگاه شریف"

Docs

• API
• CLI
• Benchmarks
• Model-pack benchmarks
• GitHub repository

License

Dual-licensed under Apache-2.0 or MIT, at your option. Lexicon attributions are in NOTICE.md.

Built by Mahdi Alikhah.