Language models integration (LangExtract)

.github/workflows/ci.yml

@@ -348,6 +348,11 @@ jobs:
       - name: Wait for services to be ready
         run: sleep 60
 
+      - name: Download Ollama model for Ollama LangExtract recognizer tests
+        run: |
+          docker exec $(docker ps -qf "name=ollama") ollama pull qwen2.5:1.5b
+          docker exec $(docker ps -qf "name=ollama") ollama run qwen2.5:1.5b
+
       - name: Run E2E tests
         working-directory: e2e-tests
         run: |
@@ -431,6 +436,11 @@ jobs:
       - name: Wait for services to be ready
         run: sleep 60
 
+      - name: Download Ollama model for Ollama LangExtract recognizer tests
+        run: |
+          docker exec $(docker ps -qf "name=ollama") ollama pull qwen2.5:1.5b
+          docker exec $(docker ps -qf "name=ollama") ollama run qwen2.5:1.5b
+
       - name: Run E2E tests
         working-directory: e2e-tests
         run: |

docker-compose.yml

@@ -1,4 +1,18 @@
 services:
+  ollama:
+    image: ollama/ollama:latest
+    ports:
+      - "127.0.0.1:11434:11434"   # or "127.0.0.1:11435:11434"
+    volumes:
+      - ollama-data:/root/.ollama
+    environment:
+      - OLLAMA_HOST=0.0.0.0
+    healthcheck:
+      test: ["CMD", "ollama", "list"]
+      interval: 10s
+      timeout: 10s
+      retries: 30        # ~5 minutes total
+      start_period: 60s  
   presidio-anonymizer:
     image: ${REGISTRY_NAME}/${IMAGE_PREFIX}presidio-anonymizer${TAG}
     build:
@@ -9,6 +23,7 @@ services:
       - PORT=5001
     ports:
       - "5001:5001"
+
   presidio-analyzer:
     image: ${REGISTRY_NAME}/${IMAGE_PREFIX}presidio-analyzer${TAG}
     build:
@@ -17,8 +32,13 @@ services:
         - type=registry,ref=${REGISTRY_NAME}/${IMAGE_PREFIX}presidio-analyzer:latest
     environment:
       - PORT=5001
+      - OLLAMA_HOST=http://ollama:11434
     ports:
       - "5002:5001"
+    depends_on:
+      ollama:
+        condition: service_healthy
+
   presidio-image-redactor:
     image: ${REGISTRY_NAME}/${IMAGE_PREFIX}presidio-image-redactor${TAG}
     build:
@@ -29,3 +49,6 @@ services:
       - PORT=5001
     ports:
       - "5003:5001"
+
+volumes:
+  ollama-data:

docs/analyzer/adding_recognizers.md

@@ -165,6 +165,13 @@ On how to integrate Presidio with AHDS De-Identification Protected Health Inform
 and a sample for a ADHS Remote Recognizer, refer to the
 [AHDS de-Identification Integration document](../samples/python/ahds/index.md).
 
+### Language Model-based PII/PHI detection recognizer
+
+Presidio supports language model-based entity detection using LLMs and SLMs for flexible PII/PHI recognition.
+
+The current implementation uses LangExtract with Ollama (local models). For full setup instructions and usage examples, 
+see the [Language Model-based PII/PHI Detection guide](../samples/python/langextract/index.md).
+
 ### Creating ad-hoc recognizers
 
 In addition to recognizers in code, it is possible to create ad-hoc recognizers via the Presidio Analyzer API for regex and deny-list based logic.

docs/samples/index.md

@@ -19,6 +19,7 @@
 | Usage | Text      | Python file                            | [Azure AI Language as a Remote Recognizer](python/text_analytics/index.md)  |
 | Usage | Text      | Python file                            | [Azure Health Data Services de-identification Service as a Remote Recognizer](python/ahds/index.md)  |
 | Usage | Text      | Python file                            | [AHDS Surrogate Example](python/ahds/example_ahds_surrogate.py)  |
