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

flock/storage/in_memory/history_aggregator.py

@@ -0,0 +1,115 @@
+"""Agent history aggregation for in-memory storage.
+
+Handles aggregation of produced/consumed artifacts for agent history summaries.
+Extracted from store.py to reduce complexity from B (7) to A (4).
+"""
+
+from __future__ import annotations
+
+from collections import defaultdict
+from typing import TYPE_CHECKING, Any
+
+
+if TYPE_CHECKING:
+    from flock.core.store import ArtifactEnvelope
+
+
+class HistoryAggregator:
+    """
+    Aggregate agent history from artifact envelopes.
+
+    Provides focused aggregation methods for produced and consumed artifacts,
+    keeping complexity low through functional patterns.
+    """
+
+    def aggregate(
+        self, envelopes: list[ArtifactEnvelope], agent_id: str
+    ) -> dict[str, Any]:
+        """
+        Aggregate produced and consumed statistics for an agent.
+
+        Args:
+            envelopes: List of artifact envelopes with consumptions
+            agent_id: Agent to aggregate history for
+
+        Returns:
+            Dictionary with produced and consumed statistics:
+            {
+                "produced": {"total": int, "by_type": dict[str, int]},
+                "consumed": {"total": int, "by_type": dict[str, int]}
+            }
+
+        Examples:
+            >>> aggregator = HistoryAggregator()
+            >>> summary = aggregator.aggregate(envelopes, "agent1")
+            >>> summary["produced"]["total"]
+            42
+        """
+        produced = self._aggregate_produced(envelopes, agent_id)
+        consumed = self._aggregate_consumed(envelopes, agent_id)
+
+        return {
+            "produced": {
+                "total": sum(produced.values()),
+                "by_type": dict(produced),
+            },
+            "consumed": {
+                "total": sum(consumed.values()),
+                "by_type": dict(consumed),
+            },
+        }
+
+    def _aggregate_produced(
+        self, envelopes: list[ArtifactEnvelope], agent_id: str
+    ) -> defaultdict[str, int]:
+        """
+        Count artifacts produced by agent, grouped by type.
+
+        Args:
+            envelopes: Artifact envelopes to analyze
+            agent_id: Producer to match
+
+        Returns:
+            Dict mapping artifact types to counts
+        """
+        from flock.core.store import ArtifactEnvelope
+
+        produced_by_type: defaultdict[str, int] = defaultdict(int)
+
+        for envelope in envelopes:
+            if not isinstance(envelope, ArtifactEnvelope):
+                raise TypeError("Expected ArtifactEnvelope instance")
+
+            artifact = envelope.artifact
+            if artifact.produced_by == agent_id:
+                produced_by_type[artifact.type] += 1
+
+        return produced_by_type
+
+    def _aggregate_consumed(
+        self, envelopes: list[ArtifactEnvelope], agent_id: str
+    ) -> defaultdict[str, int]:
+        """
+        Count artifacts consumed by agent, grouped by type.
+
+        Args:
+            envelopes: Artifact envelopes with consumption records
+            agent_id: Consumer to match
+
+        Returns:
+            Dict mapping artifact types to consumption counts
+        """
+        from flock.core.store import ArtifactEnvelope
+
+        consumed_by_type: defaultdict[str, int] = defaultdict(int)
+
+        for envelope in envelopes:
+            if not isinstance(envelope, ArtifactEnvelope):
+                raise TypeError("Expected ArtifactEnvelope instance")
+
+            artifact = envelope.artifact
+            for consumption in envelope.consumptions:
+                if consumption.consumer == agent_id:
+                    consumed_by_type[artifact.type] += 1
+
+        return consumed_by_type

flock/storage/sqlite/__init__.py

@@ -0,0 +1,10 @@
+"""SQLite storage backend components."""
+
+from flock.storage.sqlite.query_builder import SQLiteQueryBuilder
+from flock.storage.sqlite.schema_manager import SQLiteSchemaManager
+
+
+__all__ = [
+    "SQLiteQueryBuilder",
+    "SQLiteSchemaManager",
+]

flock/storage/sqlite/agent_history_queries.py

