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

htmlgraph/analytics/dependency.py

@@ -1,3 +1,9 @@
+from __future__ import annotations
+
+import logging
+
+logger = logging.getLogger(__name__)
+
 """
 Dependency-aware analytics for HtmlGraph.
 
@@ -9,25 +15,19 @@ Provides advanced graph analysis for project management:
 - Work prioritization
 """
 
-from __future__ import annotations
+from collections import deque
 from typing import TYPE_CHECKING
-from collections import defaultdict, deque
 
 from htmlgraph.dependency_models import (
     BottleneckNode,
-    CriticalPathResult,
-    CriticalPathNode,
+    ImpactAnalysis,
     ParallelizationReport,
     ParallelLevel,
     RiskAssessment,
-    RiskNode,
     RiskFactor,
-    HealthReport,
-    HealthIndicator,
-    TaskRecommendations,
+    RiskNode,
     TaskRecommendation,
-    ImpactAnalysis,
-    WhatIfResult,
+    TaskRecommendations,
 )
 
 if TYPE_CHECKING:
@@ -46,21 +46,29 @@ class DependencyAnalytics:
     - What should we prioritize next?
     - What are the high-risk dependencies?
 
+    Performance: Uses internal caching to optimize transitive dependency calculations.
+    Multiple calls to bottleneck detection or task recommendations reuse cached results.
+    Call invalidate_cache() after graph structure changes to refresh the cache.
+
     Example:
         from htmlgraph import SDK
 
         sdk = SDK(agent="claude")
         dep = sdk.dep_analytics
 
-        # Find bottlenecks
+        # 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
+        # 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")
+        dep.invalidate_cache()  # Refresh for accurate results
     """
 
     def __init__(self, graph: HtmlGraph):
@@ -72,6 +80,7 @@ class DependencyAnalytics:
         """
         self.graph = graph
         self._edge_index = graph.edge_index
+        self._transitive_cache: dict[str, set[str]] = {}
 
     # === Bottleneck Detection ===
 
@@ -79,7 +88,7 @@ class DependencyAnalytics:
         self,
         status_filter: list[str] | None = None,
         top_n: int = 10,
-        min_impact: int = 1
+        min_impact: int = 1,
     ) -> list[BottleneckNode]:
         """
         Identify nodes that are blocking the most work.
@@ -120,7 +129,12 @@ class DependencyAnalytics:
             transitive = self._count_transitive_dependents(node.id)
 
             # Calculate weighted impact
-            priority_weight = {"critical": 3.0, "high": 2.0, "medium": 1.0, "low": 0.5}.get(node.priority, 1.0)
+            priority_weight = {
+                "critical": 3.0,
+                "high": 2.0,
+                "medium": 1.0,
+                "low": 0.5,
+            }.get(node.priority, 1.0)
             completion_pct = self._calculate_completion(node)
             incompletion_factor = (100.0 - completion_pct) / 100.0
             weighted_impact = transitive * priority_weight * incompletion_factor
@@ -128,17 +142,19 @@ class DependencyAnalytics:
             # Get list of blocked nodes
             blocked_nodes = self._get_direct_dependents(node.id)
 
-            bottlenecks.append(BottleneckNode(
-                id=node.id,
-                title=node.title,
-                status=node.status,
-                priority=node.priority,
-                completion_pct=completion_pct,
-                direct_blocking=direct,
-                transitive_blocking=transitive,
-                weighted_impact=weighted_impact,
-                blocked_nodes=blocked_nodes
-            ))
+            bottlenecks.append(
+                BottleneckNode(
+                    id=node.id,
+                    title=node.title,
+                    status=node.status,
+                    priority=node.priority,
+                    completion_pct=completion_pct,
+                    direct_blocking=direct,
+                    transitive_blocking=transitive,
+                    weighted_impact=weighted_impact,
+                    blocked_nodes=blocked_nodes,
+                )
+            )
 
         # Sort by weighted impact descending
         bottlenecks.sort(key=lambda x: x.weighted_impact, reverse=True)
@@ -159,9 +175,11 @@ class DependencyAnalytics:
         if not node:
             return 0.0
 
-        direct = self._count_direct_dependents(node_id)
+        self._count_direct_dependents(node_id)
         transitive = self._count_transitive_dependents(node_id)
-        priority_weight = {"critical": 3.0, "high": 2.0, "medium": 1.0, "low": 0.5}.get(node.priority, 1.0)
+        priority_weight = {"critical": 3.0, "high": 2.0, "medium": 1.0, "low": 0.5}.get(
+            node.priority, 1.0
+        )
         completion_pct = self._calculate_completion(node)
         incompletion_factor = (100.0 - completion_pct) / 100.0
 
@@ -170,9 +188,7 @@ class DependencyAnalytics:
     # === Parallelization Analysis ===
 
     def find_parallelizable_work(
-        self,
-        status: str = "todo",
-        max_levels: int | None = None
+        self, status: str = "todo", max_levels: int | None = None
     ) -> ParallelizationReport:
         """
         Identify work that can be done in parallel.
