ludotastic 0.2.1__py3-none-any.whl

ludotastic/__init__.py

@@ -0,0 +1,54 @@
+"""Where humans and AI come to play."""
+
+__all__ = [
+    "ENTRY_POINT_GROUP",
+    "AIPlayer",
+    "ActionMode",
+    "Decision",
+    "Game",
+    "GameInfo",
+    "GameRegistry",
+    "HumanPlayer",
+    "Match",
+    "MatchStatus",
+    "MoveRecord",
+    "Outcome",
+    "Player",
+    "PlayerKind",
+    "RandomBot",
+    "RenderContext",
+    "Renderer",
+    "SeatInfo",
+    "Settings",
+    "Timing",
+    "TurnContext",
+    "View",
+    "get_settings",
+    "registry",
+]
+
+from .engine import (
+    ENTRY_POINT_GROUP,
+    ActionMode,
+    AIPlayer,
+    Decision,
+    Game,
+    GameInfo,
+    GameRegistry,
+    HumanPlayer,
+    Match,
+    MatchStatus,
+    MoveRecord,
+    Outcome,
+    Player,
+    PlayerKind,
+    RandomBot,
+    RenderContext,
+    Renderer,
+    SeatInfo,
+    Timing,
+    TurnContext,
+    View,
+    registry,
+)
+from .settings import Settings, get_settings

ludotastic/api.py

