flock-core 0.5.11__py3-none-any.whl → 0.5.20__py3-none-any.whl

flock/storage/sqlite/summary_queries.py

@@ -0,0 +1,194 @@
+"""SQLite summary query utilities.
+
+Provides focused methods for executing summary/aggregation queries.
+Extracted from summarize_artifacts to reduce complexity and improve testability.
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any
+
+
+if TYPE_CHECKING:
+    import aiosqlite
+
+
+class SQLiteSummaryQueries:
+    """
+    Executes summary SQL queries for artifact statistics.
+
+    Each method handles one specific aggregation query, making them
+    simple, testable, and easy to maintain.
+    """
+
+    async def count_total(
+        self,
+        conn: aiosqlite.Connection,
+        where_clause: str,
+        params: tuple[Any, ...],
+    ) -> int:
+        """
+        Get total artifact count.
+
+        Args:
+            conn: Database connection
+            where_clause: SQL WHERE clause (e.g., " WHERE type = ?")
+            params: Parameter values for WHERE clause
+
+        Returns:
+            Total count of matching artifacts
+        """
+        count_query = f"SELECT COUNT(*) AS total FROM artifacts{where_clause}"  # nosec B608
+        cursor = await conn.execute(count_query, params)
+        total_row = await cursor.fetchone()
+        await cursor.close()
+        return total_row["total"] if total_row else 0
+
+    async def group_by_type(
+        self,
+        conn: aiosqlite.Connection,
+        where_clause: str,
+        params: tuple[Any, ...],
+    ) -> dict[str, int]:
+        """
+        Get artifact counts grouped by type.
+
+        Args:
+            conn: Database connection
+            where_clause: SQL WHERE clause
+            params: Parameter values for WHERE clause
+
+        Returns:
+            Dict mapping canonical type names to counts
+        """
+        by_type_query = f"""
+            SELECT canonical_type, COUNT(*) AS count
+            FROM artifacts
+            {where_clause}
+            GROUP BY canonical_type
+        """  # nosec B608
+        cursor = await conn.execute(by_type_query, params)
+        by_type_rows = await cursor.fetchall()
+        await cursor.close()
+        return {row["canonical_type"]: row["count"] for row in by_type_rows}
+
+    async def group_by_producer(
+        self,
+        conn: aiosqlite.Connection,
+        where_clause: str,
+        params: tuple[Any, ...],
+    ) -> dict[str, int]:
+        """
+        Get artifact counts grouped by producer.
+
+        Args:
+            conn: Database connection
+            where_clause: SQL WHERE clause
+            params: Parameter values for WHERE clause
+
+        Returns:
+            Dict mapping producer names to counts
+        """
+        by_producer_query = f"""
+            SELECT produced_by, COUNT(*) AS count
+            FROM artifacts
+            {where_clause}
+            GROUP BY produced_by
+        """  # nosec B608
+        cursor = await conn.execute(by_producer_query, params)
+        by_producer_rows = await cursor.fetchall()
+        await cursor.close()
+        return {row["produced_by"]: row["count"] for row in by_producer_rows}
+
+    async def group_by_visibility(
+        self,
+        conn: aiosqlite.Connection,
+        where_clause: str,
+        params: tuple[Any, ...],
+    ) -> dict[str, int]:
+        """
+        Get artifact counts grouped by visibility kind.
+
+        Args:
+            conn: Database connection
+            where_clause: SQL WHERE clause
+            params: Parameter values for WHERE clause
+
+        Returns:
+            Dict mapping visibility kinds to counts
+        """
+        by_visibility_query = f"""
+            SELECT json_extract(visibility, '$.kind') AS visibility_kind, COUNT(*) AS count
+            FROM artifacts
+            {where_clause}
+            GROUP BY json_extract(visibility, '$.kind')
+        """  # nosec B608
+        cursor = await conn.execute(by_visibility_query, params)
+        by_visibility_rows = await cursor.fetchall()
+        await cursor.close()
+        return {
+            (row["visibility_kind"] or "Unknown"): row["count"]
+            for row in by_visibility_rows
+        }
+
+    async def count_tags(
+        self,
+        conn: aiosqlite.Connection,
+        where_clause: str,
+        params: tuple[Any, ...],
+    ) -> dict[str, int]:
+        """
+        Get tag occurrence counts.
+
+        Args:
+            conn: Database connection
+            where_clause: SQL WHERE clause
+            params: Parameter values for WHERE clause
+
+        Returns:
+            Dict mapping tag names to occurrence counts
+        """
+        tag_query = f"""
+            SELECT json_each.value AS tag, COUNT(*) AS count
+            FROM artifacts
+            JOIN json_each(artifacts.tags)
+            {where_clause}
+            GROUP BY json_each.value
+        """  # nosec B608
+        cursor = await conn.execute(tag_query, params)
+        tag_rows = await cursor.fetchall()
+        await cursor.close()
+        return {row["tag"]: row["count"] for row in tag_rows}
+
+    async def get_date_range(
+        self,
+        conn: aiosqlite.Connection,
+        where_clause: str,
+        params: tuple[Any, ...],
+    ) -> tuple[str | None, str | None]:
+        """
+        Get earliest and latest creation timestamps.
+
+        Args:
+            conn: Database connection
+            where_clause: SQL WHERE clause
+            params: Parameter values for WHERE clause
+
+        Returns:
+            Tuple of (earliest, latest) ISO timestamp strings, or (None, None)
+        """
+        range_query = f"""
+            SELECT MIN(created_at) AS earliest, MAX(created_at) AS latest
+            FROM artifacts
+            {where_clause}
+        """  # nosec B608
+        cursor = await conn.execute(range_query, params)
+        range_row = await cursor.fetchone()
+        await cursor.close()
+
+        if not range_row:
+            return None, None
+
+        earliest = range_row["earliest"] if range_row["earliest"] else None
+        latest = range_row["latest"] if range_row["latest"] else None
+        return earliest, latest

flock/utils/__init__.py

@@ -0,0 +1,14 @@
+"""Shared utilities for Flock framework."""
+
+from flock.utils.type_resolution import TypeResolutionHelper
+from flock.utils.visibility import VisibilityDeserializer
+from flock.utils.async_utils import async_lock_required, AsyncLockRequired
+from flock.utils.validation import ArtifactValidator
+
+__all__ = [
+    "TypeResolutionHelper",
+    "VisibilityDeserializer",
+    "async_lock_required",
+    "AsyncLockRequired",
+    "ArtifactValidator",
+]

flock/utils/async_utils.py

@@ -0,0 +1,67 @@
+"""Async utility decorators and helpers."""
+
+from collections.abc import Callable
+from functools import wraps
+from typing import Any, TypeVar
+
+
+T = TypeVar("T")
+
+
+class AsyncLockRequired:
+    """Decorator ensuring async lock acquisition.
+
+    This utility eliminates 15+ duplicate lock acquisition patterns
+    scattered throughout orchestrator.py and agent.py.
+    """
+
+    def __init__(self, lock_attr: str = "_lock"):
+        """
+        Initialize decorator.
+
+        Args:
+            lock_attr: Name of lock attribute on class (default: "_lock")
+        """
+        self.lock_attr = lock_attr
+
+    def __call__(self, func: Callable[..., Any]) -> Callable[..., Any]:
+        """Apply decorator to function."""
+        lock_attr = self.lock_attr  # Capture in closure
+
+        @wraps(func)
+        async def wrapper(instance: Any, *args: Any, **kwargs: Any) -> Any:
+            lock = getattr(instance, lock_attr)
+            async with lock:
+                return await func(instance, *args, **kwargs)
+
+        return wrapper
+
+
+def async_lock_required(lock_attr: str = "_lock") -> AsyncLockRequired:
+    """
+    Decorator ensuring async lock acquisition.
+
+    This decorator automatically acquires and releases an async lock
+    before executing the decorated method, preventing race conditions.
+
+    Args:
+        lock_attr: Name of the lock attribute on the class (default: "_lock")
+
+    Returns:
+        AsyncLockRequired decorator instance
+
+    Example:
+        >>> class MyClass:
+        ...     def __init__(self):
+        ...         self._lock = asyncio.Lock()
+        ...
+        ...     @async_lock_required()
+        ...     async def my_method(self):
+        ...         # Lock automatically acquired here
+        ...         await asyncio.sleep(0.1)
+        ...         return "done"
+
+        >>> obj = MyClass()
+        >>> result = await obj.my_method()  # Lock acquired/released automatically
+    """
+    return AsyncLockRequired(lock_attr)

flock/{runtime.py → utils/runtime.py}

@@ -7,7 +7,7 @@ from uuid import UUID
 
 from pydantic import BaseModel, ConfigDict, Field
 
-from flock.artifacts import Artifact
+from flock.core.artifacts import Artifact
 
 
 class EvalInputs(BaseModel):
@@ -99,7 +99,7 @@ class EvalResult(BaseModel):
             ...         )
             ...         return EvalResult.from_object(processed, agent=agent)
         """