@@ -0,0 +1,154 @@
+"""Agent history query utilities for SQLite storage.
+
+Handles agent-specific produced/consumed queries for history summaries.
+Extracted from store.py to reduce complexity from B (10) to A (5).
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any
+
+
+if TYPE_CHECKING:
+    import aiosqlite
+
+    from flock.core.store import FilterConfig
+
+
+class AgentHistoryQueries:
+    """
+    Execute SQLite queries for agent history summaries.
+
+    Provides focused methods for querying produced and consumed artifacts
+    for a specific agent.
+    """
+
+    async def query_produced(
+        self,
+        conn: aiosqlite.Connection,
+        agent_id: str,
+        filters: FilterConfig,
+        build_filters_fn: Any,  # Callable for filter building
+    ) -> dict[str, int]:
+        """
+        Query artifacts produced by agent, grouped by type.
+
+        Args:
+            conn: Active database connection
+            agent_id: Producer to query for
+            filters: Base filter configuration
+            build_filters_fn: Function to build WHERE clause from filters
+
+        Returns:
+            Dict mapping canonical types to production counts
+
+        Examples:
+            >>> queries = AgentHistoryQueries()
+            >>> produced = await queries.query_produced(
+            ...     conn, "agent1", filters, builder
+            ... )
+            >>> produced
+            {"Result": 10, "Message": 5}
+        """
+        # Check if agent is excluded by filters
+        if filters.produced_by and agent_id not in filters.produced_by:
+            return {}
+
+        # Derive filter for this specific agent
+        produced_filter = self._derive_produced_filter(filters, agent_id)
+
+        # Build WHERE clause
+        where_clause, params = build_filters_fn(produced_filter)
+
+        # Execute query
+        produced_query = f"""
+            SELECT canonical_type, COUNT(*) AS count
+            FROM artifacts
+            {where_clause}
+            GROUP BY canonical_type
+        """  # nosec B608 - where_clause contains only parameter placeholders
+
+        cursor = await conn.execute(produced_query, tuple(params))
+        rows = await cursor.fetchall()
+        await cursor.close()
+
+        return {row["canonical_type"]: row["count"] for row in rows}
+
+    async def query_consumed(
+        self,
+        conn: aiosqlite.Connection,
+        agent_id: str,
+        filters: FilterConfig,
+        build_filters_fn: Any,  # Callable for filter building
+    ) -> dict[str, int]:
+        """
+        Query artifacts consumed by agent, grouped by type.
+
+        Args:
+            conn: Active database connection
+            agent_id: Consumer to query for
+            filters: Base filter configuration
+            build_filters_fn: Function to build WHERE clause from filters
+
+        Returns:
+            Dict mapping canonical types to consumption counts
+
+        Examples:
+            >>> queries = AgentHistoryQueries()
+            >>> consumed = await queries.query_consumed(
+            ...     conn, "agent1", filters, builder
+            ... )
+            >>> consumed
+            {"Result": 8, "Message": 3}
+        """
+        # Build WHERE clause with table alias for JOIN
+        where_clause, params = build_filters_fn(filters, table_alias="a")
+        params_with_consumer = (*params, agent_id)
+
+        # Execute query with JOIN
+        consumption_query = f"""
+            SELECT a.canonical_type AS canonical_type, COUNT(*) AS count
+            FROM artifact_consumptions c
+            JOIN artifacts a ON a.artifact_id = c.artifact_id
+            {where_clause}
+            {"AND" if where_clause else "WHERE"} c.consumer = ?
+            GROUP BY a.canonical_type
+        """  # nosec B608 - where_clause contains only parameter placeholders
+
+        cursor = await conn.execute(consumption_query, params_with_consumer)
+        rows = await cursor.fetchall()
+        await cursor.close()
+
+        return {row["canonical_type"]: row["count"] for row in rows}
+
+    def _derive_produced_filter(
+        self, base_filters: FilterConfig, agent_id: str
+    ) -> FilterConfig:
+        """
+        Derive a filter configuration specific to agent's production.
+
+        Creates a new FilterConfig with agent_id as producer while
+        preserving other filter criteria.
+
+        Args:
+            base_filters: Base filter configuration
+            agent_id: Agent to filter production for
+
+        Returns:
+            New FilterConfig with agent_id as producer
+        """
+        from flock.core.store import FilterConfig
+
+        return FilterConfig(
+            type_names=set(base_filters.type_names)
+            if base_filters.type_names
+            else None,
+            produced_by={agent_id},
+            correlation_id=base_filters.correlation_id,
+            tags=set(base_filters.tags) if base_filters.tags else None,
+            visibility=set(base_filters.visibility)
+            if base_filters.visibility
+            else None,
+            start=base_filters.start,
+            end=base_filters.end,
+        )

flock/storage/sqlite/consumption_loader.py

@@ -0,0 +1,100 @@
+"""SQLite consumption record loading utilities.
+
+Handles loading and organizing consumption records for artifacts.
+Extracted from query_artifacts to reduce complexity.
+"""
+
+from __future__ import annotations
+
+from collections import defaultdict
+from datetime import datetime
+from typing import TYPE_CHECKING
+from uuid import UUID
+
+from flock.core.store import ConsumptionRecord
+
+
+if TYPE_CHECKING:
+    import aiosqlite
+
+
+class SQLiteConsumptionLoader:
+    """
+    Loads consumption records from SQLite database.
+
+    Separates consumption loading logic from main query method
+    for better testability and maintainability.
+    """
+
+    async def load_for_artifacts(
+        self,
+        conn: aiosqlite.Connection,
+        artifact_ids: list[str],
+    ) -> dict[UUID, list[ConsumptionRecord]]:
+        """
+        Load consumption records for given artifact IDs.
+
+        Args:
+            conn: Active database connection
+            artifact_ids: List of artifact ID strings
+
+        Returns:
+            Dict mapping artifact UUIDs to their consumption records
+
+        Example:
+            >>> loader = SQLiteConsumptionLoader()
+            >>> consumptions = await loader.load_for_artifacts(conn, ["id1", "id2"])
+            >>> consumptions[UUID("id1")]  # List[ConsumptionRecord]
+        """
+        if not artifact_ids:
+            return {}
+
+        # Build query with proper placeholders
+        placeholders = ", ".join("?" for _ in artifact_ids)
+        consumption_query = f"""
+            SELECT
+                artifact_id,
+                consumer,
+                run_id,
+                correlation_id,
+                consumed_at
+            FROM artifact_consumptions
+            WHERE artifact_id IN ({placeholders})
+            ORDER BY consumed_at ASC
+        """  # nosec B608 - placeholders string contains only '?' characters
+
+        # Execute query
+        cursor = await conn.execute(consumption_query, artifact_ids)
+        consumption_rows = await cursor.fetchall()
+        await cursor.close()
+
+        # Build consumption map
+        return self._build_consumption_map(consumption_rows)
+
+    def _build_consumption_map(
+        self, rows: list[aiosqlite.Row]
+    ) -> dict[UUID, list[ConsumptionRecord]]:
+        """
+        Build consumption map from database rows.
+
+        Args:
+            rows: Database rows with consumption data
+
+        Returns:
+            Dict mapping artifact UUIDs to consumption records
+        """
+        consumptions_map: dict[UUID, list[ConsumptionRecord]] = defaultdict(list)
+
+        for row in rows:
+            artifact_uuid = UUID(row["artifact_id"])
+            consumptions_map[artifact_uuid].append(
+                ConsumptionRecord(
+                    artifact_id=artifact_uuid,
+                    consumer=row["consumer"],
+                    run_id=row["run_id"],
+                    correlation_id=row["correlation_id"],
+                    consumed_at=datetime.fromisoformat(row["consumed_at"]),
+                )
+            )
+
+        return consumptions_map

flock/storage/sqlite/query_builder.py

@@ -0,0 +1,112 @@
+"""SQLite query building utilities for artifact filtering.
+
+This module constructs safe, parameterized SQL queries from filter configurations.
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any
+
+
+if TYPE_CHECKING:
+    from flock.core.store import FilterConfig
+
+
+class SQLiteQueryBuilder:
+    """
+    Builds safe SQL queries with proper parameter binding.
+
+    Responsibilities:
+    - Build SELECT queries from filter configurations
+    - Construct WHERE clauses with parameter placeholders
+    - Prevent SQL injection via proper parameter binding
+    - Support complex filtering (types, producers, tags, visibility, dates)
+
+    All queries use parameter placeholders (?) and return both the SQL string
+    and parameter list to ensure safe execution.
+    """
+
+    def build_filters(
+        self,
+        filters: FilterConfig,
+        *,
+        table_alias: str | None = None,
+    ) -> tuple[str, list[Any]]:
+        """
+        Build WHERE clause and parameters from filter configuration.
+
+        Args:
+            filters: Filter configuration specifying query constraints
+            table_alias: Optional table alias prefix (e.g., "a" for "a.type")
+
+        Returns:
+            Tuple of (where_clause, parameters):
+            - where_clause: SQL WHERE clause string (e.g., " WHERE type = ?")
+            - parameters: List of values for parameter binding
+
+        Example:
+            >>> filters = FilterConfig(type_names={"BugReport"}, limit=10)
+            >>> where, params = builder.build_filters(filters)
+            >>> # where = " WHERE canonical_type IN (?)"
+            >>> # params = ["flock.BugReport"]
+
+        Security:
+            All values are bound via parameters, preventing SQL injection.
+            The WHERE clause contains only placeholders (?), never raw values.
+        """
+        # Import here to avoid circular dependency
+        from flock.registry import type_registry
+
+        prefix = f"{table_alias}." if table_alias else ""
+        conditions: list[str] = []
+        params: list[Any] = []
+
+        # Type filter
+        if filters.type_names:
+            canonical = {
+                type_registry.resolve_name(name) for name in filters.type_names
+            }
+            placeholders = ", ".join("?" for _ in canonical)
+            conditions.append(f"{prefix}canonical_type IN ({placeholders})")
+            params.extend(sorted(canonical))
+
+        # Producer filter
+        if filters.produced_by:
+            placeholders = ", ".join("?" for _ in filters.produced_by)
+            conditions.append(f"{prefix}produced_by IN ({placeholders})")
+            params.extend(sorted(filters.produced_by))
+
+        # Correlation ID filter
+        if filters.correlation_id:
+            conditions.append(f"{prefix}correlation_id = ?")
+            params.append(filters.correlation_id)
+
+        # Visibility filter
+        if filters.visibility:
+            placeholders = ", ".join("?" for _ in filters.visibility)
+            conditions.append(
+                f"json_extract({prefix}visibility, '$.kind') IN ({placeholders})"
+            )
+            params.extend(sorted(filters.visibility))
+
+        # Date range filters
+        if filters.start is not None:
+            conditions.append(f"{prefix}created_at >= ?")
+            params.append(filters.start.isoformat())
+
+        if filters.end is not None:
+            conditions.append(f"{prefix}created_at <= ?")
+            params.append(filters.end.isoformat())
+
+        # Tag filter (JSON array contains check)
+        if filters.tags:
+            column = f"{prefix}tags" if table_alias else "artifacts.tags"
+            for tag in sorted(filters.tags):
+                conditions.append(
+                    f"EXISTS (SELECT 1 FROM json_each({column}) WHERE json_each.value = ?)"  # nosec B608 - column is internal constant
+                )
+                params.append(tag)
+
+        # Build final WHERE clause
+        where_clause = f" WHERE {' AND '.join(conditions)}" if conditions else ""
+        return where_clause, params

