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
  ├── 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                  # PPO training script (Google Colab)
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 (Google Colab)

Use train_colab.ipynb for a judge-friendly Colab workflow (install, train, plot rewards, inspect transcripts). The script uses PPO (TRL) with:

• 4-bit quantization for free-tier T4 GPU
• Decoupled frozen base model for NPC calls to prevent representation drift
• Per-episode reward tracking with smoothed training curves
• Milestone transcript capture for before/after behavior demos (episode_transcripts.json)

# In Colab, after uploading files:
!pip install -r requirements-train.txt
!python train_colab.py

Quick smoke test command:

./run_hf_smoke_test.sh

Artifacts generated after training:

• rewards.json (raw reward/label history)
• reward_curve.png (curve image)
• episode_transcripts.json (episodes 1/25/50 by default)

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	-8.0 (up to -10.0 with active bias penalty)
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