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

htmlgraph/sdk/orchestration/spawner.py

@@ -0,0 +1,204 @@
+"""
+Spawner utilities for creating subagent prompts.
+
+Provides session context information needed for orchestration.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import TYPE_CHECKING, Any
+
+if TYPE_CHECKING:
+    from htmlgraph.analytics import DependencyAnalytics
+    from htmlgraph.collections.feature import FeatureCollection
+    from htmlgraph.collections.session import SessionCollection
+    from htmlgraph.sdk import SDK as SDK_TYPE
+    from htmlgraph.types import SessionStartInfo
+else:
+    SDK_TYPE = "SDK"  # type: ignore[misc,assignment]
+    SessionStartInfo = dict  # type: ignore[misc,assignment]
+    FeatureCollection = Any  # type: ignore[misc,assignment]
+    SessionCollection = Any  # type: ignore[misc,assignment]
+    DependencyAnalytics = Any  # type: ignore[misc,assignment]
+
+
+class SessionInfoMixin:
+    """
+    Mixin providing session start information for orchestration.
+
+    Used by orchestrator to gather context for subagent spawning.
+
+    This mixin is used by SDK class which has these attributes.
+    """
+
+    _directory: Path
+    features: FeatureCollection
+    sessions: SessionCollection
+    dep_analytics: DependencyAnalytics
+
+    def get_status(self) -> dict[str, Any]:
+        """Get project status. Implemented by SDK."""
+        raise NotImplementedError("Implemented by SDK")
+
+    def get_active_work_item(self) -> dict[str, Any] | None:
+        """Get active work item. Implemented by SDK."""
+        raise NotImplementedError("Implemented by SDK")
+
+    def get_session_start_info(
+        self,
+        include_git_log: bool = True,
+        git_log_count: int = 5,
+        analytics_top_n: int = 3,
+        analytics_max_agents: int = 3,
+    ) -> SessionStartInfo:
+        """
+        Get comprehensive session start information in a single call.
+
+        Consolidates all information needed for session start into one method,
+        reducing context usage from 6+ tool calls to 1.
+
+        Args:
+            include_git_log: Include recent git commits (default: True)
+            git_log_count: Number of recent commits to include (default: 5)
+            analytics_top_n: Number of bottlenecks/recommendations (default: 3)
+            analytics_max_agents: Max agents for parallel work analysis (default: 3)
+
+        Returns:
+            Dict with comprehensive session start context:
+                - status: Project status (nodes, collections, WIP)
+                - active_work: Current active work item (if any)
+                - features: List of features with status
+                - sessions: Recent sessions
+                - git_log: Recent commits (if include_git_log=True)
+                - analytics: Strategic insights (bottlenecks, recommendations, parallel)
+
+        Note:
+            Returns empty dict {} if session context unavailable.
+            Always check for expected keys before accessing.
+
+        Example:
+            >>> sdk = SDK(agent="claude")
+            >>> info = sdk.get_session_start_info()
+            >>> logger.info(f"Project: {info['status']['total_nodes']} nodes")
+            >>> logger.info(f"WIP: {info['status']['in_progress_count']}")
+            >>> if info.get('active_work'):
+            ...     logger.info(f"Active: {info['active_work']['title']}")
+
+        See also:
+            status: Get project status only
+            features.list_all: Get all features
+            dep_analytics.recommend_next_tasks: Get recommendations only
+        """
+        # Build result dictionary incrementally, then cast at return
+        result: dict[str, Any] = {}
+
+        try:
+            # 1. Project status
+            status = self.get_status()
+            result["status"] = status
+
+            # 2. Active work item
+            active_work = self.get_active_work_item()
+            if active_work:
+                result["active_work"] = active_work
+
+            # 3. All features
+            features = self.features.list_all()
+            result["features"] = [
+                {
+                    "id": f.id,
+                    "title": f.title,
+                    "status": f.status,
+                    "priority": getattr(f, "priority", "medium"),
+                    "steps_total": len(f.steps) if hasattr(f, "steps") else 0,
+                    "steps_completed": sum(1 for s in f.steps if s.completed)
+                    if hasattr(f, "steps")
+                    else 0,
+                }
+                for f in features
+            ]
+
+            # 4. Recent sessions
+            sessions = self.sessions.list_all()
+            result["sessions"] = [
+                {
+                    "id": s.id,
+                    "agent": getattr(s, "agent", "unknown"),
+                    "status": s.status,
+                    "event_count": getattr(s.properties, "event_count", 0)
+                    if hasattr(s, "properties")
+                    else 0,
+                }
+                for s in sessions[:5]  # Last 5 sessions
+            ]
+
+            # 5. Git log (optional)
+            if include_git_log:
+                import subprocess
+
+                try:
+                    git_output = subprocess.check_output(
+                        [
+                            "git",
+                            "log",
+                            f"-{git_log_count}",
+                            "--oneline",
+                            "--no-decorate",
+                        ],
+                        cwd=self._directory.parent,
+                        stderr=subprocess.DEVNULL,
+                        text=True,
+                    )
+                    result["git_log"] = git_output.strip().split("\n")
+                except Exception:
+                    # Git not available or not a git repo
+                    result["git_log"] = []
+
+            # 6. Strategic analytics
+            try:
+                bottlenecks = self.dep_analytics.find_bottlenecks(top_n=analytics_top_n)
+                recommendations = self.dep_analytics.recommend_next_tasks(
+                    agent_count=1, lookahead=analytics_top_n
+                )
+                parallel_work = self.dep_analytics.find_parallelizable_work()
+
+                # Convert to serializable dicts for JSON response
+                result["analytics"] = {
+                    "bottlenecks": [
+                        {
+                            "id": b.id,
+                            "title": b.title,
+                            "weighted_impact": b.weighted_impact,
+                        }
+                        for b in bottlenecks
+                    ],
+                    "recommendations": [
+                        {"id": r.id, "title": r.title, "score": r.score}
+                        for r in recommendations.recommendations
+                    ]
+                    if hasattr(recommendations, "recommendations")
+                    else [],
+                    "parallel": {
+                        "max_parallelism": parallel_work.max_parallelism,
+                        "levels": len(parallel_work.levels)
+                        if hasattr(parallel_work, "levels")
+                        else 0,
+                    },
+                }
+            except Exception:
+                # Analytics not available
+                result["analytics"] = {
+                    "bottlenecks": [],
+                    "recommendations": [],
+                    "parallel": {
+                        "max_parallelism": 0,
+                        "levels": 0,
+                    },
+                }
+
+        except Exception:
+            # Return empty dict on any error - type ignore since we're returning partial dict
+            return {}  # type: ignore[return-value,typeddict-item]
+
+        return result  # type: ignore[return-value,typeddict-item]

htmlgraph/sdk/planning/__init__.py

@@ -0,0 +1,19 @@
+"""
+Planning module for SDK - Strategic planning and work recommendations.
+
+Provides methods for:
+- Bottleneck identification
+- Parallel work detection
+- Smart recommendations
+- Risk assessment
+- Impact analysis
+- Work queue management
+- Planning spike creation
+- Track creation from plans
+"""
+
+from __future__ import annotations
+
+from htmlgraph.sdk.planning.mixin import PlanningMixin
+
+__all__ = ["PlanningMixin"]

htmlgraph/sdk/planning/bottlenecks.py

@@ -0,0 +1,93 @@
+"""Bottleneck identification for planning."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any
+
+if TYPE_CHECKING:
+    from htmlgraph.types import BottleneckDict
+
+
+def find_bottlenecks(sdk: Any, top_n: int = 5) -> list[BottleneckDict]:
+    """
+    Identify tasks blocking the most downstream work.
+
+    Note: Prefer using sdk.dep_analytics.find_bottlenecks() directly.
+    This method exists for backward compatibility.
+
+    Args:
+        sdk: SDK instance
+        top_n: Maximum number of bottlenecks to return
+
+    Returns:
+        List of bottleneck tasks with impact metrics
+
+    Example:
+        >>> sdk = SDK(agent="claude")
+        >>> # Preferred approach
+        >>> bottlenecks = sdk.dep_analytics.find_bottlenecks(top_n=3)
+        >>> # Or via SDK (backward compatibility)
+        >>> bottlenecks = sdk.find_bottlenecks(top_n=3)
+        >>> for bn in bottlenecks:
+        ...     logger.info(f"{bn['title']} blocks {bn['blocks_count']} tasks")
+    """
+    bottlenecks = sdk.dep_analytics.find_bottlenecks(top_n=top_n)
+
+    # Convert to agent-friendly dict format for backward compatibility
+    return [
+        {
+            "id": bn.id,
+            "title": bn.title,
+            "status": bn.status,
+            "priority": bn.priority,
+            "blocks_count": bn.transitive_blocking,
+            "impact_score": bn.weighted_impact,
+            "blocked_tasks": bn.blocked_nodes[:5],
+        }
+        for bn in bottlenecks
+    ]
+
+
+def assess_risks(sdk: Any) -> dict[str, Any]:
+    """
+    Assess dependency-related risks in the project.
+
+    Note: Prefer using sdk.dep_analytics.assess_dependency_risk() directly.
+    This method exists for backward compatibility.
+
+    Identifies single points of failure, circular dependencies,
+    and orphaned tasks.
+
+    Args:
+        sdk: SDK instance
+
+    Returns:
+        Dict with risk assessment results
+
+    Example:
+        >>> sdk = SDK(agent="claude")
+        >>> # Preferred approach
+        >>> risk = sdk.dep_analytics.assess_dependency_risk()
+        >>> # Or via SDK (backward compatibility)
+        >>> risks = sdk.assess_risks()
+        >>> if risks['high_risk_count'] > 0:
+        ...     logger.info(f"Warning: {risks['high_risk_count']} high-risk tasks")
+    """
+    risk = sdk.dep_analytics.assess_dependency_risk()
+
+    return {
+        "high_risk_count": len(risk.high_risk),
+        "high_risk_tasks": [
+            {
+                "id": node.id,
+                "title": node.title,
+                "risk_score": node.risk_score,
+                "risk_factors": [f.description for f in node.risk_factors],
+            }
+            for node in risk.high_risk
+        ],
+        "circular_dependencies": risk.circular_dependencies,
+        "orphaned_count": len(risk.orphaned_nodes),
+        "orphaned_tasks": risk.orphaned_nodes[:5],
+        "recommendations": risk.recommendations,
+    }

