flock-core 0.5.9__py3-none-any.whl → 0.5.11__py3-none-any.whl

flock/dashboard/service.py

@@ -19,6 +19,7 @@ from fastapi.middleware.cors import CORSMiddleware
 from fastapi.staticfiles import StaticFiles
 from pydantic import ValidationError
 
+from flock.api_models import ArtifactTypeSchema, ArtifactTypesResponse
 from flock.dashboard.collector import DashboardEventCollector
 from flock.dashboard.events import MessagePublishedEvent, VisibilitySpec
 from flock.dashboard.graph_builder import GraphAssembler
@@ -61,6 +62,18 @@ class DashboardHTTPService(BlackboardHTTPService):
         # Initialize base service
         super().__init__(orchestrator)
 
+        # Add dashboard-specific tags to OpenAPI
+        self.app.openapi_tags.extend([
+            {
+                "name": "Dashboard UI",
+                "description": "**Internal endpoints** used by the Flock dashboard UI. Not intended for direct use.",
+            },
+            {
+                "name": "Schema Discovery",
+                "description": "Endpoints for discovering available artifact types and their schemas.",
+            },
+        ])
+
         # Initialize WebSocket manager and event collector
         self.websocket_manager = websocket_manager or WebSocketManager()
         self.event_collector = event_collector or DashboardEventCollector(
@@ -137,13 +150,19 @@ class DashboardHTTPService(BlackboardHTTPService):
 
         if self.graph_assembler is not None:
 
-            @app.post("/api/dashboard/graph", response_model=GraphSnapshot)
+            @app.post(
+                "/api/dashboard/graph",
+                response_model=GraphSnapshot,
+                tags=["Dashboard UI"],
+            )
             async def get_dashboard_graph(request: GraphRequest) -> GraphSnapshot:
                 """Return server-side assembled dashboard graph snapshot."""
                 return await self.graph_assembler.build_snapshot(request)
 
         dashboard_dir = Path(__file__).parent
-        frontend_root = dashboard_dir.parent / ("frontend_v2" if self.use_v2 else "frontend")
+        frontend_root = dashboard_dir.parent / (
+            "frontend_v2" if self.use_v2 else "frontend"
+        )
         static_dir = dashboard_dir / ("static_v2" if self.use_v2 else "static")
 
         possible_dirs = [
@@ -172,8 +191,12 @@ class DashboardHTTPService(BlackboardHTTPService):
         app = self.app
         orchestrator = self.orchestrator
 
-        @app.get("/api/artifact-types")
-        async def get_artifact_types() -> dict[str, Any]:
+        @app.get(
+            "/api/artifact-types",
+            response_model=ArtifactTypesResponse,
+            tags=["Schema Discovery"],
+        )
+        async def get_artifact_types() -> ArtifactTypesResponse:
             """Get all registered artifact types with their schemas.
 
             Returns:
@@ -194,13 +217,15 @@ class DashboardHTTPService(BlackboardHTTPService):
                     model_class = type_registry.resolve(type_name)
                     # Get Pydantic schema
                     schema = model_class.model_json_schema()
-                    artifact_types.append({"name": type_name, "schema": schema})
+                    artifact_types.append(
+                        ArtifactTypeSchema(name=type_name, schema=schema)
+                    )
                 except Exception as e:
                     logger.warning(f"Could not get schema for {type_name}: {e}")
 
-            return {"artifact_types": artifact_types}
+            return ArtifactTypesResponse(artifact_types=artifact_types)
 
-        @app.get("/api/agents")
+        @app.get("/api/agents", tags=["Dashboard UI"])
         async def get_agents() -> dict[str, Any]:
             """Get all registered agents with logic operations state.
 
@@ -244,14 +269,18 @@ class DashboardHTTPService(BlackboardHTTPService):
                 # NEW Phase 1.2: Logic operations configuration
                 logic_operations = []
                 for idx, subscription in enumerate(agent.subscriptions):
-                    logic_config = _build_logic_config(agent, subscription, idx, orchestrator)
+                    logic_config = _build_logic_config(
+                        agent, subscription, idx, orchestrator
+                    )
                     if logic_config:  # Only include if has join/batch
                         logic_operations.append(logic_config)
 
                 agent_data = {
                     "name": agent.name,
                     "description": agent.description or "",
-                    "status": _compute_agent_status(agent, orchestrator),  # NEW: Dynamic status
+                    "status": _compute_agent_status(
+                        agent, orchestrator
+                    ),  # NEW: Dynamic status
                     "subscriptions": consumed_types,
                     "output_types": produced_types,
                 }
@@ -263,7 +292,7 @@ class DashboardHTTPService(BlackboardHTTPService):
 
             return {"agents": agents}
 
-        @app.get("/api/version")
+        @app.get("/api/version", tags=["Dashboard UI"])
         async def get_version() -> dict[str, str]:
             """Get version information for the backend and dashboard.
 
@@ -281,7 +310,7 @@ class DashboardHTTPService(BlackboardHTTPService):
 
             return {"backend_version": backend_version, "package_name": "flock-flow"}
 
-        @app.post("/api/control/publish")
+        @app.post("/api/control/publish", tags=["Dashboard UI"])
         async def publish_artifact(body: dict[str, Any]) -> dict[str, str]:
             """Publish artifact with correlation tracking.
 
@@ -314,7 +343,9 @@ class DashboardHTTPService(BlackboardHTTPService):
                 try:
                     instance = model_class(**content)
                 except ValidationError as e:
-                    raise HTTPException(status_code=422, detail=f"Validation error: {e!s}")
+                    raise HTTPException(
+                        status_code=422, detail=f"Validation error: {e!s}"
+                    )
 
                 # Generate correlation ID
                 correlation_id = str(uuid4())
@@ -355,7 +386,7 @@ class DashboardHTTPService(BlackboardHTTPService):
                 logger.exception(f"Error publishing artifact: {e}")
                 raise HTTPException(status_code=500, detail=str(e))
 
-        @app.post("/api/control/invoke")
+        @app.post("/api/control/invoke", tags=["Dashboard UI"])
         async def invoke_agent(body: dict[str, Any]) -> dict[str, Any]:
             """Directly invoke a specific agent.
 
@@ -384,13 +415,17 @@ class DashboardHTTPService(BlackboardHTTPService):
                 # Get agent from orchestrator
                 agent = orchestrator.get_agent(agent_name)
             except KeyError:
-                raise HTTPException(status_code=404, detail=f"Agent not found: {agent_name}")
+                raise HTTPException(
+                    status_code=404, detail=f"Agent not found: {agent_name}"
+                )
 
             try:
                 # Parse input type and create instance
                 input_type = input_data.get("type")
                 if not input_type:
-                    raise HTTPException(status_code=400, detail="input.type is required")
+                    raise HTTPException(
+                        status_code=400, detail="input.type is required"
+                    )
 
                 # Resolve type from registry
                 model_class = type_registry.resolve(input_type)
@@ -402,7 +437,9 @@ class DashboardHTTPService(BlackboardHTTPService):
                 try:
                     instance = model_class(**payload)
                 except ValidationError as e:
-                    raise HTTPException(status_code=422, detail=f"Validation error: {e!s}")
+                    raise HTTPException(
+                        status_code=422, detail=f"Validation error: {e!s}"
+                    )
 
                 # Invoke agent
                 outputs = await orchestrator.invoke(agent, instance)
@@ -426,30 +463,36 @@ class DashboardHTTPService(BlackboardHTTPService):
             except HTTPException:
                 raise
             except KeyError:
-                raise HTTPException(status_code=422, detail=f"Unknown type: {input_type}")
+                raise HTTPException(
+                    status_code=422, detail=f"Unknown type: {input_type}"
+                )
             except Exception as e:
                 logger.exception(f"Error invoking agent: {e}")
                 raise HTTPException(status_code=500, detail=str(e))
 
-        @app.post("/api/control/pause")
+        @app.post("/api/control/pause", tags=["Dashboard UI"])
         async def pause_orchestrator() -> dict[str, Any]:
             """Pause orchestrator (placeholder).
 
             Returns:
                 501 Not Implemented
             """
-            raise HTTPException(status_code=501, detail="Pause functionality coming in Phase 12")
+            raise HTTPException(
+                status_code=501, detail="Pause functionality coming in Phase 12"
+            )
 
-        @app.post("/api/control/resume")
+        @app.post("/api/control/resume", tags=["Dashboard UI"])
         async def resume_orchestrator() -> dict[str, Any]:
             """Resume orchestrator (placeholder).
 
             Returns:
                 501 Not Implemented
             """
-            raise HTTPException(status_code=501, detail="Resume functionality coming in Phase 12")
+            raise HTTPException(
+                status_code=501, detail="Resume functionality coming in Phase 12"
+            )
 
-        @app.get("/api/traces")
+        @app.get("/api/traces", tags=["Dashboard UI"])
         async def get_traces() -> list[dict[str, Any]]:
             """Get OpenTelemetry traces from DuckDB.
 
@@ -516,10 +559,14 @@ class DashboardHTTPService(BlackboardHTTPService):
                                 "status_code": row[10],  # status_code
                                 "description": row[11],  # status_description
                             },
-                            "attributes": json.loads(row[12]) if row[12] else {},  # attributes
+                            "attributes": json.loads(row[12])
+                            if row[12]
+                            else {},  # attributes
                             "events": json.loads(row[13]) if row[13] else [],  # events
                             "links": json.loads(row[14]) if row[14] else [],  # links
-                            "resource": json.loads(row[15]) if row[15] else {},  # resource
+                            "resource": json.loads(row[15])
+                            if row[15]
+                            else {},  # resource
                         }
 
                         # Add parent_id if exists
