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

htmlgraph/__init__.py

@@ -5,6 +5,28 @@ 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
@@ -96,7 +118,7 @@ from htmlgraph.types import (
 )
 from htmlgraph.work_type_utils import infer_work_type, infer_work_type_from_id
 
-__version__ = "0.26.24"
+__version__ = "0.27.0"
 __all__ = [
     # Exceptions
     "HtmlGraphError",

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_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/cli.py

@@ -109,7 +109,7 @@ def _iter_with_progress(
 
 
 def _display_session_analytics(
-    console: Console, sdk: SDK, session_id: str, graph_dir: str, quiet: bool
+    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
@@ -221,7 +221,7 @@ def _display_session_analytics(
 
 def _display_recent_sessions(
     console: Console,
-    sdk: SDK,
+    sdk: "SDK",
     session_files: list[Path],
     graph_dir: str,
     quiet: bool,
@@ -286,7 +286,7 @@ def _display_recent_sessions(
 
 def _display_project_analytics(
     console: Console,
-    sdk: SDK,
+    sdk: "SDK",
     session_files: list[Path],
     graph_dir: str,
     quiet: bool,

htmlgraph/analytics/cost_analyzer.py

@@ -1,3 +1,7 @@
+import logging
+
+logger = logging.getLogger(__name__)
+
 """
 CostAnalyzer for OTEL ROI Analysis - Phase 1.
 
@@ -15,7 +19,7 @@ Usage:
     from htmlgraph.analytics.cost_analyzer import CostAnalyzer
     analyzer = CostAnalyzer()
     delegations = analyzer.get_task_delegations_with_costs()
-    print(f"Total delegation cost: ${delegations['total_cost_usd']:.2f}")
+    logger.info(f"Total delegation cost: ${delegations['total_cost_usd']:.2f}")
 """
 
 import sqlite3

htmlgraph/analytics/cross_session.py

@@ -1,3 +1,9 @@
+from __future__ import annotations
+
+import logging
+
+logger = logging.getLogger(__name__)
+
 """
 Cross-session analytics using Git commits as the continuity spine.
 
@@ -38,8 +44,6 @@ Example:
     authors = cross.work_by_author(since_commit="abc123")
 """
 
-from __future__ import annotations
-
 import subprocess
 from collections import defaultdict
 from dataclasses import dataclass
@@ -147,8 +151,8 @@ class CrossSessionAnalytics:
             ...     from_commit="HEAD~10",
             ...     to_commit="HEAD"
             ... )
-            >>> print(f"Total events: {report.total_events}")
-            >>> print(f"Features: {', '.join(report.features)}")
+            >>> logger.info(f"Total events: {report.total_events}")
+            >>> logger.info(f"Features: {', '.join(report.features)}")
         """
         # Get commit list from Git
         commits = self._get_commits_in_range(from_commit, to_commit)
@@ -273,7 +277,7 @@ class CrossSessionAnalytics:
 
         Example:
             >>> sessions = cross.sessions_for_feature("feature-auth")
-            >>> print(f"Feature worked on in {len(sessions)} sessions")
+            >>> logger.info(f"Feature worked on in {len(sessions)} sessions")
         """
         sessions = set()
 
@@ -320,8 +324,8 @@ class CrossSessionAnalytics:
 
         Example:
             >>> report = cross.feature_cross_session_report("feature-auth")
-            >>> print(f"Implemented across {len(report.sessions)} sessions")
-            >>> print(f"Duration: {report.duration_hours:.1f} hours")
+            >>> logger.info(f"Implemented across {len(report.sessions)} sessions")
+            >>> logger.info(f"Duration: {report.duration_hours:.1f} hours")
         """
         sessions = set()
         commits = set()
@@ -395,7 +399,7 @@ class CrossSessionAnalytics:
         Example:
             >>> authors = cross.work_by_author(since_commit="v1.0.0")
             >>> for email, stats in authors.items():
-            ...     print(f"{email}: {stats['event_count']} events")
+            ...     logger.info(f"{email}: {stats['event_count']} events")
         """
         authors: dict[str, dict[str, Any]] = defaultdict(
             lambda: {
@@ -476,7 +480,7 @@ class CrossSessionAnalytics:
 
         Example:
             >>> commits = cross.commits_for_session("session-abc")
-            >>> print(f"Session produced {len(commits)} commits")
+            >>> logger.info(f"Session produced {len(commits)} commits")
         """
         commits = set()
 

htmlgraph/analytics/dependency.py

@@ -1,3 +1,9 @@
+from __future__ import annotations
+
+import logging
+
+logger = logging.getLogger(__name__)
+
 """
 Dependency-aware analytics for HtmlGraph.
 
@@ -9,8 +15,6 @@ Provides advanced graph analysis for project management:
 - Work prioritization
 """
 
-from __future__ import annotations
-
 from collections import deque
 from typing import TYPE_CHECKING
 
@@ -55,12 +59,12 @@ class DependencyAnalytics:
         # Find bottlenecks (cached internally for performance)
         bottlenecks = dep.find_bottlenecks(top_n=5)
         for bn in bottlenecks:
-            print(f"{bn.title} blocks {bn.transitive_blocking} features")
+            logger.info(f"{bn.title} blocks {bn.transitive_blocking} features")
 
         # Get work recommendations (reuses cached data)
         recs = dep.recommend_next_tasks(agent_count=3)
         for rec in recs.recommendations:
-            print(f"Work on: {rec.title} (unlocks {len(rec.unlocks)} features)")
+            logger.info(f"Work on: {rec.title} (unlocks {len(rec.unlocks)} features)")
 
         # After making graph changes, invalidate cache
         sdk.features.update(feature_id, status="done")
@@ -201,7 +205,7 @@ class DependencyAnalytics:
 
         Example:
             report = dep.find_parallelizable_work(status="todo")
-            print(f"Can work on {report.max_parallelism} features in parallel")
+            logger.info(f"Can work on {report.max_parallelism} features in parallel")
         """
         # Get dependency levels (topological layers)
         levels = self.dependency_levels(status_filter=[status])
@@ -456,7 +460,7 @@ class DependencyAnalytics:
         Example:
             recs = dep.recommend_next_tasks(agent_count=3)
             for rec in recs.recommendations:
-                print(f"Work on: {rec.title}")
+                logger.info(f"Work on: {rec.title}")
         """
         # Get all nodes with target status
         candidates = [n for n in self.graph.nodes.values() if n.status == status]

htmlgraph/analytics/work_type.py

@@ -1,3 +1,9 @@
+from __future__ import annotations
+
+import logging
+
+logger = logging.getLogger(__name__)
+
 """
 Analytics API for HtmlGraph work type analysis.
 
@@ -25,8 +31,6 @@ Example:
     # Returns: 25.5 (% of work spent on maintenance)
 """
 
-from __future__ import annotations
-
 from datetime import datetime, timezone
 from typing import TYPE_CHECKING
 
@@ -97,7 +101,7 @@ class Analytics:
         Example:
             >>> analytics = sdk.analytics
             >>> dist = analytics.work_type_distribution(session_id="session-123")
-            >>> print(dist)
+            >>> logger.info("%s", dist)
             {
                 "feature-implementation": 45.2,
                 "spike-investigation": 28.3,
@@ -163,11 +167,11 @@ class Analytics:
 
         Example:
             >>> ratio = sdk.analytics.spike_to_feature_ratio(session_id="session-123")
-            >>> print(f"Spike-to-feature ratio: {ratio:.2f}")
+            >>> logger.info(f"Spike-to-feature ratio: {ratio:.2f}")
             Spike-to-feature ratio: 0.63
 
             >>> if ratio > 0.5:
-            ...     print("This was a research-heavy session")
+            ...     logger.info("This was a research-heavy session")
         """
         events = self._get_events(session_id, start_date, end_date)
 
@@ -221,11 +225,11 @@ class Analytics:
 
         Example:
             >>> burden = sdk.analytics.maintenance_burden(session_id="session-123")
-            >>> print(f"Maintenance burden: {burden:.1f}%")
+            >>> logger.info(f"Maintenance burden: {burden:.1f}%")
             Maintenance burden: 32.5%
 
             >>> if burden > 40:
-            ...     print("⚠️  High maintenance burden - consider addressing technical debt")
+            ...     logger.info("⚠️  High maintenance burden - consider addressing technical debt")
         """
         events = self._get_events(session_id, start_date, end_date)
 
@@ -276,7 +280,7 @@ class Analytics:
             >>> spike_sessions = sdk.analytics.get_sessions_by_work_type(
             ...     "spike-investigation"
             ... )
-            >>> print(f"Found {len(spike_sessions)} exploratory sessions")
+            >>> logger.info(f"Found {len(spike_sessions)} exploratory sessions")
         """
         session_nodes = self.sdk.sessions.all()
         matching_sessions = []
@@ -316,7 +320,7 @@ class Analytics:
 
         Example:
             >>> breakdown = sdk.analytics.calculate_session_work_breakdown("session-123")
-            >>> print(breakdown)
+            >>> logger.info("%s", breakdown)
             {
                 "feature-implementation": 45,
                 "spike-investigation": 28,
@@ -344,7 +348,7 @@ class Analytics:
 
         Example:
             >>> primary = sdk.analytics.calculate_session_primary_work_type("session-123")
-            >>> print(f"Primary work type: {primary}")
+            >>> logger.info(f"Primary work type: {primary}")
             Primary work type: spike-investigation
         """
         session = self._get_session(session_id)
@@ -399,7 +403,7 @@ class Analytics:
 
         Example:
             >>> metrics = sdk.analytics.transition_time_metrics(session_id="session-123")
-            >>> print(f"Transition time: {metrics['transition_percent']:.1f}%")
+            >>> logger.info(f"Transition time: {metrics['transition_percent']:.1f}%")
             Transition time: 15.3%
         """
         from pathlib import Path

htmlgraph/analytics_index.py

@@ -1,3 +1,5 @@
+from __future__ import annotations
+
 """
 SQLite analytics index for HtmlGraph event logs.
 
@@ -5,7 +7,6 @@ This is a rebuildable cache/index for fast dashboard queries.
 The canonical source of truth is the JSONL event log under `.htmlgraph/events/`.
 """
 
-from __future__ import annotations
 
 import json
 import sqlite3