📜 isnady  _إسناد

Hadith search built around the isnad, the chain of transmission
_{Search the collections, read every chain narrator by narrator, and see how the scholars read it}

Why • Install • Quick Start • Search • Narrators • Scholars • Books • Shia Rijal • Statistics • Learn • Meaning (AI) • Chains • Educational • Appearance • Data • CLI • Screenshots • Roadmap

Pre-alpha (0.1.8). Search and chains of transmission work today, on data you import in one command. Narrators, scholars, gradings and the rest are being built, in the open.

🎯 Why isnady

A hadith is two things: the text (matn) and the chain of people who passed it on (isnad). Most hadith sites let you search the text and show a grade. isnady is built the other way round: the chain comes first, because that is where the scholars of hadith did their work.

• The chain is read, not typed in. isnady reads the chain from the Arabic text itself: who narrated to whom, with which words, and whether it reaches the Prophet.
• Nothing is guessed. Where the wording cannot be read with confidence, the chain is kept whole and marked, never split wrongly. A missing link is shown as missing.
• Every fact has a source. Every hadith, text and grade records where it came from, under which licence.
• Grades are shown as the scholars gave them. Each grade keeps its scholar's name and wording; isnady does not merge them or invent its own.
• Window and command line, same engine. Everything the window does, the command line does too, with the same results.

📦 Install

Desktop application

Download isnady for your system from the latest release — everything included, the AI features too:

All three are portable: nothing is installed, each runs from wherever it is. Put a folder named isnady-data beside the file and isnady keeps its databases and settings there — isnady on a USB stick.

Put isnady on the desktop and in the applications menu with Tools → Create Desktop Shortcut (or iy shortcut): the shortcut starts isnady the way it is installed — the AppImage, the application, or the isnady-gui command of a Python install.

With Python

One line, on any system. Install isnady wherever you like — for all users, for yourself, in a virtual environment, with pipx: the same line installs it, and later updates every copy where it is, asking for administrator rights only when a copy needs them. Nothing is ever removed.

# Linux and macOS
curl -fsSL https://raw.githubusercontent.com/bayramkotan/isnady/main/install.sh | bash

# Windows (PowerShell)
irm https://raw.githubusercontent.com/bayramkotan/isnady/main/install.ps1 | iex

Or with pip:

pip install isnady
isnady            # or the short name:  iy

Run inside a clone of this repository, the installer makes an editable (developer) install of that clone instead.

The same program answers to several names: iy to type, isnady to read, and isnady-cli kept from the first releases. Without arguments it opens the window; with arguments it is the command line. On Windows, isnady-gui opens the window without a console.

# Isolated — recommended, no system packages touched
pipx install isnady

# Into your user site — needs the override flag
pip install isnady --break-system-packages --no-cache-dir -U

Something not right?

iy update updates every copy of isnady where it is installed. iy doctor lists every copy and which one each command really starts — an older copy in the user folder can start before a newer one elsewhere, so every copy is kept at the same version. The same report is under Help → Check Installation. If an old copy starts even for iy update, run python3 -s -m isnady update (Windows: py -s -m isnady update).

Upgrading

iy update

Your data stays where it is; a newer isnady upgrades the database in place the first time it opens it.

🚀 Quick Start

isnady ships without hadith data; it reads it from a data repository. The default is isnady's own, bayramkotan/isnady-data, which holds every Sunni and Shia collection and rijal work isnady can read — 35 sources, from Sahih al-Bukhari to al-Kafi (see Data sources below). Open the window with iy, choose File → Data Sources, and import any of them with one click — or Import all — in the languages you tick. The same from the command line:

iy catalog list                         # the sources of the repository in use
iy catalog import sahih_al_bukhari --language ara --language tur
iy catalog import musnad_ahmad_ibn_hanbal
iy catalog import al_kafi_al_kulayni    # with al-Majlisi's and al-Behbudi's grades
iy catalog import taqrib_al_tahdhib_ibn_hajar_al_asqalani   # identifies the narrators in the chains
iy catalog import --all                 # everything

