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

htmlgraph/collections/session.py

@@ -0,0 +1,194 @@
+from __future__ import annotations
+
+import logging
+
+logger = logging.getLogger(__name__)
+
+"""
+SessionCollection - Session state and management interface.
+
+Provides methods to:
+- Get current session state automatically
+- Set up environment variables automatically
+- Track session metadata
+- Detect post-compact sessions
+
+Integration with SessionStart hook:
+    sdk = SDK()
+    state = sdk.sessions.get_current_state()
+    sdk.sessions.setup_environment_variables(state)
+"""
+
+
+from typing import TYPE_CHECKING
+
+from htmlgraph.collections.base import BaseCollection
+from htmlgraph.session_state import SessionState, SessionStateManager
+
+if TYPE_CHECKING:
+    from htmlgraph.sdk import SDK
+
+
+class SessionCollection(BaseCollection):
+    """
+    Collection interface for session state management.
+
+    Extends BaseCollection with session-specific state management operations.
+
+    Provides:
+    - Automatic session state detection (post-compact, delegation status)
+    - Environment variable setup (CLAUDE_SESSION_ID, CLAUDE_DELEGATION_ENABLED, etc.)
+    - Session metadata recording and retrieval
+    - Compact detection
+
+    Example:
+        >>> sdk = SDK(agent="claude")
+        >>> state = sdk.sessions.get_current_state()
+        >>> sdk.sessions.setup_environment_variables(state)
+        # All environment variables automatically set
+    """
+
+    _collection_name = "sessions"
+    _node_type = "session"
+
+    def __init__(self, sdk: SDK):
+        """
+        Initialize SessionCollection.
+
+        Args:
+            sdk: Parent SDK instance
+        """
+        super().__init__(sdk, "sessions", "session")
+        self._state_manager = SessionStateManager(sdk._directory)
+
+    def get_current_state(self) -> SessionState:
+        """
+        Get current session state with automatic detection.
+
+        Automatically detects:
+        - Current session ID
+        - Session source (startup, resume, compact, clear)
+        - Post-compact status
+        - Delegation enable/disable
+        - Session validity
+
+        Returns:
+            SessionState dict with:
+            - session_id: Current session identifier
+            - session_source: "startup", "resume", "compact", "clear"
+            - is_post_compact: True if this is post-compact session
+            - previous_session_id: Previous session ID if available
+            - delegation_enabled: Should delegation be active
+            - prompt_injected: Was orchestrator prompt injected
+            - session_valid: Is session valid for tracking
+            - timestamp: Current UTC timestamp
+            - compact_metadata: Compact detection details
+
+        Example:
+            >>> sdk = SDK()
+            >>> state = sdk.sessions.get_current_state()
+            >>> logger.info(f"Session: {state['session_id']}")
+            >>> logger.info(f"Post-compact: {state['is_post_compact']}")
+            >>> logger.info(f"Delegation enabled: {state['delegation_enabled']}")
+        """
+        return self._state_manager.get_current_state()
+
+    def setup_environment_variables(
+        self,
+        session_state: SessionState | None = None,
+        auto_detect_compact: bool = True,
+    ) -> dict[str, str]:
+        """
+        Automatically set up environment variables for session state.
+
+        Sets up environment variables that persist across context boundaries:
+        - CLAUDE_SESSION_ID: Current session identifier
+        - CLAUDE_SESSION_SOURCE: "startup|resume|compact|clear"
+        - CLAUDE_SESSION_COMPACTED: "true|false"
+        - CLAUDE_DELEGATION_ENABLED: "true|false"
+        - CLAUDE_PREVIOUS_SESSION_ID: Previous session ID
+        - CLAUDE_ORCHESTRATOR_ACTIVE: "true|false"
+        - CLAUDE_PROMPT_PERSISTENCE_VERSION: "1.0"
+
+        Args:
+            session_state: Session state dict (auto-detected if not provided)
+            auto_detect_compact: Whether to auto-detect post-compact state
+
+        Returns:
+            Dict of environment variables that were set
+
+        Example:
+            >>> sdk = SDK()
+            >>> state = sdk.sessions.get_current_state()
+            >>> env_vars = sdk.sessions.setup_environment_variables(state)
+            >>> logger.info(f"CLAUDE_SESSION_ID: {env_vars['CLAUDE_SESSION_ID']}")
+            >>> logger.info(f"CLAUDE_DELEGATION_ENABLED: {env_vars['CLAUDE_DELEGATION_ENABLED']}")
+        """
+        return self._state_manager.setup_environment_variables(
+            session_state=session_state, auto_detect_compact=auto_detect_compact
+        )
+
+    def record_state(
+        self,
+        session_id: str,
+        source: str,
+        is_post_compact: bool,
+        delegation_enabled: bool,
+        environment_vars: dict[str, str] | None = None,
+    ) -> None:
+        """
+        Store session state metadata for future reference.
+
+        Args:
+            session_id: Current session ID
+            source: Session source ("startup", "resume", "compact", "clear")
+            is_post_compact: Whether this is post-compact
+            delegation_enabled: Whether delegation is enabled
+            environment_vars: Environment variables that were set
+
+        Example:
+            >>> sdk = SDK()
+            >>> sdk.sessions.record_state(
+            ...     session_id="sess-123",
+            ...     source="compact",
+            ...     is_post_compact=True,
+            ...     delegation_enabled=True
+            ... )
+        """
+        self._state_manager.record_state(
+            session_id=session_id,
+            source=source,
+            is_post_compact=is_post_compact,
+            delegation_enabled=delegation_enabled,
+            environment_vars=environment_vars,
+        )
+
+    def detect_compact_automatically(self) -> bool:
+        """
+        Auto-detect if this is post-compact by comparing session IDs.
+
+        Returns:
+            True if this is a post-compact session
+
+        Example:
+            >>> sdk = SDK()
+            >>> if sdk.sessions.detect_compact_automatically():
+            ...     logger.info("This is a post-compact session")
+        """
+        return self._state_manager.detect_compact_automatically()
+
+    def get_state_manager(self) -> SessionStateManager:
+        """
+        Get the underlying SessionStateManager.
+
+        Use this for advanced session state operations.
+
+        Returns:
+            SessionStateManager instance
+
+        Example:
+            >>> sdk = SDK()
+            >>> manager = sdk.sessions.get_state_manager()
+            >>> state = manager.get_current_state()
+        """
+        return self._state_manager

htmlgraph/collections/spike.py

@@ -1,20 +1,26 @@
+from __future__ import annotations
+
+import logging
+
+logger = logging.getLogger(__name__)
+
 """
 Spike collection for managing investigation and research spikes.
 
 Extends BaseCollection with spike-specific builder support.
 """
 
-from __future__ import annotations
+
+from datetime import datetime
 from typing import TYPE_CHECKING
 
 if TYPE_CHECKING:
     from htmlgraph.sdk import SDK
-    from htmlgraph.builders import SpikeBuilder
 
 from htmlgraph.collections.base import BaseCollection
 
 
-class SpikeCollection(BaseCollection['SpikeCollection']):
+class SpikeCollection(BaseCollection["SpikeCollection"]):
     """
     Collection interface for spikes with builder support.
 
@@ -37,7 +43,7 @@ class SpikeCollection(BaseCollection['SpikeCollection']):
     _collection_name = "spikes"
     _node_type = "spike"
 
-    def __init__(self, sdk: 'SDK'):
+    def __init__(self, sdk: SDK):
         """
         Initialize spike collection.
 
@@ -47,23 +53,57 @@ class SpikeCollection(BaseCollection['SpikeCollection']):
         super().__init__(sdk, "spikes", "spike")
         self._sdk = sdk
 
-    def create(self, title: str, **kwargs) -> SpikeBuilder:
+        # Set builder class for create() method
+        from htmlgraph.builders import SpikeBuilder
+
+        self._builder_class = SpikeBuilder
+
+    def get_latest(self, agent: str | None = None, limit: int = 1) -> list:
         """
-        Create a new spike with fluent interface.
+        Get the most recent spike(s), optionally filtered by agent.
+
+        Useful for retrieving subagent findings after delegation.
 
         Args:
-            title: Spike title
-            **kwargs: Additional spike properties
+            agent: Filter by agent_assigned (optional)
+            limit: Maximum number of spikes to return (default: 1)
 
         Returns:
-            SpikeBuilder for method chaining
+            List of most recent Spike nodes (newest first)
 
         Example:
-            >>> spike = sdk.spikes.create("Investigate Database Options") \\
-            ...     .set_spike_type(SpikeType.TECHNICAL) \\
-            ...     .set_timebox_hours(2) \\
-            ...     .add_steps(["Research PostgreSQL", "Research MongoDB"]) \\
-            ...     .save()
+            >>> # Get latest spike from explorer subagent
+            >>> sdk = SDK(agent="orchestrator")
+            >>> findings = sdk.spikes.get_latest(agent="explorer")
+            >>> if findings:
+            ...     print(findings[0].findings)
+            >>>
+            >>> # Get latest 5 spikes from any agent
+            >>> recent = sdk.spikes.get_latest(limit=5)
         """
