bytefight-core 0.1.0__tar.gz

bytefight_core-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Jaeheon Shim
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

bytefight_core-0.1.0/PKG-INFO

@@ -0,0 +1,15 @@
+Metadata-Version: 2.4
+Name: bytefight-core
+Version: 0.1.0
+Summary: The SDK for the ByteFight competition platform
+Author: Jaeheon Shim
+Author-email: Jaeheon Shim <jaeheon.shim@gatech.edu>
+License-Expression: MIT
+License-File: LICENSE
+Requires-Dist: pydantic>=2.0
+Requires-Python: >=3.12
+Description-Content-Type: text/markdown
+
+# bytefight-core
+
+The SDK for the ByteFight competition platform

bytefight_core-0.1.0/README.md

@@ -0,0 +1,3 @@
+# bytefight-core
+
+The SDK for the ByteFight competition platform

bytefight_core-0.1.0/pyproject.toml

@@ -0,0 +1,18 @@
+[project]
+name = "bytefight-core"
+version = "0.1.0"
+description = "The SDK for the ByteFight competition platform"
+readme = "README.md"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [
+    { name = "Jaeheon Shim", email = "jaeheon.shim@gatech.edu" }
+]
+requires-python = ">=3.12"
+dependencies = [
+    "pydantic>=2.0",
+]
+
+[build-system]
+requires = ["uv_build>=0.11.21,<0.12.0"]
+build-backend = "uv_build"

bytefight_core-0.1.0/src/bytefight_core/__init__.py

@@ -0,0 +1,28 @@
+from importlib.metadata import version
+
+from bytefight_core.interface import (Action, GameController, GameResult,
+                                      GameResultFile, MatchStatus, Obs,
+                                      PlayerController, PlayerHandle)
+from bytefight_core.local import LocalPlayerHandle
+from bytefight_core.protocol import (StdioPlayerHandle,
+                                     isolate_protocol_stream, model_args,
+                                     run_agent, serve_stdio)
+
+__all__ = [
+    "Action",
+    "Obs",
+    "MatchStatus",
+    "GameResult",
+    "GameResultFile",
+    "PlayerController",
+    "PlayerHandle",
+    "GameController",
+    "LocalPlayerHandle",
+    "StdioPlayerHandle",
+    "serve_stdio",
+    "run_agent",
+    "isolate_protocol_stream",
+    "model_args",
+]
+
+__version__ = version("bytefight-core")

bytefight_core-0.1.0/src/bytefight_core/interface.py

@@ -0,0 +1,57 @@
+from abc import ABC, abstractmethod
+from dataclasses import dataclass, field
+from enum import Enum
+from pathlib import Path
+from typing import Generic, TypeVar
+
+from pydantic import BaseModel
+
+Action = TypeVar("Action", bound=BaseModel)
+Obs = TypeVar("Obs", bound=BaseModel)
+
+
+class MatchStatus(Enum):
+    CREATED = "created"
+    SCHEDULING = "scheduling"
+    WAITING = "waiting"
+    IN_PROGRESS = "in_progress"
+    FAILED = "failed"
+    PLAYER_A_WIN = "team_a_win"
+    PLAYER_B_WIN = "team_b_win"
+    DRAW = "draw"
+    SUBMISSION_VALID = "submission_valid"
+    SUBMISSION_INVALID = "submission_invalid"
+
+
+@dataclass(frozen=True)
+class GameResultFile:
+    path: str | Path
+    slug: str
+    visibility: str
+    team_uuid: str | None = None
+
+
+@dataclass
+class GameResult:
+    status: MatchStatus
+    files: list[GameResultFile] = field(default_factory=list)
+
+    
+class GameController(ABC, Generic[Action, Obs]):
+    @abstractmethod
+    def play(self) -> GameResult: ...
+
+    @abstractmethod
+    def validate(self) -> GameResult: ...
+
+
+class PlayerHandle(ABC, Generic[Action, Obs]):
+    @abstractmethod
+    def exchange(self, obs: Obs, *, timeout: float | None = None) -> Action | None: ...
+
+    def close(self) -> None: ...
+
+
+class PlayerController(ABC, Generic[Action, Obs]):
+    @abstractmethod
+    def play(self, obs: Obs) -> Action: ...

