htmlgraph 0.26.25__py3-none-any.whl → 0.27.1__py3-none-any.whl

htmlgraph/builders/track.py

@@ -1,8 +1,9 @@
+from __future__ import annotations
+
 """
 Track Builder for agent-friendly track creation.
 """
 
-from __future__ import annotations
 
 import re
 from datetime import datetime

htmlgraph/cli/analytics.py

@@ -1,3 +1,5 @@
+from __future__ import annotations
+
 """HtmlGraph CLI - Analytics and reporting commands.
 
 Commands for analytics and reporting:
@@ -7,7 +9,6 @@ Commands for analytics and reporting:
 - sync-docs: Documentation synchronization
 """
 
-from __future__ import annotations
 
 import argparse
 import json

htmlgraph/cli/base.py

@@ -1,3 +1,5 @@
+from __future__ import annotations
+
 """Base classes and utilities for CLI commands.
 
 Provides:
@@ -10,7 +12,6 @@ Provides:
 - save_traceback: Save full tracebacks to log files instead of console
 """
 
-from __future__ import annotations
 
 import argparse
 import json

htmlgraph/cli/core.py

@@ -1,3 +1,5 @@
+from __future__ import annotations
+
 """HtmlGraph CLI - Infrastructure commands.
 
 Commands for core infrastructure operations:
@@ -11,7 +13,6 @@ Commands for core infrastructure operations:
 - Other utilities
 """
 
-from __future__ import annotations
 
 import argparse
 import sys

htmlgraph/cli/main.py

@@ -1,10 +1,11 @@
+from __future__ import annotations
+
 """HtmlGraph CLI - Main entry point.
 
 Entry point with argument parsing and command routing.
 Keeps main() thin by delegating to command modules.
 """
 
-from __future__ import annotations
 
 import argparse
 import sys

htmlgraph/cli/models.py

@@ -1,3 +1,5 @@
+from __future__ import annotations
+
 """HtmlGraph CLI - Pydantic models for command filters and configuration.
 
 This module provides type-safe models for validating command inputs:
@@ -5,7 +7,6 @@ This module provides type-safe models for validating command inputs:
 - Configuration models for infrastructure commands (init, serve)
 """
 
-from __future__ import annotations
 
 from datetime import datetime
 from typing import Literal

htmlgraph/cli/templates/cost_dashboard.py

@@ -1,10 +1,11 @@
+from __future__ import annotations
+
 """HTML template for cost dashboard.
 
 This module generates a beautiful, interactive HTML dashboard for cost analysis.
 Separated from main CLI code for maintainability and testability.
 """
 
-from __future__ import annotations
 
 from datetime import datetime
 from typing import TYPE_CHECKING, Any

htmlgraph/cli/work/__init__.py

@@ -1,3 +1,5 @@
+from __future__ import annotations
+
 """HtmlGraph CLI - Work management commands.
 
 Commands for managing work items:
@@ -9,7 +11,6 @@ Commands for managing work items:
 - Other work-related operations
 """
 
-from __future__ import annotations
 
 from typing import TYPE_CHECKING
 

htmlgraph/cli/work/browse.py

@@ -1,6 +1,7 @@
+from __future__ import annotations
+
 """HtmlGraph CLI - Browse command for opening dashboard in browser."""
 
-from __future__ import annotations
 
 import argparse
 import webbrowser

htmlgraph/cli/work/features.py

@@ -1,6 +1,7 @@
+from __future__ import annotations
+
 """HtmlGraph CLI - Feature management commands."""
 
-from __future__ import annotations
 
 import argparse
 from typing import TYPE_CHECKING

htmlgraph/cli/work/orchestration.py

@@ -1,6 +1,7 @@
+from __future__ import annotations
+
 """HtmlGraph CLI - Orchestration commands (Archive, Orchestrator, Claude)."""
 
-from __future__ import annotations
 
 import argparse
 from datetime import datetime

htmlgraph/cli/work/report.py

@@ -1,3 +1,5 @@
+from __future__ import annotations
+
 """HtmlGraph CLI - Session report commands.
 
 Commands for generating "What Did Claude Do?" reports:
@@ -7,7 +9,6 @@ THE killer feature that differentiates HtmlGraph - complete observability
 of AI agent activities with cost attribution and tool usage analysis.
 """
 
-from __future__ import annotations
 
 import argparse
 import sqlite3

htmlgraph/cli/work/sessions.py

@@ -1,6 +1,7 @@
+from __future__ import annotations
+
 """HtmlGraph CLI - Session management commands."""
 
-from __future__ import annotations
 
 import argparse
 from typing import TYPE_CHECKING

htmlgraph/cli/work/snapshot.py

@@ -1,6 +1,7 @@
+from __future__ import annotations
+
 """HtmlGraph CLI - Snapshot command for graph state visualization."""
 
