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

htmlgraph/agents.py

@@ -1,19 +1,85 @@
 """
-Agent interface for HtmlGraph.
-
-Provides a simplified API for AI agents with:
-- Lightweight context generation
-- Task claiming and completion
-- Progress tracking
+Agent interface for simplified task management.
+
+IMPERATIVE USAGE INSTRUCTIONS
+=============================
+
+The AgentInterface provides lightweight task claiming and progress tracking.
+
+TASK LIFECYCLE
+==============
+
+1. CLAIM A TASK
+   ```python
+   from htmlgraph.agents import AgentInterface
+
+   agent = AgentInterface("features/")
+   task = agent.get_next_task(
+       agent_id="claude",
+       priority="high",  # Optional filter
+       auto_claim=True   # Automatically claim the task
+   )
+   ```
+
+2. WORK ON TASK
+   ```python
+   # Get lightweight context for LLM
+   context = agent.get_context(task.id)
+   # Returns: "# feature-001: Title\\nStatus: in-progress..."
+
+   # Complete steps as you work
+   agent.complete_step(task.id, step_index=0, agent_id="claude")
+   agent.complete_step(task.id, step_index=1, agent_id="claude")
+   ```
+
+3. COMPLETE TASK
+   ```python
+   agent.complete_task(task.id, agent_id="claude")
+   ```
+
+4. IF BLOCKED
+   ```python
+   agent.release_task(task.id, agent_id="claude")
+   # Task becomes available for other agents
+   ```
+
+DISCOVERY METHODS
+=================
+
+| Method | Purpose |
+|--------|---------|
+| `get_available_tasks()` | Find all matching tasks |
+| `get_next_task()` | Get single next task |
+| `get_blocked_tasks()` | Find blocked work |
+| `get_in_progress_tasks()` | Get agent's active work |
+
+ANTI-PATTERNS
+=============
+
+NEVER:
+- Work on unclaimed tasks
+- Skip step completion updates
+- Leave tasks in-progress when blocked
+
+ALWAYS:
+- Claim before working
+- Update progress incrementally
+- Release if you can't complete
+
+Available Classes
+=================
+
+AgentInterface: Simplified interface for task management
+AgentRegistry: Capability-based agent routing
 """
 
 from datetime import datetime
 from pathlib import Path
-from typing import Any
+from typing import Any, Literal, cast
 
-from htmlgraph.models import Node, Step
+from htmlgraph.agent_registry import AgentProfile, AgentRegistry
 from htmlgraph.graph import HtmlGraph
-from htmlgraph.agent_registry import AgentRegistry, AgentProfile
+from htmlgraph.models import Node, Step
 
 
 class AgentInterface:
@@ -34,11 +100,7 @@ class AgentInterface:
         agent.complete_task(task.id, agent_id="claude")
     """
 
-    def __init__(
-        self,
-        directory: Path | str,
-        agent_id: str | None = None
-    ):
+    def __init__(self, directory: Path | str, agent_id: str | None = None):
         """
         Initialize agent interface.
 
@@ -51,7 +113,11 @@ class AgentInterface:
 
         # Initialize agent registry for capability-based routing
         # Assumes .htmlgraph is parent of directory
-        htmlgraph_dir = Path(directory).parent if Path(directory).name == "features" else Path(directory)
+        htmlgraph_dir = (
+            Path(directory).parent
+            if Path(directory).name == "features"
+            else Path(directory)
+        )
         self.registry = AgentRegistry(htmlgraph_dir)
 
     def reload(self) -> None:
@@ -67,7 +133,7 @@ class AgentInterface:
         status: str = "todo",
         priority: str | None = None,
         node_type: str | None = None,
-        limit: int = 10
+        limit: int = 10,
     ) -> list[Node]:
         """
         Get available tasks matching criteria.
@@ -81,6 +147,7 @@ class AgentInterface:
         Returns:
             List of matching nodes, sorted by priority
         """
+
         def matches(node: Node) -> bool:
             if node.status != status:
                 return False
@@ -106,7 +173,7 @@ class AgentInterface:
         agent_id: str | None = None,
         priority: str | None = None,
         node_type: str | None = None,
-        auto_claim: bool = False
+        auto_claim: bool = False,
     ) -> Node | None:
         """
         Get the next available task.
@@ -122,9 +189,7 @@ class AgentInterface:
         """
         agent_id = agent_id or self.agent_id
         tasks = self.get_available_tasks(
-            priority=priority,
-            node_type=node_type,
-            limit=1
+            priority=priority, node_type=node_type, limit=1
         )
 
         if not tasks:
@@ -135,7 +200,9 @@ class AgentInterface:
         if auto_claim and agent_id:
             self.claim_task(task.id, agent_id)
             # Reload to get updated state
