provide-foundation 0.0.0.dev0__py3-none-any.whl → 0.0.0.dev2__py3-none-any.whl

provide/foundation/eventsets/resolver.py

@@ -0,0 +1,192 @@
+"""
+Event set resolution and enrichment logic.
+"""
+
+from typing import Any
+
+from provide.foundation.eventsets.registry import get_registry
+from provide.foundation.eventsets.types import EventMapping, EventSet, FieldMapping
+
+
+class EventSetResolver:
+    """
+    Resolves and applies event set enrichments to log events.
+    """
+    
+    def __init__(self) -> None:
+        """Initialize the resolver with cached configurations."""
+        self._field_mappings: list[FieldMapping] = []
+        self._event_mappings_by_set: dict[str, list[EventMapping]] = {}
+        self._resolved = False
+    
+    def resolve(self) -> None:
+        """
+        Resolve all registered event sets into a unified configuration.
+        
+        This merges all registered event sets by priority, building
+        the field mapping and event mapping lookup tables.
+        """
+        registry = get_registry()
+        event_sets = registry.list_event_sets()  # Already sorted by priority
+        
+        # Clear existing state
+        self._field_mappings.clear()
+        self._event_mappings_by_set.clear()
+        
+        # Process each event set in priority order
+        for event_set in event_sets:
+            # Store event mappings by event set name
+            self._event_mappings_by_set[event_set.name] = event_set.mappings
+            
+            # Add field mappings
+            self._field_mappings.extend(event_set.field_mappings)
+        
+        self._resolved = True
+    
+    def enrich_event(self, event_dict: dict[str, Any]) -> dict[str, Any]:
+        """
+        Enrich a log event with event set data.
+        
+        Args:
+            event_dict: The event dictionary to enrich
+            
+        Returns:
+            The enriched event dictionary
+        """
+        if not self._resolved:
+            self.resolve()
+        
+        enrichments = []
+        
+        # Process each field in the event
+        for field_key, field_value in list(event_dict.items()):
+            if field_key == "event" or field_value is None:
+                continue
+                
+            # Find appropriate event mapping for this field
+            event_mapping = self._find_event_mapping_for_field(field_key, field_value)
+            if not event_mapping:
+                continue
+                
+            value_str = str(field_value).lower()
+            
+            # Apply transformations
+            if value_str in event_mapping.transformations:
+                field_value = event_mapping.transformations[value_str](field_value)
+                value_str = str(field_value).lower()
+            
+            # Get visual marker
+            visual_marker = event_mapping.visual_markers.get(
+                value_str,
+                event_mapping.visual_markers.get(event_mapping.default_key, "")
+            )
+            
+            if visual_marker:
+                enrichments.append(visual_marker)
+            
+            # Apply metadata fields
+            if value_str in event_mapping.metadata_fields:
+                for meta_key, meta_value in event_mapping.metadata_fields[value_str].items():
+                    if meta_key not in event_dict:
+                        event_dict[meta_key] = meta_value
+        
+        # Add visual enrichments to event message
+        if enrichments:
+            prefix = "".join(f"[{e}]" for e in enrichments)
+            event_msg = event_dict.get("event", "")
+            event_dict["event"] = f"{prefix} {event_msg}" if event_msg else prefix
+        
+        return event_dict
+    
+    def _find_event_mapping_for_field(self, field_key: str, field_value: Any) -> EventMapping | None:
+        """
+        Find the appropriate EventMapping for a given field.
+        
+        This method uses a heuristic approach to match field keys to EventMappings:
+        1. Direct field name mapping (e.g., "domain" -> "domain" mapping)
+        2. Field prefix mapping (e.g., "http.method" -> "http_method" mapping)
+        3. Field pattern matching
+        """
+        # First check for direct field name matches
+        simple_key = field_key.split('.')[-1]  # Get last part of dotted key
+        
+        for event_set_name, mappings in self._event_mappings_by_set.items():
+            for mapping in mappings:
+                # Direct name match
+                if mapping.name == simple_key or mapping.name == field_key:
+                    return mapping
+                
+                # Pattern matching for common cases
+                if field_key.startswith("http.") and mapping.name.startswith("http_"):
+                    if field_key.replace(".", "_") == mapping.name:
+                        return mapping
+                
+                if field_key.startswith("llm.") and mapping.name.startswith("llm_"):
+                    if field_key.replace(".", "_") == mapping.name:
+                        return mapping
+                
+                if field_key.startswith("db.") and mapping.name.startswith("db_"):
+                    if field_key.replace(".", "_") == mapping.name:
+                        return mapping
+                
+                if field_key.startswith("task.") and mapping.name.startswith("task_"):
+                    if field_key.replace(".", "_") == mapping.name:
+                        return mapping
+        
+        return None
+    
+    def get_visual_markers(self, event_dict: dict[str, Any]) -> list[str]:
+        """
+        Extract visual markers for an event without modifying it.
+        
+        Args:
+            event_dict: The event dictionary to analyze
+            
+        Returns:
+            List of visual markers that would be applied
+        """
+        if not self._resolved:
+            self.resolve()
+        
+        markers = []
+        
+        for field_key, field_value in event_dict.items():
+            if field_key == "event" or field_value is None:
+                continue
+                
+            event_mapping = self._find_event_mapping_for_field(field_key, field_value)
+            if not event_mapping:
+                continue
+                
+            value_str = str(field_value).lower()
+            marker = event_mapping.visual_markers.get(
+                value_str,
+                event_mapping.visual_markers.get(event_mapping.default_key, "")
+            )
+            
+            if marker:
+                markers.append(marker)
+        
+        return markers
+
+
+# Global resolver instance
+_resolver = EventSetResolver()
+
+
+def get_resolver() -> EventSetResolver:
+    """Get the global event set resolver instance."""
+    return _resolver
+
+
+def enrich_event(event_dict: dict[str, Any]) -> dict[str, Any]:
+    """
+    Enrich a log event with event set data.
+    
+    Args:
+        event_dict: The event dictionary to enrich
+        
+    Returns:
+        The enriched event dictionary
+    """
+    return _resolver.enrich_event(event_dict)

