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

htmlgraph/operations/events.py

@@ -0,0 +1,244 @@
+from __future__ import annotations
+
+"""Event and analytics index operations for HtmlGraph."""
+
+
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any
+
+
+@dataclass(frozen=True)
+class EventRebuildResult:
+    """Result of rebuilding the event index."""
+
+    db_path: Path
+    inserted: int
+    skipped: int
+
+
+@dataclass(frozen=True)
+class EventStats:
+    """Statistics about events in the system."""
+
+    total_events: int
+    session_count: int
+    file_count: int
+
+
+@dataclass(frozen=True)
+class EventQueryResult:
+    """Result of querying events."""
+
+    events: list[dict[str, Any]]
+    total: int
+
+
+@dataclass(frozen=True)
+class EventExportResult:
+    """Result of exporting sessions to JSONL."""
+
+    written: int
+    skipped: int
+    failed: int
+
+
+class EventOperationError(RuntimeError):
+    """Base error for event operations."""
+
+
+def export_sessions(*, graph_dir: Path, overwrite: bool = False) -> EventExportResult:
+    """
+    Export legacy session HTML logs to JSONL events.
+
+    Args:
+        graph_dir: Path to .htmlgraph directory
+        overwrite: Whether to overwrite existing JSONL files
+
+    Returns:
+        EventExportResult with counts of written, skipped, failed files
+
+    Raises:
+        EventOperationError: If graph_dir doesn't exist or isn't a directory
+    """
+    if not graph_dir.exists():
+        raise EventOperationError(f"Graph directory not found: {graph_dir}")
+    if not graph_dir.is_dir():
+        raise EventOperationError(f"Not a directory: {graph_dir}")
+
+    from htmlgraph.event_migration import export_sessions_to_jsonl
+
+    sessions_dir = graph_dir / "sessions"
+    events_dir = graph_dir / "events"
+
+    if not sessions_dir.exists():
+        raise EventOperationError(f"Sessions directory not found: {sessions_dir}")
+
+    try:
+        result = export_sessions_to_jsonl(
+            sessions_dir=sessions_dir,
+            events_dir=events_dir,
+            overwrite=overwrite,
+            include_subdirs=False,
+        )
+        return EventExportResult(
+            written=result["written"],
+            skipped=result["skipped"],
+            failed=result["failed"],
+        )
+    except Exception as e:
+        raise EventOperationError(f"Failed to export sessions: {e}") from e
+
+
+def rebuild_index(*, graph_dir: Path) -> EventRebuildResult:
+    """
+    Rebuild the SQLite analytics index from JSONL events.
+
+    Args:
+        graph_dir: Path to .htmlgraph directory
+
+    Returns:
+        EventRebuildResult with db_path and counts of inserted/skipped events
+
+    Raises:
+        EventOperationError: If events directory doesn't exist or rebuild fails
+    """
+    if not graph_dir.exists():
+        raise EventOperationError(f"Graph directory not found: {graph_dir}")
+    if not graph_dir.is_dir():
+        raise EventOperationError(f"Not a directory: {graph_dir}")
+
+    from htmlgraph.analytics_index import AnalyticsIndex
+    from htmlgraph.event_log import JsonlEventLog
+
+    events_dir = graph_dir / "events"
+    db_path = graph_dir / "index.sqlite"
+
+    if not events_dir.exists():
+        raise EventOperationError(f"Events directory not found: {events_dir}")
+
+    try:
+        log = JsonlEventLog(events_dir)
+        index = AnalyticsIndex(db_path)
+
+        # Stream events from all JSONL files
+        events = (event for _, event in log.iter_events())
+        result = index.rebuild_from_events(events)
+
+        return EventRebuildResult(
+            db_path=db_path,
+            inserted=result["inserted"],
+            skipped=result["skipped"],
+        )
+    except Exception as e:
+        raise EventOperationError(f"Failed to rebuild index: {e}") from e
+
+
+def query_events(
+    *,
+    graph_dir: Path,
+    session_id: str | None = None,
+    tool: str | None = None,
+    feature_id: str | None = None,
+    since: str | None = None,
+    limit: int | None = None,
+) -> EventQueryResult:
+    """
+    Query events from JSONL logs with optional filters.
+
+    Args:
+        graph_dir: Path to .htmlgraph directory
+        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 events directory doesn't exist or query fails
+    """
+    if not graph_dir.exists():
+        raise EventOperationError(f"Graph directory not found: {graph_dir}")
+    if not graph_dir.is_dir():
+        raise EventOperationError(f"Not a directory: {graph_dir}")
+
+    from htmlgraph.event_log import JsonlEventLog
+
+    events_dir = graph_dir / "events"
+
+    if not events_dir.exists():
+        raise EventOperationError(f"Events directory not found: {events_dir}")
+
+    try:
+        log = JsonlEventLog(events_dir)
+        events = log.query_events(
+            session_id=session_id,
+            tool=tool,
+            feature_id=feature_id,
+            since=since,
+            limit=limit,
+        )
+
+        return EventQueryResult(
+            events=events,
+            total=len(events),
+        )
+    except Exception as e:
+        raise EventOperationError(f"Failed to query events: {e}") from e
+
+
+def get_event_stats(*, graph_dir: Path) -> EventStats:
+    """
+    Get statistics about events in the system.
+
+    Args:
+        graph_dir: Path to .htmlgraph directory
+
+    Returns:
+        EventStats with counts of total events, sessions, and files
+
+    Raises:
+        EventOperationError: If events directory doesn't exist or stats collection fails
+    """
+    if not graph_dir.exists():
+        raise EventOperationError(f"Graph directory not found: {graph_dir}")
+    if not graph_dir.is_dir():
+        raise EventOperationError(f"Not a directory: {graph_dir}")
+
+    from htmlgraph.event_log import JsonlEventLog
+
+    events_dir = graph_dir / "events"
+
+    if not events_dir.exists():
+        # No events directory means no events
+        return EventStats(
+            total_events=0,
+            session_count=0,
+            file_count=0,
+        )
+
+    try:
+        log = JsonlEventLog(events_dir)
+
+        # Count total events and track unique sessions
+        total_events = 0
+        sessions: set[str] = set()
+
+        for _, event in log.iter_events():
+            total_events += 1
+            if session_id := event.get("session_id"):
+                sessions.add(session_id)
+
+        # Count JSONL files
+        file_count = len(list(events_dir.glob("*.jsonl")))
+
+        return EventStats(
+            total_events=total_events,
+            session_count=len(sessions),
+            file_count=file_count,
+        )
+    except Exception as e:
+        raise EventOperationError(f"Failed to get event stats: {e}") from e

