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

mycorrhizal/spores/models.py

@@ -35,16 +35,16 @@ class EventAttributeValue:
     """
     An attribute value for an event.
 
-    OCEL attributes include timestamps for versioning.
+    Event attributes don't have timestamps because the event time itself is sufficient.
 
     Attributes:
         name: The attribute name
         value: The string representation of the value
-        time: When this attribute value was set
+        type: The data type ("string", "integer", "float", "boolean", "timestamp")
     """
     name: str
     value: str
-    time: datetime
+    type: str
 
 
 @dataclass(frozen=True)
@@ -57,11 +57,13 @@ class ObjectAttributeValue:
     Attributes:
         name: The attribute name
         value: The string representation of the value
+        type: The data type ("string", "integer", "float", "boolean", "timestamp")
         time: When this attribute value was set
     """
     name: str
     value: str
-    time: datetime
+    type: str
+    time: Optional[datetime] = None
 
 
 @dataclass
@@ -71,14 +73,16 @@ class Event:
 
     Attributes:
         id: Unique event identifier
-        type: Event type/category
+        type: Event type/category (event class)
+        activity: Optional semantic activity label (defaults to type if null)
         time: When the event occurred
         attributes: Event attributes (name -> EventAttributeValue)
         relationships: Objects related to this event (qualifier -> Relationship)
     """
     id: str
     type: str
-    time: datetime
+    activity: Optional[str] = None
+    time: datetime = field(default_factory=datetime.now)
     attributes: Dict[str, EventAttributeValue] = field(default_factory=dict)
     relationships: Dict[str, Relationship] = field(default_factory=dict)
 
@@ -174,23 +178,71 @@ class EventAttr:
     name: Optional[str] = None
 
 
+@dataclass(frozen=True)
+class SporesAttr:
+    """
+    Metadata annotation for object attributes in OCEL object logging.
+
+    Used with typing.Annotated to mark fields that should be logged when an object is logged:
+
+        class Order(BaseModel):
+            id: str
+            status: Annotated[str, SporesAttr]  # Logged
+            total: Annotated[float, SporesAttr]  # Logged
+            items: list[dict]  # Not marked - not logged
+
+    When using @spore.log_event(relationships={...}), fields marked with SporesAttr
+    are automatically logged. If attributes list is provided, it overrides SporesAttr.
+
+    Attributes:
+        name: Optional custom name for the attribute (defaults to field name)
+    """
+    name: Optional[str] = None
+
+
+# ============================================================================
+# Type Inference
+# ============================================================================
+
+def infer_type(value: Any) -> str:
+    """
+    Infer the OCEL type for a Python value.
+
+    Args:
+        value: The Python value to infer type for
+
+    Returns:
+        One of: "string", "integer", "float", "boolean", "timestamp"
+    """
+    if isinstance(value, bool):
+        return "boolean"
+    elif isinstance(value, int):
+        return "integer"
+    elif isinstance(value, float):
+        return "float"
+    elif isinstance(value, datetime):
+        return "timestamp"
+    else:
+        return "string"
+
+
 # ============================================================================
 # Attribute Value Conversion
 # ============================================================================
 
-def attribute_value_from_python(value: Any, time: datetime) -> EventAttributeValue:
+def attribute_value_from_python(value: Any) -> EventAttributeValue:
     """
     Convert a Python value to an OCEL EventAttributeValue.
 
-    All values are converted to strings per OCEL specification.
-
     Args:
         value: The Python value to convert
-        time: The timestamp for this attribute value
 
     Returns:
-        An EventAttributeValue with string representation
+        An EventAttributeValue with type information
     """
+    # Infer type
+    attr_type = infer_type(value)
+
     # Handle None
     if value is None:
         str_value = "null"
@@ -218,30 +270,33 @@ def attribute_value_from_python(value: Any, time: datetime) -> EventAttributeVal
     return EventAttributeValue(
         name="",  # Name set by caller
         value=str_value,
-        time=time
+        type=attr_type
     )
 
 
