flock-core 0.5.0b28__py3-none-any.whl → 0.5.56b0__py3-none-any.whl

flock/dashboard/collector.py

@@ -0,0 +1,283 @@
+"""DashboardEventCollector - captures agent lifecycle events for real-time dashboard.
+
+This component hooks into the agent execution lifecycle to emit WebSocket events.
+Phase 1: Events stored in in-memory buffer (max 100 events).
+Phase 3: Extended to emit via WebSocket using WebSocketManager.
+"""
+
+import traceback
+from collections import deque
+from datetime import datetime, timezone
+from typing import TYPE_CHECKING, Optional
+
+from pydantic import PrivateAttr
+
+from flock.components import AgentComponent
+from flock.dashboard.events import (
+    AgentActivatedEvent,
+    AgentCompletedEvent,
+    AgentErrorEvent,
+    MessagePublishedEvent,
+    SubscriptionInfo,
+    VisibilitySpec,
+)
+from flock.logging.logging import get_logger
+from flock.runtime import Context
+
+
+logger = get_logger("dashboard.collector")
+
+if TYPE_CHECKING:  # pragma: no cover - type hints only
+    from flock.agent import Agent
+    from flock.artifacts import Artifact
+    from flock.dashboard.websocket import WebSocketManager
+
+
+class DashboardEventCollector(AgentComponent):
+    """Collects agent lifecycle events for dashboard visualization.
+
+    Implements AgentComponent interface to hook into agent execution:
+    - on_pre_consume: emits agent_activated
+    - on_post_publish: emits message_published
+    - on_terminate: emits agent_completed
+    - on_error: emits agent_error
+
+    Phase 1: Events stored in in-memory deque (max 100, LRU eviction).
+    Phase 3: Emits events via WebSocket using WebSocketManager.
+    """
+
+    # Use PrivateAttr for non-Pydantic fields (AgentComponent extends BaseModel)
+    _events: deque[
+        AgentActivatedEvent | MessagePublishedEvent | AgentCompletedEvent | AgentErrorEvent
+    ] = PrivateAttr(default=None)
+
+    # Track run start times for duration calculation
+    _run_start_times: dict[str, float] = PrivateAttr(default_factory=dict)
+
+    # WebSocketManager for broadcasting events
+    _websocket_manager: Optional["WebSocketManager"] = PrivateAttr(default=None)
+
+    def __init__(self, **data):
+        super().__init__(**data)
+        # In-memory buffer with max 100 events (LRU eviction)
+        self._events = deque(maxlen=100)
+        self._run_start_times = {}
+        self._websocket_manager = None
+
+    def set_websocket_manager(self, manager: "WebSocketManager") -> None:
+        """Set WebSocketManager for broadcasting events.
+
+        Args:
+            manager: WebSocketManager instance to use for broadcasting
+        """
+        self._websocket_manager = manager
+
+    @property
+    def events(self) -> deque:
+        """Access events buffer."""
+        return self._events
+
+    async def on_pre_consume(
+        self, agent: "Agent", ctx: Context, inputs: list["Artifact"]
+    ) -> list["Artifact"]:
+        """Emit agent_activated event when agent begins consuming.
+
+        Args:
+            agent: The agent that is consuming
+            ctx: Execution context with correlation_id
+            inputs: Artifacts being consumed
+
+        Returns:
+            Unmodified inputs (pass-through)
+        """
+        # Record start time for duration calculation
+        self._run_start_times[ctx.task_id] = datetime.now(timezone.utc).timestamp()
+
+        # Extract consumed types and artifact IDs
+        consumed_types = list({artifact.type for artifact in inputs})
+        consumed_artifacts = [str(artifact.id) for artifact in inputs]
+
+        # Extract produced types from agent outputs
+        produced_types = [output.spec.type_name for output in agent.outputs]
+
+        # Build subscription info from agent's subscriptions
+        subscription_info = SubscriptionInfo(from_agents=[], channels=[], mode="both")
+
+        if agent.subscriptions:
+            # Get first subscription's config (agents typically have one)
+            sub = agent.subscriptions[0]
+            subscription_info.from_agents = list(sub.from_agents) if sub.from_agents else []
+            subscription_info.channels = list(sub.channels) if sub.channels else []
+            subscription_info.mode = sub.mode
+
+        # Create and store event
+        event = AgentActivatedEvent(
+            correlation_id=str(ctx.correlation_id) if ctx.correlation_id else "",
+            agent_name=agent.name,
+            agent_id=agent.name,
+            run_id=ctx.task_id,  # Unique ID for this agent run
+            consumed_types=consumed_types,
+            consumed_artifacts=consumed_artifacts,
+            produced_types=produced_types,
+            subscription_info=subscription_info,
+            labels=list(agent.labels),
+            tenant_id=agent.tenant_id,
+            max_concurrency=agent.max_concurrency,
+        )
+
+        self._events.append(event)
+        logger.info(f"Agent activated: {agent.name} (correlation_id={event.correlation_id})")
+
+        # Broadcast via WebSocket if manager is configured
+        if self._websocket_manager:
+            await self._websocket_manager.broadcast(event)
+        else:
+            logger.warning("WebSocket manager not configured, event not broadcast")
+
+        return inputs
+
+    async def on_post_publish(self, agent: "Agent", ctx: Context, artifact: "Artifact") -> None:
+        """Emit message_published event when artifact is published.
+
+        Args:
+            agent: The agent that published the artifact
+            ctx: Execution context with correlation_id
+            artifact: The published artifact
+        """
+        # Convert visibility to VisibilitySpec
+        visibility_spec = self._convert_visibility(artifact.visibility)
+
+        # Create and store event
+        event = MessagePublishedEvent(
+            correlation_id=str(ctx.correlation_id) if ctx.correlation_id else "",
+            artifact_id=str(artifact.id),
+            artifact_type=artifact.type,
+            produced_by=artifact.produced_by,
+            payload=artifact.payload,
+            visibility=visibility_spec,
+            tags=list(artifact.tags) if artifact.tags else [],
+            partition_key=artifact.partition_key,
+            version=artifact.version,
+            consumers=[],  # Phase 1: empty, Phase 3: compute from subscription matching
+        )
+
+        self._events.append(event)
+        logger.info(
+            f"Message published: {artifact.type} by {artifact.produced_by} (correlation_id={event.correlation_id})"
+        )
+
+        # Broadcast via WebSocket if manager is configured
+        if self._websocket_manager:
+            await self._websocket_manager.broadcast(event)
+        else:
+            logger.warning("WebSocket manager not configured, event not broadcast")
+
+    async def on_terminate(self, agent: "Agent", ctx: Context) -> None:
+        """Emit agent_completed event when agent finishes successfully.
+
+        Args:
+            agent: The agent that completed
+            ctx: Execution context with final state
+        """
+        # Calculate duration
+        start_time = self._run_start_times.get(ctx.task_id)
+        if start_time:
+            duration_ms = (datetime.now(timezone.utc).timestamp() - start_time) * 1000
+            del self._run_start_times[ctx.task_id]
+        else:
+            duration_ms = 0.0
+
+        # Extract artifacts produced from context state (if tracked)
+        artifacts_produced = ctx.state.get("artifacts_produced", [])
+        if not isinstance(artifacts_produced, list):
+            artifacts_produced = []
+
+        # Extract metrics from context state (if tracked)
+        metrics = ctx.state.get("metrics", {})
+        if not isinstance(metrics, dict):
+            metrics = {}
+
+        # Create and store event
+        event = AgentCompletedEvent(
+            correlation_id=str(ctx.correlation_id) if ctx.correlation_id else "",
+            agent_name=agent.name,
+            run_id=ctx.task_id,
+            duration_ms=duration_ms,
+            artifacts_produced=artifacts_produced,
+            metrics=metrics,
+            final_state=dict(ctx.state),
+        )
+
+        self._events.append(event)
+
+        # Broadcast via WebSocket if manager is configured
+        if self._websocket_manager:
+            await self._websocket_manager.broadcast(event)
+
+    async def on_error(self, agent: "Agent", ctx: Context, error: Exception) -> None:
+        """Emit agent_error event when agent execution fails.
+
+        Args:
+            agent: The agent that failed
+            ctx: Execution context
+            error: The exception that was raised
+        """
+        # Get error details
+        error_type = type(error).__name__
+        error_message = str(error)
+        # Use traceback.format_exception to get traceback from exception object
+        error_traceback = "".join(
+            traceback.format_exception(type(error), error, error.__traceback__)
+        )
+        failed_at = datetime.now(timezone.utc).isoformat().replace("+00:00", "Z")
+
+        # Clean up start time tracking
+        if ctx.task_id in self._run_start_times:
+            del self._run_start_times[ctx.task_id]
+
+        # Create and store event
+        event = AgentErrorEvent(
+            correlation_id=str(ctx.correlation_id) if ctx.correlation_id else "",
+            agent_name=agent.name,
+            run_id=ctx.task_id,
+            error_type=error_type,
+            error_message=error_message,
+            traceback=error_traceback,
+            failed_at=failed_at,
+        )
+
+        self._events.append(event)
+
+        # Broadcast via WebSocket if manager is configured
+        if self._websocket_manager:
+            await self._websocket_manager.broadcast(event)
+
+    def _convert_visibility(self, visibility) -> VisibilitySpec:
+        """Convert flock.visibility.Visibility to VisibilitySpec.
+
+        Args:
+            visibility: Visibility object from artifact
+
+        Returns:
+            VisibilitySpec for event serialization
+        """
+        # Get visibility kind from class name, stripping "Visibility" suffix
+        class_name = type(visibility).__name__
+        kind = class_name[: -len("Visibility")] if class_name.endswith("Visibility") else class_name
+
+        spec = VisibilitySpec(kind=kind)
+
+        # Extract type-specific fields
+        if kind == "Private":
+            spec.agents = list(visibility.agents) if hasattr(visibility, "agents") else []
+        elif kind == "Labelled":
+            spec.required_labels = (
+                list(visibility.required_labels) if hasattr(visibility, "required_labels") else []
+            )
+        elif kind == "Tenant":
+            spec.tenant_id = visibility.tenant_id if hasattr(visibility, "tenant_id") else None
+
+        return spec
+
+
+__all__ = ["DashboardEventCollector"]

