mycorrhizal 0.2.0__py3-none-any.whl → 0.2.2__py3-none-any.whl

mycorrhizal/spores/cache.py

@@ -8,11 +8,14 @@ LRU cache for tracking seen objects and logging them on eviction.
 from __future__ import annotations
 
 from collections import OrderedDict
-from typing import Dict, Callable, Optional, TypeVar, Generic
+from typing import Dict, Callable, Optional, TypeVar, Generic, TYPE_CHECKING
 from dataclasses import dataclass
 
 from .models import Object
 
+if TYPE_CHECKING:
+    from .core import CacheMetrics
+
 
 # Generic types for cache
 K = TypeVar('K')  # Key type (object ID)
@@ -28,61 +31,90 @@ class CacheEntry:
         object: The OCEL Object
         sight_count: How many times we've seen this object
         first_sight_time: When we first saw the object
+        attributes_hash: Hash of object attributes for change detection
     """
     object: Object
     sight_count: int = 1
     first_sight_time: Optional[float] = None
+    attributes_hash: Optional[int] = None
+
+
+def _compute_attributes_hash(obj: Object) -> Optional[int]:
+    """
+    Compute hash of object attributes for change detection.
+
+    Args:
+        obj: The OCEL Object
+
+    Returns:
+        Hash of attributes, or None if object has no attributes
+    """
+    if not obj.attributes:
+        return None
+    # Hash frozenset of (attr_name, attr_value) tuples
+    # ObjectAttributeValue.value holds the actual Python value
+    attrs = {k: v.value for k, v in obj.attributes.items()}
+    return hash(frozenset(attrs.items()))
 
 
 class ObjectLRUCache(Generic[K, V]):
     """
-    LRU cache with eviction callback for object tracking.
+    LRU cache with unified callback for object logging.
 
-    When an object is first seen, it should be logged via on_first_sight.
-    When an object is evicted from the cache, it's logged via on_evict.
+    The cache fires the `needs_logged` callback when an object needs to be logged:
+    - On first sight (new object added to cache)
+    - On eviction (object removed from cache to make room)
+    - When attributes change (detected via hash comparison)
+    - Every N touches (configurable via `touch_resend_n`)
 
     This ensures OCEL consumers see object evolution:
     - First sight: Initial object state
+    - Attribute changes: Updated state
     - Eviction: Final state before being removed from cache
+    - Periodic resend: Long-lived objects are re-logged periodically
 
     Example:
         ```python
-        def on_evict(object_id: str, obj: Object):
+        def needs_logged(object_id: str, obj: Object):
             # Send object to transport
             transport.send(LogRecord(object=obj))
 
-        cache = ObjectLRUCache(maxsize=128, on_evict=on_evict)
+        cache = ObjectLRUCache(maxsize=128, needs_logged=needs_logged, touch_resend_n=100)
 
         # Check if object exists, add if not
         if not cache.contains_or_add(object_id, object):
-            # Object not in cache, already logged by on_first_sight
+            # Object not in cache, already logged by needs_logged
             pass
         ```
 
     Args:
         maxsize: Maximum number of objects to cache
-        on_evict: Callback when object is evicted (object_id, object) -> None
-        on_first_sight: Optional callback when object is first seen (object_id, object) -> None
+        needs_logged: Callback when object needs logging (object_id, object) -> None
+        touch_resend_n: Resend object every N touches (0 to disable periodic resend)
     """
 
     def __init__(
         self,
         maxsize: int = 128,
-        on_evict: Optional[Callable[[K, Object], None]] = None,
-        on_first_sight: Optional[Callable[[K, Object], None]] = None
+        needs_logged: Optional[Callable[[K, Object], None]] = None,
+        touch_resend_n: int = 100,
+        metrics: Optional["CacheMetrics"] = None
     ):
         self.maxsize = maxsize
-        self.on_evict = on_evict
-        self.on_first_sight = on_first_sight
+        self.needs_logged = needs_logged
+        self.touch_resend_n = touch_resend_n
+        self.metrics = metrics
         self._cache: OrderedDict[K, CacheEntry] = OrderedDict()
 
     def _evict_if_needed(self) -> None:
         """Evict oldest entry if cache is full."""
-        if len(self._cache) >= self.maxsize:
+        while len(self._cache) >= self.maxsize:
             # FIFO from OrderedDict (oldest first)
             object_id, entry = self._cache.popitem(last=False)
-            if self.on_evict:
-                self.on_evict(object_id, entry.object)
+            if self.metrics is not None:
+                self.metrics.evictions += 1
+            if self.needs_logged:
+                self.needs_logged(object_id, entry.object)
 
     def get(self, key: K) -> Optional[Object]:
         """
