htmlgraph 0.26.25__py3-none-any.whl → 0.27.1__py3-none-any.whl

htmlgraph/db/schema.py

@@ -141,8 +141,15 @@ class HtmlGraphDB:
 
         # Migration: rename 'agent' to 'agent_assigned' if needed
         if "agent" in columns and "agent_assigned" not in columns:
-            cursor.execute("ALTER TABLE sessions RENAME COLUMN agent TO agent_assigned")
-            logger.info("Migrated sessions.agent -> sessions.agent_assigned")
+            try:
+                cursor.execute(
+                    "ALTER TABLE sessions RENAME COLUMN agent TO agent_assigned"
+                )
+                logger.info("Migrated sessions.agent -> sessions.agent_assigned")
+            except sqlite3.OperationalError as e:
+                logger.debug(f"Could not rename column: {e}")
+                # Column may already exist
+                pass
 
         # Add missing columns with defaults
         # Note: SQLite doesn't allow CURRENT_TIMESTAMP in ALTER TABLE, so we use NULL
@@ -169,6 +176,10 @@ class HtmlGraphDB:
             ("blockers", "TEXT"),  # JSON array of blocker strings
             ("recommended_context", "TEXT"),  # JSON array of file paths
             ("continued_from", "TEXT"),  # Previous session ID
+            # Phase 3.1: Real-time cost monitoring
+            ("cost_budget", "REAL"),  # Budget in USD for this session
+            ("cost_threshold_breached", "INTEGER DEFAULT 0"),  # Whether budget exceeded
+            ("predicted_cost", "REAL DEFAULT 0.0"),  # Predicted final cost
         ]
 
         # Refresh columns after potential rename
