flock-core 0.4.542__py3-none-any.whl → 0.5.0__py3-none-any.whl

flock/frontend/src/services/api.ts

@@ -0,0 +1,337 @@
+/**
+ * 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.
+ */
+
+import type { ArtifactSummary } from '../types/filters';
+
+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 ArtifactListItem {
+  id: string;
+  type: string;
+  payload: Record<string, any>;
+  produced_by: string;
+  created_at: string;
+  correlation_id: string | null;
+  partition_key: string | null;
+  tags: string[];
+  visibility: { kind: string; [key: string]: any };
+  visibility_kind?: string;
+  version?: number;
+  consumptions?: ArtifactConsumption[];
+  consumed_by?: string[];
+}
+
+export interface ArtifactConsumption {
+  artifact_id: string;
+  consumer: string;
+  run_id: string | null;
+  correlation_id: string | null;
+  consumed_at: string;
+}
+
+export interface ArtifactListResponse {
+  items: ArtifactListItem[];
+  pagination: {
+    limit: number;
+    offset: number;
+    total: number;
+  };
+}
+
+export interface ArtifactSummaryResponse {
+  summary: ArtifactSummary;
+}
+
+export interface ArtifactQueryOptions {
+  types?: string[];
+  producers?: string[];
+  correlationId?: string | null;
+  tags?: string[];
+  visibility?: string[];
+  from?: string;
+  to?: string;
+  limit?: number;
+  offset?: number;
+  embedMeta?: boolean;
+}
+
+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');
+  }
+}
+
+// UI Optimization Migration (Phase 4.1 - Spec 002): Removed fetchRegisteredAgents()
+// OLD Phase 1 function that transformed API agents to graph store format
+// Backend now provides agent data directly in GraphSnapshot
+
+/**
+ * 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');
+  }
+}
+
+const buildArtifactQuery = (options: ArtifactQueryOptions): string => {
+  const params = new URLSearchParams();
+
+  options.types?.forEach((value) => params.append('type', value));
+  options.producers?.forEach((value) => params.append('produced_by', value));
+  options.tags?.forEach((value) => params.append('tag', value));
+  options.visibility?.forEach((value) => params.append('visibility', value));
+
+  if (options.correlationId) {
+    params.append('correlation_id', options.correlationId);
+  }
+  if (options.from) {
+    params.append('from', options.from);
+  }
+  if (options.to) {
+    params.append('to', options.to);
+  }
+  if (typeof options.limit === 'number') {
+    params.append('limit', String(options.limit));
+  }
+  if (typeof options.offset === 'number') {
+    params.append('offset', String(options.offset));
+  }
+  if (options.embedMeta) {
+    params.append('embed_meta', 'true');
+  }
+
+  return params.toString();
+};
+
+export async function fetchArtifacts(options: ArtifactQueryOptions = {}): Promise<ArtifactListResponse> {
+  const query = buildArtifactQuery(options);
+
+  try {
+    const response = await fetch(`${BASE_URL}/v1/artifacts${query ? `?${query}` : ''}`, {
+      method: 'GET',
+      headers: {
+        'Content-Type': 'application/json',
+      },
+    });
+
+    if (!response.ok) {
+      const errorData = await response.json().catch(() => ({
+        error: 'Unknown error',
+        message: 'Failed to fetch artifacts',
+      }));
+      throw new ApiError(response.status, errorData);
+    }
+
+    const data: ArtifactListResponse = await response.json();
+    return data;
+  } catch (error) {
+    if (error instanceof ApiError) {
+      throw error;
+    }
+    throw new Error('Failed to connect to API server');
+  }
+}
+
+export async function fetchArtifactSummary(options: ArtifactQueryOptions = {}): Promise<ArtifactSummary> {
+  const query = buildArtifactQuery(options);
+
+  try {
+    const response = await fetch(`${BASE_URL}/v1/artifacts/summary${query ? `?${query}` : ''}`, {
+      method: 'GET',
+      headers: {
+        'Content-Type': 'application/json',
+      },
+    });
+
+    if (!response.ok) {
+      const errorData = await response.json().catch(() => ({
+        error: 'Unknown error',
+        message: 'Failed to fetch artifact summary',
+      }));
+      throw new ApiError(response.status, errorData);
+    }
+
+    const data: ArtifactSummaryResponse = await response.json();
+    return data.summary;
+  } catch (error) {
+    if (error instanceof ApiError) {
+      throw error;
+    }
+    throw new Error('Failed to connect to API server');
+  }
+}

flock/frontend/src/services/graphService.test.ts

@@ -0,0 +1,330 @@
+import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
+import { fetchGraphSnapshot, mergeNodePositions, overlayWebSocketState } from './graphService';
+import { GraphRequest, GraphSnapshot } from '../types/graph';
+import { Node } from '@xyflow/react';
+
+/**
+ * Graph Service Tests - UI Optimization Migration (Spec 002)
+ *
+ * Tests the NEW graph service layer that replaces client-side graph construction
+ * with backend snapshot consumption.
+ *
+ * SPECIFICATION: docs/internal/ui-optimization/03-migration-implementation-guide.md
+ * FOCUS: Backend integration, position merging, WebSocket state overlay, error handling
+ */
+
+describe('graphService', () => {
+  beforeEach(() => {
+    vi.clearAllMocks();
+  });
+
+  afterEach(() => {
+    vi.restoreAllMocks();
+  });
+
+  describe('fetchGraphSnapshot', () => {
+    it('should fetch agent view graph from backend with correct request format', async () => {
+      const mockSnapshot: GraphSnapshot = {
+        nodes: [
+          { id: 'agent1', type: 'agent', data: { name: 'agent1' }, position: { x: 0, y: 0 }, hidden: false },
+        ],
+        edges: [
+          { id: 'edge1', source: 'agent1', target: 'agent2', type: 'message_flow', hidden: false, data: {} },
+        ],
+        statistics: null,
+        viewMode: 'agent',
+        filters: {
+          correlation_id: null,
+          time_range: { preset: 'last10min' },
+          artifactTypes: [],
+          producers: [],
+          tags: [],
+          visibility: [],
+        },
+        generatedAt: '2025-10-11T00:00:00Z',
+        totalArtifacts: 1,
+        truncated: false,
+      };
+
+      globalThis.fetch = vi.fn().mockResolvedValue({
+        ok: true,
+        json: async () => mockSnapshot,
+      }) as any;
+
+      const request: GraphRequest = {
+        viewMode: 'agent',
+        filters: {
+          correlation_id: null,
+          time_range: { preset: 'last10min' },
+          artifactTypes: ['Pizza'],
+          producers: ['pizza_master'],
+          tags: [],
+          visibility: [],
+        },
+        options: { include_statistics: true },
+      };
+
+      const result = await fetchGraphSnapshot(request);
+
+      expect(globalThis.fetch).toHaveBeenCalledWith('/api/dashboard/graph', {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify(request),
+      });
+
+      expect(result).toEqual(mockSnapshot);
+      expect(result.nodes).toHaveLength(1);
+      expect(result.edges).toHaveLength(1);
+    });
+
+    it('should throw error when API call fails', async () => {
+      globalThis.fetch = vi.fn().mockResolvedValue({
+        ok: false,
+        statusText: 'Internal Server Error',
+      });
+
+      const request: GraphRequest = {
+        viewMode: 'agent',
+        filters: {
+          correlation_id: null,
+          time_range: { preset: 'last10min' },
+          artifactTypes: [],
+          producers: [],
+          tags: [],
+          visibility: [],
+        },
+      };
+
+      await expect(fetchGraphSnapshot(request)).rejects.toThrow('Graph API error: Internal Server Error');
+    });
+
+    it('should handle network errors gracefully', async () => {
+      globalThis.fetch = vi.fn().mockRejectedValue(new Error('Network error'));
+
+      const request: GraphRequest = {
+        viewMode: 'blackboard',
+        filters: {
+          correlation_id: null,
+          time_range: { preset: 'last5min' },
+          artifactTypes: [],
+          producers: [],
+          tags: [],
+          visibility: [],
+        },
+      };
+
+      await expect(fetchGraphSnapshot(request)).rejects.toThrow('Network error');
+    });
+  });
+
+  describe('mergeNodePositions - Priority Logic', () => {
+    it('should prioritize saved positions over all others', () => {
+      const backendNodes = [
+        { id: 'agent1', type: 'agent' as const, data: { name: 'agent1' }, position: { x: 100, y: 100 }, hidden: false },
+      ];
+
+      const savedPositions = new Map([['agent1', { x: 500, y: 500 }]]);
+
+      const currentNodes: Node[] = [
+        { id: 'agent1', type: 'agent', data: { name: 'agent1' }, position: { x: 300, y: 300 } },
+      ];
+
+      const result = mergeNodePositions(backendNodes, savedPositions, currentNodes);
+
+      // Saved position (500, 500) wins
+      expect(result[0]?.position).toEqual({ x: 500, y: 500 });
+    });
+
+    it('should prioritize current positions when no saved position exists', () => {
+      const backendNodes = [
+        { id: 'agent1', type: 'agent' as const, data: { name: 'agent1' }, position: { x: 100, y: 100 }, hidden: false },
+      ];
+
+      const savedPositions = new Map(); // No saved position
+
+      const currentNodes: Node[] = [
+        { id: 'agent1', type: 'agent', data: { name: 'agent1' }, position: { x: 300, y: 300 } },
+      ];
+
+      const result = mergeNodePositions(backendNodes, savedPositions, currentNodes);
+
+      // Current position (300, 300) wins
+      expect(result[0]!.position).toEqual({ x: 300, y: 300 });
+    });
+
+    it('should use backend position when saved and current are unavailable', () => {
+      const backendNodes = [
+        { id: 'agent1', type: 'agent' as const, data: { name: 'agent1' }, position: { x: 100, y: 100 }, hidden: false },
+      ];
+
+      const savedPositions = new Map(); // No saved position
+      const currentNodes: Node[] = []; // No current position
+
+      const result = mergeNodePositions(backendNodes, savedPositions, currentNodes);
+
+      // Backend position (100, 100) wins
+      expect(result[0]!.position).toEqual({ x: 100, y: 100 });
+    });
+
+    it('should generate random position when backend has zero coordinates', () => {
+      const backendNodes = [
+        { id: 'agent1', type: 'agent' as const, data: { name: 'agent1' }, position: { x: 0, y: 0 }, hidden: false },
+      ];
+
+      const savedPositions = new Map(); // No saved position
+      const currentNodes: Node[] = []; // No current position
+
+      const result = mergeNodePositions(backendNodes, savedPositions, currentNodes);
+
+      // Random position should be generated (not 0, 0)
+      expect(result[0]!.position.x).toBeGreaterThan(0);
+      expect(result[0]!.position.y).toBeGreaterThan(0);
+      // Random position range: x in [400, 600], y in [300, 500]
+      expect(result[0]!.position.x).toBeGreaterThanOrEqual(400);
+      expect(result[0]!.position.x).toBeLessThanOrEqual(600);
+      expect(result[0]!.position.y).toBeGreaterThanOrEqual(300);
+      expect(result[0]!.position.y).toBeLessThanOrEqual(500);
+    });
+
+    it('should handle multiple nodes with mixed position sources', () => {
+      const backendNodes = [
+        { id: 'agent1', type: 'agent' as const, data: { name: 'agent1' }, position: { x: 100, y: 100 }, hidden: false },
+        { id: 'agent2', type: 'agent' as const, data: { name: 'agent2' }, position: { x: 200, y: 200 }, hidden: false },
+        { id: 'agent3', type: 'agent' as const, data: { name: 'agent3' }, position: { x: 0, y: 0 }, hidden: false },
+      ];
+
+      const savedPositions = new Map([['agent1', { x: 500, y: 500 }]]); // Only agent1
+
+      const currentNodes: Node[] = [
+        { id: 'agent2', type: 'agent', data: { name: 'agent2' }, position: { x: 300, y: 300 } },
+      ];
+
+      const result = mergeNodePositions(backendNodes, savedPositions, currentNodes);
+
+      // agent1: saved position wins
+      expect(result[0]!.position).toEqual({ x: 500, y: 500 });
+      // agent2: current position wins
+      expect(result[1]!.position).toEqual({ x: 300, y: 300 });
+      // agent3: random position (backend is 0,0)
+      expect(result[2]!.position.x).toBeGreaterThan(0);
+      expect(result[2]!.position.y).toBeGreaterThan(0);
+    });
+  });
+
+  describe('overlayWebSocketState', () => {
+    it('should overlay agent status from WebSocket state', () => {
+      const nodes: Node[] = [
+        {
+          id: 'agent1',
+          type: 'agent',
+          data: { name: 'agent1', status: 'idle' },
+          position: { x: 100, y: 100 },
+        },
+      ];
+
+      const agentStatus = new Map([['agent1', 'running']]);
+      const streamingTokens = new Map<string, string[]>();
+
+      const result = overlayWebSocketState(nodes, agentStatus, streamingTokens);
+
+      expect(result[0]!.data.status).toBe('running');
+    });
+
+    it('should overlay streaming tokens from WebSocket state', () => {
+      const nodes: Node[] = [
+        {
+          id: 'agent1',
+          type: 'agent',
+          data: { name: 'agent1', status: 'idle' },
+          position: { x: 100, y: 100 },
+        },
+      ];
+
+      const agentStatus = new Map<string, string>();
+      const streamingTokens = new Map([['agent1', ['token1', 'token2', 'token3']]]);
+
+      const result = overlayWebSocketState(nodes, agentStatus, streamingTokens);
+
+      expect(result[0]!.data.streamingTokens).toEqual(['token1', 'token2', 'token3']);
+    });
+
+    it('should use backend status when WebSocket state is unavailable', () => {
+      const nodes: Node[] = [
+        {
+          id: 'agent1',
+          type: 'agent',
+          data: { name: 'agent1', status: 'idle' },
+          position: { x: 100, y: 100 },
+        },
+      ];
+
+      const agentStatus = new Map<string, string>(); // Empty
+      const streamingTokens = new Map<string, string[]>(); // Empty
+
+      const result = overlayWebSocketState(nodes, agentStatus, streamingTokens);
+
+      // Backend status is preserved
+      expect(result[0]!.data.status).toBe('idle');
+      // Empty array for tokens
+      expect(result[0]!.data.streamingTokens).toEqual([]);
+    });
+
+    it('should not modify non-agent nodes', () => {
+      const nodes: Node[] = [
+        {
+          id: 'message1',
+          type: 'message',
+          data: { type: 'Pizza', payload: {} },
+          position: { x: 100, y: 100 },
+        },
+      ];
+
+      const agentStatus = new Map([['message1', 'running']]);
+      const streamingTokens = new Map([['message1', ['token1']]]);
+
+      const result = overlayWebSocketState(nodes, agentStatus, streamingTokens);
+
+      // Message node should not be modified
+      expect(result[0]!.data).toEqual({ type: 'Pizza', payload: {} });
+      expect(result[0]!.data.status).toBeUndefined();
+      expect(result[0]!.data.streamingTokens).toBeUndefined();
+    });
+
+    it('should handle multiple agent nodes with mixed WebSocket state', () => {
+      const nodes: Node[] = [
+        {
+          id: 'agent1',
+          type: 'agent',
+          data: { name: 'agent1', status: 'idle' },
+          position: { x: 100, y: 100 },
+        },
+        {
+          id: 'agent2',
+          type: 'agent',
+          data: { name: 'agent2', status: 'idle' },
+          position: { x: 200, y: 200 },
+        },
+        {
+          id: 'message1',
+          type: 'message',
+          data: { type: 'Pizza' },
+          position: { x: 300, y: 300 },
+        },
+      ];
+
+      const agentStatus = new Map([['agent1', 'running']]); // Only agent1
+      const streamingTokens = new Map([['agent2', ['token1', 'token2']]]); // Only agent2
+
+      const result = overlayWebSocketState(nodes, agentStatus, streamingTokens);
+
+      // agent1: status updated, no tokens
+      expect(result[0]!.data.status).toBe('running');
+      expect(result[0]!.data.streamingTokens).toEqual([]);
+      // agent2: status from backend, tokens updated
+      expect(result[1]!.data.status).toBe('idle');
+      expect(result[1]!.data.streamingTokens).toEqual(['token1', 'token2']);
+      // message1: unchanged
+      expect(result[2]!.data).toEqual({ type: 'Pizza' });
+    });
+  });
+});