IsnadGuard
Hadith Chain Defect Detection System

What is a Hadith?

A Hadith (حديث — plural: Ahadith) is a recorded account of something the Prophet Muhammad ﷺ said, did, or silently approved of. After the Holy Quran, the Ahadith form the second most important foundation of Islamic guidance and law. For over fourteen centuries, Muslim scholars have treated the verification of these narrations as both a scholarly duty and a religious obligation — because a fabricated or distorted statement attributed to the Prophet ﷺ would constitute a grave religious harm.

Every Hadith you encounter in any of the six major Hadith collections — Sahih al-Bukhari, Sahih Muslim, Sunan Abu Dawud, Jami al-Tirmidhi, Sunan al-Nasa'i, and Sunan Ibn Majah — has two parts:

• Isnad (إسناد) — The chain of narrators who transmitted the Hadith from one generation to the next, tracing back to someone who heard or witnessed it directly.
• Matn (متن) — The actual content — what the Prophet ﷺ said or did.

How Scholars Grade a Hadith

Not every statement attributed to the Prophet ﷺ is authentic. Over the centuries, some narrations were fabricated by people with political or religious agendas, and others were simply misremembered or confused. Islamic scholars developed a rigorous science called Ilm al-Hadith — the science of Hadith criticism — to evaluate each narration systematically. The grade assigned to a Hadith depends primarily on the quality of its narrator chain:

The Isnad — Understanding the Chain Structure

The word Isnad (إسناد) comes from the Arabic root meaning "to support" or "to lean upon." It is the ordered sequence of people who transmitted a Hadith from the Prophet ﷺ forward through time until it was recorded in a book. Each person in the chain heard the narration from the person before them and passed it to the person after them.

In computational terms, you can think of an Isnad as a directed linked list — each narrator is a node, each transmission is an edge pointing from the source toward the recorder. The list must be complete from beginning to end. A missing node anywhere in the chain is a structural defect.

How a Chain Looks

The chain below represents a simplified version of a real Isnad. Reading it left to right, it shows how the narration was passed forward in time:

Each arrow means "transmitted to." Bukhari heard from Yahya, who heard from Muhammad ibn Ibrahim, and so on back to the Companion who heard from the Prophet ﷺ directly.

Narrator Generations — Tabaqat

Every narrator belongs to a historical generation called a Tabaqah (طبقة — plural: Tabaqat). The generation number is absolutely critical for your defect detection system. Two consecutive narrators in a chain must belong to adjacent or near-adjacent generations — because they must have been alive at the same time to transmit to each other. If your data shows that Narrator A is from Generation 3 and Narrator B, who supposedly heard directly from A, is from Generation 7, that four-generation gap is your primary signal that someone is missing between them.

Types of Chain Defects — What Your System Must Detect

A defect in an Isnad is called an Illah (عِلَّة) — a hidden weakness. Islamic scholars spent centuries classifying these defects and developing systematic methods to identify them. Your project takes this classical taxonomy and implements it computationally. There are five main defect types your system must handle:

