flock-core 0.5.0b28__py3-none-any.whl → 0.5.0b51__py3-none-any.whl

flock/frontend/src/hooks/useModules.ts

@@ -0,0 +1,139 @@
+/**
+ * useModules Hook - Module Lifecycle Management
+ *
+ * Provides ModuleContext to modules and manages lifecycle hooks.
+ * Aggregates data from multiple stores into a unified context.
+ * Calls module onMount/onUnmount lifecycle hooks when instances change.
+ *
+ * SPECIFICATION: docs/specs/003-real-time-dashboard/FRONTEND_ARCHITECTURE.md Section 7.4
+ * - Build ModuleContext from store data (agents, messages, events, filters)
+ * - Call module onMount lifecycle hooks when instances added
+ * - Call module onUnmount lifecycle hooks when instances removed
+ * - Provide publish and invoke actions in context
+ */
+
+import { useEffect, useMemo, useRef } from 'react';
+import { useModuleStore } from '../store/moduleStore';
+import { useGraphStore } from '../store/graphStore';
+import { useFilterStore } from '../store/filterStore';
+import { moduleRegistry, type ModuleContext } from '../components/modules/ModuleRegistry';
+
+/**
+ * Custom hook for module lifecycle management
+ *
+ * Features:
+ * - Builds ModuleContext from graphStore, filterStore
+ * - Tracks module instances and calls lifecycle hooks
+ * - Calls onMount when new instances are added
+ * - Calls onUnmount when instances are removed
+ * - Provides publish/invoke actions (placeholder for now)
+ *
+ * @returns {Object} Hook return value
+ * @returns {ModuleContext} context - The module context object
+ */
+export function useModules() {
+  // Subscribe to store state
+  const instances = useModuleStore((state) => state.instances);
+  const agents = useGraphStore((state) => state.agents);
+  const messages = useGraphStore((state) => state.messages);
+  const events = useGraphStore((state) => state.events);
+  const correlationId = useFilterStore((state) => state.correlationId);
+  const timeRange = useFilterStore((state) => state.timeRange);
+
+  // Track previous instances to detect changes
+  const prevInstancesRef = useRef<Map<string, any>>(new Map());
+
+  // Build ModuleContext
+  const context: ModuleContext = useMemo(
+    () => ({
+      agents,
+      messages,
+      events,
+      filters: {
+        correlationId,
+        timeRange,
+      },
+      publish: (artifact: any) => {
+        // Placeholder: In production, this would dispatch to WebSocket
+        console.log('[Module Context] Publish artifact:', artifact);
+      },
+      invoke: (agentName: string, inputs: any[]) => {
+        // Placeholder: In production, this would dispatch to WebSocket
+        console.log('[Module Context] Invoke agent:', agentName, 'with inputs:', inputs);
+      },
+    }),
+    [agents, messages, events, correlationId, timeRange]
+  );
+
+  /**
+   * Lifecycle effect: Call onMount/onUnmount hooks when instances change
+   */
+  useEffect(() => {
+    const currentInstances = instances;
+    const prevInstances = prevInstancesRef.current;
+
+    // Detect added instances (in current but not in previous)
+    const addedInstances = new Map<string, any>();
+    currentInstances.forEach((instance, id) => {
+      if (!prevInstances.has(id)) {
+        addedInstances.set(id, instance);
+      }
+    });
+
+    // Detect removed instances (in previous but not in current)
+    const removedInstances = new Map<string, any>();
+    prevInstances.forEach((instance, id) => {
+      if (!currentInstances.has(id)) {
+        removedInstances.set(id, instance);
+      }
+    });
+
+    // Call onMount for added instances
+    addedInstances.forEach((instance) => {
+      const module = moduleRegistry.get(instance.type);
+      if (module?.onMount) {
+        console.log(`[useModules] Calling onMount for module: ${module.name} (${instance.id})`);
+        try {
+          module.onMount(context);
+        } catch (error) {
+          console.error(`[useModules] Error in onMount for module ${module.name}:`, error);
+        }
+      }
+    });
+
+    // Call onUnmount for removed instances
+    removedInstances.forEach((instance) => {
+      const module = moduleRegistry.get(instance.type);
+      if (module?.onUnmount) {
+        console.log(`[useModules] Calling onUnmount for module: ${module.name} (${instance.id})`);
+        try {
+          module.onUnmount();
+        } catch (error) {
+          console.error(`[useModules] Error in onUnmount for module ${module.name}:`, error);
+        }
+      }
+    });
+
+    // Update previous instances ref for next comparison
+    prevInstancesRef.current = new Map(currentInstances);
+
+    // Cleanup: Call onUnmount for all instances when hook unmounts
+    return () => {
+      currentInstances.forEach((instance) => {
+        const module = moduleRegistry.get(instance.type);
+        if (module?.onUnmount) {
+          console.log(`[useModules] Cleanup: Calling onUnmount for module: ${module.name} (${instance.id})`);
+          try {
+            module.onUnmount();
+          } catch (error) {
+            console.error(`[useModules] Error in cleanup onUnmount for module ${module.name}:`, error);
+          }
+        }
+      });
+    };
+  }, [instances, context]);
+
+  return {
+    context,
+  };
+}