-        from htmlgraph.builders import SpikeBuilder
-        return SpikeBuilder(self._sdk, title, **kwargs)
+        from datetime import timezone
+
+        # Get all spikes
+        all_spikes = self.all()
+
+        # Filter by agent if specified
+        # Check both agent_assigned and model_name fields
+        if agent:
+            all_spikes = [
+                s
+                for s in all_spikes
+                if (s.agent_assigned and agent.lower() in s.agent_assigned.lower())
+                or (s.model_name and agent.lower() in s.model_name.lower())
+            ]
+
+        # Normalize to UTC for comparison
+        def to_comparable(dt: datetime) -> datetime:
+            if dt.tzinfo is None:
+                return dt.replace(tzinfo=timezone.utc)
+            return dt
+
+        # Sort by created timestamp (newest first)
+        all_spikes.sort(key=lambda s: to_comparable(s.created), reverse=True)
+
+        # Return limited results
+        return all_spikes[:limit]

htmlgraph/collections/task_delegation.py

@@ -0,0 +1,241 @@
+from __future__ import annotations
+
+import logging
+
+logger = logging.getLogger(__name__)
+
+"""
+Task delegation collection for tracking spawned agent work.
+
+Captures observability data for Task() calls:
+- Which agent was spawned (gemini-spawner, codex-spawner, copilot-spawner, haiku)
+- What task was assigned
+- How long it took
+- What was the output/result
+- Cost (tokens used)
+- Success/failure status
+
+This data proves multi-agent orchestration works and enables dashboard attribution.
+"""
+
+
+from datetime import datetime
+from typing import TYPE_CHECKING, Any
+
+if TYPE_CHECKING:
+    from htmlgraph.sdk import SDK
+
+from htmlgraph.collections.base import BaseCollection
+
+
+class TaskDelegationCollection(BaseCollection["TaskDelegationCollection"]):
+    """
+    Collection interface for task delegations.
+
+    Tracks all spawned agent work with metrics:
+    - Agent type (gemini-spawner, codex-spawner, copilot-spawner, haiku)
+    - Task description
+    - Start and end timestamps
+    - Duration in seconds
+    - Tokens used
+    - Cost in USD
+    - Status (success/failure)
+    - Result summary
+
+    Example:
+        >>> sdk = SDK(agent="orchestrator")
+        >>> delegations = sdk.task_delegations.where(agent_type="codex-spawner")
+        >>> for d in delegations:
+        ...     logger.info(f"{d.agent_type}: {d.task_description} ({d.duration_seconds}s)")
+        >>>
+        >>> # Get all delegations for a specific agent
+        >>> gemini_work = sdk.task_delegations.where(agent_type="gemini-spawner")
+        >>>
+        >>> # Calculate total cost
+        >>> total_cost = sum(float(d.cost_usd or 0) for d in sdk.task_delegations.all())
+    """
+
+    _collection_name = "task-delegations"
+    _node_type = "task-delegation"
+
+    def __init__(self, sdk: SDK):
+        """
+        Initialize task delegation collection.
+
+        Args:
+            sdk: Parent SDK instance
+        """
+        super().__init__(sdk, "task-delegations", "task-delegation")
+        self._sdk = sdk
+
+    def create_delegation(
+        self,
+        agent_type: str,
+        task_description: str,
+        timestamp_start: datetime | None = None,
+        tokens_used: int = 0,
+        cost_usd: float = 0.0,
+        status: str = "pending",
+        result_summary: str = "",
+    ) -> Any:
+        """
+        Record a task delegation.
+
+        Args:
+            agent_type: Type of spawned agent (gemini-spawner, codex-spawner, copilot-spawner, haiku)
+            task_description: Human-readable task description
+            timestamp_start: When delegation started (defaults to now)
+            tokens_used: Number of tokens used by the agent
+            cost_usd: Cost in USD for this delegation
+            status: success/failure/pending
+            result_summary: Brief summary of the result
+
+        Returns:
+            Created task delegation node
+        """
+        if timestamp_start is None:
+            timestamp_start = datetime.utcnow()
+
+        # Create delegation record via base collection
+        return self.create(
+            title=f"{agent_type}: {task_description[:50]}...",
+        ).set_metadata(
+            {
+                "agent_type": agent_type,
+                "task_description": task_description,
+                "timestamp_start": timestamp_start.isoformat(),
+                "tokens_used": tokens_used,
+                "cost_usd": cost_usd,
+                "status": status,
+                "result_summary": result_summary,
+            }
+        )
+
+    def update_delegation(
+        self,
+        delegation_id: str,
+        timestamp_end: datetime | None = None,
+        tokens_used: int | None = None,
+        cost_usd: float | None = None,
+        status: str | None = None,
+        result_summary: str | None = None,
+    ) -> Any:
+        """
+        Update a delegation record with completion info.
+
+        Args:
+            delegation_id: ID of the delegation to update
+            timestamp_end: When delegation completed
+            tokens_used: Updated token count
+            cost_usd: Updated cost
+            status: Updated status
+            result_summary: Updated result summary
+
+        Returns:
+            Updated delegation node
+        """
+        if timestamp_end is None:
+            timestamp_end = datetime.utcnow()
+
+        with self.edit(delegation_id) as delegation:
+            if timestamp_end:
+                delegation.timestamp_end = timestamp_end.isoformat()  # type: ignore[attr-defined]
+
+            # Calculate duration if we have start time
+            if hasattr(delegation, "timestamp_start") and timestamp_end:
+                start = datetime.fromisoformat(str(delegation.timestamp_start))
+                duration = (timestamp_end - start).total_seconds()
+                delegation.duration_seconds = int(duration)  # type: ignore[attr-defined]
+
+            if tokens_used is not None:
+                delegation.tokens_used = tokens_used  # type: ignore[attr-defined]
+            if cost_usd is not None:
+                delegation.cost_usd = cost_usd  # type: ignore[attr-defined]
+            if status is not None:
+                delegation.status = status  # type: ignore[assignment]
+            if result_summary is not None:
+                delegation.result_summary = result_summary  # type: ignore[attr-defined]
+
+        return delegation
+
+    def get_by_agent_type(self, agent_type: str) -> list:
+        """
+        Get all delegations for a specific agent type.
+
+        Args:
+            agent_type: Type of agent (gemini-spawner, codex-spawner, etc.)
+
+        Returns:
+            List of delegations for that agent type
+        """
+        return self.where(agent_type=agent_type)
+
+    def get_by_status(self, status: str) -> list:
+        """
+        Get all delegations with a specific status.
+
+        Args:
+            status: Status to filter by (success/failure/pending)
+
+        Returns:
+            List of delegations with that status
+        """
+        return self.where(status=status)
+
+    def get_stats(self) -> dict:
+        """
+        Get aggregated statistics about delegations.
+
+        Returns:
+            Dictionary with:
+            - total_delegations: Count of all delegations
+            - by_agent_type: Count per agent type
+            - by_status: Count per status
+            - total_tokens: Sum of all tokens used
+            - total_cost: Sum of all costs in USD
+            - average_duration: Average duration in seconds
+        """
+        all_delegations = self.all()
+
+        if not all_delegations:
+            return {
+                "total_delegations": 0,
+                "by_agent_type": {},
+                "by_status": {},
+                "total_tokens": 0,
+                "total_cost": 0.0,
+                "average_duration": 0.0,
+            }
+
+        # Count by agent type
+        by_agent_type: dict[str, int] = {}
+        for d in all_delegations:
+            agent = getattr(d, "agent_type", "unknown")
+            by_agent_type[agent] = by_agent_type.get(agent, 0) + 1
+
+        # Count by status
+        by_status: dict[str, int] = {}
+        for d in all_delegations:
+            status = getattr(d, "status", "unknown")
+            by_status[status] = by_status.get(status, 0) + 1
+
+        # Sum tokens and cost
+        total_tokens = sum(getattr(d, "tokens_used", 0) for d in all_delegations)
+        total_cost = sum(float(getattr(d, "cost_usd", 0) or 0) for d in all_delegations)
+
+        # Average duration
+        durations = [
+            getattr(d, "duration_seconds", 0)
+            for d in all_delegations
+            if hasattr(d, "duration_seconds")
+        ]
+        average_duration = sum(durations) / len(durations) if durations else 0.0
+
+        return {
+            "total_delegations": len(all_delegations),
+            "by_agent_type": by_agent_type,
+            "by_status": by_status,
+            "total_tokens": total_tokens,
+            "total_cost": round(total_cost, 4),
+            "average_duration": round(average_duration, 2),
+        }