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

htmlgraph/sdk/planning/parallel.py

@@ -0,0 +1,186 @@
+"""Parallel work detection and orchestration."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any
+
+if TYPE_CHECKING:
+    pass
+
+
+def get_parallel_work(sdk: Any, max_agents: int = 5) -> dict[str, Any]:
+    """
+    Find tasks that can be worked on simultaneously.
+
+    Note: Prefer using sdk.dep_analytics.find_parallelizable_work() directly.
+    This method exists for backward compatibility.
+
+    Args:
+        sdk: SDK instance
+        max_agents: Maximum number of parallel agents to plan for
+
+    Returns:
+        Dict with parallelization opportunities
+
+    Example:
+        >>> sdk = SDK(agent="claude")
+        >>> # Preferred approach
+        >>> report = sdk.dep_analytics.find_parallelizable_work(status="todo")
+        >>> # Or via SDK (backward compatibility)
+        >>> parallel = sdk.get_parallel_work(max_agents=3)
+        >>> logger.info(f"Can work on {parallel['max_parallelism']} tasks at once")
+        >>> logger.info(f"Ready now: {parallel['ready_now']}")
+    """
+    report = sdk.dep_analytics.find_parallelizable_work(status="todo")
+
+    ready_now = report.dependency_levels[0].nodes if report.dependency_levels else []
+
+    return {
+        "max_parallelism": report.max_parallelism,
+        "ready_now": ready_now[:max_agents],
+        "total_ready": len(ready_now),
+        "level_count": len(report.dependency_levels),
+        "next_level": report.dependency_levels[1].nodes
+        if len(report.dependency_levels) > 1
+        else [],
+    }
+
+
+def plan_parallel_work(
+    sdk: Any,
+    max_agents: int = 5,
+    shared_files: list[str] | None = None,
+) -> dict[str, Any]:
+    """
+    Plan and prepare parallel work execution.
+
+    This integrates with smart_plan to enable parallel agent dispatch.
+    Uses the 6-phase ParallelWorkflow:
+    1. Pre-flight analysis (dependencies, risks)
+    2. Context preparation (shared file caching)
+    3. Prompt generation (for Task tool)
+
+    Args:
+        sdk: SDK instance
+        max_agents: Maximum parallel agents (default: 5)
+        shared_files: Files to pre-cache for all agents
+
+    Returns:
+        Dict with parallel execution plan:
+            - can_parallelize: Whether parallelization is recommended
+            - analysis: Pre-flight analysis results
+            - prompts: Ready-to-use Task tool prompts
+            - recommendations: Optimization suggestions
+
+    Example:
+        >>> sdk = SDK(agent="orchestrator")
+        >>> plan = sdk.plan_parallel_work(max_agents=3)
+        >>> if plan["can_parallelize"]:
+        ...     # Use prompts with Task tool
+        ...     for p in plan["prompts"]:
+        ...         Task(prompt=p["prompt"], description=p["description"])
+    """
+    from htmlgraph.parallel import ParallelWorkflow
+
+    workflow = ParallelWorkflow(sdk)
+
+    # Phase 1: Pre-flight analysis
+    analysis = workflow.analyze(max_agents=max_agents)
+
+    result = {
+        "can_parallelize": analysis.can_parallelize,
+        "max_parallelism": analysis.max_parallelism,
+        "ready_tasks": analysis.ready_tasks,
+        "blocked_tasks": analysis.blocked_tasks,
+        "speedup_factor": analysis.speedup_factor,
+        "recommendation": analysis.recommendation,
+        "warnings": analysis.warnings,
+        "prompts": [],
+    }
+
+    if not analysis.can_parallelize:
+        result["reason"] = analysis.recommendation
+        return result
+
+    # Phase 2 & 3: Prepare tasks and generate prompts
+    tasks = workflow.prepare_tasks(
+        analysis.ready_tasks[:max_agents],
+        shared_files=shared_files,
+    )
+    prompts = workflow.generate_prompts(tasks)
+
+    result["prompts"] = prompts
+    result["task_count"] = len(prompts)
+
+    # Add efficiency guidelines
+    result["guidelines"] = {
+        "dispatch": "Send ALL Task calls in a SINGLE message for true parallelism",
+        "patterns": [
+            "Grep → Read (search before reading)",
+            "Read → Edit → Bash (read, modify, test)",
+            "Glob → Read (find files first)",
+        ],
+        "avoid": [
+            "Sequential Task calls (loses parallelism)",
+            "Read → Read → Read (cache instead)",
+            "Edit → Edit → Edit (batch edits)",
+        ],
+    }
+
+    return result
+
+
+def aggregate_parallel_results(
+    sdk: Any,
+    agent_ids: list[str],
+) -> dict[str, Any]:
+    """
+    Aggregate results from parallel agent execution.
+
+    Call this after parallel agents complete to:
+    - Collect health metrics
+    - Detect anti-patterns
+    - Identify conflicts
+    - Generate recommendations
+
+    Args:
+        sdk: SDK instance
+        agent_ids: List of agent/transcript IDs to analyze
+
+    Returns:
+        Dict with aggregated results and validation
+
+    Example:
+        >>> # After parallel work completes
+        >>> results = sdk.aggregate_parallel_results([
+        ...     "agent-abc123",
+        ...     "agent-def456",
+        ...     "agent-ghi789",
+        ... ])
+        >>> logger.info(f"Health: {results['avg_health_score']:.0%}")
+        >>> logger.info(f"Conflicts: {results['conflicts']}")
+    """
+    from htmlgraph.parallel import ParallelWorkflow
+
+    workflow = ParallelWorkflow(sdk)
+
+    # Phase 5: Aggregate
+    aggregate = workflow.aggregate(agent_ids)
+
+    # Phase 6: Validate
+    validation = workflow.validate(aggregate)
+
+    return {
+        "total_agents": aggregate.total_agents,
+        "successful": aggregate.successful,
+        "failed": aggregate.failed,
+        "total_duration_seconds": aggregate.total_duration_seconds,
+        "parallel_speedup": aggregate.parallel_speedup,
+        "avg_health_score": aggregate.avg_health_score,
+        "total_anti_patterns": aggregate.total_anti_patterns,
+        "files_modified": aggregate.files_modified,
+        "conflicts": aggregate.conflicts,
+        "recommendations": aggregate.recommendations,
+        "validation": validation,
+        "all_passed": all(validation.values()),
+    }

htmlgraph/sdk/planning/queue.py

@@ -0,0 +1,210 @@
+"""Work queue management."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any
+
+if TYPE_CHECKING:
+    from htmlgraph.models import Node
+
+
+def get_work_queue(
+    sdk: Any, 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.
+
+    This method provides a comprehensive view of:
+    1. Recommended next work (using smart analytics)
+    2. Active work by all agents
+    3. Blocked items and what's blocking them
+    4. Priority-based scoring
+
+    Args:
+        sdk: SDK instance
+        agent_id: Agent to get queue for (defaults to SDK agent)
+        limit: Maximum number of items to return (default: 10)
+        min_score: Minimum score threshold (default: 0.0)
+
+    Returns:
+        List of work queue items with scoring and metadata:
+            - task_id: Work item ID
+            - title: Work item title
+            - status: Current status
+            - priority: Priority level
+            - score: Routing score
+            - complexity: Complexity level (if set)
+            - effort: Estimated effort (if set)
+            - blocks_count: Number of tasks this blocks (if any)
+            - blocked_by: List of blocking task IDs (if blocked)
+            - agent_assigned: Current assignee (if any)
+            - type: Work item type (feature, bug, spike, etc.)
+
+    Example:
+        >>> sdk = SDK(agent="claude")
+        >>> queue = sdk.get_work_queue(limit=5)
+        >>> for item in queue:
+        ...     logger.info(f"{item['score']:.1f} - {item['title']}")
+        ...     if item.get('blocked_by'):
+        ...         logger.info(f"  ⚠️  Blocked by: {', '.join(item['blocked_by'])}")
+    """
+    from htmlgraph.routing import AgentCapabilityRegistry, CapabilityMatcher
+
+    agent = agent_id or sdk._agent_id or "cli"
+
+    # Get all work item types
+    all_work = []
+    for collection_name in ["features", "bugs", "spikes", "chores", "epics"]:
+        collection = getattr(sdk, collection_name, None)
+        if collection:
+            # Get todo and blocked items
+            for item in collection.where(status="todo"):
+                all_work.append(item)
+            for item in collection.where(status="blocked"):
+                all_work.append(item)
+
+    if not all_work:
+        return []
+
+    # Get recommendations from analytics (uses strategic scoring)
+    from htmlgraph.sdk.planning.recommendations import recommend_next_work
+
+    recommendations = recommend_next_work(sdk, agent_count=limit * 2)
+    rec_scores = {rec["id"]: rec["score"] for rec in recommendations}
+
+    # Build routing registry
+    registry = AgentCapabilityRegistry()
+
+    # Register current agent
+    registry.register_agent(agent, capabilities=[], wip_limit=5)
+
+    # Get current WIP count for agent
+    wip_count = len(sdk.features.where(status="in-progress", agent_assigned=agent))
+    registry.set_wip(agent, wip_count)
+
+    # Score each work item
+    queue_items = []
+    for item in all_work:
+        # Use strategic score if available, otherwise use routing score
+        if item.id in rec_scores:
+            score = rec_scores[item.id]
+        else:
+            # Fallback to routing score
+            agent_profile = registry.get_agent(agent)
+            if agent_profile:
+                score = CapabilityMatcher.score_agent_task_fit(agent_profile, item)
+            else:
+                score = 0.0
+
+        # Apply minimum score filter
+        if score < min_score:
+            continue
+
+        # Build queue item
+        queue_item = {
+            "task_id": item.id,
+            "title": item.title,
+            "status": item.status,
+            "priority": item.priority,
+            "score": score,
+            "type": item.type,
+            "complexity": getattr(item, "complexity", None),
+            "effort": getattr(item, "estimated_effort", None),
+            "agent_assigned": getattr(item, "agent_assigned", None),
+            "blocks_count": 0,
+            "blocked_by": [],
+        }
+
+        # Add dependency information
+        if hasattr(item, "edges"):
+            # Check if this item blocks others
+            blocks = item.edges.get("blocks", [])
+            queue_item["blocks_count"] = len(blocks)
+
+            # Check if this item is blocked
+            blocked_by = item.edges.get("blocked_by", [])
+            queue_item["blocked_by"] = blocked_by
+
+        queue_items.append(queue_item)
+
+    # Sort by score (descending)
+    queue_items.sort(key=lambda x: x["score"], reverse=True)
+
+    # Limit results
+    return queue_items[:limit]
+
+
+def work_next(
+    sdk: Any,
+    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.
+
+    Uses both strategic analytics and capability-based routing to find
+    the optimal next task.
+
+    Args:
+        sdk: SDK instance
+        agent_id: Agent to get task for (defaults to SDK agent)
+        auto_claim: Automatically claim the task (default: False)
+        min_score: Minimum score threshold (default: 0.0)
+
+    Returns:
+        Next best Node or None if no suitable task found
+
+    Example:
+        >>> sdk = SDK(agent="claude")
+        >>> task = sdk.work_next(auto_claim=True)
+        >>> if task:
+        ...     logger.info(f"Working on: {task.title}")
+        ...     # Task is automatically claimed and assigned
+    """
+    agent = agent_id or sdk._agent_id or "cli"
+
+    # Get work queue - get more items since we filter for actionable (todo) only
+    queue = get_work_queue(sdk, agent_id=agent, limit=20, min_score=min_score)
+
+    if not queue:
+        return None
+
+    # Find the first actionable (todo) task - blocked tasks are not actionable
+    top_item = None
+    for item in queue:
+        if item["status"] == "todo":
+            top_item = item
+            break
+
+    if top_item is None:
+        return None
+
+    # Fetch the actual node
+    task = None
+    for collection_name in ["features", "bugs", "spikes", "chores", "epics"]:
+        collection = getattr(sdk, collection_name, None)
+        if collection:
+            try:
+                task = collection.get(top_item["task_id"])
+                if task:
+                    break
+            except (ValueError, FileNotFoundError):
+                continue
+
+    if not task:
+        return None
+
+    # Auto-claim if requested
+    if auto_claim and task.status == "todo" and collection is not None:
+        # Claim the task
+        # collection.edit returns context manager or None
+        task_editor: Any = collection.edit(task.id)
+        if task_editor is not None:
+            # collection.edit returns context manager
+            with task_editor as t:
+                t.status = "in-progress"
+                t.agent_assigned = agent
+
+    result: Node | None = task
+    return result

htmlgraph/sdk/planning/recommendations.py

@@ -0,0 +1,87 @@
+"""Smart work recommendations."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any
+
+if TYPE_CHECKING:
+    pass
+
+
+def recommend_next_work(sdk: Any, agent_count: int = 1) -> list[dict[str, Any]]:
+    """
+    Get smart recommendations for what to work on next.
+
+    Note: Prefer using sdk.dep_analytics.recommend_next_tasks() directly.
+    This method exists for backward compatibility.
+
+    Considers priority, dependencies, and transitive impact.
+
+    Args:
+        sdk: SDK instance
+        agent_count: Number of agents/tasks to recommend
+
+    Returns:
+        List of recommended tasks with reasoning
+
+    Example:
+        >>> sdk = SDK(agent="claude")
+        >>> # Preferred approach
+        >>> recs = sdk.dep_analytics.recommend_next_tasks(agent_count=3)
+        >>> # Or via SDK (backward compatibility)
+        >>> recs = sdk.recommend_next_work(agent_count=3)
+        >>> for rec in recs:
+        ...     logger.info(f"{rec['title']} (score: {rec['score']})")
+        ...     logger.info(f"  Reasons: {rec['reasons']}")
+    """
+    recommendations = sdk.dep_analytics.recommend_next_tasks(
+        agent_count=agent_count, lookahead=5
+    )
+
+    return [
+        {
+            "id": rec.id,
+            "title": rec.title,
+            "priority": rec.priority,
+            "score": rec.score,
+            "reasons": rec.reasons,
+            "estimated_hours": rec.estimated_effort,
+            "unlocks_count": len(rec.unlocks),
+            "unlocks": rec.unlocks[:3],
+        }
+        for rec in recommendations.recommendations
+    ]
+
+
+def analyze_impact(sdk: Any, node_id: str) -> dict[str, Any]:
+    """
+    Analyze the impact of completing a specific task.
+
+    Note: Prefer using sdk.dep_analytics.impact_analysis() directly.
+    This method exists for backward compatibility.
+
+    Args:
+        sdk: SDK instance
+        node_id: Task to analyze
+
+    Returns:
+        Dict with impact analysis
+
+    Example:
+        >>> sdk = SDK(agent="claude")
+        >>> # Preferred approach
+        >>> impact = sdk.dep_analytics.impact_analysis("feature-001")
+        >>> # Or via SDK (backward compatibility)
+        >>> impact = sdk.analyze_impact("feature-001")
+        >>> logger.info(f"Completing this unlocks {impact['unlocks_count']} tasks")
+    """
+    impact = sdk.dep_analytics.impact_analysis(node_id)
+
+    return {
+        "node_id": node_id,
+        "direct_dependents": impact.direct_dependents,
+        "total_impact": impact.transitive_dependents,
+        "completion_impact": impact.completion_impact,
+        "unlocks_count": len(impact.affected_nodes),
+        "affected_tasks": impact.affected_nodes[:10],
+    }