Speech2txt provider API rework (#202)

Changes proposed in this pull request:

* Example was rewritten, and now has separate repo:
https://github.com/cloud-py-api/speech2text_provider
 * added `report_result` method
* added new `get_model_path` function to easy use hugging models in
Providers

---------

Signed-off-by: Alexander Piskun <bigcat88@icloud.com>

Author: bigcat88

.run/Speech2TxtProvider (last).run.xml

@@ -2,7 +2,7 @@
 
 All notable changes to this project will be documented in this file.
 
-## [0.8.0 - 2024-01-xx]
+## [0.8.0 - 2024-01-12]
 
 ### Added
 

CHANGELOG.md

@@ -8,6 +8,6 @@
     set_handlers,
     talk_bot_app,
 )
-from .misc import persistent_storage, verify_version
+from .misc import get_model_path, persistent_storage, verify_version
 from .ui.files_actions import UiActionFileInfo
 from .uvicorn_fastapi import run_app

examples/as_app/speech2text/Dockerfile

@@ -43,3 +43,10 @@ def verify_version(finalize_update: bool = True) -> tuple[str, str] | None:
                 version_file.write(os.environ["APP_VERSION"])
                 version_file.truncate()
     return r
+
+
+def get_model_path(model_name: str) -> str:
+    """Wrapper around hugging_face's ``snapshot_download`` to return path to downloaded model directory."""
+    from huggingface_hub import snapshot_download  # noqa isort:skip pylint: disable=C0415 disable=E0401
+
+    return snapshot_download(model_name, local_files_only=True, cache_dir=persistent_storage())

examples/as_app/speech2text/Makefile

@@ -1,8 +1,9 @@
 """Nextcloud API for declaring SpeechToText provider."""
 
+import contextlib
 import dataclasses
 
-from ..._exceptions import NextcloudExceptionNotFound
+from ..._exceptions import NextcloudException, NextcloudExceptionNotFound
 from ..._misc import require_capabilities
 from ..._session import AsyncNcSessionApp, NcSessionApp
 
@@ -70,6 +71,16 @@ def get_entry(self, name: str) -> SpeechToTextProvider | None:
         except NextcloudExceptionNotFound:
             return None
 
+    def report_result(self, task_id: int, result: str = "", error: str = "") -> None:
+        """Report results of speech to text task to Nextcloud."""
+        require_capabilities("app_api", self._session.capabilities)
+        with contextlib.suppress(NextcloudException):
+            self._session.ocs(
+                "PUT",
+                f"{self._session.ae_url}/{self._ep_suffix}",
+                json={"taskId": task_id, "result": result, "error": error},
+            )
+
 
 class _AsyncSpeechToTextProviderAPI:
     """API for registering Speech2Text providers."""
@@ -107,3 +118,13 @@ async def get_entry(self, name: str) -> SpeechToTextProvider | None:
             )
         except NextcloudExceptionNotFound:
             return None
+
+    async def report_result(self, task_id: int, result: str = "", error: str = "") -> None:
+        """Report results of speech to text task to Nextcloud."""
+        require_capabilities("app_api", await self._session.capabilities)
+        with contextlib.suppress(NextcloudException):
+            await self._session.ocs(
+                "PUT",
+                f"{self._session.ae_url}/{self._ep_suffix}",
+                json={"taskId": task_id, "result": result, "error": error},
+            )