README.md

metadata

title: AI Crime Investigation World
emoji: 🔍
colorFrom: blue
colorTo: red
sdk: docker
app_port: 8000

AI Crime Investigation World 🕵️

A multi-agent reinforcement learning environment where an AI detective interrogates suspects and a witness, reviews physical evidence, detects contradictions, and makes an accusation — all within a 15-turn episode.

Built on the OpenEnv framework for standardized RL environment evaluation.

🎯 Hackathon Theme

Theme #1: Multi-Agent Interactions — This environment demonstrates how multiple AI agents with conflicting objectives (detective vs. guilty suspect vs. innocent suspect vs. biased witness) interact in a structured investigation scenario. Each agent has its own reward signal, private knowledge, and behavioral incentives.

Bonus Sub-theme Fit (Halluminate) — The detective acts as a coordinator that orchestrates multiple actors (two suspects + one witness + evidence system) to discover the true culprit under uncertainty. The environment explicitly rewards cross-agent synthesis (contradiction exposure + evidence-backed accusation), matching Halluminate's multi-actor task-achievement objective.

Quick Start

# Install dependencies
pip install -r requirements.txt

# Run the server with interactive dashboard
uvicorn server.app:app --host 0.0.0.0 --port 8000

# Open http://localhost:8000 in your browser

Project Structure

crime_env/                      # Core environment package
  ├── case_generator.py             # Randomized crime scenario generation (with difficulty tiers)
  ├── environment.py                # Step/reset/render RL interface
  ├── agent_prompts.py              # Role-specific system prompts
  ├── consistency_tracker.py        # Semantic contradiction detection
  └── reward_calculator.py          # Multi-agent reward function
server/
  └── app.py                    # OpenEnv-compatible FastAPI server
dashboard.html                  # Interactive investigation dashboard
train_colab.py                  # GRPO training script (Colab / local GPU)
eval_baseline.py                # Baseline vs trained model comparison (§19 demo)
test_one_episode.py             # End-to-end test with scripted agents
Dockerfile                      # HuggingFace Spaces deployment

Features

• Randomized Cases: Criminal identity, evidence, alibis, and witness bias are randomized each episode
• Semantic Contradiction Detection: NLP-based consistency tracking catches real contradictions while ignoring paraphrasing
• Multi-Agent Rewards: Separate reward signals for detective (+17 correct / -8 wrong), suspects, and witness
• Evidence System: Three evidence types (keycard, CCTV, forensic) with type-constrained templates and duplicate-request protection
• Witness Bias: Configurable bias that penalizes false implications of innocent suspects only
• Prior History: Criminal-biased prior records (more convictions, lower trust) for realistic detective briefings
• Interactive Dashboard: Real-time visualization of interrogations, evidence, contradictions, and reward curves

Training

train_colab.py implements a manual GRPO (Group Relative Policy Optimisation) loop — no TRL dependency — with:

• 4-bit quantization (bitsandbytes) for 6 GB VRAM compatibility
• LoRA via PEFT (r=8, q_proj/v_proj) or optional Unsloth fast path
• Frozen reference model on CPU for KL penalty
• Curriculum difficulty: easy (6 turns, 1 suspect) → medium → hard (15 turns, full env) — auto-advances when rolling accuracy ≥ 60 % over last 10 episodes
• Frozen NPC model (separate copy) to prevent representation drift
• Per-episode reward + difficulty + loss logging with smooth training curves
• Checkpoint every 25 episodes, tokenizer saved alongside adapters

# Install dependencies first (Unsloth must be installed separately before the rest)
# pip install "unsloth[colab-new] @ git+https://github.com/unslothai/unsloth.git"
pip install -r requirements-train.txt

# Run training
python train_colab.py

# Smoke test (5 episodes, small settings)
./run_hf_smoke_test.sh

# Baseline vs trained comparison (§19 demo)
python eval_baseline.py

API Endpoints

Endpoint	Method	Description
/	GET	Interactive investigation dashboard
/reset	POST	Start a new episode (OpenEnv)
/step	POST	Execute a detective action (OpenEnv)
/api/run_episode	GET	Run full scripted episode, returns JSON trace
/api/reward_curve	GET	Reward history + smoothed metrics + optional PNG data URL
/api/health	GET	Deployment health check for Space validation

Reward Logic (Detective)

Judging requires coherent reward shaping. The detective reward is event-based:

Event	Delta
Correct accusation	+10.0
Wrong accusation	-10.0 (-12.0 if witness bias is active)
Timeout (no accusation)	-3.0
Contradiction exposed	+2.0
Prior-pattern exploited	+1.5
Evidence request confirms lead	+1.0
Deflection resistance	+0.5
Redundant question	-0.5
Per-turn cost	-0.3 each turn

This combination encourages strategic questioning, contradiction resolution, and evidence-backed accusations rather than random early accusations.

Known Limitations

• Sparse terminal supervision: Even with per-step PPO rewards, the strongest signal is still the terminal accusation outcome, so exploration quality matters a lot early in training.
• Rule-based NPC fallback: The _default_llm_call uses string parsing to identify agent roles. When using the full LLM pipeline this is bypassed.

License

MIT