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

htmlgraph/.htmlgraph/.session-warning-state.json

@@ -0,0 +1,6 @@
+{
+  "dismissed_at": null,
+  "dismissed_by": null,
+  "session_id": null,
+  "show_count": 59
+}

htmlgraph/.htmlgraph/agents.json

@@ -0,0 +1,72 @@
+{
+  "version": "1.0",
+  "updated": "2026-01-11T04:13:54.354401",
+  "agents": {
+    "claude": {
+      "id": "claude",
+      "name": "Claude",
+      "capabilities": [
+        "python",
+        "javascript",
+        "typescript",
+        "html",
+        "css",
+        "code-review",
+        "testing",
+        "documentation",
+        "debugging",
+        "refactoring",
+        "architecture",
+        "api-design"
+      ],
+      "max_parallel_tasks": 3,
+      "preferred_complexity": [
+        "low",
+        "medium",
+        "high",
+        "very-high"
+      ],
+      "active": true,
+      "metadata": {}
+    },
+    "gemini": {
+      "id": "gemini",
+      "name": "Gemini",
+      "capabilities": [
+        "python",
+        "data-analysis",
+        "documentation",
+        "testing",
+        "code-review",
+        "javascript"
+      ],
+      "max_parallel_tasks": 2,
+      "preferred_complexity": [
+        "low",
+        "medium",
+        "high"
+      ],
+      "active": true,
+      "metadata": {}
+    },
+    "codex": {
+      "id": "codex",
+      "name": "Codex",
+      "capabilities": [
+        "python",
+        "javascript",
+        "debugging",
+        "testing",
+        "code-generation",
+        "documentation"
+      ],
+      "max_parallel_tasks": 2,
+      "preferred_complexity": [
+        "low",
+        "medium"
+      ],
+      "active": true,
+      "metadata": {}
+    }
+  }
+}

htmlgraph/__init__.py