Example — A Broken Chain (Munqati')

The gap from Gen 3 to Gen 7 signals Mu'dal (four generations missing). Narrator C's Da'if grade signals an additional weak narrator defect. Both are present in the same chain.

Machine Learning — The Core CS Discipline Behind This Project

Machine Learning (ML) is a branch of computer science in which systems learn patterns from data rather than following explicitly programmed rules. Instead of a programmer writing every decision, a machine learning model is trained on examples and learns to generalize from them. In the context of your project, you are training a model to look at the features of a narrator chain and predict its grade — Sahih, Hasan, or Da'if.

The Three Types of Machine Learning

Your project uses supervised learning, so understanding how the three types differ gives you the necessary context to explain your choice in the SRS:

Classification — What Your ML Module Does

Within supervised learning, your task is a classification problem — assigning each chain to one of several categories. The algorithm looks at a set of input features you provide (numbers derived from the chain structure) and maps them to an output category (the chain's grade).

The Algorithms You Will Compare

Your Module 6 requires you to train and compare at least two classification algorithms using the Scikit-learn library. Here is what each one does conceptually:

Key Evaluation Metrics You Must Know

After training, you measure how well your model performs on data it has never seen before (the test set). Your SRS should mention these metrics as non-functional requirements, and your Design Document must show them in your test cases:

Data Science — The Pipeline That Connects Everything

Data Science is the discipline of extracting meaningful insights from structured and unstructured data through a combination of statistics, programming, and domain knowledge. It is not a single technique but a pipeline — a sequence of steps that transforms raw data into useful knowledge. Your entire project follows this pipeline from beginning to end.

The Data Science Pipeline in Your Project

Every module you build corresponds to a stage in this pipeline. Understanding the pipeline as a whole helps you see why the modules are ordered the way they are, and why skipping a step causes problems downstream:

Feature Engineering — The Most Important Step You Will Do

Machine learning algorithms work with numbers, not names or text. The process of converting raw data into meaningful numerical inputs for a model is called feature engineering, and it is arguably the most important skill in data science. For this project, you must convert each narrator chain into a set of numerical features. Here are the features you should design:

Explainable AI — Why It Matters More Here Than Anywhere

Explainable AI, commonly abbreviated as XAI, is a field of artificial intelligence focused on making the decisions of machine learning models understandable to humans. When a model classifies an image as a cat, most users are satisfied with that answer. But when a model says "this Hadith chain is Da'if," a scholar, a researcher, or anyone taking that verdict seriously will immediately ask: why? Which part of the chain caused this classification? Was it a weak narrator, a broken link, or something else?

Without an explanation, your model is a black box — it produces an answer but cannot justify it. In the domain of Hadith authentication, an unjustified verdict is essentially useless, because the entire tradition of Hadith science is built on transparency of reasoning. This is precisely why the XAI module is not optional in your project — it is what makes the system academically credible and practically meaningful.

SHAP — The Method You Will Use

SHAP stands for SHapley Additive exPlanations. It is a mathematically grounded method for explaining individual predictions made by any machine learning model. The core idea comes from game theory: each feature of your input (each number in the chain's feature vector) gets a "Shapley value" that represents how much it contributed to pushing the prediction in a particular direction.

Concretely, for a chain that your model classifies as Da'if, SHAP might produce an explanation like: "The max_gen_gap feature contributed +0.42 toward the Da'if prediction, while weak_narrator_count contributed +0.31, and chain_length contributed -0.08 (slightly away from Da'if)." This tells a scholar exactly what structural feature was most responsible for the verdict.

Graph Theory — How Narrator Chains Become Visual Networks

Graph theory is a branch of mathematics and computer science dealing with structures made up of nodes (also called vertices) connected by edges. Many real-world problems map naturally to graphs: social networks, road maps, web links, electrical circuits, and — as your project demonstrates — narrator transmission chains.

How a Narrator Chain Becomes a Graph

In your project, every narrator is a node and every transmission relationship (A heard from B) is a directed edge. The chain from the Prophet ﷺ through multiple narrators to the collector is a directed path graph — a sequence of nodes where edges only go in one direction. Your visualization module renders this graph on screen, coloring each node by the narrator's reliability grade and marking broken links with a distinct visual style.

The Library You Will Use

NetworkX is the standard Python library for creating, analyzing, and drawing graphs. It supports directed and undirected graphs, weighted edges, and various layout algorithms for positioning nodes on screen. For rendering, it works together with Matplotlib. You do not need to implement graph theory from scratch — NetworkX handles the data structure and Matplotlib handles the visual output.

What Graph Features Are Useful for Your Project

Beyond visualization, graph analysis can contribute to your ML feature set. Concepts like node degree (how many chains a narrator appears in), betweenness centrality (how many chains pass through a narrator), and connected components (whether the chain forms one continuous path) are all computable from graph structures and may be worth exploring as additional features in Module 6.

Which Datasets to Use and Why

All datasets recommended for this project are peer-reviewed, publicly available, and free. No unofficial sources, no Kaggle datasets from anonymous contributors, and no data that requires any payment. The following three are your primary options:

Key Tables in hadith-kg

Using Hugging Face — What It Is and How to Get Started

Hugging Face is the world's largest open-source platform for sharing AI models and datasets. Think of it as GitHub, but purpose-built for machine learning. The platform hosts over 500,000 public datasets, all freely accessible. Your primary dataset — hadith-kg — is hosted there.

Creating Your Account

Downloading: The Windows Method

If you prefer a graphical, point-and-click approach to downloading the dataset file, this is the method for you. It requires no programming, just a browser and the Hugging Face website.

Downloading: The Python Code Method

Downloading through Python gives you more control, better progress visibility, and — most importantly — the ability to resume an interrupted download. This is the recommended method for most students.

Step 1 — Install the Required Library

Open your terminal or command prompt and run this command once. You do not need to run it again after it succeeds:

pip install huggingface_hub

Step 2 — Log In to Hugging Face

Run this command in your terminal. It will ask you to paste the access token you generated in Chapter 9. You only need to do this once — your credentials are saved to your machine after the first login:

huggingface-cli login

Step 3 — Download the Dataset File

Create a new Python file in your project folder — for example, download_dataset.py — and write the following code exactly as shown. Run it with python download_dataset.py in your terminal:

from huggingface_hub import hf_hub_download
import os

# Create the data folder if it does not exist
os.makedirs("./data", exist_ok=True)

print("Starting download of hadith-kg.db ...")
print("File size: approximately 1.6 GB. This may take a while.")
print("If interrupted, re-run this script — the download will resume.")

file_path = hf_hub_download(
    repo_id="emadjumaah/hadith-kg",
    filename="hadith-kg.db",
    repo_type="dataset",
    local_dir="./data",
    local_dir_use_symlinks=False
)

print(f"Download complete. File saved at: {file_path}")
print(f"File size on disk: {os.path.getsize(file_path) / (1024**3):.2f} GB")

Downloading the Sanadset 650K (Alternative / Additional)

To download the Sanadset dataset instead or in addition, replace the repo_id and filename in the script above with the following values. Sanadset is stored in Parquet format, which is more efficient than CSV for large datasets:

from huggingface_hub import snapshot_download

# This downloads all Parquet files of the Sanadset into ./data/sanadset/
snapshot_download(
    repo_id="arbml/Sanadset",
    repo_type="dataset",
    local_dir="./data/sanadset",
    local_dir_use_symlinks=False
)

Resumable Downloads — What to Do When the Connection Drops

Internet connections in Pakistan are often unstable, and a 1.6 GB file can take a long time to download. Here is exactly what happens in each scenario and what you should do:

Using the Streaming Option — No Download Required

If downloading is genuinely impossible on your connection, you can stream just the records you need directly from Hugging Face into your Python session — no file is saved to disk at all. This is suitable for the Sanadset dataset but not for hadith-kg (which is a SQLite file and must be opened locally). Here is how streaming works for Sanadset:

from datasets import load_dataset

# Install the datasets library first: pip install datasets
# streaming=True means no file is downloaded — data streams record by record

ds = load_dataset(
    "arbml/Sanadset",
    streaming=True,
    split="train"
)

# Take only the first 1000 records for your prototype work
sample = list(ds.take(1000))

import pandas as pd
df = pd.DataFrame(sample)
print(df.head())
print("Columns:", df.columns.tolist())
print(f"Loaded {len(df)} records")

Exploring the Dataset — What to Do Before Writing Any Module

The first thing you must do after successfully connecting to hadith-kg.db is explore the data. Do not jump to building the defect detector until you have spent time understanding what is actually in the database. Here is the exploration code to run:

import sqlite3
import pandas as pd

# Open connection to the database
conn = sqlite3.connect("./data/hadith-kg.db")

# ── Step 1: List all tables ──────────────────────────────
tables = pd.read_sql_query(
    "SELECT name FROM sqlite_master WHERE type='table' ORDER BY name",
    conn
)
print("=== Tables in database ===")
print(tables)

# ── Step 2: See all narrator grade types ─────────────────
grades = pd.read_sql_query(
    "SELECT grade, COUNT(*) as count FROM rawis GROUP BY grade ORDER BY count DESC",
    conn
)
print("\n=== Narrator Grade Distribution ===")
print(grades)

# ── Step 3: See generation distribution ──────────────────
tabaqat = pd.read_sql_query(
    "SELECT tabaqah, COUNT(*) as count FROM rawis WHERE tabaqah IS NOT NULL GROUP BY tabaqah ORDER BY tabaqah",
    conn
)
print("\n=== Generation (Tabaqah) Distribution ===")
print(tabaqat)

# ── Step 4: Sample a complete chain ──────────────────────
chain_query = """
    SELECT sr.pos, r.name, r.grade, r.tabaqah, r.death_year
    FROM sanad_rawis sr
    JOIN rawis r ON sr.rawi_id = r.id
    WHERE sr.sanad_id = 1
    ORDER BY sr.pos ASC
"""
chain = pd.read_sql_query(chain_query, conn)
print("\n=== Sample chain — sanad_id = 1 ===")
print(chain)

# ── Step 5: Check chain length distribution ───────────────
lengths = pd.read_sql_query(
    "SELECT sanad_id, COUNT(*) as length FROM sanad_rawis GROUP BY sanad_id ORDER BY length DESC LIMIT 20",
    conn
)
print("\n=== Top 20 longest chains ===")
print(lengths)

conn.close()
print("\nExploration complete.")

System Inputs and Outputs — What the User Gives and Gets

Before designing any class or writing any logic, you must know precisely what the user interacts with. This section describes the inputs and outputs for every major module of your project. This directly informs your Use Case Diagram in the SRS and your Sequence Diagrams in the Design Document.

Module 1 — Data Loading

Module 3 — Defect Detection

Module 6 — ML Classifier

Module 7 — XAI Explanation

Module 8 — Final Dashboard

Implementation Logic — Pseudocode for Core Functions

This chapter gives you the logical skeleton of each core function as pseudocode. Pseudocode describes what the function should do in plain English, without being tied to any specific programming language. Your task is to take this pseudocode and implement it yourself in Python, making decisions about data types, error handling, and edge cases along the way.

Building a Chain from the Database

FUNCTION build_chain(chain_id):

    -- Query the database --
    -- JOIN sanad_rawis with rawis WHERE sanad_id = chain_id --
    -- SELECT pos, name, grade, tabaqah, death_year --
    -- ORDER BY pos ASC --

    IF no rows returned:
        raise an error: "Chain ID not found"

    FOR EACH row in results:
        create a narrator object with: name, grade, tabaqah, death_year, position

    RETURN the ordered list of narrator objects

    -- Edge cases to handle in your implementation: --
    -- What if tabaqah is NULL for some narrators? --
    -- What if grade is NULL? --
    -- What if chain_id is not an integer? --

Munqati' Detection — Broken Chain

FUNCTION detect_munqati(narrator_list):

    gaps_found = empty list

    FOR each pair (narrator_A, narrator_B) where B immediately follows A:

        IF either narrator has no tabaqah value:
            skip this pair, record as "generation data unavailable"
            CONTINUE

        gap = absolute_value(narrator_B.tabaqah - narrator_A.tabaqah)

        IF gap is exactly 1:
            record this as a Munqati' gap
            note: which two narrators, gap size = 1
        ELSE IF gap is greater than 1:
            -- Do NOT count this here — it is Mu'dal, handled separately --
            CONTINUE

    RETURN detected = (gaps_found is not empty), details = gaps_found

Mu'dal Detection — Multiple Narrators Missing

FUNCTION detect_mudal(narrator_list):

    severe_gaps = empty list

    FOR each pair (narrator_A, narrator_B) where B immediately follows A:

        IF either has no tabaqah: skip

        gap = absolute_value(narrator_B.tabaqah - narrator_A.tabaqah)

        IF gap >= 2:
            record as Mu'dal gap
            note: which narrators, how many appear to be missing (gap - 1)

    RETURN detected = (severe_gaps is not empty), details = severe_gaps

Mursal Detection — Missing Companion

FUNCTION detect_mursal(narrator_list):

    has_companion = False
    has_successor = False

    FOR EACH narrator in narrator_list:
        IF narrator.tabaqah == 1:
            has_companion = True
        IF narrator.tabaqah == 2:
            has_successor = True

    is_mursal = (has_companion == False) AND (has_successor == True)

    RETURN detected = is_mursal,
           explanation = "Tabi'i narrates without a Companion in chain"
                         if is_mursal else "Companion present in chain"

The Master Analysis Function

FUNCTION analyze_chain(chain_id):

    narrator_list = build_chain(chain_id)

    IF narrator_list is empty or error:
        RETURN error to user: "Chain not found"

    results = empty dictionary

    results["munqati"]       = detect_munqati(narrator_list)
    results["mudal"]         = detect_mudal(narrator_list)
    results["mursal"]        = detect_mursal(narrator_list)
    results["mawquf"]        = detect_mawquf(narrator_list)
    results["weak_narrator"] = detect_weak_narrator(narrator_list)

    any_defect_found = check if ANY result has detected = True

    overall_verdict = "Defective Chain" if any_defect_found else "No structural defects detected"

    RETURN narrator_list, results, overall_verdict

    -- Remember: detect_mawquf and detect_weak_narrator pseudocode --
    -- must be written by YOU, using the concepts from Chapter 3.  --

SRS Assignment — Software Requirements Specification

The SRS is your first formal assignment and the foundation of your entire project. It describes WHAT your system will do — from the perspective of the user — without describing HOW it will do it. You should not mention Python, Scikit-learn, Pandas, SQLite, or any technology in the functional requirements section. The SRS template you have been given contains six sections. Each is explained in detail below.

Section 1 — Scope of the Project

Write a comprehensive description of what IsnadGuard does, why it exists, what problem it solves, who will use it, and what it does not do. The scope should be specific enough that a reader can tell exactly what is and is not part of your system. Include the domain background — explain briefly what an Isnad is and why defect detection matters — so that any evaluator understands the context even without prior Islamic studies knowledge. Refer to Chapters 1 through 3 of this guide for the domain content.

Section 2 — Functional and Non-Functional Requirements

This is the most technically important section of your SRS. Functional requirements describe specific behaviors your system must perform. Every requirement must start with "The system shall..." — this is the IEEE 830 standard phrasing. Non-functional requirements describe quality attributes — how well the system performs, how secure it is, how usable it must be.

Examples of correctly written functional requirements for IsnadGuard:

• The system shall allow the user to load the Hadith narrator chain database from a local file path.
• The system shall reconstruct a complete narrator chain for any given chain identifier from the loaded database.
• The system shall detect and report the presence of a Munqati' defect by identifying generation gaps between consecutive narrators.
• The system shall display each narrator's name, reliability grade, and generation number in the chain view.
• The system shall train a classification model on extracted chain features and display accuracy, precision, recall, and F1 score on the test set.
• The system shall provide an explanation for each chain grade prediction showing the contribution of each input feature.

Examples of non-functional requirements:

• The system shall display defect detection results within three seconds of receiving a chain identifier.
• The system shall handle chains of up to fifty narrators without performance degradation.
• The system's interface shall be usable by a user with no prior knowledge of Hadith science — all technical terms shall be accompanied by plain-English explanations.

Section 3 — Use Case Diagram

A Use Case Diagram shows the actors in the system and the actions they can perform. It is a high-level overview — it does not show steps or sequences, only capabilities.

Section 4 — Usage Scenarios

A Usage Scenario is a structured description of one complete use case. The template requires you to write a scenario for every use case shown in the diagram. Each scenario is presented as a table with these fields:

Section 5 — Adopted Methodology

Your project follows the VU Process Model, which combines elements of the Waterfall and Spiral models. Explain this choice specifically for your project: the Waterfall component means you follow sequential phases (requirements → design → implementation → testing → delivery), while the Spiral component means you revisit and refine each phase incrementally — for example, your prototype in Assignment 3 is an early spiral iteration, and your Final Project is the complete spiral. Reference CS605 (SE2) for the formal methodology description. Also mention that the four-assignment structure (SRS, Design Document, Prototype, Final) maps directly to the phases of this combined model.

Section 6 — Work Plan (Gantt Chart)

Create a Gantt chart using Microsoft Project or any free alternative (GanttProject, TeamGantt free tier, or even Excel's bar chart feature). The chart must show all eight modules of your project, organized across two semesters, with the four assignment submission dates marked as milestones. Each module should have a start date, an end date, and its corresponding assignment deliverable. Export the chart as PNG and insert it into your SRS document.

Design Document — How the System Is Built

The Design Document is your second assignment and describes HOW your system works internally. Where the SRS said "the system shall classify chains," the Design Document explains what classes implement this, what database queries are used, how the UI is structured, and what the data flow looks like. The template you have been given contains eight sections.

Section 1 — Introduction to the Design Document

Describe what this document contains and why the Design phase matters in a software development project. Explain that design decisions made here — class structure, database access strategy, module dependencies — prevent costly mistakes during implementation. State which design standards you followed (IEEE 1016 for design documents, which CS504 Lectures 23–25 cover). Briefly list the eight sections of the document and summarize what each one contributes.

Section 2 — Entity Relationship Diagram (ERD)

The ERD shows the structure of your data — the tables in hadith-kg.db, their attributes, and the relationships between them. You must show all five tables: rawis, sanads, sanad_rawis, hadiths, and collections. For each table, show its primary key, all important attributes with their data types, and the foreign key relationships connecting the tables.

Section 3 — Sequence Diagrams

A Sequence Diagram shows the order of messages and method calls between objects during one specific use case. The template requires one sequence diagram per use case from your SRS. For your project, you should draw sequence diagrams for at minimum: loading the dataset, analyzing a chain (defect detection), classifying a chain (ML), and exporting a report.

Section 4 — Architecture Design Diagram

The Architecture Design shows how your system is organized into layers or tiers. For IsnadGuard, use a three-tier architecture: a Presentation Layer (the Streamlit dashboard the user sees), a Business Logic Layer (your Python modules — data loader, chain builder, defect detector, ML classifier, XAI explainer, report generator), and a Data Layer (the SQLite database). Show how these layers connect and which direction communication flows.

Section 5 — Class Diagram

The Class Diagram shows the object-oriented structure of your Python code — the classes, their attributes, their methods, and the relationships between them. This is one of the most important diagrams in the Design Document, and your supervisor will use it to verify that you have properly planned your code architecture before implementing it.

Section 6 — Database Design

This section goes deeper than the ERD — it provides the actual schema of the database you are using, including data types for every column, constraints (NOT NULL, PRIMARY KEY, FOREIGN KEY), and indexes. Since you are using an existing database (hadith-kg.db) rather than designing one from scratch, this section should document the relevant tables' exact schemas as they appear in the database, along with an explanation of how your application reads from each one. You can obtain the exact schema by running PRAGMA table_info(table_name) on each table in your exploration script.

Section 7 — Interface Design

Provide three to four screenshots or hand-drawn mockups of the most important screens in your application. For IsnadGuard, show: the data loading screen (file selector and summary panel), the chain analysis screen (search box, narrator list, defect report, chain graph), the ML and XAI screen (predicted grade, confidence, SHAP chart), and the export/report screen. These do not need to be final — you can update them in your Final Project submission if the actual implementation looks different.

Section 8 — Test Cases

Write test cases for each use case scenario from the SRS. Each test case must have: a test case ID, the use case it tests, pre-conditions, test input, expected output, and pass/fail criteria. For example, for the defect detection function: Input = chain with a known Munqati' gap (you can construct this from your exploration data); Expected Output = detect_munqati returns detected=True with the correct position; Pass Criteria = output matches expected and no exception is raised.

Prototype Assignment — What to Build and How to Submit

The Prototype assignment covers 30–40% of your total project work and corresponds to Modules 1 through 4. At the end of Semester 1, you must submit a working Python application that demonstrates the core data loading, chain construction, defect detection, and visualization pipeline using real hadith-kg data.

What Must Be Working in the Prototype

• Module 1: Application successfully connects to hadith-kg.db, loads narrator and chain data, displays a summary panel with total counts and grade distribution, and reports any records with missing data.
• Module 2: Given any valid chain ID, the application reconstructs the ordered narrator list with all required attributes.
• Module 3: The DefectDetector correctly identifies Munqati', Mu'dal, Mursal, Mawquf, and weak narrator defects. Test it on at least 10 different chains — 5 with known defects and 5 that are structurally sound.
• Module 4: The chain visualization renders a colored graph showing narrator grades and marking any broken links. Export works and produces a readable PNG image.

What You Submit

• A ZIP file (maximum 25 MB) containing all Python source files
• A README.txt file with step-by-step instructions to run your application — including which Python version, which libraries to install (with version numbers), and the exact command to start the application
• Do not include hadith-kg.db in the ZIP — it is too large. Your README must include instructions for downloading it
• Screenshots of each module working correctly — at least one screenshot per module
• Upload to VULMS under the Prototype Assignment submission

Final Deliverable — The Complete System

The Final Project submission is the complete, integrated, tested IsnadGuard system covering all eight modules. It must run as a single Streamlit application that a user can open, load the database, and use to analyze any chain in the dataset. Every module must be functional, tested, and connected to the others through the shared data layer.

Minimum Requirements for Full Marks

• All eight modules are complete and integrated into the Streamlit dashboard
• The ML classifier achieves at least 70% accuracy on the test set (20% holdout from hadith-kg)
• SHAP explanations are displayed for every chain classification
• The statistics dashboard (Module 5) shows at least four meaningful charts about the dataset
• PDF report generation works and produces a clean, readable document
• All code is in Python, organized into classes with proper docstrings and exception handling
• The application runs from a README.txt with a single command

What to Submit

• ZIP file with all Python source files, organized into a package structure
• A requirements.txt file listing every library with version numbers
• README.txt with complete installation and run instructions
• A sample PDF report generated by your application from a real chain
• Screenshots of every screen in the application

All Eight Modules — The Complete Picture

What You Will Learn From This Project

Most final year projects teach students one or two technical skills. This project covers the full spectrum of modern data science and AI engineering — from database querying through machine learning to explainability to deployment. Every module you complete adds a skill that is genuinely in demand, both in Pakistan's growing technology sector and in graduate-level academic work internationally.

The Bigger Picture

The dataset you are working with has been referenced in multiple peer-reviewed publications on Hadith narrator analysis. The specific combination your project implements — rule-based detection plus supervised ML plus SHAP explainability — has not been published as a complete system at the time this guide was written. If you complete all eight modules seriously and write your work up carefully, this project has genuine potential as a conference paper. Your supervisor can advise on publication pathways once the project is complete.

Self-Test Questions — Verify Your Understanding

The ten questions below are the type your supervisor is most likely to ask during the viva. Try each one in your own words before revealing the answer. If you can answer all ten fluently without referring to any notes, you are genuinely prepared for the viva. If there are questions you cannot answer, return to the relevant chapter before your viva date.