Other repositories can be chosen instead — the datasets others publish on GitHub and Hugging Face are in the list — and any repository with an isnady catalog can be added (iy repo add https://github.com/owner/name). Your own files and links can be added too, and the data folder can be moved anywhere you like.

On the command line:

iy search النيات            # Arabic, with or without diacritics
iy search "niyetlere göre"   # Turkish, English, any imported language
iy chain bukhari 1           # one chain, narrator by narrator

Importing takes a minute or two; the search index and the chains are built as part of it.

With Ibn Hajar's Taqrib al-Tahdhib imported (8,824 narrators, his verdict on each), every chain is read narrator by narrator: iy narrator الزهري.

🔎 Search

Results appear at once and fill in as you read; the window never waits for them.

👥 Narrators

The Narrators page lists every narrator of the imported rijal work — 8,824 from Ibn Hajar's Taqrib — searchable in Arabic or in Latin letters (Abu Hurayra, Zuhri, Ibn Umar), and filtered by tabaqa, rank and book. For each narrator: Ibn Hajar's verdict and its rank, the tabaqa and death year, the books his hadith appear in, whom he narrates from and who narrates from him in the imported chains, the compilers who narrate from him directly, and every hadith whose chain includes him. On the Isnad Chains page a click on a narrator's name opens him here.

Each narrator — and each scholar — is shown by the name he is known by (al-A'mash, Ibn 'Umar, Abu Hurayra), with his full name and every part of it laid out: name, lineage, kunya, by-name, nisbas, client of; the part he is known by is marked ★.

🎓 Hadith Scholars

The scholars whose work is in the imported data, and what the data measures of it: compilers (their collection, the teachers their chains begin with, the Companions they end with), graders (how they grade, and how far they agree with each other on the same hadith — agreement, Cohen's kappa, and a strictness index: the classical mutashaddid / mutasahil, measured), and critics of narrators (Ibn Hajar's twelve ranks). On Sunan Abi Dawud, for example, Zubair 'Ali Za'i grades most strictly (−0.21) and agrees with al-Albani on 70% of the hadith; the page also flags a pair of graders whose 98% agreement suggests the source did not keep them independent.

📚 Books

isnady is not only for searching: the Books section opens every imported work and reads it in its own order. A hadith collection reads chapter by chapter, each hadith with its card (chain, narrators, other narrations, grades) and the languages you choose; Ibn Hajar's Taqrib reads letter by letter and name by name, each entry with its narrator a click away. Find within a chapter, go to the previous or next one, and isnady remembers where you were. From any search result, In its book opens the hadith where it stands, among the hadith of its chapter.

Books are not tied to hadith collections: a work is a tree of any depth (volume, book, chapter, section) whose leaves are hadith, narrators' entries or paragraphs — so the commentaries, manuals of fiqh and other works of the scholars can be read the same way as they are added.

iy book                      # the books
iy book bukhari              # its chapters
iy book bukhari 2 --language Turkish
iy book taqrib 1

🕌 Shia Rijal

The Imami tradition's judgments on narrators, on its own terms: al-Najashi's Rijal — 1,266 authors and narrators — read along the two axes of the Imami critics, reliability (thiqa; praised — jalil, wajh, 'ayn; weak) and creed (Imami, or Waqifi, Fathi, Zaydi, 'ammi …), which together give the classical four: an Imami thiqa, a praised narrator (mamduh), a thiqa of another school (muwaththaq), a weak one. The critic's own words are always shown; a creed he does not state stays unknown; nothing is mapped onto Ibn Hajar's twelve ranks. Checked on four blind samples of entries, each round's misses corrected. The book itself reads in Books, and the Shia narrators are kept apart from the (Sunni) chains: no chain link is matched to them.

Next: al-Tusi's Rijal and Fihrist, al-'Allama al-Hilli's Khulasat al-aqwal, Ibn Dawud's Rijal, al-Kashshi's reports, and the Four Books with their chains.

📊 Statistics

Measured in depth, each figure with what it means and how sure it is. Grades are ordered categories, so they are never turned into numbers or averaged. The first tab, Graders, takes the scholars who graded a book (al-Albani, Shu'ayb al-Arna'ut, Zubair 'Ali Za'i, Muhammad Muhyi al-Din 'Abd al-Hamid on Sunan Abi Dawud) and shows:

• agreement of every pair — same grade, Cohen's kappa and the ordinal kappa — with 95% intervals, and Krippendorff's alpha for all of them together;
• a Dawid–Skene model of each hadith's true grade: each grader's confusion matrix (how he grades a hadith of each true grade) and, for every hadith, how sure the model is;
• strictness — the classical mutashaddid and mutasahil, measured by order only, with intervals;
• the disputed hadith, where the scholars are furthest apart — a double-click opens one in its book.

Two graders who agree far too often to be independent (98.1%) count as one voice in the model, and the page says so. Results are computed once and kept in a file. iy stats graders. Narrators, books, hadith, chains, correlations and the models follow, tab by tab. Correlations and tests sets every measure against every other — Spearman's ρ with Benjamini–Hochberg q-values, and the partial ρ with all the others held equal (what each factor of the chain says of each scholar's grade on its own) — and tests what differs: the scholars' grades pair by pair (Stuart–Maxwell), the books (Kruskal–Wallis, Mann–Whitney with Cliff's δ), and whether the hadith model's shape holds (Brant's test). iy stats lab.

