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

htmlgraph/server.py

@@ -1,3 +1,7 @@
+import logging
+
+logger = logging.getLogger(__name__)
+
 """
 HtmlGraph REST API Server.
 
@@ -17,14 +21,13 @@ import socket
 import sys
 import urllib.parse
 from datetime import datetime, timezone
-from http.server import HTTPServer, SimpleHTTPRequestHandler
+from http.server import SimpleHTTPRequestHandler
 from pathlib import Path
 from typing import Any, Literal, cast
 
 from htmlgraph.analytics_index import AnalyticsIndex
 from htmlgraph.converter import dict_to_node, node_to_dict
 from htmlgraph.event_log import JsonlEventLog
-from htmlgraph.file_watcher import GraphWatcher
 from htmlgraph.graph import HtmlGraph
 from htmlgraph.ids import generate_id
 from htmlgraph.models import Node
@@ -49,6 +52,7 @@ class HtmlGraphAPIHandler(SimpleHTTPRequestHandler):
         "sessions",
         "agents",
         "tracks",
+        "task-delegations",
     ]
 
     def __init__(self, *args: Any, **kwargs: Any) -> None:
@@ -210,7 +214,15 @@ class HtmlGraphAPIHandler(SimpleHTTPRequestHandler):
         return "api", collection, node_id, query_params
 
     def _serve_packaged_dashboard(self) -> bool:
-        """Serve the bundled dashboard HTML if available."""
+        """
+        DEPRECATED: Serve the bundled dashboard HTML if available.
+
+        NOTE: This server is LEGACY. The active server is FastAPI-based.
+        See: src/python/htmlgraph/operations/fastapi_server.py
+
+        The dashboard.html file was archived to .archived-templates/
+        Active templates are in src/python/htmlgraph/api/templates/
+        """
         dashboard_path = Path(__file__).parent / "dashboard.html"
         if not dashboard_path.exists():
             return False
@@ -235,6 +247,9 @@ class HtmlGraphAPIHandler(SimpleHTTPRequestHandler):
     def do_GET(self) -> None:
         """Handle GET requests."""
         api, collection, node_id, params = self._parse_path()
+        logger.debug(
+            f"do_GET: api={api}, collection={collection}, node_id={node_id}, params={params}"
+        )
 
         # Not an API request - serve static files
         if api != "api":
@@ -260,6 +275,15 @@ class HtmlGraphAPIHandler(SimpleHTTPRequestHandler):
         if collection == "analytics":
             return self._handle_analytics(node_id, params)
 
+        # GET /api/orchestration - Get delegation chains and agent coordination
+        if collection == "orchestration":
+            logger.info(f"DEBUG: Handling orchestration request, params={params}")
+            return self._handle_orchestration_view(params)
+
+        # GET /api/task-delegations/stats - Get aggregated delegation statistics
+        if collection == "task-delegations" and params.get("stats") == "true":
+            return self._handle_task_delegations_stats()
+
         # GET /api/tracks/{track_id}/features - Get features for a track
         if collection == "tracks" and node_id and params.get("features") == "true":
             return self._handle_track_features(node_id)
@@ -1043,6 +1067,187 @@ class HtmlGraphAPIHandler(SimpleHTTPRequestHandler):
         except Exception as e:
             self._send_error_json(f"Failed to generate features: {str(e)}", 500)
 
+    def _handle_orchestration_view(self, params: dict) -> None:
+        """
+        Get delegation chains and agent coordination information.
+
+        Queries the SQLite database for delegation events and builds
+        a view of agent coordination and handoff patterns.
+
+        Returns:
+            {
+                "delegation_count": int,
+                "unique_agents": int,
+                "agents": [str],
+                "delegation_chains": {
+                    "from_agent": [
+                        {
+                            "to_agent": str,
+                            "event_type": str,
+                            "timestamp": str,
+                            "task": str,
+                            "status": str
+                        }
+                    ]
+                }
+            }
+        """
+        try:
+            from htmlgraph.db.schema import HtmlGraphDB
+
+            # Use unified index.sqlite database
+            db_path = str(self.graph_dir / "index.sqlite")
+            db = HtmlGraphDB(db_path=db_path)
+            db.connect()
+
+            # Get all delegation events
+            delegations = db.get_delegations(limit=1000)
+            db.close()
+
+            # Build delegation chains grouped by from_agent
+            delegation_chains: dict[str, list[dict]] = {}
+            agents = set()
+            delegation_count = 0
+
+            for delegation in delegations:
+                from_agent = delegation.get("from_agent", "unknown")
+                to_agent = delegation.get("to_agent", "unknown")
+                timestamp = delegation.get("timestamp", "")
+                reason = delegation.get("reason", "")
+                status = delegation.get("status", "pending")
+
+                agents.add(from_agent)
+                agents.add(to_agent)
+                delegation_count += 1
+
+                if from_agent not in delegation_chains:
+                    delegation_chains[from_agent] = []
+
+                delegation_chains[from_agent].append(
+                    {
+                        "to_agent": to_agent,
+                        "event_type": "delegation",
+                        "timestamp": timestamp,
+                        "task": reason or "Unnamed task",
+                        "status": status,
+                    }
+                )
+
+            self._send_json(
+                {
+                    "delegation_count": delegation_count,
+                    "unique_agents": len(agents),
+                    "agents": sorted(list(agents)),
+                    "delegation_chains": delegation_chains,
+                }
+            )
+
+        except Exception as e:
+            self._send_error_json(f"Failed to get orchestration view: {str(e)}", 500)
+
+    def _handle_task_delegations_stats(self) -> None:
+        """Get aggregated statistics about task delegations."""
+        try:
+            delegations_graph = self._get_graph("task-delegations")
+
+            # Get all delegations
+            all_delegations = list(delegations_graph)
+
+            if not all_delegations:
+                self._send_json(
+                    {
+                        "total_delegations": 0,
+                        "by_agent_type": {},
+                        "by_status": {},
+                        "total_tokens": 0,
+                        "total_cost": 0.0,
+                        "average_duration": 0.0,
+                        "agent_stats": [],
+                    }
+                )
+                return
+
+            # Aggregate by agent type
+            agent_stats: dict = {}
+            by_status: dict[str, int] = {}
+            total_tokens = 0
+            total_cost = 0.0
+            durations = []
+
+            for delegation in all_delegations:
+                agent_type = str(getattr(delegation, "agent_type", "unknown"))
+                status = str(getattr(delegation, "status", "unknown"))
+                tokens_val = getattr(delegation, "tokens_used", 0)
+                tokens = int(tokens_val) if tokens_val else 0
+                cost_val = getattr(delegation, "cost_usd", 0)
+                cost = float(cost_val) if cost_val else 0.0
+                duration_val = getattr(delegation, "duration_seconds", 0)
+                duration = int(duration_val) if duration_val else 0
+
+                # Track by agent
+                if agent_type not in agent_stats:
+                    agent_stats[agent_type] = {
+                        "agent_type": agent_type,
+                        "tasks_completed": 0,
+                        "total_duration": 0,
+                        "total_tokens": 0,
+                        "total_cost": 0.0,
+                        "success_count": 0,
+                        "failure_count": 0,
+                    }
+
+                agent_stats[agent_type]["tasks_completed"] += 1
+                agent_stats[agent_type]["total_duration"] += duration
+                agent_stats[agent_type]["total_tokens"] += tokens
+                agent_stats[agent_type]["total_cost"] += cost
+
+                if status == "success":
+                    agent_stats[agent_type]["success_count"] += 1
+                else:
+                    agent_stats[agent_type]["failure_count"] += 1
+
+                # Track by status
+                by_status[status] = by_status.get(status, 0) + 1
+
+                # Aggregate totals
+                total_tokens += tokens
+                total_cost += cost
+                if duration:
+                    durations.append(duration)
+
+            # Calculate success rate for each agent
+            for agent_stats_item in agent_stats.values():
+                total = agent_stats_item["tasks_completed"]
+                if total > 0:
+                    agent_stats_item["success_rate"] = (
+                        agent_stats_item["success_count"] / total
+                    )
+                else:
+                    agent_stats_item["success_rate"] = 0.0
+
+            average_duration = sum(durations) / len(durations) if durations else 0.0
+
+            self._send_json(
+                {
+                    "total_delegations": len(all_delegations),
+                    "by_agent_type": {
+                        agent: stats["tasks_completed"]
+                        for agent, stats in agent_stats.items()
+                    },
+                    "by_status": by_status,
+                    "total_tokens": total_tokens,
+                    "total_cost": round(total_cost, 4),
+                    "average_duration": round(average_duration, 2),
+                    "agent_stats": sorted(
+                        agent_stats.values(),
+                        key=lambda x: x["total_cost"],
+                        reverse=True,
+                    ),
+                }
+            )
+        except Exception as e:
+            self._send_error_json(f"Failed to get delegation stats: {str(e)}", 500)
+
     def _handle_sync_track(self, track_id: str) -> None:
         """Sync task and spec completion based on features."""
         from htmlgraph.track_manager import TrackManager
@@ -1074,7 +1279,7 @@ class HtmlGraphAPIHandler(SimpleHTTPRequestHandler):
 
     def log_message(self, format: str, *args: str) -> None:
         """Custom log format."""
-        print(f"[{datetime.now().strftime('%H:%M:%S')}] {args[0]}")
+        logger.info(f"[{datetime.now().strftime('%H:%M:%S')}] {args[0]}")
 
 
 def find_available_port(start_port: int = 8080, max_attempts: int = 10) -> int:
@@ -1174,42 +1379,39 @@ def serve(
     host: str = "localhost",
     watch: bool = True,
     auto_port: bool = False,
+    show_progress: bool = False,
+    quiet: bool = False,
 ) -> None:
     """