-            task = self.graph.get(task.id)
+            reloaded_task = self.graph.get(task.id)
+            if reloaded_task:
+                task = reloaded_task
 
         return task
 
@@ -158,10 +225,7 @@ class AgentInterface:
         return tasks
 
     def get_tasks_by_capability(
-        self,
-        agent_capabilities: list[str],
-        status: str = "todo",
-        limit: int = 10
+        self, agent_capabilities: list[str], status: str = "todo", limit: int = 10
     ) -> list[Node]:
         """
         Get tasks that match agent capabilities.
@@ -176,6 +240,7 @@ class AgentInterface:
         Returns:
             List of matching nodes, prioritized by exact matches first
         """
+
         def matches(node: Node) -> bool:
             if node.status != status:
                 return False
@@ -193,10 +258,11 @@ class AgentInterface:
         # Sort by capability match quality
         agent_caps = set(agent_capabilities)
 
-        def capability_score(node: Node) -> tuple[int, str]:
-            """Return (negative_exact_matches, priority) for sorting."""
+        def capability_score(node: Node) -> tuple[int, int]:
+            """Return (negative_exact_matches, priority_order) for sorting."""
             if not node.required_capabilities:
-                return (0, node.priority)
+                priority_order = {"critical": 0, "high": 1, "medium": 2, "low": 3}
+                return (0, priority_order.get(node.priority, 99))
             exact_matches = len(set(node.required_capabilities) & agent_caps)
             # Sort by exact matches (descending), then by priority
             priority_order = {"critical": 0, "high": 1, "medium": 2, "low": 3}
@@ -210,7 +276,7 @@ class AgentInterface:
         self,
         agent_capabilities: list[str],
         agent_id: str | None = None,
-        auto_claim: bool = False
+        auto_claim: bool = False,
     ) -> Node | None:
         """
         Get next task matching agent capabilities.
@@ -234,7 +300,9 @@ class AgentInterface:
         if auto_claim and agent_id:
             self.claim_task(task.id, agent_id)
             # Reload to get updated state
-            task = self.graph.get(task.id)
+            reloaded_task = self.graph.get(task.id)
+            if reloaded_task:
+                task = reloaded_task
 
         return task
 
@@ -332,10 +400,7 @@ class AgentInterface:
         return True
 
     def block_task(
-        self,
-        node_id: str,
-        blocked_by: str,
-        reason: str | None = None
+        self, node_id: str, blocked_by: str, reason: str | None = None
     ) -> bool:
         """
         Mark a task as blocked.
@@ -357,11 +422,12 @@ class AgentInterface:
 
         # Add blocking edge if not present
         from htmlgraph.models import Edge
+
         blocking_edge = Edge(
             target_id=blocked_by,
             relationship="blocked_by",
             since=datetime.now(),
-            properties={"reason": reason} if reason else {}
+            properties={"reason": reason} if reason else {},
         )
         node.add_edge(blocking_edge)
 
@@ -373,10 +439,7 @@ class AgentInterface:
     # =========================================================================
 
     def complete_step(
-        self,
-        node_id: str,
-        step_index: int,
-        agent_id: str | None = None
+        self, node_id: str, step_index: int, agent_id: str | None = None
     ) -> bool:
         """
         Mark a step as completed.
@@ -401,11 +464,7 @@ class AgentInterface:
 
         return False
 
-    def add_step(
-        self,
-        node_id: str,
-        description: str
-    ) -> bool:
+    def add_step(self, node_id: str, description: str) -> bool:
         """
         Add a new step to a task.
 
@@ -532,9 +591,7 @@ class AgentInterface:
     # =========================================================================
 
     def find_bottlenecks(
-        self,
-        top_n: int = 5,
-        status_filter: list[str] | None = None
+        self, top_n: int = 5, status_filter: list[str] | None = None
     ) -> list[dict[str, Any]]:
         """
         Identify tasks blocking the most downstream work.
@@ -555,8 +612,7 @@ class AgentInterface:
 
         analytics = DependencyAnalytics(self.graph)
         bottlenecks = analytics.find_bottlenecks(
-            status_filter=status_filter,
-            top_n=top_n
+            status_filter=status_filter, top_n=top_n
         )
 
         # Convert to agent-friendly dict format
@@ -568,15 +624,13 @@ class AgentInterface:
                 "priority": bn.priority,
                 "blocks_count": bn.transitive_blocking,
                 "impact_score": bn.weighted_impact,
-                "blocked_tasks": bn.blocked_nodes[:5]  # Limit for readability
+                "blocked_tasks": bn.blocked_nodes[:5],  # Limit for readability
             }
             for bn in bottlenecks
         ]
 
     def get_parallel_work(
-        self,
-        status: str = "todo",
-        max_agents: int = 5
+        self, status: str = "todo", max_agents: int = 5
     ) -> dict[str, Any]:
         """
         Find tasks that can be worked on simultaneously.
