htmlgraph 0.21.0__py3-none-any.whl → 0.23.0__py3-none-any.whl

htmlgraph/sdk.py

@@ -88,6 +88,31 @@ class SDK:
         - tracks: Work tracks
         - agents: Agent information
         - todos: Persistent task tracking (mirrors TodoWrite API)
+        - patterns: Workflow patterns (optimal/anti-pattern)
+        - insights: Session health insights
+        - metrics: Aggregated time-series metrics
+
+    Analytics & Decision Support:
+        sdk.dep_analytics - Dependency analysis
+            .find_bottlenecks(top_n=5) - Find blocking tasks
+            .get_parallel_work(max_agents=5) - Find parallelizable work
+            .recommend_next_tasks(agent_count=1) - Smart recommendations
+            .assess_dependency_risk() - Check for circular deps
+            .impact_analysis(node_id) - See what task unlocks
+
+        sdk.analytics - Work analytics
+            .get_work_type_distribution() - Breakdown by type
+            .get_spike_to_feature_ratio() - Investigation vs implementation
+            .get_maintenance_burden() - Chore vs feature ratio
+
+        sdk.context - Context tracking
+            .get_context_usage() - Session context metrics
+            .get_context_efficiency() - Efficiency score
+
+    Discovery & Help:
+        sdk.help() - Get structured help for all operations
+        sdk.help('analytics') - Get analytics-specific help
+        sdk.help('features') - Get feature collection help
 
     Error Handling Patterns
     =======================
@@ -131,12 +156,15 @@ class SDK:
         ... except ValidationError:
         ...     print("Title required")
 
-    BATCH OPERATIONS (Return Count):
-        Batch operations return count of successful items.
-        Silently skip items that fail.
+    BATCH OPERATIONS (Return Results Dict):
+        Batch operations return dict with success_count, failed_ids, and warnings.
+        Provides detailed feedback for partial failures.
 
-        >>> count = sdk.features.mark_done(["feat-1", "missing", "feat-2"])
-        >>> print(f"Completed {count} of 3")  # Outputs: Completed 2 of 3
+        >>> result = sdk.features.mark_done(["feat-1", "missing", "feat-2"])
+        >>> print(f"Completed {result['success_count']} of 3")
+        >>> if result['failed_ids']:
+        ...     print(f"Failed: {result['failed_ids']}")
+        ...     print(f"Reasons: {result['warnings']}")
 
     Pattern Summary:
         | Operation Type | Error Behavior      | Example Method        |
@@ -145,7 +173,7 @@ class SDK:
         | Query          | Return []          | .where(), .all()      |
         | Edit           | Raise Exception    | .edit(id)             |
         | Create         | Raise on Invalid   | .create(title)        |
-        | Batch          | Return Count       | .mark_done([ids])     |
+        | Batch          | Return Results Dict| .mark_done([ids])     |
         | Delete         | Return Bool        | .delete(id)           |
 
     Available Exceptions:
@@ -1775,6 +1803,398 @@ class SDK:
 
         return None
 
