refactor: update module docstrings for clarity and consistency

backend/app/services/board_snapshot.py

@@ -1,17 +1,17 @@
+"""Helpers for assembling denormalized board snapshot response payloads."""
+
 from __future__ import annotations
 
 from datetime import timedelta
-from uuid import UUID
+from typing import TYPE_CHECKING
 
 from sqlalchemy import case, func
 from sqlmodel import col, select
-from sqlmodel.ext.asyncio.session import AsyncSession
 
 from app.core.time import utcnow
 from app.models.agents import Agent
 from app.models.approvals import Approval
 from app.models.board_memory import BoardMemory
-from app.models.boards import Board
 from app.models.gateways import Gateway
 from app.models.tasks import Task
 from app.schemas.agents import AgentRead
@@ -25,6 +25,13 @@ from app.services.task_dependencies import (
     dependency_status_by_id,
 )
 
+if TYPE_CHECKING:
+    from uuid import UUID
+
+    from sqlmodel.ext.asyncio.session import AsyncSession
+
+    from app.models.boards import Board
+
 OFFLINE_AFTER = timedelta(minutes=10)
 
 
@@ -48,9 +55,15 @@ def _agent_to_read(agent: Agent, main_session_keys: set[str]) -> AgentRead:
     model = AgentRead.model_validate(agent, from_attributes=True)
     computed_status = _computed_agent_status(agent)
     is_gateway_main = bool(
-        agent.openclaw_session_id and agent.openclaw_session_id in main_session_keys
+        agent.openclaw_session_id
+        and agent.openclaw_session_id in main_session_keys,
+    )
+    return model.model_copy(
+        update={
+            "status": computed_status,
+            "is_gateway_main": is_gateway_main,
+        },
     )
-    return model.model_copy(update={"status": computed_status, "is_gateway_main": is_gateway_main})
 
 
 def _memory_to_read(memory: BoardMemory) -> BoardMemoryRead:
@@ -72,7 +85,9 @@ def _task_to_card(
     card = TaskCardRead.model_validate(task, from_attributes=True)
     approvals_count, approvals_pending_count = counts_by_task_id.get(task.id, (0, 0))
     assignee = (
-        agent_name_by_id.get(task.assigned_agent_id) if task.assigned_agent_id is not None else None
+        agent_name_by_id.get(task.assigned_agent_id)
+        if task.assigned_agent_id
+        else None
     )
     depends_on_task_ids = deps_by_task_id.get(task.id, [])
     blocked_by_task_ids = blocked_by_dependency_ids(
@@ -89,21 +104,26 @@ def _task_to_card(
             "depends_on_task_ids": depends_on_task_ids,
             "blocked_by_task_ids": blocked_by_task_ids,
             "is_blocked": bool(blocked_by_task_ids),
-        }
+        },
     )
 
 
 async def build_board_snapshot(session: AsyncSession, board: Board) -> BoardSnapshot:
+    """Build a board snapshot with tasks, agents, approvals, and chat history."""
     board_read = BoardRead.model_validate(board, from_attributes=True)
 
     tasks = list(
         await Task.objects.filter_by(board_id=board.id)
         .order_by(col(Task.created_at).desc())
-        .all(session)
+        .all(session),
     )
     task_ids = [task.id for task in tasks]
 
-    deps_by_task_id = await dependency_ids_by_task_id(session, board_id=board.id, task_ids=task_ids)
+    deps_by_task_id = await dependency_ids_by_task_id(
+        session,
+        board_id=board.id,
+        task_ids=task_ids,
+    )
     all_dependency_ids: list[UUID] = []
     for values in deps_by_task_id.values():
         all_dependency_ids.extend(values)
@@ -127,9 +147,9 @@ async def build_board_snapshot(session: AsyncSession, board: Board) -> BoardSnap
             await session.exec(
                 select(func.count(col(Approval.id)))
                 .where(col(Approval.board_id) == board.id)
-                .where(col(Approval.status) == "pending")
-            )
-        ).one()
+                .where(col(Approval.status) == "pending"),
+            ),
+        ).one(),
     )
 
     approvals = (
@@ -146,12 +166,14 @@ async def build_board_snapshot(session: AsyncSession, board: Board) -> BoardSnap
             select(
                 col(Approval.task_id),
                 func.count(col(Approval.id)).label("total"),
-                func.sum(case((col(Approval.status) == "pending", 1), else_=0)).label("pending"),
+                func.sum(
+                    case((col(Approval.status) == "pending", 1), else_=0),
+                ).label("pending"),
             )
             .where(col(Approval.board_id) == board.id)
             .where(col(Approval.task_id).is_not(None))
-            .group_by(col(Approval.task_id))
-        )
+            .group_by(col(Approval.task_id)),
+        ),
     )
     for task_id, total, pending in rows:
         if task_id is None: