htmlgraph 0.26.25__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.25"
+__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

htmlgraph/api/main.py

@@ -204,7 +204,37 @@ def get_app(db_path: str) -> FastAPI:
             return "0"
         return f"{value:,}"
 
+    def format_duration(seconds: float | int | None) -> str:
+        """Format duration in seconds to human-readable string."""
+        if seconds is None:
+            return "0.00s"
+        return f"{float(seconds):.2f}s"
+
+    def format_bytes(bytes_size: int | float | None) -> str:
+        """Format bytes to MB with 2 decimal places."""
+        if bytes_size is None:
+            return "0.00MB"
+        return f"{int(bytes_size) / (1024 * 1024):.2f}MB"
+
+    def truncate_text(text: str | None, length: int = 50) -> str:
+        """Truncate text to specified length with ellipsis."""
+        if text is None:
+            return ""
+        return text[:length] + "..." if len(text) > length else text
+
+    def format_timestamp(ts: Any) -> str:
+        """Format timestamp to readable string."""
+        if ts is None:
+            return ""
+        if hasattr(ts, "strftime"):
+            return str(ts.strftime("%Y-%m-%d %H:%M:%S"))
+        return str(ts)
+
     templates.env.filters["format_number"] = format_number
+    templates.env.filters["format_duration"] = format_duration
+    templates.env.filters["format_bytes"] = format_bytes
+    templates.env.filters["truncate"] = truncate_text
+    templates.env.filters["format_timestamp"] = format_timestamp
 
     # Setup static files
     static_dir = Path(__file__).parent / "static"
@@ -287,8 +317,8 @@ def get_app(db_path: str) -> FastAPI:
 
                 # Execute query with timing
                 exec_start = time.time()
-                cursor = await db.execute(query)
-                rows = await cursor.fetchall()
+                async with db.execute(query) as cursor:
+                    rows = await cursor.fetchall()
                 exec_time_ms = (time.time() - exec_start) * 1000
 
                 agents = []
@@ -434,8 +464,8 @@ def get_app(db_path: str) -> FastAPI:
 
                 # Execute query with timing
                 exec_start = time.time()
-                cursor = await db.execute(query, params)
-                rows = await cursor.fetchall()
+                async with db.execute(query, params) as cursor:
+                    rows = await cursor.fetchall()
                 exec_time_ms = (time.time() - exec_start) * 1000
 
                 # Build result models
@@ -485,15 +515,15 @@ def get_app(db_path: str) -> FastAPI:
                     (SELECT COUNT(DISTINCT agent_id) FROM agent_events) as total_agents,
                     (SELECT COUNT(*) FROM sessions) as total_sessions
             """
-            cursor = await db.execute(stats_query)
-            row = await cursor.fetchone()
+            async with db.execute(stats_query) as cursor:
+                row = await cursor.fetchone()
 
             # Query distinct agent IDs for the agent set
             agents_query = (
                 "SELECT DISTINCT agent_id FROM agent_events WHERE agent_id IS NOT NULL"
             )
-            agents_cursor = await db.execute(agents_query)
-            agents_rows = await agents_cursor.fetchall()
+            async with db.execute(agents_query) as agents_cursor:
+                agents_rows = await agents_cursor.fetchall()
             agents = [row[0] for row in agents_rows]
 
             if row is None:
@@ -616,8 +646,8 @@ def get_app(db_path: str) -> FastAPI:
             parent_query += " ORDER BY timestamp DESC LIMIT ?"
             parent_params.append(limit)
 
-            cursor = await db.execute(parent_query, parent_params)
-            parent_rows = await cursor.fetchall()
+            async with db.execute(parent_query, parent_params) as cursor:
+                parent_rows = await cursor.fetchall()
 
             traces: list[dict[str, Any]] = []
 
@@ -655,8 +685,8 @@ def get_app(db_path: str) -> FastAPI:
                     WHERE parent_event_id = ?
                     ORDER BY timestamp ASC
                 """
-                child_cursor = await db.execute(child_query, (parent_event_id,))
-                child_rows = await child_cursor.fetchall()
+                async with db.execute(child_query, (parent_event_id,)) as child_cursor:
+                    child_rows = await child_cursor.fetchall()
 
                 child_events = []
                 for child_row in child_rows:
@@ -806,8 +836,8 @@ def get_app(db_path: str) -> FastAPI:
             params.append(limit)
 
             exec_start = time.time()
