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

htmlgraph/config.py

@@ -0,0 +1,190 @@
+"""
+HtmlGraph Configuration Management.
+
+This module provides centralized configuration management using Pydantic Settings,
+allowing configuration from environment variables, .env files, and CLI arguments.
+
+IMPORTANT: Database path functions (get_database_path, get_analytics_cache_path)
+are lightweight and have NO dependencies. They can be imported anywhere.
+"""
+
+import os
+from pathlib import Path
+from typing import Any
+
+# =============================================================================
+# LIGHTWEIGHT DATABASE PATH FUNCTIONS (NO DEPENDENCIES)
+# These MUST come before any heavy imports so spawners can use them
+# =============================================================================
+
+# Database filenames (SINGLE SOURCE OF TRUTH)
+DATABASE_FILENAME = "htmlgraph.db"  # Unified event database
+ANALYTICS_CACHE_FILENAME = "index.sqlite"  # Analytics cache (rebuildable)
+
+
+def get_database_path(project_root: Path | str | None = None) -> Path:
+    """
+    Get the unified database path for event tracking.
+
+    This is the SINGLE source of truth for database location.
+    All hooks, agents, and spawners MUST use this function.
+
+    Args:
+        project_root: Optional project root path. If None, uses HTMLGRAPH_PROJECT_ROOT
+                     env var or current working directory.
+
+    Returns:
+        Path to htmlgraph.db (the unified event database)
+    """
+    if project_root is None:
+        project_root = Path(os.environ.get("HTMLGRAPH_PROJECT_ROOT", os.getcwd()))
+    else:
+        project_root = Path(project_root)
+
+    return project_root / ".htmlgraph" / DATABASE_FILENAME
+
+
+def get_analytics_cache_path(project_root: Path | str | None = None) -> Path:
+    """
+    Get the analytics cache database path.
+
+    This is for read-only analytics queries (rebuildable from events).
+    NOT for event tracking - use get_database_path() for that.
+
+    Args:
+        project_root: Optional project root path. If None, uses HTMLGRAPH_PROJECT_ROOT
+                     env var or current working directory.
+
+    Returns:
+        Path to index.sqlite (analytics cache, gitignored)
+    """
+    if project_root is None:
+        project_root = Path(os.environ.get("HTMLGRAPH_PROJECT_ROOT", os.getcwd()))
+    else:
+        project_root = Path(project_root)
+
+    return project_root / ".htmlgraph" / ANALYTICS_CACHE_FILENAME
+
+
+# =============================================================================
+# PYDANTIC CONFIGURATION (Heavy imports below - spawners don't need this)
+# =============================================================================
+
+try:
+    from pydantic_settings import BaseSettings
+
+    _PYDANTIC_AVAILABLE = True
+except ImportError:
+    _PYDANTIC_AVAILABLE = False
+    BaseSettings = object  # type: ignore
+
+
+if _PYDANTIC_AVAILABLE:
+
+    class HtmlGraphConfig(BaseSettings):
+        """Global HtmlGraph configuration using Pydantic Settings.
+
+        Configuration can be provided via:
+        1. Environment variables (prefix: HTMLGRAPH_)
+        2. .env file
+        3. Direct instantiation with parameters
+        4. CLI argument overrides
+        """
+
+        # Core paths
+        graph_dir: Path = Path.home() / ".htmlgraph"
+
+        # Database paths (SINGLE SOURCE OF TRUTH)
+        # All hooks, agents, and spawners MUST use these via get_database_path()
+        database_filename: str = "htmlgraph.db"  # Unified event database
+        analytics_cache_filename: str = "index.sqlite"  # Analytics cache (rebuildable)
+
+        # Feature tracking
+        features_dir: Path | None = None
+        sessions_dir: Path | None = None
+        spikes_dir: Path | None = None
+        tracks_dir: Path | None = None
+        archives_dir: Path | None = None
+
+        # CLI behavior
+        debug: bool = False
+        verbose: bool = False
+        auto_sync: bool = True
+        color_output: bool = True
+
+        # Session management
+        max_sessions: int = 100
+        session_retention_days: int = 30
+        auto_archive_sessions: bool = True
+
+        # Performance
+        max_query_results: int = 1000
+        cache_enabled: bool = True
+        cache_ttl_seconds: int = 3600
+
+        # Logging
+        log_level: str = "INFO"
+        log_file: Path | None = None
+
+        model_config = {
+            "env_prefix": "HTMLGRAPH_",
+            "env_file": ".env",
+            "case_sensitive": False,
+        }
+
+        def __init__(self, **data: Any) -> None:
+            """Initialize config and compute derived paths."""
+            super().__init__(**data)
+            # Compute derived paths if not explicitly set
+            if self.features_dir is None:
+                self.features_dir = self.graph_dir / "features"
+            if self.sessions_dir is None:
+                self.sessions_dir = self.graph_dir / "sessions"
+            if self.spikes_dir is None:
+                self.spikes_dir = self.graph_dir / "spikes"
+            if self.tracks_dir is None:
+                self.tracks_dir = self.graph_dir / "tracks"
+            if self.archives_dir is None:
+                self.archives_dir = self.graph_dir / "archives"
+
+        def ensure_directories(self) -> None:
+            """Create all configured directories if they don't exist."""
+            for directory in [
+                self.graph_dir,
+                self.features_dir,
+                self.sessions_dir,
+                self.spikes_dir,
+                self.tracks_dir,
+                self.archives_dir,
+            ]:
+                if directory:
+                    directory.mkdir(parents=True, exist_ok=True)
+
+        def get_config_dict(self) -> dict[str, Any]:
+            """Get configuration as dictionary."""
+            return {
+                "graph_dir": str(self.graph_dir),
+                "features_dir": str(self.features_dir),
+                "sessions_dir": str(self.sessions_dir),
+                "spikes_dir": str(self.spikes_dir),
+                "tracks_dir": str(self.tracks_dir),
+                "archives_dir": str(self.archives_dir),
+                "debug": self.debug,
+                "verbose": self.verbose,
+                "auto_sync": self.auto_sync,
+                "color_output": self.color_output,
+                "max_sessions": self.max_sessions,
+                "session_retention_days": self.session_retention_days,
+                "auto_archive_sessions": self.auto_archive_sessions,
+                "max_query_results": self.max_query_results,
+                "cache_enabled": self.cache_enabled,
+                "cache_ttl_seconds": self.cache_ttl_seconds,
+                "log_level": self.log_level,
+                "log_file": str(self.log_file) if self.log_file else None,
+            }
+
+    # Global configuration instance
+    config: HtmlGraphConfig = HtmlGraphConfig()
+else:
+    # Pydantic not available - config object won't work but database functions will
+    config = None  # type: ignore

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