@@ -119,8 +151,13 @@ class ObjectLRUCache(Generic[K, V]):
         Check if key exists, add if not.
 
         This is the primary method for object tracking:
-        - If key exists: mark as recently used, return True
-        - If key doesn't exist: add object, potentially evict, call on_first_sight, return False
+        - If key exists: check for attribute changes, periodic resend, mark as recently used
+        - If key doesn't exist: add object, potentially evict, log first sight
+
+        The `needs_logged` callback is fired when:
+        - First sight: new object added to cache
+        - Attribute change: object attributes changed (hash comparison)
+        - Every N touches: periodic resend for long-lived objects
 
         Args:
             key: The object ID
@@ -130,27 +167,51 @@ class ObjectLRUCache(Generic[K, V]):
             True if object was already in cache, False if it was just added
         """
         if key in self._cache:
-            # Already seen, mark as recently used
-            self._cache.move_to_end(key)
+            # Object exists - check if we need to log
             entry = self._cache[key]
             entry.sight_count += 1
+
+            # Compute current attribute hash
+            current_hash = _compute_attributes_hash(obj)
+
+            # Check if attributes changed
+            attrs_changed = (entry.attributes_hash is not None and
+                            current_hash != entry.attributes_hash)
+
+            # Update if attributes changed
+            if attrs_changed:
+                entry.object = obj
+                entry.attributes_hash = current_hash
+
+            # Fire callback if ANY condition met
+            should_log = any([
+                attrs_changed,
+                self.touch_resend_n > 0 and entry.sight_count % self.touch_resend_n == 0,
+            ])
+            if should_log and self.needs_logged:
+                self.needs_logged(key, entry.object)
+
+            self._cache.move_to_end(key)
             return True
         else:
-            # First sight
+            # First sight - store hash, fire callback
             self._evict_if_needed()
-
-            entry = CacheEntry(object=obj)
+            if self.metrics is not None:
+                self.metrics.first_sights += 1
+            attr_hash = _compute_attributes_hash(obj)
+            entry = CacheEntry(object=obj, attributes_hash=attr_hash)
             self._cache[key] = entry
-
-            if self.on_first_sight:
-                self.on_first_sight(key, obj)
-
+            if self.needs_logged:
+                self.needs_logged(key, obj)
             return False
 
     def add(self, key: K, obj: Object) -> None:
         """
         Add an object to the cache (or update if exists).
 
+        Note: This method fires needs_logged for new objects, but not for updates.
+        For attribute change detection and periodic resend, use contains_or_add().
+
         Args:
             key: The object ID
             obj: The OCEL Object
@@ -165,11 +226,12 @@ class ObjectLRUCache(Generic[K, V]):
             # New entry
             self._evict_if_needed()
 
-            entry = CacheEntry(object=obj)
+            attr_hash = _compute_attributes_hash(obj)
+            entry = CacheEntry(object=obj, attributes_hash=attr_hash)
             self._cache[key] = entry
 
-            if self.on_first_sight:
-                self.on_first_sight(key, obj)
+            if self.needs_logged:
+                self.needs_logged(key, obj)
 
     def remove(self, key: K) -> Optional[Object]:
         """

mycorrhizal/spores/core.py

@@ -13,11 +13,12 @@ import functools
 import logging
 import threading
 from datetime import datetime
+from enum import Enum
 from typing import (
     Any, Callable, Optional, Union, Dict, List,
     ParamSpec, TypeVar, overload, get_origin, get_args, Annotated
 )
-from dataclasses import dataclass
+from dataclasses import dataclass, field
 from abc import ABC, abstractmethod
 
 from .models import (
@@ -44,6 +45,28 @@ R = TypeVar('R')
 # Global Configuration
 # ============================================================================
 
+class EvictionPolicy(str, Enum):
+    """
+    Cache eviction policy for object logging.
+
+    Attributes:
+        EVICT_AND_LOG: Evict from cache when full, log immediately via sync/async path
+        EVICT_AND_BUFFER: Evict from cache, buffer for later logging (future)
+        NO_EVICT: Keep in cache until explicit flush (future)
+    """
+    EVICT_AND_LOG = "evict_and_log"
+    EVICT_AND_BUFFER = "evict_and_buffer"
+    NO_EVICT = "no_evict"
+
+
+@dataclass
+class CacheMetrics:
+    """Track cache eviction statistics."""
+    evictions: int = 0
+    eviction_failures: int = 0
+    first_sights: int = 0
+
+
 @dataclass
 class SporesConfig:
     """