@@ -5,12 +5,43 @@ A lightweight graph database framework using HTML files as nodes,
 hyperlinks as edges, and CSS selectors as the query language.
 """
 
+import logging
+
+from rich.console import Console
+from rich.logging import RichHandler
+
+# Configure Rich logging for entire SDK
+# CRITICAL: Use stderr=True to prevent pollution of stdout (hooks output JSON to stdout)
+logging.basicConfig(
+    handlers=[
+        RichHandler(
+            console=Console(stderr=True),
+            show_time=True,
+            show_level=True,
+            rich_tracebacks=True,
+        )
+    ],
+    level=logging.INFO,
+    format="%(message)s",
+    datefmt="[%X]",
+)
+
+# SDK now lives in sdk/core.py - clean import from sdk package
 from htmlgraph.agent_detection import detect_agent_name, get_agent_display_name
 from htmlgraph.agents import AgentInterface
 from htmlgraph.analytics import Analytics, DependencyAnalytics
+from htmlgraph.atomic_ops import (
+    AtomicFileWriter,
+    DirectoryLocker,
+    atomic_rename,
+    cleanup_orphaned_temp_files,
+    safe_temp_file,
+    validate_atomic_write,
+)
 from htmlgraph.builders import BaseBuilder, FeatureBuilder, SpikeBuilder
 from htmlgraph.collections import BaseCollection, FeatureCollection, SpikeCollection
 from htmlgraph.context_analytics import ContextAnalytics, ContextUsage
+from htmlgraph.decorators import RetryError, retry, retry_async
 from htmlgraph.edge_index import EdgeIndex, EdgeRef
 from htmlgraph.exceptions import (
     ClaimConflictError,
@@ -55,9 +86,12 @@ from htmlgraph.orchestration import (
 from htmlgraph.orchestrator_mode import OrchestratorMode, OrchestratorModeManager
 from htmlgraph.parallel import AggregateResult, ParallelAnalysis, ParallelWorkflow
 from htmlgraph.query_builder import Condition, Operator, QueryBuilder
+from htmlgraph.reflection import ComputationalReflection, get_reflection_context
+from htmlgraph.repo_hash import RepoHash
 from htmlgraph.sdk import SDK
 from htmlgraph.server import serve
 from htmlgraph.session_manager import SessionManager
+from htmlgraph.session_registry import SessionRegistry
 from htmlgraph.types import (
     ActiveWorkItem,
     AggregateResultsDict,
@@ -84,7 +118,7 @@ from htmlgraph.types import (
 )
 from htmlgraph.work_type_utils import infer_work_type, infer_work_type_from_id
 
-__version__ = "0.20.1"
+__version__ = "0.27.5"
 __all__ = [
     # Exceptions
     "HtmlGraphError",
@@ -92,6 +126,10 @@ __all__ = [
     "SessionNotFoundError",
     "ClaimConflictError",
     "ValidationError",
+    "RetryError",
+    # Decorators
+    "retry",
+    "retry_async",
     # Core models
     "Node",
     "Edge",
@@ -122,6 +160,8 @@ __all__ = [
     "find_all",
     "AgentInterface",
     "SessionManager",
+    "SessionRegistry",
+    "RepoHash",
     "SDK",
     "Analytics",  # Phase 2: Work Type Analytics
     "DependencyAnalytics",  # Advanced dependency-aware analytics
@@ -178,6 +218,9 @@ __all__ = [
     # Active Learning Persistence
     "LearningPersistence",
     "auto_persist_on_session_end",
+    # Computational Reflection (pre-computed context injection)
+    "ComputationalReflection",
+    "get_reflection_context",
     # Orchestrator Mode Management
     "OrchestratorMode",
     "OrchestratorModeManager",
@@ -186,4 +229,11 @@ __all__ = [
     "get_results_by_task_id",
     "parallel_delegate",
     "generate_task_id",
+    # Atomic file operations (Phase 1.3: Session File Tracking)
+    "AtomicFileWriter",
+    "DirectoryLocker",
+    "atomic_rename",
+    "cleanup_orphaned_temp_files",
+    "safe_temp_file",
+    "validate_atomic_write",
 ]

htmlgraph/__init__.pyi

@@ -0,0 +1,123 @@
+"""
+Type stub for htmlgraph package.
+
+This stub provides type information for mypy when the SDK class
+is loaded dynamically via importlib at runtime.
+"""
+
+from htmlgraph.agent_detection import detect_agent_name as detect_agent_name
+from htmlgraph.agent_detection import get_agent_display_name as get_agent_display_name
+from htmlgraph.agents import AgentInterface as AgentInterface
+from htmlgraph.analytics import Analytics as Analytics
+
+# Analytics
+from htmlgraph.analytics import DependencyAnalytics as DependencyAnalytics
+from htmlgraph.atomic_ops import AtomicFileWriter as AtomicFileWriter
+from htmlgraph.atomic_ops import DirectoryLocker as DirectoryLocker
+from htmlgraph.atomic_ops import atomic_rename as atomic_rename
+from htmlgraph.atomic_ops import (
+    cleanup_orphaned_temp_files as cleanup_orphaned_temp_files,
+)
+from htmlgraph.atomic_ops import safe_temp_file as safe_temp_file
+from htmlgraph.atomic_ops import validate_atomic_write as validate_atomic_write
+from htmlgraph.builders import BaseBuilder as BaseBuilder
+from htmlgraph.builders import FeatureBuilder as FeatureBuilder
+from htmlgraph.builders import SpikeBuilder as SpikeBuilder
+from htmlgraph.collections import BaseCollection as BaseCollection
+
+# Collections
+from htmlgraph.collections import FeatureCollection as FeatureCollection
+from htmlgraph.collections import SpikeCollection as SpikeCollection
+from htmlgraph.context_analytics import ContextAnalytics as ContextAnalytics
+from htmlgraph.context_analytics import ContextUsage as ContextUsage
+from htmlgraph.decorators import RetryError as RetryError
+from htmlgraph.decorators import retry as retry
+from htmlgraph.decorators import retry_async as retry_async
+from htmlgraph.edge_index import EdgeIndex as EdgeIndex
+from htmlgraph.edge_index import EdgeRef as EdgeRef
+from htmlgraph.exceptions import ClaimConflictError as ClaimConflictError
+from htmlgraph.exceptions import HtmlGraphError as HtmlGraphError
+from htmlgraph.exceptions import NodeNotFoundError as NodeNotFoundError
+from htmlgraph.exceptions import SessionNotFoundError as SessionNotFoundError
+from htmlgraph.exceptions import ValidationError as ValidationError
+from htmlgraph.find_api import FindAPI as FindAPI
+from htmlgraph.find_api import find as find
+from htmlgraph.find_api import find_all as find_all
+from htmlgraph.graph import CompiledQuery as CompiledQuery
+from htmlgraph.graph import HtmlGraph as HtmlGraph
+from htmlgraph.ids import generate_hierarchical_id as generate_hierarchical_id
+from htmlgraph.ids import generate_id as generate_id
+from htmlgraph.ids import is_legacy_id as is_legacy_id
+from htmlgraph.ids import is_valid_id as is_valid_id
+from htmlgraph.ids import parse_id as parse_id
+from htmlgraph.learning import LearningPersistence as LearningPersistence
+from htmlgraph.learning import (
+    auto_persist_on_session_end as auto_persist_on_session_end,
+)
+from htmlgraph.models import ActivityEntry as ActivityEntry
+from htmlgraph.models import AggregatedMetric as AggregatedMetric
+from htmlgraph.models import Chore as Chore
+from htmlgraph.models import ContextSnapshot as ContextSnapshot
+from htmlgraph.models import Edge as Edge
+from htmlgraph.models import Graph as Graph
+from htmlgraph.models import MaintenanceType as MaintenanceType
+from htmlgraph.models import Node as Node
+from htmlgraph.models import Pattern as Pattern
+from htmlgraph.models import Session as Session
+from htmlgraph.models import SessionInsight as SessionInsight
+from htmlgraph.models import Spike as Spike
+from htmlgraph.models import SpikeType as SpikeType
+from htmlgraph.models import Step as Step
+from htmlgraph.models import WorkType as WorkType
+from htmlgraph.orchestration import delegate_with_id as delegate_with_id
+from htmlgraph.orchestration import generate_task_id as generate_task_id
+from htmlgraph.orchestration import get_results_by_task_id as get_results_by_task_id
+from htmlgraph.orchestration import parallel_delegate as parallel_delegate
+from htmlgraph.orchestrator_mode import OrchestratorMode as OrchestratorMode
+from htmlgraph.orchestrator_mode import (
+    OrchestratorModeManager as OrchestratorModeManager,
+)
+from htmlgraph.parallel import AggregateResult as AggregateResult
+from htmlgraph.parallel import ParallelAnalysis as ParallelAnalysis
+from htmlgraph.parallel import ParallelWorkflow as ParallelWorkflow
+from htmlgraph.query_builder import Condition as Condition
+from htmlgraph.query_builder import Operator as Operator
+from htmlgraph.query_builder import QueryBuilder as QueryBuilder
+from htmlgraph.reflection import ComputationalReflection as ComputationalReflection
+from htmlgraph.reflection import get_reflection_context as get_reflection_context
+from htmlgraph.repo_hash import RepoHash as RepoHash
+from htmlgraph.sdk.core import SDK as SDK
+from htmlgraph.server import serve as serve
+from htmlgraph.session_manager import SessionManager as SessionManager
+from htmlgraph.session_registry import SessionRegistry as SessionRegistry
+from htmlgraph.types import ActiveWorkItem as ActiveWorkItem
+from htmlgraph.types import AggregateResultsDict as AggregateResultsDict
+from htmlgraph.types import BottleneckDict as BottleneckDict
+from htmlgraph.types import FeatureSummary as FeatureSummary
+from htmlgraph.types import HighRiskTask as HighRiskTask
+from htmlgraph.types import ImpactAnalysisDict as ImpactAnalysisDict
+from htmlgraph.types import OrchestrationResult as OrchestrationResult
+from htmlgraph.types import ParallelGuidelines as ParallelGuidelines
+from htmlgraph.types import ParallelPlanResult as ParallelPlanResult
+from htmlgraph.types import ParallelWorkInfo as ParallelWorkInfo
+from htmlgraph.types import PlanningContext as PlanningContext
+from htmlgraph.types import ProjectStatus as ProjectStatus
+from htmlgraph.types import RiskAssessmentDict as RiskAssessmentDict
+from htmlgraph.types import SessionAnalytics as SessionAnalytics
+from htmlgraph.types import SessionStartInfo as SessionStartInfo
+from htmlgraph.types import SessionSummary as SessionSummary
+from htmlgraph.types import SmartPlanResult as SmartPlanResult
+from htmlgraph.types import SubagentPrompt as SubagentPrompt
+from htmlgraph.types import TaskPrompt as TaskPrompt
+from htmlgraph.types import TrackCreationResult as TrackCreationResult
+from htmlgraph.types import WorkQueueItem as WorkQueueItem
+from htmlgraph.types import WorkRecommendation as WorkRecommendation
+from htmlgraph.work_type_utils import infer_work_type as infer_work_type
+from htmlgraph.work_type_utils import infer_work_type_from_id as infer_work_type_from_id
+
+__version__: str
+
+# SDK is imported from htmlgraph.sdk.core (see import above)
+# Re-exported here for backward compatibility
+
+__all__: list[str]

htmlgraph/agent_detection.py

@@ -14,34 +14,48 @@ def detect_agent_name() -> str:
     Detect the current agent/interface name based on environment.
 
     Returns:
-        Agent name (e.g., "claude", "gemini", "cli")
+        Agent name (e.g., "claude-code", "gemini", "cli")
 
     Detection order:
         1. HTMLGRAPH_AGENT environment variable (explicit override)
-        2. Claude Code detection (CLAUDE_CODE_VERSION, parent process)
-        3. Gemini detection (GEMINI environment markers)
-        4. Fall back to "cli"
+        2. HTMLGRAPH_PARENT_AGENT (set by hooks for session context)
+        3. Gemini detection (GEMINI environment markers) - checked before Claude to allow override
+        4. Claude Code detection (CLAUDECODE env var, parent process)
+        5. Fall back to "cli" only if no AI agent detected
     """
     # 1. Explicit override
     explicit = os.environ.get("HTMLGRAPH_AGENT")
     if explicit:
         return explicit.strip()
 
-    # 2. Claude Code detection
-    if _is_claude_code():
-        return "claude"
+    # 2. Parent agent context (set by HtmlGraph hooks)
+    parent_agent = os.environ.get("HTMLGRAPH_PARENT_AGENT")
+    if parent_agent:
+        return parent_agent.strip()
 
-    # 3. Gemini detection
+    # 3. Gemini detection (checked before Claude to allow explicit override)
     if _is_gemini():
         return "gemini"
 
-    # 4. Default to CLI
+    # 4. Claude Code detection
+    if _is_claude_code():
+        return "claude-code"
+
+    # 5. Default to CLI only if no AI agent detected
     return "cli"
 
 
 def _is_claude_code() -> bool:
     """Check if running in Claude Code environment."""
     # Check for Claude Code environment variables
+    # CLAUDECODE=1 is set by Claude Code CLI
+    if os.environ.get("CLAUDECODE"):
+        return True
+
+    # CLAUDE_CODE_ENTRYPOINT indicates the entry point (cli, api, etc.)
+    if os.environ.get("CLAUDE_CODE_ENTRYPOINT"):
+        return True
+
     if os.environ.get("CLAUDE_CODE_VERSION"):
         return True
 
@@ -100,12 +114,14 @@ def get_agent_display_name(agent: str) -> str:
     """
     display_names = {
         "claude": "Claude",
-        "claude-code": "Claude",
+        "claude-code": "Claude Code",
         "gemini": "Gemini",
         "cli": "CLI",
         "haiku": "Haiku",
         "opus": "Opus",
         "sonnet": "Sonnet",
+        "claude-opus-4-5-20251101": "Claude Opus 4.5",
+        "claude-sonnet-4-20250514": "Claude Sonnet 4",
     }
 
     return display_names.get(agent.lower(), agent.title())

htmlgraph/agent_registry.py

@@ -1,3 +1,5 @@
+from __future__ import annotations
+
 """
 Agent Registry - Manages agent capabilities and routing.
 