+    # =========================================================================
+    # Operations Layer - Server, Hooks, Events, Analytics
+    # =========================================================================
+
+    def start_server(
+        self,
+        port: int = 8080,
+        host: str = "localhost",
+        watch: bool = True,
+        auto_port: bool = False,
+    ) -> Any:
+        """
+        Start HtmlGraph server for browsing graph via web UI.
+
+        Args:
+            port: Port to listen on (default: 8080)
+            host: Host to bind to (default: "localhost")
+            watch: Enable file watching for auto-reload (default: True)
+            auto_port: Automatically find available port if specified port is in use (default: False)
+
+        Returns:
+            ServerStartResult with handle, warnings, and config used
+
+        Raises:
+            PortInUseError: If port is in use and auto_port=False
+            ServerStartError: If server fails to start
+
+        Example:
+            >>> sdk = SDK(agent="claude")
+            >>> result = sdk.start_server(port=8080, watch=True)
+            >>> print(f"Server running at {result.handle.url}")
+            >>> # Open browser to http://localhost:8080
+            >>>
+            >>> # Stop server when done
+            >>> sdk.stop_server(result.handle)
+
+        See also:
+            stop_server: Stop running server
+            get_server_status: Check if server is running
+        """
+        from htmlgraph.operations import server
+
+        return server.start_server(
+            port=port,
+            graph_dir=self._directory,
+            static_dir=self._directory.parent,  # Project root for index.html
+            host=host,
+            watch=watch,
+            auto_port=auto_port,
+        )
+
+    def stop_server(self, handle: Any) -> None:
+        """
+        Stop a running HtmlGraph server.
+
+        Args:
+            handle: ServerHandle returned from start_server()
+
+        Raises:
+            ServerStartError: If shutdown fails
+
+        Example:
+            >>> sdk = SDK(agent="claude")
+            >>> result = sdk.start_server()
+            >>> # Work with server...
+            >>> sdk.stop_server(result.handle)
+        """
+        from htmlgraph.operations import server
+
+        server.stop_server(handle)
+
+    def get_server_status(self, handle: Any | None = None) -> Any:
+        """
+        Check server status.
+
+        Args:
+            handle: Optional ServerHandle to check
+
+        Returns:
+            ServerStatus indicating whether server is running
+
+        Example:
+            >>> sdk = SDK(agent="claude")
+            >>> result = sdk.start_server()
+            >>> status = sdk.get_server_status(result.handle)
+            >>> print(f"Running: {status.running}")
+        """
+        from htmlgraph.operations import server
+
+        return server.get_server_status(handle)
+
+    def install_hooks(self, use_copy: bool = False) -> Any:
+        """
+        Install Git hooks for automatic tracking.
+
+        Installs hooks that automatically track sessions, activities, and features
+        as you work.
+
+        Args:
+            use_copy: Force copy instead of symlink (default: False)
+
+        Returns:
+            HookInstallResult with installation details
+
+        Raises:
+            HookInstallError: If installation fails
+            HookConfigError: If configuration is invalid
+
+        Example:
+            >>> sdk = SDK(agent="claude")
+            >>> result = sdk.install_hooks()
+            >>> print(f"Installed: {result.installed}")
+            >>> print(f"Skipped: {result.skipped}")
+            >>> if result.warnings:
+            ...     print(f"Warnings: {result.warnings}")
+
+        See also:
+            list_hooks: List installed hooks
+            validate_hook_config: Validate hook configuration
+        """
+        from htmlgraph.operations import hooks
+
+        return hooks.install_hooks(
+            project_dir=self._directory.parent,
+            use_copy=use_copy,
+        )
+
+    def list_hooks(self) -> Any:
+        """
+        List Git hooks status (enabled/disabled/missing).
+
+        Returns:
+            HookListResult with enabled, disabled, and missing hooks
+
+        Example:
+            >>> sdk = SDK(agent="claude")
+            >>> result = sdk.list_hooks()
+            >>> print(f"Enabled: {result.enabled}")
+            >>> print(f"Disabled: {result.disabled}")
+            >>> print(f"Missing: {result.missing}")
+        """
+        from htmlgraph.operations import hooks
+
+        return hooks.list_hooks(project_dir=self._directory.parent)
+
+    def validate_hook_config(self) -> Any:
+        """
+        Validate hook configuration.
+
+        Returns:
+            HookValidationResult with validation status
+
+        Example:
+            >>> sdk = SDK(agent="claude")
+            >>> result = sdk.validate_hook_config()
+            >>> if not result.valid:
+            ...     print(f"Errors: {result.errors}")
+            >>> if result.warnings:
+            ...     print(f"Warnings: {result.warnings}")
+        """
+        from htmlgraph.operations import hooks
+
+        return hooks.validate_hook_config(project_dir=self._directory.parent)
+
+    def export_sessions(self, overwrite: bool = False) -> Any:
+        """
+        Export legacy session HTML logs to JSONL events.
+
+        Converts HTML session files to JSONL format for efficient querying.
+
+        Args:
+            overwrite: Whether to overwrite existing JSONL files (default: False)
+
+        Returns:
+            EventExportResult with counts of written, skipped, failed files
+
+        Raises:
+            EventOperationError: If export fails
+
+        Example:
+            >>> sdk = SDK(agent="claude")
+            >>> result = sdk.export_sessions()
+            >>> print(f"Exported {result.written} sessions")
+            >>> print(f"Skipped {result.skipped} (already exist)")
+            >>> if result.failed > 0:
+            ...     print(f"Failed {result.failed} sessions")
+
+        See also:
+            rebuild_event_index: Rebuild SQLite index from JSONL
+            query_events: Query exported events
+        """
+        from htmlgraph.operations import events
+
+        return events.export_sessions(
+            graph_dir=self._directory,
+            overwrite=overwrite,
+        )
+
+    def rebuild_event_index(self) -> Any:
+        """
+        Rebuild SQLite analytics index from JSONL events.
+
+        Creates an optimized SQLite index for fast analytics queries.
+
+        Returns:
+            EventRebuildResult with db_path and counts of inserted/skipped events
+
+        Raises:
+            EventOperationError: If rebuild fails
+
+        Example:
+            >>> sdk = SDK(agent="claude")
+            >>> result = sdk.rebuild_event_index()
+            >>> print(f"Rebuilt index: {result.db_path}")
+            >>> print(f"Inserted {result.inserted} events")
+            >>> print(f"Skipped {result.skipped} (duplicates)")
+
+        See also:
+            export_sessions: Export HTML sessions to JSONL first
+        """
+        from htmlgraph.operations import events
+
+        return events.rebuild_index(graph_dir=self._directory)
+
+    def query_events(
+        self,
+        session_id: str | None = None,
+        tool: str | None = None,
+        feature_id: str | None = None,
+        since: str | None = None,
+        limit: int | None = None,
+    ) -> Any:
+        """
+        Query events from JSONL logs with optional filters.
+
+        Args:
+            session_id: Filter by session ID (None = all sessions)
+            tool: Filter by tool name (e.g., 'Bash', 'Edit')
+            feature_id: Filter by attributed feature ID
+            since: Only events after this timestamp (ISO string)
+            limit: Maximum number of events to return
+
+        Returns:
+            EventQueryResult with matching events and total count
+
+        Raises:
+            EventOperationError: If query fails
+
+        Example:
+            >>> sdk = SDK(agent="claude")
+            >>> # Get all events for a session
+            >>> result = sdk.query_events(session_id="sess-123")
+            >>> print(f"Found {result.total} events")
+            >>>
+            >>> # Get recent Bash events
+            >>> result = sdk.query_events(
+            ...     tool="Bash",
+            ...     since="2025-01-01T00:00:00Z",
+            ...     limit=10
+            ... )
+            >>> for event in result.events:
+            ...     print(f"{event['timestamp']}: {event['summary']}")
+
+        See also:
+            export_sessions: Export sessions to JSONL first
+            get_event_stats: Get event statistics
+        """
+        from htmlgraph.operations import events
+
+        return events.query_events(
+            graph_dir=self._directory,
+            session_id=session_id,
+            tool=tool,
+            feature_id=feature_id,
+            since=since,
+            limit=limit,
+        )
+
+    def get_event_stats(self) -> Any:
+        """
+        Get statistics about events in the system.
+
+        Returns:
+            EventStats with counts of total events, sessions, and files
+
+        Example:
+            >>> sdk = SDK(agent="claude")
+            >>> stats = sdk.get_event_stats()
+            >>> print(f"Total events: {stats.total_events}")
+            >>> print(f"Sessions: {stats.session_count}")
+            >>> print(f"JSONL files: {stats.file_count}")
+        """
+        from htmlgraph.operations import events
+
+        return events.get_event_stats(graph_dir=self._directory)
+
+    def analyze_session(self, session_id: str) -> Any:
+        """
+        Compute detailed analytics for a single session.
+
+        Analyzes work distribution, spike-to-feature ratio, maintenance burden,
+        transition metrics, and more.
+
+        Args:
+            session_id: ID of the session to analyze
+
+        Returns:
+            AnalyticsSessionResult with session metrics and warnings
+
+        Raises:
+            AnalyticsOperationError: If session cannot be analyzed
+
+        Example:
+            >>> sdk = SDK(agent="claude")
+            >>> result = sdk.analyze_session("sess-123")
+            >>> print(f"Primary work type: {result.metrics['primary_work_type']}")
+            >>> print(f"Total events: {result.metrics['total_events']}")
+            >>> print(f"Work distribution: {result.metrics['work_distribution']}")
+            >>> if result.warnings:
+            ...     print(f"Warnings: {result.warnings}")
+
+        See also:
+            analyze_project: Analyze entire project
+        """
+        from htmlgraph.operations import analytics
+
+        return analytics.analyze_session(
+            graph_dir=self._directory,
+            session_id=session_id,
+        )
+
+    def analyze_project(self) -> Any:
+        """
+        Compute project-wide analytics.
+
+        Analyzes all sessions, work distribution, spike-to-feature ratios,
+        maintenance burden, and session types across the entire project.
+
+        Returns:
+            AnalyticsProjectResult with project metrics and warnings
+
+        Raises:
+            AnalyticsOperationError: If project cannot be analyzed
+
+        Example:
+            >>> sdk = SDK(agent="claude")
+            >>> result = sdk.analyze_project()
+            >>> print(f"Total sessions: {result.metrics['total_sessions']}")
+            >>> print(f"Work distribution: {result.metrics['work_distribution']}")
+            >>> print(f"Spike-to-feature ratio: {result.metrics['spike_to_feature_ratio']}")
+            >>> print(f"Session types: {result.metrics['session_types']}")
+            >>> for session in result.metrics['recent_sessions']:
+            ...     print(f"  {session['session_id']}: {session['primary_work_type']}")
+
+        See also:
+            analyze_session: Analyze a single session
+            get_work_recommendations: Get work recommendations
+        """
+        from htmlgraph.operations import analytics
+
+        return analytics.analyze_project(graph_dir=self._directory)
+
+    def get_work_recommendations(self) -> Any:
+        """
+        Get smart work recommendations based on project state.
+
+        Uses dependency analytics to recommend next tasks based on priority,
+        dependencies, and impact.
+
+        Returns:
+            RecommendationsResult with recommendations, reasoning, and warnings
+
+        Raises:
+            AnalyticsOperationError: If recommendations cannot be generated
+
+        Example:
+            >>> sdk = SDK(agent="claude")
+            >>> result = sdk.get_work_recommendations()
+            >>> for rec in result.recommendations:
+            ...     print(f"{rec['title']} (score: {rec['score']})")
+            ...     print(f"  Reasons: {rec['reasons']}")
+            ...     print(f"  Unlocks: {rec['unlocks']}")
+            >>> print(f"Reasoning: {result.reasoning}")
+
+        See also:
+            recommend_next_work: Legacy method (backward compatibility)
+            get_work_queue: Get prioritized work queue
+        """
+        from htmlgraph.operations import analytics
+
+        return analytics.get_recommendations(graph_dir=self._directory)
+
     # =========================================================================
     # Help & Documentation
     # =========================================================================