@@ -252,7 +263,7 @@ class HtmlGraphDB:
                 title TEXT NOT NULL,
                 description TEXT,
                 status TEXT NOT NULL DEFAULT 'todo' CHECK(
-                    status IN ('todo', 'in_progress', 'blocked', 'done', 'cancelled')
+                    status IN ('todo', 'in-progress', 'blocked', 'done', 'active', 'ended', 'stale')
                 ),
                 priority TEXT DEFAULT 'medium' CHECK(
                     priority IN ('low', 'medium', 'high', 'critical')
@@ -267,7 +278,7 @@ class HtmlGraphDB:
                 parent_feature_id TEXT,
                 tags JSON,
                 metadata JSON,
-                FOREIGN KEY (track_id) REFERENCES tracks(track_id),
+                FOREIGN KEY (track_id) REFERENCES tracks(id),
                 FOREIGN KEY (parent_feature_id) REFERENCES features(id)
             )
         """)
@@ -302,6 +313,9 @@ class HtmlGraphDB:
                 blockers JSON,
                 recommended_context JSON,
                 continued_from TEXT,
+                cost_budget REAL,
+                cost_threshold_breached INTEGER DEFAULT 0,
+                predicted_cost REAL DEFAULT 0.0,
                 FOREIGN KEY (parent_session_id) REFERENCES sessions(session_id) ON DELETE SET NULL ON UPDATE CASCADE,
                 FOREIGN KEY (parent_event_id) REFERENCES agent_events(event_id) ON DELETE SET NULL ON UPDATE CASCADE,
                 FOREIGN KEY (continued_from) REFERENCES sessions(session_id) ON DELETE SET NULL ON UPDATE CASCADE
@@ -311,14 +325,15 @@ class HtmlGraphDB:
         # 4. TRACKS TABLE - Multi-feature initiatives
         cursor.execute("""
             CREATE TABLE IF NOT EXISTS tracks (
-                track_id TEXT PRIMARY KEY,
+                id TEXT PRIMARY KEY,
+                type TEXT DEFAULT 'track',
                 title TEXT NOT NULL,
                 description TEXT,
                 priority TEXT DEFAULT 'medium' CHECK(
                     priority IN ('low', 'medium', 'high', 'critical')
                 ),
                 status TEXT NOT NULL DEFAULT 'todo' CHECK(
-                    status IN ('todo', 'in_progress', 'blocked', 'done', 'cancelled')
+                    status IN ('todo', 'in-progress', 'blocked', 'done', 'active', 'ended', 'stale')
                 ),
                 created_at DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP,
                 updated_at DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP,
@@ -436,6 +451,39 @@ class HtmlGraphDB:
             )
         """)
 
+        # 11. COST_EVENTS TABLE - Phase 3.1: Real-time cost monitoring & alerts
+        cursor.execute("""
+            CREATE TABLE IF NOT EXISTS cost_events (
+                event_id TEXT PRIMARY KEY,
+                session_id TEXT NOT NULL,
+                timestamp DATETIME NOT NULL DEFAULT CURRENT_TIMESTAMP,
+
+                -- Token tracking
+                tool_name TEXT,
+                model TEXT,
+                input_tokens INTEGER DEFAULT 0,
+                output_tokens INTEGER DEFAULT 0,
+                total_tokens INTEGER DEFAULT 0,
+                cost_usd REAL DEFAULT 0.0,
+
+                -- Agent tracking
+                agent_id TEXT,
+                subagent_type TEXT,
+
+                -- Alert tracking
+                alert_type TEXT,
+                message TEXT,
+                current_cost_usd REAL,
+                budget_usd REAL,
+                predicted_cost_usd REAL,
+                severity TEXT,
+                acknowledged BOOLEAN DEFAULT 0,
+
+                created_at DATETIME DEFAULT CURRENT_TIMESTAMP,
+                FOREIGN KEY (session_id) REFERENCES sessions(session_id) ON DELETE CASCADE
+            )
+        """)
+
         # 9. Create indexes for performance
         self._create_indexes(cursor)
 
@@ -529,6 +577,19 @@ class HtmlGraphDB:
             "CREATE INDEX IF NOT EXISTS idx_handoff_from_session ON handoff_tracking(from_session_id, created_at DESC)",
             "CREATE INDEX IF NOT EXISTS idx_handoff_to_session ON handoff_tracking(to_session_id, resumed_at DESC)",
             "CREATE INDEX IF NOT EXISTS idx_handoff_rating ON handoff_tracking(user_rating, created_at DESC)",
+            # cost_events indexes - optimized for real-time cost monitoring & alerts
+            # Pattern: WHERE session_id ORDER BY timestamp DESC (cost timeline)
+            "CREATE INDEX IF NOT EXISTS idx_cost_events_session_ts ON cost_events(session_id, timestamp DESC)",
+            # Pattern: WHERE alert_type (alert filtering)
+            "CREATE INDEX IF NOT EXISTS idx_cost_events_alert_type ON cost_events(alert_type, timestamp DESC)",
+            # Pattern: WHERE model GROUP BY (cost breakdown)
+            "CREATE INDEX IF NOT EXISTS idx_cost_events_model ON cost_events(model, session_id)",
+            # Pattern: WHERE tool_name GROUP BY (tool cost analysis)
+            "CREATE INDEX IF NOT EXISTS idx_cost_events_tool ON cost_events(tool_name, session_id)",
+            # Pattern: WHERE severity (alert severity filtering)
+            "CREATE INDEX IF NOT EXISTS idx_cost_events_severity ON cost_events(severity, timestamp DESC)",
+            # Pattern: Timestamp range queries for predictions
+            "CREATE INDEX IF NOT EXISTS idx_cost_events_timestamp ON cost_events(timestamp DESC)",
         ]
 
         for index_sql in indexes:

htmlgraph/dependency_models.py

@@ -1,3 +1,5 @@
+from __future__ import annotations
+
 """
 Data models for dependency analytics.
 
@@ -9,7 +11,6 @@ Provides Pydantic models for dependency-aware analytics results including:
 - Work prioritization
 """
 
-from __future__ import annotations
 
 from typing import Literal
 

htmlgraph/edge_index.py

@@ -1,3 +1,5 @@
+from __future__ import annotations
+
 """
 Edge Index for O(1) reverse edge lookups.
 
@@ -10,7 +12,6 @@ Without this index, finding incoming edges requires scanning all nodes
 in the graph - O(V×E) complexity.
 """
 
-from __future__ import annotations
 
 from collections import defaultdict
 from collections.abc import Iterator

htmlgraph/event_log.py

@@ -1,3 +1,5 @@
+from __future__ import annotations
+
 """
 Event logging for HtmlGraph.
 