@@ -12,7 +12,16 @@ import logging
 from pathlib import Path
 from typing import Any, cast
 
-from htmlgraph.models import ActivityEntry, Chore, Edge, Node, Session, Spike, Step
+from htmlgraph.models import (
+    ActivityEntry,
+    Chore,
+    Edge,
+    Node,
+    Pattern,
+    Session,
+    Spike,
+    Step,
+)
 from htmlgraph.parser import HtmlParser
 
 logger = logging.getLogger(__name__)
@@ -74,6 +83,7 @@ def html_to_node(filepath: Path | str) -> Node:
     model_classes: dict[str, type[Node]] = {
         "spike": Spike,
         "chore": Chore,
+        "pattern": Pattern,
         "node": Node,
     }
 
@@ -385,7 +395,8 @@ def html_to_session(filepath: Path | str) -> Session:
     parser = HtmlParser.from_file(filepath)
 
     # Get article element with session data
-    article = parser.query_one("article[data-type='session']")
+    article_results = parser.query("article[data-type='session']")
+    article = article_results[0] if article_results else None
     if not article:
         raise ValueError(f"No session article found in: {filepath}")
 
@@ -455,7 +466,8 @@ def html_to_session(filepath: Path | str) -> Session:
         data["transcript_git_branch"] = transcript_branch
 
     # Parse title
-    title_el = parser.query_one("h1")
+    title_el_results = parser.query("h1")
+    title_el = title_el_results[0] if title_el_results else None
     if title_el:
         data["title"] = title_el.to_text().strip()
 
@@ -472,24 +484,28 @@ def html_to_session(filepath: Path | str) -> Session:
     data["worked_on"] = worked_on
 
     # Parse continued_from edge
-    continued_link = parser.query_one(
+    continued_link_results = parser.query(
         "nav[data-graph-edges] section[data-edge-type='continued-from'] a"
     )
+    continued_link = continued_link_results[0] if continued_link_results else None
     if continued_link:
         href = continued_link.attrs.get("href") or ""
         data["continued_from"] = href.replace(".html", "")
 
     # Parse handoff context
-    handoff_section = parser.query_one("section[data-handoff]")
+    handoff_section_results = parser.query("section[data-handoff]")
+    handoff_section = handoff_section_results[0] if handoff_section_results else None
     if handoff_section:
-        notes_el = parser.query_one("section[data-handoff] [data-handoff-notes]")
+        notes_el_results = parser.query("section[data-handoff] [data-handoff-notes]")
+        notes_el = notes_el_results[0] if notes_el_results else None
         if notes_el:
             notes_text = notes_el.to_text().strip()
             if notes_text.lower().startswith("notes:"):
                 notes_text = notes_text.split(":", 1)[1].strip()
             data["handoff_notes"] = notes_text
 
-        next_el = parser.query_one("section[data-handoff] [data-recommended-next]")
+        next_el_results = parser.query("section[data-handoff] [data-recommended-next]")
+        next_el = next_el_results[0] if next_el_results else None
         if next_el:
             next_text = next_el.to_text().strip()
             if next_text.lower().startswith("recommended next:"):
@@ -504,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"):
@@ -538,6 +565,88 @@ def html_to_session(filepath: Path | str) -> Session:
     # Activity log in HTML is reversed (newest first), so reverse back
     data["activity_log"] = list(reversed(activity_log))
 
+    # Parse detected patterns from table (if present)
+    detected_patterns = []
+    for tr in parser.query("section[data-detected-patterns] table tbody tr"):
+        # Extract pattern data from table row
+        pattern_type = tr.attrs.get("data-pattern-type", "neutral")
+
+        # Extract sequence from first <td class="sequence">
+        seq_tds = tr.query("td.sequence")
+        seq_td = seq_tds[0] if seq_tds else None
+        sequence_str = seq_td.to_text().strip() if seq_td else ""
+        sequence = [s.strip() for s in sequence_str.split("→")] if sequence_str else []
+
+        # Extract count from third <td>
+        tds = tr.query("td")
+        count_td = tds[2] if len(tds) > 2 else None
+        count_str = count_td.to_text().strip() if count_td else "0"
+        try:
+            count = int(count_str)
+        except (ValueError, TypeError):
+            count = 0
+
+        # Extract timestamps from fourth <td>
+        time_td = tds[3] if len(tds) > 3 else None
+        time_str = time_td.to_text().strip() if time_td else ""
+        times = time_str.split(" / ")
+        first_detected = times[0].strip() if len(times) > 0 else ""
+        last_detected = times[1].strip() if len(times) > 1 else ""
+
+        if sequence:  # Only add if we have a valid sequence
+            detected_patterns.append(
+                {
+                    "sequence": sequence,
+                    "pattern_type": pattern_type,
+                    "detection_count": count,
+                    "first_detected": first_detected,
+                    "last_detected": last_detected,
+                }
+            )
+
+    data["detected_patterns"] = detected_patterns
+
+    # Parse error log from error section (if present)
+    error_log = []
+    for details in parser.query("section[data-error-log] details"):
+        error_data = {
+            "error_type": details.attrs.get("data-error-type", "Unknown"),
+            "message": "",
+            "traceback": None,
+        }
+
+        ts = details.attrs.get("data-ts")
+        if ts:
+            error_data["timestamp"] = datetime.fromisoformat(ts.replace("Z", "+00:00"))
+
+        tool = details.attrs.get("data-tool")
+        if tool:
+            error_data["tool"] = tool
+
+        # Parse summary text (first line of details)
+        summary_el_results = details.query("summary")
+        summary_el = summary_el_results[0] if summary_el_results else None
+        if summary_el:
+            summary_text = summary_el.to_text().strip()
+            # Extract message from "ErrorType: message" format
+            if ": " in summary_text:
+                error_data["message"] = summary_text.split(": ", 1)[1]
+            else:
+                error_data["message"] = summary_text
+
+        # Parse traceback (if present)
+        traceback_el_results = details.query("pre.traceback")
+        traceback_el = traceback_el_results[0] if traceback_el_results else None
+        if traceback_el:
+            error_data["traceback"] = traceback_el.to_text().strip()
+
+        if error_data.get("message") or error_data.get("traceback"):
+            from htmlgraph.models import ErrorEntry
+
+            error_log.append(ErrorEntry(**error_data))
+
+    data["error_log"] = error_log
+
     return Session(**data)
 
 

htmlgraph/cost_analysis/__init__.py

@@ -0,0 +1,5 @@
+"""Cost analysis module for HtmlGraph event tracking and token cost calculation."""
+
+from .analyzer import CostAnalyzer
+
+__all__ = ["CostAnalyzer"]