Metadata-Version: 2.5
Name: isnady
Version: 0.0.7
Summary: Hadith search with full isnad chains, narrator biographies, jarh wa ta'dil verdicts and reliability scores
Project-URL: Homepage, https://github.com/bayramkotan/isnady
Project-URL: Repository, https://github.com/bayramkotan/isnady
Project-URL: Issues, https://github.com/bayramkotan/isnady/issues
Author: Bayram Kotan
License-Expression: MIT
License-File: LICENSE
Keywords: hadith,islamic studies,isnad,jarh wa tadil,narrators,rijal
Classifier: Development Status :: 2 - Pre-Alpha
Classifier: Environment :: X11 Applications :: Qt
Classifier: Intended Audience :: Education
Classifier: Intended Audience :: Science/Research
Classifier: Natural Language :: Arabic
Classifier: Natural Language :: English
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Education
Classifier: Topic :: Religion
Requires-Python: >=3.10
Requires-Dist: pyside6>=6.6
Description-Content-Type: text/markdown

<h1 align="center">📜 isnady &nbsp;<sub>إسناد</sub></h1>

<p align="center">
  <strong>Hadith search built around the isnad, the chain of transmission</strong><br>
  <sub>Search the collections, read every chain narrator by narrator, and see how the scholars read it</sub>
</p>

<p align="center">
  <a href="https://pypi.org/project/isnady/">
    <img src="https://img.shields.io/pypi/v/isnady?style=for-the-badge&color=1D4777&logo=pypi&logoColor=white" alt="PyPI">
  </a>
  <img src="https://img.shields.io/pypi/pyversions/isnady?style=for-the-badge&color=A47E24&logo=python&logoColor=white" alt="Python">
  <img src="https://img.shields.io/badge/Platform-Windows%20%7C%20Linux%20%7C%20macOS-5B6878?style=for-the-badge" alt="Platform">
  <a href="https://www.npmjs.com/package/isnady">
    <img src="https://img.shields.io/npm/v/isnady?style=for-the-badge&color=14304F&logo=npm&label=npm" alt="npm">
  </a>
  <img src="https://img.shields.io/badge/License-MIT-D6B25E?style=for-the-badge" alt="License">
</p>

<p align="center">
  <a href="#-why-isnady">Why</a> •
  <a href="#-install">Install</a> •
  <a href="#-quick-start">Quick Start</a> •
  <a href="#-search">Search</a> •
  <a href="#-chains-of-transmission">Chains</a> •
  <a href="#-educational-by-design">Educational</a> •
  <a href="#-appearance">Appearance</a> •
  <a href="#-data-and-licences">Data</a> •
  <a href="#%EF%B8%8F-cli">CLI</a> •
  <a href="#-screenshots">Screenshots</a> •
  <a href="#%EF%B8%8F-roadmap">Roadmap</a>
</p>

<p align="center">
  <img src="https://raw.githubusercontent.com/bayramkotan/isnady/main/assets/screenshots/search-arabic.png" alt="Searching النيات finds بالنيات in Sahih al-Bukhari 1, with the chain above the text" width="850">
</p>

> **Pre-alpha (0.0.7).** 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

One line, on any system — it removes earlier copies first, installs one, puts its commands on
PATH and checks the result:

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

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

Or with pip:

```bash
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.

<details>
<summary><b>🐧 On Linux, pip may refuse to install</b></summary>
<br>

Most current distributions mark the system Python as *externally managed* (PEP 668), so a
plain `pip install` stops with `error: externally-managed-environment`. Two ways around it:

```bash
# 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
```

</details>

### Something not right?

`iy doctor` lists every copy of isnady on the computer and which one each command really
starts — an older copy in the user folder can hide a newer one — and `iy doctor --fix` removes
the extras. The same report is under **Help → Check Installation**. If an old copy starts even
for `iy doctor`, run `python3 -s -m isnady doctor --fix` (Windows: `py -s -m isnady doctor --fix`).

### Upgrading

```bash
pip install -U isnady --no-cache-dir
```

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: you choose the sources. One command brings in Sahih
al-Bukhari and Sunan Abi Dawud in Arabic and Turkish from the open
[fawazahmed0/hadith-api](https://github.com/fawazahmed0/hadith-api) collection (public
domain):

```bash
iy import fawazahmed0 https://cdn.jsdelivr.net/gh/fawazahmed0/hadith-api@1/editions.json \
   --book bukhari --book abudawud --language ara --language tur --license Unlicense