@@ -189,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])
@@ -210,27 +226,31 @@ class DependencyAnalytics:
             max_parallel = len(node_ids)
             max_parallelism = max(max_parallelism, max_parallel)
 
-            parallel_levels.append(ParallelLevel(
-                level=level_idx,
-                nodes=list(node_ids),
-                max_parallel=max_parallel,
-                independent_groups=independent_groups
-            ))
+            parallel_levels.append(
+                ParallelLevel(
+                    level=level_idx,
+                    nodes=list(node_ids),
+                    max_parallel=max_parallel,
+                    independent_groups=independent_groups,
+                )
+            )
 
         # Suggest assignments (round-robin for now)
         suggestions = []
         if parallel_levels and parallel_levels[0].nodes:
             for i, node_id in enumerate(parallel_levels[0].nodes[:3]):  # Top 3
-                agent_name = f"agent-{i+1}"
+                agent_name = f"agent-{i + 1}"
                 suggestions.append((agent_name, [node_id]))
 
         return ParallelizationReport(
             max_parallelism=max_parallelism,
             dependency_levels=parallel_levels,
-            suggested_assignments=suggestions
+            suggested_assignments=suggestions,
         )
 
-    def dependency_levels(self, status_filter: list[str] | None = None) -> list[set[str]]:
+    def dependency_levels(
+        self, status_filter: list[str] | None = None
+    ) -> list[set[str]]:
         """
         Group nodes by dependency level (topological layers).
 
@@ -247,7 +267,9 @@ class DependencyAnalytics:
         """
         # Get all nodes matching filter
         if status_filter:
-            nodes_to_process = [n for n in self.graph.nodes.values() if n.status in status_filter]
+            nodes_to_process = [
+                n for n in self.graph.nodes.values() if n.status in status_filter
+            ]
         else:
             nodes_to_process = list(self.graph.nodes.values())
 
@@ -263,7 +285,7 @@ class DependencyAnalytics:
             in_degree[node.id] = count
 
         levels = []
-        processed = set()
+        processed: set[str] = set()
 
         while len(processed) < len(node_ids):
             # Find all nodes with in-degree 0 (no unprocessed dependencies)
@@ -287,7 +309,10 @@ class DependencyAnalytics:
             # Decrease in-degree for neighbors
             for node_id in current_level:
                 for edge_ref in self._edge_index.get_outgoing(node_id):
-                    if edge_ref.target_id in in_degree and edge_ref.target_id not in processed:
+                    if (
+                        edge_ref.target_id in in_degree
+                        and edge_ref.target_id not in processed
+                    ):
                         in_degree[edge_ref.target_id] -= 1
 
         return levels
@@ -309,10 +334,7 @@ class DependencyAnalytics:
 
     # === Risk Assessment ===
 
