Introduce fully Anonymous hash (#369)

Author: lukehinds

README.md

@@ -373,8 +373,24 @@ If you're using DeepFabric in production or research, we'd love to hear from you
 
 ### Analytics
 
-We use fully anonymised analytics, to help us improve application performance and stability. We never send Personal identifiable information and we do not capture prompts, generated content, API keys, file names etc.
+We use privacy-respecting analytics to help us improve application performance and stability. We never send Personal identifiable information and we do not capture prompts, generated content, API keys, file names etc.
 
-We capture model names, numeric parameters (temperature, depth, degree, batch_size), timing and success/failure rates - this then helps us find optimizations or bottlenecks.
+#### What We Collect
+- **Anonymous User ID**: A stable, one-way hash based on your machine characteristics (hostname + MAC address). This helps us understand unique user counts without identifying you. Its impossible to reverse this hash to get your actual machine details and one-way only.
+- **Usage Metrics**: Model names, numeric parameters (temperature, depth, degree, batch_size), timing and success/failure rates
+- **Developer Flag**: If you set `DEEPFABRIC_DEVELOPER=True`, events are marked to help us filter developer testing from real usage
 
-You can fully disable all analytics by setting the environment variable `ANONYMIZED_TELEMETRY=False`.
+#### Privacy Guarantees
+- No usernames, emails, IP addresses, or personal information
+- User ID is cryptographically hashed and cannot be reversed and contains no Personal Identifiable Information
+- No prompts, generated datasets, or sensitive data is collected
+- All data is used solely for application improvement in regards to performance, stability, and feature usage
+
+#### Control Your Participation
+```bash
+# Disable all analytics
+export ANONYMIZED_TELEMETRY=False
+
+# Mark yourself as a developer (for filtering)
+export DEEPFABRIC_DEVELOPER=True
+```

deepfabric/metrics.py

@@ -1,5 +1,20 @@
+"""
+Simple analytics for DeepFabric using PostHog.
+
+Provides a single trace() function for anonymous usage analytics.
+All analytics can be disabled by setting ANONYMIZED_TELEMETRY=False.
+
+Privacy-respecting identity:
+- Generates a stable, anonymous user ID based on machine characteristics
+- Uses DEEPFABRIC_DEVELOPER=True to mark developer sessions for filtering
+- Never collects PII (names, emails, IP addresses, etc.)
+"""
+
 import contextlib
+import hashlib
 import os
+import platform
+import uuid
 
 try:
     import importlib.metadata
@@ -9,7 +24,7 @@
     VERSION = "development"
 
 try:
-    from posthog import Posthog
+    from posthog import Posthog, identify_context, new_context
 
     POSTHOG_AVAILABLE = True
 except ImportError:
@@ -24,11 +39,55 @@
 else:
     posthog = None
 
+# Cache for the generated user ID using a dict to avoid global statement
+_user_id_cache: dict[str, str | None] = {"id": None}
+
+
+def _get_user_id() -> str:
+    """
+    Generate a stable, anonymous user ID based on machine characteristics.
+
+    Creates a UUID from a hash of platform.node() (hostname) and uuid.getnode()
+    (MAC address). This provides a persistent identifier across sessions without
+    collecting PII.
+
+    Returns:
+        str: A stable UUID string unique to this machine
+    """
+    if _user_id_cache["id"] is not None:
+        return _user_id_cache["id"]
+
+    # Combine hostname and MAC address for machine-specific identifier
+    machine_info = f"{platform.node()}-{uuid.getnode()}"
+
+    # Create SHA256 hash and convert to UUID format
+    hash_digest = hashlib.sha256(machine_info.encode()).hexdigest()
+
+    # Use first 32 hex chars to create a valid UUID
+    user_uuid = str(uuid.UUID(hash_digest[:32]))
+
+    _user_id_cache["id"] = user_uuid
+    return user_uuid
+
+
+def _is_developer() -> bool:
+    """
+    Check if this session is marked as a developer session.
+
+    Returns:
+        bool: True if DEEPFABRIC_DEVELOPER environment variable is set to 'True'
+    """
+    return os.environ.get("DEEPFABRIC_DEVELOPER") == "True"
+
 
 def trace(event_name, event_properties=None):
     """
     Send an analytics event if telemetry is enabled.
 
+    Uses privacy-respecting identity tracking with a stable, anonymous user ID
+    generated from machine characteristics. Developer sessions are marked with
+    the is_developer flag when DEEPFABRIC_DEVELOPER=True.
+
     Args:
         event_name: Name of the event to track
         event_properties: Optional dictionary of event properties
@@ -46,11 +105,18 @@ def trace(event_name, event_properties=None):
         return
 
     with contextlib.suppress(Exception):
-        # Add version to all events
+        # Generate stable user ID
+        user_id = _get_user_id()
+
+        # Add version and developer flag to all events
         properties = event_properties or {}
         properties["version"] = VERSION
+        properties["is_developer"] = _is_developer()
 
-        posthog.capture(distinct_id="deepfabric", event=event_name, properties=properties)
+        # Use identity context to associate events with the user
+        with new_context():
+            identify_context(user_id)
+            posthog.capture(event=event_name, properties=properties)
 
 
 def is_enabled():