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

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)

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()