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

htmlgraph/builders/feature.py

@@ -1,3 +1,5 @@
+from __future__ import annotations
+
 """
 Feature builder for creating feature nodes.
 
@@ -5,8 +7,8 @@ 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:
     from htmlgraph.sdk import SDK
@@ -14,7 +16,7 @@ if TYPE_CHECKING:
 from htmlgraph.builders.base import BaseBuilder
 
 
-class FeatureBuilder(BaseBuilder['FeatureBuilder']):
+class FeatureBuilder(BaseBuilder["FeatureBuilder"]):
     """
     Fluent builder for creating features.
 
@@ -33,7 +35,30 @@ class FeatureBuilder(BaseBuilder['FeatureBuilder']):
 
     node_type = "feature"
 
-    def set_required_capabilities(self, capabilities: list[str]) -> 'FeatureBuilder':
+    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.
 
@@ -52,7 +77,7 @@ class FeatureBuilder(BaseBuilder['FeatureBuilder']):
         self._data["required_capabilities"] = capabilities
         return self
 
-    def add_capability_tag(self, tag: str) -> 'FeatureBuilder':
+    def add_capability_tag(self, tag: str) -> FeatureBuilder:
         """
         Add a capability tag for flexible matching.
 
@@ -73,7 +98,7 @@ class FeatureBuilder(BaseBuilder['FeatureBuilder']):
         self._data["capability_tags"].append(tag)
         return self
 
-    def add_capability_tags(self, tags: list[str]) -> 'FeatureBuilder':
+    def add_capability_tags(self, tags: list[str]) -> FeatureBuilder:
         """
         Add multiple capability tags.
 

htmlgraph/builders/insight.py