provide/foundation/eventsets/sets/das.py

@@ -0,0 +1,128 @@
+"""
+Domain-Action-Status (DAS) event set.
+"""
+
+from provide.foundation.eventsets.types import EventMapping, EventSet, FieldMapping
+
+EVENT_SET = EventSet(
+    name="default",
+    description="Core Domain-Action-Status event enrichment",
+    mappings=[
+        EventMapping(
+            name="domain",
+            visual_markers={
+                "system": "⚙️",
+                "server": "🛎️",
+                "client": "🙋",
+                "network": "🌐",
+                "security": "🔐",
+                "config": "🔩",
+                "database": "🗄️",
+                "cache": "💾",
+                "task": "🔄",
+                "plugin": "🔌",
+                "telemetry": "🛰️",
+                "di": "💉",
+                "protocol": "📡",
+                "file": "📄",
+                "user": "👤",
+                "test": "🧪",
+                "utils": "🧰",
+                "core": "🌟",
+                "auth": "🔑",
+                "entity": "🦎",
+                "report": "📈",
+                "payment": "💳",
+                "default": "❓",
+            },
+            default_key="default"
+        ),
+        EventMapping(
+            name="action",
+            visual_markers={
+                "init": "🌱",
+                "start": "🚀",
+                "stop": "🛑",
+                "connect": "🔗",
+                "disconnect": "💔",
+                "listen": "👂",
+                "send": "📤",
+                "receive": "📥",
+                "read": "📖",
+                "write": "📝",
+                "process": "⚙️",
+                "validate": "🛡️",
+                "execute": "▶️",
+                "query": "🔍",
+                "update": "🔄",
+                "delete": "🗑️",
+                "login": "➡️",
+                "logout": "⬅️",
+                "auth": "🔑",
+                "error": "🔥",
+                "encrypt": "🛡️",
+                "decrypt": "🔓",
+                "parse": "🧩",
+                "transmit": "📡",
+                "build": "🏗️",
+                "schedule": "📅",
+                "emit": "📢",
+                "load": "💡",
+                "observe": "🧐",
+                "request": "🗣️",
+                "interrupt": "🚦",
+                "register": "⚙️",
+                "default": "❓",
+            },
+            default_key="default"
+        ),
+        EventMapping(
+            name="status",
+            visual_markers={
+                "success": "✅",
+                "failure": "❌",
+                "error": "🔥",
+                "warning": "⚠️",
+                "info": "ℹ️",
+                "debug": "🐞",
+                "trace": "👣",
+                "attempt": "⏳",
+                "retry": "🔁",
+                "skip": "⏭️",
+                "complete": "🏁",
+                "timeout": "⏱️",
+                "notfound": "❓",
+                "unauthorized": "🚫",
+                "invalid": "💢",
+                "cached": "🎯",
+                "ongoing": "🏃",
+                "idle": "💤",
+                "ready": "👍",
+                "default": "➡️",
+            },
+            default_key="default"
+        ),
+    ],
+    field_mappings=[
+        FieldMapping(
+            log_key="domain",
+            event_set_name="default",
+            description="System domain or component"
+        ),
+        FieldMapping(
+            log_key="action",
+            event_set_name="default",
+            description="Action being performed"
+        ),
+        FieldMapping(
+            log_key="status",
+            event_set_name="default",
+            description="Status or outcome of the action"
+        ),
+    ],
+    priority=0
+)
+
+# Alias for backward compatibility
+das_event_set = EVENT_SET
+default_event_set = EVENT_SET

