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

htmlgraph/models.py

@@ -7,7 +7,7 @@ These models provide:
 - Lightweight context generation for AI agents
 """
 
-from datetime import datetime
+from datetime import datetime, timezone
 from enum import Enum
 from pathlib import Path
 from typing import Any, Literal
@@ -15,6 +15,11 @@ from typing import Any, Literal
 from pydantic import BaseModel, Field
 
 
+def utc_now() -> datetime:
+    """Return current time as UTC-aware datetime."""
+    return datetime.now(timezone.utc)
+
+
 class WorkType(str, Enum):
     """
     Classification of work/activity type for events and sessions.
@@ -264,15 +269,15 @@ class Node(BaseModel):
         if edge.relationship not in self.edges:
             self.edges[edge.relationship] = []
         self.edges[edge.relationship].append(edge)
-        self.updated = datetime.now()
+        self.updated = utc_now()
 
     def complete_step(self, index: int, agent: str | None = None) -> bool:
         """Mark a step as completed."""
         if 0 <= index < len(self.steps):
             self.steps[index].completed = True
             self.steps[index].agent = agent
-            self.steps[index].timestamp = datetime.now()
-            self.updated = datetime.now()
+            self.steps[index].timestamp = utc_now()
+            self.updated = utc_now()
             return True
         return False
 
@@ -300,7 +305,7 @@ class Node(BaseModel):
         self.context_tokens_used += tokens_used
         self.context_peak_tokens = max(self.context_peak_tokens, peak_tokens)
         self.context_cost_usd += cost_usd
-        self.updated = datetime.now()
+        self.updated = utc_now()
 
     def context_stats(self) -> dict:
         """
@@ -317,6 +322,24 @@ class Node(BaseModel):
             "session_ids": self.context_sessions,
         }
 
+    def to_dict(self) -> dict:
+        """
+        Convert Node to dictionary format.
+
+        This is a convenience alias for Pydantic's model_dump() method,
+        providing a more discoverable API for serialization.
+
+        Returns:
+            dict: Dictionary representation of the Node with all fields
+
+        Example:
+            >>> feature = sdk.features.create("My Feature").save()
+            >>> data = feature.to_dict()
+            >>> print(data['title'])
+            'My Feature'
+        """
+        return self.model_dump()
+
     def to_html(self, stylesheet_path: str = "../styles.css") -> str:
         """
         Convert node to full HTML document.
@@ -813,9 +836,7 @@ class ContextSnapshot(BaseModel):
     def from_dict(cls, data: dict) -> "ContextSnapshot":
         """Create from dictionary."""
         return cls(
-            timestamp=datetime.fromisoformat(data["ts"])
-            if "ts" in data
-            else datetime.now(),
+            timestamp=datetime.fromisoformat(data["ts"]) if "ts" in data else utc_now(),
             input_tokens=data.get("in", 0),
             output_tokens=data.get("out", 0),
             cache_creation_tokens=data.get("cache_create", 0),
@@ -829,6 +850,48 @@ class ContextSnapshot(BaseModel):
         )
 
 