@@ -0,0 +1,195 @@
+from __future__ import annotations
+
+"""
+Insight builder for creating session insight nodes.
+
+Extends BaseBuilder with insight-specific methods for
+session health scoring and pattern detection.
+"""
+
+
+from typing import TYPE_CHECKING, Any
+
+if TYPE_CHECKING:
+    from htmlgraph.models import SessionInsight
+    from htmlgraph.sdk import SDK
+
+from htmlgraph.builders.base import BaseBuilder
+from htmlgraph.ids import generate_id
+
+
+class InsightBuilder(BaseBuilder["InsightBuilder"]):
+    """
+    Fluent builder for creating session insights.
+
+    Insights analyze session health, detect patterns, and provide
+    recommendations for improvement.
+
+    Example:
+        >>> sdk = SDK(agent="claude")
+        >>> insight = sdk.insights.create("Session ABC Health Analysis") \\
+        ...     .for_session("session-abc-123") \\
+        ...     .set_health_scores(efficiency=0.85, retry_rate=0.1) \\
+        ...     .add_issue("High retry rate on Bash commands") \\
+        ...     .add_recommendation("Use Read before Edit") \\
+        ...     .save()
+    """
+
+    node_type = "insight"
+
+    def __init__(self, sdk: SDK, title: str, **kwargs: Any):
+        """Initialize insight builder with insight-specific defaults."""
+        super().__init__(sdk, title, **kwargs)
+        # Set insight-specific defaults
+        if "insight_type" not in self._data:
+            self._data["insight_type"] = "health"
+
+    def for_session(self, session_id: str) -> InsightBuilder:
+        """
+        Set the source session ID.
+
+        Args:
+            session_id: ID of the session being analyzed
+
+        Returns:
+            Self for method chaining
+
+        Example:
+            >>> insight.for_session("session-abc-123")
+        """
+        self._data["session_id"] = session_id
+        return self
+
+    def set_health_scores(
+        self,
+        efficiency: float = 0.0,
+        retry_rate: float = 0.0,
+        context_rebuilds: int = 0,
+        tool_diversity: float = 0.0,
+        error_recovery: float = 0.0,
+    ) -> InsightBuilder:
+        """
+        Set all health metric scores.
+
+        Args:
+            efficiency: Efficiency score (0.0-1.0)
+            retry_rate: Retry rate (0.0-1.0, lower is better)
+            context_rebuilds: Number of context rebuilds
+            tool_diversity: Tool diversity score (0.0-1.0)
+            error_recovery: Error recovery rate (0.0-1.0)
+
+        Returns:
+            Self for method chaining
+
+        Example:
+            >>> insight.set_health_scores(
+            ...     efficiency=0.85,
+            ...     retry_rate=0.12,
+            ...     tool_diversity=0.70
+            ... )
+        """
+        self._data["efficiency_score"] = efficiency
+        self._data["retry_rate"] = retry_rate
+        self._data["context_rebuild_count"] = context_rebuilds
+        self._data["tool_diversity"] = tool_diversity
+        self._data["error_recovery_rate"] = error_recovery
+        # Calculate overall health score
+        self._data["overall_health_score"] = (
+            efficiency + (1 - retry_rate) + tool_diversity
+        ) / 3
+        return self
+
+    def add_issue(self, issue: str) -> InsightBuilder:
+        """
+        Add a detected issue.
+
+        Args:
+            issue: Description of the issue
+
+        Returns:
+            Self for method chaining
+
+        Example:
+            >>> insight.add_issue("High retry rate on file operations")
+        """
+        if "issues_detected" not in self._data:
+            self._data["issues_detected"] = []
+        self._data["issues_detected"].append(issue)
+        return self
+
+    def add_recommendation(self, rec: str) -> InsightBuilder:
+        """
+        Add a recommendation for improvement.
+
+        Args:
+            rec: Recommendation text
+
+        Returns:
+            Self for method chaining
+
+        Example:
+            >>> insight.add_recommendation("Use Read before attempting Edit")
+        """
+        if "recommendations" not in self._data:
+            self._data["recommendations"] = []
+        self._data["recommendations"].append(rec)
+        return self
+
+    def add_pattern_match(
+        self, pattern_id: str, is_anti: bool = False
+    ) -> InsightBuilder:
+        """
+        Add a matched pattern ID.
+
+        Args:
+            pattern_id: ID of the matched pattern
+            is_anti: Whether this is an anti-pattern match
+
+        Returns:
+            Self for method chaining
+
+        Example:
+            >>> insight.add_pattern_match("pattern-efficient-testing", is_anti=False)
+            >>> insight.add_pattern_match("pattern-excessive-retries", is_anti=True)
+        """
+        key = "anti_patterns_matched" if is_anti else "patterns_matched"
+        if key not in self._data:
+            self._data[key] = []
+        self._data[key].append(pattern_id)
+        return self
+
+    def save(self) -> SessionInsight:
+        """
+        Save the insight and return the SessionInsight instance.
+
+        Overrides BaseBuilder.save() to ensure insights are saved
+        to the insights directory.
+
+        Returns:
+            Created SessionInsight instance
+        """
+        # Generate collision-resistant ID if not provided
+        if "id" not in self._data:
+            self._data["id"] = generate_id(
+                node_type="insight",
+                title=self._data.get("title", ""),
+            )
+
+        # Import SessionInsight here to avoid circular imports
+        from htmlgraph.models import SessionInsight
+
+        node = SessionInsight(**self._data)
+
+        # Save to the insights collection
+        if hasattr(self._sdk, "insights") and self._sdk.insights is not None:
+            graph = self._sdk.insights._ensure_graph()
+            graph.add(node)
+        else:
+            # Fallback: create new graph
+            from htmlgraph.graph import HtmlGraph
+
+            graph_path = self._sdk._directory / "insights"
+            graph = HtmlGraph(graph_path, auto_load=False)
+            graph.add(node)
+
+        return node

htmlgraph/builders/metric.py