🎓 Learn

The terms of hadith and its sciences, written for isnady with their classical sources: 81 terms — the grades (sahih, hasan, da'if, mawdu', shadhdh, munkar, mu'allal), the kinds of hadith by their chain (mutawatir, mursal, munqati', mu'allaq, mudallas …), chain and text (mutaba'a, shahid, takhrij, madar), the ways of receiving (sama', ijaza, haddathana, 'an), judging narrators (the twelve ranks of Ibn Hajar, thiqa, saduq, majhul, matruk, mudallis), generations, the parts of an Arabic name, Imami rijal, the books, and isnady's own measures. Each with its Arabic, a one-line and a longer definition in English or Turkish, related terms one click away, and its source. The grades on every result explain themselves when you point at them. iy term mursal --lang tr.

🧠 Search by meaning (AI)

Choose Match → By meaning (AI) to find hadith that say the same thing in other words or in another language: komşu hakları finds the hadith on the neighbour's rights, a Turkish sentence finds its Arabic original, and إنما الأعمال بالنيات gathers the narrations of the hadith on intentions from every imported book. Each result shows how close it is in meaning (0–1), which says nothing about authenticity.

The model is learnt on your computer from the texts you imported — Arabic beside its translations is a parallel corpus, and cross-lingual latent semantic analysis learns the concepts the languages share. Nothing is downloaded and no outside model is used. Measured on al-Bukhari and Abu Dawud: for hadith the model never saw while learning, a Turkish translation finds its Arabic original first 68% of the time and among the first ten 93% of the time (chance: 0.8%). For an exact quotation the ordinary word search stays the better tool.

The same step finds the other narrations of each hadith across the imported books (takhrij): every result card says where else it is narrated — Also narrated in: Sahih al-Bukhari 5070 · 6689 · 6953 | Sunan Abi Dawud 2201 — and each number opens that hadith. Only the texts are compared, never the chains; upright numbers share the text, italic ones probably report the same event from the same Companion. In blind, hand-checked samples 34 of 35 pairs of the first kind and 18 of 20 of the second were right.

pip install "isnady[ai]"        # numpy and scipy
iy ai build                     # a few seconds; or Tools → Build AI Indexes
iy search --mode meaning "komşu hakları"
iy tahric bukhari 1             # the other narrations of a hadith

🔗 Chains of transmission

Every Arabic text is read for its chain:

Sahih al Bukhari 1
   1. حدثنا (narrated to us)  الْحُمَيْدِيُّ عَبْدُ اللَّهِ بْنُ الزُّبَيْرِ
   2. حدثنا (narrated to us)  سُفْيَانُ
   3. حدثنا (narrated to us)  يَحْيَى بْنُ سَعِيدٍ الْأَنْصَارِيُّ
   4. أخبرني (informed me)    مُحَمَّدُ بْنُ إِبْرَاهِيمَ التَّيْمِيُّ
   5. سمع (heard)            عَلْقَمَةَ بْنَ وَقَّاصٍ اللَّيْثِيَّ
   6. سمعت (I heard)          عُمَرَ بْنَ الْخَطَّابِ
      -> the Prophet

In the window, each result shows its chain as a row of names ending at the Prophet, and View chain opens it as a timeline from the book to the Prophet, with the Arabic text below: the chain in lighter ink, the text of the hadith in full ink.

👤 Who each narrator is

With Ibn Hajar's Taqrib al-Tahdhib imported, every name in a chain is matched to a narrator, and the chain shows what Ibn Hajar says of him: his verdict in his own words, its rank on Ibn Hajar's twelve-step scale, the narrator's tabaqa (generation) and his death year.

A name is linked only when the evidence leaves one person: the words of the name, the book marks (a narrator in al-Bukhari must be one Ibn Hajar marks خ), the order of generations along the chain, and the last link before the Prophet being a Companion. When several narrators remain — "Sufyan" can be al-Thawri or Ibn 'Uyayna — the chain says so and names how many, rather than choosing one. Today about half of all names are identified; in blind, hand-checked samples of the identified ones, the last fifty were all correct.

Names are kept exactly as written, with the clarifications the compilers added ("— yaʿnī Ibn Muḥammad —", "mawlā Ibn ʿAbbās"), because identifying each narrator is a separate step that comes next.

🎓 Educational by Design

isnady teaches the science it uses. Every transmission term in a chain explains itself:

The Learn section — hadith terminology, grading, jarḥ wa taʿdīl and the classical works, each shown on real hadith and real chains — is on the roadmap.

🎨 Appearance

