semantic markup update

2026-01-18 21:29:54 +03:00
parent 11c59fb420
commit 76baeb1038
85 changed files with 7020 additions and 5953 deletions
--- a/backend/src/core/task_manager/manager.py
+++ b/backend/src/core/task_manager/manager.py
@@ -186,17 +186,23 @@ class TaskManager:

    # [DEF:get_task:Function]
    # @PURPOSE: Retrieves a task by its ID.
+    # @PRE:     task_id is a string.
+    # @POST:    Returns Task object or None.
    # @PARAM:   task_id (str) - ID of the task.
    # @RETURN:  Optional[Task] - The task or None.
    def get_task(self, task_id: str) -> Optional[Task]:
-        return self.tasks.get(task_id)
+        with belief_scope("TaskManager.get_task", f"task_id={task_id}"):
+            return self.tasks.get(task_id)
    # [/DEF:get_task:Function]

    # [DEF:get_all_tasks:Function]
    # @PURPOSE: Retrieves all registered tasks.
+    # @PRE:     None.
+    # @POST:    Returns list of all Task objects.
    # @RETURN:  List[Task] - All tasks.
    def get_all_tasks(self) -> List[Task]:
-        return list(self.tasks.values())
+        with belief_scope("TaskManager.get_all_tasks"):
+            return list(self.tasks.values())
    # [/DEF:get_all_tasks:Function]

    # [DEF:get_tasks:Function]
@@ -208,7 +214,8 @@ class TaskManager:
    # @PARAM:   status (Optional[TaskStatus]) - Filter by task status.
    # @RETURN:  List[Task] - List of tasks matching criteria.
    def get_tasks(self, limit: int = 10, offset: int = 0, status: Optional[TaskStatus] = None) -> List[Task]:
-        tasks = list(self.tasks.values())
+        with belief_scope("TaskManager.get_tasks"):
+            tasks = list(self.tasks.values())
        if status:
            tasks = [t for t in tasks if t.status == status]
        # Sort by start_time descending (most recent first)
@@ -218,11 +225,14 @@ class TaskManager:

    # [DEF:get_task_logs:Function]
    # @PURPOSE: Retrieves logs for a specific task.
+    # @PRE:     task_id is a string.
+    # @POST:    Returns list of LogEntry objects.
    # @PARAM:   task_id (str) - ID of the task.
    # @RETURN:  List[LogEntry] - List of log entries.
    def get_task_logs(self, task_id: str) -> List[LogEntry]:
-        task = self.tasks.get(task_id)
-        return task.logs if task else []
+        with belief_scope("TaskManager.get_task_logs", f"task_id={task_id}"):
+            task = self.tasks.get(task_id)
+            return task.logs if task else []
    # [/DEF:get_task_logs:Function]

    # [DEF:_add_log:Function]
@@ -234,51 +244,61 @@ class TaskManager:
    # @PARAM:   message (str) - Log message.
    # @PARAM:   context (Optional[Dict]) - Log context.
    def _add_log(self, task_id: str, level: str, message: str, context: Optional[Dict[str, Any]] = None):
-        task = self.tasks.get(task_id)
-        if not task:
-            return
+        with belief_scope("TaskManager._add_log", f"task_id={task_id}"):
+            task = self.tasks.get(task_id)
+            if not task:
+                return

-        log_entry = LogEntry(level=level, message=message, context=context)
-        task.logs.append(log_entry)
-        self.persistence_service.persist_task(task)
+            log_entry = LogEntry(level=level, message=message, context=context)
+            task.logs.append(log_entry)
+            self.persistence_service.persist_task(task)

-        # Notify subscribers
-        if task_id in self.subscribers:
-            for queue in self.subscribers[task_id]:
-                self.loop.call_soon_threadsafe(queue.put_nowait, log_entry)
+            # Notify subscribers
+            if task_id in self.subscribers:
+                for queue in self.subscribers[task_id]:
+                    self.loop.call_soon_threadsafe(queue.put_nowait, log_entry)
    # [/DEF:_add_log:Function]

    # [DEF:subscribe_logs:Function]
    # @PURPOSE: Subscribes to real-time logs for a task.
+    # @PRE:     task_id is a string.
+    # @POST:    Returns an asyncio.Queue for log entries.
    # @PARAM:   task_id (str) - ID of the task.
    # @RETURN:  asyncio.Queue - Queue for log entries.
    async def subscribe_logs(self, task_id: str) -> asyncio.Queue:
-        queue = asyncio.Queue()
-        if task_id not in self.subscribers:
-            self.subscribers[task_id] = []
-        self.subscribers[task_id].append(queue)
-        return queue
+        with belief_scope("TaskManager.subscribe_logs", f"task_id={task_id}"):
+            queue = asyncio.Queue()
+            if task_id not in self.subscribers:
+                self.subscribers[task_id] = []
+            self.subscribers[task_id].append(queue)
+            return queue
    # [/DEF:subscribe_logs:Function]

    # [DEF:unsubscribe_logs:Function]
    # @PURPOSE: Unsubscribes from real-time logs for a task.
