isnady 0.1.0 → 0.1.3

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (5) hide show
  1. package/LICENSE +21 -21
  2. package/README.md +565 -32
  3. package/index.d.ts +11 -11
  4. package/index.js +1 -1
  5. package/package.json +1 -1
package/LICENSE CHANGED
@@ -1,21 +1,21 @@
1
- MIT License
2
-
3
- Copyright (c) 2026 Bayram Kotan
4
-
5
- Permission is hereby granted, free of charge, to any person obtaining a copy
6
- of this software and associated documentation files (the "Software"), to deal
7
- in the Software without restriction, including without limitation the rights
8
- to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
- copies of the Software, and to permit persons to whom the Software is
10
- furnished to do so, subject to the following conditions:
11
-
12
- The above copyright notice and this permission notice shall be included in all
13
- copies or substantial portions of the Software.
14
-
15
- THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
- IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
- FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
- AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
- LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
- OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
- SOFTWARE.
1
+ MIT License
2
+
3
+ Copyright (c) 2026 Bayram Kotan
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
package/README.md CHANGED
@@ -1,70 +1,603 @@
1
+ <!-- generated from README.md by tools/sync_readme.py — edit README.md, not this file -->
1
2
  <h1 align="center">📜 isnady &nbsp;<sub>إسناد</sub></h1>
2
3
 
3
4
  <p align="center">
4
5
  <strong>Hadith search built around the isnad, the chain of transmission</strong><br>
5
- <sub>The JavaScript and TypeScript package</sub>
6
+ <sub>Search the collections, read every chain narrator by narrator, and see how the scholars read it</sub>
6
7
  </p>
7
8
 
8
9
  <p align="center">
10
+ <a href="https://pypi.org/project/isnady/">
11
+ <img src="https://img.shields.io/pypi/v/isnady?style=for-the-badge&color=1D4777&logo=pypi&logoColor=white" alt="PyPI">
12
+ </a>
13
+ <img src="https://img.shields.io/pypi/pyversions/isnady?style=for-the-badge&color=A47E24&logo=python&logoColor=white" alt="Python">
14
+ <img src="https://img.shields.io/badge/Platform-Windows%20%7C%20Linux%20%7C%20macOS-5B6878?style=for-the-badge" alt="Platform">
9
15
  <a href="https://www.npmjs.com/package/isnady">
10
16
  <img src="https://img.shields.io/npm/v/isnady?style=for-the-badge&color=14304F&logo=npm&label=npm" alt="npm">
11
17
  </a>
12
- <a href="https://pypi.org/project/isnady/">
13
- <img src="https://img.shields.io/pypi/v/isnady?style=for-the-badge&color=1D4777&logo=pypi&logoColor=white&label=app%20on%20PyPI" alt="PyPI">
14
- </a>
15
18
  <img src="https://img.shields.io/badge/License-MIT-D6B25E?style=for-the-badge" alt="License">
16
19
  </p>
17
20
 
18
21
  <p align="center">
19
- <img src="https://raw.githubusercontent.com/bayramkotan/isnady/main/assets/screenshots/chain.png" alt="The isnady app — the chain of Sahih al-Bukhari 1 from the book to the Prophet" width="780">
22
+ <a href="#-why-isnady">Why</a> •
23
+ <a href="#-install">Install</a> •
24
+ <a href="#-quick-start">Quick Start</a> •
25
+ <a href="#-search">Search</a> •
26
+ <a href="#-narrators">Narrators</a> •
27
+ <a href="#-hadith-scholars">Scholars</a> •
28
+ <a href="#-books">Books</a> •
29
+ <a href="#-shia-rijal">Shia Rijal</a> •
30
+ <a href="#-statistics">Statistics</a> •
31
+ <a href="#-learn">Learn</a> •
32
+ <a href="#-search-by-meaning-ai">Meaning (AI)</a> •
33
+ <a href="#-chains-of-transmission">Chains</a> •
34
+ <a href="#-educational-by-design">Educational</a> •
35
+ <a href="#-appearance">Appearance</a> •
36
+ <a href="#-data-and-licences">Data</a> •
37
+ <a href="#%EF%B8%8F-cli">CLI</a> •
38
+ <a href="#-screenshots">Screenshots</a> •
39
+ <a href="#%EF%B8%8F-roadmap">Roadmap</a>
40
+ </p>
41
+
42
+ <p align="center">
43
+ <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">
20
44
  </p>
21
45
 
46
+ > **Pre-alpha (0.1.3).** Search and chains of transmission work today, on data you import
47
+ > in one command. Narrators, scholars, gradings and the rest are being built, in the open.
48
+
22
49
  ---
23
50
 
24
- ## 🧭 Where things stand
25
51
 