+class ErrorEntry(BaseModel):
+    """
+    An error record for session error tracking and debugging.
+
+    Stored inline within Session nodes for error analysis and debugging.
+    """
+
+    timestamp: datetime = Field(default_factory=datetime.now)
+    error_type: str  # Exception class name (ValueError, FileNotFoundError, etc.)
+    message: str  # Error message
+    traceback: str | None = None  # Full traceback for debugging
+    tool: str | None = None  # Tool that caused the error (Edit, Bash, etc.)
+    context: str | None = None  # Additional context information
+    session_id: str | None = None  # Session ID for cross-referencing
+    locals_dump: str | None = None  # JSON-serialized local variables at error point
+    stack_frames: list[dict[str, Any]] | None = (
+        None  # Structured stack frame information
+    )
+    command_args: dict[str, Any] | None = None  # Command arguments being executed
+    display_level: str = "minimal"  # Display level: minimal, verbose, or debug
+
+    def to_html(self) -> str:
+        """Convert error to HTML details element."""
+        attrs = [
+            f'data-ts="{self.timestamp.isoformat()}"',
+            f'data-error-type="{self.error_type}"',
+        ]
+        if self.tool:
+            attrs.append(f'data-tool="{self.tool}"')
+
+        summary = f"<span class='error-type'>{self.error_type}</span>: {self.message}"
+        details = ""
+        if self.traceback:
+            details = f"<pre class='traceback'>{self.traceback}</pre>"
+
+        return f"<details class='error-item' {' '.join(attrs)}><summary>{summary}</summary>{details}</details>"
+
+    def to_context(self) -> str:
+        """Lightweight context for AI agents."""
+        return f"[{self.timestamp.strftime('%H:%M:%S')}] ERROR {self.error_type}: {self.message}"
+
+
 class ActivityEntry(BaseModel):
     """
     A lightweight activity log entry for high-frequency events.
@@ -907,10 +970,18 @@ class Session(BaseModel):
     worked_on: list[str] = Field(default_factory=list)  # Feature IDs
     continued_from: str | None = None  # Previous session ID
 
-    # Handoff context
+    # Parent session context (for nested Task() calls)
+    parent_session: str | None = None  # Parent session ID
+    parent_activity: str | None = None  # Parent activity ID
+    nesting_depth: int = 0  # Depth of nesting (0 = top-level)
+
+    # Handoff context (Phase 2 Feature 3: Cross-Session Continuity)
     handoff_notes: str | None = None
     recommended_next: str | None = None
     blockers: list[str] = Field(default_factory=list)
+    recommended_context: list[str] = Field(
+        default_factory=list
+    )  # File paths to keep context for
 
     # High-frequency activity log
     activity_log: list[ActivityEntry] = Field(default_factory=list)
@@ -937,20 +1008,67 @@ class Session(BaseModel):
     transcript_synced_at: datetime | None = None  # Last sync timestamp
     transcript_git_branch: str | None = None  # Git branch from transcript
 
+    # Pattern detection (inline storage to avoid file bloat)
+    detected_patterns: list[dict[str, Any]] = Field(default_factory=list)
+    """
+    Patterns detected during this session.
+
+    Format:
+    {
+        "sequence": ["Bash", "Read", "Edit"],
+        "pattern_type": "neutral",  # or "optimal", "anti_pattern"
+        "detection_count": 3,
+        "first_detected": "2026-01-02T10:00:00",
+        "last_detected": "2026-01-02T10:30:00"
+    }
+    """
+
+    # Error handling (Phase 1B)
+    error_log: list[ErrorEntry] = Field(default_factory=list)
+    """Error records for this session with full tracebacks for debugging."""
+
     def add_activity(self, entry: ActivityEntry) -> None:
         """Add an activity entry to the log."""
         self.activity_log.append(entry)
         self.event_count += 1
-        self.last_activity = datetime.now()
+        self.last_activity = utc_now()
 
         # Track features worked on
         if entry.feature_id and entry.feature_id not in self.worked_on:
             self.worked_on.append(entry.feature_id)
 
+    def add_error(
+        self,
+        error_type: str,
+        message: str,
+        traceback: str | None = None,
+        tool: str | None = None,
+        context: str | None = None,
+    ) -> None:
+        """
+        Add an error entry to the error log.
+
+        Args:
+            error_type: Exception class name (ValueError, FileNotFoundError, etc.)
+            message: Error message
+            traceback: Full traceback for debugging
+            tool: Tool that caused the error (Edit, Bash, etc.)
+            context: Additional context information
+        """
+        error = ErrorEntry(
+            error_type=error_type,
+            message=message,
+            traceback=traceback,
+            tool=tool,
+            context=context,
+            session_id=self.id,
+        )
+        self.error_log.append(error)
+
     def end(self) -> None:
         """Mark session as ended."""
         self.status = "ended"
-        self.ended_at = datetime.now()
+        self.ended_at = utc_now()
 
     def record_context(
         self, snapshot: ContextSnapshot, sample_interval: int = 10
@@ -1267,7 +1385,12 @@ class Session(BaseModel):
 
         # Build handoff HTML
         handoff_html = ""
-        if self.handoff_notes or self.recommended_next or self.blockers:
+        if (
+            self.handoff_notes
+            or self.recommended_next
+            or self.blockers
+            or self.recommended_context
+        ):
             handoff_section = """
         <section data-handoff>
             <h3>Handoff Context</h3>"""
@@ -1290,6 +1413,18 @@ class Session(BaseModel):
                 </ul>
             </div>"""
 
