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
  ├── 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](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`)

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

Quick smoke test command:

```bash
./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