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

provide/foundation/eventsets/sets/llm.py

@@ -0,0 +1,139 @@
+"""
+Large Language Model (LLM) interaction event set for Foundation.
+"""
+
+from provide.foundation.eventsets.types import EventSet, EventMapping, FieldMapping
+
+EVENT_SET = EventSet(
+    name="llm",
+    description="LLM provider and interaction enrichment",
+    mappings=[
+        EventMapping(
+            name="llm_provider",
+            visual_markers={
+                "openai": "🤖",
+                "anthropic": "📚",
+                "google": "🇬",
+                "meta": "🦙",
+                "mistral": "🌬️",
+                "perplexity": "❓",
+                "cohere": "🔊",
+                "default": "💡",
+            },
+            metadata_fields={
+                "openai": {"llm.vendor": "openai", "llm.api": "openai"},
+                "anthropic": {"llm.vendor": "anthropic", "llm.api": "claude"},
+                "google": {"llm.vendor": "google", "llm.api": "gemini"},
+                "meta": {"llm.vendor": "meta", "llm.api": "llama"},
+                "mistral": {"llm.vendor": "mistral", "llm.api": "mistral"},
+            },
+            default_key="default"
+        ),
+        EventMapping(
+            name="llm_task",
+            visual_markers={
+                "generation": "✍️",
+                "completion": "✅",
+                "embedding": "🔗",
+                "chat": "💬",
+                "tool_use": "🛠️",
+                "summarization": "📜",
+                "translation": "🌐",
+                "classification": "🏷️",
+                "default": "⚡",
+            },
+            metadata_fields={
+                "generation": {"llm.type": "generative"},
+                "completion": {"llm.type": "completion"},
+                "embedding": {"llm.type": "embedding"},
+                "chat": {"llm.type": "conversational"},
+                "tool_use": {"llm.type": "function_calling"},
+            },
+            default_key="default"
+        ),
+        EventMapping(
+            name="llm_outcome",
+            visual_markers={
+                "success": "👍",
+                "error": "🔥",
+                "filtered_input": "🛡️👁️",
+                "filtered_output": "🛡️🗣️",
+                "rate_limit": "⏳",
+                "partial_success": "🤏",
+                "tool_call": "📞",
+                "default": "➡️",
+            },
+            metadata_fields={
+                "success": {"llm.success": True},
+                "error": {"llm.error": True},
+                "rate_limit": {"llm.rate_limited": True},
+                "filtered_input": {"llm.filtered": True, "llm.filter_type": "input"},
+                "filtered_output": {"llm.filtered": True, "llm.filter_type": "output"},
+            },
+            default_key="default"
+        ),
+    ],
+    field_mappings=[
+        FieldMapping(
+            log_key="llm.provider",
+            event_set_name="llm",
+            description="LLM provider name",
+            value_type="string"
+        ),
+        FieldMapping(
+            log_key="llm.task",
+            event_set_name="llm",
+            description="LLM task type",
+            value_type="string"
+        ),
+        FieldMapping(
+            log_key="llm.model",
+            event_set_name="llm",
+            description="Model identifier",
+            value_type="string"
+        ),
+        FieldMapping(
+            log_key="llm.outcome",
+            event_set_name="llm",
+            description="Operation outcome",
+            value_type="string"
+        ),
+        FieldMapping(
+            log_key="llm.input.tokens",
+            event_set_name="llm",
+            description="Input token count",
+            value_type="integer"
+        ),
+        FieldMapping(
+            log_key="llm.output.tokens",
+            event_set_name="llm",
+            description="Output token count",
+            value_type="integer"
+        ),
+        FieldMapping(
+            log_key="llm.tool.name",
+            event_set_name="llm",
+            description="Tool/function name",
+            value_type="string"
+        ),
+        FieldMapping(
+            log_key="llm.tool.call_id",
+            event_set_name="llm",
+            description="Tool call identifier",
+            value_type="string"
+        ),
+        FieldMapping(
+            log_key="duration_ms",
+            event_set_name="llm",
+            description="LLM operation duration",
+            value_type="integer"
+        ),
+        FieldMapping(
+            log_key="trace_id",
+            event_set_name="llm",
+            description="Distributed trace ID",
+            value_type="string"
+        ),
+    ],
+    priority=100  # High priority for LLM operations
+)

