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>

CHANGELOG.md

@@ -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
 

nc_py_api/ex_app/__init__.py

@@ -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

nc_py_api/ex_app/misc.py

@@ -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())

nc_py_api/ex_app/providers/speech_to_text.py

@@ -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},
+            )

nc_py_api/ex_app/providers/text_processing.py

@@ -84,7 +84,7 @@ def report_result(self, task_id: int, result: str = "", error: str = "") -> None
             self._session.ocs(
                 "PUT",
                 f"{self._session.ae_url}/{self._ep_suffix}",
-                params={"taskId": task_id, "result": result, "error": error},
+                json={"taskId": task_id, "result": result, "error": error},
             )
 
 
@@ -133,5 +133,5 @@ async def report_result(self, task_id: int, result: str = "", error: str = "") -
             await self._session.ocs(
                 "PUT",
                 f"{self._session.ae_url}/{self._ep_suffix}",
-                params={"taskId": task_id, "result": result, "error": error},
+                json={"taskId": task_id, "result": result, "error": error},
             )

tests/actual_tests/speech2text_provider_test.py

@@ -54,3 +54,14 @@ async def test_speech2text_provider_async(anc_app):
     await anc_app.providers.speech_to_text.unregister(result2.name, not_fail=False)
     assert await anc_app.providers.speech_to_text.get_entry(result2.name) is None
     assert str(result).find("name=") != -1
+
+
+@pytest.mark.require_nc(major=29)
+def test_speech2text_provider_fail_report(nc_app):
+    nc_app.providers.speech_to_text.report_result(999999)
+
+
+@pytest.mark.asyncio(scope="session")
+@pytest.mark.require_nc(major=29)
+async def test_speech2text_provider_fail_report_async(anc_app):
+    await anc_app.providers.speech_to_text.report_result(999999)