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

flock/storage/sqlite/schema_manager.py

@@ -0,0 +1,168 @@
+"""SQLite schema management for Flock blackboard store.
+
+This module handles database schema creation, versioning, and migrations.
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+
+if TYPE_CHECKING:
+    import aiosqlite
+
+
+class SQLiteSchemaManager:
+    """
+    Manages SQLite database schema for blackboard storage.
+
+    Responsibilities:
+    - Schema version tracking
+    - Table creation
+    - Index creation
+    - Schema migrations
+
+    The schema includes:
+    - artifacts table: Core artifact storage
+    - artifact_consumptions table: Consumption tracking
+    - agent_snapshots table: Agent metadata
+    - schema_meta table: Version tracking
+    """
+
+    SCHEMA_VERSION = 3
+
+    async def apply_schema(self, conn: aiosqlite.Connection) -> None:
+        """
+        Apply the blackboard schema to the SQLite connection.
+
+        Creates all tables and indices if they don't exist. Handles schema
+        versioning and migrations.
+
+        Args:
+            conn: Active SQLite connection
+
+        Schema Tables:
+            - schema_meta: Tracks schema version
+            - artifacts: Core artifact storage
+            - artifact_consumptions: Consumption events
+            - agent_snapshots: Agent metadata
+        """
+        # Schema version tracking
+        await conn.execute(
+            """
+            CREATE TABLE IF NOT EXISTS schema_meta (
+                id INTEGER PRIMARY KEY CHECK (id = 1),
+                version INTEGER NOT NULL,
+                applied_at TEXT NOT NULL DEFAULT CURRENT_TIMESTAMP
+            )
+            """
+        )
+        await conn.execute(
+            """
+            INSERT OR IGNORE INTO schema_meta (id, version)
+            VALUES (1, ?)
+            """,
+            (self.SCHEMA_VERSION,),
+        )
+
+        # Main artifacts table
+        await conn.execute(
+            """
+            CREATE TABLE IF NOT EXISTS artifacts (
+                artifact_id TEXT PRIMARY KEY,
+                type TEXT NOT NULL,
+                canonical_type TEXT NOT NULL,
+                produced_by TEXT NOT NULL,
+                payload TEXT NOT NULL,
+                version INTEGER NOT NULL,
+                visibility TEXT NOT NULL,
+                tags TEXT NOT NULL,
+                correlation_id TEXT,
+                partition_key TEXT,
+                created_at TEXT NOT NULL
+            )
+            """
+        )
+
+        # Artifact indices for performance
+        await conn.execute(
+            """
+            CREATE INDEX IF NOT EXISTS idx_artifacts_canonical_type_created
+            ON artifacts(canonical_type, created_at)
+            """
+        )
+        await conn.execute(
+            """
+            CREATE INDEX IF NOT EXISTS idx_artifacts_produced_by_created
+            ON artifacts(produced_by, created_at)
+            """
+        )
+        await conn.execute(
+            """
+            CREATE INDEX IF NOT EXISTS idx_artifacts_correlation
+            ON artifacts(correlation_id)
+            """
+        )
+        await conn.execute(
+            """
+            CREATE INDEX IF NOT EXISTS idx_artifacts_partition
+            ON artifacts(partition_key)
+            """
+        )
+
+        # Consumption tracking table
+        await conn.execute(
+            """
+            CREATE TABLE IF NOT EXISTS artifact_consumptions (
+                artifact_id TEXT NOT NULL,
+                consumer TEXT NOT NULL,
+                run_id TEXT,
+                correlation_id TEXT,
+                consumed_at TEXT NOT NULL,
+                PRIMARY KEY (artifact_id, consumer, consumed_at)
+            )
+            """
+        )
+
+        # Consumption indices
+        await conn.execute(
+            """
+            CREATE INDEX IF NOT EXISTS idx_consumptions_artifact
+            ON artifact_consumptions(artifact_id)
+            """
+        )
+        await conn.execute(
+            """
+            CREATE INDEX IF NOT EXISTS idx_consumptions_consumer
+            ON artifact_consumptions(consumer)
+            """
+        )
+        await conn.execute(
+            """
+            CREATE INDEX IF NOT EXISTS idx_consumptions_correlation
+            ON artifact_consumptions(correlation_id)
+            """
+        )
+
+        # Agent snapshots table
+        await conn.execute(
+            """
+            CREATE TABLE IF NOT EXISTS agent_snapshots (
+                agent_name TEXT PRIMARY KEY,
+                description TEXT NOT NULL,
+                subscriptions TEXT NOT NULL,
+                output_types TEXT NOT NULL,
+                labels TEXT NOT NULL,
+                first_seen TEXT NOT NULL,
+                last_seen TEXT NOT NULL,
+                signature TEXT NOT NULL
+            )
+            """
+        )
+
+        # Update schema version
+        await conn.execute(
+            "UPDATE schema_meta SET version=? WHERE id=1",
+            (self.SCHEMA_VERSION,),
+        )
+        await conn.commit()

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}"