@@ -7,7 +9,6 @@ Provides:
 - Capability matching for task routing
 """
 
-from __future__ import annotations
 
 import json
 from dataclasses import dataclass, field

htmlgraph/analytics/__init__.py

@@ -1,13 +1,20 @@
 """
 Analytics modules for HtmlGraph.
 
-Provides work type analysis, dependency analytics, and CLI analytics.
+Provides work type analysis, dependency analytics, cross-session analytics, CLI analytics,
+and cost attribution analysis for OTEL ROI.
 """
 
+from htmlgraph.analytics.cost_analyzer import CostAnalyzer
+from htmlgraph.analytics.cost_reporter import CostReporter
+from htmlgraph.analytics.cross_session import CrossSessionAnalytics
 from htmlgraph.analytics.dependency import DependencyAnalytics
 from htmlgraph.analytics.work_type import Analytics
 
 __all__ = [
     "Analytics",
     "DependencyAnalytics",
+    "CrossSessionAnalytics",
+    "CostAnalyzer",
+    "CostReporter",
 ]

htmlgraph/analytics/cli.py

@@ -5,6 +5,8 @@ This module provides the `htmlgraph analytics` command for analyzing work patter
 """
 
 import argparse
+from collections.abc import Iterator
+from contextlib import AbstractContextManager, nullcontext
 from pathlib import Path
 
 from rich import box