@@ -598,20 +652,22 @@ class AgentInterface:
         analytics = DependencyAnalytics(self.graph)
         report = analytics.find_parallelizable_work(status=status)
 
-        ready_now = report.dependency_levels[0].nodes if report.dependency_levels else []
+        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 []
+            "next_level": report.dependency_levels[1].nodes
+            if len(report.dependency_levels) > 1
+            else [],
         }
 
     def recommend_next_work(
-        self,
-        agent_count: int = 1,
-        lookahead: int = 5
+        self, agent_count: int = 1, lookahead: int = 5
     ) -> list[dict[str, Any]]:
         """
         Get smart recommendations for what to work on next.
@@ -635,8 +691,7 @@ class AgentInterface:
 
         analytics = DependencyAnalytics(self.graph)
         recommendations = analytics.recommend_next_tasks(
-            agent_count=agent_count,
-            lookahead=lookahead
+            agent_count=agent_count, lookahead=lookahead
         )
 
         return [
@@ -648,7 +703,7 @@ class AgentInterface:
                 "reasons": rec.reasons,
                 "estimated_hours": rec.estimated_effort,
                 "unlocks_count": len(rec.unlocks),
-                "unlocks": rec.unlocks[:3]  # Show first 3
+                "unlocks": rec.unlocks[:3],  # Show first 3
             }
             for rec in recommendations.recommendations
         ]
@@ -682,14 +737,14 @@ class AgentInterface:
                     "id": node.id,
                     "title": node.title,
                     "risk_score": node.risk_score,
-                    "risk_factors": [f.description for f in node.risk_factors]
+                    "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],  # First 5
-            "recommendations": risk.recommendations
+            "recommendations": risk.recommendations,
         }
 
     def analyze_impact(self, node_id: str) -> dict[str, Any]:
@@ -720,7 +775,7 @@ class AgentInterface:
             "total_impact": impact.transitive_dependents,
             "completion_impact": impact.completion_impact,
             "unlocks_count": len(impact.affected_nodes),
-            "affected_tasks": impact.affected_nodes[:10]  # First 10
+            "affected_tasks": impact.affected_nodes[:10],  # First 10
         }
 
     # =========================================================================
@@ -734,7 +789,7 @@ class AgentInterface:
         description: str = "",
         priority: str = "medium",
         node_type: str = "task",
-        steps: list[str] | None = None
+        steps: list[str] | None = None,
     ) -> Node:
         """
         Create a new task.
@@ -754,9 +809,9 @@ class AgentInterface:
             id=task_id,
             title=title,
             type=node_type,
-            priority=priority,
+            priority=cast(Literal["low", "medium", "high", "critical"], priority),
             content=f"<p>{description}</p>" if description else "",
-            steps=[Step(description=s) for s in (steps or [])]
+            steps=[Step(description=s) for s in (steps or [])],
         )
 
         self.graph.add(node)
@@ -785,7 +840,7 @@ class AgentInterface:
             "agent_id": agent_id,
             "in_progress": len(in_progress),
             "completed": len(completed),
-            "tasks": [t.id for t in in_progress]
+            "tasks": [t.id for t in in_progress],
         }
 
     # =========================================================================
@@ -793,10 +848,7 @@ class AgentInterface:
     # =========================================================================
 
     def calculate_task_score(
-        self,
-        task: Node,
-        agent: AgentProfile,
-        current_workload: int = 0
+        self, task: Node, agent: AgentProfile, current_workload: int = 0
     ) -> float:
         """
         Calculate routing score for a task-agent pair.
@@ -814,12 +866,7 @@ class AgentInterface:
         score = 0.0
 
         # Priority score (0-30 points)
-        priority_scores = {
-            "critical": 30,
-            "high": 20,
-            "medium": 10,
-            "low": 5
-        }
+        priority_scores = {"critical": 30, "high": 20, "medium": 10, "low": 5}
         score += priority_scores.get(task.priority, 5)
 
         # Capability match score (0-40 points)
@@ -828,24 +875,27 @@ class AgentInterface:
                 # Perfect match gets 40 points
                 score += 40
                 # Bonus for exact capability match (no extra capabilities)
-                matching_caps = sum(1 for cap in task.required_capabilities if cap in agent.capabilities)
+                matching_caps = sum(
+                    1 for cap in task.required_capabilities if cap in agent.capabilities
+                )
                 score += (matching_caps / len(task.required_capabilities)) * 5
             else:
                 # No match = very low score
                 score = max(score - 30, 0)
 
         # Complexity match score (0-20 points)
-        if task.complexity:
-            if agent.can_handle_complexity(task.complexity):
+        task_complexity = getattr(task, "complexity", None)
+        if task_complexity:
+            if agent.can_handle_complexity(task_complexity):
                 score += 20
                 # Bonus for preferred complexity
                 complexity_preference = {
                     "low": 2,
                     "medium": 5,
                     "high": 3,
-                    "very-high": 1
+                    "very-high": 1,
                 }
-                score += complexity_preference.get(task.complexity, 0)
+                score += complexity_preference.get(task_complexity, 0)
             else:
                 score = max(score - 15, 0)
 
@@ -865,9 +915,7 @@ class AgentInterface:
         return len(in_progress)
 
     def find_best_match(
-        self,
-        task: Node,
-        candidate_agents: list[str] | None = None
+        self, task: Node, candidate_agents: list[str] | None = None
     ) -> tuple[str, float] | None:
         """
         Find the best agent for a task using smart routing.