provide/foundation/eventsets/sets/database.py

@@ -0,0 +1,125 @@
+"""
+Database operations event set for Foundation.
+"""
+
+from provide.foundation.eventsets.types import EventSet, EventMapping, FieldMapping
+
+EVENT_SET = EventSet(
+    name="database",
+    description="Database interaction and query enrichment",
+    mappings=[
+        EventMapping(
+            name="db_system",
+            visual_markers={
+                "postgres": "🐘",
+                "mysql": "🐬",
+                "sqlite": "💾",
+                "mongodb": "🍃",
+                "redis": "🟥",
+                "elasticsearch": "🔍",
+                "default": "🗄️",
+            },
+            metadata_fields={
+                "postgres": {"db.type": "sql", "db.vendor": "postgresql"},
+                "mysql": {"db.type": "sql", "db.vendor": "mysql"},
+                "sqlite": {"db.type": "sql", "db.vendor": "sqlite"},
+                "mongodb": {"db.type": "nosql", "db.vendor": "mongodb"},
+                "redis": {"db.type": "cache", "db.vendor": "redis"},
+                "elasticsearch": {"db.type": "search", "db.vendor": "elastic"},
+            },
+            default_key="default"
+        ),
+        EventMapping(
+            name="db_operation",
+            visual_markers={
+                "query": "🔍",
+                "select": "🔍",
+                "insert": "➕",
+                "update": "🔄",
+                "delete": "🗑️",
+                "connect": "🔗",
+                "disconnect": "💔",
+                "transaction_begin": "💳🟢",
+                "transaction_commit": "💳✅",
+                "transaction_rollback": "💳❌",
+                "default": "⚙️",
+            },
+            metadata_fields={
+                "select": {"db.read": True},
+                "query": {"db.read": True},
+                "insert": {"db.write": True},
+                "update": {"db.write": True},
+                "delete": {"db.write": True},
+            },
+            default_key="default"
+        ),
+        EventMapping(
+            name="db_outcome",
+            visual_markers={
+                "success": "👍",
+                "error": "🔥",
+                "not_found": "❓🤷",
+                "timeout": "⏱️",
+                "default": "➡️",
+            },
+            metadata_fields={
+                "success": {"db.success": True},
+                "error": {"db.error": True},
+                "timeout": {"db.timeout": True},
+            },
+            default_key="default"
+        ),
+    ],
+    field_mappings=[
+        FieldMapping(
+            log_key="db.system",
+            event_set_name="database",
+            description="Database system type",
+            value_type="string"
+        ),
+        FieldMapping(
+            log_key="db.operation",
+            event_set_name="database",
+            description="Database operation performed",
+            value_type="string"
+        ),
+        FieldMapping(
+            log_key="db.outcome",
+            event_set_name="database",
+            description="Operation outcome",
+            value_type="string"
+        ),
+        FieldMapping(
+            log_key="db.statement",
+            event_set_name="database",
+            description="SQL or query statement",
+            value_type="string"
+        ),
+        FieldMapping(
+            log_key="db.table",
+            event_set_name="database",
+            description="Table name",
+            value_type="string",
+            default_override_key="default"
+        ),
+        FieldMapping(
+            log_key="db.rows_affected",
+            event_set_name="database",
+            description="Number of rows affected",
+            value_type="integer"
+        ),
+        FieldMapping(
+            log_key="duration_ms",
+            event_set_name="database",
+            description="Query duration in milliseconds",
+            value_type="integer"
+        ),
+        FieldMapping(
+            log_key="trace_id",
+            event_set_name="database",
+            description="Distributed trace ID",
+            value_type="string"
+        ),
+    ],
+    priority=90
+)