-        from flock.artifacts import Artifact
+        from flock.core.artifacts import Artifact
         from flock.registry import type_registry
 
         type_name = type_registry.name_for(type(obj))
@@ -154,7 +154,7 @@ class EvalResult(BaseModel):
             ...             movie, tagline, agent=agent, metrics={"confidence": 0.9}
             ...         )
         """
-        from flock.artifacts import Artifact
+        from flock.core.artifacts import Artifact
         from flock.registry import type_registry
 
         artifacts = []

flock/utils/time_utils.py

@@ -0,0 +1,53 @@
+"""Time formatting utilities.
+
+Provides human-readable time span formatting for date ranges.
+"""
+
+from __future__ import annotations
+
+from datetime import datetime
+
+
+def format_time_span(earliest: datetime | None, latest: datetime | None) -> str:
+    """
+    Format time span between two datetimes as human-readable string.
+
+    Args:
+        earliest: Start datetime
+        latest: End datetime
+
+    Returns:
+        Human-readable span description:
+        - "X days" for spans >= 2 days
+        - "X.Y hours" for spans >= 1 hour
+        - "X minutes" for spans > 0
+        - "moments" for zero span
+        - "empty" if no dates provided
+
+    Examples:
+        >>> from datetime import datetime, timedelta
+        >>> now = datetime.now()
+        >>> format_time_span(now, now + timedelta(days=3))
+        "3 days"
+        >>> format_time_span(now, now + timedelta(hours=2))
+        "2.0 hours"
+        >>> format_time_span(now, now + timedelta(minutes=45))
+        "45 minutes"
+    """
+    if not earliest or not latest:
+        return "empty"
+
+    span = latest - earliest
+
+    if span.days >= 2:
+        return f"{span.days} days"
+
+    if span.total_seconds() >= 3600:
+        hours = span.total_seconds() / 3600
+        return f"{hours:.1f} hours"
+
+    if span.total_seconds() > 0:
+        minutes = max(1, int(span.total_seconds() / 60))
+        return f"{minutes} minutes"
+
+    return "moments"

flock/utils/type_resolution.py

@@ -0,0 +1,38 @@
+"""Type registry resolution utilities."""
+
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from flock.registry import TypeRegistry
+
+from flock.registry import RegistryError
+
+
+class TypeResolutionHelper:
+    """Helper for safe type resolution.
+
+    This utility eliminates 8+ duplicate type resolution patterns
+    scattered across agent.py, store.py, orchestrator.py, and context_provider.py.
+    """
+
+    @staticmethod
+    def safe_resolve(registry: "TypeRegistry", type_name: str) -> str:
+        """
+        Safely resolve type name to canonical form.
+
+        Args:
+            registry: Type registry instance
+            type_name: Type name to resolve
+
+        Returns:
+            Canonical type name (or original if not found)
+
+        Example:
+            >>> canonical = TypeResolutionHelper.safe_resolve(registry, "MyType")
+            >>> # Returns "my_module.MyType" if found, else "MyType"
+        """
+        try:
+            return registry.resolve_name(type_name)
+        except RegistryError:
+            # Type not found or ambiguous - return original name
+            return type_name

flock/{utilities.py → utils/utilities.py}

@@ -19,11 +19,11 @@ from rich.pretty import Pretty
 from rich.table import Table
 from rich.text import Text
 
-from flock.components import AgentComponent
+from flock.components.agent import AgentComponent
 
 
 if TYPE_CHECKING:
-    from flock.runtime import Context, EvalInputs, EvalResult
+    from flock.utils.runtime import Context, EvalInputs, EvalResult
 
 
 class MetricsUtility(AgentComponent):

flock/utils/validation.py

@@ -0,0 +1,57 @@
+"""Common validation utilities."""
+
+from typing import Any, Callable
+
+from pydantic import BaseModel, ValidationError
+
+
+class ArtifactValidator:
+    """Validates artifacts against predicates.
+
+    This utility consolidates artifact validation patterns
+    used across agent.py for output validation.
+    """
+
+    @staticmethod
+    def validate_artifact(
+        artifact: Any,
+        model_cls: type[BaseModel],
+        predicate: Callable[[BaseModel], bool] | None = None,
+    ) -> tuple[bool, BaseModel | None, str | None]:
+        """
+        Validate artifact payload against model and optional predicate.
+
+        Args:
+            artifact: Artifact to validate
+            model_cls: Pydantic model class
+            predicate: Optional validation predicate
+
+        Returns:
+            Tuple of (is_valid, model_instance, error_message)
+
+        Example:
+            >>> from pydantic import BaseModel
+            >>> class MyModel(BaseModel):
+            ...     name: str
+            ...     age: int
+            >>> artifact = type("obj", (), {"payload": {"name": "Alice", "age": 30}})()
+            >>> is_valid, model, error = ArtifactValidator.validate_artifact(
+            ...     artifact, MyModel, lambda m: m.age >= 18
+            ... )
+            >>> assert is_valid
+            >>> assert model.name == "Alice"
+        """
+        try:
+            # Validate against model
+            model_instance = model_cls(**artifact.payload)
+
+            # Apply predicate if provided
+            if predicate and not predicate(model_instance):
+                return False, model_instance, "Predicate validation failed"
+
+            return True, model_instance, None
+
+        except ValidationError as e:
+            return False, None, str(e)
+        except Exception as e:
+            return False, None, f"Validation error: {e}"

flock/utils/visibility.py

@@ -0,0 +1,79 @@
+"""Visibility deserialization utilities."""
+
+from datetime import timedelta
+from typing import Any
+
+from flock.core.visibility import (
+    AfterVisibility,
+    LabelledVisibility,
+    PrivateVisibility,
+    PublicVisibility,
+    TenantVisibility,
+    Visibility,
+)
+
+
+class VisibilityDeserializer:
+    """Deserializes visibility from dict/str representation.
+
+    This utility eliminates 5+ duplicate visibility deserialization patterns
+    scattered across store.py, context_provider.py, and orchestrator.py.
+    """
+
+    @staticmethod
+    def deserialize(data: dict[str, Any] | str) -> Visibility:
+        """
+        Deserialize visibility from various formats.
+
+        Args:
+            data: Dict with 'kind' field or string
+
+        Returns:
+            Visibility instance
+
+        Raises:
+            ValueError: If visibility kind is unknown
+
+        Example:
+            >>> vis = VisibilityDeserializer.deserialize({"kind": "Public"})
+            >>> assert isinstance(vis, PublicVisibility)
+        """
+        if isinstance(data, str):
+            kind = data
+            props = {}
+        else:
+            kind = data.get("kind")
+            props = data
+
+        if kind == "Public":
+            return PublicVisibility()
+
+        if kind == "Private":
+            agents = set(props.get("agents", []))
+            return PrivateVisibility(agents=agents)
+
+        if kind == "Labelled":
+            required_labels = set(props.get("required_labels", []))
+            return LabelledVisibility(required_labels=required_labels)
+
+        if kind == "Tenant":
+            tenant_id = props.get("tenant_id")
+            return TenantVisibility(tenant_id=tenant_id)
+
+        if kind == "After":
+            ttl_value = props.get("ttl")
+            # Handle timedelta or raw seconds
+            if isinstance(ttl_value, (int, float)):
+                ttl = timedelta(seconds=ttl_value)
+            elif isinstance(ttl_value, dict):
+                # Pydantic dict representation
+                ttl = timedelta(**ttl_value)
+            else:
+                ttl = ttl_value or timedelta()
+
+            then_data = props.get("then")
+            then = VisibilityDeserializer.deserialize(then_data) if then_data else None
+
+            return AfterVisibility(ttl=ttl, then=then)
+
+        raise ValueError(f"Unknown visibility kind: {kind}")

flock/utils/visibility_utils.py

@@ -0,0 +1,134 @@
+"""Visibility deserialization utilities.
+
+This module handles complex visibility object deserialization from JSON data.
+Extracted from store.py to reduce complexity and improve testability.
+"""
+
+from __future__ import annotations
+
+import re
+from datetime import timedelta
+from typing import Any
+
+from flock.core.visibility import (
+    AfterVisibility,
+    LabelledVisibility,
+    PrivateVisibility,
+    PublicVisibility,
+    TenantVisibility,
+    Visibility,
+)
+
+
+ISO_DURATION_RE = re.compile(
+    r"^P(?:T?(?:(?P<hours>\d+)H)?(?:(?P<minutes>\d+)M)?(?:(?P<seconds>\d+)S)?)$"
+)
+
+
+def parse_iso_duration(value: str | None) -> timedelta:
+    """
+    Parse ISO 8601 duration string to timedelta.
+
+    Args:
+        value: ISO 8601 duration string (e.g., "PT1H30M")
+
+    Returns:
+        Parsed timedelta, or zero timedelta if invalid
+
+    Examples:
+        >>> parse_iso_duration("PT1H")
+        timedelta(hours=1)
+        >>> parse_iso_duration("PT30M")
+        timedelta(minutes=30)
+        >>> parse_iso_duration(None)
+        timedelta(0)
+    """
+    if not value:
+        return timedelta(0)
+    match = ISO_DURATION_RE.match(value)
+    if not match:
+        return timedelta(0)
+    hours = int(match.group("hours") or 0)
+    minutes = int(match.group("minutes") or 0)
+    seconds = int(match.group("seconds") or 0)
+    return timedelta(hours=hours, minutes=minutes, seconds=seconds)
+
+
+def deserialize_visibility(data: Any) -> Visibility:
+    """
+    Deserialize visibility object from JSON data.
+
+    Handles all visibility types: Public, Private, Labelled, Tenant, After.
+    Uses dictionary dispatch to reduce complexity vs if-elif chain.
+
+    Args:
+        data: JSON data dict or Visibility instance
+
+    Returns:
+        Visibility object (defaults to PublicVisibility if invalid)
+
+    Examples:
+        >>> deserialize_visibility({"kind": "Public"})
+        PublicVisibility()
+        >>> deserialize_visibility({"kind": "Private", "agents": ["agent1"]})
+        PrivateVisibility(agents={"agent1"})
+    """
+    # Early returns for simple cases
+    if isinstance(data, Visibility):
+        return data
+    if not data:
+        return PublicVisibility()
+
+    # Extract kind
+    kind = data.get("kind") if isinstance(data, dict) else None
+    if not kind:
+        return PublicVisibility()
+
+    # Dispatch to appropriate deserializer
+    return _VISIBILITY_DESERIALIZERS.get(kind, _deserialize_public)(data)
+
+
+def _deserialize_public(data: dict[str, Any]) -> PublicVisibility:
+    """Deserialize PublicVisibility."""
+    return PublicVisibility()
+
+
+def _deserialize_private(data: dict[str, Any]) -> PrivateVisibility:
+    """Deserialize PrivateVisibility."""
+    return PrivateVisibility(agents=set(data.get("agents", [])))
+
+
+def _deserialize_labelled(data: dict[str, Any]) -> LabelledVisibility:
+    """Deserialize LabelledVisibility."""
+    return LabelledVisibility(required_labels=set(data.get("required_labels", [])))
+
+
+def _deserialize_tenant(data: dict[str, Any]) -> TenantVisibility:
+    """Deserialize TenantVisibility."""
+    return TenantVisibility(tenant_id=data.get("tenant_id"))
+
+
+def _deserialize_after(data: dict[str, Any]) -> AfterVisibility:
+    """
+    Deserialize AfterVisibility with recursive 'then' handling.
+
+    Args:
+        data: JSON data dict with 'ttl' and optional 'then' fields
+
+    Returns:
+        AfterVisibility instance
+    """
+    ttl = parse_iso_duration(data.get("ttl"))
+    then_data = data.get("then") if isinstance(data, dict) else None
+    then_visibility = deserialize_visibility(then_data) if then_data else None
+    return AfterVisibility(ttl=ttl, then=then_visibility)
+
+
+# Dispatch table for visibility types
+_VISIBILITY_DESERIALIZERS = {
+    "Public": _deserialize_public,
+    "Private": _deserialize_private,
+    "Labelled": _deserialize_labelled,
+    "Tenant": _deserialize_tenant,
+    "After": _deserialize_after,
+}