@@ -0,0 +1,191 @@
+"""The REST API."""
+
+from typing import Annotated, Any, cast
+
+from fastapi import APIRouter, Body, Depends, FastAPI, HTTPException, Request, status
+from pydantic import BaseModel, Field
+
+from ludotastic.engine.game import Game, GameInfo
+from ludotastic.engine.match import Match, MatchStatus, MoveRecord, SeatInfo
+from ludotastic.service import MatchService, PlayerSpec, bot_names
+from ludotastic.storage import MatchRecord, PlayerStats
+
+__all__ = ["create_router"]
+
+
+class GameDetails(BaseModel):
+    """A game, as the API describes it."""
+
+    info: GameInfo
+    rules: str
+    bots: list[str]
+    state_schema: dict[str, Any]
+    action_schema: dict[str, Any]
+
+
+class NewMatch(BaseModel):
+    """What it takes to start a match."""
+
+    game_id: str
+    players: list[PlayerSpec] = Field(min_length=1)
+    seed: int | None = None
+
+
+class MatchView(BaseModel):
+    """A live match."""
+
+    id: str
+    game_id: str
+    status: MatchStatus
+    seed: int
+    turn: int
+    seats: list[SeatInfo]
+    to_move: list[int]
+    """Seats being waited on right now."""
+    state: dict[str, Any]
+    legal_actions: dict[int, list[dict[str, Any]]]
+    """Legal actions for every seat being waited on."""
+    history: list[MoveRecord]
+    scores: list[float] | None
+    reason: str | None
+
+    @classmethod
+    def of(cls, match: Match) -> MatchView:
+        """Describe a match."""
+        game: Game[Any, Any] = match.game
+        thinking = sorted(match.thinking)
+        return cls(
+            id=match.id,
+            game_id=game.info.id,
+            status=match.status,
+            seed=match.seed,
+            turn=match.turn,
+            seats=match.seats,
+            to_move=thinking,
+            state=match.state.model_dump(mode="json"),
+            legal_actions={
+                seat: [
+                    a.model_dump(mode="json")
+                    for a in game.legal_actions(match.state, seat)
+                ]
+                for seat in thinking
+            },
+            history=match.history,
+            scores=list(match.outcome.scores) if match.outcome else None,
+            reason=match.outcome.reason if match.outcome else match.error,
+        )
+
+
+def _service(request: Request) -> MatchService:
+    return cast("MatchService", request.app.state.service)
+
+
+type Service = Annotated[MatchService, Depends(_service)]
+
+
+def _live(service: MatchService, match_id: str) -> Match:
+    match = service.get(match_id)
+    if match is None:
+        raise HTTPException(status.HTTP_404_NOT_FOUND, "No live match with that id")
+    return match
+
+
+def create_router() -> APIRouter:  # noqa: C901
+    """Build the API routes; they expect `app.state.service` to be set."""
+    router = APIRouter(prefix="/api", tags=["ludotastic"])
+
+    @router.get("/games")
+    def list_games(service: Service) -> list[GameInfo]:
+        """Every installed game."""
+        return [service.games[game_id].info for game_id in service.games]
+
+    @router.get("/games/{game_id}")
+    def get_game(service: Service, game_id: str) -> GameDetails:
+        """One game in detail, including the JSON schemas of its state and actions."""
+        try:
+            game_type = service.games[game_id]
+        except KeyError:
+            raise HTTPException(status.HTTP_404_NOT_FOUND, "Unknown game") from None
+        game = game_type()
+        return GameDetails(
+            info=game.info,
+            rules=game.rules,
+            bots=bot_names(game),
+            state_schema=game.state_type.model_json_schema(),
+            action_schema=game.action_type.model_json_schema(),
+        )
+
+    @router.post("/matches", status_code=status.HTTP_201_CREATED)
+    async def create_match(service: Service, body: NewMatch) -> MatchView:
+        """Start a match; it runs in the background."""
+        try:
+            match = service.create(body.game_id, body.players, seed=body.seed)
+        except KeyError:
+            raise HTTPException(status.HTTP_404_NOT_FOUND, "Unknown game") from None
+        except ValueError as e:
+            raise HTTPException(status.HTTP_422_UNPROCESSABLE_CONTENT, str(e)) from None
+        return MatchView.of(match)
+
+    @router.get("/matches")
+    async def list_live_matches(service: Service) -> list[MatchView]:
+        """Matches being played right now."""
+        return [MatchView.of(m) for m in service.live()]
+
+    @router.get("/matches/{match_id}")
+    async def get_match(service: Service, match_id: str) -> MatchView:
+        """A live match."""
+        return MatchView.of(_live(service, match_id))
+
+    @router.post("/matches/{match_id}/seats/{seat}/action")
+    async def submit_action(
+        service: Service,
+        match_id: str,
+        seat: int,
+        action: Annotated[dict[str, Any], Body()],
+    ) -> MatchView:
+        """Act for a human seat."""
+        match = _live(service, match_id)
+        if not 0 <= seat < len(match.players):
+            raise HTTPException(status.HTTP_404_NOT_FOUND, "No such seat")
+        try:
+            match.submit(seat, action)
+        except TypeError as e:
+            raise HTTPException(status.HTTP_403_FORBIDDEN, str(e)) from None
+        except ValueError as e:
+            raise HTTPException(status.HTTP_409_CONFLICT, str(e)) from None
+        return MatchView.of(match)
+
+    @router.delete("/matches/{match_id}", status_code=status.HTTP_204_NO_CONTENT)
+    async def abort_match(service: Service, match_id: str) -> None:
+        """Abort a live match."""
+        _live(service, match_id).abort("Aborted through the API")
+
+    @router.get("/history")
+    def history(
+        service: Service, game_id: str | None = None, limit: int = 50
+    ) -> list[MatchRecord]:
+        """Recent matches, newest first."""
+        return service.store.recent(game_id=game_id, limit=limit)
+
+    @router.get("/history/{match_id}")
+    def history_match(service: Service, match_id: str) -> MatchRecord:
+        """A stored match, with its full move history."""
+        record = service.store.get(match_id)
+        if record is None:
+            raise HTTPException(
+                status.HTTP_404_NOT_FOUND, "No stored match with that id"
+            )
+        return record
+
+    @router.get("/stats")
+    def stats(service: Service, game_id: str | None = None) -> list[PlayerStats]:
+        """Results per game and player group."""
+        return service.store.stats(game_id=game_id)
+
+    return router
+
+
+def mount_api(app: FastAPI, service: MatchService) -> None:
+    """Add the API to an app."""
+    app.state.service = service
+    app.include_router(create_router())

