Battle Contender: Spring Boot & AI Workshop

Welcome to the Battle Contender workshop template! In this workshop, you will learn how to build an AI-powered agent using Spring Boot 4, Spring AI 2.0, and Java 25. This project is set to interact with the superhero battle arena deployed at https://superhero-battle-arena.barcelonajug.org/ to register a team, analyze game constraints, and use an LLM advisor to pick an optimal hero squad within a budget!

🚀 Workshop Structure

This repository contains the main branch, which serves as the starter project. The backend scaffolding and the HTML frontend (src/main/resources/static/index.html) are already built.

Your goal is to implement the Spring AI layer.

The main branch now includes the multi-phase drafting workflow as TODO scaffolding. The solution-subagents branch contains the full working reference implementation matching all 7 steps, including TodoWriteTool, chat memory, drafting subagents, and the complete orchestration flow.

Before wiring TodoWriteTool, treat MessageChatMemoryAdvisor as a prerequisite in both branches. The todo checklist only remains coherent if the optimization run has a dedicated memory channel scoped by teamId, sessionId, and roundNo.

Workshop Steps

This workshop is meant to be followed in this exact order. The README and the TODO comments in BattleAdvisorService use the same step names.

1. Build the tools Implement the Arena API wrappers in HeroSearchTool.java and ArenaManagementTool.java. Keep them stateless and focused on API access only.

2. Configure BattleAdvisorService Wire those tools into BattleAdvisorService.java, define the drafting strategies, and return the structured response that the UI can render.

3. Add chat memory first Before using TodoWriteTool, configure MessageChatMemoryAdvisor and scope it by teamId, sessionId, and roundNo. This is required so the optimization run has one dedicated memory channel.

4. Add TodoWriteTool on top of chat memory Once chat memory is in place, register TodoWriteTool so the agent can maintain a visible optimization checklist while it works. The intent is: memory stores the conversation for the run, and TodoWrite exposes the current task list inside that same run.

5. Use round-aware hero search The arena v3 API adds allowed roles, genders, races, publishers, and alignments to RoundSpec, plus /api/heroes/search/advanced. In this branch, the model and client already support those fields. The remaining TODO is to make the tools use round-aware advanced search so the drafter starts from candidates that already fit the round.

6. Validate every draft deterministically After the model drafts a squad, validate it against team size, budget, required roles, banned tags, and the new allowed-value constraints before presenting the result or submitting it.

7. Expose multiple draft options Return DraftOptionsResponse so the UI can show several candidate squads and highlight the recommended one.

How To Read The Code

On the main branch, the TODO comments inside BattleAdvisorService are not a second set of phases. They are the same workshop steps above, restated from the point of view of that one service.

Starter Branch Notes

Look for UnsupportedOperationException("TODO:...") in the codebase. The main workshop files are:

• src/main/java/org/barcelonajug/battlecontender/ai/tools/HeroSearchTool.java
• src/main/java/org/barcelonajug/battlecontender/ai/tools/ArenaManagementTool.java
• src/main/java/org/barcelonajug/battlecontender/ai/BattleAdvisorService.java

The main branch keeps these steps as attendee-facing TODOs. The solution-subagents branch implements the same workflow end to end.

You can verify your implementation by running:

./mvnw clean test

⚙️ Setup Instructions

Prerequisites

• Full Java 25 JDK installed on your machine (Java Development Kit, not JRE; standard distributions like Eclipse Temurin 25 or Amazon Corretto 25 work without preview flags).
• An API Key or local model for your preferred AI Provider. See docs/api-keys-setup.md for free options, obtaining keys, and setting spending limits.

Installing Java 25 with SDKMAN (Recommended for macOS / Linux / WSL)

If you do not have SDKMAN installed, run:

curl -s "https://get.sdkman.io" | bash
source "$HOME/.sdkman/bin/sdkman-init.sh"

Once installed, use the repository's .sdkmanrc configuration:

sdk env install
sdk env

Verify your active version:

java -version

(Ensure the output displays version 25)

If you are not using SDKMAN (e.g. Windows native or Homebrew), download a JDK 25 distribution from Adoptium (Eclipse Temurin) and ensure JAVA_HOME points to your JDK 25 directory.

1. Choose Your AI Provider

This project is configured with Maven profiles to support multiple AI providers. You only need to use one.

Tip

Looking for a free option?

• GitHub Models (github-copilot): 100% free with any personal GitHub account (no credit card needed).
• Ollama (ollama): 100% free, running locally on your own machine.

For full instructions on obtaining keys, setting $5 budget limits, and security best practices, read the AI Provider API Keys Guide.

Profile	Provider	Cost / Tier	Model	Required Config
github-copilot	GitHub Models (OpenAI-compatible)	Free	gpt-4o-mini	GITHUB_TOKEN
ollama	Ollama (Local)	Free	llama3.2	Make sure Ollama is running (llama3.2)
vertex-ai	Google Vertex AI	Free Trial / GCP	gemini-2.5-flash	GCP_PROJECT_ID & GCP_LOCATION
openai	OpenAI	Pay-as-you-go	gpt-5.4-mini	OPENAI_API_KEY
anthropic	Anthropic	Pay-as-you-go	claude-3-5-haiku-latest	ANTHROPIC_API_KEY

2. Configure Credentials

Create a .env file in the root of the project to set your credentials (this file is automatically loaded on startup and ignored by git).

For GitHub Models (GitHub Copilot - Recommended Free):

GITHUB_TOKEN=ghp_your-personal-access-token

For Ollama (Local Free):

No credentials needed! Just ensure Ollama is running with llama3.2.

For OpenAI:

OPENAI_API_KEY=sk-proj-your-openai-key

For Google Vertex AI:

GCP_PROJECT_ID=your-project-id
GCP_LOCATION=europe-west1
# Ensure you are authenticated with gcloud: gcloud auth application-default login

For Anthropic:

ANTHROPIC_API_KEY=sk-ant-your-anthropic-key

Important

Safety Reminder: If using paid providers (OpenAI or Anthropic), always configure a $5 hard spend limit in their platform billing dashboard, and delete your API key after the workshop. Detailed steps are in docs/api-keys-setup.md.

3. Run the Application

Use the Maven wrapper to run the project with the desired profile:

./mvnw spring-boot:run -Popenai
./mvnw spring-boot:run -Pvertex-ai
./mvnw spring-boot:run -Panthropic
./mvnw spring-boot:run -Pollama
./mvnw spring-boot:run -Pgithub-copilot

4. Play the Game

Once the application starts, navigate to: http://localhost:8080

This application connects to the live Superhero Battle Arena deployed at https://superhero-battle-arena.barcelonajug.org/:

1. Register your team (the Team ID is persisted in local storage across browser refreshes).
2. Ensure the active Session is loaded.
3. Select an Open Round.
4. Click the "✨ Optimize with AI" button to see your AI code in action!

Good luck, Contender!