htmlgraph 0.26.24__py3-none-any.whl → 0.27.0__py3-none-any.whl

htmlgraph/collections/feature.py

@@ -1,10 +1,11 @@
+from __future__ import annotations
+
 """
 Feature collection for managing feature work items.
 
 Extends BaseCollection with feature-specific builder support.
 """
 
-from __future__ import annotations
 
 from typing import TYPE_CHECKING
 

htmlgraph/collections/insight.py

@@ -1,10 +1,11 @@
+from __future__ import annotations
+
 """
 SessionInsight collection for managing session insights.
 
 Extends BaseCollection with insight-specific query methods.
 """
 
-from __future__ import annotations
 
 from typing import TYPE_CHECKING
 

htmlgraph/collections/metric.py

@@ -1,10 +1,11 @@
+from __future__ import annotations
+
 """
 AggregatedMetric collection for managing aggregated metrics.
 
 Extends BaseCollection with metric-specific query methods.
 """
 
-from __future__ import annotations
 
 from typing import TYPE_CHECKING
 

htmlgraph/collections/pattern.py

@@ -1,10 +1,11 @@
+from __future__ import annotations
+
 """
 Pattern collection for managing workflow patterns.
 
 Extends BaseCollection with pattern-specific query methods.
 """
 
-from __future__ import annotations
 
 from typing import TYPE_CHECKING
 

htmlgraph/collections/phase.py

@@ -1,10 +1,11 @@
+from __future__ import annotations
+
 """
 Phase collection for managing project phase work items.
 
 Extends BaseCollection with phase-specific builder support.
 """
 
-from __future__ import annotations
 
 from typing import TYPE_CHECKING
 

htmlgraph/collections/session.py

@@ -1,3 +1,9 @@
+from __future__ import annotations
+
+import logging
+
+logger = logging.getLogger(__name__)
+
 """
 SessionCollection - Session state and management interface.
 
@@ -13,7 +19,6 @@ Integration with SessionStart hook:
     sdk.sessions.setup_environment_variables(state)
 """
 
-from __future__ import annotations
 
 from typing import TYPE_CHECKING
 
@@ -82,9 +87,9 @@ class SessionCollection(BaseCollection):
         Example:
             >>> sdk = SDK()
             >>> state = sdk.sessions.get_current_state()
-            >>> print(f"Session: {state['session_id']}")
-            >>> print(f"Post-compact: {state['is_post_compact']}")
-            >>> print(f"Delegation enabled: {state['delegation_enabled']}")
+            >>> logger.info(f"Session: {state['session_id']}")
+            >>> logger.info(f"Post-compact: {state['is_post_compact']}")
+            >>> logger.info(f"Delegation enabled: {state['delegation_enabled']}")
         """
         return self._state_manager.get_current_state()
 
@@ -116,8 +121,8 @@ class SessionCollection(BaseCollection):
             >>> sdk = SDK()
             >>> state = sdk.sessions.get_current_state()
             >>> env_vars = sdk.sessions.setup_environment_variables(state)
-            >>> print(f"CLAUDE_SESSION_ID: {env_vars['CLAUDE_SESSION_ID']}")
-            >>> print(f"CLAUDE_DELEGATION_ENABLED: {env_vars['CLAUDE_DELEGATION_ENABLED']}")
+            >>> logger.info(f"CLAUDE_SESSION_ID: {env_vars['CLAUDE_SESSION_ID']}")
+            >>> logger.info(f"CLAUDE_DELEGATION_ENABLED: {env_vars['CLAUDE_DELEGATION_ENABLED']}")
         """
         return self._state_manager.setup_environment_variables(
             session_state=session_state, auto_detect_compact=auto_detect_compact
@@ -168,7 +173,7 @@ class SessionCollection(BaseCollection):
         Example:
             >>> sdk = SDK()
             >>> if sdk.sessions.detect_compact_automatically():
-            ...     print("This is a post-compact session")
+            ...     logger.info("This is a post-compact session")
         """
         return self._state_manager.detect_compact_automatically()
 

htmlgraph/collections/spike.py

@@ -1,10 +1,15 @@
+from __future__ import annotations
+
+import logging
+
+logger = logging.getLogger(__name__)
+
 """
 Spike collection for managing investigation and research spikes.
 
 Extends BaseCollection with spike-specific builder support.
 """
 
-from __future__ import annotations
 
 from datetime import datetime
 from typing import TYPE_CHECKING

htmlgraph/collections/task_delegation.py

@@ -1,3 +1,9 @@
+from __future__ import annotations
+
+import logging
+
+logger = logging.getLogger(__name__)
+
 """
 Task delegation collection for tracking spawned agent work.
 
@@ -12,7 +18,6 @@ Captures observability data for Task() calls:
 This data proves multi-agent orchestration works and enables dashboard attribution.
 """
 
-from __future__ import annotations
 
 from datetime import datetime
 from typing import TYPE_CHECKING, Any
@@ -41,7 +46,7 @@ class TaskDelegationCollection(BaseCollection["TaskDelegationCollection"]):
         >>> sdk = SDK(agent="orchestrator")
         >>> delegations = sdk.task_delegations.where(agent_type="codex-spawner")
         >>> for d in delegations:
-        ...     print(f"{d.agent_type}: {d.task_description} ({d.duration_seconds}s)")
+        ...     logger.info(f"{d.agent_type}: {d.task_description} ({d.duration_seconds}s)")
         >>>
         >>> # Get all delegations for a specific agent
         >>> gemini_work = sdk.task_delegations.where(agent_type="gemini-spawner")

htmlgraph/collections/todo.py

@@ -1,3 +1,5 @@
+from __future__ import annotations
+
 """
 Todo collection for managing persistent todo items.
 
@@ -8,7 +10,6 @@ Unlike other collections, TodoCollection provides:
 - Bulk sync from TodoWrite format
 """
 
-from __future__ import annotations
 
 from datetime import datetime
 from typing import TYPE_CHECKING, Any
@@ -64,6 +65,18 @@ class TodoCollection:
 
         # Cache for loaded todos (lazy-loaded)
         self._todos: dict[str, Todo] | None = None
+        self._ref_manager: Any = None  # Set by SDK during initialization
+
+    def set_ref_manager(self, ref_manager: Any) -> None:
+        """
+        Set the ref manager for this collection.
+
+        Called by SDK during initialization to enable short ref support.
+
+        Args:
+            ref_manager: RefManager instance from SDK
+        """
+        self._ref_manager = ref_manager
 
     def _ensure_loaded(self) -> dict[str, Todo]:
         """Load todos from disk if not cached."""

htmlgraph/collections/traces.py

@@ -1,3 +1,9 @@
+from __future__ import annotations
+
+import logging
+
+logger = logging.getLogger(__name__)
+
 """
 Tool Execution Traces Collection
 
@@ -11,21 +17,20 @@ Example:
     >>> # Get traces for current session
     >>> traces = sdk.traces.get_traces(session_id="sess-abc123")
     >>> for trace in traces:
-    ...     print(f"{trace.tool_name}: {trace.duration_ms}ms")
+    ...     logger.info(f"{trace.tool_name}: {trace.duration_ms}ms")
     >>>
     >>> # Find slow tool calls
     >>> slow = sdk.traces.get_slow_traces(threshold_ms=1000)
     >>>
     >>> # Get hierarchical view (parent-child relationships)
     >>> tree = sdk.traces.get_trace_tree(trace_id="trace-xyz")
-    >>> print(f"Root: {tree.root.tool_name}")
-    >>> print(f"Children: {len(tree.children)}")
+    >>> logger.info(f"Root: {tree.root.tool_name}")
+    >>> logger.info(f"Children: {len(tree.children)}")
     >>>
     >>> # Get error traces for debugging
     >>> errors = sdk.traces.get_error_traces(session_id="sess-abc123")
 """
 
-from __future__ import annotations
 
 from dataclasses import dataclass
 from datetime import datetime, timezone
@@ -245,7 +250,7 @@ class TraceCollection:
 
             return None
         except Exception as e:
-            print(f"Error getting trace {tool_use_id}: {e}")
+            logger.info(f"Error getting trace {tool_use_id}: {e}")
             return None
 
     def get_traces(
@@ -302,7 +307,7 @@ class TraceCollection:
             rows = cursor.fetchall()
             return [self._row_to_trace(row) for row in rows]
         except Exception as e:
-            print(f"Error getting traces for session {session_id}: {e}")
+            logger.info(f"Error getting traces for session {session_id}: {e}")
             return []
 
     def get_traces_by_tool(self, tool_name: str, limit: int = 100) -> list[TraceRecord]:
@@ -337,7 +342,7 @@ class TraceCollection:
             rows = cursor.fetchall()
             return [self._row_to_trace(row) for row in rows]
         except Exception as e:
-            print(f"Error getting traces for tool {tool_name}: {e}")
+            logger.info(f"Error getting traces for tool {tool_name}: {e}")
             return []
 
     def get_trace_tree(self, trace_id: str) -> TraceTree | None:
@@ -403,7 +408,7 @@ class TraceCollection:
 
             return build_tree(root)
         except Exception as e:
-            print(f"Error getting trace tree for {trace_id}: {e}")
+            logger.info(f"Error getting trace tree for {trace_id}: {e}")
             return None
 
     def get_slow_traces(self, threshold_ms: int, limit: int = 100) -> list[TraceRecord]:
@@ -440,7 +445,7 @@ class TraceCollection:
             rows = cursor.fetchall()
             return [self._row_to_trace(row) for row in rows]
         except Exception as e:
-            print(f"Error getting slow traces: {e}")
+            logger.info(f"Error getting slow traces: {e}")
             return []
 
     def get_error_traces(self, session_id: str, limit: int = 100) -> list[TraceRecord]:
@@ -478,5 +483,5 @@ class TraceCollection:
             rows = cursor.fetchall()
             return [self._row_to_trace(row) for row in rows]
         except Exception as e:
-            print(f"Error getting error traces: {e}")
+            logger.info(f"Error getting error traces: {e}")
             return []

htmlgraph/context_analytics.py

@@ -1,3 +1,5 @@
+from __future__ import annotations
+
 """
 Context Analytics for HtmlGraph
 
@@ -7,7 +9,6 @@ Provides hierarchical context usage tracking and analytics:
 Enables drill-down analysis of where context was consumed.
 """
 
-from __future__ import annotations
 
 from dataclasses import dataclass, field
 from typing import TYPE_CHECKING, Any

htmlgraph/converter.py

@@ -520,6 +520,17 @@ def html_to_session(filepath: Path | str) -> Session:
         if blockers:
             data["blockers"] = blockers
 
+        # Parse recommended context files
+        recommended_context = []
+        for li in parser.query(
+            "section[data-handoff] div[data-recommended-context] li"
+        ):
+            file_path = li.to_text().strip()
+            if file_path:
+                recommended_context.append(file_path)
+        if recommended_context:
+            data["recommended_context"] = recommended_context
+
     # Parse activity log
     activity_log = []
     for li in parser.query("section[data-activity-log] ol li"):

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,94 @@ 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
-
-    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,
-        }
+    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 []
 
 
 class JsonlEventLog:
@@ -104,7 +116,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",