Project Info
This project did not submit a demo video on Devpost.
Inspiration
Debate RPG was inspired by the idea that learning debate should feel less like memorizing rules and more like going on an adventure. Many people struggle with argumentation because feedback is intimidating, abstract, or delayed. We wanted to turn that process into something playful: a pixel RPG where every battle helps players practice clearer reasoning, stronger rebuttals, better evidence use, and more effective communication.
What it does
Debate RPG is a Pokémon-style pixel roguelike where players explore an overworld, encounter AI opponents, and win battles by making persuasive arguments. Instead of attacking with swords or spells, players use debate skills like logic, evidence, framing, rebuttal, and emotional appeal. The game helps players build argumentative skills by giving immediate feedback after each round. A judge evaluates how strong each argument was, then translates that into RPG-style damage, momentum, and battle outcomes. This makes communication practice interactive, low-pressure, and fun. At the start, players select an avatar type that represents a debate approach: Logos: logic, evidence, facts, and cause-and-effect reasoning Pathos: emotion, storytelling, stakes, and audience connection Ethos: credibility, authority, trust, and expertise Chaos: disruption, reframing, and flipping assumptions Socratic: questioning, probing, and exposing weak claims Rhetoric: style, framing, delivery, and memorable wording These avatar types are not just cosmetic. They connect directly to the battle system through type advantages, similar to elemental matchups in RPGs. For example, Logos is strong against Pathos, Pathos is strong against Ethos, Ethos is strong against Chaos, Chaos is strong against Logos and Rhetoric, Socratic is strong against Rhetoric and Pathos, and Rhetoric is strong against Logos. This teaches players that different debate strategies work better in different situations. During battles, players type their own argument, choose rhetorical skills, and watch the judge score each round. Stronger arguments deal more damage, while weaker arguments may fail to affect the opponent. Skills like Logical Thrust, Emotional Appeal, Authority Cite, Socratic Probe, Reframe Attack, and Rhetorical Flourish each have their own debate type, MP cost, and damage multiplier. The game also includes RPG systems like HP, MP, levels, attack and defense stats, momentum, party members, gacha-style persona pulls, enemy captures, training, and gambit-style behavior rules for AI teammates. Players can capture defeated debate opponents, add them to their party, train them, and customize how they argue in future encounters.
How we built it
We built the frontend with Vite, React, Phaser 3, and Tailwind to create the pixel RPG overworld and battle interface. The backend uses Python FastAPI to run encounters, debate logic, judging, training, memory, and party systems. The game uses local-first AI models through Ollama, with support for models like Gemma and Qwen. We also built systems for: AI debate opponents AI debate opponents Player-written arguments Player-written arguments Round-by-round judging Round-by-round judging RPG-style damage and HP RPG-style damage and HP Capturing defeated AI agents Capturing defeated AI agents Party management Party management Gambit-style behavior rules Gambit-style behavior rules Training and evolution through debate history Training and evolution through debate history Memory/RAG so agents can learn from past battles Memory/RAG so agents can learn from past battles
Challenges we ran into
One major challenge was making debate feel like a game without losing the educational value. We had to convert abstract debate quality into concrete RPG mechanics like damage, momentum, skills, and victory conditions. We also ran into common AI engineering issues: local model latency, inconsistent judge outputs, empty or low-quality model responses, and coordinating multiple AI agents in one battle. On the technical side, we had to handle real-time WebSocket battle streams, Redis encounter state, Postgres persistence, and frontend/backend integration across several systems. Another challenge was clarity. Debate feedback can easily become too academic or too vague, so we worked on making the judge’s feedback understandable and actionable for players.
Accomplishments we're proud of
We are proud that Debate RPG turns communication practice into a complete interactive game loop. Players can explore, encounter opponents, argue, receive feedback, win battles, capture agents, and improve their team. We are especially proud of connecting debate skills to RPG mechanics in a way that feels natural. A strong rebuttal is not just “correct”; it lands like a powerful move. Weak evidence does not just lose points; it affects the battle. This makes learning argumentation more memorable and engaging.
What we learned
We learned that educational tools work best when feedback is immediate, specific, and tied to action. Debate becomes easier to practice when players can experiment, fail safely, and see exactly why an argument worked or did not work. We also learned that building with local AI requires careful fallback systems, timeouts, and simple UX patterns. The game needs to stay responsive even when models are slow or inconsistent.
What's next
Next, we want to improve the coaching layer so players get clearer suggestions after each debate round. We also want to add richer debate topics, stronger judge models, better skill progression, more enemy types, and more visible growth over time. Long term, Debate RPG could become a full learning platform where players practice debate, public speaking, critical thinking, and persuasive writing through a fun pixel RPG adventure.
Debate RPG — BerkeleyAIHackathon2026
Debate RPG is a local-first creature-collector RPG where the monsters are autonomous debate agents. Explore a tile overworld, meet villagers and rival agents, descend into nearby dungeons, and trigger turn-based argument battles against 1-3 enemy LLM personas. You do not micromanage every line your party says: you collect agents, give them gambit-style behavior rules, train their prompt genomes, and let them argue for you.
The core loop blends Pokémon-style capture, old-school RPG overworld traversal, and AI debate tactics. Winning means making the stronger case, using agent skills at the right moment, remembering prior encounters, and evolving your party into faster, sharper rhetorical specialists. The stack runs locally with Ollama by default, with optional hosted model keys for lower-latency fallback providers.
Stack
- Frontend: Vite + React + Phaser 3 (overworld) + Tailwind. (
apps/web) - Backend: Python FastAPI — agents, debate engine, RL training, hybrid RAG. (
apps/api) - Models: local-first gateway → Ollama (Gemma 3 / Qwen) with Claude/OpenAI pluggable.
- Data: Postgres + pgvector (memories/RAG), Redis (live encounter cache).
Quickstart
pnpm install:game
pnpm game:start
pnpm install:game installs workspace dependencies, prepares .env, pulls and
builds Docker dependencies, and opens API-key pages for any missing optional
hosted model providers. The game still runs fully local with Ollama if you leave
those keys blank.
pnpm game:start starts Postgres, Redis, Ollama, the FastAPI server, and the
Vite/Phaser web client. It also pulls the default Ollama models and opens
http://localhost:5173. API docs are available at http://localhost:8000/docs.
Useful commands:
pnpm install:game --no-open # install without opening API-key pages
pnpm game:start --no-open # start services and print the game URL
pnpm game:start --skip-model-pull # start faster if models are already local
pnpm logs # follow Docker service logs
pnpm down # stop the local stack
Hosted Model Fallbacks
The API gateway can route battle actors and judges through fast hosted providers
with a local Ollama fallback. Put provider keys only in the ignored root .env
file. Latency-first defaults can use GROQ_API_KEY, CEREBRAS_API_KEY,
GEMINI_API_KEY, and OPENROUTER_API_KEY; ANTHROPIC_API_KEY and
OPENAI_API_KEY are available for explicit provider routing. .env.example
intentionally contains placeholders only.
Default latency-first candidates are configured with:
GATEWAY_ACTOR_CANDIDATES=groq/llama-3.1-8b-instant,cerebras/llama-3.3-70b,gemini/gemini-2.5-flash-lite,openrouter/openrouter/free,ollama/gemma3:1b
GATEWAY_JUDGE_CANDIDATES=groq/llama-3.3-70b-versatile,cerebras/llama-3.3-70b,gemini/gemini-2.5-flash,ollama/gemma3:1b
Use the Pareto pseudo-models from code paths that should prefer the fastest acceptable provider:
await gateway.complete(messages, model="pareto-actor")
await gateway.complete(messages, model="pareto-judge", json_mode=True)
To refresh the in-process benchmark frontier, run from apps/api:
uv run python -m app.scripts.bench_models --role actor --runs 3
uv run python -m app.scripts.bench_models --role judge --runs 3
The redacted runtime status is available at GET /api/models/pareto.
Battle Harness Training
Run a small prompt-genome loop that trains both the party agent and the enemy agent against each other. The loop uses the Pareto actor model by default, scores latency first, and keeps only mutations that clear quality/reliability floors.
cd apps/api
uv run python -m app.scripts.run_battle_training --cycles 1 --rounds 1 --variants 1 --model pareto-actor
The runner prints JSON with party/enemy score deltas, accepted mutation ops, latency measurements, and final genomes. It does not fine-tune weights and does not print provider secrets.
Encounter pacing is controlled by BATTLE_DAMAGE_MULTIPLIER (default 1.0).
Raise it to shorten battles, lower it if playtests feel too abrupt.
Layout
apps/web/ Vite + React + Phaser
apps/api/ FastAPI (gateway, debate, memory, training, party, routers, db)
packages/shared/ shared TS enums + generated API types
infra/ docker-compose, postgres init, ollama model pull
prompts/ plan files + per-workstream subagent briefs
memories/ in-repo agent memory log (handoff between waves/sessions)
See prompts/ok-claude-use-toasty-pascal.md for the full build plan.
Analysis
View
Metric
- 112
- 71
- 3
- 2
Figures cover GitHub contributors during the hackathon window. A co-authored commit counts in full for each author, so per-member totals add up to more than the whole-team figures.
Technology
- CSSIn code
- FastAPIIn code
- HTMLIn code
- PythonIn code
- ReactIn code
- RedisIn code
- SQLIn code
- Tailwind CSSIn code
- TypeScriptIn code
- DockerClaimed
- Google GeminiClaimed
- OllamaClaimed
- OpenAIClaimed
9 of 13 appear in the indexed code. 4 claimed on Devpost could not be matched to code, which may simply mean the tool leaves no trace in the repository.
AI coding agents
- Claude CodeCommits
Detected from committed agent config files and commit authorship. Absence of a signal is not proof an agent was unused.
Codebase size
Source size
2.3 MB
Source files
318
Counts recognized source files only; vendored directories, binaries and lockfiles are excluded, so this is smaller than the repository on disk.
Repository
NicoV7/BerkeleyAIHackathon2026
624 files · 4.6 MB · @ 92ee01c
Structure
Interface
36 files · 6%Screens, components and styles rendered to the user.
API & routing
371 files · 59%Request entry points: routes, handlers and controllers.
Application logic
31 files · 5%Domain rules, services and shared utilities.
Data & schema
3 files · 0%Schema definitions, migrations and data access.
Supporting
Layers are inferred from where files sit in the tree, not from reading the code. A project that names its directories unconventionally will read oddly here — open the file browser to check anything the diagram implies.
Languages
- Python59%
- TypeScript27%
- Markdown7%
- YAML5%
- CSS1%
- Shell0%
- Other (2)0%
Share of indexed source by file size. Binary and vendored files are excluded.
Dependencies
apps/web/package.json
npm · 22- @debate/shared
- @tanstack/react-query
- phaser
- react
- react-dom
- react-router-dom
- tone
- zustand
- +14 more
apps/api/pyproject.toml
pypi · 20- asyncpg
- fastapi
- greenlet
- httpx
- json-repair
- numpy
- pgvector
- pydantic
- pydantic-settings
- python-json-logger
- redis
- redisvl
- sqlmodel
- uvicorn[standard]
- websockets
- +5 more
Declared in the repository’s manifests at the indexed commit. A declared package is not proof it is used, and runtime dependencies are listed first.
Feature verification
AI judge scores each round and translates argument quality into RPG damage/momentumVerified
A judge evaluates argument strength, translating it into RPG-style damage, momentum, and battle outcomes
Claimed on Devposthigh confidenceapps/api/app/debate/judge.py:209— score_round calls an LLM judge with a rubric, parses JSON scores, falls back to heuristic scoringapps/api/app/debate/damage.py:103— compute_damage converts judge score plus momentum/type/skill multipliers into integer HP damage
Battle harness training script (run_battle_training)Verified
Run a small prompt-genome loop that trains party and enemy agents against each other via run_battle_training
Claimed on readmemedium confidenceapps/api/app/training/battle_loop.py— Battle training loop module matching the described script's purposeapps/api/app/training/selfplay.py— Self-play scoring used by the training loop
Capture defeated debate opponents into partyVerified
Players can capture defeated debate opponents and add them to their party
Claimed on Devposthigh confidenceapps/api/app/routers/debate.py:286— EncounterResult.capture triggers coin award and capture handling on battle endapps/api/app/routers/runs.py:52— _split_party_captured projects player-owned monsters into party vs captured roster
Frontend stack: Vite + React + Phaser 3 + Tailwind, with Zustand/TanStack Query/React RouterVerified
Frontend built with Vite, React, Phaser 3, and Tailwind
Claimed on readmehigh confidenceapps/web/package.json— Lists phaser ^4.2.0, react-router-dom, zustand, @tanstack/react-query, tone as dependencies
Gacha-style persona pullsVerified
Gacha-style persona pulls
Claimed on Devposthigh confidenceapps/api/app/routers/gacha.py— Dedicated gacha routerapps/web/src/ui/GachaScreen.tsx— Frontend gacha pull screen
Gambit-style behavior rules for AI teammatesVerified
Give agents gambit-style behavior rules, let them argue for you
Claimed on readmehigh confidenceapps/api/app/debate/gambits.py:1— FF12-style gambit rule engine evaluating condition/action DSL against battle stateapps/web/src/ui/GambitEditor.tsx— Frontend UI for editing gambit rules
Local-first LLM gateway (Ollama/Gemma/Qwen) with hosted fallback providers and Pareto latency-first routingVerified
Local-first AI models via Ollama with Gemma/Qwen support; hosted fallbacks via Groq/Cerebras/Gemini/OpenRouter; pareto-actor/pareto-judge pseudo-models
Claimed on readmehigh confidenceapps/api/app/gateway/gateway.py— Central LLM gateway moduleapps/api/app/gateway/candidates.py:54— HOSTED_PROVIDERS = groq/cerebras/gemini/openrouter routed through hosted_adapter, with ollama local fallbackapps/api/app/gateway/pareto.py:1— Latency-first Pareto model selection with in-process benchmark cache, ACTOR/JUDGE roles
Memory/RAG so agents learn from past battles (hybrid pgvector + trigram)Verified
Memory/RAG so agents can learn from past battles; hybrid-rag-over-postgres/redis
Claimed on Devposthigh confidenceapps/api/app/memory/retriever.py:1— Hybrid retriever combining pgvector cosine similarity and trigram keyword search via RRFapps/api/app/memory/embeddings.py— Embedding generation for memory storageapps/api/app/memory/redis_index.py— Redis-backed memory index
Model benchmarking script and GET /api/models/pareto status endpointVerified
bench_models script refreshes the benchmark frontier; redacted runtime status at GET /api/models/pareto
Claimed on readmemedium confidenceapps/api/app/training/benchmark.py— Benchmark module backing the bench_models scriptapps/api/app/routers/models.py— Router likely exposing /api/models/pareto status endpointapps/api/app/gateway/pareto.py:40— BenchResult dataclass storing latency/quality/json-compliance stats used by the status endpoint
Named debate skills with MP cost and damage multiplier (Logical Thrust, Emotional Appeal, Authority Cite, Socratic Probe, Reframe Attack, Rhetorical Flourish)Verified
Skills each have their own debate type, MP cost, and damage multiplier
Claimed on Devposthigh confidenceapps/api/app/skills/logical_thrust.md— Skill file with mp_cost/power front-matterapps/api/app/skills/emotional_appeal.md— Skill file presentapps/api/app/skills/authority_cite.md— Skill file presentapps/api/app/skills/socratic_probe.md— Skill file presentapps/api/app/skills/reframe_attack.md— Skill file presentapps/api/app/skills/rhetorical_flourish.md— Skill file presentapps/api/app/debate/skill_engine.py:218— Parses mp_cost, power, and damage-related modifiers from each skill's front-matter
Party management UI/backendVerified
Party members, training, customization of how captured agents argue
Claimed on Devposthigh confidenceapps/web/src/ui/PartyScreen.tsx— Frontend party management screenapps/api/app/routers/party.py— Backend party listing/route ownership
Pixel RPG overworld exploration with tile-based movementVerified
Players explore a tile overworld with an overworld scene, NPCs, and dungeons
Claimed on readmehigh confidenceapps/web/src/game/OverworldScene.ts— Phaser overworld scene implementationapps/web/src/game/WorldSim.ts— World simulation logic for overworld traversalapps/api/app/world/npcs.py— NPC generation backend
Real-time WebSocket battle streamingVerified
Real-time WebSocket battle streams; websocket-debate-streaming
Claimed on Devposthigh confidenceapps/api/app/routers/debate.py— WebSocket endpoint for debate encountersapps/web/src/ws/useEncounterStream.ts— Frontend hook consuming the WebSocket encounter stream
Redis encounter state cache and Postgres persistenceVerified
Redis encounter state, Postgres persistence
Claimed on readmehigh confidenceinfra/docker-compose.yml:1— docker-compose defines postgres (pgvector/pgvector:pg16) and presumably redis servicesapps/api/app/memory/redis_index.py— Redis-backed memory/encounter cache module
RPG stats: HP, MP, levels, attack/defenseVerified
RPG systems like HP, MP, levels, attack and defense stats
Claimed on Devposthigh confidenceapps/api/app/debate/damage.py:109— compute_damage takes attacker_level/defender_level, attacker_atk/defender_def as inputsapps/api/app/party/progress.py— Handles post-capture progression (leveling)
Six avatar/debate types (Logos, Pathos, Ethos, Chaos, Socratic, Rhetoric) with type advantage chartVerified
Avatar types connect to battle system via type advantages, e.g. Logos strong vs Pathos, etc.
Claimed on Devposthigh confidenceapps/api/app/debate/damage.py:38— DEFAULT_TYPE_CHART implements exactly the described matchups (LOGOS>PATHOS 1.5x, PATHOS>ETHOS, ETHOS>CHAOS, CHAOS>LOGOS/RHETORIC, SOCRATIC>RHETORIC/PATHOS, RHETORIC>LOGOS)apps/api/app/party/archetypes.py:146— Defines LOGOS/PATHOS/ETHOS/CHAOS/SOCRATIC/RHETORIC domain descriptionsapps/web/src/ui/StartMenu.tsx:61— AVATAR_MODES selection UI keyed by the six types
Test coverage: pytest/pytest-asyncio backend, Vitest/Testing Library frontend, Playwright e2eVerified
pytest, pytest-asyncio, vitest, react-testing-library, playwright listed under Built With
Claimed on Devposthigh confidenceapps/api/pyproject.toml— dev deps include pytest, pytest-asyncio, pytest-cov, ruffapps/web/package.json— vitest, @testing-library/react, @testing-library/jest-dom presentapps/web/e2e/overworld-to-debate.spec.ts— Playwright e2e spec covering overworld to debate flow
Training and evolution of prompt genomes through debate history (GEPA/GRPO-style)Verified
Training and evolution through debate history; gepa/grpo-style-training-paths
Claimed on Devpostmedium confidenceapps/api/app/training/genome.py:1— Genome read/mutate/apply system for prompt DNA of a debaterapps/api/app/training/gepa.py:1— run_gepa: tries DSPy GEPA optimizer, falls back to a hand-rolled reflective mutation loop (DSPy is optional and not installed in the running container per its own docstring)apps/api/app/training/grpo_hitl.py— GRPO-related training module present
Turn-based debate battles vs 1-3 enemy LLM personasVerified
Trigger turn-based argument battles against 1-3 enemy LLM personas
Claimed on readmehigh confidenceapps/api/app/debate/orchestrator.py— Debate orchestrator coordinates battle turns and combatantsapps/web/src/ui/BattleDebateView.tsx— Frontend battle debate view UI
Coaching/feedback layer giving players actionable suggestions after each roundCode-supported
Improve the coaching layer so players get clearer suggestions after each debate round (What's next) and immediate feedback (What it does)
Claimed on Devpostmedium confidenceapps/api/app/debate/coach.py— Dedicated coach module exists, but this was a listed 'what's next' aspiration, so functionality maturity is unconfirmed
DSPy-based GEPA/GRPO training pathsCode-supported
gepa/grpo-style-training-paths and dspy listed under Built With
Claimed on Devpostmedium confidenceapps/api/pyproject.toml— dspy-ai is an optional extra ('training' group), not a core dependencyapps/api/app/training/gepa.py:3— Code explicitly notes DSPy is optional/not installed in the running container and the hand-rolled fallback is the primary deliverable, so the DSPy path itself is unconfirmed end-to-end
One-command local stack bootstrap (pnpm install:game / pnpm game:start) that provisions Docker, Ollama models, and opens the gameCode-supported
pnpm install:game and pnpm game:start start Postgres, Redis, Ollama, FastAPI, and Vite/Phaser client and pull default Ollama models
Claimed on readmelow confidenceinfra/docker-compose.yml:1— docker-compose exists defining the service stack, but the described pnpm scripts (install:game/game:start) and their full orchestration behavior were not directly inspectedscripts— Repo has a top-level scripts/ directory likely backing these pnpm commands
An AI agent derived these features from the project’s Devpost page and readme, then searched the code for each one. Verified features are backed by cited code; claimed-only features had no supporting code, which is not by itself proof a feature is missing.
Export this project's context (description, README, evidence, key source files) to chat with an AI agent elsewhere.