Metadata-Version: 2.4
Name: arabic-sentencizer
Version: 0.1.1
Summary: Arabic sentence splitter and text statistics tool for NLP preprocessing.
Author: Faisal Alshargi
License: MIT
Project-URL: Homepage, https://www.sanaa.ai
Project-URL: Repository, https://github.com/alshargi/arabic-sentencizer
Keywords: arabic,nlp,sentence-splitting,tokenization,sentencizer
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Natural Language :: Arabic
Classifier: Topic :: Text Processing :: Linguistic
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Operating System :: OS Independent
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: nltk>=3.8
Dynamic: license-file

# Arabic Sentencizer

A lightweight Arabic sentence segmentation and text analytics toolkit designed for Arabic NLP pipelines, Information Retrieval systems, Large Language Models (LLMs), corpus processing, data annotation workflows, and Retrieval-Augmented Generation (RAG) applications.

Arabic Sentencizer addresses common challenges in Arabic sentence boundary detection while preserving important linguistic and technical patterns such as abbreviations, URLs, emails, decimal numbers, and version identifiers.

---

## Features

* Arabic sentence segmentation
* URL-aware sentence splitting
* Email-aware sentence splitting
* Decimal number preservation (`1.5`, `95.5`, `١.٩`)
* Version number preservation (`v2.1.5`)
* Arabic abbreviation handling (`د.`, `أ.د.`, `م.`)
* Arabic punctuation support (`؟`, `؛`, `!`)
* Text statistics and analytics
* NLP preprocessing support
* Corpus preparation and annotation workflows
* Information Retrieval preprocessing
* RAG chunking preparation
* Human-readable text analysis reports

---

## Installation

Install from PyPI:

```bash
pip install arabic-sentencizer
```

For local development:

```bash
pip install -e .
```

---

## Quick Start

### Sentence Segmentation

```python
from arabic_sentencizer import split_sentences

text = """
د. أحمد وصل إلى الاجتماع الساعة 10.30 صباحاً.
ثم قال إن نسبة النجاح بلغت 95.5%.
زار الموقع https://www.sanaa.ai ثم انتقل إلى bbc.com.
"""

sentences = split_sentences(text)

for i, sentence in enumerate(sentences, start=1):
    print(i, sentence)
```

Output:

```text
1 د. أحمد وصل إلى الاجتماع الساعة 10.30 صباحاً.
2 ثم قال إن نسبة النجاح بلغت 95.5%.
3 زار الموقع https://www.sanaa.ai ثم انتقل إلى bbc.com.
```

---

## Real Example

```python
from arabic_sentencizer import split_sentences, analyze_text, print_report

text = """
د. أحمد محمد، أستاذ الذكاء الاصطناعي في جامعة القاهرة، أعلن اليوم عن إصدار جديد من منصة التحليل اللغوي. الإصدار الحالي هو v2.1.5 بينما كان الإصدار السابق v2.0.9 فقط.

قال أ.د. محمد علي: "لقد حققنا نتائج ممتازة في معالجة اللغة العربية." وأضاف أن دقة النظام وصلت إلى 95.7% مقارنة بـ 88.4% العام الماضي.

يمكن للباحثين زيارة الموقع الرسمي:
https://www.sanaa.ai

كما يمكنهم مراجعة الوثائق عبر:
https://docs.sanaa.ai/api/v1.5/index.html

للتواصل مع فريق التطوير يرجى إرسال رسالة إلى:
research@sanaa.ai

بلغ عدد الوثائق المعالجة أكثر من 1.5 مليون وثيقة. كما تم تحليل 125.456.789 كلمة عربية خلال مرحلة الاختبار.

هل يمكن استخدام النظام في تطبيقات البحث الدلالي؟
نعم! يدعم النظام البحث الدلالي والبحث التقليدي معاً.

ممتاز؛ لننتقل الآن إلى تقييم النتائج.

شارك في المشروع كل من:
د. فيصل الشرقي
أ.د. محمود الأحمد
م. خالد السالم

وقد تم نشر النتائج في عدة مؤتمرات منها AAAI 2025 و ACL 2024 و EMNLP 2023.

زار الفريق مواقع مثل bbc.com و wikipedia.org و github.com أثناء جمع البيانات.

وأشار التقرير النهائي إلى أن متوسط زمن الاستجابة بلغ 0.35 ثانية فقط. بينما انخفض زمن الفهرسة من 12.5 ساعة إلى 4.2 ساعة بعد تحسين الخوارزمية.

قال أحد المراجعين:
"هذه من أفضل الأدوات مفتوحة المصدر لمعالجة النصوص العربية."

هل ستتم إضافة دعم للهجات العربية مستقبلاً؟
بالتأكيد. تشمل الخطة القادمة دعم اللهجات الخليجية والشامية والمصرية واليمنية.

شكراً لجميع المساهمين!
"""

print_report(text)
```