@@ -9,84 +11,98 @@ Design goals:
 - Deterministic serialization for rebuildable analytics indexes
 """
 
-from __future__ import annotations
 
 import json
-from dataclasses import dataclass
 from datetime import datetime
 from pathlib import Path
 from typing import TYPE_CHECKING, Any
 
+from pydantic import BaseModel, ConfigDict, Field, field_serializer, field_validator
+
 if TYPE_CHECKING:
     pass
 
 
-@dataclass(frozen=True)
-class EventRecord:
-    event_id: str
-    timestamp: datetime
-    session_id: str
-    agent: str
-    tool: str
-    summary: str
-    success: bool
-    feature_id: str | None
-    drift_score: float | None
-    start_commit: str | None
-    continued_from: str | None
-    work_type: str | None = None  # WorkType enum value
-    session_status: str | None = None
-    file_paths: list[str] | None = None
-    payload: dict[str, Any] | None = None
-    parent_session_id: str | None = None  # Link to parent session (e.g. for subagents)
+class EventRecord(BaseModel):
+    """
+    Event record for HtmlGraph tracking.
+
+    Uses Pydantic for automatic validation and serialization.
+    Immutable via ConfigDict(frozen=True).
+    """
+
+    model_config = ConfigDict(frozen=True)
+
+    event_id: str = Field(..., min_length=1, description="Unique event identifier")
+    timestamp: datetime = Field(..., description="Event timestamp")
+    session_id: str = Field(..., min_length=1, description="Session identifier")
+    agent: str = Field(..., description="Agent name (e.g., 'claude', 'gemini')")
+    tool: str = Field(..., description="Tool used (e.g., 'Bash', 'Edit', 'Read')")
+    summary: str = Field(..., description="Human-readable event summary")
+    success: bool = Field(..., description="Whether the operation succeeded")
+    feature_id: str | None = Field(None, description="Associated feature ID")
+    drift_score: float | None = Field(None, description="Context drift score")
+    start_commit: str | None = Field(None, description="Starting git commit hash")
+    continued_from: str | None = Field(
+        None, description="Previous session ID if continued"
+    )
+    work_type: str | None = Field(None, description="WorkType enum value")
+    session_status: str | None = Field(None, description="Session status")
+    file_paths: list[str] | None = Field(None, description="Files involved in event")
+    payload: dict[str, Any] | None = Field(None, description="Additional event data")
+    parent_session_id: str | None = Field(
+        None, description="Parent session ID for subagents"
+    )
+
     # Phase 1: Enhanced Event Data Schema for multi-AI delegation tracking
-    delegated_to_ai: str | None = (
-        None  # "gemini", "codex", "copilot", "claude", or None
+    delegated_to_ai: str | None = Field(
+        None, description="AI delegate: 'gemini', 'codex', 'copilot', 'claude', or None"
+    )
+    task_id: str | None = Field(
+        None, description="Unique task ID for parallel tracking"
+    )
+    task_status: str | None = Field(
+        None,
+        description="Task status: 'pending', 'running', 'completed', 'failed', 'timeout'",
+    )
+    model_selected: str | None = Field(
+        None, description="Specific model (e.g., 'gemini-2.0-flash')"
+    )
+    complexity_level: str | None = Field(
+        None, description="Complexity: 'low', 'medium', 'high', 'very-high'"
+    )
+    budget_mode: str | None = Field(
+        None, description="Budget mode: 'free', 'balanced', 'performance'"
     )
-    task_id: str | None = None  # Unique task ID for parallel tracking
-    task_status: str | None = (
-        None  # "pending", "running", "completed", "failed", "timeout"
+    execution_duration_seconds: float | None = Field(
+        None, description="Delegation execution time"
     )
-    model_selected: str | None = None  # Specific model (e.g., "gemini-2.0-flash")
-    complexity_level: str | None = None  # "low", "medium", "high", "very-high"
-    budget_mode: str | None = None  # "free", "balanced", "performance"
-    execution_duration_seconds: float | None = None  # How long delegation took
-    tokens_estimated: int | None = None  # Estimated token usage
-    tokens_actual: int | None = None  # Actual token usage
-    cost_usd: float | None = None  # Calculated cost
-    task_findings: str | None = None  # Results from delegated task
+    tokens_estimated: int | None = Field(None, description="Estimated token usage")
+    tokens_actual: int | None = Field(None, description="Actual token usage")
+    cost_usd: float | None = Field(None, description="Calculated cost in USD")
+    task_findings: str | None = Field(None, description="Results from delegated task")
+
+    @field_validator("event_id", "session_id")
+    @classmethod
+    def validate_non_empty_string(cls, v: str) -> str:
+        """Ensure event_id and session_id are non-empty."""
+        if not v or not v.strip():
+            raise ValueError("Field must be a non-empty string")
+        return v
+
+    @field_serializer("timestamp")
+    def serialize_timestamp(self, timestamp: datetime) -> str:
+        """Serialize timestamp to ISO format string."""
+        return timestamp.isoformat()
+
+    @field_serializer("file_paths")
+    def serialize_file_paths(self, file_paths: list[str] | None) -> list[str]:
+        """Ensure file_paths is always a list (never None) in JSON output."""
+        return file_paths or []
 
     def to_json(self) -> dict[str, Any]:
-        return {
-            "event_id": self.event_id,
-            "timestamp": self.timestamp.isoformat(),
-            "session_id": self.session_id,
-            "agent": self.agent,
-            "tool": self.tool,
-            "summary": self.summary,
-            "success": self.success,
-            "feature_id": self.feature_id,
-            "work_type": self.work_type,
-            "drift_score": self.drift_score,
-            "start_commit": self.start_commit,
-            "continued_from": self.continued_from,
-            "session_status": self.session_status,
-            "file_paths": self.file_paths or [],
-            "payload": self.payload,
-            "parent_session_id": self.parent_session_id,
-            # Delegation fields
-            "delegated_to_ai": self.delegated_to_ai,
-            "task_id": self.task_id,
-            "task_status": self.task_status,
-            "model_selected": self.model_selected,
-            "complexity_level": self.complexity_level,
-            "budget_mode": self.budget_mode,
-            "execution_duration_seconds": self.execution_duration_seconds,
-            "tokens_estimated": self.tokens_estimated,
-            "tokens_actual": self.tokens_actual,
-            "cost_usd": self.cost_usd,
-            "task_findings": self.task_findings,
-        }
+        """Convert EventRecord to JSON-serializable dictionary."""
+        return self.model_dump(mode="json")
 
 
 class JsonlEventLog:
@@ -104,7 +120,10 @@ class JsonlEventLog:
 
     def append(self, record: EventRecord) -> Path:
         path = self.path_for_session(record.session_id)
-        line = json.dumps(record.to_json(), ensure_ascii=False, default=str) + "\n"
+        line = (
+            json.dumps(record.model_dump(mode="json"), ensure_ascii=False, default=str)
+            + "\n"
+        )
         path.parent.mkdir(parents=True, exist_ok=True)
 
         # Best-effort dedupe: some producers (e.g. git hooks) may retry or be chained.

htmlgraph/event_migration.py

@@ -1,8 +1,9 @@
+from __future__ import annotations
+
 """
 Helpers to migrate legacy session HTML activity logs to JSONL event logs.
 """
 
-from __future__ import annotations
 
 import json
 from pathlib import Path

htmlgraph/file_watcher.py

@@ -1,3 +1,7 @@
+import logging
+
+logger = logging.getLogger(__name__)
+
 """
 File watcher for automatic graph reloading.
 