```

Or open the window with `iy` and choose **File → Data Sources**: every built-in collection
(al-Bukhari, Muslim, Abu Dawud, al-Tirmidhi, al-Nasa'i, Ibn Maja, the Muwatta and three
forty-hadith books) and the Taqrib import with one click — or **Import all** — in the
languages you tick. You can add your own files or links there too, and move the data
folder anywhere you like.

On the command line:

```bash
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.

To identify the narrators in those chains, add Ibn Hajar's *Taqrib al-Tahdhib* — 8,824
narrators with his verdict on each — from the [OpenITI](https://github.com/OpenITI) corpus:

```bash
iy import taqrib https://raw.githubusercontent.com/OpenITI/0875AH/master/data/0852IbnHajarCasqalani/0852IbnHajarCasqalani.TaqribTahdhib/0852IbnHajarCasqalani.TaqribTahdhib.JK000121-ara1.completed
iy narrator الزهري
```

---

## 🔎 Search

| | |
|:--|:--|
| **Arabic without diacritics** | `الاعمال` finds `الأَعْمَالُ`. Alef forms, alef maqsura, hamza seats and ta marbuta are treated alike, so you type the way you normally write |
| **Attached prefixes** | `النيات` finds `بالنيات`, because Arabic joins bi-, wa-, fa- and al- to the word. *Whole words only* turns this off |
| **Latin-script text** | Case and accents are ignored: `NIYET`, `niyet` and `nîyet` are one word; `Muʿādh`, `Mu'adh` and `Muadh` too |
| **Match** | All words, any word, or the exact phrase |
| **Filters** | Book and language; the language filter also chooses which translations appear |
| **Grades** | Shown under each hadith with the scholar's name, exactly as given |
| **Highlighting** | On the original, diacritised text, diacritics included |

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

---

## 🔗 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.

<details>
<summary><b>📊 How well it reads today</b></summary>
<br>

Measured on Sahih al-Bukhari and Sunan Abi Dawud (12,852 chains):

| | Bukhari | Abu Dawud | Both |
|:--|:--:|:--:|:--:|
| Split into narrators | 85.5% | 71.9% | 79.9% |
| Of those, reaching the Prophet | | | 78.3% |
| Narrators per chain | | | 5.0 |

In a blind, hand-checked sample of 30 chains: **no wrong narrator**, 27 complete.

The rest are kept whole, each with its reason: *tahwil* (ح, a second chain joining), two
teachers at one link (*qiran*), a second chain after the first, or wording that could not be
read with confidence. Abu Dawud uses *qiran* and *tahwil* far more often than Bukhari, which
is why its share is lower. One known limit: a last narrator introduced only by *qāla*
("قال قال عبد الله") is not added, because the same words also begin stories.

</details>

---

## 🎓 Educational by Design

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

| Term | Reads | What the critics took it to mean |
|:--:|:--|:--|
| حدثنا | narrated to us | The teacher recited it to a group: heard directly |
| حدثني | narrated to me | Recited to the narrator alone: heard directly |
| أخبرنا | informed us | Often a text read back to the teacher (*ʿarḍ*) |
| أنبأنا | told us | Later often transmission by permission (*ijāza*) |
| سمعت | I heard | Direct hearing, stated explicitly |
| قرأت على | I read to | The narrator read the text back to the teacher |
| عن | from | Does not say how it was received (*ʿanʿana*); connected when the two could have met and the narrator is not known for *tadlīs* |
| أن | that | Treated by most critics like ʿan (*muʾannan*) |

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

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.

<p align="center">
  <img src="https://raw.githubusercontent.com/bayramkotan/isnady/main/assets/screenshots/preferences.png" alt="Preferences — font, size, line spacing and colour for each script" width="760">
</p>

The same settings from the command line:

```bash
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 and licences

isnady reads open formats and keeps the source of everything:

- **Supported now:** the [fawazahmed0/hadith-api](https://github.com/fawazahmed0/hadith-api)
  JSON format, from a file or a URL, with or without authentication (username and
  password, bearer token, or API key; credentials are never stored).
- **Rijal:** Ibn Hajar's *Taqrib al-Tahdhib* in OpenITI mARkdown — each narrator's name,
  kunya, verdict, rank, tabaqa, death year and book marks, read by the rules Ibn Hajar sets
  out in his own introduction. The OpenITI release does not state its licence in the
  repository, so it is kept as tier C (used on your computer, never redistributed) until
  it is confirmed.
- **Coming:** CSV, SQL/SQLite, OpenITI mARkdown, REST APIs and Shamela, so any collection
  you have can be brought in.

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.

---

## ⌨️ CLI

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

| Short | Full | What it does |
|:------|:-----|:-------------|
| `iy` | `isnady` | Open the window |
| `iy search WORDS` | `isnady search WORDS` | Search; `--mode all\|any\|phrase`, `--whole-words`, `--book`, `--language`, `--limit` |
| `iy chain BOOK NUMBER` | `isnady chain bukhari 1` | One chain, narrator by narrator, with who each one is; `--raw` adds the wording |
| `iy isnads` | `isnady isnads` | Read every chain and report per book; `--rebuild` reads them again |
| `iy narrator NAME` | `isnady narrator الزهري` | A narrator: Ibn Hajar's verdict and rank, tabaqa, death year, books, other names |
| `iy import FORMAT FILE-OR-URL` | `isnady import …` | Import a source; `--book`, `--language`, `--license`, `--user`, `--token-env`, `--api-key-env` |
| `iy catalog list` | `isnady catalog list` | Built-in sources and your own, with what is imported — the same as File → Data Sources |
| `iy catalog import ID` | `isnady catalog import fawaz-muslim --language tur` | Import a listed source; `remove`, `add`, `delete` manage the list |
| `iy catalog import --all` | `isnady catalog import --all --language ara` | Every built-in source at once |
| `iy datadir [FOLDER]` | `isnady datadir /data/isnady` | Show or change where the database and settings live; `--as-is`, `--default` |
| `iy formats` | `isnady formats` | Formats that can be imported |
| `iy sources` | `isnady sources` | Imported sources, their licence and tier |
| `iy stats` | `isnady stats` | Hadith, texts, grades and chains per book |
| `iy remove KEY` | `isnady remove KEY` | Remove a source and everything imported from it |
| `iy config list\|get\|set\|reset` | `isnady config …` | Appearance and other settings — the same as Edit → Preferences |
| `iy doctor` | `isnady doctor --fix` | Every copy of isnady on this computer; `--fix` removes the extras |
| `iy -V` | `isnady -V` | Show the version (also `-v`, `--version`, `version`) |
| `iy -h` | `isnady -h` | Show help |

```console
$ 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

<p align="center">
  <img src="https://raw.githubusercontent.com/bayramkotan/isnady/main/assets/screenshots/chain.png" alt="Isnad Chains — the chain of Sahih al-Bukhari 1 as a timeline from the book to the Prophet" width="850">
</p>
<p align="center">
  <img src="https://raw.githubusercontent.com/bayramkotan/isnady/main/assets/screenshots/search-grades.png" alt="Search — Sunan Abi Dawud with each scholar's grade and the chain above the text" width="850">
</p>
<p align="center">
  <img src="https://raw.githubusercontent.com/bayramkotan/isnady/main/assets/screenshots/chain-dark.png" alt="Dark theme — a seven-narrator chain from Sunan Abi Dawud" width="850">
</p>
<p align="center">
  <img src="https://raw.githubusercontent.com/bayramkotan/isnady/main/assets/screenshots/chains-overview.png" alt="Chains overview — per-book statistics and what was kept whole" width="850">
</p>

---

## 🗺️ Roadmap

- **Narrators** — the other half of the names identified through teachers and students
  (al-Mizzi's *Tahdhib al-Kamal*), a page for every narrator, the verdicts of other critics
  beside Ibn Hajar's, and whether each link could have met the next.
- **Hadith scholars** — lives, books, teachers and students, and what their collections
  contain.
- **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.

---

## 🏗️ Build from Source

```bash
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.

---

## 📝 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](https://github.com/aliftype/amiri) by Khaled
Hosny, bundled under the SIL Open Font License 1.1 (`src/isnady/assets/fonts/OFL.txt`).
