Docs/Endpoints docs (or Backend API docs)

backend/chatsky_ui/api/api_v1/endpoints/bot.py

@@ -52,6 +52,9 @@ async def start_build(
 
     Args:
         preset (Preset): The preset to set the build process for. Must be among ("success", "failure", "loop")
+        background_tasks (BackgroundTasks): A background tasks manager. Required to schedule a task that checks the
+            status of the build process.
+        build_manager (BuildManager): The process manager dependency to start the process with.
 
     Returns:
         {"status": "ok", "build_id": build_id}: in case of **starting** the build process successfully.
@@ -70,7 +73,7 @@ async def stop_build(*, build_id: int, build_manager: BuildManager = Depends(dep
 
     Args:
         build_id (int): The id of the process to stop.
-        build_id (BuildManager): The process manager dependency to stop the process with.
+        build_manager (BuildManager): The process manager dependency to stop the process with.
 
     Raises:
         HTTPException: With status code 404 if the process is not found.
@@ -105,6 +108,15 @@ async def check_build_status(
 
 @router.get("/build/is_changed", status_code=200)
 async def check_graph_changes(*, build_manager: BuildManager = Depends(deps.get_build_manager)) -> Dict[str, Any]:
+    """Checks if the graph was changed since last build/run (???)
+
+    Args:
+        build_manager (BuildManager): The process manager dependency to check the graph with.
+
+    Returns:
+        {"status": "ok", "data": True}: in case the graph was changed.
+        {"status": "ok", "data": False}: in case the graph wasn't changed.
+    """
     if build_manager.graph_repo_manager.is_changed():
         return {"status": "ok", "data": True}
     return {"status": "ok", "data": False}
@@ -122,7 +134,14 @@ async def check_build_processes(
     The offset and limit parameters can be used to paginate the results.
 
     Args:
-        build_id (Optional[int]): The id of the process to check. If not specified, all processes will be returned.
+        build_id (Optional[int]): The id of the process to check. If not specified, all processes will be checked.
+        build_manager (BuildManager): The `build` process manager to check the processes with.
+        run_manager (RunManager): The `run` process manager to use for getting all runs of this build.
+        pagination (Pagination): An object containing the offset and limit parameters for paginating results.
+
+    Returns:
+        In case `build_id` is specified, the build info for that process is returned.
+        Otherwise, a list containing statuses of all `build` processes along with their runs info.
     """
     if build_id is not None:
         return await build_manager.get_build_info(build_id, run_manager)
@@ -139,6 +158,11 @@ async def get_build_logs(
     """Gets the logs of a specific `build` process.
 
     The offset and limit parameters can be used to paginate the results.
+
+    Args:
+        build_id (Optional[int]): The id of the process to get the logs from.
+        build_manager (BuildManager): The `build` process manager containing the `build_id` process.
+        pagination (Pagination): An object containing the offset and limit parameters for paginating results.
     """
     if build_id is not None:
         return await build_manager.fetch_build_logs(build_id, pagination.offset(), pagination.limit)
@@ -159,6 +183,9 @@ async def start_run(
     Args:
         build_id (int): The id of the build process to start running.
         preset (Preset): The preset to set the build process for. Must be among ("success", "failure", "loop")
+        background_tasks (BackgroundTasks): A background tasks manager. Required to schedule a task that checks the
+            status of the run process.
+        run_manager (RunManager): The `run` process manager to start the process with.
 
     Returns:
         {"status": "ok", "build_id": run_id}: in case of **starting** the run process successfully.
@@ -194,7 +221,7 @@ async def check_run_status(*, run_id: int, run_manager: RunManager = Depends(dep
     """Checks the status of a `run` process with the given id.
 
     Args:
-        build_id (int): The id of the process to check.
+        run_id (int): The id of the process to check.
         run_manager (RunManager): The process manager dependency to check the process with.
 
     Raises:
@@ -221,6 +248,12 @@ async def check_run_processes(
 
     Args:
         run_id (Optional[int]): The id of the process to check. If not specified, all processes will be returned.
+        run_manager (RunManager): The `run` process manager to check the process with.
+        pagination (Pagination): An object containing the offset and limit parameters for paginating results.
+
+    Returns:
+        In case `run_id` is specified, the run info for that process is returned.
+        Otherwise, a list with run info of all `run` processes is returned.
     """
 
     if run_id is not None:
@@ -236,6 +269,11 @@ async def get_run_logs(
     """Gets the logs of a specific `run` process.
 
     The offset and limit parameters can be used to paginate the results.
+
+    Args:
+        run_id (Optional[int]): The id of the process to get the logs from.
+        run_manager (RunManager): The `run` process manager containing the `build_id` process.
+        pagination (Pagination): An object containing the offset and limit parameters for paginating results.
     """
     if run_id is not None:
         return await run_manager.fetch_run_logs(run_id, pagination.offset(), pagination.limit)

backend/chatsky_ui/api/api_v1/endpoints/chatsky_services.py

@@ -18,14 +18,26 @@
 
 @router.get("/search/condition/{condition_name}", status_code=200)
 async def search_condition(condition_name: str) -> Dict[str, Union[str, list]]:
-    """Searches for a custom condition by name and returns its code."""
+    """Searches for a custom condition by name and returns its code.
+
+    Args:
+        condition_name (str): Name of the condition to search for.
+
+    Returns:
+        {"status": "ok", "data": response}: in case of searching for the condition successfully.
+    """
     custom_classes = get_all_classes(settings.conditions_path)
     response = [custom_class["body"] for custom_class in custom_classes if custom_class["name"] == condition_name]
     return {"status": "ok", "data": response}
 
 
 @router.get("/get_all_custom_conditions", status_code=200)
 async def get_all_custom_conditions_names() -> Dict[str, Union[str, list]]:
+    """Searches for all custom conditions and returns their code.
+
+    Returns:
+        {"status": "ok", "data": custom_classes}: `custom_classes` here is a list of conditions' scripts.
+    """
     all_classes = get_all_classes(settings.conditions_path)
     custom_classes = [custom_class["body"] for custom_class in all_classes]
     return {"status": "ok", "data": custom_classes}
@@ -36,6 +48,14 @@ async def lint_snippet(snippet: CodeSnippet) -> Dict[str, str]:
     """Lints a snippet with Pylint.
 
     This endpoint Joins the snippet with all imports existing in the conditions.py file and then runs Pylint on it.
+    Note that PyLint's "W,I,R,C" error codes are ignored.
+
+    Args:
+        snippet (CodeSnippet): The code snippet to run PyLint on.
+
+    Returns:
+        {"status": "ok", "message": ""}: in case PyLint ran successfully.
+        {"status": "error", "message": error}: in case PyLint found a mistake, with `message` being the error message.
     """
     code_snippet = snippet.code.replace(r"\n", "\n")
 
@@ -60,5 +80,9 @@ async def lint_snippet(snippet: CodeSnippet) -> Dict[str, str]:
 
 @router.get("/get_conditions", status_code=200)
 async def get_conditions() -> Dict[str, Union[str, list]]:
-    """Gets the chatsky's out-of-the-box conditions."""
+    """Gets the chatsky's out-of-the-box conditions.
+
+    Returns:
+        {"status": "ok", "data": chatsky_conditions}: with `data` containing a list of Chatsky conditions' info_dicts.
+    """
     return {"status": "ok", "data": get_chatsky_conditions()}

backend/chatsky_ui/api/api_v1/endpoints/config.py

@@ -7,4 +7,5 @@
 
 @router.get("/version")
 async def get_version():
+    """Returns current Chatsky-UI version using importlib.metadata"""
     return __version__

backend/chatsky_ui/api/api_v1/endpoints/flows.py

@@ -18,7 +18,16 @@
 async def flows_get(
     build_id: Optional[int] = None, build_manager: BuildManager = Depends(get_build_manager)
 ) -> Dict[str, Union[str, Dict[str, Union[list, dict]]]]:
-    """Get the flows by reading the frontend_flows.yaml file."""
+    """Get the flows by reading the frontend_flows.yaml file.
+
+    Args:
+        build_id (Optional[int]): The id of the process to get the flows from.
+        build_manager (BuildManager): The `build` process manager containing the `build_id` process.
+
+    Returns:
+        {"status": "ok", "data": dict_flows}: in case of reading the frontend_flows.yaml file successfully,
+        where `data` contains the flows obtained from the file.
+    """
     if build_id is not None:
         tag = int(build_id)
         try:
@@ -46,7 +55,15 @@ async def flows_get(
 async def flows_post(
     flows: Dict[str, Union[list, dict]], build_manager: BuildManager = Depends(get_build_manager)
 ) -> Dict[str, str]:
-    """Write the flows to the frontend_flows.yaml file."""
+    """Write the flows to the frontend_flows.yaml file.
+
+    Args:
+        flows (dict): The flows to write into the frontend_flows.yaml file.
+        build_manager (BuildManager): The `build` process manager used in the current context.
+
+    Returns:
+        {"status": "ok"}: in case of writing the flows into the file successfully.
+    """
 
     tags = sorted(build_manager.graph_repo_manager.repo.tags, key=lambda t: t.commit.committed_datetime)
     build_manager.graph_repo_manager.checkout_tag(tags[-1], settings.frontend_flows_path.name)
@@ -57,7 +74,15 @@ async def flows_post(
 
 
 @router.post("/tg_token")
-async def post_tg_token(token: str):
+async def post_tg_token(token: str) -> Dict[str, str]:
+    """Write the `TG_BOT_TOKEN` into the .env file for later use.
+
+    Args:
+        token (str): The token to write into the .env file.
+
+    Returns:
+        {"status": "ok"}: in case of writing the token into the file successfully.
+    """
     dotenv_path = Path(settings.work_directory) / ".env"
     dotenv_path.touch(exist_ok=True)