htmlgraph 0.20.1__py3-none-any.whl → 0.27.5__py3-none-any.whl

htmlgraph/db/queries.py

@@ -0,0 +1,790 @@
+"""
+HtmlGraph Query Builders - SQLite Query Construction
+
+Provides high-level query builders for common operations on HtmlGraph data:
+- Event queries (agent activity, tool usage, error tracking)
+- Feature queries (work item status, priority filtering)
+- Session queries (agent metrics, collaboration tracking)
+- Track queries (initiative progress, feature dependencies)
+- Collaboration queries (handoffs, parallel work)
+
+All builders return SQL and parameters for safe parameterized queries.
+"""
+
+from datetime import datetime
+from enum import Enum
+
+
+class EventType(Enum):
+    """Types of events that can be recorded."""
+
+    TOOL_CALL = "tool_call"
+    TOOL_RESULT = "tool_result"
+    ERROR = "error"
+    DELEGATION = "delegation"
+    COMPLETION = "completion"
+    START = "start"
+    END = "end"
+    CHECK_POINT = "check_point"
+
+
+class FeatureType(Enum):
+    """Types of work items."""
+
+    FEATURE = "feature"
+    BUG = "bug"
+    SPIKE = "spike"
+    CHORE = "chore"
+    EPIC = "epic"
+    TASK = "task"
+
+
+class FeatureStatus(Enum):
+    """Possible feature statuses."""
+
+    TODO = "todo"
+    IN_PROGRESS = "in_progress"
+    BLOCKED = "blocked"
+    DONE = "done"
+    CANCELLED = "cancelled"
+
+
+class Priority(Enum):
+    """Priority levels."""
+
+    LOW = "low"
+    MEDIUM = "medium"
+    HIGH = "high"
+    CRITICAL = "critical"
+
+
+class Queries:
+    """Query builders for HtmlGraph SQLite backend."""
+
+    # ========== AGENT EVENTS QUERIES ==========
+
+    @staticmethod
+    def get_events_by_session(session_id: str) -> tuple[str, tuple]:
+        """
+        Get all events for a session ordered by timestamp.
+
+        Args:
+            session_id: Session ID to query
+
+        Returns:
+            Tuple of (SQL query, parameters)
+        """
+        sql = """
+            SELECT * FROM agent_events
+            WHERE session_id = ?
+            ORDER BY timestamp ASC
+        """
+        return sql, (session_id,)
+
+    @staticmethod
+    def get_events_by_agent(
+        agent_id: str,
+        start_time: datetime | None = None,
+        end_time: datetime | None = None,
+    ) -> tuple[str, tuple]:
+        """
+        Get all events generated by a specific agent.
+
+        Args:
+            agent_id: Agent identifier
+            start_time: Optional start time filter
+            end_time: Optional end time filter
+
+        Returns:
+            Tuple of (SQL query, parameters)
+        """
+        sql = """
+            SELECT * FROM agent_events
+            WHERE agent_id = ?
+        """
+        params = [agent_id]
+
+        if start_time:
+            sql += " AND timestamp >= ?"
+            params.append(start_time.isoformat())
+
+        if end_time:
+            sql += " AND timestamp <= ?"
+            params.append(end_time.isoformat())
+
+        sql += " ORDER BY timestamp DESC"
+        return sql, tuple(params)
+
+    @staticmethod
+    def get_events_by_type(
+        event_type: str,
+        session_id: str | None = None,
+    ) -> tuple[str, tuple]:
+        """
+        Get events filtered by type (tool_call, error, delegation, etc.).
+
+        Args:
+            event_type: Type of event to filter
+            session_id: Optional session filter
+
+        Returns:
+            Tuple of (SQL query, parameters)
+        """
+        sql = "SELECT * FROM agent_events WHERE event_type = ?"
+        params = [event_type]
+
+        if session_id:
+            sql += " AND session_id = ?"
+            params.append(session_id)
+
+        sql += " ORDER BY timestamp DESC"
+        return sql, tuple(params)
+
+    @staticmethod
+    def get_tool_usage_summary(
+        session_id: str,
+    ) -> tuple[str, tuple]:
+        """
+        Get summary of tool usage in a session.
+
+        Returns tool calls grouped by tool name with counts.
+
+        Args:
+            session_id: Session to analyze
+
+        Returns:
+            Tuple of (SQL query, parameters)
+        """
+        sql = """
+            SELECT
+                tool_name,
+                COUNT(*) as call_count,
+                SUM(cost_tokens) as total_tokens,
+                COUNT(CASE WHEN event_type = 'error' THEN 1 END) as error_count,
+                MIN(timestamp) as first_call,
+                MAX(timestamp) as last_call
+            FROM agent_events
+            WHERE session_id = ? AND tool_name IS NOT NULL
+            GROUP BY tool_name
+            ORDER BY call_count DESC
+        """
+        return sql, (session_id,)
+
+    @staticmethod
+    def get_events_with_errors(
+        session_id: str,
+    ) -> tuple[str, tuple]:
+        """
+        Get all error events in a session with context.
+
+        Args:
+            session_id: Session to analyze
+
+        Returns:
+            Tuple of (SQL query, parameters)
+        """
+        sql = """
+            SELECT
+                event_id,
+                agent_id,
+                timestamp,
+                tool_name,
+                output_summary as error_message,
+                context
+            FROM agent_events
+            WHERE session_id = ? AND event_type = 'error'
+            ORDER BY timestamp ASC
+        """
+        return sql, (session_id,)
+
+    @staticmethod
+    def get_delegation_chain(
+        session_id: str,
+    ) -> tuple[str, tuple]:
+        """
+        Get the chain of delegations in a session.
+
+        Shows parent-child relationships between delegated events.
+
+        Args:
+            session_id: Session to analyze
+
+        Returns:
+            Tuple of (SQL query, parameters)
+        """
+        sql = """
+            SELECT
+                event_id,
+                parent_event_id,
+                agent_id,
+                parent_agent_id,
+                event_type,
+                timestamp,
+                tool_name
+            FROM agent_events
+            WHERE session_id = ? AND (parent_agent_id IS NOT NULL OR event_type = 'delegation')
+            ORDER BY timestamp ASC
+        """
+        return sql, (session_id,)
+
+    # ========== FEATURES QUERIES ==========
+
+    @staticmethod
+    def get_features_by_status(
+        status: str,
+        limit: int | None = None,
+    ) -> tuple[str, tuple]:
+        """
+        Get features filtered by status.
+
+        Args:
+            status: Status to filter by (todo, in_progress, done, etc.)
+            limit: Optional limit on results
+
+        Returns:
+            Tuple of (SQL query, parameters)
+        """
+        sql = """
+            SELECT * FROM features
+            WHERE status = ?
+            ORDER BY priority DESC, created_at DESC
+        """
+        params: list[str | int] = [status]
+
+        if limit:
+            sql += " LIMIT ?"
+            params.append(limit)
+
+        return sql, tuple(params)
+
+    @staticmethod
+    def get_features_by_track(
+        track_id: str,
+    ) -> tuple[str, tuple]:
+        """
+        Get all features linked to a track.
+
+        Args:
+            track_id: Track ID
+
+        Returns:
+            Tuple of (SQL query, parameters)
+        """
+        sql = """
+            SELECT * FROM features
+            WHERE track_id = ?
+            ORDER BY priority DESC, created_at ASC
+        """
+        return sql, (track_id,)
+
+    @staticmethod
+    def get_features_assigned_to(
+        agent_id: str,
+    ) -> tuple[str, tuple]:
+        """
+        Get all features assigned to an agent.
+
+        Args:
+            agent_id: Agent identifier
+
+        Returns:
+            Tuple of (SQL query, parameters)
+        """
+        sql = """
+            SELECT * FROM features
+            WHERE assigned_to = ?
+            ORDER BY priority DESC, created_at DESC
+        """
+        return sql, (agent_id,)
+
+    @staticmethod
+    def get_feature_progress(
+        feature_id: str,
+    ) -> tuple[str, tuple]:
+        """
+        Get progress info for a feature (steps completed, estimated vs actual time).
+
+        Args:
+            feature_id: Feature ID
+
+        Returns:
+            Tuple of (SQL query, parameters)
+        """
+        sql = """
+            SELECT
+                id,
+                title,
+                type,
+                status,
+                steps_total,
+                steps_completed,
+                CASE WHEN steps_total > 0 THEN (steps_completed * 100.0 / steps_total) ELSE 0 END as progress_percent,
+                created_at,
+                completed_at,
+                CASE WHEN completed_at IS NOT NULL
+                    THEN CAST((julianday(completed_at) - julianday(created_at)) * 24 AS INT)
+                    ELSE NULL
+                END as hours_elapsed
+            FROM features
+            WHERE id = ?
+        """
+        return sql, (feature_id,)
+
+    @staticmethod
+    def get_high_priority_features(
+        limit: int = 10,
+    ) -> tuple[str, tuple]:
+        """
+        Get all high/critical priority features not yet done.
+
+        Args:
+            limit: Maximum results to return
+
+        Returns:
+            Tuple of (SQL query, parameters)
+        """
+        sql = """
+            SELECT * FROM features
+            WHERE priority IN ('high', 'critical')
+            AND status != 'done'
+            ORDER BY priority DESC, created_at ASC
+            LIMIT ?
+        """
+        return sql, (limit,)
+
+    @staticmethod
+    def get_blocked_features() -> tuple[str, tuple]:
+        """
+        Get all currently blocked features.
+
+        Returns:
+            Tuple of (SQL query, parameters)
+        """
+        sql = """
+            SELECT id, title, type, assigned_to, created_at
+            FROM features
+            WHERE status = 'blocked'
+            ORDER BY created_at ASC
+        """
+        return sql, ()
+
+    @staticmethod
+    def get_feature_dependency_tree(
+        feature_id: str,
+    ) -> tuple[str, tuple]:
+        """
+        Get feature dependency tree (parent-child relationships).
+
+        Args:
+            feature_id: Root feature ID
+
+        Returns:
+            Tuple of (SQL query, parameters)
+        """
+        sql = """
+            WITH RECURSIVE feature_tree AS (
+                -- Base case: start with the requested feature
+                SELECT id, title, parent_feature_id, type, status, 0 as depth
+                FROM features
+                WHERE id = ?
+
+                UNION ALL
+
+                -- Recursive case: get all child features
+                SELECT f.id, f.title, f.parent_feature_id, f.type, f.status, ft.depth + 1
+                FROM features f
+                INNER JOIN feature_tree ft ON f.parent_feature_id = ft.id
+                WHERE ft.depth < 10  -- Prevent infinite loops
+            )
+            SELECT * FROM feature_tree
+            ORDER BY depth ASC, id
+        """
+        return sql, (feature_id,)
+
+    # ========== SESSIONS QUERIES ==========
+
+    @staticmethod
+    def get_session_metrics(
+        session_id: str,
+    ) -> tuple[str, tuple]:
+        """
+        Get comprehensive metrics for a session.
+
+        Includes event count, token usage, features worked on, etc.
+
+        Args:
+            session_id: Session ID
+
+        Returns:
+            Tuple of (SQL query, parameters)
+        """
+        sql = """
+            SELECT
+                s.session_id,
+                s.agent_assigned,
+                s.created_at,
+                s.completed_at,
+                CASE WHEN s.completed_at IS NOT NULL
+                    THEN CAST((julianday(s.completed_at) - julianday(s.created_at)) * 24 * 60 AS INT)
+                    ELSE CAST((julianday(CURRENT_TIMESTAMP) - julianday(s.created_at)) * 24 * 60 AS INT)
+                END as duration_minutes,
+                COUNT(DISTINCT e.event_id) as total_events,
+                COUNT(DISTINCT CASE WHEN e.event_type = 'error' THEN e.event_id END) as error_count,
+                COUNT(DISTINCT CASE WHEN e.event_type = 'delegation' THEN e.event_id END) as delegation_count,
+                SUM(e.cost_tokens) as total_tokens,
+                s.status,
+                s.is_subagent
+            FROM sessions s
+            LEFT JOIN agent_events e ON s.session_id = e.session_id
+            WHERE s.session_id = ?
+            GROUP BY s.session_id
+        """
+        return sql, (session_id,)
+
+    @staticmethod
+    def get_agent_sessions(
+        agent_id: str,
+        limit: int = 10,
+    ) -> tuple[str, tuple]:
+        """
+        Get all sessions for an agent (most recent first).
+
+        Args:
+            agent_id: Agent identifier
+            limit: Maximum sessions to return
+
+        Returns:
+            Tuple of (SQL query, parameters)
+        """
+        sql = """
+            SELECT
+                session_id,
+                agent_assigned,
+                created_at,
+                completed_at,
+                total_events,
+                total_tokens_used,
+                status,
+                is_subagent
+            FROM sessions
+            WHERE agent_assigned = ?
+            ORDER BY created_at DESC
+            LIMIT ?
+        """
+        return sql, (agent_id, limit)
+
+    @staticmethod
+    def get_active_sessions() -> tuple[str, tuple]:
+        """
+        Get all currently active sessions.
+
+        Returns:
+            Tuple of (SQL query, parameters)
+        """
+        sql = """
+            SELECT
+                session_id,
+                agent_assigned,
+                created_at,
+                total_events,
+                total_tokens_used,
+                status
+            FROM sessions
+            WHERE status = 'active'
+            ORDER BY created_at DESC
+        """
+        return sql, ()
+
+    @staticmethod
+    def get_subagent_sessions(
+        parent_session_id: str,
+    ) -> tuple[str, tuple]:
+        """
+        Get all subagent sessions spawned from a parent session.
+
+        Args:
+            parent_session_id: Parent session ID
+
+        Returns:
+            Tuple of (SQL query, parameters)
+        """
+        sql = """
+            SELECT
+                session_id,
+                agent_assigned,
+                created_at,
+                completed_at,
+                total_events,
+                total_tokens_used,
+                status
+            FROM sessions
+            WHERE parent_session_id = ?
+            ORDER BY created_at ASC
+        """
+        return sql, (parent_session_id,)
+
+    @staticmethod
+    def get_context_drift(
+        session_id: str,
+    ) -> tuple[str, tuple]:
+        """
+        Get context drift metric for a session.
+
+        Higher drift indicates context loss across session.
+
+        Args:
+            session_id: Session ID
+
+        Returns:
+            Tuple of (SQL query, parameters)
+        """
+        sql = """
+            SELECT
+                session_id,
+                context_drift,
+                total_events,
+                CASE WHEN total_events > 0 THEN (context_drift / total_events) ELSE 0 END as drift_per_event
+            FROM sessions
+            WHERE session_id = ?
+        """
+        return sql, (session_id,)
+
+    # ========== TRACKS QUERIES ==========
+
+    @staticmethod
+    def get_track_status(
+        track_id: str,
+    ) -> tuple[str, tuple]:
+        """
+        Get comprehensive status of a track and its features.
+
+        Args:
+            track_id: Track ID
+
+        Returns:
+            Tuple of (SQL query, parameters)
+        """
+        sql = """
+            SELECT
+                t.track_id,
+                t.title,
+                t.status,
+                t.priority,
+                t.created_at,
+                t.completed_at,
+                COUNT(DISTINCT f.id) as total_features,
+                COUNT(DISTINCT CASE WHEN f.status = 'done' THEN f.id END) as completed_features,
+                COUNT(DISTINCT CASE WHEN f.status = 'in_progress' THEN f.id END) as in_progress_features,
+                COUNT(DISTINCT CASE WHEN f.status = 'blocked' THEN f.id END) as blocked_features,
+                CASE WHEN COUNT(f.id) > 0
+                    THEN CAST(COUNT(CASE WHEN f.status = 'done' THEN f.id END) * 100.0 / COUNT(f.id) AS INT)
+                    ELSE 0
+                END as completion_percent
+            FROM tracks t
+            LEFT JOIN features f ON t.track_id = f.track_id
+            WHERE t.track_id = ?
+            GROUP BY t.track_id
+        """
+        return sql, (track_id,)
+
+    @staticmethod
+    def get_active_tracks(
+        limit: int = 10,
+    ) -> tuple[str, tuple]:
+        """
+        Get all active (in-progress) tracks.
+
+        Args:
+            limit: Maximum tracks to return
+
+        Returns:
+            Tuple of (SQL query, parameters)
+        """
+        sql = """
+            SELECT
+                t.track_id,
+                t.title,
+                t.priority,
+                COUNT(f.id) as feature_count,
+                COUNT(CASE WHEN f.status = 'done' THEN f.id END) as completed_count
+            FROM tracks t
+            LEFT JOIN features f ON t.track_id = f.track_id
+            WHERE t.status = 'in_progress'
+            GROUP BY t.track_id
+            ORDER BY t.priority DESC, t.created_at DESC
+            LIMIT ?
+        """
+        return sql, (limit,)
+
+    # ========== COLLABORATION QUERIES ==========
+
+    @staticmethod
+    def get_handoffs(
+        session_id: str,
+    ) -> tuple[str, tuple]:
+        """
+        Get all handoffs (delegations) in a session.
+
+        Args:
+            session_id: Session ID
+
+        Returns:
+            Tuple of (SQL query, parameters)
+        """
+        sql = """
+            SELECT
+                handoff_id,
+                from_agent,
+                to_agent,
+                timestamp,
+                feature_id,
+                handoff_type,
+                status,
+                reason
+            FROM agent_collaboration
+            WHERE session_id = ?
+            ORDER BY timestamp ASC
+        """
+        return sql, (session_id,)
+
+    @staticmethod
+    def get_agent_collaboration_summary() -> tuple[str, tuple]:
+        """
+        Get summary of agent collaboration patterns.
+
+        Shows which agents delegate to whom most frequently.
+
+        Returns:
+            Tuple of (SQL query, parameters)
+        """
+        sql = """
+            SELECT
+                from_agent,
+                to_agent,
+                COUNT(*) as handoff_count,
+                COUNT(CASE WHEN status = 'completed' THEN 1 END) as successful_handoffs,
+                COUNT(CASE WHEN status = 'failed' THEN 1 END) as failed_handoffs,
+                COUNT(DISTINCT feature_id) as unique_features
+            FROM agent_collaboration
+            GROUP BY from_agent, to_agent
+            ORDER BY handoff_count DESC
+        """
+        return sql, ()
+
+    @staticmethod
+    def get_parallel_work(
+        session_id: str,
+    ) -> tuple[str, tuple]:
+        """
+        Get instances of parallel work in a session.
+
+        Returns:
+            Tuple of (SQL query, parameters)
+        """
+        sql = """
+            SELECT
+                handoff_id,
+                from_agent,
+                to_agent,
+                feature_id,
+                timestamp,
+                status
+            FROM agent_collaboration
+            WHERE session_id = ? AND handoff_type = 'parallel'
+            ORDER BY timestamp ASC
+        """
+        return sql, (session_id,)
+
+    # ========== ANALYTICAL QUERIES ==========
+
+    @staticmethod
+    def get_system_statistics() -> tuple[str, tuple]:
+        """
+        Get system-wide statistics across all data.
+
+        Returns:
+            Tuple of (SQL query, parameters)
+        """
+        sql = """
+            SELECT
+                (SELECT COUNT(*) FROM agent_events) as total_events,
+                (SELECT COUNT(*) FROM features) as total_features,
+                (SELECT COUNT(*) FROM sessions) as total_sessions,
+                (SELECT COUNT(*) FROM tracks) as total_tracks,
+                (SELECT COUNT(DISTINCT agent_id) FROM agent_events) as unique_agents,
+                (SELECT SUM(cost_tokens) FROM agent_events) as total_tokens,
+                (SELECT COUNT(*) FROM features WHERE status = 'done') as completed_features,
+                (SELECT COUNT(*) FROM features WHERE status = 'blocked') as blocked_features,
+                (SELECT COUNT(*) FROM agent_collaboration) as total_handoffs
+        """
+        return sql, ()
+
+    @staticmethod
+    def get_agent_performance_metrics() -> tuple[str, tuple]:
+        """
+        Get performance metrics per agent.
+
+        Includes event counts, token usage, error rates, etc.
+
+        Returns:
+            Tuple of (SQL query, parameters)
+        """
+        sql = """
+            SELECT
+                e.agent_id,
+                COUNT(*) as total_events,
+                COUNT(DISTINCT e.session_id) as total_sessions,
+                COUNT(DISTINCT CASE WHEN e.event_type = 'error' THEN e.event_id END) as error_count,
+                CAST(
+                    COUNT(DISTINCT CASE WHEN e.event_type = 'error' THEN e.event_id END) * 100.0
+                    / COUNT(*) AS DECIMAL(5, 2)
+                ) as error_rate,
+                SUM(e.cost_tokens) as total_tokens,
+                ROUND(AVG(e.cost_tokens), 2) as avg_tokens_per_event,
+                COUNT(DISTINCT CASE WHEN e.tool_name IS NOT NULL THEN e.tool_name END) as unique_tools_used
+            FROM agent_events e
+            GROUP BY e.agent_id
+            ORDER BY total_events DESC
+        """
+        return sql, ()
+
+    @staticmethod
+    def get_events_timeline(
+        start_date: datetime,
+        end_date: datetime,
+        bucket_minutes: int = 60,
+    ) -> tuple[str, tuple]:
+        """
+        Get timeline of events grouped by time bucket.
+
+        Useful for visualizing activity over time.
+
+        Args:
+            start_date: Start of time range
+            end_date: End of time range
+            bucket_minutes: Group events into buckets of this size
+
+        Returns:
+            Tuple of (SQL query, parameters)
+        """
+        sql = f"""
+            SELECT
+                strftime('%Y-%m-%d %H:%M', datetime(
+                    (julianday(timestamp) - julianday(?)) * 24 * 60 / {bucket_minutes}
+                    * {bucket_minutes} / 24 / 60 + julianday(?)
+                )) as time_bucket,
+                COUNT(*) as event_count,
+                COUNT(DISTINCT agent_id) as unique_agents,
+                COUNT(DISTINCT session_id) as unique_sessions,
+                SUM(cost_tokens) as total_tokens
+            FROM agent_events
+            WHERE timestamp BETWEEN ? AND ?
+            GROUP BY time_bucket
+            ORDER BY time_bucket ASC
+        """
+        return sql, (
+            start_date.isoformat(),
+            start_date.isoformat(),
+            start_date.isoformat(),
+            end_date.isoformat(),
+        )