git clone <repository-url> GLiNER_MultiLingual_PII_PHI
cd GLiNER_MultiLingual_PII_PHI

Windows (PowerShell):

pip install uv

Linux/macOS:

curl -LsSf https://astral.sh/uv/install.sh | sh

Or with pip:

pip install uv

Windows:

uv venv
.venv\Scripts\activate

Linux/macOS:

uv venv
source .venv/bin/activate

uv pip install -r requirements.txt

GLiNER_MultiLingual_PII_PHI/
├── src/
│   ├── main_service.py          # FastAPI service
│   └── streamlit_app.py         # Streamlit web UI for testing
├── data/
│   ├── data_gen.py              # Dataset generation script
│   ├── medical_phi_dataset.json # Medical PHI evaluation data
│   ├── mixed_language_dataset.json # Multilingual evaluation data
│   ├── ner_evaluation_dataset.json # NER evaluation dataset
│   ├── structured_pii_phi.csv   # Structured CSV evaluation data
│   └── travel_pii_dataset.json  # Travel PII evaluation data
├── evals/
│   ├── evaluation.py            # Evaluation script
│   ├── evaluation_service.py    # NER evaluation service
│   └── evaluation_report.json   # Generated evaluation report
├── tests/
│   └── test_extraction.py       # Pytest test cases
├── screenshots/                 # UI screenshots
├── requirements.txt             # Python dependencies
├── README.md                    # This file
└── .venv/                       # Virtual environment

Or with uvicorn directly:

cd src && uvicorn main_service:app --host 127.0.0.1 --port 8000 --reload

You should see:

INFO:     Loading GLiNER PII model...
INFO:     Model loaded successfully
INFO:     Uvicorn running on http://127.0.0.1:8000
INFO:     Application startup complete.

Option A: Open API Docs in Browser

http://127.0.0.1:8000/docs

Option B: Test with curl (Linux/macOS/Windows)

# Health check
curl http://127.0.0.1:8000/health

# Extract PII
curl -X POST "http://127.0.0.1:8000/extract" \
  -H "Content-Type: application/json" \
  -d '{"text":"John Smith email is john@test.com and phone is 555-123-4567"}'

Option C: Test with PowerShell (Windows)

# Health check
Invoke-RestMethod -Uri "http://127.0.0.1:8000/health"

# Extract PII
$body = '{"text":"John Smith email is john@test.com and phone is 555-123-4567"}'
Invoke-RestMethod -Uri "http://127.0.0.1:8000/extract" -Method Post -Body $body -ContentType "application/json"

Option D: Streamlit Web UI

For an interactive web interface, run the Streamlit app:

# Make sure the FastAPI service is running first, then:
python -m streamlit run src/streamlit_app.py

Open http://localhost:8501 in your browser.

Request:

{
  "text": "Contact John Smith at john.smith@email.com or call 555-123-4567",
  "threshold": 0.5
}

Response:

{
  "entities": [
    {"text": "John Smith", "label": "person", "start": 8, "end": 18, "score": 0.98},
    {"text": "john.smith@email.com", "label": "email", "start": 22, "end": 42, "score": 0.99},
    {"text": "555-123-4567", "label": "phone number", "start": 51, "end": 63, "score": 0.96}
  ],
  "text": "Contact John Smith at john.smith@email.com or call 555-123-4567",
  "entity_count": 3,
  "entity_types": {"person": 1, "email": 1, "phone number": 1}
}

• Model: urchade/gliner_multi_pii-v1
• Size: ~1.16 GB
• Base Model: microsoft/mdeberta-v3-base

Cache Location:

# Set custom Hugging Face cache directory
export HF_HOME=/path/to/cache  # Linux/macOS
set HF_HOME=C:\path\to\cache   # Windows

# Disable symlinks (Windows - fixes download errors)
set HF_HUB_DISABLE_SYMLINKS_WARNING=1

FROM python:3.11-slim

WORKDIR /app
COPY requirements.txt .
RUN pip install uv && uv pip install --system -r requirements.txt

COPY main_service.py .
EXPOSE 8000