@@ -880,15 +928,16 @@ class AgentInterface:
             Tuple of (agent_id, score) or None if no match
         """
         # Get candidate agents
+        agents: list[AgentProfile]
         if candidate_agents:
-            agents = [self.registry.get(aid) for aid in candidate_agents]
-            agents = [a for a in agents if a and a.active]
+            agents_maybe = [self.registry.get(aid) for aid in candidate_agents]
+            agents = [a for a in agents_maybe if a and a.active]
         else:
             # Find capable agents based on requirements
-            if task.required_capabilities:
+            required_caps = getattr(task, "required_capabilities", None)
+            if required_caps:
                 agents = self.registry.find_capable_agents(
-                    task.required_capabilities,
-                    task.complexity
+                    required_caps, getattr(task, "complexity", None)
                 )
             else:
                 # No requirements, all active agents
@@ -914,10 +963,7 @@ class AgentInterface:
         return None
 
     def get_work_queue(
-        self,
-        agent_id: str | None = None,
-        limit: int = 10,
-        min_score: float = 20.0
+        self, agent_id: str | None = None, limit: int = 10, min_score: float = 20.0
     ) -> list[dict[str, Any]]:
         """
         Get prioritized work queue for an agent using smart routing.
@@ -949,19 +995,26 @@ class AgentInterface:
             score = self.calculate_task_score(task, agent, workload)
 
             if score >= min_score:
-                queue.append({
-                    "task_id": task.id,
-                    "title": task.title,
-                    "priority": task.priority,
-                    "status": task.status,
-                    "score": round(score, 2),
-                    "required_capabilities": task.required_capabilities,
-                    "complexity": task.complexity,
-                    "estimated_effort": task.estimated_effort
-                })
+                queue.append(
+                    {
+                        "task_id": task.id,
+                        "title": task.title,
+                        "priority": task.priority,
+                        "status": task.status,
+                        "score": round(score, 2),
+                        "required_capabilities": getattr(
+                            task, "required_capabilities", None
+                        ),
+                        "complexity": getattr(task, "complexity", None),
+                        "estimated_effort": getattr(task, "estimated_effort", None),
+                    }
+                )
 
         # Sort by score (highest first)
-        queue.sort(key=lambda x: x["score"], reverse=True)
+        queue.sort(
+            key=lambda x: float(x["score"]) if x["score"] is not None else 0.0,
+            reverse=True,
+        )
 
         return queue[:limit]
 
@@ -969,7 +1022,7 @@ class AgentInterface:
         self,
         agent_id: str | None = None,
         auto_claim: bool = False,
-        min_score: float = 20.0
+        min_score: float = 20.0,
     ) -> Node | None:
         """
         Get next task using smart routing based on capabilities.

htmlgraph/analytics/__init__.py

@@ -1,13 +1,20 @@
 """
 Analytics modules for HtmlGraph.
 
-Provides work type analysis, dependency analytics, and CLI analytics.
+Provides work type analysis, dependency analytics, cross-session analytics, CLI analytics,
+and cost attribution analysis for OTEL ROI.
 """
 
-from htmlgraph.analytics.work_type import Analytics
+from htmlgraph.analytics.cost_analyzer import CostAnalyzer
+from htmlgraph.analytics.cost_reporter import CostReporter
+from htmlgraph.analytics.cross_session import CrossSessionAnalytics
 from htmlgraph.analytics.dependency import DependencyAnalytics
+from htmlgraph.analytics.work_type import Analytics
 
 __all__ = [
     "Analytics",
     "DependencyAnalytics",
+    "CrossSessionAnalytics",
+    "CostAnalyzer",
+    "CostReporter",
 ]