README.md

---
language:
  - ar
license: apache-2.0
pipeline_tag: token-classification
library_name: spacy
tags:
  - arabic
  - named-entity-recognition
  - ner
  - finance
  - financial-ner
  - spacy
  - information-extraction
  - ontology-aligned
datasets:
  - custom
model-index:
  - name: AMWAL
    results:
      - task:
          type: token-classification
          name: Named Entity Recognition
        dataset:
          name: Arabic Financial News Corpus
          type: custom
        metrics:
          - type: precision
            value: 0.9608
          - type: recall
            value: 0.9587
          - type: f1
            value: 0.9597
    paper:
      title: "AMWAL: Named Entity Recognition for Arabic Financial News"
      authors:
        - Muhammad S. Abdo
        - Yash Hatekar
        - Damir Cavar
      conference: "FinNLP / FNP / LLMFinLegal Workshop (2025)"
      year: 2025
      url: https://aclanthology.org/2025.finnlp-1.20
---

## 📄 Associated Paper

This model is described in the following paper:

**AMWAL: Named Entity Recognition for Arabic Financial News**  
Muhammad S. Abdo, Yash Hatekar, Damir Cavar  

ACL Anthology: https://aclanthology.org/2025.finnlp-1.20


# AMWAL: Arabic Financial Named Entity Recognition (NER)

## Quick Start

### Install (recommended)

```bash
pip install git+https://huggingface.co/Muhsabrys/AMWAL_ArFinNER
```

```python
from amwal import load_ner

ner = load_ner()

text = "يطرح البنك المركزي المصري، بعد غد، سندات خزانة ثابتة ومتغيرة العائد بقيمة 45 مليار جنيه"
result = ner(text)

print(result["entities"])
```

---

## Model Summary

**AMWAL** is a **spaCy-based Named Entity Recognition (NER) system** designed for extracting **financial entities from Arabic text**, with a primary focus on **Arabic financial news and reports**.

The model addresses challenges specific to Arabic financial NLP, including orthographic variation, domain-specific terminology, and the scarcity of annotated financial resources for Arabic.

---

## Intended Use

AMWAL is intended for:

* Arabic financial news analysis
* Information extraction from financial reports
* Financial text preprocessing
* Academic research in Arabic NLP and finance
* Data enrichment for financial knowledge graphs

It is **not intended** for:

* General-purpose Arabic NER
* Non-financial domains
* Direct use with Hugging Face Transformers APIs

---

## Data Collection and Annotation

A specialized Arabic financial corpus was constructed from **three major Arabic financial newspapers**, covering the period **2000–2023**.

The annotation process followed a **semi-automatic workflow**:

1. Automatic candidate entity extraction
2. Manual annotation
3. Expert review and correction

The final dataset contains:

* **17.1K annotated entity tokens**
* **21 financial entity categories**
* Consistent domain coverage across multiple time periods

---

## Entity Schema and Standardization

Entity categories were standardized using concepts from the
**Financial Industry Business Ontology (FIBO, 2020)** to ensure conceptual consistency and compatibility with structured financial representations.

---

## Model Architecture and Training

* **Framework:** spaCy
* **Pipeline:** Custom Named Entity Recognition (NER)
* **Domain:** Arabic financial text

The model was trained on the annotated corpus using spaCy’s NER pipeline.
To mitigate sparsity caused by Arabic orthographic variation, normalization was applied consistently during training and inference.

---

## Arabic Normalization

The following normalization steps are applied **internally during inference**, matching the training setup:

* Removal of all diacritics
* Character normalization:

  * `إ`, `أ`, `آ` → `ا`
  * `ؤ`, `ئ` → `ء`
  * `ة` → `ه`
  * `ى` → `ي`

The original input text is always preserved and returned as `raw_text`.

---

## Entity Types

The model recognizes **21 financial entity types**, including (but not limited to):

* `COUNTRY`
* `CITY`
* `CURRENCY`
* `FINANCIAL_INSTRUMENT`
* `BANK`
* `ORGANIZATION`
* `NATIONALITY`
* `EVENT`
* `TIME`
* `QUANTITY_OR_UNIT`

---

## Evaluation Results

The model was evaluated on a held-out test set using standard NER metrics:

| Metric    | Score      |
| --------- | ---------- |
| Precision | **96.08%** |
| Recall    | **95.87%** |
| F1-score  | **95.97%** |

These results are competitive with reported financial NER systems in other languages, despite the additional challenges posed by Arabic morphology and orthography.

---

## Usage

AMWAL supports **two officially supported usage modes**.

### Option 1 — Install via `pip` (recommended)

```bash
pip install git+https://huggingface.co/Muhsabrys/AMWAL_ArFinNER
```

```python
from amwal import load_ner

ner = load_ner()
result = ner("يطرح البنك المركزي المصري، بعد غد، سندات خزانة ثابتة ومتغيرة العائد بقيمة 45 مليار جنيه")
print(result["entities"])
[{'text': 'البنك المركزي المصري', 'label': 'BANK', 'start': 5, 'end': 25}, {'text': 'سندات', 'label': 'FINANCIAL_INSTRUMENT', 'start': 35, 'end': 40}, {'text': '45 مليار', 'label': 'QUNATITY_OR_UNIT', 'start': 74, 'end': 82}, {'text': 'جنيه', 'label': 'CURRENCY', 'start': 83, 'end': 87}]

```

---

### Option 2 — Use directly from Hugging Face (no installation)

```python
from huggingface_hub import snapshot_download
import sys

repo_path = snapshot_download("Muhsabrys/AMWAL_ArFinNER")
sys.path.append(repo_path)

from amwal import load_ner

ner = load_ner(local_path=repo_path)
result = ner("الصادرات البترولية المصرية ترتفع إلى 3.6 مليار دولار خلال 9 أشهر")
print(result["entities"])
```

---

## Output Format

```json
{
  "entities_in_order": [
    {
      "text": "الصادرات",
      "label": "Events",
      "start": 1,
      "end": 9
    },
    {
      "text": "البتروليه",
      "label": "PRODUCT_OR_SERVICE",
      "start": 10,
      "end": 19
    },
    {
      "text": "المصريه",
      "label": "NATIONALITY",
      "start": 20,
      "end": 27
    },
    {
      "text": "ترتفع",
      "label": "Events",
      "start": 28,
      "end": 33
    },
    {
      "text": "مليار",
      "label": "QUNATITY_OR_UNIT",
      "start": 42,
      "end": 47
    },
    {
      "text": "دولار",
      "label": "CURRENCY",
      "start": 48,
      "end": 53
    }
  ]
}
```

---

## Limitations

* Domain-specific to financial text
* Not suitable for general-purpose Arabic NER
* Does not model relations between entities
* Not compatible with Hugging Face Transformers APIs

---

## Future Work

Planned future directions include:

* Expanding the annotated corpus
* Introducing hierarchical entity structures
* Modeling relations between financial entities
* Constructing an Arabic financial knowledge graph

---

## Citation

```bibtex
@inproceedings{abdo2025amwal,
  title={AMWAL: Named Entity Recognition for Arabic Financial News},
  author={Abdo, Muhammad S and Hatekar, Yash and {\'C}avar, Damir},
  booktitle={Proceedings of the Joint Workshop of the 9th Financial Technology and Natural Language Processing (FinNLP), the 6th Financial Narrative Processing (FNP), and the 1st Workshop on Large Language Models for Finance and Legal (LLMFinLegal)},
  pages={207--213},
  year={2025}
}
```