Add improved documentation

.dockerignore

@@ -10,6 +10,9 @@ spec/
 .venv-pyserver
 .venv-pyclient
 
+# Compiled elm files
+elo_tracker/static/elo_tracker.js
+
 # ---> Elm
 # elm-package generated files
 elm-stuff

.gitignore

@@ -2,6 +2,9 @@
 .venv-pyserver
 .venv-pyclient
 
+# Compiled elm files
+elo_tracker/static/elo_tracker.js
+
 # ---> Elm
 # elm-package generated files
 elm-stuff

README.md

@@ -1,15 +1,24 @@
 # Bot-Man-Toe
 
-Bot-Man-Toe is an attempt to create a way for players to play games against
+Write a script that plays tic-tac-toe, and see how well it performs against
-themselves, other players, or self-trained AI players.
+other programs!
 
-## Technology stack
+- [🚀 Write your own agent](agents/README.md)
+- [🖊 Compare how well your agent performs](/elo_tracker/README.md)
+- [🌐 Publish your agent to the internet](/pyserver/README.md)
 
-Counterintuitively, the **servers** are participants to a game. The **clients**
+## Get started
-are programs or browsers that mediate matches between servers.
 
-## More
+1. Clone this repository.
+2. Run `python client.py` in the terminal and let two random agents play
+    against each other.
+3. Copy the example agent and [create your own](agents/README.md).
+4. Play against the AgentOfChaos while you improve your strategy.
+5. Publish your agent. _(optional)_
+6. Compare it against others with the Elo tracker. _(optional)_
 
