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

htmlgraph/analytics/work_type.py

@@ -1,3 +1,9 @@
+from __future__ import annotations
+
+import logging
+
+logger = logging.getLogger(__name__)
+
 """
 Analytics API for HtmlGraph work type analysis.
 
@@ -25,19 +31,35 @@ Example:
     # Returns: 25.5 (% of work spent on maintenance)
 """
 
-from __future__ import annotations
-
-from datetime import datetime
+from datetime import datetime, timezone
 from typing import TYPE_CHECKING
 
 if TYPE_CHECKING:
     from htmlgraph import SDK
 
 from htmlgraph.converter import html_to_session
-from htmlgraph.models import Session, WorkType
+from htmlgraph.models import Session, WorkType, utc_now
 from htmlgraph.session_manager import SessionManager
 
 
+def normalize_datetime(dt: datetime | None) -> datetime | None:
+    """
+    Normalize datetime to UTC-aware format for safe comparisons.
+
+    Handles three cases:
+    - None: returns None
+    - Naive (no timezone): assumes UTC and adds timezone
+    - Aware (has timezone): converts to UTC
+    """
+    if dt is None:
+        return None
+    if dt.tzinfo is None:
+        # Naive datetime - assume UTC
+        return dt.replace(tzinfo=timezone.utc)
+    # Already aware - convert to UTC
+    return dt.astimezone(timezone.utc)
+
+
 class Analytics:
     """
     Analytics interface for work type analysis.
@@ -79,7 +101,7 @@ class Analytics:
         Example:
             >>> analytics = sdk.analytics
             >>> dist = analytics.work_type_distribution(session_id="session-123")
-            >>> print(dist)
+            >>> logger.info("%s", dist)
             {
                 "feature-implementation": 45.2,
                 "spike-investigation": 28.3,
@@ -145,11 +167,11 @@ class Analytics:
 
         Example:
             >>> ratio = sdk.analytics.spike_to_feature_ratio(session_id="session-123")
-            >>> print(f"Spike-to-feature ratio: {ratio:.2f}")
+            >>> logger.info(f"Spike-to-feature ratio: {ratio:.2f}")
             Spike-to-feature ratio: 0.63
 
             >>> if ratio > 0.5:
-            ...     print("This was a research-heavy session")
+            ...     logger.info("This was a research-heavy session")
         """
         events = self._get_events(session_id, start_date, end_date)
 
@@ -203,11 +225,11 @@ class Analytics:
 
         Example:
             >>> burden = sdk.analytics.maintenance_burden(session_id="session-123")
-            >>> print(f"Maintenance burden: {burden:.1f}%")
+            >>> logger.info(f"Maintenance burden: {burden:.1f}%")
             Maintenance burden: 32.5%
 
             >>> if burden > 40:
-            ...     print("⚠️  High maintenance burden - consider addressing technical debt")
+            ...     logger.info("⚠️  High maintenance burden - consider addressing technical debt")
         """
         events = self._get_events(session_id, start_date, end_date)
 
@@ -258,7 +280,7 @@ class Analytics:
             >>> spike_sessions = sdk.analytics.get_sessions_by_work_type(
             ...     "spike-investigation"
             ... )
-            >>> print(f"Found {len(spike_sessions)} exploratory sessions")
+            >>> logger.info(f"Found {len(spike_sessions)} exploratory sessions")
         """
         session_nodes = self.sdk.sessions.all()
         matching_sessions = []
@@ -270,9 +292,11 @@ class Analytics:
                 continue
 
             # Check date range
-            if start_date and session.started_at < start_date:
+            start_normalized = normalize_datetime(start_date)
+            end_normalized = normalize_datetime(end_date)
+            if start_normalized and session.started_at < start_normalized:
                 continue
-            if end_date and session.started_at > end_date:
+            if end_normalized and session.started_at > end_normalized:
                 continue
 
             # Check primary work type
@@ -296,7 +320,7 @@ class Analytics:
 
         Example:
             >>> breakdown = sdk.analytics.calculate_session_work_breakdown("session-123")
-            >>> print(breakdown)
+            >>> logger.info("%s", breakdown)
             {
                 "feature-implementation": 45,
                 "spike-investigation": 28,
@@ -324,7 +348,7 @@ class Analytics:
 
         Example:
             >>> primary = sdk.analytics.calculate_session_primary_work_type("session-123")
-            >>> print(f"Primary work type: {primary}")
+            >>> logger.info(f"Primary work type: {primary}")
             Primary work type: spike-investigation
         """
         session = self._get_session(session_id)
@@ -379,7 +403,7 @@ class Analytics:
 
         Example:
             >>> metrics = sdk.analytics.transition_time_metrics(session_id="session-123")
-            >>> print(f"Transition time: {metrics['transition_percent']:.1f}%")
+            >>> logger.info(f"Transition time: {metrics['transition_percent']:.1f}%")
             Transition time: 15.3%
         """
         from pathlib import Path
@@ -413,18 +437,26 @@ class Analytics:
         # Calculate time for each spike
         for spike in all_spikes:
             # Apply date filters
-            if start_date and spike.created < start_date:
+            start_normalized = normalize_datetime(start_date)
+            end_normalized = normalize_datetime(end_date)
+            if start_normalized and spike.created < start_normalized:
                 continue
-            if end_date and spike.created > end_date:
+            if end_normalized and spike.created > end_normalized:
                 continue
 
-            # Calculate duration
-            start_time = spike.created
+            # Calculate duration (normalize datetimes for safe comparison)
+            start_time = normalize_datetime(spike.created)
+            if not start_time:
+                continue  # Skip if spike creation date is missing
             if spike.status == "done" and spike.updated:
-                end_time = spike.updated
+                end_time = normalize_datetime(spike.updated)
             else:
                 # If still in progress, use last updated time
-                end_time = spike.updated if spike.updated else datetime.now()
+                end_time = normalize_datetime(
+                    spike.updated if spike.updated else utc_now()
+                )
+            if not end_time:
+                end_time = start_time  # Fallback to start time if end time missing
 
             duration = (
                 end_time - start_time
@@ -460,17 +492,25 @@ class Analytics:
 
             for node in nodes:
                 # Apply date filters
-                if start_date and node.created < start_date:
+                start_normalized = normalize_datetime(start_date)
+                end_normalized = normalize_datetime(end_date)
+                if start_normalized and node.created < start_normalized:
                     continue
-                if end_date and node.created > end_date:
+                if end_normalized and node.created > end_normalized:
                     continue
 
-                # Calculate duration
-                start_time = node.created
+                # Calculate duration (normalize datetimes for safe comparison)
+                start_time = normalize_datetime(node.created)
+                if not start_time:
+                    continue  # Skip if node creation date is missing
                 if node.status == "done" and node.updated:
-                    end_time = node.updated
+                    end_time = normalize_datetime(node.updated)
                 else:
-                    end_time = node.updated if node.updated else datetime.now()
+                    end_time = normalize_datetime(
+                        node.updated if node.updated else utc_now()
+                    )
+                if not end_time:
+                    end_time = start_time  # Fallback to start time if end time missing
 
                 duration = (end_time - start_time).total_seconds() / 60
                 feature_minutes += duration

htmlgraph/analytics_index.py

@@ -1,3 +1,5 @@
+from __future__ import annotations
+
 """
 SQLite analytics index for HtmlGraph event logs.
 
@@ -5,7 +7,6 @@ This is a rebuildable cache/index for fast dashboard queries.
 The canonical source of truth is the JSONL event log under `.htmlgraph/events/`.
 """
 
-from __future__ import annotations
 
 import json
 import sqlite3
@@ -14,7 +15,7 @@ from dataclasses import dataclass
 from pathlib import Path
 from typing import Any
 
-SCHEMA_VERSION = 2
+SCHEMA_VERSION = 4  # Bumped: renamed 'agent' column to 'agent_assigned'
 
 
 @dataclass(frozen=True)
@@ -82,12 +83,14 @@ class AnalyticsIndex:
                 """
                 CREATE TABLE IF NOT EXISTS sessions (
                     session_id TEXT PRIMARY KEY,
-                    agent TEXT,
+                    agent_assigned TEXT,
                     start_commit TEXT,
                     continued_from TEXT,
                     status TEXT,
                     started_at TEXT,
-                    ended_at TEXT
+                    ended_at TEXT,
+                    parent_session_id TEXT,
+                    parent_event_id TEXT
                 )
                 """
             )
@@ -103,6 +106,9 @@ class AnalyticsIndex:
                     feature_id TEXT,
                     drift_score REAL,
                     payload_json TEXT,
+                    parent_event_id TEXT,
+                    cost_tokens INTEGER,
+                    execution_duration_seconds REAL,
                     FOREIGN KEY(session_id) REFERENCES sessions(session_id)
                 )
                 """
@@ -157,6 +163,9 @@ class AnalyticsIndex:
             )
 
             # Indexes for typical dashboard queries
+            conn.execute(
+                "CREATE INDEX IF NOT EXISTS idx_sessions_parent ON sessions(parent_session_id)"
+            )
             conn.execute("CREATE INDEX IF NOT EXISTS idx_events_ts ON events(ts)")
             conn.execute(
                 "CREATE INDEX IF NOT EXISTS idx_events_session_ts ON events(session_id, ts)"
@@ -190,15 +199,17 @@ class AnalyticsIndex:
         with self.connect() as conn:
             conn.execute(
                 """
