Metadata-Version: 2.4
Name: tarkib
Version: 2.0.0
Summary: Computational Philology, Sub-Lexical Algebraic Semantics, Jadwal & Iqtiran Arabic NLP SDK (Maqayis)
Author-email: Salah Abdo <Salah.Abdo.Tech@gmail.com>
License: Apache-2.0
Project-URL: Homepage, https://maqayis.org
Project-URL: Repository, https://github.com/maqayis/tarkib
Project-URL: Mirror, https://codeberg.org/maqayis/tarkib
Project-URL: Documentation, https://maqayis.org
Keywords: arabic,nlp,computational-philology,morphology,zero-llm,maqayis,tarkib
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Science/Research
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Natural Language :: Arabic
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Topic :: Text Processing :: Linguistic
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
License-File: NOTICE
Requires-Dist: numpy>=1.24
Requires-Dist: scipy>=1.10
Requires-Dist: scikit-learn>=1.3
Provides-Extra: hybrid
Requires-Dist: torch>=2.1; extra == "hybrid"
Requires-Dist: transformers>=4.40; extra == "hybrid"
Requires-Dist: sentence-transformers>=2.6; extra == "hybrid"
Dynamic: license-file

# Tarkīb (`تركيب`) v2.0.0 — هندسة اللسان العربي وجبر المعجم التحت-جذري

<div align="center">