@@ -535,7 +582,7 @@ class DashboardHTTPService(BlackboardHTTPService):
                 logger.exception(f"Error reading traces from DuckDB: {e}")
                 return []
 
-        @app.get("/api/traces/services")
+        @app.get("/api/traces/services", tags=["Dashboard UI"])
         async def get_trace_services() -> dict[str, Any]:
             """Get list of unique services that have been traced.
 
@@ -581,7 +628,7 @@ class DashboardHTTPService(BlackboardHTTPService):
                 logger.exception(f"Error reading trace services: {e}")
                 return {"services": [], "operations": []}
 
-        @app.post("/api/traces/clear")
+        @app.post("/api/traces/clear", tags=["Dashboard UI"])
         async def clear_traces() -> dict[str, Any]:
             """Clear all traces from DuckDB database.
 
@@ -600,7 +647,7 @@ class DashboardHTTPService(BlackboardHTTPService):
 
             return result
 
-        @app.post("/api/traces/query")
+        @app.post("/api/traces/query", tags=["Dashboard UI"])
         async def execute_trace_query(request: dict[str, Any]) -> dict[str, Any]:
             """
             Execute a DuckDB SQL query on the traces database.
@@ -619,10 +666,22 @@ class DashboardHTTPService(BlackboardHTTPService):
             # Security: Only allow SELECT queries
             query_upper = query.upper().strip()
             if not query_upper.startswith("SELECT"):
-                return {"error": "Only SELECT queries are allowed", "results": [], "columns": []}
+                return {
+                    "error": "Only SELECT queries are allowed",
+                    "results": [],
+                    "columns": [],
+                }
 
             # Check for dangerous keywords
-            dangerous = ["DROP", "DELETE", "INSERT", "UPDATE", "ALTER", "CREATE", "TRUNCATE"]
+            dangerous = [
+                "DROP",
+                "DELETE",
+                "INSERT",
+                "UPDATE",
+                "ALTER",
+                "CREATE",
+                "TRUNCATE",
+            ]
             if any(keyword in query_upper for keyword in dangerous):
                 return {
                     "error": "Query contains forbidden operations",
@@ -632,12 +691,20 @@ class DashboardHTTPService(BlackboardHTTPService):
 
             db_path = Path(".flock/traces.duckdb")
             if not db_path.exists():
-                return {"error": "Trace database not found", "results": [], "columns": []}
+                return {
+                    "error": "Trace database not found",
+                    "results": [],
+                    "columns": [],
+                }
 
             try:
                 with duckdb.connect(str(db_path), read_only=True) as conn:
                     result = conn.execute(query).fetchall()
-                    columns = [desc[0] for desc in conn.description] if conn.description else []
+                    columns = (
+                        [desc[0] for desc in conn.description]
+                        if conn.description
+                        else []
+                    )
 
                     # Convert to JSON-serializable format
                     results = []
@@ -652,12 +719,16 @@ class DashboardHTTPService(BlackboardHTTPService):
                                 row_dict[col] = val
                         results.append(row_dict)
 
-                    return {"results": results, "columns": columns, "row_count": len(results)}
+                    return {
+                        "results": results,
+                        "columns": columns,
+                        "row_count": len(results),
+                    }
             except Exception as e:
                 logger.exception(f"DuckDB query error: {e}")
                 return {"error": str(e), "results": [], "columns": []}
 
-        @app.get("/api/traces/stats")
+        @app.get("/api/traces/stats", tags=["Dashboard UI"])
         async def get_trace_stats() -> dict[str, Any]:
             """Get statistics about the trace database.
 