@@ -0,0 +1,217 @@
+from __future__ import annotations
+
+"""
+Metric builder for creating aggregated metric nodes.
+
+Extends BaseBuilder with metric-specific methods for
+time-series aggregation and trend analysis.
+"""
+
+
+from datetime import datetime
+from typing import TYPE_CHECKING, Any
+
+if TYPE_CHECKING:
+    from htmlgraph.models import AggregatedMetric
+    from htmlgraph.sdk import SDK
+
+from htmlgraph.builders.base import BaseBuilder
+from htmlgraph.ids import generate_id
+
+
+class MetricBuilder(BaseBuilder["MetricBuilder"]):
+    """
+    Fluent builder for creating aggregated metrics.
+
+    Metrics aggregate data over time periods (daily/weekly/monthly)
+    and scopes (session/feature/track/agent).
+
+    Example:
+        >>> sdk = SDK(agent="claude")
+        >>> metric = sdk.metrics.create("Weekly Efficiency") \\
+        ...     .set_scope("agent", "claude") \\
+        ...     .set_period("weekly", start=datetime(...), end=datetime(...)) \\
+        ...     .set_metrics({"avg_efficiency": 0.85, "median_retry_rate": 0.12}) \\
+        ...     .set_trend("improving", strength=0.15) \\
+        ...     .save()
+    """
+
+    node_type = "metric"
+
+    def __init__(self, sdk: SDK, title: str, **kwargs: Any):
+        """Initialize metric builder with metric-specific defaults."""
+        super().__init__(sdk, title, **kwargs)
+        # Set metric-specific defaults
+        if "metric_type" not in self._data:
+            self._data["metric_type"] = "efficiency"
+        if "scope" not in self._data:
+            self._data["scope"] = "session"
+        if "period" not in self._data:
+            self._data["period"] = "weekly"
+
+    def set_scope(self, scope: str, scope_id: str | None = None) -> MetricBuilder:
+        """
+        Set metric scope: session, feature, track, or agent.
+
+        Args:
+            scope: Scope type (session/feature/track/agent)
+            scope_id: Specific ID within scope (optional)
+
+        Returns:
+            Self for method chaining
+
+        Example:
+            >>> metric.set_scope("agent", "claude")
+            >>> metric.set_scope("track", "track-planning-workflow")
+        """
+        self._data["scope"] = scope
+        if scope_id:
+            self._data["scope_id"] = scope_id
+        return self
+
+    def set_period(
+        self,
+        period: str,
+        start: datetime | None = None,
+        end: datetime | None = None,
+    ) -> MetricBuilder:
+        """
+        Set time period for aggregation.
+
+        Args:
+            period: Period type (daily/weekly/monthly)
+            start: Period start datetime (optional)
+            end: Period end datetime (optional)
+
+        Returns:
+            Self for method chaining
+
+        Example:
+            >>> metric.set_period("weekly", start=datetime(...), end=datetime(...))
+        """
+        self._data["period"] = period
+        if start:
+            self._data["period_start"] = start.isoformat()
+        if end:
+            self._data["period_end"] = end.isoformat()
+        return self
+
+    def set_metrics(self, metrics: dict[str, float]) -> MetricBuilder:
+        """
+        Set metric values dict.
+
+        Args:
+            metrics: Dictionary of metric name -> value
+
+        Returns:
+            Self for method chaining
+
+        Example:
+            >>> metric.set_metrics({
+            ...     "avg_efficiency": 0.85,
+            ...     "median_retry_rate": 0.12,
+            ...     "tool_diversity": 0.68
+            ... })
+        """
+        self._data["metric_values"] = metrics
+        return self
+
+    def set_percentiles(self, percentiles: dict[str, float]) -> MetricBuilder:
+        """
+        Set percentile values (p50, p90, p99, etc.).
+
+        Args:
+            percentiles: Dictionary of percentile name -> value
+
+        Returns:
+            Self for method chaining
+
+        Example:
+            >>> metric.set_percentiles({
+            ...     "p50": 0.82,
+            ...     "p90": 0.95,
+            ...     "p99": 0.98
+            ... })
+        """
+        self._data["percentiles"] = percentiles
+        return self
+
+    def set_trend(
+        self,
+        direction: str,
+        strength: float = 0.0,
+        vs_previous_pct: float = 0.0,
+    ) -> MetricBuilder:
+        """
+        Set trend information.
+
+        Args:
+            direction: Trend direction (improving/declining/stable)
+            strength: Trend strength (0.0-1.0)
+            vs_previous_pct: Percentage change vs previous period
+
+        Returns:
+            Self for method chaining
+
+        Example:
+            >>> metric.set_trend("improving", strength=0.15, vs_previous_pct=8.5)
+        """
+        self._data["trend_direction"] = direction
+        self._data["trend_strength"] = strength
+        self._data["vs_previous_period_pct"] = vs_previous_pct
+        return self
+
+    def add_session(self, session_id: str) -> MetricBuilder:
+        """
+        Add a session to the aggregation.
+
+        Args:
+            session_id: Session ID to include
+
+        Returns:
+            Self for method chaining
+
+        Example:
+            >>> metric.add_session("session-abc-123")
+        """
+        if "sessions_in_period" not in self._data:
+            self._data["sessions_in_period"] = []
+        self._data["sessions_in_period"].append(session_id)
+        self._data["data_points_count"] = len(self._data["sessions_in_period"])
+        return self
+
+    def save(self) -> AggregatedMetric:
+        """
+        Save the metric and return the AggregatedMetric instance.
+
+        Overrides BaseBuilder.save() to ensure metrics are saved
+        to the metrics directory.
+
+        Returns:
+            Created AggregatedMetric node instance
+        """
+        # Generate collision-resistant ID if not provided
+        if "id" not in self._data:
+            self._data["id"] = generate_id(
+                node_type="metric",
+                title=self._data.get("title", ""),
+            )
+
+        # Import AggregatedMetric here to avoid circular imports
+        from htmlgraph.models import AggregatedMetric
+
+        node = AggregatedMetric(**self._data)
+
+        # Save to the metrics collection
+        if hasattr(self._sdk, "metrics") and self._sdk.metrics is not None:
+            graph = self._sdk.metrics._ensure_graph()
+            graph.add(node)
+        else:
+            # Fallback: create new graph
+            from htmlgraph.graph import HtmlGraph
+
+            graph_path = self._sdk._directory / "metrics"
+            graph = HtmlGraph(graph_path, auto_load=False)
+            graph.add(node)
+
+        return node

