Implement /api/external_engine endpoints

CHANGELOG.rst

@@ -4,14 +4,20 @@ Changelog
 To be released
 --------------
 
-* Add ``
+* Add::
+    client.external_engine.get
+    client.external_engine.get_by_id
+    client.external_engine.create
+    client.external_engine.update
+    client.external_engine.delete
+* Add::
     client.tournaments.edit_swiss
     client.tournaments.get_swiss
     client.tournaments.join_swiss
     client.tournaments.stream_swiss_results
     client.tournaments.schedule_swiss_next_round
     client.tournaments.terminate_swiss
-    client.tournaments.withdraw_swiss``
+    client.tournaments.withdraw_swiss
 * Add ``client.puzzles.create_race``
 * Add ``client.users.get_by_autocomplete``
 

README.rst

@@ -124,6 +124,12 @@ Most of the API is available:
     client.explorer.get_player_games
     client.explorer.stream_player_games
 
+    client.external_engine.get
+    client.external_engine.get_by_id
+    client.external_engine.create
+    client.external_engine.update
+    client.external_engine.delete
+
     client.games.export
     client.games.export_ongoing_by_player
     client.games.export_by_player

berserk/clients/__init__.py

@@ -22,6 +22,7 @@
 from .tablebase import Tablebase
 from .opening_explorer import OpeningExplorer
 from .bulk_pairings import BulkPairings
+from .external_engine import ExternalEngine
 
 __all__ = [
     "Client",
@@ -43,6 +44,7 @@
     "TV",
     "Tablebase",
     "BulkPairings",
+    "ExternalEngine",
 ]
 
 
@@ -67,6 +69,7 @@ class Client(BaseClient):
     - :class:`tv <berserk.clients.TV>` - get information on tv channels and games
     - :class:`tablebase <berserk.clients.Tablebase>` - lookup endgame tablebase
     - :class:`bulk_pairings <berserk.clients.BulkPairing>` - manage bulk pairings
+    - :class: `external_engine <berserk.clients.ExternalEngine>` - manage external engines
 
     :param session: request session, authenticated as needed
     :param base_url: base API URL to use (if other than the default)
@@ -106,3 +109,4 @@ def __init__(
         self.tablebase = Tablebase(session, tablebase_url)
         self.opening_explorer = OpeningExplorer(session, explorer_url)
         self.bulk_pairings = BulkPairings(session, base_url)
+        self.external_engine = ExternalEngine(session, base_url)

berserk/clients/external_engine.py

@@ -0,0 +1,114 @@
+from __future__ import annotations
+
+from typing import List, cast
+
+from .base import BaseClient
+
+
+class ExternalEngine(BaseClient):
+    """Client for external engine related endpoints."""
+
+    def get(self) -> List[ExternalEngine]:
+        """Lists all external engines that have been registered for the user, and the credentials required to use them.
+
+        Requires OAuth2 authorization.
+
+        :return: info about the external engines
+        """
+        path = "/api/external-engine"
+        return cast(List[ExternalEngine], self._r.get(path))
+
+    def get_by_id(self, engine_id: str) -> ExternalEngine:
+        """Get properties and credentials of an external engine.
+
+        Requires OAuth2 authorization.
+
+        :param engine_id: external engine ID
+        :return: info about the external engine
+        """
+        path = f"/api/external-engine/{engine_id}"
+        return cast(ExternalEngine, self._r.get(path))
+
+    def create(
+        self,
+        name: str,
+        max_threads: int,
+        max_hash_table_size: int,
+        default_depth: int,
+        provider_secret: str,
+        variants: List[str] | None = None,
+        provider_data: str | None = None,
+    ) -> ExternalEngine:
+        """Registers a new external engine for the user.
+
+        Requires OAuth2 authorization.
+
+        :param name: engine display name
+        :param max_threads: maximum number of available threads
+        :param max_hash_table_size: maximum available hash table size, in MiB
+        :param default_depth: estimated depth of normal search
+        :param provider_secret: random token that used to wait for analysis requests and provide analysis
+        :param variants: list of supported chess variants
+        :param provider_data: arbitrary data that engine provider can use for identification or bookkeeping
+        :return: info about the external engine
+        """
+        path = "/api/external-engine"
+        payload = {
+            "name": name,
+            "maxThreads": max_threads,
+            "maxHash": max_hash_table_size,
+            "defaultDepth": default_depth,
+            "variants": variants,
+            "providerSecret": provider_secret,
+            "providerData": provider_data,
+        }
+        return cast(ExternalEngine, self._r.post(path=path, payload=payload))
+
+    def update(
+        self,
+        engine_id: str,
+        name: str,
+        max_threads: int,
+        max_hash_table_size: int,
+        default_depth: int,
+        provider_secret: str,
+        variants: List[str] | None = None,
+        provider_data: str | None = None,
+    ) -> ExternalEngine:
+        """Updates the properties of an external engine.
+
+        Requires OAuth2 authorization.
+
+        :param engine_id: engine ID
+        :param name: engine display name
+        :param max_threads: maximum number of available threads
+        :param max_hash_table_size: maximum available hash table size, in MiB
+        :param default_depth: estimated depth of normal search
+        :param provider_secret: random token that used to wait for analysis requests and provide analysis
+        :param variants: list of supported chess variants
+        :param provider_data: arbitrary data that engine provider can use for identification or bookkeeping
+        :return: info about the external engine
+        """
+        path = f"/api/external-engine/{engine_id}"
+        payload = {
+            "name": name,
+            "maxThreads": max_threads,
+            "maxHash": max_hash_table_size,
+            "defaultDepth": default_depth,
+            "variants": variants,
+            "providerSecret": provider_secret,
+            "providerData": provider_data,
+        }
+        return cast(
+            ExternalEngine, self._r.request(method="PUT", path=path, payload=payload)
+        )
+
+    def delete(self, engine_id: str) -> None:
+        """Unregisters an external engine.
+
+        Requires OAuth2 authorization.
+
+        :param engine_id: engine ID
+        """
+        path = f"/api/external-engine/{engine_id}"
+        self._r.request("DELETE", path)

berserk/types/__init__.py

@@ -2,7 +2,7 @@
 
 from .account import AccountInformation, Perf, Preferences, Profile, StreamerInfo
 from .bulk_pairings import BulkPairing, BulkPairingGame
-from .common import ClockConfig, LightUser, OnlineLightUser
+from .common import ClockConfig, ExternalEngine, LightUser, OnlineLightUser
 from .puzzles import PuzzleRace
 from .opening_explorer import (
     OpeningExplorerRating,
@@ -19,6 +19,7 @@
     "BulkPairing",
     "BulkPairingGame",
     "ClockConfig",
+    "ExternalEngine",
     "LightUser",
     "OnlineLightUser",
     "CurrentTournaments",

berserk/types/common.py

@@ -12,6 +12,27 @@ class ClockConfig(TypedDict):
     increment: int
 
 
+class ExternalEngine(TypedDict):
+    # Engine ID
+    id: str
+    # Engine display name
+    name: str
+    # Secret token that can be used to request analysis
+    clientSecret: str
+    # User this engine has been registered for
+    userId: str
+    # Max number of available threads
+    maxThreads: int
+    # Max available hash table size, in MiB
+    maxHash: int
+    # Estimated depth of normal search
+    defaultDepth: int
+    # List of supported chess variants
+    variants: str
+    # Arbitrary data that engine provider can use for identification or bookkeeping
+    providerData: NotRequired[str]
+
+
 Color: TypeAlias = Literal["white", "black"]
 
 GameType: TypeAlias = Literal[