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

htmlgraph/builders/chore.py

@@ -1,3 +1,5 @@
+from __future__ import annotations
+
 """
 Chore builder for creating maintenance task nodes.
 
@@ -5,12 +7,11 @@ Extends BaseBuilder with chore-specific methods like
 chore type and recurrence.
 """
 
-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
 
@@ -36,6 +37,21 @@ class ChoreBuilder(BaseBuilder["ChoreBuilder"]):
 
     node_type = "chore"
 
+    def __init__(self, sdk: SDK, title: str, **kwargs: Any):
+        """Initialize chore 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 chore '{self._data.get('title', 'Unknown')}' without agent attribution. "
+                "Pass agent='name' to SDK() initialization."
+            )
+
     def set_chore_type(self, chore_type: str) -> ChoreBuilder:
         """
         Set the type of chore.

htmlgraph/builders/epic.py

@@ -1,3 +1,5 @@
+from __future__ import annotations
+
 """
 Epic builder for creating large body of work nodes.
 
@@ -5,13 +7,12 @@ Extends BaseBuilder with epic-specific methods like
 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 +39,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

@@ -1,3 +1,5 @@
+from __future__ import annotations
+
 """
 Feature builder for creating feature nodes.
 
@@ -5,12 +7,11 @@ Extends BaseBuilder with feature-specific methods like
 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 +35,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/insight.py

@@ -1,3 +1,5 @@
+from __future__ import annotations
+
 """
 Insight builder for creating session insight nodes.
 
@@ -5,7 +7,6 @@ Extends BaseBuilder with insight-specific methods for
 session health scoring and pattern detection.
 """
 
-from __future__ import annotations
 
 from typing import TYPE_CHECKING, Any
 

htmlgraph/builders/metric.py

@@ -1,3 +1,5 @@
+from __future__ import annotations
+
 """
 Metric builder for creating aggregated metric nodes.
 
@@ -5,7 +7,6 @@ Extends BaseBuilder with metric-specific methods for
 time-series aggregation and trend analysis.
 """
 
-from __future__ import annotations
 
 from datetime import datetime
 from typing import TYPE_CHECKING, Any

htmlgraph/builders/pattern.py

@@ -1,3 +1,5 @@
+from __future__ import annotations
+
 """
 Pattern builder for creating workflow pattern nodes.
 
@@ -5,7 +7,6 @@ Extends BaseBuilder with pattern-specific methods for
 tracking optimal and anti-pattern tool sequences.
 """
 
-from __future__ import annotations
 
 from datetime import datetime
 from typing import TYPE_CHECKING, Any

htmlgraph/builders/phase.py

@@ -1,3 +1,5 @@
+from __future__ import annotations
+
 """
 Phase builder for creating project phase nodes.
 
@@ -5,13 +7,12 @@ Extends BaseBuilder with phase-specific methods like
 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 +38,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

@@ -1,3 +1,5 @@
+from __future__ import annotations
+
 """
 Spike builder for creating spike investigation nodes.
 
@@ -5,7 +7,6 @@ Extends BaseBuilder with spike-specific methods like
 spike_type and timebox_hours.
 """
 
-from __future__ import annotations
 
 from typing import TYPE_CHECKING, Any
 
@@ -48,6 +49,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 +99,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

@@ -1,8 +1,9 @@
+from __future__ import annotations
+
 """
 Track Builder for agent-friendly track creation.
 """
 
-from __future__ import annotations
 
 import re
 from datetime import datetime
@@ -617,6 +618,30 @@ class TrackBuilder:
                     Phase(id=f"phase-{i + 1}", name=phase_name, tasks=phase_tasks)
                 )
 
+        # Persist features to database from plan phases
+        features_created = 0
+        if phases:
+            for phase in phases:
+                for task in phase.tasks:
+                    # Generate feature ID from task description
+                    feature_id = generate_id(node_type="feat", title=task.description)
+
+                    # Insert feature into database
+                    success = self.sdk._db.insert_feature(
+                        feature_id=feature_id,
+                        feature_type="task",  # Tasks from tracks are features of type "task"
+                        title=task.description,
+                        status="todo",  # All new tasks start as "todo"
+                        priority=self._priority,  # Inherit priority from track
+                        assigned_to=None,  # No assignment initially
+                        track_id=track_id,
+                        description=f"Task from {phase.name}",
+                        steps_total=0,
+                        tags=None,
+                    )
+                    if success:
+                        features_created += 1
+
         if self._consolidated:
             # Single-file format: everything in one index.html
             track_file = self.sdk._directory / "tracks" / f"{track_id}.html"
@@ -677,5 +702,21 @@ class TrackBuilder:
         if self._plan_phases:
             total_tasks = sum(len(tasks) for _, tasks in self._plan_phases)
             print(f"  - Plan with {len(self._plan_phases)} phases, {total_tasks} tasks")
+        if features_created > 0:
+            print(f"  - Persisted {features_created} features to database")
 
         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

@@ -0,0 +1,81 @@
+"""
+Computational Imperative Guidance System (CIGS)
+
+Provides guidance, messaging, and tracking for delegation enforcement in HtmlGraph.
+
+Modules:
+- messages_basic: Level 0-1 imperative message templates
+- models: Data models for violations, patterns, and autonomy
+- tracker: Violation tracking and persistence
+- 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
+from htmlgraph.cigs.messages_basic import (
+    BasicMessageGenerator,
+    MessageTemplateLibrary,
+    OperationContext,
+    ToolCategory,
+    classify_operation,
+    estimate_costs,
+)
+from htmlgraph.cigs.messaging import (
+    ImperativeMessageGenerator,
+    PositiveReinforcementGenerator,
+)
+from htmlgraph.cigs.models import (
+    AutonomyLevel,
+    CostMetrics,
+    CostPrediction,
+    OperationClassification,
+    PatternRecord,
+    SessionViolationSummary,
+    TokenCost,
+    ViolationRecord,
+    ViolationType,
+)
+from htmlgraph.cigs.patterns import (
+    DetectionResult,
+    PatternDetector,
+    detect_patterns,
+)
+from htmlgraph.cigs.posttool_analyzer import CIGSPostToolAnalyzer
+from htmlgraph.cigs.reporter import CostReporter
+from htmlgraph.cigs.tracker import ViolationTracker
+
+__all__ = [
+    # Messages
+    "BasicMessageGenerator",
+    "PositiveReinforcementGenerator",
+    "ImperativeMessageGenerator",
+    "MessageTemplateLibrary",
+    "OperationContext",
+    "ToolCategory",
+    "classify_operation",
+    "estimate_costs",
+    # Models
+    "ViolationType",
+    "ViolationRecord",
+    "SessionViolationSummary",
+    "PatternRecord",
+    "TokenCost",
+    "CostPrediction",
+    "OperationClassification",
+    "AutonomyLevel",
+    "CostMetrics",
+    # Autonomy
+    "AutonomyRecommender",
+    # Patterns
+    "PatternDetector",
+    "DetectionResult",
+    "detect_patterns",
+    # Tracker
+    "ViolationTracker",
+    # PostTool Analysis
+    "CIGSPostToolAnalyzer",
+    # Reporter
+    "CostReporter",
+]