flock/dashboard/events.py

@@ -0,0 +1,182 @@
+"""Event models for real-time dashboard.
+
+Defines 5 core event types that capture agent execution lifecycle.
+All schemas match DATA_MODEL.md specification exactly.
+"""
+
+from datetime import datetime, timezone
+from typing import Any
+
+from pydantic import BaseModel, Field
+
+
+class SubscriptionInfo(BaseModel):
+    """Subscription configuration for an agent."""
+
+    from_agents: list[str] = Field(default_factory=list)
+    channels: list[str] = Field(default_factory=list)
+    mode: str = "both"  # "both" | "events" | "direct"
+
+
+class VisibilitySpec(BaseModel):
+    """Visibility specification for artifacts.
+
+    Matches visibility types from flock.visibility module.
+    """
+
+    kind: str  # "Public" | "Private" | "Labelled" | "Tenant" | "After"
+    agents: list[str] | None = None  # For Private
+    required_labels: list[str] | None = None  # For Labelled
+    tenant_id: str | None = None  # For Tenant
+
+
+class AgentActivatedEvent(BaseModel):
+    """Event emitted when agent begins consuming artifacts.
+
+    Corresponds to on_pre_consume lifecycle hook.
+    Schema per DATA_MODEL.md lines 53-66.
+    """
+
+    # Event metadata
+    correlation_id: str
+    timestamp: str = Field(
+        default_factory=lambda: datetime.now(timezone.utc).isoformat().replace("+00:00", "Z")
+    )
+
+    # Agent identification
+    agent_name: str
+    agent_id: str  # Same as agent.name (unique per orchestrator)
+    run_id: str  # Context.task_id (unique per agent activation)
+
+    # Consumption info
+    consumed_types: list[str]  # Artifact types being consumed
+    consumed_artifacts: list[str]  # Artifact IDs being consumed
+
+    # Production info
+    produced_types: list[str]  # Artifact types this agent can produce
+
+    # Subscription configuration
+    subscription_info: SubscriptionInfo
+
+    # Agent metadata
+    labels: list[str]
+    tenant_id: str | None = None
+    max_concurrency: int = 1
+
+
+class MessagePublishedEvent(BaseModel):
+    """Event emitted when artifact is published to blackboard.
+
+    Corresponds to on_post_publish lifecycle hook.
+    Schema per DATA_MODEL.md lines 100-115.
+    """
+
+    # Event metadata
+    correlation_id: str
+    timestamp: str = Field(
+        default_factory=lambda: datetime.now(timezone.utc).isoformat().replace("+00:00", "Z")
+    )
+
+    # Artifact identification
+    artifact_id: str  # UUID
+    artifact_type: str  # "Movie", "Tagline", etc.
+
+    # Provenance
+    produced_by: str  # agent.name or "external"
+
+    # Content
+    payload: dict[str, Any]  # Full artifact.payload
+
+    # Access control
+    visibility: VisibilitySpec
+    tags: list[str] = Field(default_factory=list)
+    partition_key: str | None = None
+    version: int = 1
+
+    # Flow tracking (Phase 1: empty, Phase 3: computed from subscription matching)
+    consumers: list[str] = Field(default_factory=list)  # [agent.name]
+
+
+class StreamingOutputEvent(BaseModel):
+    """Event emitted when agent generates LLM tokens or logs.
+
+    For Phase 1: This is optional and not fully implemented.
+    Schema per DATA_MODEL.md lines 152-159.
+    """
+
+    # Event metadata
+    correlation_id: str
+    timestamp: str = Field(
+        default_factory=lambda: datetime.now(timezone.utc).isoformat().replace("+00:00", "Z")
+    )
+
+    # Agent identification
+    agent_name: str
+    run_id: str  # Context.task_id
+
+    # Output info
+    output_type: str  # "llm_token" | "log" | "stdout" | "stderr"
+    content: str  # Token text or log line
+    sequence: int  # Monotonic sequence for ordering
+    is_final: bool = False  # True when agent completes this output stream
+
+
+class AgentCompletedEvent(BaseModel):
+    """Event emitted when agent execution finishes successfully.
+
+    Corresponds to on_terminate lifecycle hook.
+    Schema per DATA_MODEL.md lines 205-212.
+    """
+
+    # Event metadata
+    correlation_id: str
+    timestamp: str = Field(
+        default_factory=lambda: datetime.now(timezone.utc).isoformat().replace("+00:00", "Z")
+    )
+
+    # Agent identification
+    agent_name: str
+    run_id: str  # Context.task_id
+
+    # Execution metrics
+    duration_ms: float  # Execution time in milliseconds
+    artifacts_produced: list[str] = Field(default_factory=list)  # [artifact_id]
+
+    # Metrics and state
+    metrics: dict[str, Any] = Field(default_factory=dict)  # {"tokens_used": 1234, "cost": 0.05}
+    final_state: dict[str, Any] = Field(default_factory=dict)  # Context.state snapshot
+
+
+class AgentErrorEvent(BaseModel):
+    """Event emitted when agent execution fails.
+
+    Corresponds to on_error lifecycle hook.
+    Schema per DATA_MODEL.md lines 247-253.
+    """
+
+    # Event metadata
+    correlation_id: str
+    timestamp: str = Field(
+        default_factory=lambda: datetime.now(timezone.utc).isoformat().replace("+00:00", "Z")
+    )
+
+    # Agent identification
+    agent_name: str
+    run_id: str  # Context.task_id
+
+    # Error details
+    error_type: str  # Exception class name
+    error_message: str  # Exception message
+    traceback: str  # Full Python traceback
+    failed_at: str  # ISO timestamp of failure
+
+
+__all__ = [
+    "AgentActivatedEvent",
+    "AgentCompletedEvent",
+    "AgentErrorEvent",
+    "MessagePublishedEvent",
+    "StreamingOutputEvent",
+    "SubscriptionInfo",
+    "VisibilitySpec",
+]