-                INSERT INTO sessions(session_id, agent, start_commit, continued_from, status, started_at, ended_at)
-                VALUES(?,?,?,?,?,?,?)
+                INSERT INTO sessions(session_id, agent_assigned, start_commit, continued_from, status, started_at, ended_at, parent_session_id, parent_event_id)
+                VALUES(?,?,?,?,?,?,?,?,?)
                 ON CONFLICT(session_id) DO UPDATE SET
-                    agent=excluded.agent,
+                    agent_assigned=excluded.agent_assigned,
                     start_commit=excluded.start_commit,
                     continued_from=excluded.continued_from,
                     status=excluded.status,
                     started_at=excluded.started_at,
-                    ended_at=excluded.ended_at
+                    ended_at=excluded.ended_at,
+                    parent_session_id=excluded.parent_session_id,
+                    parent_event_id=excluded.parent_event_id
                 """,
                 (
                     session.get("session_id"),
@@ -208,6 +219,8 @@ class AnalyticsIndex:
                     session.get("status"),
                     session.get("started_at"),
                     session.get("ended_at"),
+                    session.get("parent_session_id"),
+                    session.get("parent_event_id"),
                 ),
             )
 
@@ -238,8 +251,8 @@ class AnalyticsIndex:
         with self.connect() as conn:
             conn.execute(
                 """
-                INSERT OR IGNORE INTO events(event_id, session_id, ts, tool, summary, success, feature_id, drift_score, payload_json)
-                VALUES(?,?,?,?,?,?,?,?,?)
+                INSERT OR IGNORE INTO events(event_id, session_id, ts, tool, summary, success, feature_id, drift_score, payload_json, parent_event_id, cost_tokens, execution_duration_seconds)
+                VALUES(?,?,?,?,?,?,?,?,?,?,?,?)
                 """,
                 (
                     event_id,
@@ -251,6 +264,9 @@ class AnalyticsIndex:
                     event.get("feature_id"),
                     event.get("drift_score"),
                     payload_json,
+                    event.get("parent_event_id"),
+                    event.get("cost_tokens"),
+                    event.get("execution_duration_seconds"),
                 ),
             )
             # Insert file path rows, idempotent by (event_id, path)
@@ -367,6 +383,8 @@ class AnalyticsIndex:
                         "status": event.get("session_status"),
                         "started_at": None,
                         "ended_at": None,
+                        "parent_session_id": event.get("parent_session_id"),
+                        "parent_event_id": event.get("parent_event_id"),
                     },
                 )
                 if meta.get("agent") is None and event.get("agent"):
@@ -377,6 +395,12 @@ class AnalyticsIndex:
                     meta["continued_from"] = event.get("continued_from")
                 if meta.get("status") is None and event.get("session_status"):
                     meta["status"] = event.get("session_status")
+                if meta.get("parent_session_id") is None and event.get(
+                    "parent_session_id"
+                ):
+                    meta["parent_session_id"] = event.get("parent_session_id")
+                if meta.get("parent_event_id") is None and event.get("parent_event_id"):
+                    meta["parent_event_id"] = event.get("parent_event_id")
 
                 # Track time range (treat earliest event as started_at, latest as ended_at if session is ended)
                 if meta["started_at"] is None or ts < meta["started_at"]:
@@ -393,8 +417,8 @@ class AnalyticsIndex:
 
                 conn.execute(
                     """
