Metadata-Version: 2.5
Name: manhaj
Version: 2.0.0
Summary: Manhaj (مَنْهَج) — Open-Source Arabic Scientific Mastery Academy & Zero-Custody BYOK Runtime (Maqāyīs)
Project-URL: Homepage, https://maqayis.org/manhaj/
Project-URL: Repository, https://github.com/maqayis/manhaj
Project-URL: Mirror, https://codeberg.org/maqayis/manhaj
Project-URL: Documentation, https://maqayis.org/manhaj/
Author-email: Salah Abdo <Salah.Abdo.Tech@gmail.com>
License: Apache-2.0
License-File: LICENSE
License-File: NOTICE
Requires-Python: >=3.11
Requires-Dist: beautifulsoup4>=4.12
Requires-Dist: pydantic>=2.7
Provides-Extra: llm
Requires-Dist: dspy<3.3,>=3.2.1; extra == 'llm'
Requires-Dist: mlflow>=3.0; extra == 'llm'
Description-Content-Type: text/markdown

# مَنْهَج (`Manhaj`) — أكاديمية الإتقان العلمي العربي المفتوحة

**Open-Source Arabic Scientific Mastery Academy & Zero-Custody BYOK Runtime**  
Part of the **[Maqāyīs (`مَقاييس`)](https://maqayis.org)** Computational Arabic Linguistics Ecosystem · **[Live Academy (`maqayis.org/manhaj/`)](https://maqayis.org/manhaj/)** · **[GitHub (`maqayis/manhaj`)](https://github.com/maqayis/manhaj)** · **[Codeberg Mirror](https://codeberg.org/maqayis/manhaj)**

[![License: Code Apache-2.0](https://img.shields.io/badge/Code-Apache%202.0-1d4ed8.svg)](LICENSE)
[![License: Curriculum CC BY 4.0](https://img.shields.io/badge/Curriculum-CC%20BY%204.0-b45309.svg)](NOTICE)

---

## نبذة بالعربية | Overview

**مَنْهَج (`Manhaj`)** منصّةُ إتقانٍ علميّ مفتوحةُ المصدر، صُمِّمت لتدريس اللسانيات الحاسوبية العربية ورياضياتها التأسيسية بالعربية الفصحى الرصينة، مرافِقةً لكتاب **«هندسة اللسان العربي: الفيزياء الصوتية، الجبر الجذري، والتركيب الدلالي» (`الإصدار 2.0`)**.

Unlike passive lecture portals, **Manhaj** models curriculum as a **validated prerequisite Directed Acyclic Graph (DAG)** with deterministic pedagogical gates:
1. **Two Interlinked Tracks (`23` Rigorous Arabic Units, `305` Standardized Glossary Terms, `107` Course KB Documents):**
   - **`cl-nlp-handasat-allisan` (`19` Core Units):** Triliteral Root & Morphological *Mīzān*, Sībawayh Vocal-Tract Kinematics, Blind Delexicalization & Leakage-Free Evaluation, Spherical Semantic Manifold & CSLS, Zero-LLM Spectral Graph & Nyström, Stasheff Associahedron & Tree-Cut Subtraction, Riemannian Tangent Space & Geodesic Maps, Grassmannian Subspaces & Jordan Angles, Conjugate vMF & Epistemic Concentration, Positional Coherence Hierarchy, Sub-Root Composition & Mendeleev Table, Two-Scale Merge & Tree-Cut Hierarchy, Riemannian Morphological Operators, Vocal-Tract Kinematics & Qur'anic Two-Regime Law, Differential Geometry of Qur'anic *Furūq*, Zero-LLM Proof & Empirical-Bayes vMF, Grassmannian Fiber Bundles & *Jāmid* Excision, Riemannian Metaphor Transport, and Sub-Morphemic Lexical Compression (*ʾĪjāz*).
   - **`math-handasat-allisan` (`4` Active `L1` Mathematical Foundation Units):** Set Theory & Inclusion–Exclusion (`M1.1`), Combinatorics, Equivalence Quotients & Stasheff Trees (`M1.2`), Vector Spaces, Inner Products & Discrete Kinematics (`M2.1`), and Probability, Bayes, Expectation & Logarithms (`M5.1`).
2. **4-Pillar *Explain-Back* Mastery Defense (`دفاع الفهم`):**
   - Learners unlock downstream nodes on the Knowledge Fringe (`حافة المعرفة`) by defending each concept in their own Arabic prose across four explicit criteria: **Definition (`P-Def`)**, **Mathematical Formulation (`P-Math`)**, **Empirical Evidence (`P-Emp`)**, and **Computational Realization (`P-Code`)**, with a deterministic 25-word floor before any LLM call is invoked.
3. **Zero-Custody Browser Runtime (`$0/mo` Static Hosting + BYOK `OpenRouter PKCE`):**
   - Runs 100% statically on Cloudflare Pages (`portal/public/manhaj/` at `https://maqayis.org/manhaj/`) with local-first `IndexedDB` persistence, morphological root search, grapheme-cluster-safe Arabic text anchoring, a Guided-Mode **Solution ACL Firewall** (`403` until an exercise is explicitly revealed in the active unit), and **RFC 7636 OAuth PKCE** (`OpenRouter` Bring-Your-Own-Key) where credentials never touch Maqāyīs servers.
4. **Double-Scrubbed Opt-In Research Telemetry (`Misbar` Spine):**
   - Strictly local-only (`Tier 0`) by default; optional anonymous research traces (`POST /api/v1/traces`) apply client-side + edge regex redaction (`[REDACTED_API_KEY]`, `[REDACTED_EMAIL]`, `[REDACTED_PHONE]`) and 1-click cryptographic right-to-erasure (`DELETE /api/v1/traces`).

---

## Repository Structure

| Path | Description | License |
|------|-------------|---------|
| `concepts/<concept-id>/` | Validated concept dossiers (`dossier.md`) + published Arabic lessons (`lessons/*.md`) | `CC BY 4.0` |
| `graph/` | Prerequisite concept graph (`edges.tsv`, `tracks/*.tsv`, `map.md`) | `CC BY 4.0` |
| `fields/` & `fihris/` | Field charters (`cl-nlp.md`), bilingual terminology glossaries, and bibliographic registry | `CC BY 4.0` |
| `corpus/` | Grounded Arabic corpus slices and deterministic terminology extraction tools | `Apache-2.0` / `CC BY 4.0` |
| `pipeline/validate.py` | Deterministic 14-gate curriculum, terminology, math, and provenance validator | `Apache-2.0` |
| `learner/kb/` | Arabic grapheme-safe document parser, morphological root search, and verification suites | `Apache-2.0` |
| `learner/ui/` | RTL Arabic single-page learner application, BYOK `ai-engine.js`, `public-runtime.js`, and local `serve.py` | `Apache-2.0` |
| `deploy/build_public_site.py` | Static SEO & subpath-capable compiler (`333` RTL HTML pages + `static-api/` + `llms.txt` + `sitemap.xml`) | `Apache-2.0` |
| `deploy/verify_public_deployment.py` | End-to-end 5-suite verification harness (Python + Node 22 + SQLite `Misbar` bridge) | `Apache-2.0` |

---

## Quickstart

### 1. Build the Static Public Academy (`/manhaj` Subpath or Root Domain)

```bash
# Build integrated under Maqāyīs Portal (/manhaj subpath + shared /api/v1/traces):
uv run --no-project python deploy/build_public_site.py \
  --out dist \
  --base-url https://maqayis.org/manhaj \
  --trace-endpoint /api/v1/traces \
  --hub-url /

# Serve locally to inspect static bundle:
python3 -m http.server 8080 --directory dist
```

### 2. Run the Local Interactive Learner Server (Offline / Dev Mode)

```bash
uv run --no-project python learner/ui/serve.py --port 8765 --learner student
```

### 3. Run All Curriculum & Public Deployment Verification Gates

```bash
# Validate curriculum lessons across both tracks:
uv run --no-project python pipeline/validate.py --concept triliteral-root-and-mizan
uv run --no-project python pipeline/validate.py --concept set-theory-and-inclusion-exclusion --track math-handasat-allisan

# Run the full 5-suite end-to-end public deployment verification (Python + Node 22):
uv run --no-project python deploy/verify_public_deployment.py
```

---

## Citation & Licensing

- **Platform, Compiler, & Runtime Code:** Licensed under the **Apache License 2.0** ([`LICENSE`](LICENSE)).
- **Curriculum, Lessons, Concept Dossiers, & Glossaries:** Licensed under **Creative Commons Attribution 4.0 International (`CC BY 4.0`)** ([`NOTICE`](NOTICE)).
- **Author:** Salah Abdo (`صلاح عبده`) — `<Salah.Abdo.Tech@gmail.com>` ([Maqāyīs Organization](https://github.com/maqayis)).

```bibtex
@software{abdo2026manhaj,
  author    = {Abdo, Salah},
  title     = {{Manhaj}: Open Arabic Scientific Mastery Academy and Zero-Custody {BYOK} Runtime},
  year      = {2026},
  version   = {1.0.0},
  publisher = {Maq\={a}y\={\i}s},
  url       = {https://maqayis.org/manhaj/},
  note      = {Code: Apache-2.0; Curriculum: CC BY 4.0}
}
```