ludotastic/cli.py

@@ -0,0 +1,182 @@
+"""The `ludotastic` command."""
+
+import asyncio
+from typing import Annotated, Any
+
+import typer
+from dotenv import load_dotenv
+from pydantic_ai import prices
+
+from ludotastic.engine.game import ActionMode, View
+from ludotastic.engine.registry import registry
+from ludotastic.engine.usage import Usage, format_cost, format_tokens
+from ludotastic.service import AISpec, BotSpec, MatchService, bot_names
+from ludotastic.settings import get_settings
+
+__all__ = ["app"]
+
+app = typer.Typer(
+    name="ludotastic",
+    help="Where humans and AI come to play.",
+    no_args_is_help=True,
+)
+
+
+@app.command()
+def serve(
+    host: Annotated[str | None, typer.Option(help="Address to listen on.")] = None,
+    port: Annotated[int | None, typer.Option(help="Port to listen on.")] = None,
+) -> None:
+    """Run the playground and the API."""
+    import uvicorn  # noqa: PLC0415
+
+    from ludotastic.web import create_app  # noqa: PLC0415
+
+    settings = get_settings()
+    uvicorn.run(
+        create_app(),
+        host=host or settings.host,
+        port=port or settings.port,
+    )
+
+
+@app.command("games")
+def list_games() -> None:
+    """List the installed games."""
+    for game_id in registry:
+        game = registry[game_id]()
+        info = game.info
+        modes = ", ".join(info.action_modes)
+        typer.echo(
+            f"{game_id}: {info.name} ({info.min_players}-{info.max_players} players, "
+            f"{info.timing}; bots: {', '.join(bot_names(game))}; AI modes: {modes})"
+        )
+    for name, error in registry.errors.items():
+        typer.secho(f"{name}: failed to load: {error}", fg=typer.colors.RED, err=True)
+
+
+def _spec(text: str) -> BotSpec | AISpec:
+    """Parse `bot:NAME`, or a model name with optional `@mode` and `+view`.
+
+    Examples:
+        >>> spec = _spec("typesafe:jev-latest@choice+image")
+        >>> spec.model, str(spec.mode), str(spec.view)
+        ('typesafe:jev-latest', 'choice', 'image')
+    """
+    if text.startswith("bot:"):
+        return BotSpec(bot=text.removeprefix("bot:"))
+    rest, _, view = text.partition("+")
+    model, _, mode = rest.partition("@")
+    return AISpec(
+        model=model,
+        mode=ActionMode(mode) if mode else None,
+        view=View(view) if view else View.TEXT,
+    )
+
+
+@app.command()
+def play(
+    game_id: Annotated[str, typer.Argument(help="The game to play.")],
+    players: Annotated[
+        list[str],
+        typer.Argument(
+            help=(
+                "One per seat: `bot:NAME` for a bot, or a model name such as "
+                "`typesafe:jev-latest`, optionally with `@choice`, `@structured` "
+                "or `@tools`, and `+image` or `+both` to show it pictures."
+            )
+        ),
+    ],
+    rounds: Annotated[int, typer.Option(help="How many matches to play.")] = 1,
+    seed: Annotated[int | None, typer.Option(help="Seed for the first match.")] = None,
+    swap: Annotated[
+        bool, typer.Option(help="Rotate seats every round, for fairness.")
+    ] = True,
+    quiet: Annotated[bool, typer.Option(help="Only print the summary.")] = False,
+) -> None:
+    """Play matches between bots and AI models, without the UI."""
+    settings = get_settings().model_copy(update={"ai_delay": 0.0})
+    service = MatchService(settings=settings)
+    specs = [_spec(p) for p in players]
+    totals: dict[str, float] = {}
+    spent: dict[str, Usage] = {}
+
+    async def run_all() -> None:
+        for round_ in range(rounds):
+            shift = round_ % len(specs) if swap else 0
+            seated = specs[shift:] + specs[:shift]
+            match = service.create(
+                game_id,
+                seated,
+                seed=None if seed is None else seed + round_,
+                start=False,
+            )
+            if not quiet:
+                match.subscribe(_printer())
+            await match.run()
+            names = [p.label for p in match.players]
+            for seat, name in enumerate(names):
+                spent[name] = spent.get(name, Usage()) + match.usage(seat)
+            if match.outcome is None:
+                typer.secho(f"Round {round_ + 1}: aborted: {match.error}", fg="red")
+                continue
+            for name, score in zip(names, match.outcome.scores, strict=True):
+                totals[name] = totals.get(name, 0.0) + score
+            result = ", ".join(
+                f"{n}={s:g}" for n, s in zip(names, match.outcome.scores, strict=True)
+            )
+            typer.echo(f"Round {round_ + 1}: {match.outcome.reason} ({result})")
+
+    updater = prices.update_in_background() if settings.update_prices else None
+    try:
+        asyncio.run(run_all())
+    except KeyError:
+        typer.secho(f"Unknown game: {game_id}", fg="red", err=True)
+        raise typer.Exit(1) from None
+    except ValueError as e:
+        typer.secho(str(e), fg="red", err=True)
+        raise typer.Exit(1) from None
+    finally:
+        if updater is not None:
+            updater.stop()
+        service.store.close()
+    _summary(totals, spent)
+
+
+def _summary(totals: dict[str, float], spent: dict[str, Usage]) -> None:
+    typer.echo("Total score:")
+    for name, score in sorted(totals.items(), key=lambda kv: -kv[1]):
+        usage = spent.get(name, Usage())
+        cost = (
+            f" ({format_cost(usage.cost, priced=usage.priced)}, "
+            f"{format_tokens(usage.tokens)} tokens, {usage.requests} requests)"
+            if usage.requests
+            else ""
+        )
+        typer.echo(f"  {name}: {score:g}{cost}")
+
+
+def _printer() -> Any:  # noqa: ANN401
+    printed = 0
+
+    def show(match: Any) -> None:  # noqa: ANN401
+        nonlocal printed
+        for move in match.history[printed:]:
+            typer.echo(
+                f"  {move.turn + 1}. {match.game.player_label(move.seat)}: "
+                f"{move.description}"
+            )
+        printed = len(match.history)
+
+    return show
+
+
+def main() -> None:
+    """Run the CLI.
+
+    Variables in a `.env` file in the working directory are loaded first, so
+    model provider keys such as `TYPESAFE_API_KEY` can live there. Variables
+    already set in the environment win.
+    """
+    load_dotenv(".env")
+    app()

ludotastic/engine/__init__.py

@@ -0,0 +1,33 @@
+"""The game engine: games, players, matches and the plugin registry."""
+
+__all__ = [
+    "ENTRY_POINT_GROUP",
+    "AIPlayer",
+    "ActionMode",
+    "Decision",
+    "Game",
+    "GameInfo",
+    "GameRegistry",
+    "HumanPlayer",
+    "Match",
+    "MatchStatus",
+    "MoveRecord",
+    "Outcome",
+    "Player",
+    "PlayerKind",
+    "RandomBot",
+    "RenderContext",
+    "Renderer",
+    "SeatInfo",
+    "Timing",
+    "TurnContext",
+    "View",
+    "registry",
+]
+
+from .ai import AIPlayer
+from .game import ActionMode, Game, GameInfo, Outcome, Timing, View
+from .match import Match, MatchStatus, MoveRecord, SeatInfo
+from .players import Decision, HumanPlayer, Player, PlayerKind, RandomBot, TurnContext
+from .registry import ENTRY_POINT_GROUP, GameRegistry, registry
+from .render import RenderContext, Renderer