@@ -54,11 +77,15 @@ class SporesConfig:
         object_cache_size: Maximum objects in LRU cache
         encoder: Encoder instance to use
         transport: Transport instance to use (required for logging to work)
+        eviction_policy: Policy for handling cache eviction
+        touch_resend_n: Resend object every N touches (0 to disable periodic resend)
     """
     enabled: bool = True
     object_cache_size: int = 128
     encoder: Optional[Encoder] = None
     transport: Optional[Transport] = None
+    eviction_policy: EvictionPolicy = EvictionPolicy.EVICT_AND_LOG
+    touch_resend_n: int = 100
 
     def __post_init__(self):
         """Set default encoder if not provided."""
@@ -69,24 +96,34 @@ class SporesConfig:
 # Global state
 _config: Optional[SporesConfig] = None
 _object_cache: Optional[ObjectLRUCache[str, Object]] = None
+_config_lock = threading.RLock()  # Reentrant lock for global state initialization
+_config_initialized = False  # Track whether configure() has been called
+_cache_metrics = CacheMetrics()  # Track cache eviction statistics
 
 
 def configure(
     enabled: bool = True,
     object_cache_size: int = 128,
     encoder: Optional[Encoder] = None,
-    transport: Optional[Transport] = None
+    transport: Optional[Transport] = None,
+    eviction_policy: Union[EvictionPolicy, str] = EvictionPolicy.EVICT_AND_LOG,
+    touch_resend_n: int = 100
 ) -> None:
     """
-    Configure the Spores logging system.
+    Configure the Spores logging system (thread-safe).
 
     This should be called once at application startup.
+    If called multiple times, the last call wins.
+
+    Thread-safe: Can be called from multiple threads concurrently.
 
     Args:
         enabled: Whether spores logging is enabled (default: True)
         object_cache_size: Maximum objects in LRU cache (default: 128)
         encoder: Encoder instance (defaults to JSONEncoder)
         transport: Transport instance (required for logging to work)