+    # @PRE:     task_id is a string, queue is asyncio.Queue.
+    # @POST:    Queue removed from subscribers.
    # @PARAM:   task_id (str) - ID of the task.
    # @PARAM:   queue (asyncio.Queue) - Queue to remove.
    def unsubscribe_logs(self, task_id: str, queue: asyncio.Queue):
-        if task_id in self.subscribers:
-            if queue in self.subscribers[task_id]:
-                self.subscribers[task_id].remove(queue)
-            if not self.subscribers[task_id]:
-                del self.subscribers[task_id]
+        with belief_scope("TaskManager.unsubscribe_logs", f"task_id={task_id}"):
+            if task_id in self.subscribers:
+                if queue in self.subscribers[task_id]:
+                    self.subscribers[task_id].remove(queue)
+                if not self.subscribers[task_id]:
+                    del self.subscribers[task_id]
    # [/DEF:unsubscribe_logs:Function]

    # [DEF:load_persisted_tasks:Function]
    # @PURPOSE: Load persisted tasks using persistence service.
+    # @PRE:     None.
+    # @POST:    Persisted tasks loaded into self.tasks.
    def load_persisted_tasks(self) -> None:
-        loaded_tasks = self.persistence_service.load_tasks(limit=100)
-        for task in loaded_tasks:
-            if task.id not in self.tasks:
-                self.tasks[task.id] = task
+        with belief_scope("TaskManager.load_persisted_tasks"):
+            loaded_tasks = self.persistence_service.load_tasks(limit=100)
+            for task in loaded_tasks:
+                if task.id not in self.tasks:
+                    self.tasks[task.id] = task
    # [/DEF:load_persisted_tasks:Function]

    # [DEF:await_input:Function]
@@ -334,6 +354,8 @@ class TaskManager:

    # [DEF:clear_tasks:Function]
    # @PURPOSE: Clears tasks based on status filter.
+    # @PRE:     status is Optional[TaskStatus].
+    # @POST:    Tasks matching filter (or all non-active) cleared from registry and database.
    # @PARAM:   status (Optional[TaskStatus]) - Filter by task status.
    # @RETURN:  int - Number of tasks cleared.
    def clear_tasks(self, status: Optional[TaskStatus] = None) -> int:
--- a/backend/src/core/task_manager/persistence.py
+++ b/backend/src/core/task_manager/persistence.py
@@ -26,12 +26,15 @@ class TaskPersistenceService:
    # @PRE:     None.
    # @POST:    Service is ready.
    def __init__(self):
-        # We use TasksSessionLocal from database.py
-        pass
+        with belief_scope("TaskPersistenceService.__init__"):
+            # We use TasksSessionLocal from database.py
+            pass
    # [/DEF:__init__:Function]

    # [DEF:persist_task:Function]
    # @PURPOSE: Persists or updates a single task in the database.
+    # @PRE:     isinstance(task, Task)
+    # @POST:    Task record created or updated in database.
    # @PARAM:   task (Task) - The task object to persist.
    def persist_task(self, task: Task) -> None:
        with belief_scope("TaskPersistenceService.persist_task", f"task_id={task.id}"):
@@ -75,14 +78,19 @@ class TaskPersistenceService:

    # [DEF:persist_tasks:Function]
    # @PURPOSE: Persists multiple tasks.
+    # @PRE:     isinstance(tasks, list)
+    # @POST:    All tasks in list are persisted.
    # @PARAM:   tasks (List[Task]) - The list of tasks to persist.
    def persist_tasks(self, tasks: List[Task]) -> None:
-        for task in tasks:
-            self.persist_task(task)
+        with belief_scope("TaskPersistenceService.persist_tasks"):
+            for task in tasks:
+                self.persist_task(task)
    # [/DEF:persist_tasks:Function]

    # [DEF:load_tasks:Function]
    # @PURPOSE: Loads tasks from the database.
+    # @PRE:     limit is an integer.
+    # @POST:    Returns list of Task objects.
    # @PARAM:   limit (int) - Max tasks to load.
    # @PARAM:   status (Optional[TaskStatus]) - Filter by status.
    # @RETURN:  List[Task] - The loaded tasks.
@@ -128,6 +136,8 @@ class TaskPersistenceService:

    # [DEF:delete_tasks:Function]
    # @PURPOSE: Deletes specific tasks from the database.
+    # @PRE:     task_ids is a list of strings.
+    # @POST:    Specified task records deleted from database.
    # @PARAM:   task_ids (List[str]) - List of task IDs to delete.
    def delete_tasks(self, task_ids: List[str]) -> None:
        if not task_ids: