htmlgraph 0.24.1__py3-none-any.whl → 0.25.0__py3-none-any.whl

htmlgraph/builders/epic.py

@@ -8,10 +8,10 @@ child features and milestones.
 from __future__ import annotations
 
 from datetime import date
-from typing import TYPE_CHECKING
+from typing import TYPE_CHECKING, Any
 
 if TYPE_CHECKING:
-    pass
+    from htmlgraph.sdk import SDK
 
 from htmlgraph.builders.base import BaseBuilder
 
@@ -38,6 +38,21 @@ class EpicBuilder(BaseBuilder["EpicBuilder"]):
 
     node_type = "epic"
 
+    def __init__(self, sdk: SDK, title: str, **kwargs: Any):
+        """Initialize epic builder with agent attribution."""
+        super().__init__(sdk, title, **kwargs)
+        # Auto-assign agent from SDK for work tracking
+        if sdk._agent_id:
+            self._data["agent_assigned"] = sdk._agent_id
+        elif "agent_assigned" not in self._data:
+            # Log warning if agent not assigned (defensive check)
+            import logging
+
+            logging.warning(
+                f"Creating epic '{self._data.get('title', 'Unknown')}' without agent attribution. "
+                "Pass agent='name' to SDK() initialization."
+            )
+
     def add_child_feature(self, feature_id: str) -> EpicBuilder:
         """
         Add a feature as a child of this epic.

htmlgraph/builders/feature.py

@@ -7,10 +7,10 @@ capability management.
 
 from __future__ import annotations
 
-from typing import TYPE_CHECKING
+from typing import TYPE_CHECKING, Any
 
 if TYPE_CHECKING:
-    pass
+    from htmlgraph.sdk import SDK
 
 from htmlgraph.builders.base import BaseBuilder
 
@@ -34,6 +34,29 @@ class FeatureBuilder(BaseBuilder["FeatureBuilder"]):
 
     node_type = "feature"
 
+    def __init__(self, sdk: SDK, title: str, **kwargs: Any):
+        """Initialize feature builder with agent attribution and validation."""
+        # Validate title before creating builder
+
+        stripped_title = title.strip() if title else ""
+        if not stripped_title:
+            raise ValueError("Feature title cannot be empty or whitespace only")
+        if len(stripped_title) < 3:
+            raise ValueError("Feature title must be at least 3 characters")
+
+        super().__init__(sdk, title, **kwargs)
+        # Auto-assign agent from SDK for work tracking
+        if sdk._agent_id:
+            self._data["agent_assigned"] = sdk._agent_id
+        elif "agent_assigned" not in self._data:
+            # Log warning if agent not assigned (defensive check)
+            import logging
+
+            logging.warning(
+                f"Creating feature '{self._data.get('title', 'Unknown')}' without agent attribution. "
+                "Pass agent='name' to SDK() initialization."
+            )
+
     def set_required_capabilities(self, capabilities: list[str]) -> FeatureBuilder:
         """
         Set required capabilities for this feature.

htmlgraph/builders/phase.py

@@ -8,10 +8,10 @@ phase ordering and dependencies.
 from __future__ import annotations
 
 from datetime import date
-from typing import TYPE_CHECKING
+from typing import TYPE_CHECKING, Any
 
 if TYPE_CHECKING:
-    pass
+    from htmlgraph.sdk import SDK
 
 from htmlgraph.builders.base import BaseBuilder
 
@@ -37,6 +37,21 @@ class PhaseBuilder(BaseBuilder["PhaseBuilder"]):
 
     node_type = "phase"
 
+    def __init__(self, sdk: SDK, title: str, **kwargs: Any):
+        """Initialize phase builder with agent attribution."""
+        super().__init__(sdk, title, **kwargs)
+        # Auto-assign agent from SDK for work tracking
+        if sdk._agent_id:
+            self._data["agent_assigned"] = sdk._agent_id
+        elif "agent_assigned" not in self._data:
+            # Log warning if agent not assigned (defensive check)
+            import logging
+
+            logging.warning(
+                f"Creating phase '{self._data.get('title', 'Unknown')}' without agent attribution. "
+                "Pass agent='name' to SDK() initialization."
+            )
+
     def set_phase_number(self, number: int) -> PhaseBuilder:
         """
         Set the phase number for ordering.

htmlgraph/builders/spike.py

@@ -48,6 +48,18 @@ class SpikeBuilder(BaseBuilder["SpikeBuilder"]):
             self._data["spike_type"] = SpikeType.GENERAL
         if "timebox_hours" not in self._data:
             self._data["timebox_hours"] = 4
+        # Auto-assign agent from SDK (critical for work tracking)
+        if sdk._agent_id:
+            self._data["agent_assigned"] = sdk._agent_id
+        elif "agent_assigned" not in self._data:
+            # This should never happen now because SDK enforces agent parameter,
+            # but log warning if it does occur (for debugging)
+            import logging
+
+            logging.warning(
+                f"Creating spike '{self._data.get('title', 'Unknown')}' without agent attribution. "
+                "This will make work tracking impossible. Pass agent='name' to SDK() initialization."
+            )
 
     def set_spike_type(self, spike_type: SpikeType) -> SpikeBuilder:
         """
@@ -86,15 +98,28 @@ class SpikeBuilder(BaseBuilder["SpikeBuilder"]):
         Set the findings/learnings from spike investigation.
 
         Args:
-            findings: Summary of what was learned
+            findings: Summary of what was learned (must be non-empty, min 10 chars)
 
         Returns:
             Self for method chaining
 
+        Raises:
+            ValueError: If findings are empty or too short
+
         Example:
             >>> spike.set_findings("OAuth2 is best fit. Recommend Auth0.")
         """
-        self._data["findings"] = findings
+        # Validate findings quality
+        stripped = findings.strip() if findings else ""
+        if not stripped:
+            raise ValueError(
+                "Findings cannot be empty. Provide meaningful investigation results."
+            )
+        if len(stripped) < 10:
+            raise ValueError(
+                "Findings must be at least 10 characters. Provide detailed results."
+            )
+        self._data["findings"] = stripped
         return self
 
     def set_decision(self, decision: str) -> SpikeBuilder:

htmlgraph/builders/track.py

@@ -679,3 +679,17 @@ class TrackBuilder:
             print(f"  - Plan with {len(self._plan_phases)} phases, {total_tasks} tasks")
 
         return track
+
+    def save(self) -> Track:
+        """
+        Save/create the track (alias for create()).
+
+        Provides API consistency with other builders.
+
+        Returns:
+            Track object that was created
+
+        Example:
+            track = sdk.tracks.create("My Track").save()
+        """
+        return self.create()

htmlgraph/cigs/__init__.py

@@ -10,6 +10,7 @@ Modules:
 - cost: Cost calculation and efficiency metrics
 - patterns: Anti-pattern detection and analysis
 - autonomy: Autonomy level management
+- reporter: Dashboard generation for cost analysis
 """
 
 from htmlgraph.cigs.autonomy import AutonomyRecommender
@@ -42,6 +43,7 @@ from htmlgraph.cigs.patterns import (
     detect_patterns,
 )
 from htmlgraph.cigs.posttool_analyzer import CIGSPostToolAnalyzer
+from htmlgraph.cigs.reporter import CostReporter
 from htmlgraph.cigs.tracker import ViolationTracker
 
 __all__ = [
@@ -74,4 +76,6 @@ __all__ = [
     "ViolationTracker",
     # PostTool Analysis
     "CIGSPostToolAnalyzer",
+    # Reporter
+    "CostReporter",
 ]