-    def assess_dependency_risk(
-        self,
-        spof_threshold: int = 3
-    ) -> RiskAssessment:
+    def assess_dependency_risk(self, spof_threshold: int = 3) -> RiskAssessment:
         """
         Assess risk based on dependency structure.
 
@@ -343,18 +365,20 @@ class DependencyAnalytics:
                     type="spof",
                     severity="high" if dependents_count > 10 else "medium",
                     description=f"Blocks {dependents_count} features with no alternative paths",
-                    mitigation="Consider breaking into smaller independent features"
+                    mitigation="Consider breaking into smaller independent features",
                 )
             ]
 
             risk_score = min(dependents_count / 20.0, 1.0)  # Cap at 1.0
 
-            high_risk.append(RiskNode(
-                id=node_id,
-                title=node.title,
-                risk_score=risk_score,
-                risk_factors=risk_factors
-            ))
+            high_risk.append(
+                RiskNode(
+                    id=node_id,
+                    title=node.title,
+                    risk_score=risk_score,
+                    risk_factors=risk_factors,
+                )
+            )
 
         # Find circular dependencies
         cycles = self.graph.find_cycles()
@@ -370,24 +394,27 @@ class DependencyAnalytics:
 
         # Generate recommendations
         recommendations = []
-        for node in high_risk[:3]:
-            recommendations.append(f"Break {node.title} into smaller features to reduce SPOF risk")
+        for risk_node in high_risk[:3]:
+            recommendations.append(
+                f"Break {risk_node.title} into smaller features to reduce SPOF risk"
+            )
         if cycles:
-            recommendations.append(f"Resolve {len(cycles)} circular dependencies detected")
+            recommendations.append(
+                f"Resolve {len(cycles)} circular dependencies detected"
+            )
         if orphaned:
-            recommendations.append(f"Review {len(orphaned)} orphaned nodes with no dependents")
+            recommendations.append(
+                f"Review {len(orphaned)} orphaned nodes with no dependents"
+            )
 
         return RiskAssessment(
             high_risk=high_risk,
             circular_dependencies=cycles,
             orphaned_nodes=orphaned,
-            recommendations=recommendations
+            recommendations=recommendations,
         )
 
-    def single_points_of_failure(
-        self,
-        min_dependents: int = 3
-    ) -> list[str]:
+    def single_points_of_failure(self, min_dependents: int = 3) -> list[str]:
         """
         Identify nodes with high fan-in (many dependents).
 
@@ -411,10 +438,7 @@ class DependencyAnalytics:
     # === Work Prioritization ===
 
     def recommend_next_tasks(
-        self,
-        agent_count: int = 1,
-        status: str = "todo",
-        lookahead: int = 3
+        self, agent_count: int = 1, status: str = "todo", lookahead: int = 3
     ) -> TaskRecommendations:
         """
         Recommend which tasks to work on next.
@@ -436,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]
@@ -470,21 +494,26 @@ class DependencyAnalytics:
             if not reasons:
                 reasons.append("Ready to start (all dependencies complete)")
 
-            scored.append((score, TaskRecommendation(
-                id=node.id,
-                title=node.title,
-                priority=node.priority,
-                score=score,
-                reasons=reasons,
-                estimated_effort=effort,
-                unlocks=unlocks
-            )))
+            scored.append(
+                (
+                    score,
+                    TaskRecommendation(
+                        id=node.id,
+                        title=node.title,
+                        priority=node.priority,
+                        score=score,
+                        reasons=reasons,
+                        estimated_effort=effort,
+                        unlocks=unlocks,
+                    ),
+                )
+            )
 
         # Sort by score descending
         scored.sort(key=lambda x: x[0], reverse=True)
 
         # Take top recommendations
-        recommendations = [rec for _, rec in scored[:lookahead * agent_count]]
+        recommendations = [rec for _, rec in scored[: lookahead * agent_count]]
 
         # Find parallel suggestions
         parallel_suggestions = []
@@ -492,17 +521,16 @@ class DependencyAnalytics:
             # Simple approach: suggest non-overlapping dependency chains
             for i in range(0, min(len(recommendations), agent_count * 2), 2):
                 if i + 1 < len(recommendations):
-                    parallel_suggestions.append([recommendations[i].id, recommendations[i+1].id])
+                    parallel_suggestions.append(
+                        [recommendations[i].id, recommendations[i + 1].id]
+                    )
 
         return TaskRecommendations(
-            recommendations=recommendations,
-            parallel_suggestions=parallel_suggestions
+            recommendations=recommendations, parallel_suggestions=parallel_suggestions
         )
 
     def prioritization_score(
-        self,
-        node_id: str,
-        weights: dict[str, float] | None = None
+        self, node_id: str, weights: dict[str, float] | None = None
     ) -> float:
         """
         Calculate priority score for a node.
@@ -525,7 +553,7 @@ class DependencyAnalytics:
                 "transitive_blocking": 2.0,
                 "priority": 1.5,
                 "dependency_penalty": -0.5,
-                "critical_path": 3.0
+                "critical_path": 3.0,
             }
 
         node = self.graph.get(node_id)