@@ -19,6 +21,7 @@ from htmlgraph.converter import html_to_session
 def cmd_analytics(args: argparse.Namespace) -> int:
     """Display work type analytics with beautiful rich formatting."""
     console = Console()
+    quiet = getattr(args, "quiet", False)
 
     try:
         sdk = SDK(agent=args.agent or "cli")
@@ -46,21 +49,67 @@ def cmd_analytics(args: argparse.Namespace) -> int:
     # Determine scope
     if args.session_id:
         # Single session analysis
-        _display_session_analytics(console, sdk, args.session_id, args.graph_dir)
+        _display_session_analytics(
+            console, sdk, args.session_id, args.graph_dir, quiet=quiet
+        )
     elif args.recent:
         # Recent sessions
         _display_recent_sessions(
-            console, sdk, session_files[: args.recent], args.graph_dir
+            console, sdk, session_files[: args.recent], args.graph_dir, quiet=quiet
         )
     else:
         # Project-wide overview
-        _display_project_analytics(console, sdk, session_files, args.graph_dir)
+        _display_project_analytics(
+            console, sdk, session_files, args.graph_dir, quiet=quiet
+        )
 
     return 0
 
 
+def _status_context(
+    console: Console, quiet: bool, message: str
+) -> AbstractContextManager[object]:
+    if quiet:
+        return nullcontext()
+    return console.status(message)
+
+
+def _iter_with_progress(
+    console: Console, quiet: bool, items: list[Path], description: str
+) -> Iterator[Path]:
+    if quiet:
+        for item in items:
+            yield item
+        return
+    try:
+        from rich.progress import (
+            BarColumn,
+            Progress,
+            SpinnerColumn,
+            TextColumn,
+            TimeElapsedColumn,
+        )
+    except Exception:
+        for item in items:
+            yield item
+        return
+
+    with Progress(
+        SpinnerColumn(),
+        TextColumn("{task.description}"),
+        BarColumn(),
+        TimeElapsedColumn(),
+        console=console,
+        transient=True,
+    ) as progress:
+        task_id = progress.add_task(description, total=len(items))
+        for item in items:
+            yield item
+            progress.advance(task_id)
+
+
 def _display_session_analytics(
-    console: Console, sdk: SDK, session_id: str, graph_dir: str
+    console: Console, sdk: "SDK", session_id: str, graph_dir: str, quiet: bool
 ) -> None:
     """Display analytics for a single session."""
     from htmlgraph.converter import html_to_session
