Update README.md

README.md

@@ -1,3 +1,91 @@
----
-license: apache-2.0
----
+---
+license: apache-2.0
+---
+
+<table>
+  <tr>
+    <td width="80">
+      <img src="assets/ner_logo.png" alt="NER Logo" width="80"/>
+    </td>
+    <td>
+      <h1 style="margin: 0; padding: 0;">German Named Entity Recognition (GERMANER)</h1>
+    </td>
+  </tr>
+</table>
+
+
+<p align="center">
+  <em>Robust 7-class NER model for the German language, built on <code>xlm-roberta-large</code> with LoRA optimization.</em>
+</p>
+
+---
+
+## 🔍 Overview
+
+**GermanER** is a high-performance Named Entity Recognition (NER) model tailored for the German language. It combines the multilingual power of `xlm-roberta-large` with **Parameter-Efficient Fine-Tuning (PEFT)** using **LoRA**, delivering strong results on both in-domain and out-of-domain German datasets.
+
+This model is fine-tuned on a hybrid dataset composed of:
+
+- [GermEval 2014](https://www.kaggle.com/datasets/rtatman/germaneval2014-ner)
+- [WikiANN (de)](https://huggingface.co/datasets/wikiann)
+
+---
+
+## 🏷️ Label Schema
+
+The model uses a standard BIO tagging format with 7 labels:
+
+| Tag    | Entity Type                            |
+|--------|----------------------------------------|
+| B-PER  | Beginning of a person entity           |
+| I-PER  | Inside a person entity                 |
+| B-ORG  | Beginning of an organization entity    |
+| I-ORG  | Inside an organization entity          |
+| B-LOC  | Beginning of a location entity         |
+| I-LOC  | Inside a location entity               |
+| O      | Outside any named entity               |
+
+---
+
+## 📈 Performance
+
+Evaluated on a combined test set (GermEval + WikiANN):
+
+| Metric              | Value     |
+|---------------------|-----------|
+| **F1 Score**        | 0.8062    |
+| **Accuracy**        | 95.28%    |
+| **Validation Loss** | 0.1841    |
+| **Training Samples**| 44,000    |
+| **Epochs**          | 1         |
+
+---
+
+## 🧠 Model Architecture
+
+- **Base Model**: [`xlm-roberta-large`](https://huggingface.co/xlm-roberta-large)
+- **Fine-Tuning Strategy**: PEFT with LoRA
+- **LoRA Details**:
+  - `r=16`, `alpha=32`, `dropout=0.1`
+  - Applied to: Query, Key, and Value projection layers
+- **Sequence Length**: 128 tokens
+- **Precision**: Mixed-precision (fp16)
+
+---
+
+## 🔗 Usage
+
+```python
+from transformers import AutoTokenizer, AutoModelForTokenClassification
+from transformers import pipeline
+
+model_id = "zamal/GermaNER"
+
+tokenizer = AutoTokenizer.from_pretrained(model_id)
+model = AutoModelForTokenClassification.from_pretrained(model_id)
+
+ner_pipeline = pipeline("ner", model=model, tokenizer=tokenizer, aggregation_strategy="simple")
+
+text = "Angela Merkel war die Bundeskanzlerin von Deutschland."
+entities = ner_pipeline(text)
+print(entities)