From eca29af5e1af48c644ac0b8002affbb3aedf9770 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?=D0=9A=D0=BE=D0=B1=D1=8B=D0=BB=D0=BA=D0=B5=D0=B2=D0=B8?=
 =?UTF-8?q?=D1=87=20=D0=A4=D1=91=D0=B4=D0=BE=D1=80?=
 <fmkobylkevich@mai.education>
Date: Tue, 7 Apr 2026 22:08:33 +0300
Subject: [PATCH] add descriptions in schemas.py

---
 api/schemas.py | 34 ++++++++++++++++++++++------------
 1 file changed, 22 insertions(+), 12 deletions(-)

diff --git a/api/schemas.py b/api/schemas.py
index 9fe3acbe..4b36d5ba 100644
--- a/api/schemas.py
+++ b/api/schemas.py
@@ -1,10 +1,12 @@
 from enum import Enum
-from typing import Optional, Any
+from typing import Any
 
 from pydantic import BaseModel, Field
 
 
 class TaskStatus(str, Enum):
+    """Состояние задачи браузерного агента."""
+
     queued = "queued"
     running = "running"
     succeeded = "succeeded"
@@ -12,30 +14,38 @@ class TaskStatus(str, Enum):
 
 
 class BrowserTaskRequest(BaseModel):
-    task: str = Field(..., description="Задача для браузера")
+    """Запрос на запуск задачи в browser-use агенте."""
+
+    task: str = Field(..., description="Текстовая задача для browser-use агента")
     timeout: int = Field(300, description="Максимальное время выполнения задачи в секундах")
-    metadata: dict[str, Any] | None = Field(default=None, description="Метаданные клиента")
+    metadata: dict[str, Any] | None = Field(default=None, description="Дополнительные метаданные клиента")
 
 
 class BrowserTaskAcceptedResponse(BaseModel):
+    """Ответ о том, что задача принята в обработку."""
+
     task_id: str
     status: TaskStatus
 
 
 class BrowserTaskStatusResponse(BaseModel):
+    """Текущий статус задачи и временные отметки её выполнения."""
+
     task_id: str
     status: TaskStatus
-    create_at: float
-    started_at: float | None = None
-    finished_at: float | None = None
-    error: str | None = None
+    create_at: float = Field(..., description="Время создания задачи в Unix timestamp")
+    started_at: float | None = Field(default=None, description="Время начала выполнения в Unix timestamp")
+    finished_at: float | None = Field(default=None, description="Время завершения выполнения в Unix timestamp")
+    error: str | None = Field(default=None, description="Текст ошибки, если задача завершилась с ошибкой")
 
 
 class BrowserTaskResultResponse(BaseModel):
+    """Финальный результат выполнения задачи в browser-use."""
+
     task_id: str
     status: TaskStatus
-    success: bool
-    execution_time: float
-    result: str | None = None
-    error: str | None = None
-    raw_response: dict[str, Any] | None = None
+    success: bool = Field(..., description="Успешно ли выполнена задача")
+    execution_time: float = Field(..., description="Фактическое время выполнения в секундах")
+    result: str | None = Field(default=None, description="Итоговый текстовый результат")
+    error: str | None = Field(default=None, description="Текст ошибки, если выполнение не удалось")
+    raw_response: dict[str, Any] | None = Field(default=None, description="Сырой ответ от browser-use RPC")