htmlgraph/operations/fastapi_server.py

@@ -0,0 +1,231 @@
+from __future__ import annotations
+
+"""FastAPI-based server for HtmlGraph dashboard with real-time observability."""
+
+
+import logging
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any
+
+from htmlgraph.mcp_server import _resolve_project_dir
+
+logger = logging.getLogger(__name__)
+
+
+@dataclass(frozen=True)
+class FastAPIServerHandle:
+    """Handle to a running FastAPI server."""
+
+    url: str
+    port: int
+    host: str
+    server: Any | None = None
+
+
+@dataclass(frozen=True)
+class FastAPIServerStartResult:
+    """Result of starting FastAPI server."""
+
+    handle: FastAPIServerHandle
+    warnings: list[str]
+    config_used: dict[str, Any]
+
+
+class FastAPIServerError(RuntimeError):
+    """FastAPI server error."""
+
+    pass
+
+
+class PortInUseError(FastAPIServerError):
+    """Requested port is already in use."""
+
+    pass
+
+
+def start_fastapi_server(
+    *,
+    port: int = 8000,
+    host: str = "127.0.0.1",
+    db_path: str | None = None,
+    auto_port: bool = False,
+    reload: bool = False,
+) -> FastAPIServerStartResult:
+    """
+    Start FastAPI-based HtmlGraph dashboard server.
+
+    Args:
+        port: Port to listen on (default: 8000)
+        host: Host to bind to (default: 127.0.0.1)
+        db_path: Path to SQLite database file
+        auto_port: Automatically find available port if in use
+        reload: Enable auto-reload on file changes (development mode)
+
+    Returns:
+        FastAPIServerStartResult with handle, warnings, and config used
+
+    Raises:
+        PortInUseError: If port is in use and auto_port=False
+        FastAPIServerError: If server fails to start
+    """
+    import uvicorn
+
+    from htmlgraph.api.main import create_app
+
+    warnings: list[str] = []
+    original_port = port
+
+    # Default database path - prefer project-local database if available
+    if db_path is None:
+        # Check for project-local database first
+        project_dir = _resolve_project_dir()
+        project_db = Path(project_dir) / ".htmlgraph" / "htmlgraph.db"
+        if project_db.exists():
+            db_path = str(project_db)  # Use project-local database
+        else:
+            db_path = str(
+                Path.home() / ".htmlgraph" / "htmlgraph.db"
+            )  # Fall back to home
+
+    # Ensure database exists
+    db_path_obj = Path(db_path)
+    db_path_obj.parent.mkdir(parents=True, exist_ok=True)
+
+    # Handle auto-port selection
+    if auto_port and _check_port_in_use(port, host):
+        port = _find_available_port(port + 1)
+        warnings.append(f"Port {original_port} is in use, using {port} instead")
+
+    # Check if port is in use
+    if not auto_port and _check_port_in_use(port, host):
+        raise PortInUseError(
+            f"Port {port} is already in use. Use auto_port=True or choose a different port."
+        )
+
+    # Create FastAPI app
+    app = create_app(db_path=db_path)
+
+    # Create server config
+    config = uvicorn.Config(
+        app,
+        host=host,
+        port=port,
+        log_level="info",
+        reload=reload,
+        reload_dirs=None,  # Disable file watching for now
+    )
+
+    # Create server instance
+    server = uvicorn.Server(config)
+
+    # Create handle
+    handle = FastAPIServerHandle(
+        url=f"http://{host}:{port}",
+        port=port,
+        host=host,
+        server=server,
+    )
+
+    # Configuration used
+    config_used = {
+        "port": port,
+        "original_port": original_port,
+        "host": host,
+        "db_path": db_path,
+        "auto_port": auto_port,
+        "reload": reload,
+    }
+
+    return FastAPIServerStartResult(
+        handle=handle,
+        warnings=warnings,
+        config_used=config_used,
+    )
+
+
+async def run_fastapi_server(handle: FastAPIServerHandle) -> None:
+    """
+    Run FastAPI server (async).
+
+    Args:
+        handle: FastAPIServerHandle from start_fastapi_server()
+
+    Raises:
+        FastAPIServerError: If server fails
+    """
+    if handle.server is None:
+        raise FastAPIServerError("Invalid server handle")
+
+    try:
+        await handle.server.serve()
+    except Exception as e:
+        raise FastAPIServerError(f"Server error: {e}") from e
+
+
+def stop_fastapi_server(handle: FastAPIServerHandle) -> None:
+    """
+    Stop FastAPI server.
+
+    Args:
+        handle: FastAPIServerHandle from start_fastapi_server()
+
+    Raises:
+        FastAPIServerError: If shutdown fails
+    """
+    if handle.server is None:
+        return
+
+    try:
+        handle.server.should_exit = True
+    except Exception as e:
+        raise FastAPIServerError(f"Failed to stop server: {e}") from e
+
+
+def _check_port_in_use(port: int, host: str = "localhost") -> bool:
+    """
+    Check if a port is already in use.
+
+    Args:
+        port: Port number to check
+        host: Host to check on
+
+    Returns:
+        True if port is in use, False otherwise
+    """
+    import socket
+
+    try:
+        with socket.socket(socket.AF_INET, socket.SOCK_STREAM) as s:
+            s.bind((host, port))
+            return False
+    except OSError:
+        return True
+
+
+def _find_available_port(start_port: int = 8000, max_attempts: int = 10) -> int:
+    """
+    Find an available port starting from start_port.
+
+    Args:
+        start_port: Port to start searching from
+        max_attempts: Maximum number of ports to try
+
+    Returns:
+        Available port number
+
+    Raises:
+        FastAPIServerError: If no available port found
+    """
+    import socket
+
+    for port in range(start_port, start_port + max_attempts):
+        try:
+            with socket.socket(socket.AF_INET, socket.SOCK_STREAM) as s:
+                s.bind(("", port))
+                return port
+        except OSError:
+            continue
+    raise FastAPIServerError(
+        f"No available ports found in range {start_port}-{start_port + max_attempts}"
+    )