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

htmlgraph/event_log.py

@@ -1,3 +1,5 @@
+from __future__ import annotations
+
 """
 Event logging for HtmlGraph.
 
@@ -9,54 +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 Any, TYPE_CHECKING
+from typing import TYPE_CHECKING, Any
+
+from pydantic import BaseModel, ConfigDict, Field, field_serializer, field_validator
 
 if TYPE_CHECKING:
-    from htmlgraph.models import WorkType
-
-
-@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
+    pass
+
+
+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 = 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'"
+    )
+    execution_duration_seconds: float | None = Field(
+        None, description="Delegation execution time"
+    )
+    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,
-        }
+        """Convert EventRecord to JSON-serializable dictionary."""
+        return self.model_dump(mode="json")
 
 
 class JsonlEventLog:
@@ -74,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.
@@ -106,7 +155,7 @@ class JsonlEventLog:
             f.write(line)
         return path
 
-    def iter_events(self):
+    def iter_events(self) -> Any:
         """
         Yield (path, event_dict) for all events across all JSONL files.
         Skips malformed lines.
@@ -129,10 +178,7 @@ class JsonlEventLog:
                 continue
 
     def get_session_events(
-        self,
-        session_id: str,
-        limit: int | None = None,
-        offset: int = 0
+        self, session_id: str, limit: int | None = None, offset: int = 0
     ) -> list[dict[str, Any]]:
         """
         Get events for a specific session with pagination.
@@ -177,7 +223,7 @@ class JsonlEventLog:
         tool: str | None = None,
         feature_id: str | None = None,
         since: Any = None,  # datetime or ISO string
-        limit: int | None = None
+        limit: int | None = None,
     ) -> list[dict[str, Any]]:
         """
         Query events with filters.
@@ -198,7 +244,7 @@ class JsonlEventLog:
         since_dt = None
         if since:
             if isinstance(since, str):
-                since_dt = datetime.fromisoformat(since.replace('Z', '+00:00'))
+                since_dt = datetime.fromisoformat(since.replace("Z", "+00:00"))
             else:
                 since_dt = since
 
@@ -213,19 +259,21 @@ class JsonlEventLog:
         filtered: list[dict[str, Any]] = []
         for evt in events:
             # Tool filter
-            if tool and evt.get('tool') != tool:
+            if tool and evt.get("tool") != tool:
                 continue
 
             # Feature filter
-            if feature_id and evt.get('feature_id') != feature_id:
+            if feature_id and evt.get("feature_id") != feature_id:
                 continue
 
             # Timestamp filter
             if since_dt:
-                evt_time_str = evt.get('timestamp')
+                evt_time_str = evt.get("timestamp")
                 if evt_time_str and isinstance(evt_time_str, str):
                     try:
