persian-rag demo

persian-rag demo

Try Persian text normalization and BM25, dense or hybrid search over 34 sample passages, all running in your browser through Pyodide. No server, no model download, no API key.

Made by sadrmanesh on Hugging Face. These notes are Mindket's, written from its Space page and README; the app's own files and license are on Hugging Face.

About

What it is: This Space is a small browser demo of persian-rag, a Python toolkit for retrieval-augmented generation that puts Persian first. The library needs no other packages, so the demo runs it directly in your browser through Pyodide, with no server.

The demo covers two things. It searches 34 bundled Persian passages, and it normalizes Persian text. Answer generation is left out on purpose.

Who it suits: It suits people who build search or question answering for Persian text and want to try the library first, and developers who want to see Python run inside a static page.

Industry | Who uses it | How they use it | Example
Natural language processing | NLP engineers | Compare keyword, dense and hybrid search on Persian passages | Seeing how reciprocal rank fusion changes the ranking
Search and knowledge tools | Search developers | Test spelling variant rewriting | Matching variants of the same Persian word
Research | Language researchers | Inspect which characters normalization changes | Checking how Arabic and Persian letter forms are unified
Education | Students | Try the demo with nothing to install | Learning how retrieval works before adding a model

Skip it if you want a full question answering system, since the demo leaves answer generation out.

Where to use it: The demo runs in these places.

• A web browser, on the Space's page at Hugging Face
• A web browser on Windows, macOS or Linux, from a local copy served by a static file server
• Your own Python code, through the persian-rag package

Use case | Who | What they get back
Search Persian passages | Developers | Ranked results from BM25, dense or hybrid search
Normalize Persian text | Researchers | Cleaned text with the changed code points listed
Try spelling variants | Search builders | Matches across alternate spellings

How to set it up: Online you only need a browser. A local copy needs these.

• Python and pip, for the hf download command
• A web browser
• Any static file server, such as the one built into Python

1. Install the huggingface_hub package.
2. Download the Space's files into a folder with the hf command.
3. Move into that folder.
4. Serve the folder with a static file server.
5. Open the served page on port 8000 in a web browser.

pip install -U huggingface_hub
hf download sadrmanesh/persian-rag-demo --repo-type space --local-dir persian-rag-demo
cd persian-rag-demo
python -m http.server

If you want the library in a project of your own, this command installs release 0.4.0.

pip install persian-rag==0.4.0

How to use it: Open the Space's page and choose a search mode, then type a Persian query. You can switch spelling variant rewriting on or off, and you can run the normalization on a piece of text to see which code points changed.

Tool | What it does
BM25 | Ranks passages by how well their words match the query
Dense | Ranks passages by embedding similarity, though the demo's scores are not semantic
Hybrid | Combines the two rankings with reciprocal rank fusion
Variant rewriting | Lets one word match under its alternate spellings, such as two common forms of the city name Tehran
Normalization | Unifies Arabic Yeh and Kaf, digits, half-spaces and punctuation

Example: You type a Persian query and choose hybrid search. The page returns the best matching passages from the 34 bundled ones, and with variant rewriting on, it also finds passages that spell a word another way.

For newcomers and experts: If you are new, open the Space's page and try the normalization first. It shows you how different keyboards can type the same Persian letter in different ways.

If you know the field, the demo embeds text with HashingEmbedder, which works offline. Its dense scores therefore carry no meaning about semantics. On a real corpus, the README points to SentenceTransformerEmbedder, whose default model from 0.4.0 is multilingual-e5-small with the E5 prefixes added automatically, or to an OpenAI-compatible embedder.

Open the page and Pyodide loads
Type a Persian query or text
The library searches or normalizes it
Results show with the changes listed

Good to know: The corpus and questions come from the persian-rag retrieval benchmark. The file demo.py holds the Python part of the demo, and a built 0.4.0 package file sits in the repository.

• License: MIT
• Cost to run: none named, and the demo asks for no key or model files
• Data it reaches: the bundled passages and benchmark data in the repository
• Not for: generating answers, since the demo leaves answer generation out

On Hugging Face, 13 November 2026

• Likes: 1
• Built with: static
• License: mit

Links

• Space: https://huggingface.co/spaces/sadrmanesh/persian-rag-demo
• Files: https://huggingface.co/spaces/sadrmanesh/persian-rag-demo/tree/main

Try it

Open the Space in your browser, or copy it to your own Hugging Face account from its page. Nothing in this kit runs by itself.