**Computational Philology, Sub-Lexical Algebraic Semantics, & Zero-LLM Arabic NLP Engine**  
Part of the **Maqāyīs (`مَقاييس`)** Open-Source Ecosystem · [maqayis.org](https://maqayis.org) · [github.com/maqayis/tarkib](https://github.com/maqayis/tarkib)

[![License: Apache-2.0](https://img.shields.io/badge/Code-Apache--2.0-blue.svg)](LICENSE)
[![Data & Book: CC BY 4.0](https://img.shields.io/badge/Book%20%26%20Atlases-CC%20BY%204.0-teal.svg)](NOTICE)
[![Python 3.10+](https://img.shields.io/badge/Python-3.10%2B-3776AB.svg)](pyproject.toml)
[![Zero-LLM Ready](https://img.shields.io/badge/Mode-Zero--LLM%20%280%20Neural%20Params%29-success.svg)](DATA_PROVENANCE_BOM.md)

</div>

---

## نظرة عامّة | Overview

**`tarkib` (`تركيب` v2.0.0)** هو المحرّك الأساسي للفقه الحاسوبي وجبر الدلالة التحت-جذرية والصرف الريماني في منظومة **مَقاييس (`Maqāyīs`)** بقيادة المؤلّف **صلاح عبده (`Salah Abdo`)**. يعمل المحرّك في طوره الافتراضي **`mode="zero_llm"`** بصفر أوزان عصبية وباعتمادٍ نقيّ (`TARKIB_OPENITI_ONLY=1`) على خمسة معاجم تراثية عربية من المشاع العام تمتدّ عبر **1,035 سنة قمرية (`170–1205` هـ)**: *العين*، *الصحاح*، *مقاييس اللغة* لابن فارس، *لسان العرب*، و*تاج العروس*.

**`tarkib` (`v2.0.0`)** is the core computational-philology and sub-lexical algebraic Arabic NLP SDK of the **Maqāyīs (`مَقاييس`)** ecosystem by **Salah Abdo**. In its default `mode="zero_llm"`, `TarkibEngine` executes with **zero neural parameters** over a 256-dimensional spectral manifold constructed strictly from five pre-modern public-domain classical Arabic lexicons (`170–1205 AH`), packaged cleanly inside the Python wheel so every API works out of the box with zero external database setup.

---

## التثبيت السريع | Installation

```bash
pip install tarkib
# Or with uv:
uv add tarkib
```

Optional neural hybrid manifold (`intfloat/multilingual-e5-large` + PyTorch adapter):

```bash
pip install "tarkib[hybrid]"
```

---

## الاستخدام البرمجي الموحَّد (`v2.0.0` SDK) | Quickstart

```python
from tarkib import TarkibEngine

engine = TarkibEngine(mode="zero_llm")

# 1. Structural, kinematic, & Grassmannian Root X-Ray (`21,952` Sigma_28^3 cube)
xray = engine.inspect_root("كتب")

# 2. Zero-leakage Furūq near-synonym comparison
furuq = engine.compare_furuq("سنة", "عام")

# 3. Al-Jadwal Periodic Table of Arabic Roots (`11,249` roots across S0–S5 strata)
jadwal = engine.inspect_jadwal("كتب")

# 4. Iqtirān 66-Atom Morpho-Syntactic Phase-Coupling Algebra (`B01–B31 × R01–R35`)
iqtiran_all = engine.inspect_iqtiran()
iqtiran_fi = engine.inspect_iqtiran("في")

# 5. Paleographic undotted rasm Viterbi restoration (0% post-1205 AH anachronism)
rasm = engine.restore_rasm("ٮسم الله الرحمں الرحىم")

# 6. Six-Gate CI/CD Terminology & Localization Governance QA (legal/financial/technical)
qa = engine.terminology_qa("msgid \" Encryption\"\nmsgstr \"تعمية\"\n", fmt="po")
```

### Unified `TarkibEngine(mode="zero_llm")` Methods (`v2.0.0`)

| Method | Subsystem | Description |
| :--- | :--- | :--- |
| `inspect_root(token_or_root)` | **Tarkīb · Bayān · Burhān** | Full Root X-Ray across `21,952` cells (`((C1*C2)*C3)`, Sībawayhian 13-feature kinematics, Grassmannian fibers) |
| `inspect_jadwal(root)` | **Al-Jadwal (`الجدول`)** | Periodic Table lookup across `11,249` roots, `S0–S5` strata, `[C1C2_]` genera, and verified witnesses |
| `inspect_iqtiran(particle=None)` | **Iqtirān (`اقتران`)** | Closed `66`-atom morpho-syntactic algebra (`31` `B` × `35` `R` = `1,085` cells, `Delta_12`, Laws `ن١١–ن١٦`) |
| `compare_furuq(a, b, sentence=...)` | **Bayān (`بيان`)** | Zero-leakage contextual & intrinsic *Furūq* ranker (`rank_contextual_furuq`) |
| `audit_tashif(text)` | **Ījāz (`إيجاز`)** | Shannon guardband anti-*taṣḥīf* & `OCR/ASR` repair (`audit_tashif_and_ocr`) |
| `coin_term(concept_ar, ...)` | **Ījāz · Dīwān** | Six-gate scientific/technical/regulatory neologism coining (`coin_scientific_term`) |
| `tokenize_text(text)` | **Mīzān (`ميزان`)** | Non-concatenative `(proclitic, root_3, pattern_id, enclitic)` tokenizer (`0.0%` root fragmentation) |
| `fiber_rag(query, ...)` | **Burhān · Tayf** | Grassmannian fiber & metaphor-transport `T_majaz` retrieval (`search_fiber_rag`) |
| `restore_rasm(text, ...)` | **Paleography** | Exact Viterbi undotted *rasm* decoder over `170–1205 AH` lexicons (`restore_undotted_rasm`) |
| `audit_diachronic(text, ...)` | **Millennium Drift** | 5-epoch (`170→1205 AH`) semantic drift & anachronism detector (`audit_diachronic_anachronism`) |
| `terminology_qa(content, ...)` | **CI/CD Governance** | 6-gate localization QA for legal, financial, regulatory, & software pipelines (`SARIF 2.1.0`) |

---

## الحصيلة القياسية المجمّدة (`data/*.json`) | Frozen Empirical Benchmarks

All headline benchmarks are deterministically synchronized with `data/*.json` and verified by `pytest`:

- **First-Principles Vocal-Tract OCP Hamiltonian (`ocp_physics_derivation.json`):** Zero-corpus biomechanical Hamiltonian achieves **`0.8451`** out-of-fold AUROC across `6,963` pan-classical roots vs. **`0.7960`** for the unigram consonant-frequency baseline.
- **Grassmannian Fiber & Metaphor-Aware RAG (`fiber_rag_benchmark.json`):** Surgical `rigid_jamid_nominal` vs. `eventive_derived` isolation reaches **`53.03%`** `Precision@1` under strict `0%` non-root vocabulary overlap.
- **Paleographic Rasm Viterbi Restorer (`rasm_restorer_benchmark.json`):** Contextual Viterbi lattice decoding achieves **`+13.64`** percentage-point accuracy gain over unigram baselines on minimal-pair *rasm* traps with `0.00%` modern lexical intrusion.
- **Millennium Diachronic Anachronism Auditor (`diachronic_auditor_benchmark.json`):** Semantic calque detection achieves **`90.0%`** balanced accuracy with the classical calque atlas (`65.0%` fully unsupervised Leave-One-Root-Out graph coherence).
- **Six-Gate CI/CD Terminology QA (`terminology_qa_benchmark.json`):** Achieves **`98.04%`** `F1` across all 6 governance gates and **`97.67%`** `F1` under objective-defects-only policy on software, financial, regulatory, and legal localization suites.

---

## الواجهات التنفيذية (`CLI` · `MCP` · `Web Studio`) | Interfaces

```bash
# Command-line interface
tarkib inspect يستغفرون
tarkib qa-gate path/to/translations.po --fail-under 85

# Model Context Protocol (MCP) JSON-RPC 2.0 stdio server (11 tools)
tarkib-mcp --mode zero_llm

# Interactive RTL Web Studio
tarkib-studio --port 8765
```

---

## الترخيص ونسب المصادر | License & Provenance

- **Code (`Apache-2.0`):** Licensed under the [Apache License, Version 2.0](LICENSE).
- **Book & Public Linguistic Atlases (`CC BY 4.0`):** `book/`, `paper*/`, `papers_en/`, and `data/` are licensed under [Creative Commons Attribution 4.0 International (`CC BY 4.0`)](https://creativecommons.org/licenses/by/4.0/).
- **Provenance BOM:** See [`DATA_PROVENANCE_BOM.md`](DATA_PROVENANCE_BOM.md) and [`NOTICE`](NOTICE).
- **Copyright:** `Copyright 2026 Salah Abdo and successor entity`.