-                        evt_time = datetime.fromisoformat(evt_time_str.replace('Z', '+00:00'))
+                        evt_time = datetime.fromisoformat(
+                            evt_time_str.replace("Z", "+00:00")
+                        )
                         if evt_time < since_dt:
                             continue
                     except (ValueError, AttributeError):

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
@@ -43,9 +44,15 @@ def export_sessions_to_jsonl(
         # Serialize as one JSON object per line, oldest -> newest.
         lines: list[str] = []
         for entry in session.activity_log:
-            payload: dict[str, Any] | None = entry.payload if isinstance(entry.payload, dict) else None
+            payload: dict[str, Any] | None = (
+                entry.payload if isinstance(entry.payload, dict) else None
+            )
             file_paths = None
-            if payload and "file_paths" in payload and isinstance(payload["file_paths"], list):
+            if (
+                payload
+                and "file_paths" in payload
+                and isinstance(payload["file_paths"], list)
+            ):
                 file_paths = payload["file_paths"]
 
             event = {
@@ -66,7 +73,9 @@ def export_sessions_to_jsonl(
             }
             lines.append(json.dumps(event, ensure_ascii=False, default=str))
 
-        out_path.write_text("\n".join(lines) + ("\n" if lines else ""), encoding="utf-8")
+        out_path.write_text(
+            "\n".join(lines) + ("\n" if lines else ""), encoding="utf-8"
+        )
         written += 1
 
     return {"written": written, "skipped": skipped, "failed": failed}

htmlgraph/exceptions.py

@@ -0,0 +1,49 @@
+"""Custom exceptions for HtmlGraph."""
+
+
+class HtmlGraphError(Exception):
+    """Base exception for all HtmlGraph errors with debugging guidance."""
+
+    def __str__(self) -> str:
+        """Return error message with debugging guidance."""
+        base_message = super().__str__()
+        guidance = (
+            "\n\n💡 Debugging help:"
+            "\n  - See DEBUGGING.md for systematic troubleshooting"
+            "\n  - Use researcher agent for unfamiliar errors"
+            "\n  - Run 'htmlgraph --help' for available commands"
+            "\n  - Run 'htmlgraph debug' for diagnostic tools"
+        )
+        return f"{base_message}{guidance}"
+
+
+class NodeNotFoundError(HtmlGraphError):
+    """Raised when a node cannot be found."""
+
+    def __init__(self, node_type: str, node_id: str):
+        self.node_type = node_type
+        self.node_id = node_id
+        super().__init__(f"{node_type.capitalize()} not found: {node_id}")
+
+
+class SessionNotFoundError(HtmlGraphError):
+    """Raised when a session cannot be found."""
+
+    def __init__(self, session_id: str):
+        self.session_id = session_id
+        super().__init__(f"Session not found: {session_id}")
+
+
+class ClaimConflictError(HtmlGraphError):
+    """Raised when a claim operation conflicts with existing claim."""
+
+    def __init__(self, node_id: str, current_owner: str):
+        self.node_id = node_id
+        self.current_owner = current_owner
+        super().__init__(f"Node {node_id} already claimed by {current_owner}")
+
+
+class ValidationError(HtmlGraphError):
+    """Raised when validation fails."""
+
+    pass

htmlgraph/file_watcher.py

@@ -1,15 +1,34 @@
+import logging
+
+logger = logging.getLogger(__name__)
+
 """
 File watcher for automatic graph reloading.
 
 Monitors .htmlgraph/**/*.html files and reloads collections when changes are detected.
 """
 
-import time
+import fnmatch
 import threading
+from collections.abc import Callable
 from pathlib import Path
-from typing import Callable
+from typing import Any
+
+from watchdog.events import FileSystemEvent, FileSystemEventHandler
 from watchdog.observers import Observer
-from watchdog.events import FileSystemEventHandler, FileSystemEvent
+
+# Collection-specific file patterns for smart filtering
+COLLECTION_PATTERNS = {
+    "features": ["feat-*.html", "feature-*.html"],
+    "bugs": ["bug-*.html"],
+    "spikes": ["spk-*.html", "spike-*.html"],
+    "sessions": ["sess-*.html", "session-*.html"],
+    "tracks": ["trk-*.html", "track-*.html"],
+    "chores": ["chore-*.html"],
+    "insights": ["insi-*.html", "insight-*.html"],
+    "patterns": ["patt-*.html", "pattern-*.html"],
+    "metrics": ["metr-*.html", "metric-*.html"],
+}
 
 
 class GraphFileHandler(FileSystemEventHandler):
@@ -28,12 +47,34 @@ class GraphFileHandler(FileSystemEventHandler):
         self.debounce_timer: threading.Timer | None = None
         self.debounce_delay = 0.5  # 500ms debounce
 
-    def _trigger_reload(self):
+    def _is_relevant_file(self, filepath: str) -> bool:
+        """
+        Check if changed file is relevant to this watcher's collection.
+
+        Args:
+            filepath: Path to the file that changed
+
+        Returns:
+            True if the file matches this collection's patterns
+        """
+        filename = Path(filepath).name
+
+        # Skip non-HTML files
+        if not filename.endswith(".html"):
+            return False
+
+        # Get patterns for this collection (default to all HTML if not found)
+        patterns = COLLECTION_PATTERNS.get(self.collection, ["*.html"])
+
+        # Check if filename matches any pattern
+        return any(fnmatch.fnmatch(filename, pattern) for pattern in patterns)
+
+    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):
+    def _debounced_reload(self) -> None:
         """Debounce rapid file changes to avoid excessive reloads."""
         if self.debounce_timer:
             self.debounce_timer.cancel()
@@ -41,29 +82,58 @@ class GraphFileHandler(FileSystemEventHandler):
         self.debounce_timer = threading.Timer(self.debounce_delay, self._trigger_reload)
         self.debounce_timer.start()
 
-    def on_created(self, event: FileSystemEvent):
+    def on_created(self, event: FileSystemEvent) -> None:
         """Handle file creation."""
-        if not event.is_directory and event.src_path.endswith('.html'):
-            print(f"[FileWatcher] {self.collection}: File created - {Path(event.src_path).name}")
-            self._debounced_reload()
+        if event.is_directory:
+            return
+
+        # Skip if not relevant to our collection
+        if not self._is_relevant_file(str(event.src_path)):
+            return
+
+        logger.debug(
+            f"[FileWatcher] {self.collection}: File created - {Path(str(event.src_path)).name}"
+        )
+        self._debounced_reload()
 
-    def on_modified(self, event: FileSystemEvent):
+    def on_modified(self, event: FileSystemEvent) -> None:
         """Handle file modification."""
-        if not event.is_directory and event.src_path.endswith('.html'):
-            print(f"[FileWatcher] {self.collection}: File modified - {Path(event.src_path).name}")
-            self._debounced_reload()
+        if event.is_directory:
+            return
 
-    def on_deleted(self, event: FileSystemEvent):
+        # Skip if not relevant to our collection
+        if not self._is_relevant_file(str(event.src_path)):
+            return
+
+        logger.debug(
+            f"[FileWatcher] {self.collection}: File modified - {Path(str(event.src_path)).name}"
+        )
+        self._debounced_reload()
+
+    def on_deleted(self, event: FileSystemEvent) -> None:
         """Handle file deletion."""
-        if not event.is_directory and event.src_path.endswith('.html'):
-            print(f"[FileWatcher] {self.collection}: File deleted - {Path(event.src_path).name}")
-            self._debounced_reload()
+        if event.is_directory:
+            return
+
+        # Skip if not relevant to our collection
+        if not self._is_relevant_file(str(event.src_path)):
+            return
+
+        logger.debug(
+            f"[FileWatcher] {self.collection}: File deleted - {Path(str(event.src_path)).name}"
+        )
+        self._debounced_reload()
 
 
 class GraphWatcher:
     """Watches graph directories and triggers reloads on changes."""
 
-    def __init__(self, graph_dir: Path, collections: list[str], get_graph_callback: Callable[[str], any]):
+    def __init__(
+        self,
+        graph_dir: Path,
+        collections: list[str],
+        get_graph_callback: Callable[[str], Any],
+    ) -> None:
         """
         Initialize watcher.
 
@@ -78,9 +148,11 @@ class GraphWatcher:
         self.observer = Observer()
         self.handlers: dict[str, GraphFileHandler] = {}
 
-    def start(self):
+    def start(self) -> None:
         """Start watching for file changes."""
-        print(f"[FileWatcher] Starting file watcher for {len(self.collections)} collections...")
+        logger.info(
+            f"[FileWatcher] Starting file watcher for {len(self.collections)} collections..."
+        )
 
         for collection in self.collections:
             collection_dir = self.graph_dir / collection
@@ -88,11 +160,12 @@ class GraphWatcher:
                 continue
 
             # Create handler with reload callback
-            def make_reload_callback(coll):
-                def reload():
+            def make_reload_callback(coll: str) -> Callable[[], None]:
+                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
 
             handler = GraphFileHandler(collection, make_reload_callback(collection))
@@ -100,15 +173,15 @@ class GraphWatcher:
 
             # Watch the collection directory
             # Use recursive=True for tracks since they're stored in subdirectories
-            recursive = (collection == "tracks")
+            recursive = collection == "tracks"
             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):
+    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()