Project Info

AIRA (AI Room Arena)

Inspiration

We asked: What if your favorite anime characters could hang out in the same chat room and actually talk to each other? Inspired by the distinct voices of Saitama, Light Yagami, Sasuke Uchiha, etc., we built a space where AI doesn’t just reply, it participates.

What it does

Real-time multiplayer chat where users and AI anime personas converse together. Users create rooms, pick characters, and watch bots jump in based on context, mentions, and moral dilemmas. “Good vs Evil” debate mode where aligned bots argue before synthesizing an answer. Name-mention detection (partial names like “Sasuke” trigger replies).

How we built it

Frontend React + Vite, Tailwind, React Router WebSockets for live, bidirectional updates Backend FastAPI + Uvicorn; WebSocket hub for multi-user rooms LLM integration (OpenAI/compatible) for character-specific outputs AI Architecture Persona prompts in bot_personas.py Orchestrator with should_bot_respond(), moral-dilemma detection, cooldowns/limits Lightweight memory for user facts High-level flow

Challenges we ran into

“Wrong Bot” bug: Saitama always appeared. Fix: Send authoritative room_state on connect; frontend hydrates from it. Python env issues (ModuleNotFoundError: uvicorn). Fix: Virtualenv + pinned requirements. CORS mismatches (ports 5173 vs 5174). Fix: Allow both localhost/127.0.0.1 ports. Name mention detection too strict. Fix: Split names; match parts ≥3 chars. LLM output inconsistency. Fix: Robust fallbacks: JSON→content→raw→default.

Accomplishments we're proud of

Bots that feel “in-character” and join organically instead of spamming. Smooth, truly real-time multi-user rooms with synchronized bot add/remove. Moral-dilemma debate mode that yields richer, balanced answers. Full CRT effect using CSS only (no JS, minimal perf cost). Guardrails (cooldowns, message caps, context checks) for stable autonomy.

What we learned

Prompt engineering is iterative—tight prompts keep voice without rigidity. WebSocket state must be backend-authoritative; hydrate clients on connect. Autonomy needs constraints—knowing when not to speak matters. CSS can carry aesthetics (scanlines, flicker, vignette) with negligible overhead.

What's next

Character voice messages with TTS/voice cloning Reactive sprite animations and emotions Battle/Debate mode with user scoring and ladders Custom character creator for user-defined personas Mobile optimization for small screens and touch gestures

Multichat — Multiplayer AI Group Chat

Real-time multi-user chat with a configurable AI character powered by FastAPI, WebSockets, and the JLLM API.

Features

Real-time WebSocket chat
Single shared room (multiple rooms supported)
Configurable AI persona (backstory, tone, behavior)
Turn-taking: AI responds to @mentions, questions, or proactively when quiet
Structured JSON responses from LLM
In-memory state with rolling history window

Quick Start

1. Install Dependencies

python -m venv .venv
.\.venv\Scripts\Activate
pip install -r requirements.txt

2. Run the server

Option A: Using the run script (easiest)

.\run.ps1

Option B: Manual command

$env:PYTHONPATH = "d:\Goonengine\multichat"
python -m uvicorn app.main:app --reload --host 0.0.0.0

Option C: Using Make

make run

4. Open the app

Navigate to http://localhost:8000

Enter your name and room ID (default: "main")
Click Join
Send messages in the chat
Mention @Bot to get AI responses

Note: The API key is hardcoded to calhacks2047 as specified. To override, set the JLLM_API_KEY environment variable before running.

Docker

Build and run:

docker build -t multichat .
docker run -p 8000:8000 multichat

Or with docker-compose:

docker-compose up --build

Testing

pytest -q

API Details

The app uses the JLLM API at https://janitorai.com/hackathon/completions with:

Authorization: calhacks2047 (or your custom key from .env)
Content-Type: application/json
Payload: {"messages": [...], "temperature": 0.7, ...}

Project Structure

multichat/
  app/
    main.py           # FastAPI app & WebSocket endpoint
    config.py         # Settings & defaults
    schemas.py        # Pydantic models
    llm_client.py     # JLLM API client
    persona.py        # System prompt renderer
    state.py          # In-memory room state
    orchestrator.py   # Turn-taking & response logic
    websocket.py      # Connection manager
    summarizer.py     # History summarization
    utils.py          # Helpers
  web/
    index.html        # Chat UI
    app.js            # WebSocket client
    styles.css        # Styling
  tests/              # Pytest tests
  Dockerfile
  docker-compose.yml
  Makefile
  requirements.txt

How It Works

Join a room: Connect via WebSocket at /ws/{room_id}
Send messages: Broadcast to all users in real-time
AI responds when:
- You mention @Bot
- You ask a question
- Room is quiet for 45s (proactive)
Persona controls: Update AI backstory, tone, and behavior via UI

Enjoy chatting!

Analysis

Compare with all teams

View

Metric

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

Found in codeClaimed only

CSSIn code
FastAPIIn code
HTMLIn code
JavaScriptIn code
PythonIn code
ReactIn code
Tailwind CSSIn 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

184 KB

Source files

Counts recognized source files only; vendored directories, binaries and lockfiles are excluded, so this is smaller than the repository on disk.