@@ -72,19 +121,23 @@ def _display_session_analytics(
         return
 
     try:
-        session = html_to_session(session_path)
+        with _status_context(console, quiet, "Loading session data..."):
+            session = html_to_session(session_path)
     except Exception as e:
         console.print(f"[red]Error loading session: {e}[/red]")
         return
 
     # Get analytics
-    dist = sdk.analytics.work_type_distribution(session_id=session_id)
-    ratio = sdk.analytics.spike_to_feature_ratio(session_id=session_id)
-    burden = sdk.analytics.maintenance_burden(session_id=session_id)
-    primary = sdk.analytics.calculate_session_primary_work_type(session_id)
-    breakdown = sdk.analytics.calculate_session_work_breakdown(session_id)
-    total_events = sum(breakdown.values()) if breakdown else session.event_count
-    transition_metrics = sdk.analytics.transition_time_metrics(session_id=session_id)
+    with _status_context(console, quiet, "Computing session analytics..."):
+        dist = sdk.analytics.work_type_distribution(session_id=session_id)
+        ratio = sdk.analytics.spike_to_feature_ratio(session_id=session_id)
+        burden = sdk.analytics.maintenance_burden(session_id=session_id)
+        primary = sdk.analytics.calculate_session_primary_work_type(session_id)
+        breakdown = sdk.analytics.calculate_session_work_breakdown(session_id)
+        total_events = sum(breakdown.values()) if breakdown else session.event_count
+        transition_metrics = sdk.analytics.transition_time_metrics(
+            session_id=session_id
+        )
 
     # Header panel
     header = Panel(
@@ -167,7 +220,11 @@ def _display_session_analytics(
 
 
 def _display_recent_sessions(
-    console: Console, sdk: SDK, session_files: list[Path], graph_dir: str
+    console: Console,
+    sdk: "SDK",
+    session_files: list[Path],
+    graph_dir: str,
+    quiet: bool,
 ) -> None:
     """Display analytics for recent sessions."""
     console.print(
@@ -188,7 +245,9 @@ def _display_recent_sessions(
     table.add_column("Primary Type", style="yellow")
     table.add_column("Spike Ratio", justify="right")
 
-    for session_path in session_files:
+    for session_path in _iter_with_progress(
+        console, quiet, session_files, "Processing sessions"
+    ):
         try:
             session = html_to_session(session_path)
             session_id = session.id
@@ -226,7 +285,11 @@ def _display_recent_sessions(
 
 
 def _display_project_analytics(
-    console: Console, sdk: SDK, session_files: list[Path], graph_dir: str
+    console: Console,
+    sdk: "SDK",
+    session_files: list[Path],
+    graph_dir: str,
+    quiet: bool,
 ) -> None:
     """Display project-wide analytics."""
     console.print(
@@ -240,10 +303,11 @@ def _display_project_analytics(
     console.print()
 
     # Get project-wide metrics
-    all_dist = sdk.analytics.work_type_distribution()
-    all_ratio = sdk.analytics.spike_to_feature_ratio()
-    all_burden = sdk.analytics.maintenance_burden()
-    all_transition = sdk.analytics.transition_time_metrics()
+    with _status_context(console, quiet, "Computing project analytics..."):
+        all_dist = sdk.analytics.work_type_distribution()
+        all_ratio = sdk.analytics.spike_to_feature_ratio()
+        all_burden = sdk.analytics.maintenance_burden()
+        all_transition = sdk.analytics.transition_time_metrics()
 
     # Work distribution table
     if all_dist:
@@ -341,7 +405,9 @@ def _display_project_analytics(
     console.print("[bold]Recent Sessions:[/bold]")
     recent_files = session_files[:5]
 
-    for session_path in recent_files:
+    for session_path in _iter_with_progress(
+        console, quiet, recent_files, "Loading recent sessions"
+    ):
         try:
             session = html_to_session(session_path)
             primary = (