Seven themes, chosen in Edit → Preferences → Themes — each shown as a small live isnady window — or in View → Theme: Lapis (lapis and gold of illuminated manuscripts) and Lapis Night, which "Follow system" switches between; Paper (warm cream and ink, for long reading); Slate (quiet and modern, with a light sidebar); Emerald; Midnight (deep dark with teal); and High Contrast (black, white and yellow, for low vision). iy config set view.theme paper.

Every script has its own reading font, size, colour and line spacing — Arabic, Latin, Cyrillic, Bengali and Tamil today, more as sources in other scripts arrive. The light and the dark theme each keep their own colours, and the interface font can be changed too. Edit → Preferences (Ctrl + ,) applies every change at once; each row has its own Default button.

The same settings from the command line:

iy config list --prefix text.arabic       # what is set, and what is changed
iy config set text.arabic.size 22
iy config set text.latin.family "Noto Serif"
iy config set colors.dark.gilt "#5A4A1E"  # matched words in the dark theme
iy config reset text.arabic               # back to the defaults

Settings live in settings.json in the isnady data folder, shared by the window and the command line.

📚 Data sources

isnady reads its sources from a repository: a catalog.json listing books and rijal works, where each file is, its format, its licence and its tradition. Choose one in Settings → Data sources (or iy repo use ID); add your own with Add a repository… (iy repo add URL: a GitHub repository, a Hugging Face dataset, a catalog URL or a folder).

The default — isnady-data holds every source below in one place and in isnady's own format, each book in a folder named by its full title and its compiler — sunni/sahih_al_bukhari/, sunni/musnad_ahmad_ibn_hanbal/, shia/al_kafi_al_kulayni/ (a book.json and one file per language) — and the works on the narrators in rijal/sunni/, rijal/shia/.

The credits for where each text was first published are in the repository's README.

Optional repositories, each the dataset as its authors publish it (their books under their own keys, e.g. bukhari-lk, so editions with other numbering never mix):

Every source records a licence tier: A may be redistributed, B may be redistributed under its conditions, C may not. Sources you add yourself stay on your computer. Help → Licences lists every source in your database with its licence. Any CSV or JSON table of hadith can be read through a catalog that names its columns (format table); the fawazahmed0 JSON format, OpenITI mARkdown (the Taqrib, al-Najashi) and files of your own with or without authentication (credentials are never stored) are read as well.

⌨️ CLI

Everything the window does also works without it — on a server, over SSH, or in a script. The command line never loads Qt.

$ iy search niyet --book abudawud --limit 1
43 hadith found in 8 ms

Sunan Abu Dawud #472
  grades: Al-Albani: Hasan; Muhammad Muhyi Al-Din Abdul Hamid: Hasan; Shuaib Al Arnaut: Daif; Zubair Ali Zai: Daif
  [Turkish] Ebu Hureyre (r.a.); Resulullah (Sallallahu aleyhi ve Sellem)'in şöyle buyurduğunu rivayet etmiştir: "Bir kimse mescid'e hangi [niyet]le gelirse nasibi ondan ibarettir"

📸 Screenshots

🗺️ Roadmap

• Narrators — the other half of the names identified through teachers and students (al-Mizzi's Tahdhib al-Kamal), the verdicts of other critics beside Ibn Hajar's, and whether each link could have met the next.
• Hadith scholars — their lives in full, and more scholars as more collections and grades are imported.
• Shia rijal — narrator verdicts from the Shia rijal works, beside the Sunni view.
• Learn — the sciences of hadith, shown on real hadith and real chains.
• More sources and formats — and adding your own from inside the window.
• Glossary — every Arabic term of hadith and the Islamic sciences explained where it appears: hover or click a term, read its meaning in the interface language.
• isnady.net — the same engine on the web.

🔁 Versions and releases

One version number on GitHub, PyPI and npm, always. A release builds the Python package and the Windows, Linux and macOS applications first; only when every build succeeds is anything published — PyPI, then the GitHub Release with every file and its checksum. What each version brought is in the CHANGELOG. The README on npm is made from this one.

🏗️ Build from Source

git clone https://github.com/bayramkotan/isnady.git
cd isnady
pip install -e .
iy

Python 3.10 or newer and PySide6. The command line alone needs no PySide6.

The desktop application of your own system: pip install ".[ai]" pyinstaller, then python packaging/build_app.py linux|windows|macos VERSION.

📝 License

MIT for the application code. Hadith data comes from separate sources, each under its own licence, recorded with the data and listed under Help → Licences.

The Arabic and reading typeface is Amiri by Khaled Hosny, bundled under the SIL Open Font License 1.1 (src/isnady/assets/fonts/OFL.txt).