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

htmlgraph/collections/bug.py

@@ -0,0 +1,53 @@
+from __future__ import annotations
+
+"""
+Bug collection for managing bug report work items.
+
+Extends BaseCollection with bug-specific builder support.
+"""
+
+
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from htmlgraph.sdk import SDK
+
+from htmlgraph.collections.base import BaseCollection
+
+
+class BugCollection(BaseCollection["BugCollection"]):
+    """
+    Collection interface for bugs with builder support.
+
+    Provides all base collection methods plus a fluent builder
+    interface for creating new bugs.
+
+    Example:
+        >>> sdk = SDK(agent="claude")
+        >>> bug = sdk.bugs.create("Login button broken") \\
+        ...     .set_priority("critical") \\
+        ...     .set_severity("high") \\
+        ...     .set_repro_steps(["Go to login", "Click button"]) \\
+        ...     .save()
+        >>>
+        >>> # Query bugs
+        >>> critical_bugs = sdk.bugs.where(priority="critical")
+    """
+
+    _collection_name = "bugs"
+    _node_type = "bug"
+
+    def __init__(self, sdk: SDK):
+        """
+        Initialize bug collection.
+
+        Args:
+            sdk: Parent SDK instance
+        """
+        super().__init__(sdk, "bugs", "bug")
+        self._sdk = sdk
+
+        # Set builder class for create() method
+        from htmlgraph.builders.bug import BugBuilder
+
+        self._builder_class = BugBuilder

htmlgraph/collections/chore.py

@@ -0,0 +1,53 @@
+from __future__ import annotations
+
+"""
+Chore collection for managing maintenance task work items.
+
+Extends BaseCollection with chore-specific builder support.
+"""
+
+
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from htmlgraph.sdk import SDK
+
+from htmlgraph.collections.base import BaseCollection
+
+
+class ChoreCollection(BaseCollection["ChoreCollection"]):
+    """
+    Collection interface for chores with builder support.
+
+    Provides all base collection methods plus a fluent builder
+    interface for creating new chores.
+
+    Example:
+        >>> sdk = SDK(agent="claude")
+        >>> chore = sdk.chores.create("Update dependencies") \\
+        ...     .set_priority("low") \\
+        ...     .set_chore_type("maintenance") \\
+        ...     .set_recurring(interval_days=30) \\
+        ...     .save()
+        >>>
+        >>> # Query chores
+        >>> maintenance = sdk.chores.where(status="todo")
+    """
+
+    _collection_name = "chores"
+    _node_type = "chore"
+
+    def __init__(self, sdk: SDK):
+        """
+        Initialize chore collection.
+
+        Args:
+            sdk: Parent SDK instance
+        """
+        super().__init__(sdk, "chores", "chore")
+        self._sdk = sdk
+
+        # Set builder class for create() method
+        from htmlgraph.builders.chore import ChoreBuilder
+
+        self._builder_class = ChoreBuilder

htmlgraph/collections/epic.py

@@ -0,0 +1,53 @@
+from __future__ import annotations
+
+"""
+Epic collection for managing large body of work items.
+
+Extends BaseCollection with epic-specific builder support.
+"""
+
+
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from htmlgraph.sdk import SDK
+
+from htmlgraph.collections.base import BaseCollection
+
+
+class EpicCollection(BaseCollection["EpicCollection"]):
+    """
+    Collection interface for epics with builder support.
+
+    Provides all base collection methods plus a fluent builder
+    interface for creating new epics.
+
+    Example:
+        >>> sdk = SDK(agent="claude")
+        >>> epic = sdk.epics.create("v2.0 Release") \\
+        ...     .set_priority("high") \\
+        ...     .set_target_date(date(2025, 6, 1)) \\
+        ...     .add_child_features(["feat-001", "feat-002"]) \\
+        ...     .save()
+        >>>
+        >>> # Query epics
+        >>> active_epics = sdk.epics.where(status="in-progress")
+    """
+
+    _collection_name = "epics"
+    _node_type = "epic"
+
+    def __init__(self, sdk: SDK):
+        """
+        Initialize epic collection.
+
+        Args:
+            sdk: Parent SDK instance
+        """
+        super().__init__(sdk, "epics", "epic")
+        self._sdk = sdk
+
+        # Set builder class for create() method
+        from htmlgraph.builders.epic import EpicBuilder
+
+        self._builder_class = EpicBuilder