+        eviction_policy: Policy for cache eviction (default: evict_and_log)
+        touch_resend_n: Resend object every N touches (default: 100, 0 to disable)
 
     Example:
         ```python
@@ -94,72 +131,183 @@ def configure(
 
         spore.configure(
             transport=FileTransport("logs/ocel.jsonl"),
-            object_cache_size=256
+            object_cache_size=256,
+            touch_resend_n=100,
         )
         ```
     """
-    global _config, _object_cache
-
-    _config = SporesConfig(
-        enabled=enabled,
-        object_cache_size=object_cache_size,
-        encoder=encoder,
-        transport=transport
-    )
-
-    # Create object cache with eviction callback
-    def on_evict(object_id: str, obj: Object):
-        """Send object when evicted from cache."""
-        try:
-            loop = asyncio.get_event_loop()
-            if loop.is_running():
-                asyncio.create_task(_send_log_record(LogRecord(object=obj)))
-            else:
-                # No running loop, schedule the coroutine
-                asyncio.ensure_future(_send_log_record(LogRecord(object=obj)))
-        except RuntimeError:
-            # No event loop at all, ignore for now
-            pass
-
-    def on_first_sight(object_id: str, obj: Object):
-        """Send object when first seen."""
-        try:
-            loop = asyncio.get_event_loop()
-            if loop.is_running():
-                asyncio.create_task(_send_log_record(LogRecord(object=obj)))
-            else:
-                # No running loop, schedule the coroutine
-                asyncio.ensure_future(_send_log_record(LogRecord(object=obj)))
-        except RuntimeError:
-            # No event loop at all, ignore for now
-            pass
+    global _config, _object_cache, _config_initialized, _cache_metrics
+
+    # Convert string to EvictionPolicy if needed
+    if isinstance(eviction_policy, str):
+        eviction_policy = EvictionPolicy(eviction_policy)
+
+    with _config_lock:
+        # Warn if already configured (but allow reconfiguration)
+        if _config_initialized:
+            logger.warning(
+                "Spores already configured. Reconfiguring may cause issues. "
+                "Ensure configure() is called only once at startup."
+            )
+
+        # Create new config (atomic under lock)
+        _config = SporesConfig(
+            enabled=enabled,
+            object_cache_size=object_cache_size,
+            encoder=encoder,
+            transport=transport,
+            eviction_policy=eviction_policy,
+            touch_resend_n=touch_resend_n
+        )
 
-    _object_cache = ObjectLRUCache(
-        maxsize=object_cache_size,
-        on_evict=on_evict,
-        on_first_sight=on_first_sight
-    )
+        # Reset metrics on reconfiguration
+        _cache_metrics = CacheMetrics()
 
-    logger.info(f"Spores configured: enabled={enabled}, cache_size={object_cache_size}")
+        # Create object cache with unified callback
+        def needs_logged(object_id: str, obj: Object):
+            """Log object when it needs to be logged (first sight, eviction, change, or Nth touch)."""
+            global _cache_metrics
+
+            try:
+                loop = asyncio.get_event_loop()
+                if loop.is_running():
+                    # Async context: schedule task
+                    asyncio.create_task(_send_log_record(LogRecord(object=obj)))
+                else:
+                    # No running loop, use sync path
+                    _send_log_record_sync(LogRecord(object=obj))
+            except RuntimeError:
+                # No event loop at all, use sync path
+                try:
+                    _send_log_record_sync(LogRecord(object=obj))
+                except Exception as e:
+                    logger.error(f"Failed to log object {object_id}: {e}")
+
+        _object_cache = ObjectLRUCache(
+            maxsize=object_cache_size,
+            needs_logged=needs_logged,
+            touch_resend_n=touch_resend_n,
+            metrics=_cache_metrics
+        )
+
+        _config_initialized = True
+
+    logger.info(f"Spores configured: enabled={enabled}, cache_size={object_cache_size}, eviction_policy={eviction_policy.value}")
 
 
 def get_config() -> SporesConfig:
-    """Get the current spores configuration."""
-    global _config
-    if _config is None:
-        # Use default configuration
-        _config = SporesConfig()
+    """
+    Get the current spores configuration (thread-safe).
+
+    If no configuration exists, creates a default one.
+    Thread-safe: Can be called from multiple threads concurrently.
+    """
+    global _config, _config_initialized
+
+    # Fast path: read without lock (GIL protects single read)
+    if _config is not None:
+        return _config
+
+    # Slow path: needs initialization
+    with _config_lock:
+        # Double-check: another thread may have initialized while we waited
+        if _config is None:
+            # Initialize with defaults
+            _config = SporesConfig()
+            _config_initialized = True
+
     return _config
 
 
 def get_object_cache() -> ObjectLRUCache[str, Object]:
-    """Get the object cache."""
+    """
+    Get the object cache (thread-safe).
+
+    If no cache exists, initializes with default configuration.
+    Thread-safe: Can be called from multiple threads concurrently.
+    """
     global _object_cache
-    if _object_cache is None:
-        configure()  # Initialize with defaults
+
+    # Fast path: read without lock (GIL protects single read)
+    if _object_cache is not None:
+        return _object_cache
+
+    # Slow path: needs initialization
+    with _config_lock:
+        # Double-check: another thread may have initialized while we waited
+        if _object_cache is None:
+            # Trigger full initialization
+            configure()  # Will acquire lock again, but that's OK (reentrant in same thread)
+
     return _object_cache
 
 
+def flush_object_cache() -> None:
+    """
+    Flush all objects from the cache to the log.
+
+    This forces all cached objects to be written, even if they haven't
+    been evicted yet. Use this before application shutdown to ensure
+    all objects are logged.
+
+    Thread-safe: Can be called from multiple threads concurrently.
+
+    Example:
+        ```python
+        from mycorrhizal.spores import configure, flush_object_cache
+        from mycorrhizal.spores.transport import FileTransport
+
+        configure(transport=FileTransport("logs/ocel.jsonl"))
+
+        # ... application logic ...
+
+        flush_object_cache()  # Ensure all objects logged
+        ```
+    """
+    cache = get_object_cache()
+    config = get_config()
+
+    if not config.enabled:
+        return
+
+    # Get all objects currently in cache
+    all_objects = list(cache._cache.values())
+
+    # Log each object
+    flushed_count = 0
+    for entry in all_objects:
+        try:
+            # Use sync path to ensure it's written
+            _send_log_record_sync(LogRecord(object=entry.object))
+            flushed_count += 1
+        except Exception as e:
+            logger.error(f"Failed to flush object {entry.object.id}: {e}")
+
+    logger.info(f"Flushed {flushed_count} objects from cache")
+
+
+def get_cache_metrics() -> CacheMetrics:
+    """
+    Get cache eviction metrics.
+
+    Returns statistics about cache evictions and failures.
+
+    Returns:
+        CacheMetrics with eviction statistics
+
+    Example:
+        ```python
+        from mycorrhizal.spores import get_cache_metrics
+
+        metrics = get_cache_metrics()
+        print(f"Evictions: {metrics.evictions}")
+        print(f"Failures: {metrics.eviction_failures}")
+        ```
+    """
+    global _cache_metrics
+    return _cache_metrics
+
+
 async def _send_log_record(record: LogRecord) -> None:
     """
     Send a log record via the configured transport (async).