flock/frontend/src/hooks/usePersistence.ts

@@ -0,0 +1,139 @@
+/**
+ * usePersistence Hook - Node Position Persistence
+ *
+ * Provides position persistence for graph nodes using IndexedDB.
+ * Manages loading and saving of node positions with debouncing.
+ * Handles separate layouts for Agent View and Blackboard View.
+ *
+ * SPECIFICATION: docs/specs/003-real-time-dashboard/FRONTEND_ARCHITECTURE.md
+ * - Debounce: 300ms delay on drag stop
+ * - Performance: Position save <50ms (after debounce)
+ * - Separate layouts for Agent View vs Blackboard View
+ */
+
+import { useEffect, useCallback, useRef } from 'react';
+import { useGraphStore } from '../store/graphStore';
+import { useUIStore, VisualizationMode } from '../store/uiStore';
+import { indexedDBService } from '../services/indexeddb';
+
+interface Position {
+  x: number;
+  y: number;
+}
+
+/**
+ * Custom debounce implementation
+ * Creates a debounced function that delays invoking func until after delay milliseconds
+ */
+function debounce<T extends (...args: any[]) => void>(
+  func: T,
+  delay: number
+): (...args: Parameters<T>) => void {
+  let timeoutId: ReturnType<typeof setTimeout> | null = null;
+
+  return (...args: Parameters<T>) => {
+    if (timeoutId) {
+      clearTimeout(timeoutId);
+    }
+
+    timeoutId = setTimeout(() => {
+      func(...args);
+      timeoutId = null;
+    }, delay);
+  };
+}
+
+/**
+ * React hook for node position persistence
+ *
+ * Features:
+ * - Loads node positions from IndexedDB on mount
+ * - Applies loaded positions to graphStore
+ * - Returns debounced saveNodePosition function (300ms delay)
+ * - Handles mode switching (reloads positions for new mode)
+ *
+ * @returns {Object} Hook return value
+ * @returns {Function} saveNodePosition - Debounced function to save node position
+ */
+export function usePersistence() {
+  const mode = useUIStore((state) => state.mode);
+  const updateNodePosition = useGraphStore((state) => state.updateNodePosition);
+
+  // Use ref to maintain debounced function identity across renders
+  const debouncedSaveRef = useRef<((nodeId: string, mode: VisualizationMode, position: Position) => void) | null>(null);
+
+  // Initialize debounced save function once
+  if (!debouncedSaveRef.current) {
+    debouncedSaveRef.current = debounce(
+      async (nodeId: string, mode: VisualizationMode, position: Position) => {
+        try {
+          console.log(`[usePersistence] Saving position for ${nodeId} in ${mode} view:`, position);
+          const layoutRecord = {
+            node_id: nodeId,
+            x: position.x,
+            y: position.y,
+            last_updated: new Date().toISOString(),
+          };
+
+          if (mode === 'agent') {
+            await indexedDBService.saveAgentViewLayout(layoutRecord);
+            console.log(`[usePersistence] ✓ Saved to agent view layout`);
+          } else {
+            await indexedDBService.saveBlackboardViewLayout(layoutRecord);
+            console.log(`[usePersistence] ✓ Saved to blackboard view layout`);
+          }
+        } catch (error) {
+          console.error(`[usePersistence] Failed to save node position for ${nodeId}:`, error);
+        }
+      },
+      300 // 300ms debounce delay as per specification
+    );
+  }
+
+  /**
+   * Load node positions from IndexedDB for current mode
+   */
+  const loadNodePositions = useCallback(async (currentMode: VisualizationMode) => {
+    try {
+      let layouts: Array<{ node_id: string; x: number; y: number; last_updated: string }> = [];
+
+      if (currentMode === 'agent') {
+        layouts = await indexedDBService.getAllAgentViewLayouts();
+      } else {
+        layouts = await indexedDBService.getAllBlackboardViewLayouts();
+      }
+
+      // Apply loaded positions to graph store
+      layouts.forEach((layout) => {
+        updateNodePosition(layout.node_id, { x: layout.x, y: layout.y });
+      });
+
+      console.log(`[usePersistence] Loaded ${layouts.length} node positions for ${currentMode} view`);
+    } catch (error) {
+      console.error(`[usePersistence] Failed to load node positions for ${currentMode} view:`, error);
+    }
+  }, [updateNodePosition]);
+
+  /**
+   * Load positions on mount and when mode changes
+   */
+  useEffect(() => {
+    loadNodePositions(mode);
+  }, [mode, loadNodePositions]);
+
+  /**
+   * Public API: Save node position with debouncing
+   */
+  const saveNodePosition = useCallback(
+    (nodeId: string, position: Position) => {
+      if (debouncedSaveRef.current) {
+        debouncedSaveRef.current(nodeId, mode, position);
+      }
+    },
+    [mode]
+  );
+
+  return {
+    saveNodePosition,
+  };
+}