htmlgraph/builders/pattern.py

@@ -0,0 +1,202 @@
+from __future__ import annotations
+
+"""
+Pattern builder for creating workflow pattern nodes.
+
+Extends BaseBuilder with pattern-specific methods for
+tracking optimal and anti-pattern tool sequences.
+"""
+
+
+from datetime import datetime
+from typing import TYPE_CHECKING, Any
+
+if TYPE_CHECKING:
+    from htmlgraph.models import Pattern
+    from htmlgraph.sdk import SDK
+
+from htmlgraph.builders.base import BaseBuilder
+from htmlgraph.ids import generate_id
+
+
+class PatternBuilder(BaseBuilder["PatternBuilder"]):
+    """
+    Fluent builder for creating workflow patterns.
+
+    Patterns represent observed tool usage sequences that are
+    either optimal (should encourage) or anti-patterns (should warn against).
+
+    Example:
+        >>> sdk = SDK(agent="claude")
+        >>> pattern = sdk.patterns.create("Efficient Testing Pattern") \\
+        ...     .set_pattern_type("optimal") \\
+        ...     .set_sequence(["Edit", "Bash", "Edit"]) \\
+        ...     .set_success_rate(0.92) \\
+        ...     .set_recommendation("Write tests, run them, fix failures") \\
+        ...     .save()
+    """
+
+    node_type = "pattern"
+
+    def __init__(self, sdk: SDK, title: str, **kwargs: Any):
+        """Initialize pattern builder with pattern-specific defaults."""
+        super().__init__(sdk, title, **kwargs)
+        # Set pattern-specific defaults
+        if "pattern_type" not in self._data:
+            self._data["pattern_type"] = "neutral"
+        if "sequence" not in self._data:
+            self._data["sequence"] = []
+        if "detection_count" not in self._data:
+            self._data["detection_count"] = 0
+
+    def set_pattern_type(self, ptype: str) -> PatternBuilder:
+        """
+        Set pattern type: optimal, anti-pattern, or neutral.
+
+        Args:
+            ptype: Pattern classification (optimal/anti-pattern/neutral)
+
+        Returns:
+            Self for method chaining
+
+        Example:
+            >>> pattern.set_pattern_type("optimal")
+        """
+        self._data["pattern_type"] = ptype
+        return self
+
+    def set_sequence(self, sequence: list[str]) -> PatternBuilder:
+        """
+        Set the tool sequence for this pattern.
+
+        Args:
+            sequence: List of tool names in order (e.g., ["Edit", "Bash", "Read"])
+
+        Returns:
+            Self for method chaining
+
+        Example:
+            >>> pattern.set_sequence(["Edit", "Bash", "Bash", "Edit"])
+        """
+        self._data["sequence"] = sequence
+        return self
+
+    def set_success_rate(self, rate: float) -> PatternBuilder:
+        """
+        Set success rate (0.0-1.0).
+
+        Args:
+            rate: Success rate as decimal (0.0 = 0%, 1.0 = 100%)
+
+        Returns:
+            Self for method chaining
+
+        Example:
+            >>> pattern.set_success_rate(0.85)
+        """
+        self._data["success_rate"] = rate
+        return self
+
+    def set_recommendation(self, rec: str) -> PatternBuilder:
+        """
+        Set recommendation text for when this pattern is detected.
+
+        Args:
+            rec: Recommendation message
+
+        Returns:
+            Self for method chaining
+
+        Example:
+            >>> pattern.set_recommendation("Consider running tests after changes")
+        """
+        self._data["recommendation"] = rec
+        return self
+
+    def increment_detection(self) -> PatternBuilder:
+        """
+        Increment detection count (number of times pattern was observed).
+
+        Returns:
+            Self for method chaining
+
+        Example:
+            >>> pattern.increment_detection()
+        """
+        self._data["detection_count"] = self._data.get("detection_count", 0) + 1
+        return self
+
+    def set_detection_count(self, count: int) -> PatternBuilder:
+        """
+        Set detection count directly.
+
+        Args:
+            count: Number of times pattern was detected
+
+        Returns:
+            Self for method chaining
+        """
+        self._data["detection_count"] = count
+        return self
+
+    def set_first_detected(self, dt: datetime) -> PatternBuilder:
+        """
+        Set first detection timestamp.
+
+        Args:
+            dt: Timestamp of first detection
+
+        Returns:
+            Self for method chaining
+        """
+        self._data["first_detected"] = dt
+        return self
+
+    def set_last_detected(self, dt: datetime) -> PatternBuilder:
+        """
+        Set last detection timestamp.
+
+        Args:
+            dt: Timestamp of last detection
+
+        Returns:
+            Self for method chaining
+        """
+        self._data["last_detected"] = dt
+        return self
+
+    def save(self) -> Pattern:
+        """
+        Save the pattern and return the Node instance.
+
+        Overrides BaseBuilder.save() to ensure patterns are saved
+        to the patterns directory.
+
+        Returns:
+            Created Pattern node instance
+        """
+        # Generate collision-resistant ID if not provided
+        if "id" not in self._data:
+            self._data["id"] = generate_id(
+                node_type="pattern",
+                title=self._data.get("title", ""),
+            )
+
+        # Import Pattern here to avoid circular imports
+        from htmlgraph.models import Pattern
+
+        node = Pattern(**self._data)
+
+        # Save to the patterns collection
+        if hasattr(self._sdk, "patterns") and self._sdk.patterns is not None:
+            graph = self._sdk.patterns._ensure_graph()
+            graph.add(node)
+        else:
+            # Fallback: create new graph
+            from htmlgraph.graph import HtmlGraph
+
+            graph_path = self._sdk._directory / "patterns"
+            graph = HtmlGraph(graph_path, auto_load=False)
+            graph.add(node)
+
+        return node