chore: update semantic index, agent configs, and app startup

backend/src/app.py

@@ -1,14 +1,15 @@
 # #region AppModule [C:5] [TYPE Module] [SEMANTICS fastapi, websocket, startup, scheduler, middleware]
 # @BRIEF The main entry point for the FastAPI application. It initializes the app, configures CORS, sets up dependencies, includes API routers, and defines the WebSocket endpoint for log streaming.
-# @LAYER: UI (API)
-# @RELATION DEPENDS_ON -> [AppDependencies]
+# @LAYER UI (API)
 # @RELATION DEPENDS_ON -> [ApiRoutesModule]
-# @INVARIANT: Only one FastAPI app instance exists per process.
-# @INVARIANT: All WebSocket connections must be properly cleaned up on disconnect.
-# @PRE: Python environment and dependencies installed; configuration database available.
-# @POST: FastAPI app instance is created, middleware configured, and routes registered.
-# @SIDE_EFFECT: Starts background scheduler and binds network ports for HTTP/WS traffic.
-# @DATA_CONTRACT: [HTTP Request | WS Message] -> [HTTP Response | JSON Log Stream]
+# @RELATION DEPENDS_ON -> [ApiRoutesModule]
+# @INVARIANT All WebSocket connections must be properly cleaned up on disconnect.
+# @INVARIANT All WebSocket connections must be properly cleaned up on disconnect.
+# @PRE Python environment and dependencies installed; configuration database available.
+# @POST FastAPI app instance is created, middleware configured, and routes registered.
+# @SIDE_EFFECT Starts background scheduler and binds network ports for HTTP/WS traffic.
+# @DATA_CONTRACT [HTTP Request | WS Message] -> [HTTP Response | JSON Log Stream]
+
 import os
 from pathlib import Path
 
@@ -116,8 +117,8 @@ def ensure_initial_admin_user() -> None:
 # #region startup_event [C:3] [TYPE Function]
 # @BRIEF Handles application startup tasks, such as starting the scheduler.
 # @RELATION CALLS -> [AppDependencies]
-# @PRE: None.
-# @POST: Scheduler is started.
+# @PRE None.
+# @POST Scheduler is started.
 # Startup event
 @app.on_event("startup")
 async def startup_event():
@@ -131,8 +132,8 @@ async def startup_event():
 # #region shutdown_event [C:3] [TYPE Function]
 # @BRIEF Handles application shutdown tasks, such as stopping the scheduler.
 # @RELATION CALLS -> [AppDependencies]
-# @PRE: None.
-# @POST: Scheduler is stopped.
+# @PRE None.
+# @POST Scheduler is stopped.
 # Shutdown event
 @app.on_event("shutdown")
 async def shutdown_event():
