Updating documentation with code examples.

Author: jzonthemtn

README.md

@@ -2,9 +2,9 @@
 
 A Python port of [Phileas (Java)](https://github.com/philterd/phileas) — a library to deidentify and redact PII, PHI, and other sensitive information from text.
 
-Check out the [documentation](https://philterd.github.io/phileas-python/) or details and code examples.
-
-Built by [Philterd](https://www.philterd.ai).
+* Check out the [documentation](https://philterd.github.io/phileas-python/) or details and code examples.
+* Built by [Philterd](https://www.philterd.ai).
+* Commercial support and consulting is available - [contact us](https://www.philterd.ai).
 
 ## Overview
 
@@ -504,7 +504,7 @@ pytest tests/ -v
 
 ## License
 
-Copyright 2027 Philterd, LLC.
+Copyright 2026 Philterd, LLC.
 
 Licensed under the Apache License, Version 2.0. See [LICENSE](LICENSE) for details.
 

docs/api-reference.md

@@ -8,21 +8,56 @@ The main entry point for filtering text. `FilterService` is stateless; a single
 
 ```python
 from phileas.services.filter_service import FilterService
+from phileas.policy.policy import Policy
 
+# Create with default in-memory context service
 service = FilterService()
+
+# Or provide a custom context service
+from phileas.services.context_service import InMemoryContextService
+ctx_svc = InMemoryContextService()
+service = FilterService(context_service=ctx_svc)
 ```
 
+### Constructor
+
+```python
+FilterService(context_service=None)
+```
+
+**Parameters**
+
+| Parameter | Type | Default | Description |
+|---|---|---|
+| `context_service` | `AbstractContextService` or `None` | `None` | Context service implementation for managing referential integrity. If `None`, an `InMemoryContextService` is created automatically. |
+
 ### `filter(policy, context, document_id, text)`
 
 Apply the policy to the given text and return a `FilterResult`.
 
 ```python
+from phileas.services.filter_service import FilterService
+from phileas.policy.policy import Policy
+
+policy = Policy.from_dict({
+    "name": "example",
+    "identifiers": {
+        "emailAddress": {
+            "emailAddressFilterStrategies": [{"strategy": "REDACT"}]
+        }
+    }
+})
+
+service = FilterService()
 result = service.filter(
     policy=policy,
     context="my-app",
     document_id="doc-001",
     text="Contact john@example.com.",
 )
+
+print(result.filtered_text)
+# Contact {{{REDACTED-email-address}}}.
 ```
 
 **Parameters**
@@ -215,6 +250,119 @@ Serialise to a dict.
 
 ---
 
+## AbstractContextService
+
+`phileas.services.context_service.AbstractContextService`
+
+Abstract base class for context service implementations. Subclass this to provide a custom backend (e.g., Redis, database, etc.).
+
+```python
+from phileas.services.context_service import AbstractContextService
+from phileas.services.filter_service import FilterService
+from phileas.policy.policy import Policy
+
+class RedisContextService(AbstractContextService):
+    """Example custom context service using Redis."""
+
+    def __init__(self, redis_client):
+        self.redis = redis_client
+
+    def put(self, context: str, token: str, replacement: str) -> None:
+        """Store token -> replacement mapping in Redis."""
+        key = f"phileas:{context}:{token}"
+        self.redis.set(key, replacement)
+
+    def get(self, context: str, token: str) -> str | None:
+        """Retrieve replacement from Redis, or None if not found."""
+        key = f"phileas:{context}:{token}"
+        value = self.redis.get(key)
+        return value.decode('utf-8') if value else None
+
+    def contains(self, context: str, token: str) -> bool:
+        """Check if token exists in Redis."""
+        key = f"phileas:{context}:{token}"
+        return self.redis.exists(key) > 0
+
+# Usage example (requires redis package)
+# import redis
+# redis_client = redis.Redis(host='localhost', port=6379, db=0)
+# ctx_svc = RedisContextService(redis_client)
+# service = FilterService(context_service=ctx_svc)
+```
+
+### Methods
+
+| Method | Signature | Description |
+|---|---|---|
+| `put` | `(context, token, replacement) -> None` | Store a replacement value for a token under the given context |
+| `get` | `(context, token) -> str \| None` | Return the stored replacement, or `None` if not found |
+| `contains` | `(context, token) -> bool` | Return `True` if a replacement exists for the token in the given context |
+
+---
+
+## InMemoryContextService
+
+`phileas.services.context_service.InMemoryContextService`
+
+Default implementation of `AbstractContextService` backed by a `dict[str, dict[str, str]]`. Suitable for single-process, in-memory use.
+
+```python
+from phileas.services.context_service import InMemoryContextService
+from phileas.services.filter_service import FilterService
+from phileas.policy.policy import Policy
+
+# Create and pre-populate the context service
+ctx_svc = InMemoryContextService()
+ctx_svc.put("patient-123", "john@example.com", "EMAIL-001")
+ctx_svc.put("patient-123", "555-867-5309", "PHONE-001")
+
+# Use it with FilterService
+policy = Policy.from_dict({
+    "name": "medical",
+    "identifiers": {
+        "emailAddress": {
+            "emailAddressFilterStrategies": [{"strategy": "REDACT"}]
+        },
+        "phoneNumber": {
+            "phoneNumberFilterStrategies": [{"strategy": "REDACT"}]
+        }
+    }
+})
+
+service = FilterService(context_service=ctx_svc)
+
+# The pre-populated replacements will be used
+result1 = service.filter(
+    policy, "patient-123", "doc-1",
+    "Contact john@example.com or 555-867-5309."
+)
+print(result1.filtered_text)
+# Contact EMAIL-001 or PHONE-001.
+
+# The same replacements persist across documents in the same context
+result2 = service.filter(
+    policy, "patient-123", "doc-2",
+    "Patient called 555-867-5309 from john@example.com."
+)
+print(result2.filtered_text)
+# Patient called PHONE-001 from EMAIL-001.
+
+# Check what's stored
+print(ctx_svc.get("patient-123", "john@example.com"))      # EMAIL-001
+print(ctx_svc.contains("patient-123", "555-867-5309"))     # True
+print(ctx_svc.get("patient-123", "unknown@example.com"))   # None
+```
+
+### Methods
+
+| Method | Signature | Description |
+|---|---|---|
+| `put` | `(context, token, replacement) -> None` | Store a replacement for a token |
+| `get` | `(context, token) -> str \| None` | Retrieve a replacement, or `None` if not found |
+| `contains` | `(context, token) -> bool` | Check if a replacement exists |
+
+---
+
 ## Policy key reference
 
 The table below maps every JSON/YAML policy key to the `Identifiers` attribute it populates and the strategies key used in its filter config.

docs/examples.md

@@ -341,6 +341,9 @@ ignoredPatterns:
 Requires a running [ph-eye](https://github.com/philterd/ph-eye) service.
 
 ```python
+from phileas.policy.policy import Policy
+from phileas.services.filter_service import FilterService
+
 policy = Policy.from_dict({
     "name": "ner-demo",
     "identifiers": {
@@ -355,10 +358,158 @@ policy = Policy.from_dict({
     }
 })
 
+service = FilterService()
 result = service.filter(
     policy, "app", "doc-12",
     "Dr. Alice Johnson reviewed the case."
 )
 print(result.filtered_text)
 # Dr. {{{REDACTED-person}}} reviewed the case.
 ```
+
+---
+
+## Redact custom patterns with regex
+
+Use custom pattern filters to detect domain-specific PII not covered by built-in filters.
+
+```python
+from phileas.policy.policy import Policy
+from phileas.services.filter_service import FilterService
+
+policy = Policy.from_dict({
+    "name": "custom-patterns",
+    "identifiers": {
+        "patterns": [
+            {
+                "pattern": r"EMP-\d{6}",
+                "label": "employee-id",
+                "patternFilterStrategies": [{"strategy": "REDACT"}]
+            },
+            {
+                "pattern": r"[A-Z]{2}\d{6}",
+                "label": "passport-number",
+                "patternFilterStrategies": [{"strategy": "MASK"}]
+            }
+        ]
+    }
+})
+
+service = FilterService()
+result = service.filter(
+    policy, "app", "doc-13",
+    "Employee EMP-123456 has passport AB123456."
+)
+print(result.filtered_text)
+# Employee {{{REDACTED-employee-id}}} has passport *********.
+```
+
+---
+
+## Redact terms from a dictionary
+
+Use the dictionaries filter to redact known names or sensitive terms.
+
+```python
+from phileas.policy.policy import Policy
+from phileas.services.filter_service import FilterService
+
+policy = Policy.from_dict({
+    "name": "dictionary-demo",
+    "identifiers": {
+        "dictionaries": [
+            {
+                "terms": ["John Smith", "Jane Doe", "confidential", "proprietary"],
+                "dictionaryFilterStrategies": [{"strategy": "REDACT"}]
+            }
+        ]
+    }
+})
+
+service = FilterService()
+result = service.filter(
+    policy, "app", "doc-14",
+    "John Smith shared confidential data with Jane Doe about the proprietary algorithm."
+)
+print(result.filtered_text)
+# {{{REDACTED-dictionary}}} shared {{{REDACTED-dictionary}}} data with {{{REDACTED-dictionary}}} about the {{{REDACTED-dictionary}}} algorithm.
+```
+
+---
+
+## Use conditions to filter selectively
+
+Apply different strategies based on the matched value using condition expressions.
+
+```python
+from phileas.policy.policy import Policy
+from phileas.services.filter_service import FilterService
+
+policy = Policy.from_dict({
+    "name": "conditional-filtering",
+    "identifiers": {
+        "phoneNumber": {
+            "phoneNumberFilterStrategies": [
+                # Redact phone numbers starting with 555 (test numbers)
+                {"strategy": "REDACT", "condition": 'token startswith "555"'},
+                # Mask all other phone numbers
+                {"strategy": "MASK"}
+            ]
+        }
+    }
+})
+
+service = FilterService()
+result = service.filter(
+    policy, "app", "doc-15",
+    "Test: 555-123-4567, Real: 800-867-5309"
+)
+print(result.filtered_text)
+# Test: {{{REDACTED-phone-number}}}, Real: ***-***-****
+```
+
+---
+
+## Maintain referential integrity across documents
+
+Use contexts to ensure the same PII value gets the same replacement across multiple documents.
+
+```python
+from phileas.policy.policy import Policy
+from phileas.services.filter_service import FilterService
+
+policy = Policy.from_dict({
+    "name": "context-demo",
+    "identifiers": {
+        "emailAddress": {
+            "emailAddressFilterStrategies": [{"strategy": "HASH_SHA256_REPLACE"}]
+        }
+    }
+})
+
+service = FilterService()
+
+# Filter multiple documents in the same context
+doc1 = service.filter(
+    policy, "patient-123", "note-1",
+    "Patient emailed from john@example.com"
+)
+doc2 = service.filter(
+    policy, "patient-123", "note-2",
+    "Follow-up: john@example.com responded"
+)
+
+# The hash will be identical in both documents
+print(doc1.filtered_text)
+# Patient emailed from 5bb8a5cbf6...
+
+print(doc2.filtered_text)
+# Follow-up: 5bb8a5cbf6... responded
+
+# Different context = different hash
+doc3 = service.filter(
+    policy, "patient-456", "note-1",
+    "Patient emailed from john@example.com"
+)
+# Hash will be different in patient-456 context
+```