htmlgraph/collections/feature.py

@@ -1,21 +1,22 @@
+from __future__ import annotations
+
 """
 Feature collection for managing feature work items.
 
 Extends BaseCollection with feature-specific builder support.
 """
 
-from __future__ import annotations
-from typing import TYPE_CHECKING, Any
+
+from typing import TYPE_CHECKING
 
 if TYPE_CHECKING:
-    from htmlgraph.sdk import SDK
-    from htmlgraph.builders import FeatureBuilder
     from htmlgraph.models import Node
+    from htmlgraph.sdk import SDK
 
 from htmlgraph.collections.base import BaseCollection
 
 
-class FeatureCollection(BaseCollection['FeatureCollection']):
+class FeatureCollection(BaseCollection["FeatureCollection"]):
     """
     Collection interface for features with builder support.
 
@@ -37,7 +38,7 @@ class FeatureCollection(BaseCollection['FeatureCollection']):
     _collection_name = "features"
     _node_type = "feature"
 
-    def __init__(self, sdk: 'SDK'):
+    def __init__(self, sdk: SDK):
         """
         Initialize feature collection.
 
@@ -47,25 +48,10 @@ class FeatureCollection(BaseCollection['FeatureCollection']):
         super().__init__(sdk, "features", "feature")
         self._sdk = sdk
 
-    def create(self, title: str, **kwargs) -> FeatureBuilder:
-        """
-        Create a new feature with fluent interface.
-
-        Args:
-            title: Feature title
-            **kwargs: Additional feature properties
-
-        Returns:
-            FeatureBuilder for method chaining
-
-        Example:
-            >>> feature = sdk.features.create("User Auth") \\
-            ...     .set_priority("high") \\
-            ...     .add_steps(["Login", "Logout"]) \\
-            ...     .save()
-        """
+        # Set builder class for create() method
         from htmlgraph.builders import FeatureBuilder
-        return FeatureBuilder(self._sdk, title, **kwargs)
+
+        self._builder_class = FeatureBuilder
 
     def set_primary(self, node_id: str) -> Node | None:
         """
@@ -79,11 +65,11 @@ class FeatureCollection(BaseCollection['FeatureCollection']):
         Returns:
             Updated Node
         """
-        if hasattr(self._sdk, 'session_manager'):
+        if hasattr(self._sdk, "session_manager"):
             return self._sdk.session_manager.set_primary_feature(
                 feature_id=node_id,
                 collection=self._collection_name,
                 agent=self._sdk.agent,
-                log_activity=True
+                log_activity=True,
             )
         return None

htmlgraph/collections/insight.py