flock/frontend/src/main.tsx

@@ -0,0 +1,13 @@
+import ReactDOM from 'react-dom/client';
+import App from './App';
+import './styles/index.css';
+
+// Mock data removed - dashboard now starts empty and shows only real WebSocket data
+
+const rootElement = document.getElementById('root');
+
+if (!rootElement) {
+  throw new Error('Root element not found');
+}
+
+ReactDOM.createRoot(rootElement).render(<App />);

flock/frontend/src/services/api.ts

@@ -0,0 +1,213 @@
+/**
+ * REST API client for orchestrator control operations.
+ *
+ * Provides methods to publish artifacts and invoke agents via HTTP endpoints.
+ * Handles error responses and provides typed return values.
+ *
+ * Base URL defaults to /api for same-origin requests.
+ */
+
+const BASE_URL = import.meta.env.VITE_API_BASE_URL || '/api';
+
+export interface ArtifactType {
+  name: string;
+  schema: {
+    type: string;
+    properties: Record<string, any>;
+  };
+}
+
+export interface Agent {
+  name: string;
+  description: string;
+  status: string;
+  subscriptions: string[];
+  output_types: string[];
+}
+
+export interface PublishResponse {
+  status: string;
+  correlation_id: string;
+  message: string;
+}
+
+export interface InvokeResponse {
+  status: string;
+  invocation_id: string;
+  correlation_id?: string | null;
+  agent: string;
+  message: string;
+}
+
+export interface ArtifactTypesResponse {
+  artifact_types: ArtifactType[];
+}
+
+export interface AgentsResponse {
+  agents: Agent[];
+}
+
+export interface ErrorResponse {
+  error: string;
+  message: string;
+}
+
+class ApiError extends Error {
+  constructor(public status: number, public errorResponse: ErrorResponse) {
+    super(errorResponse.message || errorResponse.error);
+    this.name = 'ApiError';
+  }
+}
+
+/**
+ * Fetch artifact types from orchestrator
+ */
+export async function fetchArtifactTypes(): Promise<ArtifactType[]> {
+  try {
+    const response = await fetch(`${BASE_URL}/artifact-types`, {
+      method: 'GET',
+      headers: {
+        'Content-Type': 'application/json',
+      },
+    });
+
+    if (!response.ok) {
+      const errorData = await response.json().catch(() => ({
+        error: 'Unknown error',
+        message: 'Failed to fetch artifact types',
+      }));
+      throw new ApiError(response.status, errorData);
+    }
+
+    const data: ArtifactTypesResponse = await response.json();
+    return data.artifact_types;
+  } catch (error) {
+    if (error instanceof ApiError) {
+      throw error;
+    }
+    throw new Error('Failed to connect to API server');
+  }
+}
+
+/**
+ * Fetch available agents from orchestrator
+ */
+export async function fetchAgents(): Promise<Agent[]> {
+  try {
+    const response = await fetch(`${BASE_URL}/agents`, {
+      method: 'GET',
+      headers: {
+        'Content-Type': 'application/json',
+      },
+    });
+
+    if (!response.ok) {
+      const errorData = await response.json().catch(() => ({
+        error: 'Unknown error',
+        message: 'Failed to fetch agents',
+      }));
+      throw new ApiError(response.status, errorData);
+    }
+
+    const data: AgentsResponse = await response.json();
+    return data.agents;
+  } catch (error) {
+    if (error instanceof ApiError) {
+      throw error;
+    }
+    throw new Error('Failed to connect to API server');
+  }
+}
+
+/**
+ * Fetch registered agents and transform to graph store format
+ * Returns agents with 'idle' status ready for initial display
+ */
+export async function fetchRegisteredAgents(): Promise<import('../types/graph').Agent[]> {
+  const agents = await fetchAgents();
+  return agents.map(agent => ({
+    id: agent.name,
+    name: agent.name,
+    status: 'idle' as const,
+    subscriptions: agent.subscriptions || [],
+    outputTypes: agent.output_types || [],
+    lastActive: Date.now(),
+    sentCount: 0,
+    recvCount: 0,
+    receivedByType: {},
+    sentByType: {},
+  }));
+}
+
+/**
+ * Publish an artifact to the orchestrator
+ * @param artifactType - The type of artifact to publish
+ * @param content - The artifact content as a parsed JSON object
+ * @returns Response with correlation ID
+ */
+export async function publishArtifact(
+  artifactType: string,
+  content: any
+): Promise<PublishResponse> {
+  try {
+    const response = await fetch(`${BASE_URL}/control/publish`, {
+      method: 'POST',
+      headers: {
+        'Content-Type': 'application/json',
+      },
+      body: JSON.stringify({
+        artifact_type: artifactType,
+        content: content,
+      }),
+    });
+
+    if (!response.ok) {
+      const errorData = await response.json().catch(() => ({
+        error: 'Unknown error',
+        message: 'Failed to publish artifact',
+      }));
+      throw new ApiError(response.status, errorData);
+    }
+
+    return await response.json();
+  } catch (error) {
+    if (error instanceof ApiError) {
+      throw error;
+    }
+    throw new Error('Failed to connect to API server');
+  }
+}
+
+/**
+ * Invoke an agent via the orchestrator
+ * @param agentName - The name of the agent to invoke
+ * @returns Response with invocation ID
+ */
+export async function invokeAgent(agentName: string): Promise<InvokeResponse> {
+  try {
+    const response = await fetch(`${BASE_URL}/control/invoke`, {
+      method: 'POST',
+      headers: {
+        'Content-Type': 'application/json',
+      },
+      body: JSON.stringify({
+        agent: agentName,
+      }),
+    });
+
+    if (!response.ok) {
+      const errorData = await response.json().catch(() => ({
+        error: 'Unknown error',
+        message: 'Failed to invoke agent',
+      }));
+      throw new ApiError(response.status, errorData);
+    }
+
+    return await response.json();
+  } catch (error) {
+    if (error instanceof ApiError) {
+      throw error;
+    }
+    throw new Error('Failed to connect to API server');
+  }
+}