CMD ["uvicorn", "main_service:app", "--host", "0.0.0.0", "--port", "8000"]

Build and run:

docker build -t gliner-pii .
docker run -p 8000:8000 gliner-pii

# Activate virtual environment
# Windows:
.venv\Scripts\activate
# Linux/macOS:
source .venv/bin/activate

# Run all tests
python -m pytest tests/test_extraction.py -v

# Run specific test class
python -m pytest tests/test_extraction.py::TestPersonExtraction -v

# Run multilingual tests
python -m pytest tests/test_extraction.py::TestMultilingualParagraphs -v

# Run with short traceback
python -m pytest tests/test_extraction.py -v --tb=short

The Streamlit app provides an interactive interface for testing the PII extraction service:

Features

• Service Health Check - Real-time connection status to the FastAPI backend
• Configurable Threshold - Slider to adjust detection sensitivity (0.0-1.0)
• Entity Type Selection - Choose specific PII/PHI types or select all
• Sample Texts - Pre-loaded examples (Medical Record, Financial Document, Business Contact, International Document)
• Results Display - Summary metrics, entity breakdown, and detailed entity list with confidence scores
• Highlighted Text View - Visual color-coded highlighting of detected entities
• Raw JSON Output - Expandable section with the full API response

Running the Streamlit App

Windows:

# Terminal 1: Start FastAPI service
python src/main_service.py

# Terminal 2: Start Streamlit app
python -m streamlit run src/streamlit_app.py

Linux/macOS:

# Terminal 1: Start FastAPI service
source .venv/bin/activate
python src/main_service.py

# Terminal 2: Start Streamlit app
source .venv/bin/activate
python -m streamlit run src/streamlit_app.py

Screenshot

The UI includes:

• Left panel: Input text area with sample text selector
• Right panel: Extraction results with entity details
• Bottom: Highlighted text with color-coded entities and legend

To add the screenshot: Run the Streamlit app, take a screenshot, and save it as screenshots/streamlit_app.png

• evaluation_service.py → Creates detailed evaluation_report.json with language breakdowns and failure analysis
• evaluation.py → Creates per-dataset predictions_*.csv and predictions_*.json files in data/predicted_output/ with raw predictions

# Run the main evaluation script (generates prediction files for all datasets)
python evals/evaluation.py

# Run the NER evaluation service with detailed report
python evals/evaluation_service.py --dataset data/ner_evaluation_dataset.json --output evals/evaluation_report.json --verbose

This project includes tools for generating synthetic test datasets.

Data Generation (data_gen.py)

Generate synthetic multilingual NER datasets for testing PII/PHI extraction.

Features:

• 30 template variations per language for diverse sentence structures
• 50 positive samples per language (sentences with PII entities)
• 10 negative samples per language (clean sentences without PII)
• 30 entity types with realistic synthetic data
• Automatic position tracking for entity spans

Usage:

python data/data_gen.py

Output: ner_evaluation_dataset.json with 360 samples (300 positive, 60 negative)

Dataset Format:

{
  "language": "English",
  "text": "Patient John Doe, born 15/03/1985, diagnosed with Diabetes Type 2...",
  "entities": [
    {"text": "John Doe", "label": "person", "start": 8, "end": 16},
    {"text": "15/03/1985", "label": "date_of_birth", "start": 23, "end": 33},
    {"text": "Diabetes Type 2", "label": "medical_condition", "start": 50, "end": 65}
  ]
}

• ✅ phone_number / email - Highly reliable across all contexts
• ✅ passport_number - Strong performance (0.90+)
• ✅ medical_condition - Excellent in medical/structured contexts

• ⚠️ person - Variable performance (0.57-1.00) depending on context
• ⚠️ address - Poor in travel context, excellent in structured data
• ❌ student_id_number - Not recognized by model
• ❌ transaction_number - Inconsistent across datasets

1. Organization over-detection: Model tends to identify non-organization text as organizations
2. Student ID not recognized: Model doesn't support student_id_number label
3. Address extraction in travel: Struggles with complex international addresses
4. ID format confusion: Various national ID formats get misclassified