26
- **isnady** is a hadith search application whose centre is the *isnad*: it reads each
27
- chain of transmission from the Arabic text, narrator by narrator, and explains what each
28
- link means. The application runs today on Windows, Linux and macOS:
52
+ > **About this npm package.** `npm install isnady` installs a small JavaScript library that will grow into
53
+ > isnady's API for the web (isnady.net); it does **not** install the isnady application. The application is
54
+ > installed with Python (`pip install isnady`, or the one-line installers below) or downloaded as a desktop
55
+ > app from the [GitHub Releases](https://github.com/bayramkotan/isnady/releases/latest) page. The npm package
56
+ > always carries the same version number as the application.
57
+ >
58
+ > ```js
59
+ > import { info, version } from "isnady";
60
+ > console.log(version); // the isnady version, the same as on PyPI and GitHub
61
+ > console.log(info()); // { name, version, dataLoaded, homepage }
62
+ > ```
63
+
64
+ ## 🎯 Why isnady
65
+
66
+ A hadith is two things: the text (*matn*) and the chain of people who passed it on
67
+ (*isnad*). Most hadith sites let you search the text and show a grade. isnady is built
68
+ the other way round: the chain comes first, because that is where the scholars of hadith
69
+ did their work.
70
+
71
+ - **The chain is read, not typed in.** isnady reads the chain from the Arabic text itself:
72
+ who narrated to whom, with which words, and whether it reaches the Prophet.
73
+ - **Nothing is guessed.** Where the wording cannot be read with confidence, the chain is
74
+ kept whole and marked, never split wrongly. A missing link is shown as missing.
75
+ - **Every fact has a source.** Every hadith, text and grade records where it came from,
76
+ under which licence.
77
+ - **Grades are shown as the scholars gave them.** Each grade keeps its scholar's name and
78
+ wording; isnady does not merge them or invent its own.
79
+ - **Window and command line, same engine.** Everything the window does, the command line
80
+ does too, with the same results.
81
+
82
+ ---
83
+
84
+ ## 📦 Install
85
+
86
+ ### Desktop application
87
+
88
+ Download isnady for your system from the **[latest release](https://github.com/bayramkotan/isnady/releases/latest)** —
89
+ everything included, the AI features too:
90
+
91
+ | System | File |
92
+ |---|---|
93
+ | Windows 10/11 | `isnady-<version>-windows-setup.exe` — Windows may say the publisher is unknown (the app is not signed): *More info → Run anyway* |
94
+ | Linux | `isnady-<version>-linux-x86_64.AppImage` — make it executable (`chmod +x`) and run it |
95
+ | macOS, Apple silicon / Intel | `isnady-<version>-macos-arm64.dmg` / `…-macos-x86_64.dmg` — the first time, right-click the app and choose *Open* (it is not notarized) |
96
+
97
+ Put isnady on the desktop and in the applications menu with **Tools → Create Desktop Shortcut** (or
98
+ `iy shortcut`): the shortcut starts isnady the way it is installed — the AppImage, the application, or the
99
+ `isnady-gui` command of a Python install.
100
+
101
+ ### With Python
102
+
103
+ One line, on any system. Install isnady wherever you like — for all users, for yourself, in a
104
+ virtual environment, with pipx: the same line installs it, and later updates every copy where it
105
+ is, asking for administrator rights only when a copy needs them. Nothing is ever removed.
106
+
107
+ ```bash
108
+ # Linux and macOS
109
+ curl -fsSL https://raw.githubusercontent.com/bayramkotan/isnady/main/install.sh | bash
110
+ ```
111
+
112
+ ```powershell
113
+ # Windows (PowerShell)
114
+ irm https://raw.githubusercontent.com/bayramkotan/isnady/main/install.ps1 | iex
115
+ ```
116
+
117
+ Or with pip:
29
118
 
30
119
  ```bash
31
120
  pip install isnady
32
- iy
121
+ isnady # or the short name: iy
122
+ ```
123
+
124
+ Run inside a clone of this repository, the installer makes an editable (developer) install of
125
+ that clone instead.
126
+
127
+ The same program answers to several names: **`iy`** to type, **`isnady`** to read, and
128
+ `isnady-cli` kept from the first releases. Without arguments it opens the window; with
129
+ arguments it is the command line. On Windows, **`isnady-gui`** opens the window without a
130
+ console.
131
+
132
+ <details>
133
+ <summary><b>🐧 On Linux, pip may refuse to install</b></summary>
134
+ <br>
135
+
136
+ Most current distributions mark the system Python as *externally managed* (PEP 668), so a
137
+ plain `pip install` stops with `error: externally-managed-environment`. Two ways around it:
138
+
139
+ ```bash
140
+ # Isolated — recommended, no system packages touched
141
+ pipx install isnady
142
+
143
+ # Into your user site — needs the override flag
144
+ pip install isnady --break-system-packages --no-cache-dir -U
145
+ ```
146
+
147
+ </details>
148
+
149
+ ### Something not right?
150
+
151
+ `iy update` updates every copy of isnady where it is installed. `iy doctor` lists every copy and
152
+ which one each command really starts — an older copy in the user folder can start before a newer
153
+ one elsewhere, so every copy is kept at the same version. The same report is under
154
+ **Help → Check Installation**. If an old copy starts even for `iy update`, run
155
+ `python3 -s -m isnady update` (Windows: `py -s -m isnady update`).
156
+
157
+ ### Upgrading
158
+
159
+ ```bash
160
+ iy update
161
+ ```
162
+
163
+ Your data stays where it is; a newer isnady upgrades the database in place the first time
164
+ it opens it.
165
+
166
+ ---
167
+
168
+ ## 🚀 Quick Start
169
+
170
+ isnady ships without hadith data: you choose the sources. One command brings in Sahih
171
+ al-Bukhari and Sunan Abi Dawud in Arabic and Turkish from the open
172
+ [fawazahmed0/hadith-api](https://github.com/fawazahmed0/hadith-api) collection (public
173
+ domain):
174
+
175
+ ```bash
176
+ iy import fawazahmed0 https://cdn.jsdelivr.net/gh/fawazahmed0/hadith-api@1/editions.json \
177
+ --book bukhari --book abudawud --language ara --language tur --license Unlicense
178
+ ```
179
+
180
+ Or open the window with `iy` and choose **File → Data Sources**: every built-in collection
181
+ (al-Bukhari, Muslim, Abu Dawud, al-Tirmidhi, al-Nasa'i, Ibn Maja, the Muwatta and three
182
+ forty-hadith books) and the Taqrib import with one click — or **Import all** — in the
183
+ languages you tick. You can add your own files or links there too, and move the data
184
+ folder anywhere you like.
185
+
186
+ On the command line:
187
+
188
+ ```bash
189
+ iy search النيات # Arabic, with or without diacritics
190
+ iy search "niyetlere göre" # Turkish, English, any imported language
191
+ iy chain bukhari 1 # one chain, narrator by narrator
33
192
  ```
34
193
 
35
- **This npm package is the JavaScript side, and it is not functional yet.** It will be the
36
- client of the isnady.net web service, which runs the same engine as the application, so a
37
- chain read on the web and in the app always gives the same answer. Until that service
38
- exists, the package only reports its version:
194
+ Importing takes a minute or two; the search index and the chains are built as part of it.
39
195
 
40
- ```js
41
- import { info, version } from "isnady";
196
+ To identify the narrators in those chains, add Ibn Hajar's *Taqrib al-Tahdhib* — 8,824
197
+ narrators with his verdict on each — from the [OpenITI](https://github.com/OpenITI) corpus:
42
198
 
43
- console.log(version); // "0.1.0"
44
- console.log(info()); // { name: "isnady", version: "0.1.0", dataLoaded: false, homepage: "…" }
199
+ ```bash
200
+ iy import taqrib https://raw.githubusercontent.com/OpenITI/0875AH/master/data/0852IbnHajarCasqalani/0852IbnHajarCasqalani.TaqribTahdhib/0852IbnHajarCasqalani.TaqribTahdhib.JK000121-ara1.completed
201
+ iy narrator الزهري
45
202
  ```
46
203
 
47
- TypeScript declarations are included.
204
+ ---
48
205
 
49
- ## 🗺️ Planned
206
+ ## 🔎 Search
50
207
 
51
- ```js
52
- import { searchHadith, getChain, getNarrator } from "isnady";
208
+ | | |
209
+ |:--|:--|
210
+ | **Arabic without diacritics** | `الاعمال` finds `الأَعْمَالُ`. Alef forms, alef maqsura, hamza seats and ta marbuta are treated alike, so you type the way you normally write |
211
+ | **Attached prefixes** | `النيات` finds `بالنيات`, because Arabic joins bi-, wa-, fa- and al- to the word. *Whole words only* turns this off |
212
+ | **Latin-script text** | Case and accents are ignored: `NIYET`, `niyet` and `nîyet` are one word; `Muʿādh`, `Mu'adh` and `Muadh` too |
213
+ | **Match** | All words, any word, or the exact phrase |
214
+ | **Filters** | Book and language; the language filter also chooses which translations appear |
215
+ | **Grades** | Shown under each hadith with the scholar's name, exactly as given |
216
+ | **Highlighting** | On the original, diacritised text, diacritics included |
53
217
 
54
- const results = await searchHadith("النيات", { book: "bukhari" });
55
- const chain = await getChain("bukhari", 1); // narrators and the words linking them
56
- const person = await getNarrator(chain.links[0]); // biography, teachers, students, verdicts
218
+ Results appear at once and fill in as you read; the window never waits for them.
219
+
220
+ ### 👥 Narrators
221
+
222
+ The **Narrators** page lists every narrator of the imported rijal work — 8,824 from Ibn
223
+ Hajar's *Taqrib* — searchable in Arabic or in Latin letters (`Abu Hurayra`, `Zuhri`, `Ibn Umar`),
224
+ and filtered by tabaqa, rank and book. For each narrator: Ibn Hajar's verdict and its rank, the
225
+ tabaqa and death year, the books his hadith appear in, **whom he narrates from and who
226
+ narrates from him** in the imported chains, the compilers who narrate from him directly, and
227
+ every hadith whose chain includes him. On the Isnad Chains page a click on a narrator's name
228
+ opens him here.
229
+
230
+ Each narrator — and each scholar — is shown by the name he is **known by** (al-A'mash, Ibn 'Umar,
231
+ Abu Hurayra), with his full name and every part of it laid out: name, lineage, kunya, by-name,
232
+ nisbas, client of; the part he is known by is marked ★.
233
+
234
+ <p align="center">
235
+ <img src="https://raw.githubusercontent.com/bayramkotan/isnady/main/assets/screenshots/narrators.png" alt="Narrators — 'Abdullah b. 'Umar: Ibn Hajar's verdict, tabaqa, death year, teachers and students in the chains" width="850">
236
+ </p>
237
+
238
+ ### 🎓 Hadith Scholars
239
+
240
+ The scholars whose work is in the imported data, and what the data measures of it:
241
+ **compilers** (their collection, the teachers their chains begin with, the Companions they end
242
+ with), **graders** (how they grade, and how far they agree with each other on the same hadith —
243
+ agreement, Cohen's kappa, and a strictness index: the classical *mutashaddid* / *mutasahil*,
244
+ measured), and **critics** of narrators (Ibn Hajar's twelve ranks). On Sunan Abi Dawud, for
245
+ example, Zubair 'Ali Za'i grades most strictly (−0.21) and agrees with al-Albani on 70% of the
246
+ hadith; the page also flags a pair of graders whose 98% agreement suggests the source did not keep
247
+ them independent.
248
+
249
+ <p align="center">
250
+ <img src="https://raw.githubusercontent.com/bayramkotan/isnady/main/assets/screenshots/scholars.png" alt="Hadith Scholars — al-Albani: his grades on Sunan Abi Dawud and his agreement with the other graders" width="850">
251
+ </p>
252
+
253
+ ### 📚 Books
254
+
255
+ isnady is not only for searching: the **Books** section opens every imported work and reads it in
256
+ its own order. A hadith collection reads chapter by chapter, each hadith with its card (chain,
257
+ narrators, other narrations, grades) and the languages you choose; Ibn Hajar's *Taqrib* reads
258
+ letter by letter and name by name, each entry with its narrator a click away. Find within a
259
+ chapter, go to the previous or next one, and isnady remembers where you were. From any search
260
+ result, **In its book** opens the hadith where it stands, among the hadith of its chapter.
261
+
262
+ Books are not tied to hadith collections: a work is a tree of any depth (volume, book, chapter,
263
+ section) whose leaves are hadith, narrators' entries or paragraphs — so the commentaries, manuals
264
+ of fiqh and other works of the scholars can be read the same way as they are added.
265
+
266
+ <p align="center">
267
+ <img src="https://raw.githubusercontent.com/bayramkotan/isnady/main/assets/screenshots/books.png" alt="Books — reading Sahih al-Bukhari chapter by chapter, Arabic and Turkish, each hadith with its chain" width="850">
268
+ </p>
269
+
270
+ ```bash
271
+ iy book # the books
272
+ iy book bukhari # its chapters
273
+ iy book bukhari 2 --language Turkish
274
+ iy book taqrib 1
57
275
  ```
58
276
 
59
- Search with Arabic diacritics ignored, chains read narrator by narrator, and grades shown
60
- exactly as each scholar gave them — the same results as the application.
277
+ ### 🕌 Shia Rijal
278
+
279
+ The Imami tradition's judgments on narrators, on its own terms: al-Najashi's *Rijal* — 1,266
280
+ authors and narrators — read along the two axes of the Imami critics, **reliability** (thiqa;
281
+ praised — *jalil*, *wajh*, *'ayn*; weak) and **creed** (Imami, or Waqifi, Fathi, Zaydi, *'ammi* …),
282
+ which together give the classical four: an Imami *thiqa*, a praised narrator (*mamduh*), a *thiqa*
283
+ of another school (*muwaththaq*), a weak one. The critic's own words are always shown; a creed he
284
+ does not state stays unknown; nothing is mapped onto Ibn Hajar's twelve ranks. Checked on four
285
+ blind samples of entries, each round's misses corrected. The book itself reads in **Books**, and
286
+ the Shia narrators are kept apart from the (Sunni) chains: no chain link is matched to them.
287
+
288
+ <p align="center">
289
+ <img src="https://raw.githubusercontent.com/bayramkotan/isnady/main/assets/screenshots/shia-rijal.png" alt="Shia Rijal — al-Najashi on 'Ali b. al-Husayn b. Babawayh: his words and their reading on the Imami scale" width="850">
290
+ </p>
291
+
292
+ Next: al-Tusi's *Rijal* and *Fihrist*, al-'Allama al-Hilli's *Khulasat al-aqwal*, Ibn Dawud's
293
+ *Rijal*, al-Kashshi's reports, and the Four Books with their chains.
294
+
295
+ ### 📊 Statistics
61
296
 
62
- ## 🔗 Links
297
+ Measured in depth, each figure with what it means and how sure it is. Grades are ordered
298
+ categories, so they are never turned into numbers or averaged. The first tab, **Graders**, takes
299
+ the scholars who graded a book (al-Albani, Shu'ayb al-Arna'ut, Zubair 'Ali Za'i, Muhammad Muhyi
300
+ al-Din 'Abd al-Hamid on Sunan Abi Dawud) and shows:
63
301
 
64
- - **Application and source:** [github.com/bayramkotan/isnady](https://github.com/bayramkotan/isnady)
65
- - **Python package:** [pypi.org/project/isnady](https://pypi.org/project/isnady/)
66
- - **Issues:** [github.com/bayramkotan/isnady/issues](https://github.com/bayramkotan/isnady/issues)
302
+ - agreement of every pair — same grade, Cohen's kappa and the ordinal kappa — with 95% intervals,
303
+ and Krippendorff's alpha for all of them together;
304
+ - a **Dawid–Skene model** of each hadith's true grade: each grader's confusion matrix (how he grades
305
+ a hadith of each true grade) and, for every hadith, how sure the model is;
306
+ - **strictness** — the classical *mutashaddid* and *mutasahil*, measured by order only, with intervals;
307
+ - the **disputed hadith**, where the scholars are furthest apart — a double-click opens one in its book.
308
+
309
+ Two graders who agree far too often to be independent (98.1%) count as one voice in the model,
310
+ and the page says so. Results are computed once and kept in a file. `iy stats graders`.
311
+ Narrators, books, hadith, chains, correlations and the models follow, tab by tab.
312
+
313
+ <p align="center">
314
+ <img src="https://raw.githubusercontent.com/bayramkotan/isnady/main/assets/screenshots/statistics.png" alt="Statistics — the graders of Sunan Abi Dawud: Krippendorff's alpha, agreement with intervals, the model's certainty" width="850">
315
+ </p>
316
+
317
+ ### 🎓 Learn
318
+
319
+ The terms of hadith and its sciences, written for isnady with their classical sources: 81 terms —
320
+ the grades (sahih, hasan, da'if, mawdu', shadhdh, munkar, mu'allal), the kinds of hadith by their
321
+ chain (mutawatir, mursal, munqati', mu'allaq, mudallas …), chain and text (mutaba'a, shahid,
322
+ takhrij, madar), the ways of receiving (sama', ijaza, haddathana, 'an), judging narrators (the
323
+ twelve ranks of Ibn Hajar, thiqa, saduq, majhul, matruk, mudallis), generations, the parts of an
324
+ Arabic name, Imami rijal, the books, and isnady's own measures. Each with its Arabic, a one-line
325
+ and a longer definition in **English or Turkish**, related terms one click away, and its source.
326
+ The grades on every result explain themselves when you point at them. `iy term mursal --lang tr`.
327
+
328
+ <p align="center">
329
+ <img src="https://raw.githubusercontent.com/bayramkotan/isnady/main/assets/screenshots/learn.png" alt="Learn — the term mursal: Arabic, definition, related terms and source" width="850">
330
+ </p>
331
+
332
+ ### 🧠 Search by meaning (AI)
333
+
334
+ Choose **Match → By meaning (AI)** to find hadith that say the same thing in other words or in
335
+ another language: `komşu hakları` finds the hadith on the neighbour's rights, a Turkish sentence
336
+ finds its Arabic original, and `إنما الأعمال بالنيات` gathers the narrations of the hadith on
337
+ intentions from every imported book. Each result shows how close it is in meaning (0–1), which
338
+ says nothing about authenticity.
339
+
340
+ The model is learnt on your computer from the texts you imported — Arabic beside its
341
+ translations is a parallel corpus, and cross-lingual latent semantic analysis learns the
342
+ concepts the languages share. Nothing is downloaded and no outside model is used. Measured on
343
+ al-Bukhari and Abu Dawud: for hadith the model never saw while learning, a Turkish translation
344
+ finds its Arabic original first 68% of the time and among the first ten 93% of the time (chance:
345
+ 0.8%). For an exact quotation the ordinary word search stays the better tool.
346
+
347
+ The same step finds the **other narrations of each hadith** across the imported books
348
+ (takhrij): every result card says where else it is narrated — *Also narrated in: Sahih
349
+ al-Bukhari 5070 · 6689 · 6953 | Sunan Abi Dawud 2201* — and each number opens that hadith.
350
+ Only the texts are compared, never the chains; upright numbers share the text, italic ones
351
+ probably report the same event from the same Companion. In blind, hand-checked samples 34 of
352
+ 35 pairs of the first kind and 18 of 20 of the second were right.
353
+
354
+ ```bash
355
+ pip install "isnady[ai]" # numpy and scipy
356
+ iy ai build # a few seconds; or Tools → Build AI Indexes
357
+ iy search --mode meaning "komşu hakları"
358
+ iy tahric bukhari 1 # the other narrations of a hadith
359
+ ```
360
+
361
+ ---
362
+
363
+ ## 🔗 Chains of transmission
364
+
365
+ Every Arabic text is read for its chain:
366
+
367
+ ```
368
+ Sahih al Bukhari 1
369
+ 1. حدثنا (narrated to us) الْحُمَيْدِيُّ عَبْدُ اللَّهِ بْنُ الزُّبَيْرِ
370
+ 2. حدثنا (narrated to us) سُفْيَانُ
371
+ 3. حدثنا (narrated to us) يَحْيَى بْنُ سَعِيدٍ الْأَنْصَارِيُّ
372
+ 4. أخبرني (informed me) مُحَمَّدُ بْنُ إِبْرَاهِيمَ التَّيْمِيُّ
373
+ 5. سمع (heard) عَلْقَمَةَ بْنَ وَقَّاصٍ اللَّيْثِيَّ
374
+ 6. سمعت (I heard) عُمَرَ بْنَ الْخَطَّابِ
375
+ -> the Prophet
376
+ ```
377
+
378
+ In the window, each result shows its chain as a row of names ending at the Prophet, and
379
+ **View chain** opens it as a timeline from the book to the Prophet, with the Arabic text
380
+ below: the chain in lighter ink, the text of the hadith in full ink.
381
+
382
+ ### 👤 Who each narrator is
383
+
384
+ With Ibn Hajar's *Taqrib al-Tahdhib* imported, every name in a chain is matched to a
385
+ narrator, and the chain shows what Ibn Hajar says of him: his verdict in his own words, its
386
+ rank on Ibn Hajar's twelve-step scale, the narrator's *tabaqa* (generation) and his death
387
+ year.
388
+
389
+ A name is linked only when the evidence leaves one person: the words of the name, the book
390
+ marks (a narrator in al-Bukhari must be one Ibn Hajar marks خ), the order of generations
391
+ along the chain, and the last link before the Prophet being a Companion. When several
392
+ narrators remain — "Sufyan" can be al-Thawri or Ibn 'Uyayna — the chain says so and names
393
+ how many, rather than choosing one. Today about half of all names are identified; in blind,
394
+ hand-checked samples of the identified ones, the last fifty were all correct.
395
+
396
+ Names are kept exactly as written, with the clarifications the compilers added
397
+ (*"— yaʿnī Ibn Muḥammad —"*, *"mawlā Ibn ʿAbbās"*), because identifying each narrator is
398
+ a separate step that comes next.
399
+
400
+ <details>
401
+ <summary><b>📊 How well it reads today</b></summary>
402
+ <br>
403
+
404
+ Measured on Sahih al-Bukhari and Sunan Abi Dawud (12,852 chains):
405
+
406
+ | | Bukhari | Abu Dawud | Both |
407
+ |:--|:--:|:--:|:--:|
408
+ | Split into narrators | 85.5% | 71.9% | 79.9% |
409
+ | Of those, reaching the Prophet | | | 78.3% |
410
+ | Narrators per chain | | | 5.0 |
411
+
412
+ In a blind, hand-checked sample of 30 chains: **no wrong narrator**, 27 complete.
413
+
414
+ The rest are kept whole, each with its reason: *tahwil* (ح, a second chain joining), two
415
+ teachers at one link (*qiran*), a second chain after the first, or wording that could not be
416
+ read with confidence. Abu Dawud uses *qiran* and *tahwil* far more often than Bukhari, which
417
+ is why its share is lower. One known limit: a last narrator introduced only by *qāla*
418
+ ("قال قال عبد الله") is not added, because the same words also begin stories.
419
+
420
+ </details>
421
+
422
+ ---
423
+
424
+ ## 🎓 Educational by Design
425
+
426
+ isnady teaches the science it uses. Every transmission term in a chain explains itself:
427
+
428
+ | Term | Reads | What the critics took it to mean |
429
+ |:--:|:--|:--|
430
+ | حدثنا | narrated to us | The teacher recited it to a group: heard directly |
431
+ | حدثني | narrated to me | Recited to the narrator alone: heard directly |
432
+ | أخبرنا | informed us | Often a text read back to the teacher (*ʿarḍ*) |
433
+ | أنبأنا | told us | Later often transmission by permission (*ijāza*) |
434
+ | سمعت | I heard | Direct hearing, stated explicitly |
435
+ | قرأت على | I read to | The narrator read the text back to the teacher |
436
+ | عن | 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* |
437
+ | أن | that | Treated by most critics like ʿan (*muʾannan*) |
438
+
439
+ The Learn section — hadith terminology, grading, *jarḥ wa taʿdīl* and the classical works,
440
+ each shown on real hadith and real chains — is on the roadmap.
441
+
442
+ ---
443
+
444
+ ## 🎨 Appearance
445
+
446
+ Every script has its own reading font, size, colour and line spacing — Arabic, Latin,
447
+ Cyrillic, Bengali and Tamil today, more as sources in other scripts arrive. The light and
448
+ the dark theme each keep their own colours, and the interface font can be changed too.
449
+ **Edit → Preferences** (Ctrl + ,) applies every change at once; each row has its own
450
+ Default button.
451
+
452
+ <p align="center">
453
+ <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">
454
+ </p>
455
+
456
+ The same settings from the command line:
457
+
458
+ ```bash
459
+ iy config list --prefix text.arabic # what is set, and what is changed
460
+ iy config set text.arabic.size 22
461
+ iy config set text.latin.family "Noto Serif"
462
+ iy config set colors.dark.gilt "#5A4A1E" # matched words in the dark theme
463
+ iy config reset text.arabic # back to the defaults
464
+ ```
465
+
466
+ Settings live in `settings.json` in the isnady data folder, shared by the window and the
467
+ command line.
468
+
469
+ ---
470
+
471
+ ## 📚 Data and licences
472
+
473
+ isnady reads open formats and keeps the source of everything:
474
+
475
+ - **Supported now:** the [fawazahmed0/hadith-api](https://github.com/fawazahmed0/hadith-api)
476
+ JSON format, from a file or a URL, with or without authentication (username and
477
+ password, bearer token, or API key; credentials are never stored).
478
+ - **Rijal:** Ibn Hajar's *Taqrib al-Tahdhib* in OpenITI mARkdown — each narrator's name,
479
+ kunya, verdict, rank, tabaqa, death year and book marks, read by the rules Ibn Hajar sets
480
+ out in his own introduction. The OpenITI release does not state its licence in the
481
+ repository, so it is kept as tier C (used on your computer, never redistributed) until
482
+ it is confirmed.
483
+ - **Coming:** CSV, SQL/SQLite, OpenITI mARkdown, REST APIs and Shamela, so any collection
484
+ you have can be brought in.
485
+
486
+ Every source records a licence **tier**: **A** may be redistributed, **B** may be
487
+ redistributed under its conditions, **C** may not. Sources you add yourself stay on your
488
+ computer. **Help → Licences** lists every source in your database with its licence.
489
+
490
+ ---
491
+
492
+ ## ⌨️ CLI
493
+
494
+ Everything the window does also works without it — on a server, over SSH, or in a
495
+ script. The command line never loads Qt.
496
+
497
+ | Short | Full | What it does |
498
+ |:------|:-----|:-------------|
499
+ | `iy` | `isnady` | Open the window |
500
+ | `iy search WORDS` | `isnady search WORDS` | Search; `--mode all\|any\|phrase`, `--whole-words`, `--book`, `--language`, `--limit` |
501
+ | `iy chain BOOK NUMBER` | `isnady chain bukhari 1` | One chain, narrator by narrator, with who each one is; `--raw` adds the wording |
502
+ | `iy isnads` | `isnady isnads` | Read every chain and report per book; `--rebuild` reads them again |
503
+ | `iy ai build` | `isnady ai build` | Learn the meaning index from the imported texts (`iy ai status` to check) |
504
+ | `iy import najashi FILE` | `isnady catalog import najashi` | al-Najashi's Rijal: Shia narrators read on the Imami scale, and the book |
505
+ | `iy shortcut` | `isnady shortcut --no-desktop` | A desktop and applications-menu shortcut, with isnady's icon |
506
+ | `iy term [NAME]` | `isnady term --search tadlis` | The glossary: a term's meaning, English or Turkish (`--lang tr`) |
507
+ | `iy stats graders` | `isnady stats graders --book abudawud` | The graders of a book in depth: agreement, model, strictness |
508
+ | `iy book [KEY [CHAPTER]]` | `isnady book bukhari 2` | The books; a book's chapters; a chapter read in order |
509
+ | `iy scholar [NAME]` | `isnady scholar albani` | The scholars in the data, or one of them with his measured statistics |
510
+ | `iy tahric BOOK NUMBER` | `isnady tahric bukhari 1` | Other narrations of a hadith in the imported books (takhrij) |
511
+ | `iy search --mode meaning WORDS` | `isnady search --mode meaning "komşu hakları"` | Search by meaning and across languages |
512
+ | `iy narrator NAME` | `isnady narrator "Ibn Umar"` | A narrator: Ibn Hajar's verdict and rank, tabaqa, death year, books, other names; with `--limit 1` also teachers, students and hadith |
513
+ | `iy import FORMAT FILE-OR-URL` | `isnady import …` | Import a source; `--book`, `--language`, `--license`, `--user`, `--token-env`, `--api-key-env` |
514
+ | `iy catalog list` | `isnady catalog list` | Built-in sources and your own, with what is imported — the same as File → Data Sources |
515
+ | `iy catalog import ID` | `isnady catalog import fawaz-muslim --language tur` | Import a listed source; `remove`, `add`, `delete` manage the list |
516
+ | `iy catalog import --all` | `isnady catalog import --all --language ara` | Every built-in source at once |
517
+ | `iy datadir [FOLDER]` | `isnady datadir /data/isnady` | Show or change where the database and settings live; `--as-is`, `--default` |
518
+ | `iy formats` | `isnady formats` | Formats that can be imported |
519
+ | `iy sources` | `isnady sources` | Imported sources, their licence and tier |
520
+ | `iy stats` | `isnady stats` | Hadith, texts, grades and chains per book |
521
+ | `iy remove KEY` | `isnady remove KEY` | Remove a source and everything imported from it |
522
+ | `iy config list\|get\|set\|reset` | `isnady config …` | Appearance and other settings — the same as Edit → Preferences |
523
+ | `iy update` | `isnady update` | Update every copy of isnady where it is installed (system, user, venv, pipx, clone) |
524
+ | `iy doctor` | `isnady doctor` | Every copy of isnady on this computer and which one each command starts |
525
+ | `iy -V` | `isnady -V` | Show the version (also `-v`, `--version`, `version`) |
526
+ | `iy -h` | `isnady -h` | Show help |
527
+
528
+ ```console
529
+ $ iy search niyet --book abudawud --limit 1
530
+ 43 hadith found in 8 ms
531
+
532
+ Sunan Abu Dawud #472
533
+ grades: Al-Albani: Hasan; Muhammad Muhyi Al-Din Abdul Hamid: Hasan; Shuaib Al Arnaut: Daif; Zubair Ali Zai: Daif
534
+ [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"
535
+ ```
536
+
537
+ ---
538
+
539
+ ## 📸 Screenshots
540
+
541
+ <p align="center">
542
+ <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">
543
+ </p>
544
+ <p align="center">
545
+ <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">
546
+ </p>
547
+ <p align="center">
548
+ <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">
549
+ </p>
550
+ <p align="center">
551
+ <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">
552
+ </p>
553
+
554
+ ---
555
+
556
+ ## 🗺️ Roadmap
557
+
558
+ - **Narrators** — the other half of the names identified through teachers and students
559
+ (al-Mizzi's *Tahdhib al-Kamal*), the verdicts of other critics beside Ibn Hajar's, and
560
+ whether each link could have met the next.
561
+ - **Hadith scholars** — their lives in full, and more scholars as more collections and grades
562
+ are imported.
563
+ - **Shia rijal** — narrator verdicts from the Shia rijal works, beside the Sunni view.
564
+ - **Learn** — the sciences of hadith, shown on real hadith and real chains.
565
+ - **More sources and formats** — and adding your own from inside the window.
566
+ - **Glossary** — every Arabic term of hadith and the Islamic sciences explained where it
567
+ appears: hover or click a term, read its meaning in the interface language.
568
+ - **isnady.net** — the same engine on the web.
569
+
570
+ ---
571
+
572
+ ## 🔁 Versions and releases
573
+
574
+ One version number on GitHub, PyPI and npm, always. A release builds the Python package and the Windows,
575
+ Linux and macOS applications first; only when every build succeeds is anything published — PyPI, then the
576
+ [GitHub Release](https://github.com/bayramkotan/isnady/releases) with every file and its checksum. What each
577
+ version brought is in the [CHANGELOG](https://github.com/bayramkotan/isnady/blob/main/CHANGELOG.md). The
578
+ README on npm is made from this one.
579
+
580
+ ## 🏗️ Build from Source
581
+
582
+ ```bash
583
+ git clone https://github.com/bayramkotan/isnady.git
584
+ cd isnady
585
+ pip install -e .
586
+ iy
587
+ ```
588
+
589
+ Python 3.10 or newer and PySide6. The command line alone needs no PySide6.
590
+
591
+ ---
592
+
593
+
594
+ The desktop application of your own system: `pip install ".[ai]" pyinstaller`, then
595
+ `python packaging/build_app.py linux|windows|macos VERSION` (Windows also needs Inno Setup).
67
596
 
68
597
  ## 📝 License
69
598
 
70
- MIT. Hadith data comes from separate sources, each under its own licence.
599
+ MIT for the application code. Hadith data comes from separate sources, each under its own
600
+ licence, recorded with the data and listed under **Help → Licences**.
601
+
602
+ The Arabic and reading typeface is [Amiri](https://github.com/aliftype/amiri) by Khaled
603
+ Hosny, bundled under the SIL Open Font License 1.1 (`src/isnady/assets/fonts/OFL.txt`).
package/index.d.ts CHANGED
@@ -1,11 +1,11 @@
1
- export declare const version: string;
2
- export declare const name: string;
3
-
4
- export interface IsnadyInfo {
5
- name: string;
6
- version: string;
7
- dataLoaded: boolean;
8
- homepage: string;
9
- }
10
-
11
- export declare function info(): IsnadyInfo;
1
+ export declare const version: string;
2
+ export declare const name: string;
3
+
4
+ export interface IsnadyInfo {
5
+ name: string;
6
+ version: string;
7
+ dataLoaded: boolean;
8
+ homepage: string;
9
+ }
10
+
11
+ export declare function info(): IsnadyInfo;
package/index.js CHANGED
@@ -6,7 +6,7 @@
6
6
  * database (used by both the Python and JavaScript packages) exists.
7
7
  */
8
8
 
9
- export const version = "0.1.0";
9
+ export const version = "0.1.3";
10
10
  export const name = "isnady";
11
11
 
12
12
  /** Returns basic package information. */
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "isnady",
3
- "version": "0.1.0",
3
+ "version": "0.1.3",
4
4
  "description": "Hadith search with full isnad chains, narrator biographies, jarh wa ta'dil verdicts and reliability scores",
5
5
  "type": "module",
6
6
  "main": "./index.js",