wingspan-rl 1.0.0__py3-none-any.whl

wingspan/__init__.py

@@ -0,0 +1,3 @@
+"""Wingspan simulator and RL training pipeline."""
+
+__version__ = "1.0.0"

wingspan/__main__.py

@@ -0,0 +1,134 @@
+"""Unified ``wingspan`` CLI dispatcher.
+
+Usage: wingspan <command> [args …]
+       wingspan -V | --version   (package version, artifact era, bundled model)
+
+Commands:
+  play        Play games between any mix of human, random, and trained-AI seats.
+  aid         Live assistant for a physical 2-player game (model advice + board tracking).
+  dashboard   FLIGHT PLAN: configure a run, then train and monitor it live.
+  tournament  Round-robin tournament between trained AIs.
+  cloud       Run a training job headless with S3 persistence.
+  monitor     FLOCK WATCH: watch all cloud runs from their S3 status snapshots.
+  inspect     Print the model introspection report.
+  summary     Training-progression HTML report for a run directory.
+  research    Offline research studies over a trained checkpoint (docs/RESEARCH.md).
+  analysis    Offline architecture-importance probe over a trained checkpoint
+              (docs/TRAINING.md "6.5 Representation diagnostics").
+"""
+
+from __future__ import annotations
+
+import sys
+
+# One-line description per verb — printed by the top-level help.
+_VERBS: dict[str, str] = {
+    "play": "Play games between any mix of human, random, and trained-AI seats.",
+    "aid": "Live assistant for a physical 2-player game (model advice + board tracking).",
+    "dashboard": "FLIGHT PLAN: configure a run, then train and monitor it live.",
+    "tournament": "Round-robin tournament between trained AIs.",
+    "cloud": "Run a training job headless with S3 persistence.",
+    "monitor": "FLOCK WATCH: watch all cloud runs from their S3 status snapshots.",
+    "inspect": "Print the model introspection report.",
+    "summary": "Training-progression HTML report for a run directory.",
+    "research": "Offline research studies over a trained checkpoint (docs/RESEARCH.md).",
+    "analysis": "Offline architecture-importance probe over a trained checkpoint.",
+}
+
+
+def main(argv: list[str] | None = None) -> int:
+    """Entry point for the unified ``wingspan`` command."""
+    args = list(argv) if argv is not None else sys.argv[1:]
+    if not args or args[0] in ("-h", "--help"):
+        _print_help()
+        return 0
+    if args[0] in ("-V", "--version"):
+        _print_version()
+        return 0
+    verb, rest = args[0], args[1:]
+    match verb:
+        case "play":
+            import wingspan.cli as cli
+
+            return cli.main_play(rest)
+        case "aid":
+            import wingspan.aid.app as aid_app
+
+            return aid_app.main(rest)
+        case "dashboard":
+            import wingspan.training.app as training_app
+
+            return training_app.main(rest)
+        case "tournament":
+            import wingspan.tournament.app as tournament_app
+
+            return tournament_app.main(rest)
+        case "cloud":
+            import wingspan.cloud.__main__ as cloud_entry
+
+            return cloud_entry.main(rest)
+        case "monitor":
+            import wingspan.cloud.monitor as cloud_monitor
+
+            return cloud_monitor.main(rest)
+        case "inspect":
+            from wingspan.reporting import inspect_cli as introspect
+
+            return introspect.main_inspect(rest)
+        case "summary":
+            from wingspan.reporting import summary_cli
+
+            return summary_cli.main_summary(rest)
+        case "research":
+            import wingspan.research.app as research_app
+
+            return research_app.main(rest)
+        case "analysis":
+            import wingspan.analysis.cli as analysis_cli
+
+            return analysis_cli.main_analysis(rest)
+        case _:
+            print(
+                f"wingspan: unknown command '{verb}'  (try `wingspan --help`)",
+                file=sys.stderr,
+            )
+            return 1
+
+
+###### PRIVATE #######
+
+
+def _print_version() -> None:
+    """Print the package version, the artifact era, and the bundled model."""
+    import wingspan
+    from wingspan import release, version
+
+    print(f"wingspan-rl {wingspan.__version__} (artifact era {version.MODEL_VERSION})")
+    if release.has_release():
+        manifest = release.load_manifest()
+        if manifest is not None:
+            print(
+                f"bundled model: era {manifest.era}, run {manifest.run_name}, "
+                f"iteration {manifest.iteration}"
+            )
+        else:
+            print("bundled model: present (no manifest)")
+
+
+def _print_help() -> None:
+    """Print the top-level usage table."""
+    width = max(len(verb) for verb in _VERBS)
+    lines = [
+        "usage: wingspan <command> [args …]",
+        "",
+        "Commands:",
+        *(f"  {verb:<{width}}  {desc}" for verb, desc in _VERBS.items()),
+        "",
+        "Run `wingspan <command> --help` for per-command usage.",
+        "Run `wingspan --version` for the package version and bundled model.",
+    ]
+    print("\n".join(lines))
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