@@ -691,7 +762,9 @@ class DashboardHTTPService(BlackboardHTTPService):
             try:
                 with duckdb.connect(str(db_path), read_only=True) as conn:
                     # Get total spans
-                    total_spans = conn.execute("SELECT COUNT(*) FROM spans").fetchone()[0]
+                    total_spans = conn.execute("SELECT COUNT(*) FROM spans").fetchone()[
+                        0
+                    ]
 
                     # Get total unique traces
                     total_traces = conn.execute(
@@ -745,7 +818,7 @@ class DashboardHTTPService(BlackboardHTTPService):
                     "database_size_mb": 0,
                 }
 
-        @app.get("/api/streaming-history/{agent_name}")
+        @app.get("/api/streaming-history/{agent_name}", tags=["Dashboard UI"])
         async def get_streaming_history(agent_name: str) -> dict[str, Any]:
             """Get historical streaming output for a specific agent.
 
@@ -777,12 +850,14 @@ class DashboardHTTPService(BlackboardHTTPService):
                     "events": [event.model_dump() for event in history],
                 }
             except Exception as e:
-                logger.exception(f"Failed to get streaming history for {agent_name}: {e}")
+                logger.exception(
+                    f"Failed to get streaming history for {agent_name}: {e}"
+                )
                 raise HTTPException(
                     status_code=500, detail=f"Failed to get streaming history: {e!s}"
                 )
 
-        @app.get("/api/artifacts/history/{node_id}")
+        @app.get("/api/artifacts/history/{node_id}", tags=["Dashboard UI"])
         async def get_message_history(node_id: str) -> dict[str, Any]:
             """Get complete message history for a node (both produced and consumed).
 