@@ -1870,11 +2290,24 @@ ANALYTICS INTERFACES:
   sdk.dep_analytics    - Dependency analytics
   sdk.context          - Context analytics
 
+OPERATIONS (Server, Hooks, Events):
+  sdk.start_server()         - Start web server for graph browsing
+  sdk.stop_server()          - Stop running server
+  sdk.install_hooks()        - Install Git hooks for tracking
+  sdk.list_hooks()           - List Git hooks status
+  sdk.export_sessions()      - Export HTML sessions to JSONL
+  sdk.rebuild_event_index()  - Rebuild SQLite index from events
+  sdk.query_events()         - Query JSONL event logs
+  sdk.get_event_stats()      - Get event statistics
+  sdk.analyze_session()      - Analyze single session metrics
+  sdk.analyze_project()      - Analyze project-wide metrics
+  sdk.get_work_recommendations() - Get work recommendations
+
 ERROR HANDLING:
   Lookup (.get)      - Returns None if not found
   Query (.where)     - Returns empty list on no matches
   Edit (.edit)       - Raises NodeNotFoundError if missing
-  Batch (.mark_done) - Returns count of successful operations
+  Batch (.mark_done) - Returns dict with success_count, failed_ids, warnings
 
 For detailed help on a topic:
   sdk.help('features')      - Feature collection methods
