README.md

---
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](https://github.com/ScalerAI/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

```bash
# 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

```bash
# 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