flock/storage/sqlite/query_params_builder.py

@@ -0,0 +1,91 @@
+"""Query parameter building utilities for SQLite storage.
+
+Handles pagination parameter construction for SQLite queries.
+Extracted from store.py to reduce complexity from B (10) to A (4).
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+
+class QueryParamsBuilder:
+    """
+    Build query parameters for SQLite pagination.
+
+    Simplifies limit/offset parameter handling by providing focused
+    methods for different pagination scenarios.
+    """
+
+    def build_pagination_params(
+        self,
+        base_params: list[Any],
+        limit: int,
+        offset: int,
+    ) -> tuple[str, tuple[Any, ...]]:
+        """
+        Build LIMIT/OFFSET clause and parameters for pagination.
+
+        Handles three scenarios:
+        1. No limit, no offset: Return all results
+        2. No limit, with offset: Skip first N results
+        3. With limit: Standard pagination
+
+        Args:
+            base_params: Base query parameters (from WHERE clause)
+            limit: Maximum number of results (0 = unlimited)
+            offset: Number of results to skip
+
+        Returns:
+            Tuple of (SQL clause suffix, complete parameters tuple)
+
+        Examples:
+            >>> builder = QueryParamsBuilder()
+            >>> clause, params = builder.build_pagination_params([], 10, 0)
+            >>> clause
+            ' LIMIT ? OFFSET ?'
+            >>> params
+            (10, 0)
+        """
+        normalized_offset = max(offset, 0)
+
+        if limit <= 0:
+            return self._build_unlimited_params(base_params, normalized_offset)
+
+        return self._build_limited_params(base_params, limit, normalized_offset)
+
+    def _build_unlimited_params(
+        self, base_params: list[Any], offset: int
+    ) -> tuple[str, tuple[Any, ...]]:
+        """
+        Build parameters for unlimited results with optional offset.
+
+        Args:
+            base_params: Base query parameters
+            offset: Number of results to skip (0 = no offset)
+
+        Returns:
+            Tuple of (SQL clause, parameters)
+        """
+        if offset > 0:
+            # Need to skip first N results but return rest
+            return " LIMIT -1 OFFSET ?", (*base_params, offset)
+
+        # Return all results, no pagination
+        return "", tuple(base_params)
+
+    def _build_limited_params(
+        self, base_params: list[Any], limit: int, offset: int
+    ) -> tuple[str, tuple[Any, ...]]:
+        """
+        Build parameters for standard pagination with limit and offset.
+
+        Args:
+            base_params: Base query parameters
+            limit: Maximum number of results
+            offset: Number of results to skip
+
+        Returns:
+            Tuple of (SQL clause, parameters)
+        """
+        return " LIMIT ? OFFSET ?", (*base_params, limit, offset)