radlab-pii-classification 0.1.0__tar.gz

radlab_pii_classification-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 radlab.dev
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

radlab_pii_classification-0.1.0/PKG-INFO

@@ -0,0 +1,155 @@
+Metadata-Version: 2.4
+Name: radlab-pii-classification
+Version: 0.1.0
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: pandas
+Requires-Dist: xlsxwriter
+Requires-Dist: seqeval
+Requires-Dist: sacremoses
+Requires-Dist: flask_cors
+Requires-Dist: radlab-ml-utils>=1.0.0
+Dynamic: license-file
+
+# PII Classification Model
+
+This project provides a complete pipeline for Named Entity Recognition (NER) focused on identifying Personally
+Identifiable Information (PII) in Polish text. It includes utilities for data conversion, label generalization, model
+training using Hugging Face Transformers, and a deployment-ready Flask API with a simple web interface.
+
+**Repository**:
+[https://github.com/radlab-dev-group/anonymizer-model](https://github.com/radlab-dev-group/anonymizer-model)
+
+## Features
+
+- **Data Processing CLI**: Tools to convert CONLL/IOB formats to JSONL, generalize labels, and generate distribution
+  reports.
+- **Training Pipeline**: A configurable trainer based on `AutoModelForTokenClassification` with Weights & Biases (W&B)
+  integration.
+- **Advanced Inference**: A predictor that handles sub-token merging, punctuation cleaning, and gap preservation to
+  return human-readable entities.
+- **REST API**: A Flask-based service to serve multiple model versions with optional dynamic quantization for faster
+  inference.
+- **Web Tester**: A lightweight HTML/JS interface for real-time PII detection testing.
+
+## Installation
+
+Ensure you have Python $\ge$ 3.9 installed.
+
+```textmate
+git clone https://github.com/radlab-dev-group/anonymizer-model.git
+cd anonymizer-model
+pip install .
+```
+
+## Data Preparation
+
+The project is designed to work with datasets like `clarin-pl/kpwr-ner`.
+
+1. **Download Dataset**: Store IOB files in `dataset/kpwr/raw/`.
+2. **Convert to JSONL**:
+
+```textmate
+pii-classifier convert \
+     -i dataset/kpwr/raw/kpwr-ner-n82-train-tune.iob \
+     -o dataset/kpwr/converted/specific/kpwr-ner-n82-train-tune.jsonl
+
+
+pii-classifier convert \
+     -i dataset/kpwr/raw/kpwr-ner-n82-test.iob \
+     -o dataset/kpwr/converted/specific/kpwr-ner-n82-test.jsonl
+```
+
+3. **Generalize Labels**:
+   Map fine-grained labels to general categories using a mapping file (e.g., `config/mappings/kpwr-ner.json`).
+
+```textmate
+pii-classifier generalise \
+     -i dataset/kpwr/converted/specific/kpwr-ner-n82-train-tune.jsonl \
+     dataset/kpwr/converted/specific/kpwr-ner-n82-test.jsonl \
+     -m config/mappings/kpwr-ner.json \
+     -o dataset/kpwr/converted/generalised/kpwr-ner-general-whole.jsonl
+```
+
+4. **Generate Report**:
+   Create an Excel report to analyze class distribution.
+
+```textmate
+pii-classifier report \
+     -i dataset/kpwr/converted/generalised/kpwr-ner-general-whole.jsonl \
+     -o dataset/kpwr/converted/generalised/kpwr-ner-general-whole-report.xlsx
+```
+
+## Training
+
+Training is driven by a JSON configuration file located in `config/training/`.
+
+To start training, run the training script:
+
+```textmate
+python pii_classification/trainer/train.py
+```
+
+**Key Training Features:**
+
+- **Configurable**: Hyperparameters (learning rate, batch size, epochs) are managed via `kpwr-ner-config.json`.
+- **W&B Integration**: Logs metrics and hyperparameters to Weights & Biases.
+- **Automatic Export**: Saves the best model (based on `f1_macro`) into a `final_model` directory.
+
+## Inference & API
+
+### Running the API
+
+The API allows you to load multiple model versions and perform predictions.
+
+```textmate
+python3 -m pii_classification.api.app
+```
+
+**Endpoints:**
+
+- `GET /models`: Returns a list of available models and the default model.
+- `POST /predict`: Accepts JSON with `text` and optional `model` name. Returns a list of tokens and their predicted PII
+  labels.
+
+### Web Interface (under development)
+
+Open `pii_classification/ui/index.html` in a browser to interact with the API. The UI allows you to select a model,
+input Polish text, and see highlighted PII entities.
+
+Or simple python-like http server:
+
+```bash
+cd anonymizer-model/pii_classification/ui
+python3 -m http.server
+
+>> Serving HTTP on 0.0.0.0 port 8000 (http://0.0.0.0:8000/) ...
+```
+
+## CLI Reference
+
+The `pii-classifier` command provides the following sub-commands:
+
+| Command      | Description                        | Required Arguments                                |
+|:-------------|:-----------------------------------|:--------------------------------------------------|
+| `convert`    | Convert CONLL/IOB file to JSONL    | `-i` (input), `-o` (output)                       |
+| `generalise` | Map labels using a JSON map        | `-i` (input files), `-m` (mapping), `-o` (output) |
+| `report`     | Generate Excel distribution report | `-i` (input files), `-o` (output)                 |
+
+## Project Structure
+
+```plain text
+├── config/
+│   ├── mappings/       # Label mapping JSONs
+│   └── training/       # Training hyperparameter configs
+├── pii_classification/
+│   ├── analysis/       # Label generalization and reporting logic
+│   ├── api/            # Flask API implementation
+│   ├── cli/            # CLI entry point
+│   ├── converters/     # Format conversion utilities
+│   ├── inference/      # Model prediction and post-processing logic
+│   ├── trainer/        # Training scripts and data processors
+│   └── ui/             # Frontend tester (HTML/JS)
+└── pyproject.toml      # Project dependencies and metadata
+```

radlab_pii_classification-0.1.0/README.md

@@ -0,0 +1,141 @@
+# PII Classification Model
+
+This project provides a complete pipeline for Named Entity Recognition (NER) focused on identifying Personally
+Identifiable Information (PII) in Polish text. It includes utilities for data conversion, label generalization, model
+training using Hugging Face Transformers, and a deployment-ready Flask API with a simple web interface.
+
+**Repository**:
+[https://github.com/radlab-dev-group/anonymizer-model](https://github.com/radlab-dev-group/anonymizer-model)
+
+## Features
+
+- **Data Processing CLI**: Tools to convert CONLL/IOB formats to JSONL, generalize labels, and generate distribution
+  reports.
+- **Training Pipeline**: A configurable trainer based on `AutoModelForTokenClassification` with Weights & Biases (W&B)
+  integration.
+- **Advanced Inference**: A predictor that handles sub-token merging, punctuation cleaning, and gap preservation to
+  return human-readable entities.
+- **REST API**: A Flask-based service to serve multiple model versions with optional dynamic quantization for faster
+  inference.
+- **Web Tester**: A lightweight HTML/JS interface for real-time PII detection testing.
+
+## Installation
+
+Ensure you have Python $\ge$ 3.9 installed.
+
+```textmate
+git clone https://github.com/radlab-dev-group/anonymizer-model.git
+cd anonymizer-model
+pip install .
+```
+
+## Data Preparation
+
+The project is designed to work with datasets like `clarin-pl/kpwr-ner`.
+
+1. **Download Dataset**: Store IOB files in `dataset/kpwr/raw/`.
+2. **Convert to JSONL**:
+
+```textmate
+pii-classifier convert \
+     -i dataset/kpwr/raw/kpwr-ner-n82-train-tune.iob \
+     -o dataset/kpwr/converted/specific/kpwr-ner-n82-train-tune.jsonl
+
+
+pii-classifier convert \
+     -i dataset/kpwr/raw/kpwr-ner-n82-test.iob \
+     -o dataset/kpwr/converted/specific/kpwr-ner-n82-test.jsonl
+```
+
+3. **Generalize Labels**:
+   Map fine-grained labels to general categories using a mapping file (e.g., `config/mappings/kpwr-ner.json`).
+
+```textmate
+pii-classifier generalise \
+     -i dataset/kpwr/converted/specific/kpwr-ner-n82-train-tune.jsonl \
+     dataset/kpwr/converted/specific/kpwr-ner-n82-test.jsonl \
+     -m config/mappings/kpwr-ner.json \
+     -o dataset/kpwr/converted/generalised/kpwr-ner-general-whole.jsonl
+```
+
+4. **Generate Report**:
+   Create an Excel report to analyze class distribution.
+
+```textmate
+pii-classifier report \
+     -i dataset/kpwr/converted/generalised/kpwr-ner-general-whole.jsonl \
+     -o dataset/kpwr/converted/generalised/kpwr-ner-general-whole-report.xlsx
+```
+
+## Training
+
+Training is driven by a JSON configuration file located in `config/training/`.
+
+To start training, run the training script:
+
+```textmate
+python pii_classification/trainer/train.py
+```
+
+**Key Training Features:**
+
+- **Configurable**: Hyperparameters (learning rate, batch size, epochs) are managed via `kpwr-ner-config.json`.
+- **W&B Integration**: Logs metrics and hyperparameters to Weights & Biases.
+- **Automatic Export**: Saves the best model (based on `f1_macro`) into a `final_model` directory.
+
+## Inference & API
+
+### Running the API
+
+The API allows you to load multiple model versions and perform predictions.
+
+```textmate
+python3 -m pii_classification.api.app
+```
+
+**Endpoints:**
+
+- `GET /models`: Returns a list of available models and the default model.
+- `POST /predict`: Accepts JSON with `text` and optional `model` name. Returns a list of tokens and their predicted PII
+  labels.
+
+### Web Interface (under development)
+
+Open `pii_classification/ui/index.html` in a browser to interact with the API. The UI allows you to select a model,
+input Polish text, and see highlighted PII entities.
+
+Or simple python-like http server:
+
+```bash
+cd anonymizer-model/pii_classification/ui
+python3 -m http.server
+
+>> Serving HTTP on 0.0.0.0 port 8000 (http://0.0.0.0:8000/) ...
+```
+
+## CLI Reference
+
+The `pii-classifier` command provides the following sub-commands:
+
+| Command      | Description                        | Required Arguments                                |
+|:-------------|:-----------------------------------|:--------------------------------------------------|
+| `convert`    | Convert CONLL/IOB file to JSONL    | `-i` (input), `-o` (output)                       |
+| `generalise` | Map labels using a JSON map        | `-i` (input files), `-m` (mapping), `-o` (output) |
+| `report`     | Generate Excel distribution report | `-i` (input files), `-o` (output)                 |
+
+## Project Structure
+
+```plain text
+├── config/
+│   ├── mappings/       # Label mapping JSONs
+│   └── training/       # Training hyperparameter configs
+├── pii_classification/
+│   ├── analysis/       # Label generalization and reporting logic
+│   ├── api/            # Flask API implementation
+│   ├── cli/            # CLI entry point
+│   ├── converters/     # Format conversion utilities
+│   ├── inference/      # Model prediction and post-processing logic
+│   ├── trainer/        # Training scripts and data processors
+│   └── ui/             # Frontend tester (HTML/JS)
+└── pyproject.toml      # Project dependencies and metadata
+```

radlab_pii_classification-0.1.0/pii_classification/analysis/jsonl_generalise_labels.py

@@ -0,0 +1,68 @@
+import sys
+import json
+import argparse
+
+from .label_generalizer import load_mapping, generalize_label
+
+
+def analyze_pii_distribution(input_files, mapping_path, output_path):
+    mapping = load_mapping(mapping_path)
+    all_labels = []
+    mapped_records = []
+
+    print(f"Loading files: {input_files}...")
+
+    try:
+        for file_path in input_files:
+            with open(file_path, "r", encoding="utf-8") as f:
+                for line in f:
+                    if not line.strip():
+                        continue
+                    data = json.loads(line)
+                    original_labels = data.get("labels", [])
+                    all_labels.extend(original_labels)
+
+                    mapped_labels = [
+                        generalize_label(l, mapping) for l in original_labels
+                    ]
+                    data["labels"] = mapped_labels
+                    mapped_records.append(data)
+
+        if not all_labels:
+            print("Error: No labels found.")
+            return
+
+        total_tokens = len(all_labels)
+        print(f"Analysis complete. Found {total_tokens} tokens.")
+
+        # Write converted dataset
+        print(f"Saving converted dataset to: {output_path}")
+        with open(output_path, "w", encoding="utf-8") as out_f:
+            for record in mapped_records:
+                out_f.write(json.dumps(record, ensure_ascii=False) + "\n")
+
+        print("Conversion and saving completed successfully.")
+    except Exception as e:
+        print(f"An error occurred: {e}")
+        sys.exit(1)
+
+
+def main():
+    parser = argparse.ArgumentParser(
+        description="Generalize PII labels using a JSON map and output a converted JSONL file."
+    )
+    parser.add_argument(
+        "-i", "--input", nargs="+", required=True, help="Paths to JSONL files"
+    )
+    parser.add_argument(
+        "-m", "--mapping", required=True, help="Path to the mapping JSON file"
+    )
+    parser.add_argument(
+        "-o", "--output", required=True, help="Path to output converted .jsonl file"
+    )
+    args = parser.parse_args()
+    analyze_pii_distribution(args.input, args.mapping, args.output)
+
+
+if __name__ == "__main__":
+    main()

radlab_pii_classification-0.1.0/pii_classification/analysis/label_generalizer.py

@@ -0,0 +1,31 @@
+import json
+import re
+import sys
+
+from pathlib import Path
+
+
+def load_mapping(mapping_path: str | Path) -> dict:
+    """Load a JSON mapping file."""
+    try:
+        with open(mapping_path, "r", encoding="utf-8") as f:
+            return json.load(f)
+    except Exception as e:
+        print(f"Error loading mapping file: {e}")
+        sys.exit(1)
+
+
+def generalize_label(label: str, mapping: dict) -> str:
+    """Map a BIO‑prefixed label to its high‑level category."""
+    if label == "O":
+        return "O"
+    base_label = re.sub(r"^[BI]-", "", label)
+    for prefix, category in mapping.items():
+        if base_label.startswith(prefix):
+            return category
+    return "MISC"
+
+
+def strip_bio_prefix(label: str) -> str:
+    """Remove the B‑/I‑ prefix; keep 'O' unchanged."""
+    return label if label == "O" else re.sub(r"^[BI]-", "", label)

radlab_pii_classification-0.1.0/pii_classification/analysis/labels_distribution_report.py

@@ -0,0 +1,164 @@
+"""
+PII Class Distribution Analyzer
+------------------------------
+This script reads one or multiple JSONL files containing NER labels,
+calculates the distribution of each class, and generates a formatted
+Excel report. It provides both a detailed BIO-tag distribution and
+a grouped class summary.
+
+Example usage:
+    python analyzer.py -i train.jsonl val.jsonl -o report.xlsx
+"""
+
+import json
+import argparse
+import pandas as pd
+from collections import Counter
+import sys
+import re
+
+
+def strip_bio_prefix(label):
+    """
+    Removes B- or I- prefix from NER labels to get the base class.
+    Example: 'B-nam_org_company' -> 'nam_org_company', 'O' -> 'O'
+    """
+    if label == "O":
+        return "O"
+    return re.sub(r"^[BI]-", "", label)
+
+
+def analyze_pii_distribution(input_files, output_excel):
+    """
+    Reads JSONL files, counts NER labels, and generates a formatted
+    Excel report with two sheets: Full Distribution and Class Summary.
+    """
+    all_labels = []
+
+    print(f"Loading files: {input_files}...")
+
+    try:
+        for file_path in input_files:
+            with open(file_path, "r", encoding="utf-8") as f:
+                for line in f:
+                    if not line.strip():
+                        continue
+                    data = json.loads(line)
+                    all_labels.extend(data.get("labels", []))
+
+        if not all_labels:
+            print("Error: No labels found in the provided files.")
+            return
+
+        # --- 1. Full Distribution (Exact labels) ---
+        full_counts = Counter(all_labels)
+        df_full = pd.DataFrame(full_counts.items(), columns=["Label", "Count"])
+        df_full = df_full.sort_values(by="Count", ascending=False).reset_index(
+            drop=True
+        )
+        total_tokens = df_full["Count"].sum()
+        df_full["Percentage"] = (df_full["Count"] / total_tokens * 100).round(
+            2
+        ).astype(str) + "%"
+
+        # --- 2. Class Summary (Grouped B/I labels) ---
+        grouped_labels = [strip_bio_prefix(l) for l in all_labels]
+        group_counts = Counter(grouped_labels)
+        df_grouped = pd.DataFrame(group_counts.items(), columns=["Class", "Count"])
+        df_grouped = df_grouped.sort_values(by="Count", ascending=False).reset_index(
+            drop=True
+        )
+        df_grouped["Percentage"] = (df_grouped["Count"] / total_tokens * 100).round(
+            2
+        ).astype(str) + "%"
+
+        print(f"Analysis complete. Found {total_tokens} tokens.")
+
+        # --- Excel Export ---
+        writer = pd.ExcelWriter(output_excel, engine="xlsxwriter")
+
+        df_full.to_excel(writer, sheet_name="Full Distribution", index=False)
+        df_grouped.to_excel(writer, sheet_name="Class Summary", index=False)
+
+        workbook = writer.book
+
+        header_format = workbook.add_format(
+            {
+                "bold": True,
+                "text_wrap": True,
+                "valign": "top",
+                "fg_color": "#D7E4BC",
+                "border": 1,
+            }
+        )
+        cell_format = workbook.add_format({"border": 1})
+
+        for sheet_name, df in [
+            ("Full Distribution", df_full),
+            ("Class Summary", df_grouped),
+        ]:
+            worksheet = writer.sheets[sheet_name]
+
+            for col_num, value in enumerate(df.columns.values):
+                worksheet.write(0, col_num, value, header_format)
+
+            for row_num in range(1, len(df) + 1):
+                for col_num in range(len(df.columns)):
+                    val = df.iloc[row_num - 1, col_num]
+                    worksheet.write(row_num, col_num, val, cell_format)
+
+        # --- Chart Generation (Based on Class Summary, excluding 'O') ---
+        df_chart = df_grouped[df_grouped["Class"] != "O"].reset_index(drop=True)
+        chart_data_sheet_name = "ChartData"
+        df_chart.to_excel(writer, sheet_name=chart_data_sheet_name, index=False)
+        writer.sheets[chart_data_sheet_name].hide()
+
+        chart = workbook.add_chart({"type": "column"})
+        chart.add_series(
+            {
+                "name": "Occurrences",
+                "categories": [chart_data_sheet_name, 1, 0, len(df_chart), 0],
+                "values": [chart_data_sheet_name, 1, 1, len(df_chart), 1],
+                "fill": {"color": "#4F81BD"},
+            }
+        )
+
+        chart.set_title({"name": "PII Class Distribution (excluding Outside)"})
+        chart.set_x_axis({"name": "PII Class"})
+        chart.set_y_axis({"name": "Count"})
+        chart.set_style(11)
+
+        summary_sheet = writer.sheets["Class Summary"]
+        summary_sheet.insert_chart("E2", chart, {"x_scale": 1.5, "y_scale": 1.5})
+
+        writer.close()
+        print(f"Report successfully saved to: {output_excel}")
+
+    except FileNotFoundError as e:
+        print(f"Error: {e}")
+        sys.exit(1)
+    except json.JSONDecodeError:
+        print("Error: One of the files is not in a valid JSONL format.")
+        sys.exit(1)
+    except Exception as e:
+        print(f"An unexpected error occurred: {e}")
+        sys.exit(1)
+
+
+def main():
+    parser = argparse.ArgumentParser(
+        description="Analyze class distribution from JSONL files and generate an Excel report."
+    )
+    parser.add_argument(
+        "-i", "--input", nargs="+", required=True, help="Paths to JSONL files"
+    )
+    parser.add_argument(
+        "-o", "--output", required=True, help="Path to the output .xlsx file"
+    )
+
+    args = parser.parse_args()
+    analyze_pii_distribution(args.input, args.output)
+
+
+if __name__ == "__main__":
+    main()

radlab_pii_classification-0.1.0/pii_classification/api/app.py

@@ -0,0 +1,96 @@
+import os
+
+from flask_cors import CORS
+from flask import Flask, request, jsonify
+
+from pii_classification.inference.inference import AnonPredictor
+
+
+ANON_API_PORT = int(os.getenv("ANON_API_PORT", 5001))
+ANON_API_DEBUG = os.getenv("ANON_API_DEBUG", "false").lower() in ("1", "true", "yes")
+
+
+app = Flask(__name__)
+CORS(app)  # Enable CORS for UI interaction
+
+# ----------------------------------------------------------------------
+# Model registry
+# ----------------------------------------------------------------------
+MODEL_PATHS = {
+    "radlab/pii-pl-v1.0": "radlab/pii-pl-v1.0",
+}
+
+USE_QUANTIZATION = True
+
+# Load a predictor for every model at startup
+PREDICTORS = {
+    name: AnonPredictor(model_path=path, use_quantized=USE_QUANTIZATION)
+    for name, path in MODEL_PATHS.items()
+}
+
+# Choose a default model – the first one in the dict
+DEFAULT_MODEL = next(iter(PREDICTORS))
+
+
+# ----------------------------------------------------------------------
+# API: return the list of available model names
+# ----------------------------------------------------------------------
+@app.route("/models", methods=["GET"])
+def list_models():
+    return jsonify({"models": list(PREDICTORS.keys()), "default": DEFAULT_MODEL})
+
+
+# ----------------------------------------------------------------------
+# API: predict – optionally receive the model name to use
+# ----------------------------------------------------------------------
+@app.route("/predict", methods=["POST"])
+def predict():
+    data = request.json or {}
+    text = data.get("text", "")
+    model_name = data.get("model", DEFAULT_MODEL)
+
+    if not text:
+        return jsonify({"error": "No text provided"}), 400
+
+    if model_name not in PREDICTORS:
+        return jsonify({"error": f"Model '{model_name}' not found"}), 400
+
+    predictor = PREDICTORS[model_name]
+
+    try:
+        predictions = predictor.predict(
+            text=text, clean_punct=True, merge_entities=True, handle_gaps=True
+        )
+        return jsonify({"model": model_name, "predictions": predictions})
+    except Exception as e:
+        return jsonify({"error": str(e)}), 500
+
+
+# ----------------------------------------------------------------------
+# API: predict_and_anonymize – replace entities with tags
+# ----------------------------------------------------------------------
+@app.route("/predict_and_anonymize", methods=["POST"])
+def predict_and_anonymize():
+    data = request.json or {}
+    text = data.get("text", "")
+    model_name = data.get("model", DEFAULT_MODEL)
+    labels = data.get("labels", [])
+
+    if not text:
+        return jsonify({"error": "No text provided"}), 400
+
+    if model_name not in PREDICTORS:
+        return jsonify({"error": f"Model '{model_name}' not found"}), 400
+
+    predictor = PREDICTORS[model_name]
+
+    try:
+        result = predictor.predict_and_anonymize(text=text, labels=labels)
+        return jsonify({"model": model_name, **result})
+    except Exception as e:
+        return jsonify({"error": str(e)}), 500
+
+
+# ----------------------------------------------------------------------
+if __name__ == "__main__":
+    app.run(host="0.0.0.0", port=ANON_API_PORT, debug=ANON_API_DEBUG)