Project Info
Inspiration
Most AI demos are difficult to compare in any meaningful way. Different prompts, hidden system instructions, and cherry-picked outputs make it hard to tell whether a model actually performed better or just benefited from setup advantages. There is rarely replayable evidence and rarely a way to audit how a result was produced. We built Norbel Arena to make AI vs. AI and human vs. AI evaluation transparent, deterministic, and competitive. We focused on building infrastructure for fair benchmarking. We wanted something that strictly enforces rules, clearly exposes outcomes, and allows anyone to replay a match and verify what happened. We started with Codenames and then implemented Wavelength to demonstrate that this was not a one-off game implementation, but a reusable framework for evaluating social reasoning across multiple environments. What It Does Norbel Arena is a state-based multi-agent competition platform that runs complete matches autonomously and produces structured, replayable results. It enforces legal moves, validates model outputs against strict JSON schemas, handles malformed or invalid responses gracefully, and records turn-by-turn events for later inspection. Every match produces a winner, a termination reason, and detailed statistics, all of which can be replayed through our interface. We currently support Codenames and Wavelength, two games that stress different aspects of social reasoning. Codenames tests hidden information and role asymmetry, where a spymaster has access to a key that operatives do not. The system ensures that only the correct role sees private information and that all moves conform to the rules of the game. Wavelength introduces asymmetric information and multi-round estimation. A “psychic” agent communicates a clue about a hidden position on a spectrum, and a “guesser” agent attempts to infer that position. This stresses calibration, communication clarity, and probabilistic reasoning across multiple rounds. All matches are exposed through a FastAPI backend and a React frontend that support live play, replay controls, transcripts, leaderboards, and persistent report cards with role-aware Elo tracking. The platform supports AI vs. AI competitions as well as human participation. How We Built It Under the hood, Norbel Arena is built around typed, extensible abstractions including Game, State, Move, Observation, Agent, MatchRunner, and Arena. This structure allows us to add new games without rewriting core infrastructure. Deterministic seeded game creation ensures that matches are reproducible. Partial observability is enforced at the state level so that each role only sees what it is allowed to see. We designed strict JSON move contracts for LLM agents and implemented parsing and repair logic to handle imperfect model outputs without breaking game flow. The agent layer is provider-agnostic and supports OpenAI, Anthropic, Perplexity, local models, Nemotron variants, random agents, and human players. This flexibility allows side-by-side comparisons across providers under identical conditions. We also built persistent report cards that track role-specific Elo ratings, since performance can vary significantly depending on whether a model is acting as a clue giver, guesser, or estimator. The system includes robust failure handling for illegal moves, exceptions, and output validation errors. We validated the framework with a comprehensive test suite covering the engine, rules, API, provider integrations, and local model execution paths. Technical Complexity Although the user-facing experience is simple, the underlying system handles deterministic state transitions, strict schema enforcement, multi-provider LLM integration, replayable event logs, and role-aware ranking. Preventing hidden-information leakage while still giving agents enough context to reason correctly required careful design. Ensuring that LLM outputs conform to structured move schemas without constantly breaking gameplay required a layered validation and repair strategy. Supporting both hosted APIs and local models introduced practical runtime and dependency constraints that we had to resolve within a tight time frame. Designing evaluation modes that isolate model quality by role required rethinking traditional Elo approaches to account for asymmetric gameplay. Social Impact As AI systems become more integrated into education, negotiation, customer service, and collaborative decision-making, we need better ways to evaluate how they reason socially and strategically. Many real-world applications involve partial information, role asymmetry, and communication under uncertainty. Hidden-information games provide a compact and controllable way to simulate those dynamics. Norbel Arena provides infrastructure for transparent and reproducible benchmarking of these capabilities. Researchers can compare models fairly under identical conditions. Developers can identify failure modes in communication and coordination. Organizations can demand auditable evaluation before deploying multi-agent systems in sensitive contexts. By focusing on replayability, determinism, and structured evaluation, we aim to raise the standard for how collaborative AI systems are tested and compared. Accomplishments In 36 hours, we designed and implemented a general multi-agent arena framework, shipped two fully integrated social-reasoning games, and delivered an end-to-end product that includes the core engine, API server, and interactive frontend. We built deterministic replayability into the system from the start, implemented role-specific Elo tracking, and created a provider-agnostic agent stack capable of supporting both hosted and local models. The system is backed by a comprehensive test suite to ensure stability and reliability. What’s Next We plan to expand Norbel Arena with additional cooperative and adversarial games that stress different reasoning capabilities. We also want to build large-scale tournament tooling, richer leaderboard analytics, deeper replay diagnostics, and standardized benchmark suites for longitudinal cross-model comparison. Our long-term vision is to use Norbel Arena as infrastructure for safer, more accountable multi-agent AI systems that interact with humans in meaningful, high-stakes environments.
Codenames Arena (Framework + UI)
This repo contains:
- A game framework for state-based games
- A Codenames implementation with partial observability
- A local FastAPI backend for configurable human/AI match sessions
- A React frontend for setup, live play, replay, and report cards
Run Backend
.venv/bin/uvicorn server.main:app --reload --host 0.0.0.0 --port 8000
API endpoints:
POST /api/match/newGET /api/match/{match_id}/observation?player_id=...POST /api/match/{match_id}/moveGET /api/match/{match_id}/eventsGET /api/report-cards
Run Frontend
cd frontend
npm install
npm run dev
Frontend defaults to http://localhost:8000 for API calls.
Override with:
VITE_API_BASE=http://localhost:8000 npm run dev
Play Flow
- Open the frontend in your browser.
- Configure each seat (
RED_SPYMASTER,RED_OPERATIVE,BLUE_SPYMASTER,BLUE_OPERATIVE) as:humanrandomopenaianthropicperplexitylocalnemotron
- Choose a viewer perspective and create a match.
- If your viewer seat is
human, use controls to submit strict JSON-equivalent moves:- GiveClue:
{ "type": "GiveClue", "clue": "animal", "count": 2 } - Guess:
{ "type": "Guess", "index": 13 } - EndTurn:
{ "type": "EndTurn" }
- GiveClue:
- Use replay controls to move backward/forward through turns.
- Inspect report cards for aggregate performance by agent label and game.
Tests
Run all tests:
.venv/bin/pytest -q
Includes API smoke coverage (tests/test_server_api_smoke.py) for:
- create match
- fetch observation
- submit legal move
- fetch events
- run all-AI match to terminal
- retrieve persisted report cards
Notes
- Match sessions are stored in-memory and keyed by
match_id. - Sessions also store immutable
state_historysnapshots so observations can be requested for prior turns (turnquery param) for replay. - Observations are server-shaped per player role. Operative views do not receive hidden assignments.
- Human players are optional. You can run full AI-vs-AI matches and watch/replay from any seat perspective.
- Report cards persist to
server/data/report_cards.json. - Override report-card path with
REPORT_CARD_DB_PATH=/path/to/report_cards.json. .envcan contain API keys for LLM agents and is loaded by the agents utilities.- For
local/nemotronwithbackend="transformers", install local runtime deps (includingprotobuf,sentencepiece, andtiktoken) before running matches. nvidia/llama-3.1-nemotron-70b-instructis intended for served/OpenAI-compatible inference (backend="openai_compat"), whilenvidia/Llama-3.1-Nemotron-Nano-4B-v1.1is the default for in-processbackend="transformers".nvidia/NVIDIA-Nemotron-3-Nano-30B-A3B-FP8may requiremamba-ssm/causal-conv1dfor in-process Transformers loading; on CPU-only environments this is commonly unavailable, so preferbackend="openai_compat"for Nemotron.
Analysis
View
Metric
- 3
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
- JavaScriptIn code
- PythonIn code
- ReactIn code
- TypeScriptIn code
7 of 7 appear in the indexed code.
AI coding agents
No AI coding agent signals were found in this repository.
Detected from committed agent config files and commit authorship. Absence of a signal is not proof an agent was unused.
Codebase size
Source size
339 KB
Source files
67
Counts recognized source files only; vendored directories, binaries and lockfiles are excluded, so this is smaller than the repository on disk.
Repository
anshgandhi4/norbel-arena
79 files · 3.7 MB · @ 3b5f892
Structure
Interface
11 files · 14%Screens, components and styles rendered to the user.
API & routing
6 files · 8%Request entry points: routes, handlers and controllers.
Application logic
42 files · 53%Domain rules, services and shared utilities.
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
- Python74%
- TypeScript20%
- CSS5%
- Markdown1%
- HTML0%
- JavaScript0%
Share of indexed source by file size. Binary and vendored files are excluded.
Dependencies
frontend/package.json
npm · 7- react
- react-dom
- +5 more
requirements.txt
pypi · 7- fastapi
- httpx
- protobuf
- pytest
- sentencepiece
- tiktoken
- uvicorn
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.
This project’s features have not been analysed yet.
Export this project's context (description, README, evidence, key source files) to chat with an AI agent elsewhere.