@@ -158,8 +159,8 @@ app.add_middleware(
 # #endregion app_middleware
 # #region network_error_handler [C:1] [TYPE Function]
 # @BRIEF Global exception handler for NetworkError.
-# @PRE: request is a FastAPI Request object.
-# @POST: Returns 503 HTTP Exception.
+# @PRE request is a FastAPI Request object.
+# @POST Returns 503 HTTP Exception.
 @app.exception_handler(NetworkError)
 async def network_error_handler(request: Request, exc: NetworkError):
     with belief_scope("network_error_handler"):
@@ -172,8 +173,8 @@ async def network_error_handler(request: Request, exc: NetworkError):
 # #region log_requests [C:3] [TYPE Function]
 # @BRIEF Middleware to log incoming HTTP requests and their response status.
 # @RELATION DEPENDS_ON -> [LoggerModule]
-# @PRE: request is a FastAPI Request object.
-# @POST: Logs request and response details.
+# @PRE request is a FastAPI Request object.
+# @POST Logs request and response details.
 @app.middleware("http")
 async def log_requests(request: Request, call_next):
     with belief_scope("log_requests"):
@@ -241,20 +242,20 @@ app.include_router(translate.router)
 # #endregion API_Routes
 # #region api.include_routers [C:1] [TYPE Action] [SEMANTICS routes, registration, api]
 # @BRIEF Registers all API routers with the FastAPI application.
-# @LAYER: API
+# @LAYER API
 # #endregion api.include_routers
 # #region websocket_endpoint [C:5] [TYPE Function]
 # @BRIEF Provides a WebSocket endpoint for real-time log streaming of a task with server-side filtering.
 # @RELATION CALLS -> [TaskManagerPackage]
 # @RELATION DEPENDS_ON -> [LoggerModule]
-# @PRE: task_id must be a valid task ID.
-# @POST: WebSocket connection is managed and logs are streamed until disconnect.
-# @SIDE_EFFECT: Subscribes to TaskManager log queue and broadcasts messages over network.
-# @DATA_CONTRACT: [task_id: str, source: str, level: str] -> [JSON log entry objects]
-# @INVARIANT: Every accepted WebSocket subscription is unsubscribed exactly once even when streaming fails or the client disconnects.
-# @UX_STATE: Connecting -> Streaming -> (Disconnected)
+# @PRE task_id must be a valid task ID.
+# @POST WebSocket connection is managed and logs are streamed until disconnect.
+# @SIDE_EFFECT Subscribes to TaskManager log queue and broadcasts messages over network.
+# @DATA_CONTRACT [task_id: str, source: str, level: str] -> [JSON log entry objects]
+# @INVARIANT Every accepted WebSocket subscription is unsubscribed exactly once even when streaming fails or the client disconnects.
+# @UX_STATE Connecting -> Streaming -> (Disconnected)
 #
-# @TEST_CONTRACT: WebSocketLogStreamApi ->
+# @TEST_CONTRACT WebSocketLogStreamApi ->
 # {
 #   required_fields: {websocket: WebSocket, task_id: str},
 #   optional_fields: {source: str, level: str},
@@ -264,10 +265,10 @@ app.include_router(translate.router)
 #       "Cleans up subscriptions on disconnect"
 #   ]
 # }
-# @TEST_FIXTURE: valid_ws_connection -> {"task_id": "test_1", "source": "plugin"}
-# @TEST_EDGE: task_not_found_ws -> closes connection or sends error
-# @TEST_EDGE: empty_task_logs -> waits for new logs
-# @TEST_INVARIANT: consistent_streaming -> verifies: [valid_ws_connection]
+# @TEST_FIXTURE valid_ws_connection -> {"task_id": "test_1", "source": "plugin"}
+# @TEST_EDGE task_not_found_ws -> closes connection or sends error
+# @TEST_EDGE empty_task_logs -> waits for new logs
+# @TEST_INVARIANT consistent_streaming -> verifies: [valid_ws_connection]
 @app.websocket("/ws/logs/{task_id}")
 async def websocket_endpoint(
     websocket: WebSocket, task_id: str, source: str = None, level: str = None
@@ -395,9 +396,9 @@ if frontend_path.exists():
         "/_app", StaticFiles(directory=str(frontend_path / "_app")), name="static"
     )
     # #region serve_spa [TYPE Function] [C:1]
-    # @PURPOSE: Serves the SPA frontend for any path not matched by API routes.
-    # @PRE: frontend_path exists.
-    # @POST: Returns the requested file or index.html.
+    # @PURPOSE Serves the SPA frontend for any path not matched by API routes.
+    # @PRE frontend_path exists.
+    # @POST Returns the requested file or index.html.
     @app.get("/{file_path:path}", include_in_schema=False)
     async def serve_spa(file_path: str):
         with belief_scope("serve_spa"):
@@ -420,9 +421,9 @@ if frontend_path.exists():
     # #endregion serve_spa
 else:
     # #region read_root [TYPE Function] [C:1]
-    # @PURPOSE: A simple root endpoint to confirm that the API is running when frontend is missing.
-    # @PRE: None.
-    # @POST: Returns a JSON message indicating API status.
+    # @PURPOSE A simple root endpoint to confirm that the API is running when frontend is missing.
+    # @PRE None.
+    # @POST Returns a JSON message indicating API status.
     @app.get("/")
     async def read_root():
         with belief_scope("read_root"):
@@ -432,3 +433,4 @@ else:
     # #endregion read_root
 # #endregion StaticFiles
 # #endregion AppModule
+# #endregion AppModule