wingspan/agents/__init__.py

@@ -0,0 +1,20 @@
+"""Agents that resolve Decisions.
+
+An agent is any callable matching ``wingspan.engine.core.Agent`` — given the
+engine and a ``Decision[C]``, it returns the chosen ``C``. The Agent type
+itself lives next to the Engine; this package collects implementations:
+
+- ``base`` — the random-policy agent
+- ``cli``  — the interactive human (stdin/stdout) agent
+
+The public entry points are re-exported so callers can keep writing
+``from wingspan.agents import cli_agent``.
+"""
+
+from wingspan.agents.base import random_agent
+from wingspan.agents.cli import cli_agent
+
+__all__ = [
+    "random_agent",
+    "cli_agent",
+]

wingspan/agents/base.py

@@ -0,0 +1,34 @@
+"""The random-policy agent.
+
+This is the minimal surface area every agent implementation depends on: a
+tiny default agent that just picks a uniformly-random offered choice. Other
+modules (e.g. ``cli``) build on this without pulling the interactive bits.
+
+The shared callable type is ``wingspan.engine.core.Agent`` — a Protocol with
+a generic ``__call__`` so the returned Choice subtype tracks the Decision's
+parameterization automatically.
+"""
+
+from __future__ import annotations
+
+import random
+
+from wingspan import decisions
+from wingspan.engine import core as engine_core
+
+
+def random_agent(rng: random.Random | None = None) -> engine_core.Agent:
+    """Build an agent that picks uniformly at random from the offered choices.
+
+    A fresh ``random.Random`` is allocated when ``rng`` is omitted so callers
+    that want reproducibility can supply a seeded one.
+    """
+    chooser = rng or random.Random()
+
+    def agent[C: decisions.Choice](
+        _engine: engine_core.Engine,
+        decision: decisions.Decision[C],
+    ) -> C:
+        return chooser.choice(decision.choices)
+
+    return agent

wingspan/agents/cli.py

@@ -0,0 +1,278 @@
+"""Interactive human (stdin/stdout) agent.
+
+The CLI agent walks a human through the offered choices index-by-index.
+The combined ``SetupDecision`` is special-cased: enumerating all 504 legal
+setup combinations on one screen is unusable, so the setup pick is broken
+into three sub-dialogs (cards / foods / bonus) — each driven by an
+arrow-key checkbox/radio widget from ``agents.interactive`` — and the
+human's answer is reassembled back into one of the offered ``SetupChoice``
+instances.
+"""
+
+from __future__ import annotations
+
+import typing
+
+from wingspan import cards, decisions, state
+from wingspan.agents import display, interactive
+from wingspan.engine import core as engine_core
+
+
+def cli_agent() -> engine_core.Agent:
+    """Interactive human agent. Prints prompt and choices, reads index."""
+    interactive.enable_ansi()
+
+    def agent[C: decisions.Choice](
+        engine: engine_core.Engine,
+        decision: decisions.Decision[C],
+    ) -> C:
+        if isinstance(decision, decisions.SetupDecision):
+            # SetupDecision is Decision[SetupChoice], but the type checker
+            # can't propagate that narrowing back onto the bound C — so the
+            # SetupChoice return is cast through.
+            return typing.cast(
+                C,
+                resolve_setup_choice_dialog(
+                    decision,
+                    [b for b in engine.state.tray if b is not None],
+                ),
+            )
+        # The main-action prompt — and the play-bird menu it can open — are the
+        # natural moments to show the full board: the human needs the resource
+        # picture both to pick an action type and to pick which bird to play.
+        if isinstance(
+            decision,
+            (decisions.MainActionDecision, decisions.PlayBirdDecision),
+        ):
+            print()
+            print(
+                display.format_board(
+                    engine.state, engine.state.players[decision.player_id]
+                )
+            )
+        print()
+        print(decision.prompt)
+        player = engine.state.players[decision.player_id]
+        for i, choice in enumerate(decision.choices):
+            print(format_choice_line(i, choice, player))
+        while True:
+            raw = input("choice> ").strip()
+            try:
+                idx = int(raw)
+            except ValueError:
+                print("  enter a number")
+                continue
+            if 0 <= idx < len(decision.choices):
+                return typing.cast(C, decision.choices[idx])
+            print("  out of range")
+
+    return agent
+
+
+def format_choice_line(
+    idx: int,
+    choice: decisions.Choice,
+    player: state.Player,
+    *,
+    show_index: bool = True,
+) -> str:
+    """Render one offered choice line with type-aware extra context.
+
+    Bird- and bonus-card-carrying choices are expanded to show food cost,
+    power text, and scoring conditions respectively — the engine's stored
+    ``label`` is too terse for a human at decision time. A bonus card also
+    gets a second line with how useful it is to ``player`` right now. Other
+    Choice subclasses fall through to ``label`` as-is.
+
+    ``show_index`` controls whether the line is prefixed with a ``  [idx] ``
+    marker; callers that display a bare label out of index order (e.g. the
+    aid advisor's probability-ranked recommendation lines) pass
+    ``show_index=False`` and get the label text with no leading indent.
+    """
+    prefix = f"  [{idx}] " if show_index else ""
+    if isinstance(choice, decisions.PlayBirdChoice):
+        # The board (printed in full above the main-action prompt) already
+        # shows every hand card's stats and power, so a play option only needs
+        # the bird name and target habitat; the costs are follow-up prompts.
+        return f"{prefix}play {choice.bird.name} in {choice.habitat.value}"
+    if isinstance(choice, decisions.FoodPaymentChoice):
+        # One complete payment for the committed play; the parent decision's
+        # prompt already names the bird being paid for.
+        return f"{prefix}pay {display.format_food_pool(choice.payment)}"
+    if isinstance(choice, decisions.BirdChoice):
+        return f"{prefix}{display.format_bird_full(choice.bird)}"
+    if isinstance(choice, decisions.BonusCardChoice):
+        head = f"{prefix}{display.format_bonus(choice.bonus_card)}"
+        return (
+            f"{head}\n      "
+            f"{display.format_bonus_score_now(choice.bonus_card, player)}"
+        )
+    if isinstance(choice, decisions.PlayedBirdChoice):
+        return f"{prefix}{display.format_played_bird(choice.played_bird)}"
+    if isinstance(choice, decisions.DrawSourceChoice):
+        if choice.bird is not None:
+            return f"{prefix}{display.format_bird_full(choice.bird)}"
+        return f"{prefix}Draw from the Deck"
+    return f"{prefix}{choice.display_label()}"
+
+
+def setup_dialog_axes(decision: decisions.SetupDecision) -> tuple[bool, bool]:
+    """Which of the setup dialog's two optional axes the offered choices carry.
+
+    Returns ``(ask_bonus, ask_food)``. Under the split-setup regimes the
+    engine resolves the bonus pick and/or the food pick as separate later
+    decisions, so the offered ``SetupChoice``s come back with that axis
+    pinned to its empty value on every option: ``bonus_card=None`` for a
+    deferred bonus pick, ``kept_foods=()`` for a deferred food pick. This is
+    a sound test for "deferred" because under the non-split regime the
+    candidate enumerator (``setup_model/candidates.py``) always assigns a
+    dealt bonus card to every choice, and the keep-0-cards choice always
+    carries all five foods — so all-``None``/all-empty across *every* choice
+    only happens when the axis is genuinely deferred, never as a byproduct of
+    the non-split enumeration.
+
+    The one other way ``bonus_card`` is ``None`` on every choice is when no
+    bonus cards were dealt at all. That collapses onto the same correct
+    behavior: with an empty ``dealt_bonus`` the dialog already omits the
+    bonus section (``_cli_pick_hand_and_bonus`` returns ``None`` for it), so
+    treating that case as "don't ask" changes nothing observable.
+    """
+    ask_bonus = any(choice.bonus_card is not None for choice in decision.choices)
+    ask_food = any(choice.kept_foods for choice in decision.choices)
+    return ask_bonus, ask_food
+
+
+def resolve_setup_choice_dialog(
+    decision: decisions.SetupDecision,
+    tray: list[cards.Bird],
+) -> decisions.SetupChoice:
+    """Two-step sub-dialog for the combined setup pick, split-aware.
+
+    Step 1 is one screen: keep any subset of the dealt birds, plus — when the
+    offered choices carry a bonus pick (see :func:`setup_dialog_axes`) —
+    choose exactly one bonus card. Step 2 keeps the matching number of foods,
+    but only when the offered choices carry a food pick; otherwise the axis
+    is left at its deferred empty value. This mirrors whichever combination
+    of axes ``decision.choices`` actually varies over — under the split-setup
+    regimes the bonus and/or food pick are resolved by later decisions, so
+    asking for them here would never match any offered choice. The assembled
+    answer is located among ``decision.choices`` and returned. ``tray`` is
+    the face-up bird display, used to gauge bonus-card value.
+    """
+    dealt_cards = decision.dealt_cards
+    ask_bonus, ask_food = setup_dialog_axes(decision)
+
+    print()
+    print(decision.prompt)
+
+    kept_cards, bonus_card = _cli_pick_hand_and_bonus(
+        dealt_cards, decision.dealt_bonus if ask_bonus else [], tray
+    )
+    kept_foods = _cli_pick_kept_foods(kept_cards) if ask_food else ()
+
+    for choice in decision.choices:
+        if (
+            choice.kept_cards == kept_cards
+            and choice.kept_foods == kept_foods
+            and choice.bonus_card == bonus_card
+        ):
+            return choice
+    raise AssertionError(
+        "assembled setup answer did not match any offered SetupChoice: "
+        f"keep={[bird.name for bird in kept_cards]} foods={kept_foods} bonus={bonus_card}"
+    )
+
+
+###### PRIVATE #######
+
+
+def _cli_pick_hand_and_bonus(
+    dealt_cards: list[cards.Bird],
+    dealt_bonus: list[cards.BonusCard],
+    tray: list[cards.Bird],
+) -> tuple[tuple[cards.Bird, ...], cards.BonusCard | None]:
+    """Step 1: keep any subset of birds (each costs 1 food) plus one bonus card.
+
+    Birds and bonus cards share one screen as a two-section form; the bird
+    section is unconstrained (0+) while the bonus section is a radio requiring
+    exactly one pick. Each bonus card shows how many qualifying birds sit in
+    hand vs. the ``tray`` display. When no bonus cards were dealt the bonus
+    section is omitted and ``None`` is returned for it.
+    """
+    name_width = max((len(bird.name) for bird in dealt_cards), default=0)
+    bird_options = [
+        display.format_bird_full(bird, indent="", name_width=name_width)
+        for bird in dealt_cards
+    ]
+    sections = [
+        interactive.Section(
+            title="Keep which birds? (each kept bird costs 1 food)",
+            options=bird_options,
+        )
+    ]
+    live: typing.Callable[[list[set[int]]], list[list[str]]] | None = None
+    if dealt_bonus:
+        bonus_width = max(len(bc.name) for bc in dealt_bonus)
+
+        def render_bonus(selected: list[cards.Bird]) -> list[str]:
+            return [
+                display.format_bonus_with_setup_help(
+                    bc, dealt_cards, tray, selected, bonus_width
+                )
+                for bc in dealt_bonus
+            ]
+
+        sections.append(
+            interactive.Section(
+                title="Keep which bonus card? (choose exactly one)",
+                options=render_bonus([]),
+                mode=interactive.Mode.SINGLE,
+            )
+        )
+
+        # The bonus help line counts selected matching birds, so re-render it
+        # each frame against the live bird-section (index 0) selection.
+        def _live(selections: list[set[int]]) -> list[list[str]]:
+            selected = [dealt_cards[i] for i in selections[0]]
+            return [bird_options, render_bonus(selected)]
+
+        live = _live
+
+    picks = interactive.select_form(
+        sections, header="Step 1 — choose your opening hand:", live_options=live
+    )
+    kept_cards = tuple(dealt_cards[i] for i in picks[0])
+    bonus_card = dealt_bonus[picks[1][0]] if dealt_bonus else None
+    return kept_cards, bonus_card
+
+
+def _cli_pick_kept_foods(
+    kept_cards: tuple[cards.Bird, ...],
+) -> tuple[cards.Food, ...]:
+    """Step 2: check which ``keep_count`` distinct foods to keep.
+
+    ``keep_count`` is ``len(ALL_FOODS) - len(kept_cards)``, since each kept card
+    costs one food off the player's one-of-each starting stash. A live footer
+    shows which of the ``kept_cards`` the current food selection could play
+    immediately. The food order in the returned tuple follows
+    :data:`cards.ALL_FOODS` to match the enumeration the engine offers.
+    """
+    keep_count = len(cards.ALL_FOODS) - len(kept_cards)
+    section = interactive.Section(
+        options=[food.value for food in cards.ALL_FOODS],
+        required_count=keep_count,
+    )
+
+    def _can_play_footer(selections: list[set[int]]) -> list[str]:
+        chosen_foods = [cards.ALL_FOODS[i] for i in selections[0]]
+        return [display.format_can_play(kept_cards, chosen_foods)]
+
+    picks = interactive.select_form(
+        [section],
+        header=(
+            f"Step 2 — keep which {keep_count} food(s)? "
+            f"(you start with one of each)"
+        ),
+        live_footer=_can_play_footer,
+    )
+    return tuple(cards.ALL_FOODS[i] for i in picks[0])