+| Usage | Text      | Python file                            | [Language Model-based PII/PHI Detection using LangExtract](python/langextract/index.md)  |
 | Usage | CSV       | Python file                            | [Analyze and Anonymize CSV file](https://github.com/microsoft/presidio/blob/main/docs/samples/python/process_csv_file.py) |
 | Usage | Text      | Python                                 | [Using Flair as an external PII model](https://github.com/microsoft/presidio/blob/main/docs/samples/python/flair_recognizer.py)|
 | Usage | Text      | Python file                            | [Using Span Marker as an external PII model](https://github.com/microsoft/presidio/blob/main/docs/samples/python/span_marker_recognizer.py)|

docs/samples/python/langextract/index.md

@@ -0,0 +1,181 @@
+# Language Model-based PII/PHI Detection (Experimental Feature)
+
+## Introduction
+
+Presidio supports language model-based PII/PHI detection for flexible entity recognition using language models (LLMs, SLMs, etc.). This approach enables detection of both:
+- **PII (Personally Identifiable Information)**: Names, emails, phone numbers, SSN, credit cards, etc.
+- **PHI (Protected Health Information)**: Medical records, health identifiers, etc.
+
+(The default approach uses [LangExtract](https://github.com/google/langextract) under the hood to integrate with language model providers.)
+
+## Entity Detection Capabilities
+
+Unlike pattern-based recognizers, language model-based detection is flexible and depends on:
+
+- The language model being used
+- The prompt description provided
+- The few-shot examples configured
+
+The default configuration includes examples for common PII/PHI entities such as PERSON, EMAIL_ADDRESS, PHONE_NUMBER, US_SSN, CREDIT_CARD, MEDICAL_LICENSE, and more. 
+**You can customize the prompts and examples to detect any entity types relevant to your use case**.
+
+For the default entity mappings and examples, see the [default configuration](https://github.com/microsoft/presidio/blob/main/presidio-analyzer/presidio_analyzer/conf/langextract_config_ollama.yaml).
+
+## Supported Language Model Providers
+
+Presidio supports the following language model providers through LangExtract:
+
+1. **Ollama** - Local language model deployment (open-source models like Gemma, Llama, etc.)
+2. **Azure OpenAI** - _Documentation coming soon_
+
+## Language Model-based Recognizer Implementation
+
+Presidio provides a hierarchy of recognizers for language model-based PII/PHI detection:
+
+- **`LMRecognizer`**: Abstract base class for all language model recognizers (LLMs, SLMs, etc.)
+- **`LangExtractRecognizer`**: Abstract base class for LangExtract library integration (model-agnostic)
+- **`OllamaLangExtractRecognizer`**: Concrete implementation for Ollama local language models
+- **`AzureOpenAILangExtractRecognizer`**: _Documentation coming soon_
+
+[OllamaLangExtractRecognizer implementation](https://github.com/microsoft/presidio/blob/main/presidio-analyzer/presidio_analyzer/predefined_recognizers/third_party/ollama_langextract_recognizer.py)
+
+---
+
+## Using Ollama (Local Models)
+
+### Prerequisites
+
+1. **Install Presidio with LangExtract support**:
+   ```sh
+   pip install presidio-analyzer[langextract]
+   ```
+
+2. **Set up Ollama**
+
+You have two options to set up Ollama:
+
+  **Option 1: Docker Compose** (recommended for CPU)
+
+  This option requires Docker to be installed on your system.
+
+  **Where to run:** From the root presidio directory (where `docker-compose.yml` is located)
+
+  ```bash
+  docker compose up -d ollama
+  docker exec presidio-ollama-1 ollama pull qwen2.5:1.5b
+  docker exec presidio-ollama-1 ollama list
+  ```
+
+  **Platform differences:**
+  - **Linux/Mac**: Commands above work as-is
+  - **Windows**: Use PowerShell or CMD, commands are the same
+
+  If you don't have Docker installed:
+  - Linux: Follow [Docker installation guide](https://docs.docker.com/engine/install/)
+  - Mac: Install [Docker Desktop for Mac](https://docs.docker.com/desktop/install/mac-install/)
+  - Windows: Install [Docker Desktop for Windows](https://docs.docker.com/desktop/install/windows-install/)
+
+  **Option 2: Native installation** (recommended for GPU acceleration)
+
+  Follow the [official LangExtract Ollama guide](https://github.com/google/langextract?tab=readme-ov-file#using-local-llms-with-ollama).
+
+  After installation, pull and run the model:
+  ```bash
+  ollama pull qwen2.5:1.5b
+  ollama run qwen2.5:1.5b
+  ```
+
+  > This option provides better performance with GPU acceleration (e.g., on Mac with Metal Performance Shaders or systems with NVIDIA GPUs).
+  > The model must be pulled and run before using the recognizer. The default model is `qwen2.5:1.5b`.
+
+3. **Configuration** (optional): Create your own `ollama_config.yaml` or use the [default configuration](https://github.com/microsoft/presidio/blob/main//presidio-analyzer/presidio_analyzer/conf/langextract_config_ollama.yaml)
+
+### Usage
+
+**Option 1: Enable in configuration file**
+
+Enable the recognizer in [`default_recognizers.yaml`](https://github.com/microsoft/presidio/blob/main/presidio-analyzer/presidio_analyzer/conf/default_recognizers.yaml):
+```yaml
+- name: OllamaLangExtractRecognizer
+  enabled: true  # Change from false to true
+```
+
+Then load the analyzer using this modified configuration file:
+
+```python
+from presidio_analyzer import AnalyzerEngine
+from presidio_analyzer.recognizer_registry import RecognizerRegistryProvider
+
+# Point to your modified default_recognizers.yaml with Ollama enabled
+provider = RecognizerRegistryProvider(
+    conf_file="/path/to/your/modified/default_recognizers.yaml"
+)
+registry = provider.create_recognizer_registry()
+
+# Create analyzer with the registry that includes Ollama recognizer
+analyzer = AnalyzerEngine(registry=registry, supported_languages=["en"])
+
+# Analyze text - Ollama recognizer will participate in detection
+results = analyzer.analyze(text="My email is john.doe@example.com", language="en")
+```
+
+**Option 2: Add programmatically**
+
+```python
+from presidio_analyzer import AnalyzerEngine
+from presidio_analyzer.predefined_recognizers.third_party.ollama_langextract_recognizer import OllamaLangExtractRecognizer
+
+analyzer = AnalyzerEngine()
+analyzer.registry.add_recognizer(OllamaLangExtractRecognizer())
+
+results = analyzer.analyze(text="My email is john.doe@example.com", language="en")
+```
+
+!!! note "Note"
+    The recognizer is disabled by default in `default_recognizers.yaml` to avoid requiring Ollama for basic Presidio usage. Enable it when you have Ollama set up and running.
+
+### Custom Configuration
+
+To use a custom configuration file:
+
+```python
+analyzer.registry.add_recognizer(
+    OllamaLangExtractRecognizer(config_path="/path/to/custom_config.yaml")
+)
+```
+
+### Configuration Options
+
+The `langextract_config_ollama.yaml` file supports the following options:
+
+- **`model_id`**: The Ollama model to use (default: `"qwen2.5:1.5b"`)
+- **`model_url`**: Ollama server URL (default: `"http://localhost:11434"`)
+- **`temperature`**: Model temperature for generation (default: `null` for model default)
+- **`supported_entities`**: PII/PHI entity types to detect
+- **`entity_mappings`**: Map LangExtract entity classes to Presidio entity names
+- **`min_score`**: Minimum confidence score (default: `0.5`)
+
+See the [configuration file](https://github.com/microsoft/presidio/blob/main/presidio-analyzer/presidio_analyzer/conf/ollama_config.yaml) for all options.
+
+## Troubleshooting
+
+**ConnectionError: "Ollama server not reachable"**
+- Ensure Ollama is running: `docker ps` or check `http://localhost:11434`
+- Verify the `model_url` in your configuration matches your Ollama server address
+
+**RuntimeError: "Model 'qwen2.5:1.5b' not found"**
+- Pull the model: `docker exec -it presidio-ollama-1 ollama pull qwen2.5:1.5b`
+- Or for manual setup: `ollama pull qwen2.5:1.5b`
+- Verify the model name matches the `model_id` in your configuration
+
+---
+
+## Using Azure OpenAI (Cloud Models)
+
+_Documentation coming soon_
+
+---
+
+## Choosing Between Ollama and Azure OpenAI
+
+_Comparison documentation coming soon_

e2e-tests/requirements.txt

@@ -1,4 +1,4 @@
 requests>=2.32.4
 pytest
-file:../presidio-analyzer
-file:../presidio-anonymizer
+-e ../presidio-analyzer[langextract]
+-e ../presidio-anonymizer

e2e-tests/resources/ollama_test_config.yaml

@@ -0,0 +1,51 @@
+# LMRecognizer base configuration
+lm_recognizer:
+  supported_entities:
+    - PERSON
+    - LOCATION
+    - ORGANIZATION
+    - PHONE_NUMBER
+    - EMAIL_ADDRESS
+    - DATE_TIME
+    - US_SSN
+    - CREDIT_CARD
+    - MEDICAL_LICENSE
+    - IP_ADDRESS
+    - URL
+    - IBAN_CODE
+
+  labels_to_ignore:
+    - payment_status
+
+  enable_generic_consolidation: true
+  min_score: 0.5
+
+langextract:
+  prompt_file: presidio-analyzer/presidio_analyzer/conf/langextract_prompts/default_pii_phi_prompt.j2
+  examples_file: presidio-analyzer/presidio_analyzer/conf/langextract_prompts/default_pii_phi_examples.yaml
+
+  entity_mappings:
+    person: PERSON
+    full_name: PERSON
+    name_first: PERSON
+    name_last: PERSON
+    name_middle: PERSON
+    location: LOCATION
+    address: LOCATION
+    organization: ORGANIZATION
+    phone: PHONE_NUMBER
+    phone_number: PHONE_NUMBER
+    email: EMAIL_ADDRESS
+    date: DATE_TIME
+    ssn: US_SSN
+    identification_number: US_SSN
+    credit_card: CREDIT_CARD
+    medical_record: MEDICAL_LICENSE
+    ip_address: IP_ADDRESS
+    url: URL
+    iban: IBAN_CODE
+
+  model:
+    model_id: qwen2.5:1.5b
+    model_url: http://localhost:11434
+    temperature: 0.0