@@ -1882,6 +2315,7 @@ For detailed help on a topic:
   sdk.help('sessions')      - Session management
   sdk.help('orchestration') - Subagent orchestration
   sdk.help('planning')      - Planning workflow
+  sdk.help('operations')    - Server, hooks, events operations
 """
 
     def __dir__(self) -> list[str]:
@@ -1917,6 +2351,11 @@ For detailed help on a topic:
             # Work queue
             "get_work_queue",
             "work_next",
+            # Operations
+            "start_server",
+            "install_hooks",
+            "export_sessions",
+            "analyze_project",
             # Help
             "help",
         ]
@@ -1964,6 +2403,18 @@ CONTEXT MANAGER:
       f.complete_step(0)
       # Auto-saves on exit
 
+BATCH OPERATIONS:
+  result = sdk.features.mark_done(["feat-001", "feat-002"])
+  print(f"Completed {result['success_count']} features")
+  if result['failed_ids']:
+      print(f"Failed: {result['failed_ids']}")
+
+COMMON MISTAKES:
+  ❌ sdk.features.mark_complete([ids])  → ✅ sdk.features.mark_done([ids])
+  ❌ sdk.feature.create(...)            → ✅ sdk.features.create(...)
+  ❌ claim(id, agent_id=...)            → ✅ claim(id, agent=...)
+  ❌ builder.status = "done"            → ✅ builder.save(); then edit()
+
 See also: sdk.help('bugs'), sdk.help('spikes'), sdk.help('chores')
 """
 