-            cursor = await db.execute(query, params)
-            rows = await cursor.fetchall()
+            async with db.execute(query, params) as cursor:
+                rows = await cursor.fetchall()
 
             for row in rows:
                 events.append(
@@ -851,8 +881,8 @@ def get_app(db_path: str) -> FastAPI:
                     spike_query += " ORDER BY created_at DESC LIMIT ?"
                     spike_params.append(limit)
 
-                    spike_cursor = await db.execute(spike_query, spike_params)
-                    spike_rows = await spike_cursor.fetchall()
+                    async with db.execute(spike_query, spike_params) as spike_cursor:
+                        spike_rows = await spike_cursor.fetchall()
 
                     for row in spike_rows:
                         events.append(
@@ -902,8 +932,8 @@ def get_app(db_path: str) -> FastAPI:
                     collab_query += " ORDER BY timestamp DESC LIMIT ?"
                     collab_params.append(limit)
 
-                    collab_cursor = await db.execute(collab_query, collab_params)
-                    collab_rows = await collab_cursor.fetchall()
+                    async with db.execute(collab_query, collab_params) as collab_cursor:
+                        collab_rows = await collab_cursor.fetchall()
 
                     for row in collab_rows:
                         events.append(
@@ -1016,8 +1046,8 @@ def get_app(db_path: str) -> FastAPI:
                 LIMIT ?
             """
 
-            cursor = await db.execute(user_query_query, [limit])
-            user_query_rows = await cursor.fetchall()
+            async with db.execute(user_query_query, [limit]) as cursor:
+                user_query_rows = await cursor.fetchall()
 
             conversation_turns: list[dict[str, Any]] = []
 
@@ -1061,8 +1091,8 @@ def get_app(db_path: str) -> FastAPI:
                     if depth >= max_depth:
                         return [], 0.0, 0, 0
 
-                    cursor = await db.execute(children_query, [parent_id])
-                    rows = await cursor.fetchall()
+                    async with db.execute(children_query, [parent_id]) as cursor:
+                        rows = await cursor.fetchall()
 
                     children_list: list[dict[str, Any]] = []
                     total_dur = 0.0
@@ -1338,8 +1368,8 @@ def get_app(db_path: str) -> FastAPI:
             query += " ORDER BY started_at DESC LIMIT ? OFFSET ?"
             params.extend([limit, offset])
 
-            cursor = await db.execute(query, params)
-            rows = await cursor.fetchall()
+            async with db.execute(query, params) as cursor:
+                rows = await cursor.fetchall()
 
             # Get total count for pagination
             count_query = "SELECT COUNT(*) FROM sessions WHERE 1=1"
@@ -1348,8 +1378,8 @@ def get_app(db_path: str) -> FastAPI:
                 count_query += " AND status = ?"
                 count_params.append(status)
 
-            count_cursor = await db.execute(count_query, count_params)
-            count_row = await count_cursor.fetchone()
+            async with db.execute(count_query, count_params) as count_cursor:
+                count_row = await count_cursor.fetchone()
             total = int(count_row[0]) if count_row else 0
 
             # Build session objects
@@ -1416,8 +1446,8 @@ def get_app(db_path: str) -> FastAPI:
                 LIMIT 50
             """
 
-            cursor = await db.execute(query)
-            rows = list(await cursor.fetchall())
+            async with db.execute(query) as cursor:
+                rows = list(await cursor.fetchall())
             logger.debug(f"orchestration_view: Query executed, got {len(rows)} rows")
 
             delegations = []

htmlgraph/attribute_index.py

@@ -1,3 +1,5 @@
+from __future__ import annotations
+
 """
 Attribute Index for O(1) attribute-based lookups.
 
@@ -11,7 +13,6 @@ Without this index, finding nodes by attribute requires scanning
 all nodes in the graph - O(n) complexity.
 """
 
-from __future__ import annotations
 
 from collections import defaultdict
 from dataclasses import dataclass, field

htmlgraph/builders/base.py

@@ -1,10 +1,11 @@
+from __future__ import annotations
+
 """
 Base builder class for fluent node creation.
 
 Provides common builder patterns shared across all node types.
 """
 
-from __future__ import annotations
 
 from datetime import datetime
 from typing import TYPE_CHECKING, Any, Generic, TypeVar

htmlgraph/builders/bug.py

@@ -1,3 +1,5 @@
+from __future__ import annotations
+
 """
 Bug builder for creating bug report nodes.
 
@@ -5,7 +7,6 @@ Extends BaseBuilder with bug-specific methods like
 severity and reproduction steps.
 """
 
-from __future__ import annotations
 
 from typing import TYPE_CHECKING, Any