bytefight_core-0.1.0/src/bytefight_core/local.py

@@ -0,0 +1,21 @@
+from bytefight_core.interface import (Action, Obs, PlayerController,
+                                      PlayerHandle)
+
+
+class LocalPlayerHandle(PlayerHandle[Action, Obs]):
+    def __init__(
+        self,
+        controller: PlayerController[Action, Obs],
+        *,
+        raise_errors: bool = False,
+    ):
+        self._controller = controller
+        self._raise_errors = raise_errors
+
+    def exchange(self, obs: Obs, *, timeout: float | None = None) -> Action | None:
+        try:
+            return self._controller.play(obs)
+        except Exception:
+            if self._raise_errors:
+                raise
+            return None

bytefight_core-0.1.0/src/bytefight_core/protocol.py

@@ -0,0 +1,91 @@
+import os
+import select
+import sys
+from typing import IO, Any, get_args, get_origin
+
+from bytefight_core.interface import (Action, Obs, PlayerController,
+                                      PlayerHandle)
+from pydantic import BaseModel
+
+
+def model_args(
+    controller: PlayerController[Action, Obs] | type[PlayerController[Action, Obs]],
+) -> tuple[type[Any], type[Any]]:
+    cls = controller if isinstance(controller, type) else type(controller)
+    for klass in cls.__mro__:
+        for base in getattr(klass, "__orig_bases__", ()):
+            if get_origin(base) is PlayerController:
+                args = get_args(base)
+                if len(args) == 2 and all(
+                    isinstance(a, type) and issubclass(a, BaseModel) for a in args
+                ):
+                    return args  # type: ignore[return-value]
+    raise TypeError(
+        f"{cls.__name__} must subclass "
+        "PlayerController[YourAction, YourObs] with concrete pydantic models so the "
+        "protocol knows how to parse observations"
+    )
+
+
+class StdioPlayerHandle(PlayerHandle[Action, Obs]):
+    def __init__(
+        self,
+        stdin: IO[str],
+        stdout: IO[str],
+        action_type: type[Action],
+    ):
+        self._stdin = stdin
+        self._stdout = stdout
+        self._action_type = action_type
+
+    def exchange(self, obs: Obs, *, timeout: float | None = None) -> Action | None:
+        try:
+            self._stdin.write(obs.model_dump_json() + "\n")
+            self._stdin.flush()
+            if timeout is not None:
+                ready, _, _ = select.select([self._stdout], [], [], timeout)
+                if not ready:
+                    return None
+            line = self._stdout.readline()
+            if not line:
+                return None
+            return self._action_type.model_validate_json(line)
+        except (OSError, ValueError):
+            return None
+
+    def close(self) -> None:
+        self._stdin.close()
+        self._stdout.close()
+
+
+def serve_stdio(
+    controller: PlayerController[Action, Obs],
+    stdin: IO[str],
+    stdout: IO[str],
+    obs_type: type[Obs] | None = None,
+) -> None:
+    model = obs_type if obs_type is not None else model_args(controller)[1]
+    for line in stdin:
+        obs = model.model_validate_json(line)
+        action = controller.play(obs)
+        stdout.write(action.model_dump_json() + "\n")
+        stdout.flush()
+
+
+def isolate_protocol_stream() -> IO[str]:
+    sys.stdout.flush()
+    protocol_out = os.fdopen(os.dup(1), "w", buffering=1)
+    os.dup2(2, 1)
+    sys.stdout = sys.stderr
+    return protocol_out
+
+
+def run_agent(
+    controller: PlayerController[Action, Obs],
+    *,
+    stdin: IO[str] | None = None,
+    stdout: IO[str] | None = None,
+    obs_type: type[Obs] | None = None,
+) -> None:
+    protocol_out = stdout if stdout is not None else isolate_protocol_stream()
+    serve_stdio(controller, stdin or sys.stdin, protocol_out, obs_type)