Output:

```text
Arabic Text Analysis Report
===================================
Sentences: 18
Words: 242
Arabic Words: 193
Unique Words: 190
Characters: 1342
Characters without spaces: 1115
Lines: 24
URLs: 6
Emails: 1
Decimal / Version Numbers: 10
Questions: 2
Exclamations: 2
Average Words per Sentence: 13.44
Max Words in a Sentence: 44
Min Words in a Sentence: 1
```

This example demonstrates support for:

* Arabic abbreviations (`د.`, `أ.د.`, `م.`)
* URLs and domains
* Email addresses
* Decimal numbers
* Version numbers
* Questions and exclamations
* Arabic punctuation
* Text analytics

---

## Text Analytics

```python
from arabic_sentencizer import analyze_text

stats = analyze_text(text)

print(stats["sentences"])
print(stats["words"])
print(stats["top_words"])
```

---

## Human-Readable Report

```python
from arabic_sentencizer import print_report

print_report(text)
```

---

## API

### Split Sentences

```python
split_sentences(text: str) -> list[str]
```

Returns a list of segmented Arabic sentences.

### Analyze Text

```python
analyze_text(text: str) -> dict
```

Returns a dictionary containing text statistics and extracted information.

### Print Report

```python
print_report(text: str) -> None
```

Prints a human-readable summary report.

---

## Supported Cases

### Arabic Abbreviations

```text
د. أحمد محمد
أ.د. محمد علي
م. خالد السالم
```

### URLs

```text
https://www.sanaa.ai
https://docs.sanaa.ai/api/v1.5/index.html
bbc.com
github.com
wikipedia.org
```

### Emails

```text
research@sanaa.ai
```

### Decimal Numbers

```text
1.5
95.7
88.4
0.35
12.5
4.2
١.٩
```

### Version Numbers

```text
v2.1.5
v2.0.9
```

### Arabic Punctuation

```text
؟
!
؛
```

---

## Text Statistics

The `analyze_text()` function returns:

| Statistic                  | Description                  |
| -------------------------- | ---------------------------- |
| characters                 | Total characters             |
| characters_no_spaces       | Characters excluding spaces  |
| lines                      | Number of non-empty lines    |
| sentences                  | Number of detected sentences |
| words                      | Total words                  |
| arabic_words               | Arabic words only            |
| unique_words               | Unique word count            |
| urls                       | Number of URLs               |
| emails                     | Number of emails             |
| decimal_or_version_numbers | Decimal and version numbers  |
| questions                  | Number of questions          |
| exclamations               | Number of exclamations       |
| avg_words_per_sentence     | Average sentence length      |
| max_words_sentence         | Longest sentence length      |
| min_words_sentence         | Shortest sentence length     |
| long_sentences             | Long sentences               |
| short_sentences            | Short sentences              |
| top_words                  | Most frequent words          |
| sentences_list             | All detected sentences       |
| urls_list                  | Extracted URLs               |
| emails_list                | Extracted emails             |
| numbers_list               | Extracted numbers            |

---

## Use Cases

* Arabic NLP preprocessing
* Corpus preparation
* Dataset annotation
* Information Retrieval
* Search engines
* Retrieval-Augmented Generation (RAG)
* LLM pipelines
* Arabic content analytics
* Text mining
* Digital humanities research
* Academic research projects

---

## Author

### Dr. Faisal Alshargi
