Docs/chatsky UI pics

.github/workflows/build_and_publish_docs.yml

@@ -24,20 +24,40 @@ jobs:
       - name: setup poetry
         run: |
           python -m pip install --upgrade pip poetry
-  
-      - name: install dependencies
+
+      - name: install backend dependencies
         run: poetry install
         working-directory: backend
 
-      - name: build documentation
-        run: make build_docs
+      - name: build api documentation
+        run: make build_api_docs
 
-      - name: remove jekyll theming
+      - name: remove jekyll theming for api
         run: touch docs/_build/html/.nojekyll
 
-      - name: deploy website
+      - name: install ui docs dependencies
+        run: bun install
+        working-directory: docs/ui-docs
+
+      - name: build ui documentation
+        run: bun run build
+        working-directory: docs/ui-docs
+
+      - name: remove jekyll theming for ui
+        run: touch docs/ui-docs/out/.nojekyll
+
+      - name: deploy api documentation
         uses: JamesIves/github-pages-deploy-action@v4
         with:
           branch: gh-pages
           folder: docs/_build/html
+          target-folder: backend
+          single-commit: True
+
+      - name: deploy frontend documentation
+        uses: JamesIves/github-pages-deploy-action@v4
+        with:
+          branch: gh-pages
+          folder: docs/ui-docs/out
+          target-folder: frontend
           single-commit: True

.gitignore

@@ -82,6 +82,7 @@ yarn-error.log*
 # Dependency directories
 node_modules/
 jspm_packages/
+docs/ui-docs/out
 
 # Optional npm cache directory
 .npm

CONTRIBUTING.md

@@ -7,7 +7,7 @@ All PRs are reviewed by Chatsky-UI developers team. In order to make the reviewe
 
 ## Development
 We use poetry as a handy dependency management and packaging tool, which reads pyproject.toml to get specification for commands. poetry is a tool for command running automatization. If your environment does not support poetry, it can be installed as a python package with `pipx install poetry`. However, It's recommended to install isolated from the global Python environment, which prevents potential conflicts with other packages ([Installation on the official site](https://python-poetry.org/docs/#installing-with-the-official-installer:~:text=its%20own%20environment.-,Install%20Poetry,-The%20installer%20script)).
