Epic: Add Bots to End-User Games

[tgrunnagle]

Overview

Enable adding already-trained neural network bots and rules-based bots to end-user games. Bots run as a separate Python service (FastAPI) that connects to games like regular WebSocket clients. The Go backend proxies requests to the Bot Service.

Background

This feature allows players to add AI opponents to their games dynamically. The Bot Service manages bot lifecycles, loads trained models from the ModelRegistry, and connects bots to game rooms via WebSocket. Both rule-based bots and trained neural network bots are supported.

Architecture:

Frontend/CLI  --->  Go Backend (proxy)  --->  Bot Service (FastAPI)
                         |                           |
                         |<--- WebSocket ------------|
                         |    (bot joins game)       |

Task Breakdown

Task ID	Title	Dependencies	GitHub Issue #
TASK-001	Neural Network Bot Runner	—	#96
TASK-002	WebSocket Bot Client	TASK-001	#97
TASK-003	Bot Manager	TASK-001, TASK-002	#98
TASK-004	FastAPI Bot Service	TASK-003	#99
TASK-005	Go Backend Bot Proxy	TASK-004	#100
TASK-006	Taskfile & Dependencies	TASK-004, TASK-005	#101

Dependency Graph

#96 (Neural Network Bot Runner)
    |
    v
#97 (WebSocket Bot Client)
    |
    v
#98 (Bot Manager)
    |
    v
#99 (FastAPI Bot Service)
    |
    +--> #100 (Go Backend Bot Proxy)
    |         |
    v         v
#101 (Taskfile & Dependencies)

Acceptance Criteria

• NeuralNetBot runs inference using ActorCriticNetwork and converts actions to BotAction tuples
• WebSocketBotClient connects to game server and forwards game state to bot runner
• BotManager can spawn/destroy bots and load models from ModelRegistry
• FastAPI service exposes /bots/spawn, /bots/{id}, /bots, /bots/models, /health endpoints
• Go Backend proxies POST /api/rooms/{roomId}/bots to Bot Service
• All unit tests pass (task bot2:test:unit, task be:test)
• Manual verification: spawn rule-based bot, spawn neural net bot, both play in game

References

• Design document: squishy-drifting-otter.md
• Related issue: #78 (Add bots to human game)
• Related epic: Epic: ML Reinforcement Learning Bot Training Pipeline #14 (ML Reinforcement Learning Bot Training Pipeline)

[tgrunnagle]

Intake & Clarification

Original Requirements

Source Document: squishy-drifting-otter.md

Feature Summary

Enable adding already-trained neural network bots and rules-based bots to end-user games. Bots run as a separate Python service that connects to games like regular WebSocket clients.

Key Features

• Add bots at game creation time OR dynamically after game starts
• Support both rules-based bots (RuleBasedBot) and trained neural network bots (from ModelRegistry)
• Users can select specific trained model generations
• Frontend only talks to Go Backend - Go Backend proxies requests to Bot Service

Architecture

Frontend/CLI  --->  Go Backend (proxy)  --->  Bot Service (FastAPI)
                         |                           |
                         |<--- WebSocket ------------|
                         |    (bot joins game)       |

Clarifications

Repository & Project

• Target repository: https://github.com/tgrunnagle/go-towerfall
• Issue tracking repo: Same repo
• Parent epic: This issue (Epic: Add Bots to End-User Games #95)
• Common label: feature:add-bots

Scope & Boundaries

• In scope:
  • NeuralNetBot and NeuralNetBotRunner for ML bot inference
  • WebSocketBotClient for bot-game connections
  • BotManager for bot lifecycle
  • FastAPI Bot Service with REST endpoints
  • Go Backend proxy endpoint
  • Taskfile commands and dependencies
  • Unit tests for all new components
• Out of scope:
  • Frontend UI changes (not specified in design)
  • New model training features

Technical Context

• Components affected: bot2/ (Python), backend/ (Go)
• Technical constraints:
  • Use Pydantic v2 patterns
  • Use native Python typing
  • Follow existing bot runner patterns (RuleBasedBotRunner)
  • FastAPI for Python service
  • Go standard HTTP patterns for backend

Dependencies & Integration

• Bot Service must connect to Go Backend via WebSocket
• Go Backend must proxy requests to Bot Service
• ModelRegistry integration for loading trained models

Acceptance & Verification

• All unit tests pass (task bot2:test:unit, task be:test)
• Manual testing: spawn rule-based bot, spawn neural net bot, both play in game
• Integration: bot joins room, receives game state, sends actions