flock/dashboard/launcher.py

@@ -0,0 +1,230 @@
+"""DashboardLauncher - manages npm lifecycle and browser launch for the dashboard.
+
+This module handles:
+- npm dependency installation (first run)
+- npm dev server (DASHBOARD_DEV=1) or production build
+- Automatic browser launch
+- Process cleanup on shutdown
+"""
+
+import os
+import subprocess
+import sys
+import time
+import webbrowser
+from pathlib import Path
+
+
+# Frontend directory location (adjacent to this dashboard package)
+FRONTEND_DIR = Path(__file__).parent.parent.parent.parent / "frontend"
+
+
+class DashboardLauncher:
+    """Manages dashboard frontend lifecycle.
+
+    Responsibilities:
+    - Ensure npm dependencies installed
+    - Start npm dev server (dev mode) or build for production
+    - Launch browser automatically
+    - Clean up npm processes on shutdown
+
+    Usage:
+        launcher = DashboardLauncher(port=8000)
+        launcher.start()  # Starts npm and opens browser
+        # ... orchestrator runs ...
+        launcher.stop()  # Cleanup
+
+    Or as context manager:
+        with DashboardLauncher(port=8000):
+            # orchestrator.serve() runs
+            pass  # Automatically cleaned up
+    """
+
+    def __init__(self, port: int = 8000, frontend_dir: Path | None = None):
+        """Initialize dashboard launcher.
+
+        Args:
+            port: HTTP port where dashboard will be served (default: 8000)
+            frontend_dir: Optional frontend directory path (defaults to FRONTEND_DIR)
+        """
+        self.port = port
+        self.frontend_dir = frontend_dir or FRONTEND_DIR
+        self.dev_mode = os.getenv("DASHBOARD_DEV", "0") == "1"
+        self._npm_process: subprocess.Popen | None = None
+
+    def _ensure_npm_dependencies(self) -> None:
+        """Ensure npm dependencies are installed.
+
+        Runs 'npm install'.
+        """
+
+        print(f"[Dashboard] Installing npm dependencies in {self.frontend_dir}...")
+        try:
+            subprocess.run(
+                [self._get_npm_command(), "install"],
+                cwd=self.frontend_dir,
+                check=True,
+                capture_output=True,
+                text=True,
+            )
+            print("[Dashboard] npm dependencies installed successfully")
+        except subprocess.CalledProcessError as e:
+            print(f"[Dashboard] Warning: npm install failed: {e.stderr}")
+            print("[Dashboard] Continuing anyway, dashboard may not work correctly")
+        except FileNotFoundError:
+            print("[Dashboard] Error: npm not found. Please install Node.js and npm.")
+            print("[Dashboard] Dashboard will not be available.")
+
+    def _get_npm_command(self) -> str:
+        """Get npm command (npm or npm.cmd on Windows)."""
+        return "npm.cmd" if sys.platform == "win32" else "npm"
+
+    def _start_npm_process(self) -> None:
+        """Start npm dev server or production build based on mode."""
+        if self.dev_mode:
+            self._start_dev_server()
+        else:
+            self._build_production()
+
+    def _start_dev_server(self) -> None:
+        """Start npm dev server for hot-reload development."""
+        print(f"[Dashboard] Starting dev server (DASHBOARD_DEV=1) on port {self.port}...")
+
+        try:
+            self._npm_process = subprocess.Popen(
+                [self._get_npm_command(), "run", "dev"],
+                cwd=self.frontend_dir,
+                stdout=subprocess.PIPE,
+                stderr=subprocess.PIPE,
+                text=True,
+            )
+            print(f"[Dashboard] Dev server started (PID: {self._npm_process.pid})")
+        except FileNotFoundError:
+            print("[Dashboard] Error: npm not found. Dev server not started.")
+
+    def _build_production(self) -> None:
+        """Build frontend for production (static files)."""
+        print("[Dashboard] Building frontend for production...")
+
+        try:
+            subprocess.run(
+                [self._get_npm_command(), "run", "build"],
+                cwd=self.frontend_dir,
+                check=True,
+                capture_output=True,
+                text=True,
+            )
+            print("[Dashboard] Production build completed")
+
+            # Copy build output from frontend/dist to src/flock/dashboard/static
+            self._copy_build_output()
+
+        except subprocess.CalledProcessError as e:
+            print(f"[Dashboard] Warning: Production build failed: {e.stderr}")
+            print("[Dashboard] Dashboard may not be available")
+        except FileNotFoundError:
+            print("[Dashboard] Error: npm not found. Build skipped.")
+
+    def _copy_build_output(self) -> None:
+        """Copy built frontend files from frontend/dist to dashboard/static."""
+        import shutil
+
+        source_dir = self.frontend_dir / "dist"
+        # Dashboard directory is src/flock/dashboard
+        target_dir = Path(__file__).parent / "static"
+
+        if not source_dir.exists():
+            print(f"[Dashboard] Warning: Build output not found at {source_dir}")
+            return
+
+        # Remove old static files if they exist
+        if target_dir.exists():
+            shutil.rmtree(target_dir)
+
+        # Copy dist to static
+        print(f"[Dashboard] Copying build output from {source_dir} to {target_dir}")
+        shutil.copytree(source_dir, target_dir)
+        print(f"[Dashboard] Static files ready at {target_dir}")
+
+    def _launch_browser(self) -> None:
+        """Launch browser to dashboard URL after brief delay.
+
+        Waits 2 seconds to allow server to start before opening browser.
+        Catches errors gracefully (e.g., headless environments).
+        """
+        # Wait for server to start
+        time.sleep(2)
+
+        dashboard_url = f"http://localhost:{self.port}"
+        print(f"[Dashboard] Opening browser to {dashboard_url}...")
+
+        try:
+            webbrowser.open(dashboard_url)
+            print("[Dashboard] Browser launched successfully")
+        except Exception as e:
+            print(f"[Dashboard] Could not launch browser: {e}")
+            print(f"[Dashboard] Please open {dashboard_url} manually")
+
+    def start(self) -> None:
+        """Start dashboard: install deps, start npm, launch browser.
+
+        This method:
+        1. Ensures npm dependencies are installed
+        2. Starts npm dev server (dev mode) or builds production
+        3. Launches browser to dashboard URL
+        """
+        print(f"[Dashboard] Starting dashboard on port {self.port}")
+        print(f"[Dashboard] Mode: {'DEVELOPMENT' if self.dev_mode else 'PRODUCTION'}")
+        print(f"[Dashboard] Frontend directory: {self.frontend_dir}")
+
+        # Step 1: Ensure dependencies installed
+        self._ensure_npm_dependencies()
+
+        # Step 2: Start npm process
+        self._start_npm_process()
+
+        # Step 3: Launch browser
+        self._launch_browser()
+
+    def stop(self) -> None:
+        """Stop dashboard and cleanup npm processes.
+
+        Attempts graceful termination, falls back to kill if needed.
+        """
+        if self._npm_process is None:
+            return
+
+        print("[Dashboard] Stopping npm process...")
+
+        try:
+            # Try graceful termination first
+            self._npm_process.terminate()
+
+            # Wait up to 5 seconds for process to exit
+            for _ in range(5):
+                if self._npm_process.poll() is not None:
+                    print("[Dashboard] npm process stopped gracefully")
+                    return
+                time.sleep(1)
+
+            # Force kill if still running
+            print("[Dashboard] npm process did not stop gracefully, forcing kill...")
+            self._npm_process.kill()
+            self._npm_process.wait(timeout=2)
+            print("[Dashboard] npm process killed")
+
+        except Exception as e:
+            print(f"[Dashboard] Error stopping npm process: {e}")
+
+        finally:
+            self._npm_process = None
+
+    def __enter__(self):
+        """Context manager entry: start dashboard."""
+        self.start()
+        return self
+
+    def __exit__(self, exc_type, exc_val, exc_tb):
+        """Context manager exit: stop dashboard."""
+        self.stop()
+        return False  # Don't suppress exceptions