provide/foundation/eventsets/sets/task_queue.py

@@ -0,0 +1,107 @@
+"""
+Task queue and async job processing event set for Foundation.
+"""
+
+from provide.foundation.eventsets.types import EventSet, EventMapping, FieldMapping
+
+EVENT_SET = EventSet(
+    name="task_queue",
+    description="Asynchronous task queue operation enrichment",
+    mappings=[
+        EventMapping(
+            name="task_system",
+            visual_markers={
+                "celery": "🥕",
+                "rq": "🟥🇶",
+                "dramatiq": "🎭",
+                "kafka": "🌊",
+                "rabbitmq": "🐇",
+                "default": "📨",
+            },
+            metadata_fields={
+                "celery": {"task.broker": "celery"},
+                "rq": {"task.broker": "redis"},
+                "dramatiq": {"task.broker": "dramatiq"},
+                "kafka": {"task.broker": "kafka", "task.streaming": True},
+                "rabbitmq": {"task.broker": "amqp"},
+            },
+            default_key="default"
+        ),
+        EventMapping(
+            name="task_status",
+            visual_markers={
+                "submitted": "➡️📨",
+                "received": "📥",
+                "started": "▶️",
+                "progress": "🔄",
+                "retrying": "🔁",
+                "success": "✅🏁",
+                "failure": "❌🔥",
+                "revoked": "🚫",
+                "default": "❓",
+            },
+            metadata_fields={
+                "submitted": {"task.state": "pending"},
+                "received": {"task.state": "pending"},
+                "started": {"task.state": "active"},
+                "progress": {"task.state": "active"},
+                "retrying": {"task.state": "retry"},
+                "success": {"task.state": "completed", "task.success": True},
+                "failure": {"task.state": "failed", "task.success": False},
+                "revoked": {"task.state": "cancelled"},
+            },
+            default_key="default"
+        ),
+    ],
+    field_mappings=[
+        FieldMapping(
+            log_key="task.system",
+            event_set_name="task_queue",
+            description="Task queue system",
+            value_type="string"
+        ),
+        FieldMapping(
+            log_key="task.status",
+            event_set_name="task_queue",
+            description="Task execution status",
+            value_type="string"
+        ),
+        FieldMapping(
+            log_key="task.id",
+            event_set_name="task_queue",
+            description="Unique task identifier",
+            value_type="string"
+        ),
+        FieldMapping(
+            log_key="task.name",
+            event_set_name="task_queue",
+            description="Task or job name",
+            value_type="string"
+        ),
+        FieldMapping(
+            log_key="task.queue_name",
+            event_set_name="task_queue",
+            description="Queue name",
+            value_type="string"
+        ),
+        FieldMapping(
+            log_key="task.retries",
+            event_set_name="task_queue",
+            description="Retry attempt count",
+            value_type="integer"
+        ),
+        FieldMapping(
+            log_key="duration_ms",
+            event_set_name="task_queue",
+            description="Task execution duration",
+            value_type="integer"
+        ),
+        FieldMapping(
+            log_key="trace_id",
+            event_set_name="task_queue",
+            description="Distributed trace ID",
+            value_type="string"
+        ),
+    ],
+    priority=70
+)

provide/foundation/eventsets/types.py

