---
title: Mafia
emoji: 🕵️
colorFrom: red
colorTo: yellow
sdk: gradio
sdk_version: 6.18.0
python_version: 3.12.12
app_file: app.py
pinned: false
---

# Mafia

AI-native one-human plus six-AI Mafia game.

## Current Build

Implemented:

- Authoritative seven-player Mafia engine.
- Roles: 2 Mafia, 1 Detective, 1 Doctor, 3 Villagers.
- Classic loop: Night -> Dawn -> Discussion -> Hot Seat -> Vote -> Resolution.
- Private/public view isolation.
- Event-sourced logs and replay summaries.
- Time-to-Talk style non-player `ModeratorAgent`.
- Product `holy_grail` player architecture, with `holy_grail_v4` compatibility alias.
- Online-only Hugging Face ZeroGPU runtime for Mafia Gemma BF16 players and the base Gemma BF16 Time-to-Talk moderator.
- Phaser/Gradio Server game app with onboarding, avatar selection, status updates, discussions, action controls, role reveal, and endgame reveal.
- Hugging Face Space entrypoint.

## Local Development

Use the Conda Python that has Gradio installed:

```bash
PYTHONPATH=src /Users/alfaxad/miniconda3/bin/python3 app.py
```

Then open:

```text
http://127.0.0.1:7860
```

## Tests

```bash
pytest -q
```

## Deterministic Engine Policy Playtests

```bash
PYTHONPATH=src /Users/alfaxad/miniconda3/bin/python3 -m mafia.simulation --games 20 --out-dir reports/playtests
```

## Hugging Face Space

```bash
python app.py
```

Production deployment target:

```text
https://build-small-hackathon-mafia.hf.space
```

The Space uses `src/mafia/models/zerogpu_client.py`, with GPU work wrapped in
`@spaces.GPU` on the default ZeroGPU `large` size.