@@ -0,0 +1,100 @@
+from __future__ import annotations
+
+"""
+SessionInsight collection for managing session insights.
+
+Extends BaseCollection with insight-specific query methods.
+"""
+
+
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from htmlgraph.models import Node
+    from htmlgraph.sdk import SDK
+
+from htmlgraph.collections.base import BaseCollection
+
+
+class InsightCollection(BaseCollection["InsightCollection"]):
+    """
+    Collection interface for session insights.
+
+    Provides all base collection methods plus insight-specific
+    queries for analyzing session efficiency and detecting issues.
+
+    Example:
+        >>> sdk = SDK(agent="claude")
+        >>> insight = sdk.insights.for_session("sess-abc-123")
+        >>>
+        >>> # Query insights
+        >>> low_eff = sdk.insights.get_low_efficiency(threshold=0.7)
+        >>> with_issues = sdk.insights.get_with_issues()
+    """
+
+    _collection_name = "insights"
+    _node_type = "insight"
+
+    def __init__(self, sdk: SDK):
+        """
+        Initialize insight collection.
+
+        Args:
+            sdk: Parent SDK instance
+        """
+        super().__init__(sdk, "insights", "insight")
+        self._sdk = sdk
+
+        # Set builder class for create() method
+        from htmlgraph.builders import InsightBuilder
+
+        self._builder_class = InsightBuilder
+
+    def for_session(self, session_id: str) -> Node | None:
+        """
+        Get insight for a specific session.
+
+        Args:
+            session_id: Session ID to find insight for
+
+        Returns:
+            Insight node if found, None otherwise
+
+        Example:
+            >>> insight = sdk.insights.for_session("sess-abc-123")
+        """
+        results = list(self.where(session_id=session_id))
+        return results[0] if results else None
+
+    def get_low_efficiency(self, threshold: float = 0.7) -> list[Node]:
+        """
+        Get insights with efficiency below threshold.
+
+        Args:
+            threshold: Minimum efficiency score (0.0 to 1.0)
+
+        Returns:
+            List of insights with efficiency_score < threshold
+
+        Example:
+            >>> low_eff = sdk.insights.get_low_efficiency(threshold=0.6)
+        """
+        return [
+            i
+            for i in self.all()
+            if hasattr(i, "efficiency_score") and i.efficiency_score < threshold
+        ]
+
+    def get_with_issues(self) -> list[Node]:
+        """
+        Get insights that detected issues.
+
+        Returns:
+            List of insights where issues_detected is True
+
+        Example:
+            >>> problematic = sdk.insights.get_with_issues()
+        """
+        return [
+            i for i in self.all() if hasattr(i, "issues_detected") and i.issues_detected
+        ]

htmlgraph/collections/metric.py

@@ -0,0 +1,92 @@
+from __future__ import annotations
+
+"""
+AggregatedMetric collection for managing aggregated metrics.
+
+Extends BaseCollection with metric-specific query methods.
+"""
+
+
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from htmlgraph.models import Node
+    from htmlgraph.sdk import SDK
+
+from htmlgraph.collections.base import BaseCollection
+
+
+class MetricCollection(BaseCollection["MetricCollection"]):
+    """
+    Collection interface for aggregated metrics.
+
+    Provides all base collection methods plus metric-specific
+    queries for analyzing trends and retrieving latest metrics.
+
+    Example:
+        >>> sdk = SDK(agent="claude")
+        >>> latest = sdk.metrics.get_latest(scope="session", period="weekly")
+        >>>
+        >>> # Query metrics
+        >>> trending = sdk.metrics.get_trend(scope="session")
+    """
+
+    _collection_name = "metrics"
+    _node_type = "metric"
+
+    def __init__(self, sdk: SDK):
+        """
+        Initialize metric collection.
+
+        Args:
+            sdk: Parent SDK instance
+        """
+        super().__init__(sdk, "metrics", "metric")
+        self._sdk = sdk
+
+        # Set builder class for create() method
+        from htmlgraph.builders import MetricBuilder
+
+        self._builder_class = MetricBuilder
+
+    def get_latest(self, scope: str = "session", period: str = "weekly") -> Node | None:
+        """
+        Get the most recent metric for a scope/period.
+
+        Args:
+            scope: Metric scope (e.g., "session", "feature", "agent")
+            period: Time period (e.g., "daily", "weekly", "monthly")
+
+        Returns:
+            Most recent metric node if found, None otherwise
+
+        Example:
+            >>> latest = sdk.metrics.get_latest(scope="session", period="weekly")
+        """
+        results = list(self.where(scope=scope, period=period))
+        if not results:
+            return None
+        # Sort by period_end descending (most recent first)
+        results.sort(key=lambda m: getattr(m, "period_end", "") or "", reverse=True)
+        return results[0]
+
+    def get_trend(self, scope: str = "session") -> list[Node]:
+        """
+        Get metrics showing trends for a scope.
+
+        Filters out metrics with "stable" trend_direction.
+
+        Args:
+            scope: Metric scope to filter by
+
+        Returns:
+            List of metrics with non-stable trends
+
+        Example:
+            >>> trending = sdk.metrics.get_trend(scope="session")
+        """
+        return [
+            m
+            for m in self.where(scope=scope)
+            if hasattr(m, "trend_direction") and m.trend_direction != "stable"
+        ]

htmlgraph/collections/pattern.py