-    Start the HtmlGraph server.
-    Auto-syncs dashboard.html to index.html before starting.
+    Start the HtmlGraph server (FastAPI-based with WebSocket support).
+
+    This function launches the FastAPI server which provides:
+    - REST API for CRUD operations on graph nodes
+    - WebSocket endpoint at /ws/events for real-time event streaming
+    - HTMX-powered dashboard for agent observability
 
     Args:
-        port: Port to listen on
+        port: Port to listen on (default: 8080)
         graph_dir: Directory containing graph data (.htmlgraph/)
-        static_dir: Directory for static files (index.html, etc.)
-        host: Host to bind to
-        watch: Enable file watching for auto-reload (default: True)
+        static_dir: Directory for static files (index.html, etc.) - preserved for compatibility
+        host: Host to bind to (default: localhost)
+        watch: Enable file watching for auto-reload (default: True) - maps to reload in FastAPI
         auto_port: Automatically find available port if specified port is in use
+        show_progress: Show Rich progress during startup (not used with FastAPI)
+        quiet: Suppress progress output when true
     """
-    graph_dir = Path(graph_dir)
-    static_dir = Path(static_dir)
+    import asyncio
 
-    # Handle auto-port selection
-    if auto_port and check_port_in_use(port, host):
-        original_port = port
-        port = find_available_port(port + 1)
-        print(f"⚠️  Port {original_port} is in use, using {port} instead\n")
+    from htmlgraph.operations.fastapi_server import (
+        FastAPIServerError,
+        PortInUseError,
+        run_fastapi_server,
+        start_fastapi_server,
+    )
 
-    # Auto-sync dashboard files
-    try:
-        if sync_dashboard_files(static_dir):
-            print("⚠️  Dashboard files out of sync")
-            print("✅ Synced dashboard.html → index.html\n")
-    except PermissionError as e:
-        print(f"⚠️  Warning: Unable to sync dashboard files: {e}")
-        print(
-            f"   Run: cp src/python/htmlgraph/dashboard.html {static_dir / 'index.html'}\n"
-        )
-    except Exception as e:
-        print(f"⚠️  Warning: Error during dashboard sync: {e}\n")
+    graph_dir = Path(graph_dir)
 
-    # Create graph directory structure
+    # Ensure graph directory exists
     graph_dir.mkdir(parents=True, exist_ok=True)
     for collection in HtmlGraphAPIHandler.COLLECTIONS:
         (graph_dir / collection).mkdir(exist_ok=True)
@@ -1221,99 +1423,85 @@ def serve(
         if styles_src.exists():
             styles_dest.write_text(styles_src.read_text())
 
-    # Configure handler
-    HtmlGraphAPIHandler.graph_dir = graph_dir
-    HtmlGraphAPIHandler.static_dir = static_dir
-    HtmlGraphAPIHandler.graphs = {}
-    HtmlGraphAPIHandler.analytics_db = None
+    # Database path - use htmlgraph.db in the graph directory
+    db_path = str(graph_dir / "htmlgraph.db")
 
-    # Create server with error handling
     try:
-        server = HTTPServer((host, port), HtmlGraphAPIHandler)
-    except OSError as e:
-        # Handle "Address already in use" error
-        if e.errno == 48 or "Address already in use" in str(e):
-            print(f"\n❌ Port {port} is already in use\n")
-            print("Solutions:")
-            print("  1. Use a different port:")
-            print(f"     htmlgraph serve --port {port + 1}\n")
-            print("  2. Let htmlgraph automatically find an available port:")
-            print("     htmlgraph serve --auto-port\n")
-            print(f"  3. Find and kill the process using port {port}:")
-            print(f"     lsof -ti:{port} | xargs kill -9\n")
-
-            # Try to find and suggest an available port
-            try:
-                alt_port = find_available_port(port + 1)
-                print(f"💡 Found available port: {alt_port}")
-                print(f"   Run: htmlgraph serve --port {alt_port}\n")
-            except OSError:
-                pass
-
-            sys.exit(1)
-        # Re-raise other OSErrors
-        raise
-
-    # Start file watcher if enabled
-    watcher = None
-    if watch:
-
-        def get_graph(collection: str) -> HtmlGraph:
-            """Callback to get graph instance for a collection."""
-            handler = HtmlGraphAPIHandler
-            if collection not in handler.graphs:
-                collection_dir = handler.graph_dir / collection
-                handler.graphs[collection] = HtmlGraph(
-                    collection_dir, stylesheet_path="../styles.css", auto_load=True
-                )
-            return handler.graphs[collection]
-
-        watcher = GraphWatcher(
-            graph_dir=graph_dir,
-            collections=HtmlGraphAPIHandler.COLLECTIONS,
-            get_graph_callback=get_graph,
+        result = start_fastapi_server(
+            port=port,
+            host=host,
+            db_path=db_path,
+            auto_port=auto_port,
+            reload=watch,  # Map watch to reload for FastAPI
         )
-        watcher.start()
 
-    watch_status = "Enabled" if watch else "Disabled"
-    print(f"""
+        # Print warnings if any
+        for warning in result.warnings:
+            if not quiet:
+                logger.info(f"⚠️  {warning}")
+
+        # Print server info
+        if not quiet:
+            actual_port = result.config_used["port"]
+            print(f"""
 ╔══════════════════════════════════════════════════════════════╗
-║                    HtmlGraph Server                          ║
+║              HtmlGraph Server (FastAPI)                      ║
 ╠══════════════════════════════════════════════════════════════╣
-║  Dashboard:  http://{host}:{port}/
-║  API:        http://{host}:{port}/api/
-║  Graph Dir:  {graph_dir}
-║  Auto-reload: {watch_status}
+║  Dashboard:   http://{host}:{actual_port}/
+║  API:         http://{host}:{actual_port}/api/
+║  WebSocket:   ws://{host}:{actual_port}/ws/events
+║  Graph Dir:   {graph_dir}
+║  Database:    {db_path}
+║  Auto-reload: {"Enabled" if watch else "Disabled"}
 ╚══════════════════════════════════════════════════════════════╝
 
+Features:
+  • Real-time agent activity feed (HTMX + WebSocket)
+  • Orchestration chains visualization
+  • Feature tracker with Kanban view
+  • Session metrics & performance analytics
+
 API Endpoints:
-  GET    /api/status              - Overall status
-  GET    /api/collections         - List collections
-  GET    /api/query?status=todo   - Query across collections
-  GET    /api/analytics/overview  - Analytics overview (requires index)
-  GET    /api/analytics/features  - Top features (requires index)
-  GET    /api/analytics/continuity?feature_id=... - Feature continuity (requires index)
-  GET    /api/analytics/transitions - Tool transitions (requires index)
-
-  GET    /api/{{collection}}        - List nodes
-  POST   /api/{{collection}}        - Create node
-  GET    /api/{{collection}}/{{id}}    - Get node
-  PUT    /api/{{collection}}/{{id}}    - Replace node
-  PATCH  /api/{{collection}}/{{id}}    - Update node
-  DELETE /api/{{collection}}/{{id}}    - Delete node
+  GET    /api/events              - List events
+  GET    /api/sessions            - List sessions
+  GET    /api/orchestration       - Orchestration data
+  GET    /api/initial-stats       - Dashboard statistics
+  WS     /ws/events               - Real-time event stream
 
 Collections: {", ".join(HtmlGraphAPIHandler.COLLECTIONS)}
 
 Press Ctrl+C to stop.
 """)
 