-
+For frontend development you will also require Bun - a JavaScript package manager, which you can install on Linux with Curl: `curl -fsSL https://bun.sh/install | bash`. For Windows installation or more information you can visit the [official website](https://bun.sh/).
 
 ### Prepare the Enviroment
 

Makefile

@@ -160,12 +160,16 @@ init_with_cc: ## Initiates a new project using cookiecutter
 	cookiecutter https://github.com/deeppavlov/chatsky-ui-template.git
 
 
-.PHONY: build_docs
-build_docs: install_backend_env ## Builds the docs
+.PHONY: build_api_docs
+build_api_docs: install_backend_env ## Builds the docs
 	cd ${BACKEND_DIR} && \
 	. `poetry env info --path`/bin/activate && \
 	cd ../docs && make html && cd ../
 
+.PHONY: build_ui_docs
+build_ui_docs: install_frontend_env ## Builds the docs
+	cd docs/ui-docs && bun run build && cd ../
+
 .PHONY: style
 style: ## Formats code using black and checks with flake8 and isort
 	cd ${BACKEND_DIR} && poetry install --with lint

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

@@ -14,7 +14,18 @@
 
 
 async def _stop_process(id_: int, process_manager: ProcessManager, process="run") -> Dict[str, str]:
-    """Stops a `build` or `run` process with the given id."""
+    """Stops a `build` or `run` process with the given id.
+
+    Args:
+        id_ (int): The id of the process to stop.
+        process_manager (ProcessManager): The process manager containing the process with the given id.
+
+    Raises:
+        HTTPException: With status code 404 if the process with the given id is not found.
+
+    Returns:
+        {"status": "ok"}: in case of stopping a process successfully.
+    """
 
     try:
         await process_manager.stop(id_)
@@ -29,7 +40,18 @@ async def _stop_process(id_: int, process_manager: ProcessManager, process="run"
 
 
 async def _check_process_status(id_: int, process_manager: ProcessManager) -> Dict[str, str]:
-    """Checks the status of a `build` or `run` process with the given id."""
+    """Checks the status of a `build` or `run` process with the given id.
+
+    Args:
+        id_ (int): The id of the process to check.
+        process_manager (ProcessManager): The process manager containing the process with the given id.
+
+    Raises:
+        HTTPException: With status code 404 if the process is not found.
+
+    Returns:
+        {"status": response}: with `response` being the status of the given process.
+    """
     if id_ not in process_manager.processes:
         raise HTTPException(
             status_code=status.HTTP_404_NOT_FOUND,
@@ -45,13 +67,15 @@ async def start_build(
     background_tasks: BackgroundTasks,
     build_manager: BuildManager = Depends(deps.get_build_manager),
 ) -> Dict[str, Union[str, int]]:
-
     """Starts a `build` process with the given preset.
 
     This runs a background task to check the status of the process every 2 seconds.
 
     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 keeps checking
+            the status of the build process in the background after returning a response.
+        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 +94,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 +129,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.
+
+    Args:
+        build_manager (BuildManager): The process manager dependency to check the graph with.
+
+    Returns:
+        {"status": "ok", "data": True}: in case the graph was changed since last build.
+        {"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 +155,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 +179,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 +204,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 keeps checking
+            the status of the run process in the background after returning a response.
+        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 +242,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 +269,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 +290,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)
@@ -246,6 +305,11 @@ async def respond(
     user_id: str,
     user_message: str,
 ):
+    """Sends a response to "http://localhost:chatsky_port/chat".
+
+    Raises:
+        HTTPException: With status code 503 if the service is unavailable.
+    """
     async with AsyncClient() as client:
         try:
             response = await client.post(

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,17 @@
 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."""
+    """Gets the flows by reading the frontend_flows.yaml file. If the build_id isn't passed
+    then it will return the last saved (committed) flow.
+
+    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:
@@ -44,9 +54,17 @@ async def flows_get(
 
 @router.post("/")
 async def flows_post(
-    flows: Dict[str, Union[list, dict]], build_manager: BuildManager = Depends(get_build_manager)
+    flows: Dict[str, Union[str, Dict[str, Union[list, dict]]]], build_manager: BuildManager = Depends(get_build_manager)
 ) -> Dict[str, str]:
-    """Write the flows to the frontend_flows.yaml file."""
+    """Writes the flows to the frontend_flows.yaml file. Then commit changes to git without a tag.
+
+    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)
@@ -58,7 +76,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]:
+    """Writes 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)
 

backend/chatsky_ui/api/deps.py

@@ -4,6 +4,7 @@
 
 
 def get_build_manager() -> BuildManager:
+    """Returns the only used instance of `build` process manager."""
     build_manager.set_logger()
     build_manager.set_bot_repo_manager()
     build_manager.set_graph_repo_manager()
@@ -14,6 +15,7 @@ def get_build_manager() -> BuildManager:
 
 
 def get_run_manager() -> RunManager:
+    """Returns the only used instance of `run` process manager."""
     run_manager.set_logger()
     run_manager.set_bot_repo_manager()
     run_manager.set_graph_repo_manager()

backend/chatsky_ui/services/json_converter/base_converter.py

@@ -2,9 +2,15 @@
 
 
 class BaseConverter(ABC):
+    """Base class for converting frontend's logic components and implementations
+    of Chatsky core classes into actual Chatsky classes.
+    """
+
     def __call__(self, *args, **kwargs):
+        """Calling any `BaseConverter` will call `_convert` and thus return a converted object."""
         return self._convert()
 
     @abstractmethod
     def _convert(self):
+        """Returns a fully converted object."""
         raise NotImplementedError