+            if self.recommended_context:
+                context_items = "\n                ".join(
+                    f"<li>{file_path}</li>" for file_path in self.recommended_context
+                )
+                handoff_section += f"""
+            <div data-recommended-context>
+                <strong>Recommended Context:</strong>
+                <ul>
+                    {context_items}
+                </ul>
+            </div>"""
+
             handoff_section += "\n        </section>"
             handoff_html = handoff_section
 
@@ -1324,6 +1459,14 @@ class Session(BaseModel):
             if self.primary_work_type
             else ""
         )
+        # Parent session attributes
+        parent_session_attrs = ""
+        if self.parent_session:
+            parent_session_attrs += f' data-parent-session="{self.parent_session}"'
+        if self.parent_activity:
+            parent_session_attrs += f' data-parent-activity="{self.parent_activity}"'
+        if self.nesting_depth > 0:
+            parent_session_attrs += f' data-nesting-depth="{self.nesting_depth}"'
 
         # Serialize work_breakdown as JSON if present
         import json
@@ -1378,6 +1521,62 @@ class Session(BaseModel):
             </dl>
         </section>"""
 
+        # Build detected patterns section
+        patterns_html = ""
+        if self.detected_patterns:
+            patterns_html = f"""
+        <section data-detected-patterns>
+            <h3>Detected Patterns ({len(self.detected_patterns)})</h3>
+            <table class="patterns-table">
+                <thead>
+                    <tr>
+                        <th>Sequence</th>
+                        <th>Type</th>
+                        <th>Count</th>
+                        <th>First/Last Detected</th>
+                    </tr>
+                </thead>
+                <tbody>"""
+
+            for pattern in self.detected_patterns:
+                seq_str = " → ".join(pattern.get("sequence", []))
+                pattern_type = pattern.get("pattern_type", "neutral")
+                count = pattern.get("detection_count", 0)
+                first = pattern.get("first_detected", "")
+                last = pattern.get("last_detected", "")
+
+                patterns_html += f"""
+                    <tr data-pattern-type="{pattern_type}">
+                        <td class="sequence">{seq_str}</td>
+                        <td><span class="badge pattern-{pattern_type}">{pattern_type}</span></td>
+                        <td>{count}</td>
+                        <td>{first} / {last}</td>
+                    </tr>"""
+
+            patterns_html += """
+                </tbody>
+            </table>
+        </section>"""
+
+        # Build error log section
+        error_html = ""
+        if self.error_log:
+            error_items = "\n                ".join(
+                error.to_html() for error in self.error_log
+            )
+            error_html = f"""
+        <section data-error-log>
+            <h3>Errors ({len(self.error_log)})</h3>
+            <div class="error-log">
+                {error_items}
+            </div>
+            <style>
+                .error-item {{ margin: 10px 0; padding: 10px; border-left: 3px solid #ff6b6b; }}
+                .error-type {{ font-weight: bold; color: #ff6b6b; }}
+                .traceback {{ background: #f5f5f5; padding: 10px; overflow-x: auto; font-size: 0.9em; margin-top: 5px; }}
+            </style>
+        </section>"""
+
         title = self.title or f"Session {self.id}"
 
         return f'''<!DOCTYPE html>
@@ -1396,7 +1595,7 @@ class Session(BaseModel):
              data-agent="{self.agent}"
              data-started-at="{self.started_at.isoformat()}"
              data-last-activity="{self.last_activity.isoformat()}"
-             data-event-count="{self.event_count}"{subagent_attr}{commit_attr}{ended_attr}{primary_work_type_attr}{work_breakdown_attr}{context_attrs}{transcript_attrs}>
+             data-event-count="{self.event_count}"{subagent_attr}{commit_attr}{ended_attr}{primary_work_type_attr}{work_breakdown_attr}{context_attrs}{transcript_attrs}{parent_session_attrs}>
 
         <header>
             <h1>{title}</h1>
@@ -1406,7 +1605,7 @@ class Session(BaseModel):
                 <span class="badge">{self.event_count} events</span>
             </div>
         </header>
-{edges_html}{handoff_html}{context_html}{activity_html}
+{edges_html}{handoff_html}{context_html}{error_html}{patterns_html}{activity_html}
     </article>
 </body>
 </html>
@@ -2058,16 +2257,16 @@ class Todo(BaseModel):
     def start(self) -> "Todo":
         """Mark todo as in progress."""
         self.status = "in_progress"
-        self.started_at = datetime.now()
-        self.updated = datetime.now()
+        self.started_at = utc_now()
+        self.updated = utc_now()
         return self
 
     def complete(self, agent: str | None = None) -> "Todo":
         """Mark todo as completed."""
         self.status = "completed"
-        self.completed_at = datetime.now()
+        self.completed_at = utc_now()
         self.completed_by = agent
-        self.updated = datetime.now()
+        self.updated = utc_now()
 
         # Calculate duration if started
         if self.started_at:

htmlgraph/operations/README.md

@@ -0,0 +1,62 @@
+# HtmlGraph Operations Layer
+
+This module defines a shared, backend operations layer for HtmlGraph. The CLI and SDK
+should call these operations rather than duplicating logic. The operations layer is
+pure Python, stateless, and returns structured data instead of printing.
+
+## Design Principles
+
+- Stateless: all inputs passed explicitly; no global CLI state.
+- Typed: full type hints, dataclasses for results.
+- Structured results: return data, warnings, and metadata; no printing.
+- Exceptions for errors: no sys.exit.
+- Path-first: accept Path objects for filesystem inputs.
+- Reusable: callable from CLI, SDK, and tests.
+
+## Module Structure
+
+- `operations/server.py`   Server startup and lifecycle helpers
+- `operations/hooks.py`    Git hook installation and configuration
+- `operations/events.py`   Event export, index rebuild, event queries
+- `operations/analytics.py` Analytics summaries and report generation
+
+## Example Signature
+
+```python
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any
+
+@dataclass
+class ServerHandle:
+    url: str
+    port: int
+    host: str
+
+@dataclass
+class ServerStartResult:
+    handle: ServerHandle
+    warnings: list[str]
+    config_used: dict[str, Any]
+
+class ServerStartError(RuntimeError):
+    pass
+
+
+def start_server(
+    *,
+    port: int,
+    graph_dir: Path,
+    host: str = "localhost",
+    watch: bool = True,
+    auto_port: bool = False,
+) -> ServerStartResult:
+    """Start HtmlGraph server with validated config."""
+    raise NotImplementedError
+```
+
+## Conventions
+
+- Functions should avoid any CLI-specific formatting.
+- Results should be serializable for JSON output.
+- Keep modules focused on a single domain (server, hooks, events, analytics).

htmlgraph/operations/__init__.py

@@ -0,0 +1,79 @@
+"""Shared operations layer for HtmlGraph CLI and SDK."""
+
+from .analytics import (
+    AnalyticsProjectResult,
+    AnalyticsSessionResult,
+    analyze_project,
+    analyze_session,
+)
+from .events import (
+    EventExportResult,
+    EventQueryResult,
+    EventRebuildResult,
+    EventStats,
+    export_sessions,
+    get_event_stats,
+    query_events,
+    rebuild_index,
+)
+from .hooks import (
+    HookInstallResult,
+    HookListResult,
+    HookValidationResult,
+    install_hooks,
+    list_hooks,
+    validate_hook_config,
+)
+from .initialization import (
+    create_analytics_index,
+    create_config_files,
+    create_database,
+    create_directory_structure,
+    initialize_htmlgraph,
+    install_git_hooks,
+    update_gitignore,
+    validate_directory,
+)
+from .server import (
+    ServerHandle,
+    ServerStartResult,
+    ServerStatus,
+    get_server_status,
+    start_server,
+    stop_server,
+)
+
+__all__ = [
+    "AnalyticsProjectResult",
+    "AnalyticsSessionResult",
+    "analyze_project",
+    "analyze_session",
+    "EventExportResult",
+    "EventQueryResult",
+    "EventRebuildResult",
+    "EventStats",
+    "export_sessions",
+    "get_event_stats",
+    "query_events",
+    "rebuild_index",
+    "HookInstallResult",
+    "HookListResult",
+    "HookValidationResult",
+    "install_hooks",
+    "list_hooks",
+    "validate_hook_config",
+    "ServerHandle",
+    "ServerStartResult",
+    "ServerStatus",
+    "start_server",
+    "stop_server",
+    "get_server_status",
+    "initialize_htmlgraph",
+    "validate_directory",
+    "create_directory_structure",
+    "create_database",
+    "create_analytics_index",
+    "create_config_files",
+    "update_gitignore",
+    "install_git_hooks",
+]