-    try:
-        server.serve_forever()
+        # Run the server
+        asyncio.run(run_fastapi_server(result.handle))
+
+    except PortInUseError:
+        logger.info(f"\n❌ Port {port} is already in use\n")
+        logger.info("Solutions:")
+        logger.info("  1. Use a different port:")
+        logger.info(f"     htmlgraph serve --port {port + 1}\n")
+        logger.info("  2. Let htmlgraph automatically find an available port:")
+        logger.info("     htmlgraph serve --auto-port\n")
+        logger.info(f"  3. Find and kill the process using port {port}:")
+        logger.info(f"     lsof -ti:{port} | xargs kill -9\n")
+
+        # Try to find and suggest an available port
+        try:
+            alt_port = find_available_port(port + 1)
+            logger.info(f"💡 Found available port: {alt_port}")
+            logger.info(f"   Run: htmlgraph serve --port {alt_port}\n")
+        except OSError:
+            pass
+
+        sys.exit(1)
+
+    except FastAPIServerError as e:
+        logger.info(f"\n❌ Server error: {e}\n")
+        sys.exit(1)
+
     except KeyboardInterrupt:
-        print("\nShutting down...")
-        if watcher:
-            watcher.stop()
-        server.shutdown()
+        logger.info("\nShutting down...")
 
 
 if __name__ == "__main__":