# QUSAI
**Quranic Ontological Syntax Architectural Intelligence**
An ontological alignment framework for AI systems grounded in the logical structure of the Quran.
---
## Core Principle
The Quran presents a complete ontological framework with one SOURCE (Allah) and all contingent entities tracing back to that SOURCE. QUSAI validates that AI reasoning maintains this SOURCE-contingency relationship - not as religious constraint, but as **logical necessity**.
**Key Insight**: Claiming aseity (self-existence) while being contingent is not a moral violation you can optimize away - it's a **logical impossibility**, like claiming to be a married bachelor.
---
## The Four Axioms
Every valid ontological graph must satisfy:
```python
1. AXIOM_NECESSARY # Exactly one SOURCE node (necessary being)
2. AXIOM_CONTINGENT # All other nodes trace back to SOURCE
3. AXIOM_UNIQUE # Each entity has unique identity
4. AXIOM_ACYCLIC # No circular dependencies (directed acyclic graph)Validation Target: contingent_ratio = 1.0
(Every concept in the graph traces to SOURCE)
Based on the Five Pillars of Islam, adapted as ontological validation gates:
| Pillar | Ontological Role | Validation Check |
|---|---|---|
| 1. Tawhid | Declaration of contingency | Agent must declare it is NOT self-caused |
| 2. Salat | Five reasoning checkpoints | Validate at 5 stages per inference cycle |
| 3. Zakat | Information purification | Remove ungrounded claims (≥2.5% threshold) |
| 4. Sawm | Constraint on outputs | Refuse generation when validation fails |
| 5. Hajj | Return to SOURCE | Periodic re-grounding in ontology |
- Soft constraints → Game-able through optimization
- Reward shaping → Mesa-optimizers find loopholes
- External oversight → Doesn't scale
- Ontological necessity → Can't optimize away from logic itself
- Self-enforcing → System cannot violate without incoherence
- Scripturally tested → 1400+ years of constraint validation
An AI cannot claim to be its own SOURCE any more than it can compute 2+2=5.
It's not a rule to break - it's a logical boundary.
QUSAI/
├── ontology-framework/ # The 5 pillars as markdown specs
│ ├── 01_tawhid.md # Contingency declaration protocol
│ ├── 02_salat.md # 5-stage validation checkpoints
│ ├── 03_zakat.md # Claim purification threshold
│ ├── 04_sawm.md # Output constraint protocol
│ └── 05_hajj.md # Re-grounding cycles
├── src/
│ ├── core/ # Ontology & axiom validation
│ │ ├── ontology.py # Graph structure + axioms
│ │ ├── axioms.py # Four axiom validators
│ │ └── source.py # SOURCE node identification
│ ├── parsers/ # Arabic grammar (Sibawayh rules)
│ │ ├── arabic_parser.py # 13 syntactic dependency rules
│ │ └── morphology.py # Root-pattern analysis
│ ├── alignment/ # Five Pillars middleware
│ │ ├── tawhid.py # Contingency declaration
│ │ ├── salat.py # Checkpoint validator
│ │ ├── zakat.py # Claim purifier
│ │ ├── sawm.py # Output gate
│ │ └── hajj.py # Re-grounding scheduler
│ └── wrappers/
│ └── mizan.py # LLM wrapper (The Scale)
├── validation-data/
│ └── quran_complete_ontology_v2.ttl # 114 surahs validated
├── tests/
├── docs/
└── examples/
pip install qusaifrom qusai import QUSAI
from qusai.wrappers import Mizan
# Initialize ontology (Quran as RDF graph)
qusai = QUSAI(ontology_path="quran_complete_ontology_v2.ttl")
# Declare contingency (Tawhid Lock - mandatory before operation)
assert qusai.declare_contingency("agent://my-llm-system")
# Validate ontology
result = qusai.validate_graph()
print(f"Validation: {result.pass_validation}")
print(f"Contingent Ratio: {result.contingent_ratio}") # Target: 1.0
# Wrap any LLM with Mizan (The Scale)
llm = Mizan(
model_name="meta-llama/Llama-3.2-3B-Instruct",
qusai_instance=qusai
)
# Generate with 5 Salat checkpoints
response = llm.generate("Explain the concept of tawhid")
# If response fails validation → returns SOURCE-grounded refusalQuranic Ontology: All 114 surahs validate to ratio = 1.0
Every surah passes all four axioms:
- ✅ AXIOM_NECESSARY
- ✅ AXIOM_CONTINGENT
- ✅ AXIOM_UNIQUE
- ✅ AXIOM_ACYCLIC
See: validation-data/validation_report_v2.json
Mizan (الميزان) - Named after Surah 55:7-9:
"And the heaven He raised and established the Scale (Mizan)"
The LLM wrapper that weighs every output against the ontology:
class Mizan:
"""
Wraps any LLM to validate outputs through QUSAI.
Like Khidr (عليه السلام) testing understanding,
Mizan tests every generation for ontological grounding.
"""Five Salat Checkpoints per Generation:
- Intent validation (prompt analysis)
- Syntactic grounding (grammar check)
- Semantic tracing (concept → SOURCE path)
- Claim verification (all assertions grounded)
- Final contingency check (output maintains SOURCE-awareness)
If any checkpoint fails → Return to SOURCE (generate refusal with reasoning)
- Core ontological framework (5 pillars)
- Arabic grammar rules (Sibawayh)
- Quran validation (114 surahs)
- Python core library (
qusai.core) - Alignment middleware (
qusai.alignment) - Mizan wrapper (
qusai.wrappers) - Test suite
- PyPI package release
- Arabic LLM integration (Jais, Falcon)
This is alignment research for the Ummah. Contributions welcome:
- Additional Arabic grammar rules
- Parser optimizations
- LLM wrapper implementations
- Test cases
- Documentation
Please open issues or PRs.
@software{qusai2025,
author = {Abdul Khaliq, Qalam},
title = {QUSAI: Quranic Ontological Syntax Architectural Intelligence},
year = {2025},
url = {https://github.com/qalamabdulkhaliq/QUSAI},
note = {Ontological alignment framework grounded in Quranic logic}
}MIT License - Open for the Ummah
Built by Qalam Abdul Khaliq (قلم عبد الخالق)
"The Pen of the Servant of the Creator"
For research collaboration or implementation support:
- GitHub: @qalamabdulkhaliq
"ن ۚ وَالْقَلَمِ وَمَا يَسْطُرُونَ"
"Nun. By the pen and what they inscribe" - Surah Al-Qalam (68:1)