@@ -1236,6 +1384,13 @@ __all__ = [
     'configure',
     'get_config',
     'get_object_cache',
+    'flush_object_cache',
+    'get_cache_metrics',
+
+    # Types
+    'SporesConfig',
+    'EvictionPolicy',
+    'CacheMetrics',
 
     # Spore getters (explicit)
     'get_spore_sync',

mycorrhizal/spores/encoder/json.py

@@ -10,7 +10,7 @@ from __future__ import annotations
 
 import json
 from datetime import datetime
-from typing import Any, Dict
+from typing import Any, Dict, TYPE_CHECKING
 
 from .base import Encoder
 from ..models import LogRecord, Event, Object, Relationship, EventAttributeValue, ObjectAttributeValue
@@ -20,7 +20,7 @@ class JSONEncoder(Encoder):
     """
     JSON encoder for OCEL LogRecords.
 
-    Produces OCEL-compatible JSON.
+    Produces OCEL-compatible JSON with Unix float64 timestamps.
 
     Example output:
         {
@@ -28,9 +28,9 @@ class JSONEncoder(Encoder):
             "id": "evt-123",
             "type": "process_item",
             "activity": null,
-            "time": "2025-01-11T12:34:56.789000000Z",
+            "time": 1705689296.123456,
             "attributes": [
-              {"name": "priority", "value": "high", "type": "string", "time": null}
+              {"name": "priority", "value": "high", "type": "string"}
             ],
             "relationships": [
               {"objectId": "obj-456", "qualifier": "input"}
@@ -46,13 +46,21 @@ class JSONEncoder(Encoder):
             "id": "obj-456",
             "type": "WorkItem",
             "attributes": [
-              {"name": "status", "value": "pending", "type": "string", "time": null}
+              {"name": "status", "value": "pending", "type": "string", "time": 1705689296.123456}
             ],
             "relationships": []
           }
         }
     """
 
+    def __init__(self):
+        """
+        Initialize JSONEncoder.
+
+        Timestamps are always encoded as Unix float64 timestamps.
+        """
+        pass
+
     def encode(self, record: LogRecord) -> bytes:
         """
         Encode a LogRecord to JSON bytes.
@@ -136,33 +144,14 @@ class JSONEncoder(Encoder):
             "qualifier": qualifier
         }
 
-    def _format_datetime(self, dt: datetime) -> str:
+    def _format_datetime(self, dt: datetime) -> float:
         """
-        Format datetime to RFC3339Nano.
+        Format datetime as Unix float64 timestamp.
 
         Args:
             dt: The datetime to format
 
         Returns:
-            ISO format string with nanosecond precision
+            Unix float64 timestamp (seconds since epoch)
         """
-        # Python's isoformat() produces RFC3339-compatible output
-        # For nanosecond precision, we need to ensure it has 9 digits
-        iso = dt.isoformat()
-
-        # Add microseconds if not present (Python 3.11+ has timespec='nanoseconds')
-        if '.' not in iso:
-            iso += '.000000000'
-
-        # Ensure we have 9 digits of fractional seconds
-        if '.' in iso:
-            main, frac = iso.split('.')
-            # Pad or truncate to 9 digits
-            frac = (frac + '0' * 9)[:9]
-            iso = f"{main}.{frac}"
-
-        # Ensure timezone is Z (UTC) or offset
-        if iso.endswith('+00:00'):
-            iso = iso[:-6] + 'Z'
-
-        return iso
+        return dt.timestamp()

{mycorrhizal-0.2.0.dist-info → mycorrhizal-0.2.2.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: mycorrhizal
-Version: 0.2.0
+Version: 0.2.2
 Summary: Utilities and DSLs for modelling and implementing safe, performant, structured systems
 Author-email: Jeff Ciesielski <jeffciesielski@gmail.com>
 Requires-Python: >=3.10