@@ -67,7 +71,7 @@ class GraphFileHandler(FileSystemEventHandler):
 
     def _trigger_reload(self) -> None:
         """Trigger a reload after debounce delay."""
-        print(f"[FileWatcher] Reloading collection: {self.collection}")
+        logger.info(f"[FileWatcher] Reloading collection: {self.collection}")
         self.reload_callback()
 
     def _debounced_reload(self) -> None:
@@ -87,7 +91,7 @@ class GraphFileHandler(FileSystemEventHandler):
         if not self._is_relevant_file(str(event.src_path)):
             return
 
-        print(
+        logger.debug(
             f"[FileWatcher] {self.collection}: File created - {Path(str(event.src_path)).name}"
         )
         self._debounced_reload()
@@ -101,7 +105,7 @@ class GraphFileHandler(FileSystemEventHandler):
         if not self._is_relevant_file(str(event.src_path)):
             return
 
-        print(
+        logger.debug(
             f"[FileWatcher] {self.collection}: File modified - {Path(str(event.src_path)).name}"
         )
         self._debounced_reload()
@@ -115,7 +119,7 @@ class GraphFileHandler(FileSystemEventHandler):
         if not self._is_relevant_file(str(event.src_path)):
             return
 
-        print(
+        logger.debug(
             f"[FileWatcher] {self.collection}: File deleted - {Path(str(event.src_path)).name}"
         )
         self._debounced_reload()
@@ -146,7 +150,7 @@ class GraphWatcher:
 
     def start(self) -> None:
         """Start watching for file changes."""
-        print(
+        logger.info(
             f"[FileWatcher] Starting file watcher for {len(self.collections)} collections..."
         )
 
@@ -160,7 +164,7 @@ class GraphWatcher:
                 def reload() -> None:
                     graph = self.get_graph_callback(coll)
                     count = graph.reload()
-                    print(f"[FileWatcher] Reloaded {count} nodes in {coll}")
+                    logger.info(f"[FileWatcher] Reloaded {count} nodes in {coll}")
 
                 return reload
 
@@ -173,11 +177,11 @@ class GraphWatcher:
             self.observer.schedule(handler, str(collection_dir), recursive=recursive)
 
         self.observer.start()
-        print(f"[FileWatcher] Watching {self.graph_dir} for changes...")
+        logger.info(f"[FileWatcher] Watching {self.graph_dir} for changes...")
 
     def stop(self) -> None:
         """Stop watching for file changes."""
-        print("[FileWatcher] Stopping file watcher...")
+        logger.info("[FileWatcher] Stopping file watcher...")
         self.observer.stop()
         self.observer.join()
 

htmlgraph/find_api.py

@@ -1,3 +1,5 @@
+from __future__ import annotations
+
 """
 BeautifulSoup-style Find API for HtmlGraph.
 
@@ -22,7 +24,6 @@ Example:
     nodes = graph.find_all(properties__effort__gt=8)
 """
 
-from __future__ import annotations
 
 import re
 from collections.abc import Callable

htmlgraph/git_events.py

@@ -1,3 +1,5 @@
+from __future__ import annotations
+
 """
 Git event logging for HtmlGraph.
 
@@ -10,7 +12,6 @@ Design goals:
 - Analytics-friendly: schema compatible with EventRecord/AnalyticsIndex
 """
 
-from __future__ import annotations
 
 import os
 import re
@@ -277,7 +278,10 @@ def _append_event(
         p.parent.mkdir(parents=True, exist_ok=True)
         with p.open("a", encoding="utf-8") as f:
             f.write(
-                json.dumps(record.to_json(), ensure_ascii=False, default=str) + "\n"
+                json.dumps(
+                    record.model_dump(mode="json"), ensure_ascii=False, default=str
+                )
+                + "\n"
             )
         return
 

htmlgraph/hooks/cigs_pretool_enforcer.py

@@ -1,3 +1,7 @@
+import logging
+
+logger = logging.getLogger(__name__)
+
 """
 CIGS PreToolUse Enforcer - Enhanced Orchestrator Enforcement with Escalation
 
@@ -309,7 +313,7 @@ def enforce_cigs_pretool(tool_input: dict[str, Any]) -> dict[str, Any]:
         return enforcer.enforce(tool, params)
     except Exception as e:
         # Graceful degradation - allow on error
-        print(f"Warning: CIGS enforcement error: {e}", file=sys.stderr)
+        logger.warning(f"Warning: CIGS enforcement error: {e}")
         return {
             "hookSpecificOutput": {
                 "hookEventName": "PreToolUse",

htmlgraph/hooks/drift_handler.py

@@ -133,7 +133,7 @@ def load_drift_config(graph_dir: Path) -> dict[str, Any]:
     Example:
         ```python
         config = load_drift_config(Path(".htmlgraph"))
-        print(f"Auto-classify threshold: {config['drift_detection']['auto_classify_threshold']}")
+        logger.info(f"Auto-classify threshold: {config['drift_detection']['auto_classify_threshold']}")
         ```
     """
     graph_dir = Path(graph_dir)
@@ -196,7 +196,7 @@ def detect_drift(
         ```python
         score, feature_id = detect_drift(activity_result, config)
         if score > config['drift_detection']['auto_classify_threshold']:
-            print(f"HIGH DRIFT: {score:.2f}")
+            logger.info(f"HIGH DRIFT: {score:.2f}")
         ```
     """
     drift_score = getattr(activity_result, "drift_score", 0.0) or 0.0
@@ -242,7 +242,7 @@ def handle_high_drift(
         ```python
         nudge = handle_high_drift(context, 0.87, queue, config)
         if nudge:
-            print(nudge)  # "HIGH DRIFT (0.87): Activity queued for classification..."
+            logger.info("%s", nudge)  # "HIGH DRIFT (0.87): Activity queued for classification..."
         ```
     """
     drift_config = config.get("drift_detection", {})