@@ -818,24 +893,25 @@ class DashboardHTTPService(BlackboardHTTPService):
 
                 # 1. Get messages PRODUCED by this node
                 produced_filter = FilterConfig(produced_by={node_id})
-                produced_artifacts, _produced_count = await orchestrator.store.query_artifacts(
+                (
+                    produced_artifacts,
+                    _produced_count,
+                ) = await orchestrator.store.query_artifacts(
                     produced_filter, limit=100, offset=0, embed_meta=False
                 )
 
                 for artifact in produced_artifacts:
-                    messages.append(
-                        {
-                            "id": str(artifact.id),
-                            "type": artifact.type,
-                            "direction": "published",
-                            "payload": artifact.payload,
-                            "timestamp": artifact.created_at.isoformat(),
-                            "correlation_id": str(artifact.correlation_id)
-                            if artifact.correlation_id
-                            else None,
-                            "produced_by": artifact.produced_by,
-                        }
-                    )
+                    messages.append({
+                        "id": str(artifact.id),
+                        "type": artifact.type,
+                        "direction": "published",
+                        "payload": artifact.payload,
+                        "timestamp": artifact.created_at.isoformat(),
+                        "correlation_id": str(artifact.correlation_id)
+                        if artifact.correlation_id
+                        else None,
+                        "produced_by": artifact.produced_by,
+                    })
 
                 # 2. Get messages CONSUMED by this node
                 # Query all artifacts with consumption metadata
@@ -848,31 +924,37 @@ class DashboardHTTPService(BlackboardHTTPService):
                     artifact = envelope.artifact
                     for consumption in envelope.consumptions:
                         if consumption.consumer == node_id:
-                            messages.append(
-                                {
-                                    "id": str(artifact.id),
-                                    "type": artifact.type,
-                                    "direction": "consumed",
-                                    "payload": artifact.payload,
-                                    "timestamp": artifact.created_at.isoformat(),
-                                    "correlation_id": str(artifact.correlation_id)
-                                    if artifact.correlation_id
-                                    else None,
-                                    "produced_by": artifact.produced_by,
-                                    "consumed_at": consumption.consumed_at.isoformat(),
-                                }
-                            )
+                            messages.append({
+                                "id": str(artifact.id),
+                                "type": artifact.type,
+                                "direction": "consumed",
+                                "payload": artifact.payload,
+                                "timestamp": artifact.created_at.isoformat(),
+                                "correlation_id": str(artifact.correlation_id)
+                                if artifact.correlation_id
+                                else None,
+                                "produced_by": artifact.produced_by,
+                                "consumed_at": consumption.consumed_at.isoformat(),
+                            })
 
                 # Sort by timestamp (most recent first)
-                messages.sort(key=lambda m: m.get("consumed_at", m["timestamp"]), reverse=True)
+                messages.sort(
+                    key=lambda m: m.get("consumed_at", m["timestamp"]), reverse=True
+                )
 
-                return {"node_id": node_id, "messages": messages, "total": len(messages)}
+                return {
+                    "node_id": node_id,
+                    "messages": messages,
+                    "total": len(messages),
+                }
 
             except Exception as e:
                 logger.exception(f"Failed to get message history for {node_id}: {e}")
-                raise HTTPException(status_code=500, detail=f"Failed to get message history: {e!s}")
+                raise HTTPException(
+                    status_code=500, detail=f"Failed to get message history: {e!s}"
+                )
 
-        @app.get("/api/agents/{agent_id}/runs")
+        @app.get("/api/agents/{agent_id}/runs", tags=["Dashboard UI"])
         async def get_agent_runs(agent_id: str) -> dict[str, Any]:
             """Get run history for an agent.
 
@@ -919,7 +1001,9 @@ class DashboardHTTPService(BlackboardHTTPService):
 
             except Exception as e:
                 logger.exception(f"Failed to get run history for {agent_id}: {e}")
-                raise HTTPException(status_code=500, detail=f"Failed to get run history: {e!s}")
+                raise HTTPException(
+                    status_code=500, detail=f"Failed to get run history: {e!s}"
+                )
 
     def _register_theme_routes(self) -> None:
         """Register theme API endpoints for dashboard customization."""
@@ -930,7 +1014,7 @@ class DashboardHTTPService(BlackboardHTTPService):
         app = self.app
         themes_dir = Path(__file__).parent.parent / "themes"
 
-        @app.get("/api/themes")
+        @app.get("/api/themes", tags=["Dashboard UI"])
         async def list_themes() -> dict[str, Any]:
             """Get list of available theme names.
 
@@ -947,9 +1031,11 @@ class DashboardHTTPService(BlackboardHTTPService):
                 return {"themes": theme_names}
             except Exception as e:
                 logger.exception(f"Failed to list themes: {e}")
-                raise HTTPException(status_code=500, detail=f"Failed to list themes: {e!s}")
+                raise HTTPException(
+                    status_code=500, detail=f"Failed to list themes: {e!s}"
+                )
 
-        @app.get("/api/themes/{theme_name}")
+        @app.get("/api/themes/{theme_name}", tags=["Dashboard UI"])
         async def get_theme(theme_name: str) -> dict[str, Any]:
             """Get theme data by name.
 
@@ -966,12 +1052,16 @@ class DashboardHTTPService(BlackboardHTTPService):
             """
             try:
                 # Sanitize theme name to prevent path traversal
-                theme_name = theme_name.replace("/", "").replace("\\", "").replace("..", "")
+                theme_name = (
+                    theme_name.replace("/", "").replace("\\", "").replace("..", "")
+                )
 
                 theme_path = themes_dir / f"{theme_name}.toml"
 
                 if not theme_path.exists():
-                    raise HTTPException(status_code=404, detail=f"Theme '{theme_name}' not found")
+                    raise HTTPException(
+                        status_code=404, detail=f"Theme '{theme_name}' not found"
+                    )
 
                 # Load TOML theme
                 theme_data = toml.load(theme_path)
@@ -981,7 +1071,9 @@ class DashboardHTTPService(BlackboardHTTPService):
                 raise
             except Exception as e:
                 logger.exception(f"Failed to load theme '{theme_name}': {e}")
-                raise HTTPException(status_code=500, detail=f"Failed to load theme: {e!s}")
+                raise HTTPException(
+                    status_code=500, detail=f"Failed to load theme: {e!s}"
+                )
 
     async def start(self) -> None:
         """Start the dashboard service.
@@ -1088,22 +1180,22 @@ def _get_correlation_groups(
             if collected_types.get(type_name, 0) < required_count
         ]
 
-        result.append(
-            {
-                "correlation_key": str(corr_key),
-                "created_at": group.created_at_time.isoformat() if group.created_at_time else None,
-                "elapsed_seconds": round(elapsed, 1),
-                "expires_in_seconds": round(expires_in_seconds, 1)
-                if expires_in_seconds is not None
-                else None,
-                "expires_in_artifacts": expires_in_artifacts,
-                "collected_types": collected_types,
-                "required_types": dict(group.type_counts),
-                "waiting_for": waiting_for,
-                "is_complete": group.is_complete(),
-                "is_expired": group.is_expired(engine.global_sequence),
-            }
-        )
+        result.append({
+            "correlation_key": str(corr_key),
+            "created_at": group.created_at_time.isoformat()
+            if group.created_at_time
+            else None,
+            "elapsed_seconds": round(elapsed, 1),
+            "expires_in_seconds": round(expires_in_seconds, 1)
+            if expires_in_seconds is not None
+            else None,
+            "expires_in_artifacts": expires_in_artifacts,
+            "collected_types": collected_types,
+            "required_types": dict(group.type_counts),
+            "waiting_for": waiting_for,
+            "is_complete": group.is_complete(),
+            "is_expired": group.is_expired(engine.global_sequence),
+        })
 
     return result
 
@@ -1328,7 +1420,9 @@ def _build_logic_config(  # noqa: F821
             config["batch"]["timeout_seconds"] = int(batch_spec.timeout.total_seconds())
 
         # Get waiting state from BatchEngine
-        batch_state = _get_batch_state(orchestrator._batch_engine, agent.name, idx, batch_spec)
+        batch_state = _get_batch_state(
+            orchestrator._batch_engine, agent.name, idx, batch_spec
+        )
         if batch_state:
             if "waiting_state" not in config:
                 config["waiting_state"] = {"is_waiting": True}

flock/dashboard/websocket.py

@@ -72,7 +72,11 @@ class WebSocketManager:
         logger.info(f"WebSocket client added. Total clients: {len(self.clients)}")
 
         # Start heartbeat task if enabled and not already running
-        if self.enable_heartbeat and self._heartbeat_task is None and not self._shutdown:
+        if (
+            self.enable_heartbeat
+            and self._heartbeat_task is None
+            and not self._shutdown
+        ):
             self._heartbeat_task = asyncio.create_task(self._heartbeat_loop())
 
     async def remove_client(self, websocket: WebSocket) -> None:
@@ -167,7 +171,9 @@ class WebSocketManager:
 
                 # Send ping to all clients
                 ping_tasks = []
-                for client in list(self.clients):  # Copy to avoid modification during iteration
+                for client in list(
+                    self.clients
+                ):  # Copy to avoid modification during iteration
                     ping_tasks.append(self._ping_client(client))
 
                 # Execute pings concurrently
@@ -186,7 +192,10 @@ class WebSocketManager:
             client: WebSocket client to ping
         """
         try:
-            await client.send_json({"type": "ping", "timestamp": asyncio.get_event_loop().time()})
+            await client.send_json({
+                "type": "ping",
+                "timestamp": asyncio.get_event_loop().time(),
+            })
         except Exception as e:
             logger.warning(f"Failed to ping client: {e}")
             await self.remove_client(client)
@@ -197,7 +206,11 @@ class WebSocketManager:
         In production, heartbeat is disabled by default (enable_heartbeat=False).
         Only starts if enable_heartbeat=True.
         """
-        if self.enable_heartbeat and self._heartbeat_task is None and not self._shutdown:
+        if (
+            self.enable_heartbeat
+            and self._heartbeat_task is None
+            and not self._shutdown
+        ):
             self._heartbeat_task = asyncio.create_task(self._heartbeat_loop())
 
     async def shutdown(self) -> None: