README.md

---
language:
- tr
license: apache-2.0
tags:
- encoderfile
- medical
- token-classification
- ner
- turkish
- bert
- mammography
library_name: encoderfile
metrics:
- accuracy
- f1
- precision
- recall
pipeline_tag: token-classification
base_model:
- ahmetcangunay/MammoTagger
- akdeniz27/bert-base-turkish-cased-ner
---

# 🩺 MammoTagger: Turkish Mammography NER (.encoderfile)

[![Encoderfile Standard](https://img.shields.io/badge/Format-Encoderfile-orange)](https://github.com/mozilla-ai/encoderfile)
[![Architecture](https://img.shields.io/badge/Architecture-BERT%20Turkish%20NER-blue)](#)
[![License](https://img.shields.io/badge/License-Apache%202.0-green.svg)](LICENSE)
[![Base Model](https://img.shields.io/badge/Base%20Model-ahmetcangunay/MammoTagger-yellow)](https://huggingface.co/ahmetcangunay/MammoTagger)

This repository contains a standalone, zero-dependency executable binary (`.encoderfile`) built with [Mozilla AI's Encoderfile](https://github.com/mozilla-ai/encoderfile) specification. Fine-tuned from [ahmetcangunay/MammoTagger](https://huggingface.co/ahmetcangunay/MammoTagger), it is designed for Named Entity Recognition (NER) on Turkish mammography reports.

> 🏆 **TEKNOFEST Achievement:** Developed as part of the project that achieved **5th Place & Finalist** status in the **TEKNOFEST 2024 Sağlıkta Yapay Zekâ Yarışması (Üniversite ve Üzeri Seviyesi - Bilgisayarlı Görüyle Hastalık Tespiti Kategorisi)**.

---

## 🚀 Quick Start / Instant CLI Usage

You can download and run this executable directly on any x86_64 Linux machine without installing Python, PyTorch, Transformers, or SpaCy.

### 1. Download & Prepare Binary

```bash
# Download the executable via Hugging Face CLI
hf download ahmetcangunay/MammoTagger_encoderfile mammo-tagger.x86_64-unknown-linux-gnu.encoderfile --local-dir .

# Make it executable
chmod +x mammo-tagger.x86_64-unknown-linux-gnu.encoderfile
```

### 2. Direct CLI Token Inference (infer)
```bash
./mammo-tagger.x86_64-unknown-linux-gnu.encoderfile infer "BILATERAL MAMOGRAFI INCELEMESI: Sağ meme üst dış kadranda yaklaşık 1 cm çapında düzgün sınırlı nodüler lezyon izlendi."
```

#### Example Response:
```json
{
  "results": [
    {
      "tokens": [
        {
          "token_info": { "token": "Sağ", "token_id": 3644, "start": 32, "end": 36 },
          "label": "B-ANAT",
          "score": 7.4060626
        },
        {
          "token_info": { "token": "meme", "token_id": 13135, "start": 37, "end": 41 },
          "label": "I-ANAT",
          "score": 7.988982
        },
        {
          "token_info": { "token": "yaklaşık", "token_id": 3870, "start": 62, "end": 72 },
          "label": "B-OBS-PRESENT",
          "score": 6.614647
        },
        {
          "token_info": { "token": "1", "token_id": 21, "start": 73, "end": 74 },
          "label": "I-OBS-PRESENT",
          "score": 6.538508
        }
      ]
    }
  ],
  "model_id": "mammo-tagger",
  "metadata": {}
}
```

## 🌐 Serving Options

### REST API Server (serve)

Start a lightweight local REST server:

```bash
./mammo-tagger.x86_64-unknown-linux-gnu.encoderfile serve --http-port 8080
```

### Anthropic MCP Server (mcp)

Start as a Model Context Protocol (MCP) server for integration with LLM agents:

```bash
./mammo-tagger.x86_64-unknown-linux-gnu.encoderfile mcp
```

## 📊 Model Performance & Metrics

Evaluated on an independent test dataset of 257 clinical mammography report sentences (18,893 total evaluated tokens):

- Overall Accuracy: 93.14%

- Weighted F1-Score: 0.9308

- Macro Average F1-Score: 0.9254

| Category       | Precision | Recall | F1-Score | Support |
|----------------|-----------|--------|----------|---------|
| ANAT           | 0.9479    | 0.9919 | 0.9694   | 5416    |
| IMPRESSION     | 0.9960    | 0.9861 | 0.9910   | 502     |
| O              | 0.9466    | 0.8684 | 0.9058   | 6268    |
| OBS-ABSENT     | 0.9297    | 0.9627 | 0.9460   | 2227    |
| OBS-PRESENT    | 0.8868    | 0.9277 | 0.9068   | 4368    |
| OBS-UNCERTAIN  | 0.8654    | 0.8036 | 0.8333   | 112     |

## 🏷️ Entity Types

- ANAT: Anatomical regions (e.g., sağ meme, üst dış kadran)
- IMPRESSION: Overall clinical conclusion / summary notes
- OBS-PRESENT: Present findings (e.g., nodül, kitle, mikrokalsifikasyon)
- OBS-ABSENT: Negative findings / Absence of findings (e.g., kitle saptanmadı)
- OBS-UNCERTAIN: Doubtful / Suspicious findings (e.g., şüpheli görünüm)
- O: Outside / Non-entity tokens

## ⚙️ Technical Details

- Base Architecture: ahmetcangunay/MammoTagger (Fine-tuned from akdeniz27/bert-base-turkish-cased-ner)
- Runtime: Standalone CPU Executable (Rust/C++ Bindings via Mozilla Encoderfile)
- Tagging Scheme: IOB2 (B-*, I-*, O)
- Target OS: x86_64-unknown-linux-gnu