@@ -2344,6 +2795,77 @@ BENEFITS:
   - All context in one place
 
 See also: sdk.help('sessions')
+"""
+
+        elif topic in ["operation", "operations", "server", "hooks", "events"]:
+            return """OPERATIONS - Server, Hooks, Events
+
+Infrastructure operations for running HtmlGraph.
+
+SERVER OPERATIONS:
+  # Start server for web UI
+  result = sdk.start_server(port=8080, watch=True)
+  print(f"Server at {result.handle.url}")
+
+  # Stop server
+  sdk.stop_server(result.handle)
+
+  # Check status
+  status = sdk.get_server_status(result.handle)
+
+HOOK OPERATIONS:
+  # Install Git hooks for automatic tracking
+  result = sdk.install_hooks()
+  print(f"Installed: {result.installed}")
+
+  # List hook status
+  result = sdk.list_hooks()
+  print(f"Enabled: {result.enabled}")
+  print(f"Missing: {result.missing}")
+
+  # Validate configuration
+  result = sdk.validate_hook_config()
+  if not result.valid:
+      print(f"Errors: {result.errors}")
+
+EVENT OPERATIONS:
+  # Export HTML sessions to JSONL
+  result = sdk.export_sessions()
+  print(f"Exported {result.written} sessions")
+
+  # Rebuild SQLite index
+  result = sdk.rebuild_event_index()
+  print(f"Inserted {result.inserted} events")
+
+  # Query events
+  result = sdk.query_events(
+      session_id="sess-123",
+      tool="Bash",
+      limit=10
+  )
+  for event in result.events:
+      print(f"{event['timestamp']}: {event['summary']}")
+
+  # Get statistics
+  stats = sdk.get_event_stats()
+  print(f"Total events: {stats.total_events}")
+
+ANALYTICS OPERATIONS:
+  # Analyze session
+  result = sdk.analyze_session("sess-123")
+  print(f"Primary work: {result.metrics['primary_work_type']}")
+
+  # Analyze project
+  result = sdk.analyze_project()
+  print(f"Total sessions: {result.metrics['total_sessions']}")
+  print(f"Work distribution: {result.metrics['work_distribution']}")
+
+  # Get recommendations
+  result = sdk.get_work_recommendations()
+  for rec in result.recommendations:
+      print(f"{rec['title']} (score: {rec['score']})")
+
+See also: sdk.help('analytics'), sdk.help('sessions')
 """
 
         else: