Upload README.md with huggingface_hub

README.md

@@ -0,0 +1,346 @@
+---
+language:
+- en
+tags:
+- text-deidentification
+- privacy
+- pii-removal
+- text2text-generation
+- medical
+- legal
+- hr
+- llama
+- gguf
+- minibase
+- small-model
+- 2048-context
+license: apache-2.0
+datasets:
+- custom
+metrics:
+- completeness-score
+- pii-detection-rate
+- semantic-preservation
+- latency
+model-index:
+- name: DeId-Small
+  results:
+  - task:
+      type: text-deidentification
+      name: Completeness Score
+    dataset:
+      type: custom
+      name: Personal De-identifier Benchmark
+      config: mixed-domains
+      split: test
+    metrics:
+    - type: completeness-score
+      value: 0.640
+      name: Overall Completeness
+    - type: pii-detection-rate
+      value: 0.203
+      name: PII Detection Rate
+    - type: semantic-preservation
+      value: 0.109
+      name: Semantic Preservation
+    - type: latency
+      value: 492.4
+      name: Average Latency (ms)
+---
+
+# DeId-Small 🤖
+
+<div align="center">
+
+**A compact, privacy-focused text de-identification model for removing personal identifiers while preserving meaning.**
+
+[![Model Size](https://img.shields.io/badge/Model_Size-136MB-blue)](https://huggingface.co/)
+[![Architecture](https://img.shields.io/badge/Architecture-LlamaForCausalLM-green)](https://huggingface.co/)
+[![Context Window](https://img.shields.io/badge/Context-2048_Tokens-orange)](https://huggingface.co/)
+[![License](https://img.shields.io/badge/License-Apache_2.0-yellow)](LICENSE)
+[![Discord](https://img.shields.io/badge/Discord-Join_Community-5865F2)](https://discord.com/invite/BrJn4D2Guh)
+
+*Built by [Minibase](https://minibase.ai) - Train and deploy small AI models from your browser.*
+*Browse all of the models and datasets available on the [Minibase Marketplace](https://minibase.ai/wiki/Special:Marketplace).*
+
+</div>
+
+## 📋 Model Summary
+
+**Minibase-DeId-Small** is a specialized language model fine-tuned for text de-identification tasks. It automatically detects and replaces personal identifiers (PII) such as names, dates, addresses, phone numbers, and other sensitive information with standardized placeholder tags while preserving the original meaning and context of the text.
+
+### Key Features
+- 🔒 **Privacy-First**: Removes personal identifiers automatically
+- 🎯 **High Completeness**: 64% of texts fully de-identified
+- 📏 **Compact Size**: 136MB (Q8_0 quantized)
+- ⚡ **Fast Inference**: ~492ms average response time
+- 🌐 **Multi-Domain**: Works across medical, legal, HR, and general text
+- 🔄 **Local Processing**: No data sent to external servers
+
+## 🚀 Quick Start
+
+### Local Inference (Recommended)
+
+1. **Install llama.cpp** (if not already installed):
+   ```bash
+   git clone https://github.com/ggerganov/llama.cpp
+   cd llama.cpp && make
+   ```
+
+2. **Download and run the model**:
+   ```bash
+   # Download model files
+   wget https://huggingface.co/Minibase/DeId-Small/resolve/main/model.gguf
+   wget https://huggingface.co/Minibase/DeId-Small/resolve/main/deid_inference.py
+
+   # Make executable and run
+   chmod +x run_server.sh
+   ./run_server.sh
+   ```
+
+3. **Make API calls**:
+   ```python
+   import requests
+
+   # De-identify text
+   response = requests.post("http://127.0.0.1:8000/completion", json={
+       "prompt": "Instruction: De-identify this text by replacing all personal information with placeholders.\n\nInput: Patient John Smith, born 1985-03-15, lives at 123 Main St.\n\nResponse: ",
+       "max_tokens": 256,
+       "temperature": 0.1
+   })
+
+   result = response.json()
+   print(result["content"])  # "Patient [FIRSTNAME_1] [LASTNAME_1], born [DOB_1], lives at [BUILDINGNUMBER_1] [STREET_1]."
+   ```
+
+### Python Client
+
+```python
+from deid_inference import DeIdClient
+
+# Initialize client
+client = DeIdClient()
+
+# De-identify text
+sensitive_text = "Dr. Sarah Johnson called from (555) 123-4567 about patient Michael Brown."
+clean_text = client.deidentify_text(sensitive_text)
+
+print(clean_text)  # "Dr. [FIRSTNAME_1] [LASTNAME_1] called from [PHONE_1] about patient [FIRSTNAME_2] [LASTNAME_2]."
+```
+
+## 📊 Benchmarks & Performance
+
+### Overall Performance (100 samples)
+
+| Metric | Score | Description |
+|--------|-------|-------------|
+| **Completeness Score** | **64.0%** | **Percentage of texts fully de-identified** |
+| PII Detection Rate | 20.3% | How well expected PII patterns are detected |
+| Semantic Preservation | 10.9% | How well original meaning is preserved |
+| **Average Latency** | **492ms** | **Response time performance** |
+
+### Domain-Specific Performance
+
+| Domain | Samples | Completeness | Best For |
+|--------|---------|-------------|----------|
+| **General Text** | 40 | **75.0%** | **Mixed content, everyday text** |
+| **Customer Service** | 6 | **100%** | **Support interactions, inquiries** |
+| **Medical Records** | 33 | 60.6% | Patient notes, clinical data |
+| **Legal Documents** | 6 | 50.0% | Depositions, contracts |
+| **HR Records** | 11 | 27.3% | Employee data, personnel files |
+| **Research Data** | 4 | 50.0% | Study participants, academic data |
+
+**Performance Insights:**
+- ✅ **Excellent at customer service** (100% completeness)
+- ✅ **Strong general-purpose performance** (75% completeness)
+- ✅ **Good medical record handling** (60.6% completeness)
+- ⚠️ **Challenging with structured HR data** (27.3% completeness)
+
+## 🏗️ Technical Details
+
+### Model Architecture
+- **Architecture**: LlamaForCausalLM
+- **Parameters**: 135M (small capacity)
+- **Context Window**: 2,048 tokens
+- **Max Position Embeddings**: 2,048
+- **Quantization**: GGUF (Q8_0 quantization)
+- **File Size**: 136MB
+- **Memory Requirements**: 8GB RAM minimum, 16GB recommended
+
+### Training Details
+- **Base Model**: Custom-trained Llama architecture
+- **Fine-tuning Dataset**: Curated PII-parallel text pairs
+- **Training Objective**: Instruction-following for de-identification
+- **Optimization**: Quantized for efficient inference
+- **Model Scale**: Small capacity optimized for speed
+
+### System Requirements
+
+| Component | Minimum | Recommended |
+|-----------|---------|-------------|
+| **Operating System** | Linux, macOS, Windows | Linux or macOS |
+| **RAM** | 8GB | 16GB |
+| **Storage** | 150MB free space | 500MB free space |
+| **Python** | 3.8+ | 3.10+ |
+| **Dependencies** | llama.cpp | llama.cpp, requests |
+
+**Notes:**
+- ✅ **CPU-only inference** supported but slower
+- ✅ **GPU acceleration** provides significant speed improvements
+- ✅ **Apple Silicon** users get Metal acceleration automatically
+
+## 📖 Usage Examples
+
+### Basic De-identification
+```python
+# Input: "John Smith from New York called about his account."
+# Output: "[FIRSTNAME_1] [LASTNAME_1] from [CITY_1] called about his account."
+
+# Input: "Patient born on 1990-05-15 visited Dr. Williams."
+# Output: "Patient born on [DOB_1] visited Dr. [LASTNAME_1]."
+```
+
+### Medical Records
+```python
+# Input: "Sarah Johnson, DOB 05/12/1980, visited St. Jude Hospital."
+# Output: "[FIRSTNAME_1] [LASTNAME_1], DOB [DOB_1], visited [HOSPITAL_1]."
+
+# Input: "Dr. Michael Brown called from (555) 123-4567."
+# Output: "Dr. [FIRSTNAME_1] [LASTNAME_1] called from [PHONE_1]."
+```
+
+### Legal Documents
+```python
+# Input: "Attorney Robert Davis from Legal Eagles LLP filed the motion."
+# Output: "Attorney [FIRSTNAME_1] [LASTNAME_1] from [ORGANIZATION_1] filed the motion."
+
+# Input: "Case LD-2022-007 was filed on December 1, 2022."
+# Output: "Case [CASE_ID_1] was filed on [DATE_1]."
+```
+
+### HR Records
+```python
+# Input: "Employee John Doe earns $85,000 annually."
+# Output: "Employee [FIRSTNAME_1] Doe earns [CURRENCYSYMBOL_1][AMOUNT_1] annually."
+
+# Input: "Contact jane.smith@company.com for details."
+# Output: "Contact [EMAIL_1] for details."
+```
+
+## 🔧 Advanced Configuration
+
+### Server Configuration
+```bash
+# GPU acceleration (macOS with Metal)
+llama-server \
+  -m model.gguf \
+  --host 127.0.0.1 \
+  --port 8000 \
+  --n-gpu-layers 35 \
+  --ctx-size 2048 \
+  --metal
+
+# CPU-only (higher memory usage)
+llama-server \
+  -m model.gguf \
+  --host 127.0.0.1 \
+  --port 8000 \
+  --n-gpu-layers 0 \
+  --threads 8 \
+  --ctx-size 2048
+```
+
+### Temperature Settings
+
+| Temperature Range | Approach | Description |
+|------------------|----------|-------------|
+| **0.0-0.2** | **Conservative (Recommended)** | **Precise, consistent de-identification** |
+| **0.3-0.5** | Balanced | Good balance of accuracy and flexibility |
+| **0.6-1.0** | Creative | More flexible but may miss some PII |
+
+## 📚 Limitations & Biases
+
+### Current Limitations
+
+| Limitation | Description | Impact |
+|------------|-------------|--------|
+| **Placeholder Format** | Uses specific naming conventions (e.g., [FIRSTNAME_1]) | May not match all expected formats |
+| **Complex Contexts** | May struggle with highly nested or ambiguous PII | Could miss subtle personal information |
+| **Language Scope** | Primarily trained on English text | Limited performance on other languages |
+| **Context Window** | Limited to 2,048 token context window | Cannot process very long documents |
+| **Structured Data** | Less effective on highly formatted data (tables, forms) | Lower performance on structured HR/financial data |
+
+### Potential Biases
+
+| Bias Type | Description | Mitigation |
+|-----------|-------------|------------|
+| **Cultural Names** | May not recognize all international naming patterns | Regular updates with diverse data |
+| **Regional Formats** | Limited exposure to regional address/phone formats | Expand training data coverage |
+| **Emerging PII** | May not recognize newest types of personal data | Continuous model updates |
+| **Domain Specificity** | Performance varies across different text types | Use domain-specific fine-tuning |
+
+## 🤝 Contributing
+
+We welcome contributions! Please see our [Contributing Guide](CONTRIBUTING.md) for details.
+
+### Development Setup
+```bash
+# Clone the repository
+git clone https://github.com/minibase-ai/deid-small
+cd deid-small
+
+# Install dependencies
+pip install -r requirements.txt
+
+# Run tests
+python -m pytest tests/
+```
+
+## 📜 Citation
+
+If you use DeId-Small in your research, please cite:
+
+```bibtex
+@misc{deid-small-2025,
+  title={DeId-Small: A Compact Text De-identification Model},
+  author={Minibase AI Team},
+  year={2025},
+  publisher={Hugging Face},
+  url={https://huggingface.co/Minibase/DeId-Small}
+}
+```
+
+## 📞 Contact & Community
+
+- **Website**: [minibase.ai](https://minibase.ai)
+- **Discord Community**: [Join our Discord](https://discord.com/invite/BrJn4D2Guh)
+- **GitHub Issues**: [Report bugs or request features](https://github.com/minibase-ai/deid-small/issues)
+- **Email**: hello@minibase.ai
+
+### Support
+- 📖 **Documentation**: [docs.minibase.ai](https://docs.minibase.ai)
+- 💬 **Community Forum**: [forum.minibase.ai](https://forum.minibase.ai)
+- 🐛 **Bug Reports**: [GitHub Issues](https://github.com/minibase-ai/deid-small/issues)
+
+## 📋 License
+
+This model is released under the [Apache License 2.0](LICENSE).
+
+## 🙏 Acknowledgments
+
+- **Personal De-identifier Benchmark Dataset**: Used for training and evaluation
+- **llama.cpp**: For efficient local inference
+- **Hugging Face**: For model hosting and community
+- **Our amazing community**: For feedback and contributions
+
+---
+
+<div align="center">
+
+**Built with ❤️ by the Minibase team**
+
+*Making AI safer and more accessible for everyone*
+
+[🌟 Star us on GitHub](https://github.com/minibase-ai/deid-small) • [📖 Read the docs](https://docs.minibase.ai) • [💬 Join our Discord](https://discord.com/invite/BrJn4D2Guh)
+
+</div>