-- The discovery contract is documented in `spec/README.md`.
+
-- Python client helpers live under `pyclient/`.
+## Links
-- Python server helpers live under `pyserver/`.
+
+- [📜 API specification](pyserver/spec.md)
+- [🏆 Online ELO tracker](https://elo.noordstar.me/)

agents/README.md

@@ -0,0 +1,70 @@
+# 🚀 Write your own agent!
+
+An **agent** is a Python class that knows how to play one or more games.
+
+Don't worry about writing a perfect strategy. Start with something that works,
+print the incoming game state, and improve it one step at a time.
+
+## Quick start
+
+1. Copy `example.py`.
+2. Rename the file and the `ExampleAgent` class.
+3. Update the agent's name, author and version.
+4. Implement `play_tic_tac_toe()`.
+5. Import your agent in `client.py` and let it play a game.
+
+That's enough to get started.
+
+## Understanding the game
+
+Whenever your agent has to make a move, it receives the current game state as
+a Python dictionary.
+
+Start by printing it:
+
+```py
+print(payload)
+```
+
+Run a few games and watch how the payload changes after every move. Once you
+understand what you're receiving, you can start writing your own strategy!
+
+Your function should return:
+
+```py
+{"move": 7}
+```
+
+where the number is the square you want to play.
+
+## Testing your agent
+
+Open [client.py](/client.py) and replace one of the players with your own agent.
+For example:
+
+```py
+from agents.my_agent import MyAgent
+from agents.chaos import AgentOfChaos
+
+players = [
+    MyAgent(),
+    AgentOfChaos(),
+]
+```
+
+The repository includes `AgentOfChaos`, a very simple opponent that plays
+random moves. It's useful for testing your own agent while you're developing it.
+
+>  ⚠️ Don't try to build the perfect player immediately! Agents are easy to
+> improve while you test against other agents. Plus, imperfect agents are
+> typically the most interesting.
+
+Run the client, inspect the output, tweak your algorithm, and repeat. You don't
+need to understand the rest of the project before you can start experimenting.
+
+## What's next?
+
+Once you're happy with your agent, you can:
+
+- [🖊 Compare your agent against other agents with the ELO tracker](/elo_tracker/README.md)
+- [🌐 Publish your agent so other people can play against it](/pyserver/README.md)

agents/__init__.py

@@ -0,0 +1,20 @@
+"""
+    Agents are players that can participate in a game. THey contain a unified
+    API that allows other systems to apply to them for communication.
+    For example:
+
+    1. The PyClient can locally run a game with agents as participants.
+    2. A PyServer can host a web server and asks a specific agent to respond.
+"""
+
+from .agent import Agent
+from .chaos import AgentOfChaos
+from .mute import MuteAgent
+from .remote import RemoteAgent
+
+__all__ = [
+    "Agent",
+    "AgentOfChaos",
+    "MuteAgent",
+    "RemoteAgent",
+]

agents/agent.py

@@ -0,0 +1,134 @@
+"""
+    The agent module hosts the base class of all agents. It dictates how
+    agents are expected to behave.
+"""
+
+from __future__ import annotations
+
+from typing import Any, Callable
+
+# Communication type that the players communicate in
+Payload = dict[str, Any]
+
+# Function that the agent is expected to communicate with.
+# The ActionFunction takes a Payload as input and returns a Payload of its own.
+ActionFunction = Callable[[Payload], Payload]
+
+GameInfo = tuple[Payload, dict[str, ActionFunction]]
+
+class Agent:
+    """
+        Base class for all agents to communicate in.
+    """
+
+    # Local variables
+    author : str
+    name : str
+    profile : Payload
+    registered_games : dict[str, tuple[Payload, dict[str, ActionFunction]]]
+    version : str | None
+
+    def __init__(
+        self,
+        name : str,
+        author : str,
+        version : str | None = None,
+        profile : Payload = {},
+    ) -> None:
+        """
+            Create an instance of the agent.
+
+            Note that the base class expects quite a lot of variables for the
+            initialization, whereas the subclasses are expected to require
+            no inputs for initialization. It is the subclasses' responsibility
+            to override the current function by inserting its own values.
+
+            :param name: String value giving the player a name.
+            :type name: str
+            :param author: String value representing the player's designer or programmer.
+            :type author: str
+            :param version: Version of the player, in case an update changes its behavior.
+            :type version: str | None
+            :param profile: Custom profile pertaining to the player.
+            :type profile: dict[str, Any]
+        """
+
+        # Register basic (required) variables
+        self.author = author
+        self.name = name
+        self.profile = profile
+        self.version = version
+
+        # Have the subclass register games
+        self.registered_games = {}
+
+    def add_game(
+        self,
+        name : str,
+        actions : dict[str, ActionFunction],
+        profile : Payload,
+        required_actions : list[str] = [],
+    ) -> None:
+        """
+            Add a new game to the player. Replaces any prior definition for the
+            game.
+
+            :param name: Game name
+            :type name: str
+            :param actions: Dictionary containing all actions the player is willing to take.
+            :type actions: dict[str, Callable[[dict[str, Any]], dict[str, Any]]]
+            :param profile: Custom profile describing some details about a game.
+            :type profile: dict[str, Any]
+            :param required_actions: Optional completeness check. If provided,
+                all required action names must exist in `actions` and map to
+                callables.
+            :type required_actions: list[str]
+            :raises AssertionError: Some of the required actions aren't present.
+        """
+
+        # Verify that all required actions exist
+        for ra in required_actions:
+            if ra not in actions.keys():
+                raise AssertionError(
+                    f"Missing required action `{ra}` in action mapping."
+                )
+        
+        self.registered_games[name] = ( profile, actions )
+    
+    def add_tic_tac_toe(
+        self,
+        on_move : ActionFunction,
+        profile : Payload = {},
+    ) -> None:
+        """
+            Convenience registration for the tic-tac-toe game.
+
+            :param on_move: Called function when the player is to make a move.
+            :type on_move: Callable[[dict[str, Any]], dict[str, Any]]
+            :param profile: Custom details to share about the game.
+            :type profile: dict[str, Any]
+        """
+        return self.add_game(
+            name="tic-tac-toe",
+            actions={"": on_move},
+            profile=profile,
+            required_actions=[""],
+        )
+    
+    def get_action(self, game : str, action : str | None) -> ActionFunction | None:
+        """
+            Get an action function for a given game, if it exists.
+
+            :param game: The name of the game.
+            :type game: str
+            :param action: The name of the action, or None if the game only has one action.
+            :type action: str | None
+            :return: The action with which the agent would like to act, if at all.
+            :rtype: Callable[[dict[str, Any]], dict[str, Any]] | None
+        """
+        _, actions = self.registered_games.get(game, ({}, {}))
+
+        if action is None:
+            return list(actions.values())[0] if len(actions) == 1 else None
+        else:
+            return actions.get(action, None)

agents/chaos.py

@@ -0,0 +1,64 @@
+"""
+    The agent of chaos is an agent that always attempts to return a random
+    response.
+
+    In most games, the Agent of chaos makes two considerations:
+
+    1. Which moves are valid? Since invalid moves fallback to "default" moves,
+        this can destabilize the probability distribution, making some moves
+        more likely to be chosen than others. As a result, we refrain from
+        "invalid" moves and take the effort to filter them out.
+    
+    2. What's a reasonable probability distribution? Sometimes, a uniform
+        distribution across all options doesn't make a lot of sense. For
+        example, imagine asking the agent every turn whether they want to
+        use their super duper special single-use ability, and leaving that to
+        a 50/50 call every turn. It feels much more random if such an ability
+        is more randomly used throughout the GAME, than to have every choice
+        be a uniformly distributed decision.
+"""
+
+from __future__ import annotations
+
+import random
+
+from .agent import Agent, Payload
+
+
+class AgentOfChaos(Agent):
+    """
+        The agent of chaos always aims to deliver a random response.
+    """
+
+    def __init__(self) -> None:
+        """
+            Create a new instance of the agent of chaos.
+        """
+        super().__init__(
+            name="Agent of chaos",
+            author="Bram",
+            version="1.0.1",
+            profile={
+                "me.noordstar.peanuts.is_ai": False,
+            },
+        )
+
+        self.add_tic_tac_toe(on_move=play_tic_tac_toe, profile={})
+
+
+def play_tic_tac_toe(payload : Payload) -> Payload:
+    """
+        In tic-tac-toe, the agent of chaos makes uniformly distributed choices
+        on unclaimed tiles.
+
+        :param payload: The incoming game state.
+        :type payload: dict[str, Any]
+        :return: The agent of chaos' random choice
+        :rtype: dict[str, Any]
+    """
+    options = [
+        int(k)
+        for k, v in dict(payload).items()
+        if k in "0123456789" and v == ""
+    ]
+    return { "move": random.choice(options) }

agents/example.py

@@ -0,0 +1,104 @@
+"""
+    This module contains an example agent that you can use to create your own!
+
+    Please copy this file, rename it, and then build it the way you see fit.
+"""
+
+from __future__ import annotations
+
+import random
+
+from .agent import Agent, Payload
+
+class ExampleAgent(Agent):
+    """
+        Describe here what your agent does and how it behaves! This will help
+        others understand how your agent works.
+    """
+
+    def __init__(self) -> None:
+        """
+            Create a custom instance of your agent. This function allows you
+            to define which games your agent can play.
+
+            You may add parameters to the function if your agent requires more
+            information to be able to operate.
+        """
+
+        super().__init__(
+            # Give your bot a name to display in leaderboards
+            name="MY super smart agent",
+
+            # Your name, to give you credit
+            author="Unknown programmer",
+
+            # Update the version to indicate the agent behaves differently.
+            # This will later allow you to compare different versions of your
+            # agent against one another.
+            version="1.0.0",
+
+            # Add extra custom information about the agent to this dictionary.
+            profile={},
+        )
+
+        # Indicate that you're willing to play tic-tac-toe
+        # Remove this if you don't want your bot to participate there.
+        self.add_tic_tac_toe(on_move=self.play_tic_tac_toe, profile={})
+
+    @staticmethod
+    def play_tic_tac_toe(payload : Payload) -> Payload:
+        """
+            Play a game of tic-tac-toe.
+
+            You receive a payload that looks like this:
+
+            {
+                "1": "X", "2": "",  "3": "O",
+                "4": "X", "5": "O", "6": "",
+                "7": "",  "8": "",  "9": "",
+                "your_token": "X"
+            }
+
+            And you're expected to return a response of which field you'd like to
+            place your piece in. For example, if you wish to place your token in
+            field 7, your response should look like this:
+
+            { "move": 7 }
+
+            The board is arranged as follows:
+
+             1 | 2 | 3
+            ---+---+---
+             4 | 5 | 6
+            ---+---+---
+             7 | 8 | 9
+            
+            :param payload: The incoming JSON that contains the game state.
+            :type payload: dict[str, Any]
+            :return: The move you wish to take.
+            :rtype: dict[str, Any]
+        """
+
+        # Try printing the payload to see what it looks like!
+        print(payload)
+
+        options = [ 1, 2, 3, 4, 5, 6, 7, 8, 9, ]
+
+        # 1. Try filtering out the impossible moves!
+        #    If an X or O was already placed at a field, remove it from the options
+
+        #
+
+        # 2. Try finding two in a row! If possible, you can try to place the third
+        #    item on the board and get 3 in a row.
+
+        #
+
+        # 3. Perhaps you can block the opponent from getting 3 in a row?
+
+        #
+
+        # Now, pick any of the remaining options.
+        # This is just a simple implementation. Naturally, you're welcome to try
+        # your own algorithm.
+        return { "move": random.choice(options) }

agents/mute.py

@@ -0,0 +1,54 @@
+"""
+    The mute agent is a proof-of-concept agent of an agent that simply doesn't
+    respond - it always responds with an empty object.
+
+    This is the simplest agent to implement, and it can be used as a test to
+    make sure that the "default" move can be picked properly each turn.    
+"""
+
+from __future__ import annotations
+
+from .agent import ActionFunction, Agent, Payload
+
+def respond_mute(payload : Payload) -> Payload:
+    """
+        Standard response from the mute. Returns an empty object, always.
+
+        :param payload: Incoming game state.
+        :type payload: dict[str, Any]
+        :return: The empty object.
+        :rtype: dict[str, Any]
+    """
+    return {}
+
+class MuteAgent(Agent):
+    """
+        The mute agent class refuses to respond to any incoming game states,
+        and simply responds with an empty dictionary. For most games,
+        this means that the mute player takes the "default" option as a result
+        of not responding.
+    """
+
+    def __init__(self) -> None:
+        """
+            Create a new instance of the mute agent.
+        """
+        super().__init__(
+            name="Mute",
+            author="Bram",
+            version="1.0.1",
+            profile={
+                "me.noordstar.peanuts.is_ai": False,
+            },
+        )
+
+    def get_action(self, game: str, action: str | None) -> ActionFunction:
+        """
+            Return the mute response for any game or action.
+
+            :param game: The game that the mute ignores.
+            :type game: str
+            :param action: The action that the mute ignores.
+            :type action: str
+        """
+        return respond_mute

agents/remote.py

@@ -0,0 +1,99 @@
+"""
+    The remote agent is the agent that is accessible on the internet.
+
+    The common implementation of the back-end is the PyClient, although the
+    remote agent communicates through an API so the agent is 
+    implementation-agnostic.
+"""
+
+from __future__ import annotations
+from typing import Any, Callable
+
+import requests
+
+from .agent import Agent, Payload
+
+class RemoteAgent(Agent):
+    """
+        The RemoteAgent is the agent that is remotely accessible on an external
+        URL through the specified protocol.
+    """
+
+    url : str
+
+    def __init__(self, url : str, timeout : float = 1.0) -> None:
+        """
+            Create a new instance of the remote agent.
+
+            :param url: URL at which the agent can be accessed.
+            :type url: str
+            :param timeout: The maximum time the client is allowed to respond.
+            :type timeout: float
+            :raises requests.HTTPError: The server could not be reached.
+            :raises ValueError: The server returned an invalid response.
+        """
+        self.url = url.strip("/")
+        self.timeout = timeout
+    
+        # Get discovery from URL
+        response = requests.get(self.url.strip("/") + "/", timeout=self.timeout)
+        response.raise_for_status()
+        content = response.json()
+
+        if not isinstance(content, dict):
+            raise ValueError(
+                "Remote agent's discovery response must be a JSON object."
+            )
+        
+        raw_author = content.get("author", content.get("me.noordstar.peanuts.author", ""))
+        raw_name = content.get("name", "")
+        raw_version = content.get("version", content.get("me.noordstar.peanuts.agent.version", None))
+
+        # Initialize agent based on given information
+        super().__init__(
+            author="" if raw_author is None else str(raw_author),
+            name="" if raw_name is None else str(raw_name),
+            version=None if raw_version is None else str(raw_version),
+            profile=content,
+        )
+
+        games = content.get("games")
+        if isinstance(games, dict):
+            if "tic-tac-toe" in games:
+                self.add_tic_tac_toe(
+                    on_move=lambda x : self.poll("tic-tac-toe", "", x),
+                    profile=games["tic-tac-toe"],
+                )
+
+    def get_action(self, game: str, action: str | None) -> Callable[[dict[str, Any]], dict[str, Any]] | None:
+        """
+            Get an action function for any given game.
+
+            :param game: The name of the game.
+            :type game: str
+            :param action: The name of the action, or None if the game only has one action.
+            :type action: str | None
+            :return: The action with which the agent would like to act, if at all.
+            :rtype: Callable[[dict[str, Any]], dict[str, Any]] | None
+        """
+        return lambda x : self.poll(game=game, action=action or "", payload=x)
+
+    def poll(
+        self,
+        game : str,
+        action : str,
+        payload : Payload
+    ) -> Payload:
+        """
+            Inquire the remote agent for a response.
+        """
+        url = "/".join([self.url, game.strip("/"), action.strip("/")]).strip("/")
+
+        try:
+            response = requests.get(url, json=payload, timeout=self.timeout)
+            response.raise_for_status()
+            content = response.json()
+        except (requests.ConnectTimeout, requests.RequestException, requests.HTTPError, ValueError):
+            return {}
+        else:
+            return content if isinstance(content, dict) else {}

client.py

@@ -23,8 +23,14 @@ from __future__ import annotations
 import json
 import pyclient
 
-from pyclient import Agent, PyClient
+# Import your game(s) here
 from pyclient.games import TicTacToe
+# ...
+
+# Import your agent(s) here
+from agents import Agent, AgentOfChaos
+# from agents.my_agent import MyAgent
+# ...
 
 def main() -> int:
     """
@@ -33,22 +39,29 @@ def main() -> int:
         :return: Exit code
         :rtype: int
     """
-    c = PyClient(debug=False)
 
+    # Start the game engine
+    c = pyclient.PyClient(debug=True)
+
+    # Mix and match any agents you'd like.
+    # During development it's usually easiest to play against AgentOfChaos().
     players : list[Agent] = [
-        Agent.from_url(url="https://bmt001.noordstar.me/"),
+        AgentOfChaos(),
-        Agent.from_url(url="https://bmt001.noordstar.me/"),
+        AgentOfChaos(),
     ]
 
-    out = c.play_game(
+    # Play a given game with your players
+    result = c.play_game(
         players=players,
         start=TicTacToe.empty(),
     )
 
-    inspect_game(out)
+    # Print the game results to the terminal!
+    inspect_game(result)
 
     return 0
 
+
 def inspect_game(game : pyclient.GameReplay) -> None:
     """
         Print a diagnostic of a played game to the terminal.
@@ -88,5 +101,6 @@ def inspect_game(game : pyclient.GameReplay) -> None:
     print(f"Total turns taken: {len(game.turns)}")
     print(f"Result: {final_state.winner()}")
 
+
 if __name__ == "__main__":
     raise SystemExit(main())

elm/Api/Elo.elm

@@ -0,0 +1,156 @@
+module Api.Elo exposing
+    ( EloStat
+    , HealthCheck
+    , Leaderboard
+    , Match
+    , Participant
+    , Players
+    , getHealth
+    , getLeaderboard
+    , getMatches
+    , getPlayers
+    )
+
+{-|
+
+
+# ELO API
+
+This module contains functions to address the API of the ELO tracker.
+
+-}
+
+import Http
+import Json.Decode as D
+
+
+type alias EloStat =
+    { draws : Int
+    , elo : Int
+    , losses : Int
+    , name : String
+    , url : String
+    , wins : Int
+    }
+
+
+type alias HealthCheck =
+    { ok : Bool, periodicMatches : Bool }
+
+
+type alias Leaderboard =
+    { name : String, players : Players }
+
+
+type alias Match =
+    { name : String
+    , participants : List Participant
+    , timestamp : String
+    }
+
+
+type alias Participant =
+    { name : String
+    , result : String
+    , url : String
+    , version : Maybe String
+    }
+
+
+type alias Players =
+    List EloStat
+
+
+eloStatDecoder : D.Decoder EloStat
+eloStatDecoder =
+    D.map6 EloStat
+        (D.field "draws" D.int)
+        (D.field "elo" D.int)
+        (D.field "losses" D.int)
+        (D.field "name" D.string)
+        (D.field "url" D.string)
+        (D.field "wins" D.int)
+
+
+getHealth :
+    { baseUrl : String
+    , toMsg : Result Http.Error HealthCheck -> msg
+    }
+    -> Cmd msg
+getHealth data =
+    Http.get
+        { url = data.baseUrl ++ "/health"
+        , expect = Http.expectJson data.toMsg healthCheckDecoder
+        }
+
+
+getLeaderboard :
+    { baseUrl : String
+    , toMsg : Result Http.Error Leaderboard -> msg
+    }
+    -> Cmd msg
+getLeaderboard data =
+    Http.get
+        { url = data.baseUrl ++ "/leaderboard"
+        , expect = Http.expectJson data.toMsg leaderboardDecoder
+        }
+
+
+getMatches :
+    { baseUrl : String
+    , toMsg : Result Http.Error (List Match) -> msg
+    }
+    -> Cmd msg
+getMatches data =
+    Http.get
+        { url = data.baseUrl ++ "/matches"
+        , expect = Http.expectJson data.toMsg (D.list matchDecoder)
+        }
+
+
+getPlayers :
+    { baseUrl : String
+    , toMsg : Result Http.Error Players -> msg
+    }
+    -> Cmd msg
+getPlayers data =
+    Http.get
+        { url = data.baseUrl ++ "/players"
+        , expect = Http.expectJson data.toMsg playersDecoder
+        }
+
+
+healthCheckDecoder : D.Decoder HealthCheck
+healthCheckDecoder =
+    D.map2 HealthCheck
+        (D.field "ok" D.bool)
+        (D.field "periodic_matches" D.bool)
+
+
+leaderboardDecoder : D.Decoder Leaderboard
+leaderboardDecoder =
+    D.map2 Leaderboard
+        (D.field "name" D.string)
+        (D.field "players" playersDecoder)
+
+
+matchDecoder : D.Decoder Match
+matchDecoder =
+    D.map3 Match
+        (D.field "name" D.string)
+        (D.field "participants" <| D.list participantDecoder)
+        (D.field "timestamp" D.string)
+
+
+participantDecoder : D.Decoder Participant
+participantDecoder =
+    D.map4 Participant
+        (D.field "name" D.string)
+        (D.field "result" D.string)
+        (D.field "url" D.string)
+        (D.maybe <| D.field "version" D.string)
+
+
+playersDecoder : D.Decoder Players
+playersDecoder =
+    D.list eloStatDecoder

elm/EloTracker.elm

@@ -0,0 +1,193 @@
+module EloTracker exposing (main)
+
+import Api.Elo as Elo
+import Element exposing (Element)
+import Http
+import Json.Decode as D
+import Program
+import Time
+import Widget.Icon
+import Layout
+import Theme
+import Screen.Leaderboard
+import Element.Font
+import Pixels
+import Element.Background
+
+
+main =
+    Program.document
+        { flagsDecoder = D.field "baseUrl" D.string
+        , headers = headers
+        , init = init
+        , subscriptions = subscriptions
+        , title = title
+        , update = update
+        , view = view
+        }
+
+
+
+-- MODEL
+
+
+type alias Model =
+    { baseUrl : String
+    , leaderboard : Result Int Elo.Leaderboard
+    , matches : Result Int (List Elo.Match)
+    }
+
+
+type Msg
+    = OnLeaderboard (Result Http.Error Elo.Leaderboard)
+    | OnMatches (Result Http.Error (List Elo.Match))
+    | RefreshLeaderboard
+    | RefreshMatches
+
+
+init : Result D.Error String -> ( Model, Cmd Msg )
+init flag =
+    let
+        baseUrl =
+            case flag of
+                Err _ ->
+                    "http://localhost:5000"
+
+                Ok v ->
+                    v
+
+        model =
+            { baseUrl = baseUrl
+            , leaderboard = Err 0
+            , matches = Err 0
+            }
+    in
+    ( model
+    , Cmd.batch
+        [ getLeaderboard model
+        , getMatches model
+        ]
+    )
+
+
+
+-- UPDATE
+
+
+update : Msg -> Model -> ( Model, Cmd Msg )
+update msg model =
+    case msg of
+        OnLeaderboard (Err _) ->
+            case model.leaderboard of
+                Err n ->
+                    ( { model | leaderboard = Err (n + 1) }, Cmd.none )
+
+                Ok _ ->
+                    ( model, Cmd.none )
+
+        OnLeaderboard (Ok v) ->
+            ( { model | leaderboard = Ok v }, Cmd.none )
+
+        OnMatches (Err _) ->
+            case model.matches of
+                Err n ->
+                    ( { model | matches = Err (n + 1) }, Cmd.none )
+
+                Ok _ ->
+                    ( model, Cmd.none )
+
+        OnMatches (Ok v) ->
+            ( { model | matches = Ok v }, Cmd.none )
+        
+        RefreshLeaderboard ->
+            ( model, getLeaderboard model )
+        
+        RefreshMatches ->
+            ( model, getMatches model )
+
+
+getLeaderboard : Model -> Cmd Msg
+getLeaderboard model =
+    Elo.getLeaderboard { baseUrl = model.baseUrl, toMsg = OnLeaderboard }
+
+
+getMatches : Model -> Cmd Msg
+getMatches model =
+    Elo.getMatches { baseUrl = model.baseUrl, toMsg = OnMatches }
+
+
+
+-- SUBSCRIPTIONS
+
+
+subscriptions : Model -> Sub Msg
+subscriptions _ =
+    Sub.batch
+        [ Time.every (5 * 1000) (always RefreshLeaderboard)
+        , Time.every (1 * 60 * 1000) (always RefreshMatches)
+        ]
+
+
+
+-- VIEW
+
+
+headers : Model -> List { icon : Widget.Icon.Icon msg, onPress : msg }
+headers _ =
+    []
+
+
+title : Model -> String
+title model =
+    case model.leaderboard of
+        Err _ ->
+            "EloTracker | Loading..."
+        
+        Ok _ ->
+            "EloTracker | Leaderboard"
+
+
+view : Program.ViewBox Model -> Element Msg
+view data =
+    case data.model.leaderboard of
+        Err 0 ->
+            Element.column
+                [ Element.width <| Element.px <| Pixels.inPixels data.size.width
+                , Element.height <| Element.px <| Pixels.inPixels data.size.height
+                ]
+                [ Element.column
+                    [ Element.centerX
+                    , Element.centerY
+                    , Element.Background.color (Theme.mantleUI data.flavor)
+                    , Element.padding 15
+                    , Element.spacing 10
+                    ]
+                    [ Element.text "Loading leaderboard..."
+                    , Layout.loadingIndicator { color = Theme.lavender data.flavor }
+                        |> Element.el [ Element.centerX ]
+                    ]
+                ]
+        
+        Err n ->
+            Element.column
+                [ Element.width <| Element.px <| Pixels.inPixels data.size.width
+                , Element.height <| Element.px <| Pixels.inPixels data.size.height
+                ]
+                [ Element.column
+                    [ Element.centerX
+                    , Element.centerY
+                    , Element.Background.color (Theme.mantleUI data.flavor)
+                    , Element.padding 15
+                    , Element.spacing 10
+                    ]
+                    [ Element.text "Loading leaderboard..."
+                    , Element.el [ Element.centerX, Element.Font.color (Theme.redUI data.flavor) ] (Element.text ("Failed " ++ (String.fromInt n) ++ " times"))
+                    , Layout.loadingIndicator { color = Theme.lavender data.flavor }
+                        |> Element.el [ Element.centerX ]
+                    ]
+                ]
+        
+        Ok leaderboard ->
+            Screen.Leaderboard.view
+                { flavor = data.flavor, model = leaderboard, size = data.size }
+

elm/Program.elm

@@ -156,32 +156,43 @@ view :
     -> Html.Html (Msg msg)
 view data model =
     let
-        preferredNavBarHeight =
+        navBarIconHeight =
             Pixels.pixels 40
 
+        navBarHeight =
+            Quantity.twice navBarIconHeight
+
         showNavBar =
-            preferredNavBarHeight
+            navBarHeight
                 |> Quantity.multiplyBy 6
                 |> Quantity.lessThanOrEqualTo model.size.height
 
         contentHeight =
             if showNavBar then
-                model.size.height |> Quantity.minus preferredNavBarHeight
+                model.size.height |> Quantity.minus navBarHeight
 
             else
                 model.size.height
     in
-    [ viewNavBar
+    [ if showNavBar then
+        viewNavBar
             { headers = data.headers model.content
-        , iconHeight = preferredNavBarHeight
+            , iconHeight = navBarIconHeight
             , model = model
             }
+
+      else
+        Element.none
     , data.body
         { flavor = model.flavor
         , model = model.content
-        , size = { height = contentHeight, width = model.size.width }
+        , size =
+            { height = contentHeight --|> Quantity.minus (Pixels.pixels 25)
+            , width = model.size.width --|> Quantity.minus (Pixels.pixels 25)
+            }
         }
         |> Element.map OnContent
+        |> Element.el []
     ]
         |> Element.column [ Element.width Element.fill ]
         |> Element.layout

elm/Screen/CreateGame.elm

@@ -2,18 +2,23 @@ module Screen.CreateGame exposing (..)
 
 -- MODEL
 
+
 type alias Model =
     { baseUrl : String
     , players : List String
     }
 
+
 type Msg
     = OnBaseUrl String
     | OnPlayer Int String
     | RemovePlayer Int
 
+
+
 -- UPDATE
 
+
 update : Msg -> Model -> ( Model, Cmd Msg )
 update msg model =
     case msg of
@@ -22,21 +27,23 @@ update msg model =
 
         OnPlayer n p ->
             let
-                newIndex = List.length model.players == n
+                newIndex =
+                    List.length model.players == n
 
                 newPlayers =
                     if newIndex && mayCreateNewPlayer model.players then
                         List.append model.players [ p ]
+
                     else
                         List.indexedMap
                             (\i player ->
                                 if n == i then
                                     p
+
                                 else
                                     player
                             )
                             model.players
-
             in
             ( { model | players = newPlayers }, Cmd.none )
 
@@ -48,6 +55,7 @@ update msg model =
                             (\i player ->
                                 if n == i then
                                     Nothing
+
                                 else
                                     Just player
                             )
@@ -56,10 +64,12 @@ update msg model =
             , Cmd.none
             )
 
--- SUBSCRIPTIONS
 
+
+-- SUBSCRIPTIONS
 -- VIEW
 
+
 mayCreateNewPlayer : List String -> Bool
 mayCreateNewPlayer =
     List.all (not << String.isEmpty)

elm/Screen/Leaderboard.elm

@@ -0,0 +1,90 @@
+module Screen.Leaderboard exposing (..)
+
+{-| Widget module for a leaderboard page.
+-}
+
+import Api.Elo exposing (EloStat, Leaderboard)
+import Element exposing (Element)
+import Element.Font
+import Layout
+import Pixels exposing (Pixels)
+import Program exposing (ViewBox)
+import Quantity exposing (Quantity)
+import Theme
+import Element.Background
+import Element.Border
+import Color
+
+
+view : ViewBox Leaderboard -> Element msg
+view data =
+    let
+        boardWidth =
+            data.size.width
+                |> Quantity.toFloatQuantity
+                |> Quantity.multiplyBy (2/3)
+                |> Quantity.floor
+                |> Quantity.clamp (Pixels.pixels 600) (Pixels.pixels 1800)
+                |> Pixels.inPixels
+                |> Element.px
+                |> Element.width
+    in
+    data.model.players
+        |> List.map (viewEloStat { flavor = data.flavor })
+        |> Element.column [ Element.centerX, boardWidth ]
+        |> List.singleton
+        |> (::) (
+                Element.text data.model.name
+                    |> Element.el
+                        [ Element.centerX, Element.Font.size 50 ]
+            )
+        |> Element.column
+            [ Element.padding 15
+            , Element.spacing 30
+            , Element.width <| Element.px <| Pixels.inPixels data.size.width 
+            ]
+
+
+viewEloStat : { flavor : Theme.Flavor } -> EloStat -> Element msg
+viewEloStat data stat =
+    Element.row
+        [ Element.Background.color (Theme.mantleUI data.flavor)
+        , Element.Border.rounded 5
+        , Element.padding 10
+        , Element.spacing 5
+        , Element.width Element.fill
+        ]
+        [ Element.column
+            [ Element.centerY, Element.spacing 5, Element.width Element.fill ]
+            [ Element.text stat.name
+                |> Element.el [ Element.Font.size 30 ]
+            , Element.el
+                [ Element.Font.color (Theme.subtext0UI data.flavor)
+                , Element.Font.size 15
+                ]
+                (Element.text stat.url)
+            ]
+
+        -- Bar to push the rest to the right
+        , Element.column [ Element.width Element.fill ] []
+        , field { text = "ELO", value = stat.elo, color = Theme.lavenderUI data.flavor }
+            |> Element.el [ Element.paddingEach { top = 0, bottom = 0, left = 0, right = 15 } ]
+        , field { text = "WINS", value = stat.wins, color = Theme.greenUI data.flavor }
+        , field { text = "DRAWS", value = stat.draws, color = Theme.subtext0UI data.flavor }
+        , field { text = "LOSSES", value = stat.losses, color = Theme.redUI data.flavor }
+        ]
+
+field : { text : String, value : Int, color : Element.Color } -> Element msg
+field { text, value, color } =
+    Element.column
+        [ Element.Font.color color
+        , Element.spacing 3
+        , Element.width (Element.px 70)
+        ]
+        [ String.fromInt value
+            |> Element.text
+            |> Element.el [ Element.centerX, Element.Font.size 25 ]
+        , text
+            |> Element.text
+            |> Element.el [ Element.centerX, Element.Font.size 15 ]
+        ]

elo_tracker/Containerfile

@@ -0,0 +1,60 @@
+FROM alpine:3.10 AS elm-builder
+
+ARG ELM_VERSION=0.19.1
+ARG ELM_URL=https://github.com/elm/compiler/releases/download/${ELM_VERSION}/binary-for-linux-64-bit.gz
+
+# Download internet packages + Node & npm
+RUN apk add --no-cache ca-certificates curl gzip bash nodejs npm
+
+# Download & install Elm
+RUN curl -L ${ELM_URL} \
+    | gunzip > /usr/local/bin/elm \
+    && chmod +x /usr/local/bin/elm
+
+# Install uglify-js globally
+RUN npm install -g uglify-js
+
+WORKDIR /app
+
+# Copy Elm code
+COPY elm.json .
+COPY elm/ elm/
+
+# Compile module
+RUN elm make --output=/app/elm.js --optimize elm/EloTracker.elm
+
+# Optimize & Minify compiled JS
+RUN uglifyjs elm.js \
+        --compress "pure_funcs=[F2,F3,F4,F5,F6,F7,F8,F9,A2,A3,A4,A5,A6,A7,A8,A9],pure_getters,keep_fargs=false,unsafe_comps,unsafe" \
+        | uglifyjs --mangle --output elo_tracker.js
+
+FROM python:3.10-alpine AS python-builder
+WORKDIR /app
+
+# Install build dependencies
+RUN apk add --no-cache gcc musl-dev python3-dev
+COPY requirements-elo.txt .
+
+# Create wheels for faster installation
+RUN pip wheel --no-cache-dir --wheel-dir /wheels -r requirements-elo.txt
+
+FROM python:3.10-alpine
+WORKDIR /app
+
+# Install from pre-built wheels
+COPY --from=python-builder /wheels /wheels
+COPY requirements-elo.txt .
+RUN pip install --no-cache-dir --no-index --find-links=/wheels \
+        -r requirements-elo.txt && rm -rf /wheels
+
+# Install Elm front-end JS
+COPY --from=elm-builder /app/elo_tracker.js /app/elo_tracker/static/elo_tracker.js
+
+# Install ELO tracker code
+COPY agents/ agents/
+COPY elo_tracker/ elo_tracker/
+COPY pyclient/ pyclient/
+COPY pyserver/ pyserver/
+COPY elo.py .
+
+CMD ["python", "elo.py"]

elo_tracker/README.md

@@ -0,0 +1,49 @@
+# ELO tracker
+
+The ELO tracker lets your agent play many games and assigns every participant
+an Elo rating.
+
+## Before you start
+
+The tracker only plays against **remote agents**. Remote agents are available
+through a URL, and usually run on the internet.
+
+If your agent only exists as a local Python class,
+[publish it first](/pyserver/README.md).
+
+## Add players
+
+Open `known_players.json` and add the URLs you want to include.
+
+For example:
+
+```json
+{
+    "players": [
+        "https://my-agent.example",
+        "https://bmt001.noordstar.me"
+    ]
+}
+```
+
+Every listed URL is considered a participant. The ELO tracker will compare
+these players with one another.
+
+## Start the tracker
+
+Run:
+
+```sh
+python elo.py
+```
+
+The tracker will continuously schedule new matches until you stop it.
+
+## Results
+
+Two files are updated while the tracker runs:
+
+* `games.jsonl` stores the played games.
+* `known_players.json` stores the list of participants.
+
+You can stop the tracker with <kbd>Ctrl</kbd>+<kbd>C</kbd>.

elo_tracker/app.py

@@ -14,6 +14,7 @@ from dataclasses import dataclass
 from datetime import datetime, timezone
 from typing import Any, Sequence
 
+import agents
 import pyclient
 
 from pyclient.games import FinishState, Game
@@ -37,17 +38,11 @@ class PlayerIdentifier:
         return (self.name, self.url, self.version)
     
     @classmethod
-    def from_server_agent(cls, agent : pyclient.ServerAgent) -> "PlayerIdentifier":
+    def from_server_agent(cls, agent : agents.RemoteAgent) -> "PlayerIdentifier":
         """
             Gain a player identifier from an agent.
         """
-        return cls(
+        return cls(name=agent.name, url=agent.url, version=agent.version)
-            name=agent.name,
-            url=agent.url,
-            version=agent.profile.get("version",
-                agent.profile.get("me.noordstar.peanuts.agent.version", None)
-            ),
-        )
 
 @dataclass()
 class EloStat:
@@ -181,7 +176,7 @@ class Match:
     @classmethod
     def from_replay(
         cls,
-        players : list[pyclient.ServerAgent],
+        players : list[agents.RemoteAgent],
         replay : pyclient.GameReplay,
         timestamp : str | None,
     ) -> "Match":
@@ -189,7 +184,7 @@ class Match:
             Convert a GameReplay into a match.
 
             :param players: The participants of the match.
-            :type players: list[pyclient.ServerAgent]
+            :type players: list[agents.RemoteAgent]
             :param replay: Game summary.
             :type replay: pyclient.GameReplay
             :param timestamp: ISO formatted timestamp of when the game was planned.
@@ -295,7 +290,7 @@ class EloTracker:
 
         # Thread-unsafe variables
         # Please use a lock while doing CRUD operations on them
-        self.players: list[pyclient.ServerAgent] = []
+        self.players: list[agents.RemoteAgent] = []
         self.__matches: list[Match] = []
         self.__stats: dict[PlayerIdentifier, EloStat] = {}
 
@@ -465,7 +460,7 @@ class EloTracker:
                     self.play_random_match(game=game, player_count=player_count)
             except Exception as exc:
                 self.__debug(f"Scheduled match failed: {exc}")
-                raise exc
+                # raise exc
 
             if self.__scheduler_stop.wait(interval_seconds):
                 break
@@ -496,15 +491,22 @@ class EloTracker:
   <head>
     <meta charset="utf-8">
     <title>Bot-Man-Toe Elo Tracker</title>
+    <script src="/static/elo_tracker.js"></script>
   </head>
   <body>
-    <main>
+    <main id="main-block">
       <h1>Bot-Man-Toe Elo Tracker</h1>
       <p>The JSON API is available at /leaderboard, /matches, /players, and /health.</p>
     </main>
   </body>
+  <script>
+    var app = Elm.EloTracker.init({
+        node: document.body,
+        flags: { baseUrl: "" }
+    });
+  </script>
 </html>
-""".strip(),
+""".strip(), # TODO: Make base URL more explicit
                 mimetype="text/html",
             )
 
@@ -558,13 +560,13 @@ class EloTracker:
                     "Expected `players` field to be a list of strings."
                 )
 
-            players : list[pyclient.ServerAgent] = []
+            players : list[agents.RemoteAgent] = []
             for url in urls:
                 if not isinstance(url, str):
                     continue
 
                 try:
-                    agent = pyclient.Agent.from_url(url, debug=self.debug)
+                    agent = agents.RemoteAgent(url=url)
                 except ValueError:
                     pass  # Not an available player right now
                 else:
@@ -586,17 +588,14 @@ class EloTracker:
             :rtype: pyclient.GameReplay
             :raises ValueError: One of the URLs could not be accessed.
         """
-        agents : list[Any] = [
+        ags : list[Any] = [ agents.RemoteAgent(url=url) for url in players ]
-            pyclient.Agent.from_url(url, debug=self.debug)
-            for url in players
-        ]
 
         replay = pyclient.PyClient(debug=self.debug).play_game(
-            players=agents,
+            players=ags,
             start=game,
         )
         
-        m = Match.from_replay(players=agents, replay=replay, timestamp=Match.now())
+        m = Match.from_replay(players=ags, replay=replay, timestamp=Match.now())
 
         # Record match
         m.log(self.game_file_name)
@@ -721,7 +720,7 @@ class EloTracker:
 
     def start_server(
         self,
-        host: str = "127.0.0.1",
+        host: str = "0.0.0.0",
         import_name : str = __name__,
         port: int = 5000,
         debug: bool = False,

known_players.json

@@ -1,6 +1,7 @@
 {
     "players": [
         "https://bmt001.noordstar.me",
-        "https://bmt002.noordstar.me"
+        "https://bmt002.noordstar.me",
+        "https://bmt003.noordstar.me"
     ]
 }

pyclient/__init__.py

@@ -2,15 +2,12 @@
     Entry points for developers who wish to use the PyClient module.
 """
 
-from .agent import Agent, ServerAgent
 from .client import PyClient
 from .replay import GameReplay
 from .transition import Transition
 
 __all__ = [
-    "Agent",
     "GameReplay",
     "PyClient",
-    "ServerAgent",
     "Transition",
 ]

pyclient/agent.py

@@ -1,178 +0,0 @@
-"""
-    This module hosts various agents that can participate in games.
-
-    Examples of possible agents could be:
-
-    - An online server
-    - A locally running neural network
-    - A hacker who participates from the terminal
-    - A user interface that allows users to play against their own creations
-"""
-
-from dataclasses import dataclass
-from typing import Any, Dict, Optional, Tuple, Union
-
-import requests
-import time
-
-@dataclass(frozen=True)
-class Agent:
-    """
-        Base class of a game participant. Mostly used to inherit from.
-    """
-
-    debug : bool
-    games : dict[str, dict[str, Any]]
-    profile : dict[str, Any]
-
-    @classmethod
-    def from_url(cls, url : str, **kwargs) -> "ServerAgent":
-        """
-            Create an agent based on a URL.
-
-            :param url: The URL where the agent can be accessed.
-            :type url: str            
-            :return: An agent that contacts a server when polled.
-            :rtype: ServerAgent
-            :raises ValueError: The server fails to reach out one of the URLs.
-        """
-        try:
-            return ServerAgent.from_server_url(url=url, **kwargs)
-        except (ValueError, requests.RequestException, requests.HTTPError):
-            pass
-
-        raise ValueError(
-            "URL did not lead to a willing agent"
-        )
-
-    @property
-    def name(self) -> str:
-        """
-            The name by which the agent calls itself.
-        """
-        return str(self.profile.get("name", "Nameless agent"))
-
-    def poll(
-        self,
-        game : str,
-        payload : dict[str, Any],
-        **kwargs
-    ) -> Optional[dict[str, Any]]:
-        """
-            Ask the agent to make a move.
-
-            :param game: The game the ServerAgent is asked to play.
-            :type game: str
-            :param payload: The JSON payload that represents the game's state.
-            :type payload: dict[str, Any]
-            :return: The agent's response, or None if the agent doesn't respond.
-            :rtype: Optional[dict[str, Any]]
-        """
-        print(f"WARNING: The `poll` method is not defined on the {self.__class__.__name__} class")
-        return None
-
-@dataclass(frozen=True)
-class ServerAgent(Agent):
-    """
-        Agent that reaches out to the internet to poll for moves.
-    """
-
-    url : str
-
-    @classmethod
-    def from_server_url(
-        cls,
-        url: str,
-        timeout: float | tuple[float, float] | None = 10.0,
-        debug : bool = False
-    ) -> "ServerAgent":
-        """
-        Create a server agent by polling its discovery endpoint.
-
-        :param url: The URL that the server can be reached at.
-        :type url: str
-        :param timeout: Request timeout.
-        :type timeout: float | tuple[float, float] | None
-        :param debug: Enables debug mode
-        :type debug: bool
-        :return: The server's representation as an agent.
-        :rtype: ServerAgent
-        :raises requests.exceptions.HTTPError: If the server returns a
-            non-success HTTP status code.
-        :raises requests.exceptions.RequestException: If the request fails
-            before a response is received.
-        :raises ValueError: If the response body is not a JSON object or if the
-            payload contains malformed discovery fields.
-        """
-        response = requests.get(url.rstrip("/") + "/", timeout=timeout)
-        response.raise_for_status()
-        content = response.json()
-
-        if not isinstance(content, dict):
-            raise ValueError("Server discovery responses must be JSON objects.")
-
-        raw_name = content.get("name", "")
-        name = "" if raw_name is None else str(raw_name)
-
-        games: dict[str, dict[str, Any]] = {}
-        raw_games = content.get("games", {})
-        if raw_games is not None:
-            if not isinstance(raw_games, dict):
-                raise ValueError("The 'games' field must be a JSON object when provided.")
-
-            for game_name, profile in raw_games.items():
-                if isinstance(profile, dict):
-                    games[str(game_name)] = profile
-
-        return cls(
-            debug=debug,
-            games=games,
-            profile=content,
-            url=url,
-        )
-    
-    def poll(
-        self,
-        game : str,
-        payload : dict[str, Any],
-        **kwargs
-    ) -> Optional[dict[str, Any]]:
-        """
-            Inquire a game to make a move.
-
-            :param game: The game the ServerAgent is asked to play.
-            :type game: str
-            :param payload: The JSON payload that represents the game's state.
-            :type payload: dict[str, Any]
-            :return: The server's response, or None if the server did not respond.
-            :rtype: Optional[dict[str, Any]]
-        """
-        url = f"{self.url.rstrip('/')}/{game.lstrip('/')}"
-        timeout = float(kwargs.get("timeout", 1.0))
-
-        try:
-            response = requests.get(url, json=payload, timeout=timeout)
-            response.raise_for_status()
-            content = response.json()
-        except (requests.exceptions.RequestException, ValueError):
-            return None
-
-        if self.debug:
-            print(f"[DBG] Agent `{self.name}` returned:")
-            print(content)
-
-        return content if isinstance(content, dict) else None
-
-    def to_dict(self) -> dict[str, Any]:
-        """
-            Represent the agent in the form of a dict.
-
-            :return: Dictionary representation of the ServerAgent
-            :rtype: dict[str, Any]
-        """
-        return dict(
-            name=self.name,
-            games=self.games,
-            url=self.url,
-            profile=self.profile,
-        )

pyclient/client.py

@@ -5,7 +5,7 @@
 
 from __future__ import annotations
 
-from .agent import Agent
+from agents import Agent
 from .games import Game
 from .replay import GameReplay, Turn
 from dataclasses import dataclass
@@ -43,12 +43,20 @@ class PyClient:
             
             else:
                 agent = players[player - 1]
-                payload = agent.poll(
+                on_move = agent.get_action(
                     game=current_state.game_name(),
-                    payload=current_state.as_seen_by(player=player),
+                    action=current_state.action_name(),
                 )
 
                 # Calculate move
+                if on_move is None:
+                    payload = {}
+                else:
+                    try:
+                        payload = on_move(current_state.as_seen_by(player=player))
+                    except Exception:
+                        payload = {}
+
                 current_state = current_state.move(payload=payload)
 
                 yield Turn(action=payload, player=player, state=current_state)

pyserver/README.md

@@ -0,0 +1,36 @@
+# Publishing your agent
+
+Once your agent behaves the way you want, you can expose it over HTTP so other clients can play against it.
+
+You only need this if you want other programs to connect to your agent.
+
+## Use this repository
+
+1. Open `server.py`.
+2. Replace the agent passed to `PyServer` with your own. For example:
+
+```py
+from agents.my_agent import MyAgent
+
+player = PyServer(MyAgent())
+```
+
+3. Start the server. Run:
+
+```sh
+python server.py
+```
+
+By default, the server listens on port `5000`.
+
+4. Open your browser and visit `http://localhost:5000/`. You should receive
+a JSON document describing your agent and the games it supports.
+If that works, your agent is ready to receive game requests.
+
+## Writing your own server
+
+The included server is the easiest way to publish a Python agent.
+
+If you want to implement the protocol yourself
+_(for example in another language)_ you can use the specification in
+[the protocol specification](spec.md).

pyserver/server.py

@@ -2,85 +2,39 @@
 
 from __future__ import annotations
 
-from collections.abc import Callable, Mapping
+from flask import Flask, jsonify, request
-from typing import Any, Optional
+from agents import Agent
-
+from typing import Any
-from flask import Flask, Response, jsonify, request
-from functools import wraps
 
 PayloadType = dict[str, Any]
-GameHandler = Callable[[PayloadType], PayloadType]
 
 
 class PyServer:
-    """A tiny stateless Flask app that serves discovery and game routes."""
-
-    def __init__(self,
-        name: str,
-        import_name: str = __name__,
-        profile: Optional[PayloadType] = None,
-        subpath : str = "",
-    ) -> None:
     """
-        Create a PyServer.
+        A tiny stateless Flask app that serves discovery and routes
+        game behavior to an agent.
+    """
 
-        :param name: Preferred display name for discovery.
+    def __init__(self, agent : Agent, import_name : str = __name__) -> None:
-        :type name: str
+        """
-        :param import_name: Flask import name.
+        Create a PyServer that serves the behavior of an Agent.
+
+        :param agent: The agent that one can communicate with.
+        :type agent: Agent
+        :param import_name: Flask application import name
         :type import_name: str
-        :param profile: Additional root-level discovery metadata.
-        :type profile: Optional[Dict[str, Any]]
-        :type subpath: str
-        :raises ValueError: The input contains invalid information.
         """
-        self.name = name
+        self.agent = agent
-        self.profile = dict(profile or {})
-
-        if "name" in self.profile:
-            raise ValueError(
-                "Root profile metadata must not define 'name'."
-            )
-        if "games" in self.profile:
-            raise ValueError(
-                "Root profile metadata must not define 'games'."
-            )
-
         self.app = Flask(import_name)
-        self.__games: dict[str, PayloadType] = {}
-        self.__registered_routes: set[str] = set()
 
-        # Register the root
+        @self.app.get("/")
-        self.__add_api_endpoint("", "", lambda _ : self.__discovery())
+        def discovery():
-        # self.app.add_url_rule("/",
+            return jsonify(self.__discovery())
-        #     endpoint="botman_discovery",
-        #     view_func=self.__discovery,
-        #     methods=["GET"]
-        # )
 
-    def __add_api_endpoint(self, name : str, route : str, func : GameHandler) -> None:
+        @self.app.get("/<path:game>")
-        """
+        @self.app.get("/<path:game>/<path:action>")
-            Create a new API endpoint.
+        def dispatch(game: str, action: str | None = None):
-
+            return jsonify(self.__dispatch(game=game, action=action))
-            :param name: The name of the action to undertake.
-            :type name: str
-            :param func: The player's function that determines what action to take.
-            :type func: Callable[[dict[str, Any]], dict[str, Any]]
-            :raises ValueError: The URL has already been registered.
-        """
-        url = self.__make_url(name, route)
-
-        if url in self.__registered_routes:
-            raise ValueError(
-                f"Route already registered: {url}"
-            )
-        
-        self.__registered_routes.add(url)
-
-        return self.app.add_url_rule(url,
-            endpoint="botman_" + name.replace("/", "_"),
-            view_func=self.__func_wrapper(func),
-            methods=["GET"],
-        )
 
     def __discovery(self) -> PayloadType:
         """
@@ -89,103 +43,33 @@ class PyServer:
             :return: The personal discovery information.
             :rtype: dict[str, Any]
         """
-        return {
+        d = dict(name=self.agent.name, author=self.agent.author)
-            "name": self.name,
+        if self.agent.version is not None:
-            "games": dict(self.__games),
+            d["version"] = self.agent.version
-            **self.profile,
-        }
         
-    def __func_wrapper(self, func : GameHandler) -> Callable[[], Response]:
+        d = { **self.agent.profile, **d }
+
+        d["games"] = {}
+        for game, (profile, _) in self.agent.registered_games.items():
+            d["games"][game] = profile
+        
+        return d
+
+    def __dispatch(self, game: str, action: str | None) -> PayloadType:
         """
-            Wrapper that catches an incoming request, parses it, and responds
+            Resolve a request against the agent's action lookup.
-            with a player's action response.
         """
-        @wraps(func)
-        def exec():
         payload = request.get_json(silent=True) or {}
+        func = self.agent.get_action(
+            game=game.strip("/"),
+            action=action.strip("/") if isinstance(action, str) else None,
+        )
+
+        if func is None:
+            return {}
+
         result = func(payload) or {}
-            return jsonify(result)
+        return result if isinstance(result, dict) else {}
-        
-        return exec
-
-    def __make_url(self, name : str, route : str) -> str:
-        return "/" + "/".join([ name.strip("/"), route.strip("/") ]).strip("/")
-
-    def add_game(
-        self,
-        name: str,
-        profile: PayloadType,
-        actions: dict[str, GameHandler],
-        required_actions: Optional[list[str]] = None,
-    ) -> None:
-        """
-        Register a stateless game with one or more action routes.
-
-        :param name: Base route name for the game.
-        :type name: str
-        :param profile: Game-specific discovery metadata.
-        :type profile: dict[str, Any]
-        :param actions: Mapping of action subpaths to handlers.
-        :type actions: dict[str, Callable[[dict[str, Any]], dict[str, Any]]]
-        :param required_actions: Optional completeness check. If provided, all
-            required action names must exist in ``actions`` and map to callables.
-        :type required_actions: Optional[list[str]]
-        :raises AssertionError: Some of the required actions aren't present.
-        :raises ValueError: Some of the requested URL paths are already occupied.
-        """
-
-        # Verify that all required actions are present
-        if required_actions is not None:
-            missing_actions = [ action for action in required_actions if action not in actions ]
-
-            if len(missing_actions) > 0:
-                raise AssertionError(
-                    f"Missing required action handlers: {', '.join(sorted(missing_actions))}"
-                )
-        
-        # Verify that there are no duplicate URLs being registered
-        # Even though this will automatically be checked later, checking this
-        # now ensures that the operation is atomic and doesn't add
-        # games partially.
-        new_routes : set[str] = set()
-
-        for route in actions:
-            url = self.__make_url(name, route)
-
-            if url in self.__registered_routes:
-                raise ValueError(
-                    "Route {url} was already registered"
-                )
-            if url in new_routes:
-                raise ValueError(
-                    "Route {url} was registered twice by the same function call"
-                )
-            
-            new_routes.add(url)
-        
-        # Register all actions
-        for route, func in actions.items():
-            self.__add_api_endpoint(name=name, route=route, func=func)
-        
-        # Add profile data
-        self.__games[name] = profile
-
-    def add_tic_tac_toe(self, on_move: GameHandler, profile: PayloadType = {}) -> None:
-        """
-        Convenience registration for tic-tac-toe.
-
-        The game is exposed at `/tic-tac-toe`.
-
-        :param profile: The player's custom profile.
-        :type profile: dict[str, Any]
-        :param on_move:
-        """
-        self.add_game(
-            name="tic-tac-toe",
-            profile=profile,
-            actions={"": on_move},
-            required_actions=[""],
-        )
 
     def start(self, host: str = "127.0.0.1", port: int = 5000, debug: bool = False, **kwargs: Any) -> None:
         """Start the Flask development server."""

pyserver/spec.md

@@ -3,6 +3,10 @@
 This document describes how a Bot-Man-Toe server or client is supposed to
 behave.
 
+**This document requires familiarity with setting up an HTTP server.** Please
+use [the easy implementation](/pyserver/README.md) if you're building
+[a simple agent](/agents/README.md) in this repository.
+
 ## Terminology
 
 A **server** is a REST API server that hosts a player willing to play games.
@@ -65,3 +69,13 @@ package namespace guidelines.
 }
 ```
 
+There's a few optional data fields that are specified here:
+
+| Field | Type | Description |
+| ----- | ---- | ----------- |
+| author | string | The name of the person who designed the agent. |
+| version | string | The version of the agent, in case there's an update. |
+| me.noordstar.peanuts.containerized | bool | Whether the agent is running in a container. |
+| me.noordstar.peanuts.is_ai | bool | Whether the agent runs on a trained deep learning model or some artificial intelligence. |
+| me.noordstar.peanuts.agent.version | string | **Deprecated.** Experimental value to demonstrate an agent's version. Please use `version` instead. |
+| me.noordstar.peanuts.author | string | **Deprecated.** Experimental value to demonstrate an agent's author. Please use `author` instead. |

requirements-elo.txt

@@ -0,0 +1,13 @@
+blinker==1.9.0
+certifi==2026.6.17
+charset-normalizer==3.4.7
+click==8.4.1
+colorama==0.4.6
+Flask==3.1.3
+idna==3.18
+itsdangerous==2.2.0
+Jinja2==3.1.6
+MarkupSafe==3.0.3
+requests==2.34.2
+urllib3==2.7.0
+Werkzeug==3.1.8

server.py

@@ -4,10 +4,9 @@
 
 from __future__ import annotations
 
-import random
+import agents
 
 from pyserver import PyServer
-from typing import Any
 
 def main() -> int:
     """
@@ -16,19 +15,7 @@ def main() -> int:
         :return: Exit code
         :rtype: int
     """
-    player = PyServer(
+    player = PyServer(agents.AgentOfChaos())
-        # Customize this to whatever you'd like to call your player
-        name="My super smart robot player",
-
-        # Custom information that you can use to tell people about this player
-        profile={},
-
-        # Unless you know what you're doing, don't touch this.
-        import_name=__name__,
-    )
-
-    # Register games! Comment out any you don't want your player to play.
-    player.add_tic_tac_toe(on_move=play_tic_tac_toe, profile={})
 
     # Start listening for games
     player.start(
@@ -38,62 +25,5 @@ def main() -> int:
 
     return 0
 
-def play_tic_tac_toe(payload : dict[str, Any]) -> dict[str, Any]:
-    """
-        Play a game of tic-tac-toe.
-
-        You receive a payload that looks like this:
-
-        {
-            "1": "X", "2": "",  "3": "O",
-            "4": "X", "5": "O", "6": "",
-            "7": "",  "8": "",  "9": "",
-            "your_token": "X"
-        }
-
-        And you're expected to return a response of which field you'd like to
-        place your piece in. For example, if you wish to place your token in
-        field 7, your response should look like this:
-
-        { "move": 7 }
-
-        The board is arranged as follows:
-
-         1 | 2 | 3
-        ---+---+---
-         4 | 5 | 6
-        ---+---+---
-         7 | 8 | 9
-        
-        :param payload: The incoming JSON that contains the game state.
-        :type payload: dict[str, Any]
-        :return: The move you wish to take.
-        :rtype: dict[str, Any]
-    """
-
-    # Try printing the payload to see what it looks like!
-    print(payload)
-
-    options = [ 1, 2, 3, 4, 5, 6, 7, 8, 9, ]
-
-    # 1. Try filtering out the impossible moves!
-    #    If an X or O was already placed at a field, remove it from the options
-
-    #
-
-    # 2. Try finding two in a row! If possible, you can try to place the third
-    #    item on the board and get 3 in a row.
-
-    #
-
-    # 3. Perhaps you can block the opponent from getting 3 in a row?
-
-    #
-
-    # Now, pick any of the remaining options.
-    # This is just a simple implementation. Naturally, you're welcome to try
-    # your own logic.
-    return { "move": random.choice(options) }
-
 if __name__ == "__main__":
     raise SystemExit(main())