@@ -0,0 +1,97 @@
+from __future__ import annotations
+
+"""
+Pattern collection for managing workflow patterns.
+
+Extends BaseCollection with pattern-specific query methods.
+"""
+
+
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from htmlgraph.models import Node
+    from htmlgraph.sdk import SDK
+
+from htmlgraph.collections.base import BaseCollection
+
+
+class PatternCollection(BaseCollection["PatternCollection"]):
+    """
+    Collection interface for workflow patterns.
+
+    Provides all base collection methods plus pattern-specific
+    queries for finding optimal patterns and anti-patterns.
+
+    Example:
+        >>> sdk = SDK(agent="claude")
+        >>> pattern = sdk.patterns.create("File-then-Edit Pattern") \\
+        ...     .set_sequence(["Read", "Edit"]) \\
+        ...     .save()
+        >>>
+        >>> # Query patterns
+        >>> optimal = sdk.patterns.get_optimal_patterns()
+        >>> anti = sdk.patterns.get_anti_patterns()
+    """
+
+    _collection_name = "patterns"
+    _node_type = "pattern"
+
+    def __init__(self, sdk: SDK):
+        """
+        Initialize pattern collection.
+
+        Args:
+            sdk: Parent SDK instance
+        """
+        super().__init__(sdk, "patterns", "pattern")
+        self._sdk = sdk
+
+        # Set builder class for create() method
+        from htmlgraph.builders import PatternBuilder
+
+        self._builder_class = PatternBuilder
+
+    def find_by_sequence(self, sequence: list[str]) -> list[Node]:
+        """
+        Find patterns matching a specific tool sequence.
+
+        Args:
+            sequence: List of tool names in order (e.g., ["Read", "Edit"])
+
+        Returns:
+            List of patterns with matching sequence
+
+        Example:
+            >>> patterns = sdk.patterns.find_by_sequence(["Read", "Edit"])
+        """
+        seq_str = "->".join(sequence)
+        return [
+            p
+            for p in self.all()
+            if hasattr(p, "sequence") and "->".join(p.sequence) == seq_str
+        ]
+
+    def get_anti_patterns(self) -> list[Node]:
+        """
+        Get all anti-patterns.
+
+        Returns:
+            List of anti-pattern nodes
+
+        Example:
+            >>> anti_patterns = sdk.patterns.get_anti_patterns()
+        """
+        return self.where(pattern_type="anti-pattern")
+
+    def get_optimal_patterns(self) -> list[Node]:
+        """
+        Get all optimal patterns.
+
+        Returns:
+            List of optimal pattern nodes
+
+        Example:
+            >>> optimal = sdk.patterns.get_optimal_patterns()
+        """
+        return self.where(pattern_type="optimal")

htmlgraph/collections/phase.py

@@ -0,0 +1,53 @@
+from __future__ import annotations
+
+"""
+Phase collection for managing project phase work items.
+
+Extends BaseCollection with phase-specific builder support.
+"""
+
+
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from htmlgraph.sdk import SDK
+
+from htmlgraph.collections.base import BaseCollection
+
+
+class PhaseCollection(BaseCollection["PhaseCollection"]):
+    """
+    Collection interface for phases with builder support.
+
+    Provides all base collection methods plus a fluent builder
+    interface for creating new phases.
+
+    Example:
+        >>> sdk = SDK(agent="claude")
+        >>> phase = sdk.phases.create("Phase 1: Core Library") \\
+        ...     .set_priority("high") \\
+        ...     .set_phase_number(1) \\
+        ...     .set_deliverables(["Core API", "Tests"]) \\
+        ...     .save()
+        >>>
+        >>> # Query phases
+        >>> active_phases = sdk.phases.where(status="in-progress")
+    """
+
+    _collection_name = "phases"
+    _node_type = "phase"
+
+    def __init__(self, sdk: SDK):
+        """
+        Initialize phase collection.
+
+        Args:
+            sdk: Parent SDK instance
+        """
+        super().__init__(sdk, "phases", "phase")
+        self._sdk = sdk
+
+        # Set builder class for create() method
+        from htmlgraph.builders.phase import PhaseBuilder
+
+        self._builder_class = PhaseBuilder