-def object_attribute_from_python(value: Any, time: datetime) -> ObjectAttributeValue:
+def object_attribute_from_python(value: Any, time: Optional[datetime] = None) -> ObjectAttributeValue:
     """
     Convert a Python value to an OCEL ObjectAttributeValue.
 
-    Same conversion rules as attribute_value_from_python but for objects.
-
     Args:
         value: The Python value to convert
-        time: The timestamp for this attribute value
+        time: The timestamp for this attribute value (optional)
 
     Returns:
-        An ObjectAttributeValue with string representation
+        An ObjectAttributeValue with type information
     """
-    # Use same conversion logic
-    event_attr = attribute_value_from_python(value, time)
+    # Use same type inference logic
+    event_attr = attribute_value_from_python(value)
+
+    # Default to current time if not provided
+    if time is None:
+        time = datetime.now()
 
     return ObjectAttributeValue(
         name=event_attr.name,
         value=event_attr.value,
-        time=event_attr.time
+        type=event_attr.type,
+        time=time
     )
 
 

mycorrhizal/spores/transport/__init__.py

@@ -5,6 +5,13 @@ Spores Transports
 Transports for sending OCEL LogRecords to various destinations.
 """
 
-from .base import Transport
+from .base import SyncTransport, AsyncTransport, Transport
+from .file import SyncFileTransport, AsyncFileTransport
 
-__all__ = ['Transport']
+__all__ = [
+    'SyncTransport',
+    'AsyncTransport',
+    'Transport',  # Backward compatibility alias for AsyncTransport
+    'SyncFileTransport',
+    'AsyncFileTransport',
+]

mycorrhizal/spores/transport/base.py

@@ -2,26 +2,28 @@
 """
 Spores Transport Interface
 
-Abstract base class for transporting encoded LogRecords.
+Protocols for transporting encoded LogRecords.
+Separate sync and async protocols for clarity.
 """
 
 from __future__ import annotations
 
-from abc import ABC, abstractmethod
-from typing import Protocol, Callable, Optional
+from typing import Protocol
 
 
-class Transport(Protocol):
+class SyncTransport(Protocol):
     """
-    Protocol for transports that send encoded LogRecords.
+    Protocol for synchronous transports (blocking I/O).
 
-    Transports handle the actual delivery of log records to consumers
-    (e.g., HTTP POST, files, message queues, etc.).
+    Sync transports use blocking send() - they write data immediately
+    and block until complete. Use these with get_spore_sync().
+
+    Examples: file writes, blocking HTTP requests, etc.
     """
 
-    async def send(self, data: bytes, content_type: str) -> None:
+    def send(self, data: bytes, content_type: str) -> None:
         """
-        Send encoded data to the transport destination.
+        Send encoded data to the transport destination (blocking).
 
         Args:
             data: The encoded log record data
@@ -29,18 +31,35 @@ class Transport(Protocol):
         """
         ...
 
-    def is_async(self) -> bool:
-        """
-        Return True if this transport is async (non-blocking).
+    def close(self) -> None:
+        """Close the transport and release resources."""
+        ...
+
+
+class AsyncTransport(Protocol):
+    """
+    Protocol for asynchronous transports (async I/O).
+
+    Async transports use non-blocking async send() - they await completion.
+    Use these with get_spore_async().
 
-        Async transports don't block the caller when sending data.
-        They typically use background threads, queues, or async I/O.
+    Examples: async file writes, async HTTP requests, message queues, etc.
+    """
 
-        Returns:
-            True if transport is async, False if synchronous
+    async def send(self, data: bytes, content_type: str) -> None:
+        """
+        Send encoded data to the transport destination (async).
+
+        Args:
+            data: The encoded log record data
+            content_type: MIME content type (e.g., "application/json")
         """
         ...
 