provide/foundation/eventsets/sets/http.py

@@ -0,0 +1,153 @@
+"""
+HTTP request/response event set for Foundation.
+"""
+
+from provide.foundation.eventsets.types import EventMapping, EventSet, FieldMapping
+
+EVENT_SET = EventSet(
+    name="http",
+    description="HTTP client and server interaction enrichment",
+    mappings=[
+        EventMapping(
+            name="http_method",
+            visual_markers={
+                "get": "📥",
+                "post": "📤",
+                "put": "📝⬆️",
+                "delete": "🗑️",
+                "patch": "🩹",
+                "head": "👤❔",
+                "options": "⚙️❔",
+                "default": "🌐",
+            },
+            default_key="default"
+        ),
+        EventMapping(
+            name="http_status_class",
+            visual_markers={
+                "1xx": "ℹ️",
+                "2xx": "✅",
+                "3xx": "↪️",
+                "4xx": "⚠️CLIENT",
+                "5xx": "🔥SERVER",
+                "default": "❓",
+            },
+            metadata_fields={
+                "2xx": {"http.success": True},
+                "4xx": {"http.client_error": True},
+                "5xx": {"http.server_error": True},
+            },
+            default_key="default"
+        ),
+        EventMapping(
+            name="http_target_type",
+            visual_markers={
+                "path": "🛣️",
+                "query": "❓",
+                "fragment": "#️⃣",
+                "default": "🎯",
+            },
+            default_key="default"
+        ),
+    ],
+    field_mappings=[
+        FieldMapping(
+            log_key="http.method",
+            event_set_name="http",
+            description="HTTP request method",
+            value_type="string"
+        ),
+        FieldMapping(
+            log_key="http.status_class",
+            event_set_name="http",
+            description="HTTP status code class",
+            value_type="string"
+        ),
+        FieldMapping(
+            log_key="http.target",
+            event_set_name="http",
+            description="Request target path and query",
+            value_type="string",
+            default_override_key="path"
+        ),
+        FieldMapping(
+            log_key="http.url",
+            event_set_name="http",
+            description="Full HTTP URL",
+            value_type="string"
+        ),
+        FieldMapping(
+            log_key="http.scheme",
+            event_set_name="http",
+            description="URL scheme",
+            value_type="string"
+        ),
+        FieldMapping(
+            log_key="http.host",
+            event_set_name="http",
+            description="Request hostname",
+            value_type="string"
+        ),
+        FieldMapping(
+            log_key="http.status_code",
+            event_set_name="http",
+            description="HTTP response status code",
+            value_type="integer"
+        ),
+        FieldMapping(
+            log_key="http.request.body.size",
+            event_set_name="http",
+            description="Request body size in bytes",
+            value_type="integer"
+        ),
+        FieldMapping(
+            log_key="http.response.body.size",
+            event_set_name="http",
+            description="Response body size in bytes",
+            value_type="integer"
+        ),
+        FieldMapping(
+            log_key="client.address",
+            event_set_name="http",
+            description="Client IP address",
+            value_type="string"
+        ),
+        FieldMapping(
+            log_key="server.address",
+            event_set_name="http",
+            description="Server address or hostname",
+            value_type="string"
+        ),
+        FieldMapping(
+            log_key="duration_ms",
+            event_set_name="http",
+            description="Request duration in milliseconds",
+            value_type="integer"
+        ),
+        FieldMapping(
+            log_key="trace_id",
+            event_set_name="http",
+            description="Distributed trace ID",
+            value_type="string"
+        ),
+        FieldMapping(
+            log_key="span_id",
+            event_set_name="http",
+            description="Span ID",
+            value_type="string"
+        ),
+        FieldMapping(
+            log_key="error.message",
+            event_set_name="http",
+            description="Error message if request failed",
+            value_type="string"
+        ),
+        FieldMapping(
+            log_key="error.type",
+            event_set_name="http",
+            description="Error type if request failed",
+            value_type="string"
+        ),
+    ],
+    priority=80
+)