-from __future__ import annotations
 
 import argparse
 import json

htmlgraph/cli/work/tracks.py

@@ -1,6 +1,7 @@
+from __future__ import annotations
+
 """HtmlGraph CLI - Track management commands."""
 
-from __future__ import annotations
 
 import argparse
 from pathlib import Path

htmlgraph/collections/base.py

@@ -1,3 +1,9 @@
+from __future__ import annotations
+
+import logging
+
+logger = logging.getLogger(__name__)
+
 """
 Base collection class for managing nodes.
 
@@ -5,7 +11,6 @@ Provides common collection functionality for all node types
 with lazy-loading, filtering, and batch operations.
 """
 
-from __future__ import annotations
 
 from collections.abc import Callable, Iterator
 from contextlib import contextmanager
@@ -227,7 +232,7 @@ class BaseCollection(Generic[CollectionT]):
         Example:
             >>> feature = sdk.features.get("feat-abc123")
             >>> ref = sdk.features.get_ref(feature.id)
-            >>> print(ref)  # "@f1"
+            >>> logger.info("%s", ref)  # "@f1"
         """
         if self._ref_manager:
             result = self._ref_manager.get_ref(node_id)
@@ -466,7 +471,7 @@ class BaseCollection(Generic[CollectionT]):
 
         Example:
             >>> count = sdk.features.batch_delete(["feat-001", "feat-002", "feat-003"])
-            >>> print(f"Deleted {count} features")
+            >>> logger.info(f"Deleted {count} features")
         """
         graph = self._ensure_graph()
         return cast(int, graph.batch_delete(node_ids))
@@ -540,9 +545,9 @@ class BaseCollection(Generic[CollectionT]):
 
         Example:
             >>> result = sdk.features.mark_done(["feat-001", "feat-002"])
-            >>> print(f"Completed {result['success_count']} of {len(node_ids)}")
+            >>> logger.info(f"Completed {result['success_count']} of {len(node_ids)}")
             >>> if result['failed_ids']:
-            ...     print(f"Failed: {result['failed_ids']}")
+            ...     logger.info(f"Failed: {result['failed_ids']}")
         """
         graph = self._ensure_graph()
         results: dict[str, Any] = {"success_count": 0, "failed_ids": [], "warnings": []}

htmlgraph/collections/bug.py

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

htmlgraph/collections/chore.py

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

htmlgraph/collections/epic.py

@@ -1,10 +1,11 @@
+from __future__ import annotations
+
 """
 Epic collection for managing large body of work items.
 
 Extends BaseCollection with epic-specific builder support.
 """
 
-from __future__ import annotations
 
 from typing import TYPE_CHECKING
 

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

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/config/cost_models.json

@@ -0,0 +1,56 @@
+{
+  "description": "Model pricing configuration for cost tracking",
+  "last_updated": "2026-01-16",
+  "models": {
+    "claude-haiku-4-5-20251001": {
+      "name": "Claude Haiku",
+      "display_name": "Haiku 4.5",
+      "input_cost_per_mtok": 0.80,
+      "output_cost_per_mtok": 4.00,
+      "description": "Fast, efficient model for routine tasks"
+    },
+    "claude-sonnet-4-20250514": {
+      "name": "Claude Sonnet",
+      "display_name": "Sonnet 4",
+      "input_cost_per_mtok": 3.00,
+      "output_cost_per_mtok": 15.00,
+      "description": "Balanced model for most tasks"
+    },
+    "claude-opus-4-1-20250805": {
+      "name": "Claude Opus",
+      "display_name": "Opus 4.1",
+      "input_cost_per_mtok": 15.00,
+      "output_cost_per_mtok": 75.00,
+      "description": "Most capable model for complex reasoning"
+    }
+  },
+  "gemini_models": {
+    "gemini-2.0-flash": {
+      "name": "Gemini 2.0 Flash",
+      "input_cost_per_mtok": 0.075,
+      "output_cost_per_mtok": 0.30,
+      "description": "Fast multimodal model"
+    },
+    "gemini-2.0-pro": {
+      "name": "Gemini 2.0 Pro",
+      "input_cost_per_mtok": 1.50,
+      "output_cost_per_mtok": 6.00,
+      "description": "Advanced reasoning model"
+    }
+  },
+  "defaults": {
+    "input_cost_per_mtok": 2.00,
+    "output_cost_per_mtok": 10.00
+  },
+  "alert_thresholds": {
+    "budget_warning_percent": 80,
+    "budget_critical_percent": 95,
+    "model_overage_multiplier": 1.5,
+    "trajectory_overage_multiplier": 1.3
+  },
+  "tracking": {
+    "accuracy_target_percent": 5,
+    "cost_calculation_method": "token_based",
+    "rounding_precision": 4
+  }
+}

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