-    def close(self) -> None:
+    async def close(self) -> None:
         """Close the transport and release resources."""
         ...
+
+
+# Backward compatibility alias
+Transport = AsyncTransport

mycorrhizal/spores/transport/file.py

@@ -0,0 +1,126 @@
+#!/usr/bin/env python3
+"""
+Spores File Transports
+
+File-based transports for OCEL log records.
+Includes both synchronous (blocking I/O) and asynchronous (async I/O) implementations.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import threading
+from pathlib import Path
+from typing import Optional
+
+
+class SyncFileTransport:
+    """
+    Synchronous file transport using blocking I/O.
+
+    Writes log records to a file in JSONL format (one JSON object per line).
+    Thread-safe with a lock for concurrent writes.
+    """
+
+    def __init__(self, filepath: str | Path):
+        """
+        Initialize the file transport.
+
+        Args:
+            filepath: Path to the log file. Will be created if it doesn't exist.
+        """
+        self.filepath = Path(filepath)
+        self.filepath.parent.mkdir(parents=True, exist_ok=True)
+        self._file = open(self.filepath, 'a', encoding='utf-8')
+        self._lock = threading.Lock()
+
+    def send(self, data: bytes, content_type: str) -> None:
+        """
+        Write data to file (blocking call).
+
+        Args:
+            data: Encoded log record data
+            content_type: MIME content type (e.g., "application/json")
+        """
+        with self._lock:
+            self._file.write(data.decode('utf-8') + '\n')
+            self._file.flush()
+
+    def close(self) -> None:
+        """Close the file handle."""
+        with self._lock:
+            if self._file and not self._file.closed:
+                self._file.close()
+                self._file = None
+
+    def __enter__(self):
+        """Context manager support."""
+        return self
+
+    def __exit__(self, exc_type, exc_val, exc_tb):
+        """Context manager support."""
+        self.close()
+
+
+class AsyncFileTransport:
+    """
+    Asynchronous file transport using async I/O.
+
+    Writes log records to a file in JSONL format (one JSON object per line).
+    Uses asyncio.to_thread() for non-blocking async file I/O.
+
+    This is the async version of SyncFileTransport - use it with get_spore_async().
+    """
+
+    def __init__(self, filepath: str | Path):
+        """
+        Initialize the async file transport.
+
+        Args:
+            filepath: Path to the log file. Will be created if it doesn't exist.
+        """
+        self.filepath = Path(filepath)
+        self.filepath.parent.mkdir(parents=True, exist_ok=True)
+        # Open file in append mode, will be managed by asyncio.to_thread
+        self._file = open(self.filepath, 'a', encoding='utf-8')
+        self._lock = asyncio.Lock()
+
+    async def send(self, data: bytes, content_type: str) -> None:
+        """
+        Write data to file asynchronously.
+
+        Uses asyncio.to_thread() to run blocking I/O in a thread pool,
+        avoiding the need for external dependencies like aiofiles.
+
+        Args:
+            data: Encoded log record data
+            content_type: MIME content type (e.g., "application/json")
+        """
+        async with self._lock:
+            # Run blocking file I/O in thread pool
+            await asyncio.to_thread(self._write_sync, data)
+
+    def _write_sync(self, data: bytes) -> None:
+        """
+        Synchronous write helper - runs in thread pool.
+
+        Args:
+            data: Encoded log record data
+        """
+        self._file.write(data.decode('utf-8') + '\n')
+        self._file.flush()
+
+    async def close(self) -> None:
+        """Close the file handle asynchronously."""
+        async with self._lock:
+            if self._file and not self._file.closed:
+                await asyncio.to_thread(self._file.close)
+                self._file = None
+
+    async def __aenter__(self):
+        """Async context manager support."""
+        return self
+
+    async def __aexit__(self, exc_type, exc_val, exc_tb):
+        """Async context manager support."""
+        await self.close()