@@ -0,0 +1,70 @@
+"""
+Event set type definitions for the Foundation event enrichment system.
+"""
+
+from collections.abc import Callable
+from typing import Any
+
+from attrs import define, field
+
+
+@define(frozen=True, slots=True)
+class EventMapping:
+    """
+    Individual event enrichment mapping for a specific domain.
+    
+    Attributes:
+        name: Unique identifier for this mapping
+        visual_markers: Mapping of values to visual indicators (e.g., emojis)
+        metadata_fields: Additional metadata to attach based on values
+        transformations: Value transformation functions
+        default_key: Key to use when no specific match is found
+    """
+    
+    name: str
+    visual_markers: dict[str, str] = field(factory=lambda: {})
+    metadata_fields: dict[str, dict[str, Any]] = field(factory=lambda: {})
+    transformations: dict[str, Callable[[Any], Any]] = field(factory=lambda: {})
+    default_key: str = field(default="default")
+
+
+@define(frozen=True, slots=True)
+class FieldMapping:
+    """
+    Maps a log field to an event set for enrichment.
+    
+    Attributes:
+        log_key: The field key in log events (e.g., "http.method", "llm.provider")
+        description: Human-readable description of this field
+        value_type: Expected type of the field value
+        event_set_name: Name of the EventSet to use for enrichment
+        default_override_key: Override the default key for this specific field
+        default_value: Default value to use if field is not present
+    """
+    
+    log_key: str
+    description: str | None = field(default=None)
+    value_type: str | None = field(default=None)
+    event_set_name: str | None = field(default=None)
+    default_override_key: str | None = field(default=None)
+    default_value: Any | None = field(default=None)
+
+
+@define(frozen=True, slots=True)
+class EventSet:
+    """
+    Complete event enrichment domain definition.
+    
+    Attributes:
+        name: Unique identifier for this event set
+        description: Human-readable description
+        mappings: List of EventMapping definitions
+        field_mappings: List of field-to-mapping associations
+        priority: Higher priority sets override lower ones
+    """
+    
+    name: str
+    description: str | None = field(default=None)
+    mappings: list[EventMapping] = field(factory=lambda: [])
+    field_mappings: list[FieldMapping] = field(factory=lambda: [])
+    priority: int = field(default=0, converter=int)

provide/foundation/file/directory.py

@@ -6,6 +6,8 @@ from pathlib import Path
 import shutil
 import tempfile
 
+from provide.foundation.errors.decorators import with_error_handling
+from provide.foundation.errors.handlers import error_boundary
 from provide.foundation.logger import get_logger
 
 log = get_logger(__name__)
@@ -80,17 +82,12 @@ def temp_dir(
         yield temp_path
     finally:
         if cleanup and temp_path and temp_path.exists():
-            try:
+            with error_boundary(Exception, reraise=False):
                 shutil.rmtree(temp_path)
                 log.debug("Cleaned up temp directory", path=str(temp_path))
-            except Exception as e:
-                log.warning(
-                    "Failed to cleanup temp directory",
-                    path=str(temp_path),
-                    error=str(e),
-                )
 
 
+@with_error_handling(fallback=False, suppress=(FileNotFoundError,) if False else ())
 def safe_rmtree(
     path: Path | str,
     missing_ok: bool = True,
@@ -109,21 +106,15 @@ def safe_rmtree(
     """
     path = Path(path)
 
-    try:
-        if path.exists():
-            shutil.rmtree(path)
-            log.debug("Removed directory tree", path=str(path))
-            return True
-        elif missing_ok:
-            log.debug("Directory already absent", path=str(path))
-            return False
-        else:
-            raise FileNotFoundError(f"Directory does not exist: {path}")
-    except Exception as e:
-        if not path.exists() and missing_ok:
-            return False
-        log.error("Failed to remove directory tree", path=str(path), error=str(e))
-        raise
+    if path.exists():
+        shutil.rmtree(path)
+        log.debug("Removed directory tree", path=str(path))
+        return True
+    elif missing_ok:
+        log.debug("Directory already absent", path=str(path))
+        return False
+    else:
+        raise FileNotFoundError(f"Directory does not exist: {path}")
 
 
 __all__ = [

provide/foundation/file/lock.py

@@ -4,6 +4,8 @@ import os
 from pathlib import Path
 import time
 
+from provide.foundation.config.defaults import DEFAULT_FILE_LOCK_TIMEOUT
+from provide.foundation.errors.decorators import with_error_handling
 from provide.foundation.errors.resources import LockError
 from provide.foundation.logger import get_logger
 
@@ -25,7 +27,7 @@ class FileLock:
     def __init__(
         self,
         path: Path | str,
-        timeout: float = 10.0,
+        timeout: float = DEFAULT_FILE_LOCK_TIMEOUT,
         check_interval: float = 0.1,
     ) -> None:
         """Initialize file lock.