htmlgraph/sdk/planning/mixin.py

@@ -0,0 +1,211 @@
+"""Planning mixin for SDK - integrates all planning functionality."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any
+
+if TYPE_CHECKING:
+    from htmlgraph.models import Node
+    from htmlgraph.types import BottleneckDict
+
+
+class PlanningMixin:
+    """
+    Mixin class providing planning and recommendation methods to SDK.
+
+    This mixin delegates to specialized planning modules for:
+    - Bottleneck identification (bottlenecks.py)
+    - Parallel work detection (parallel.py)
+    - Smart recommendations (recommendations.py)
+    - Work queue management (queue.py)
+    - Planning spike creation (smart_planning.py)
+    - Track creation from plans (smart_planning.py)
+    """
+
+    # =========================================================================
+    # Strategic Planning & Analytics (Agent-Friendly Interface)
+    # =========================================================================
+
+    def find_bottlenecks(self, top_n: int = 5) -> list[BottleneckDict]:
+        """
+        Identify tasks blocking the most downstream work.
+
+        Delegates to sdk.planning.bottlenecks.find_bottlenecks()
+        """
+        from htmlgraph.sdk.planning.bottlenecks import find_bottlenecks
+
+        return find_bottlenecks(self, top_n=top_n)  # type: ignore[arg-type]
+
+    def get_parallel_work(self, max_agents: int = 5) -> dict[str, Any]:
+        """
+        Find tasks that can be worked on simultaneously.
+
+        Delegates to sdk.planning.parallel.get_parallel_work()
+        """
+        from htmlgraph.sdk.planning.parallel import get_parallel_work
+
+        return get_parallel_work(self, max_agents=max_agents)  # type: ignore[arg-type]
+
+    def recommend_next_work(self, agent_count: int = 1) -> list[dict[str, Any]]:
+        """
+        Get smart recommendations for what to work on next.
+
+        Delegates to sdk.planning.recommendations.recommend_next_work()
+        """
+        from htmlgraph.sdk.planning.recommendations import recommend_next_work
+
+        return recommend_next_work(self, agent_count=agent_count)  # type: ignore[arg-type]
+
+    def assess_risks(self) -> dict[str, Any]:
+        """
+        Assess dependency-related risks in the project.
+
+        Delegates to sdk.planning.bottlenecks.assess_risks()
+        """
+        from htmlgraph.sdk.planning.bottlenecks import assess_risks
+
+        return assess_risks(self)  # type: ignore[arg-type]
+
+    def analyze_impact(self, node_id: str) -> dict[str, Any]:
+        """
+        Analyze the impact of completing a specific task.
+
+        Delegates to sdk.planning.recommendations.analyze_impact()
+        """
+        from htmlgraph.sdk.planning.recommendations import analyze_impact
+
+        return analyze_impact(self, node_id)  # type: ignore[arg-type]
+
+    def get_work_queue(
+        self, agent_id: str | None = None, limit: int = 10, min_score: float = 0.0
+    ) -> list[dict[str, Any]]:
+        """
+        Get prioritized work queue showing recommended work, active work, and dependencies.
+
+        Delegates to sdk.planning.queue.get_work_queue()
+        """
+        from htmlgraph.sdk.planning.queue import get_work_queue
+
+        return get_work_queue(self, agent_id=agent_id, limit=limit, min_score=min_score)  # type: ignore[arg-type]
+
+    def work_next(
+        self,
+        agent_id: str | None = None,
+        auto_claim: bool = False,
+        min_score: float = 0.0,
+    ) -> Node | None:
+        """
+        Get the next best task for an agent using smart routing.
+
+        Delegates to sdk.planning.queue.work_next()
+        """
+        from htmlgraph.sdk.planning.queue import work_next
+
+        return work_next(
+            self, agent_id=agent_id, auto_claim=auto_claim, min_score=min_score
+        )  # type: ignore[arg-type]
+
+    # =========================================================================
+    # Planning Workflow Integration
+    # =========================================================================
+
+    def start_planning_spike(
+        self,
+        title: str,
+        context: str = "",
+        timebox_hours: float = 4.0,
+        auto_start: bool = True,
+    ) -> Node:
+        """
+        Create a planning spike to research and design before implementation.
+
+        Delegates to sdk.planning.smart_planning.start_planning_spike()
+        """
+        from htmlgraph.sdk.planning.smart_planning import start_planning_spike
+
+        return start_planning_spike(
+            self,
+            title=title,
+            context=context,
+            timebox_hours=timebox_hours,
+            auto_start=auto_start,
+        )  # type: ignore[arg-type]
+
+    def create_track_from_plan(
+        self,
+        title: str,
+        description: str,
+        spike_id: str | None = None,
+        priority: str = "high",
+        requirements: list[str | tuple[str, str]] | None = None,
+        phases: list[tuple[str, list[str]]] | None = None,
+    ) -> dict[str, Any]:
+        """
+        Create a track with spec and plan from planning results.
+
+        Delegates to sdk.planning.smart_planning.create_track_from_plan()
+        """
+        from htmlgraph.sdk.planning.smart_planning import create_track_from_plan
+
+        return create_track_from_plan(
+            self,  # type: ignore[arg-type]
+            title=title,
+            description=description,
+            spike_id=spike_id,
+            priority=priority,
+            requirements=requirements,
+            phases=phases,
+        )
+
+    def smart_plan(
+        self,
+        description: str,
+        create_spike: bool = True,
+        timebox_hours: float = 4.0,
+        research_completed: bool = False,
+        research_findings: dict[str, Any] | None = None,
+    ) -> dict[str, Any]:
+        """
+        Smart planning workflow: analyzes project context and creates spike or track.
+
+        Delegates to sdk.planning.smart_planning.smart_plan()
+        """
+        from htmlgraph.sdk.planning.smart_planning import smart_plan
+
+        return smart_plan(
+            self,  # type: ignore[arg-type]
+            description=description,
+            create_spike=create_spike,
+            timebox_hours=timebox_hours,
+            research_completed=research_completed,
+            research_findings=research_findings,
+        )
+
+    def plan_parallel_work(
+        self,
+        max_agents: int = 5,
+        shared_files: list[str] | None = None,
+    ) -> dict[str, Any]:
+        """
+        Plan and prepare parallel work execution.
+
+        Delegates to sdk.planning.parallel.plan_parallel_work()
+        """
+        from htmlgraph.sdk.planning.parallel import plan_parallel_work
+
+        return plan_parallel_work(
+            self, max_agents=max_agents, shared_files=shared_files
+        )  # type: ignore[arg-type]
+
+    def aggregate_parallel_results(
+        self,
+        agent_ids: list[str],
+    ) -> dict[str, Any]:
+        """
+        Aggregate results from parallel agent execution.
+
+        Delegates to sdk.planning.parallel.aggregate_parallel_results()
+        """
+        from htmlgraph.sdk.planning.parallel import aggregate_parallel_results
+
+        return aggregate_parallel_results(self, agent_ids=agent_ids)  # type: ignore[arg-type]