-                    INSERT OR IGNORE INTO events(event_id, session_id, ts, tool, summary, success, feature_id, drift_score, payload_json)
-                    VALUES(?,?,?,?,?,?,?,?,?)
+                    INSERT OR IGNORE INTO events(event_id, session_id, ts, tool, summary, success, feature_id, drift_score, payload_json, parent_event_id, cost_tokens, execution_duration_seconds)
+                    VALUES(?,?,?,?,?,?,?,?,?,?,?,?)
                     """,
                     (
                         event_id,
@@ -406,6 +430,9 @@ class AnalyticsIndex:
                         event.get("feature_id"),
                         event.get("drift_score"),
                         payload_json,
+                        event.get("parent_event_id"),
+                        event.get("cost_tokens"),
+                        event.get("execution_duration_seconds"),
                     ),
                 )
 
@@ -483,17 +510,19 @@ class AnalyticsIndex:
             for meta in session_meta.values():
                 conn.execute(
                     """
-                    INSERT INTO sessions(session_id, agent, start_commit, continued_from, status, started_at, ended_at)
-                    VALUES(?,?,?,?,?,?,?)
+                    INSERT INTO sessions(session_id, agent_assigned, start_commit, continued_from, status, started_at, ended_at, parent_session_id, parent_event_id)
+                    VALUES(?,?,?,?,?,?,?,?,?)
                     """,
                     (
                         meta.get("session_id"),
-                        meta.get("agent"),
+                        meta.get("agent"),  # Source data still uses 'agent' key
                         meta.get("start_commit"),
                         meta.get("continued_from"),
                         meta.get("status"),
                         meta.get("started_at"),
                         meta.get("ended_at"),
+                        meta.get("parent_session_id"),
+                        meta.get("parent_event_id"),
                     ),
                 )
 
@@ -676,13 +705,17 @@ class AnalyticsIndex:
         with self.connect() as conn:
             rows = conn.execute(
                 """
-                SELECT event_id, session_id, ts, tool, summary, success, feature_id, drift_score
-                FROM events
-                WHERE session_id=?
-                ORDER BY ts DESC
+                SELECT e.event_id, e.session_id, e.ts, e.tool, e.summary, e.success, e.feature_id, e.drift_score,
+                       COALESCE(e.parent_event_id, s.parent_event_id) as parent_event_id,
+                       e.cost_tokens, e.execution_duration_seconds
+                FROM events e
+                JOIN sessions s ON e.session_id = s.session_id
+                WHERE e.session_id = ?
+                   OR s.parent_session_id = ?
+                ORDER BY e.ts DESC
                 LIMIT ?
                 """,
-                (session_id, int(limit)),
+                (session_id, session_id, int(limit)),
             ).fetchall()
         return [dict(r) for r in rows]
 

htmlgraph/api/__init__.py

@@ -0,0 +1,3 @@
+"""HtmlGraph FastAPI Backend - Real-time Agent Observability Dashboard."""
+
+__all__ = ["app", "get_app"]