@@ -570,9 +598,7 @@ class DependencyAnalytics:
         return (fan_in, fan_out)
 
     def impact_analysis(
-        self,
-        node_id: str,
-        include_done: bool = False
+        self, node_id: str, include_done: bool = False
     ) -> ImpactAnalysis:
         """
         Analyze the downstream impact of a node.
@@ -585,19 +611,27 @@ class DependencyAnalytics:
             ImpactAnalysis with dependency impact
         """
         direct = self._count_direct_dependents(node_id)
-        transitive = self._count_transitive_dependents(node_id, include_done=include_done)
-        affected = self._get_all_transitive_dependents(node_id, include_done=include_done)
+        transitive = self._count_transitive_dependents(
+            node_id, include_done=include_done
+        )
+        affected = self._get_all_transitive_dependents(
+            node_id, include_done=include_done
+        )
 
         # Calculate what % of total work this represents
-        total_nodes = len([n for n in self.graph.nodes.values() if include_done or n.status != "done"])
-        completion_impact = (transitive / total_nodes * 100.0) if total_nodes > 0 else 0.0
+        total_nodes = len(
+            [n for n in self.graph.nodes.values() if include_done or n.status != "done"]
+        )
+        completion_impact = (
+            (transitive / total_nodes * 100.0) if total_nodes > 0 else 0.0
+        )
 
         return ImpactAnalysis(
             node_id=node_id,
             direct_dependents=direct,
             transitive_dependents=transitive,
             affected_nodes=affected,
-            completion_impact=completion_impact
+            completion_impact=completion_impact,
         )
 
     # === Private Helper Methods ===
@@ -608,13 +642,25 @@ class DependencyAnalytics:
 
     def _get_direct_dependents(self, node_id: str) -> list[str]:
         """Get list of node IDs that directly depend on this node."""
-        return [edge_ref.source_id for edge_ref in self._edge_index.get_incoming(node_id)]
+        return [
+            edge_ref.source_id for edge_ref in self._edge_index.get_incoming(node_id)
+        ]
 
-    def _count_transitive_dependents(self, node_id: str, include_done: bool = False) -> int:
-        """Count all downstream nodes that transitively depend on this node."""
-        return len(self._get_all_transitive_dependents(node_id, include_done=include_done))
+    def _count_transitive_dependents(
+        self, node_id: str, include_done: bool = False
+    ) -> int:
+        """
+        Count all downstream nodes that transitively depend on this node.
+
+        Uses cached results when available to improve performance from O(V²+VE) to O(V+E)
+        for repeated calls.
+        """
+        transitive_set = self._get_or_compute_transitive(node_id, include_done)
+        return len(transitive_set)
 
-    def _get_all_transitive_dependents(self, node_id: str, include_done: bool = False) -> list[str]:
+    def _get_all_transitive_dependents(
+        self, node_id: str, include_done: bool = False
+    ) -> list[str]:
         """Get all downstream nodes (BFS traversal of dependents)."""
         visited = set()
         queue = deque([node_id])
@@ -676,3 +722,49 @@ class DependencyAnalytics:
         # Simple implementation: return individual nodes for now
         # A more sophisticated version would use graph coloring
         return [[nid] for nid in node_ids]
+
+    def _get_or_compute_transitive(
+        self, node_id: str, include_done: bool = False
+    ) -> set[str]:
+        """
+        Get or compute transitive dependents with caching.
+
+        Uses a cache to avoid redundant BFS traversals. The cache key combines
+        node_id and include_done flag to ensure correct results for both cases.
+
+        Args:
+            node_id: Node to analyze
+            include_done: Whether to include completed nodes
+
+        Returns:
+            Set of node IDs that transitively depend on this node
+        """
+        cache_key = f"{node_id}:{include_done}"
+
+        if cache_key in self._transitive_cache:
+            return self._transitive_cache[cache_key]
+
+        # Compute transitive dependents via BFS
+        dependents = self._get_all_transitive_dependents(
+            node_id, include_done=include_done
+        )
+        dependents_set = set(dependents)
+
+        # Cache the result
+        self._transitive_cache[cache_key] = dependents_set
+
+        return dependents_set
+
+    def invalidate_cache(self) -> None:
+        """
+        Clear the transitive dependency cache.
+
+        Call this method after making structural changes to the graph
+        (adding/removing nodes or edges) to ensure cached results remain accurate.
+
+        Example:
+            analytics = sdk.dep_analytics
+            analytics.invalidate_cache()  # After graph updates
+            bottlenecks = analytics.find_bottlenecks()  # Fresh calculation
+        """
+        self._transitive_cache.clear()