---
title: Analog Town
emoji: 📻
colorFrom: yellow
colorTo: green
sdk: gradio
app_file: app.py
pinned: false
license: mit
tags:
  - track:wood
  - achievement:offbrand
  - achievement:fieldnotes
---

# 📻 Analog Town

- Demo: https://youtu.be/y-Hc-Iu7YBs
- Post link: https://huggingface.co/blog/build-small-hackathon/analog-town

**A shortwave simulator for fictional minds**

> *You drop a piece of news into the town. The town changes. You tune the dial. The hidden reactions come through the static.*

Analog Town is a whimsical "shortwave radio" interface for simulating how different fictional personas might internally process a piece of news, a story event, or a local proposal. It helps writers, tabletop RPG designers, and community organizers **rehearse perspectives** they might have missed.

## ✨ Key Features

- **🏘️ Create fictional towns** with 3-6 agents, each with values, fears, hopes, and relationships
- **📢 Broadcast events** — drop news into the town and watch how each persona reacts
- **📻 Tune the radio dial** — slide through FM frequencies to intercept different minds
- **🔍 Inspect structured traces** — see exactly what the model noticed, remembered, and felt
- **📦 Export to Hugging Face Hub** — share your simulation traces as inspectable datasets

## 🚀 Quick Start

```bash
# Clone and enter the project
cd analog-town

# Install dependencies
pip install -r requirements.txt

# Set your Hugging Face token
echo "HF_TOKEN=your_token_here" > .env

# Run the app
python app.py
```

Then open `http://localhost:7860` in your browser.

## 🎮 How It Works

1. **Load a town** — Choose from preset towns or create your own
2. **Broadcast an event** — Enter a piece of news (e.g., "The old train station will become a luxury hotel")
3. **Tune the dial** — Slide the frequency knob to intercept different agents' thoughts
4. **Read the monologue** — Each agent produces a short internal monologue
5. **Inspect the trace** — See structured emotional state changes, value conflicts, and likely actions
6. **Export** — Download traces as JSON/JSONL or upload to HF Hub

## 🏗️ Architecture

```
analog-town/
├── app.py              # Gradio UI application
├── schemas.py          # Pydantic data models
├── prompts.py          # Prompt templates
├── model_client.py     # HF Inference API wrapper
├── simulator.py        # State-transition engine
├── export_hub.py       # Export & HF Hub upload
├── theme.py            # Retro scanner CSS theme
├── test_cli.py         # CLI test script
├── sample_towns/       # Preset town configurations
│   ├── graybridge.json
│   ├── neighborhood_council.json
│   ├── port_whisper.json
│   ├── brimstone_hollow.json
│   ├── echo_summit.json
│   └── rustwood.json
├── avatars/            # 2D Pixel-Art Character Avatars
│   ├── default.png
│   ├── elder_man.png
│   ├── elder_woman.png
│   ├── young_man.png
│   ├── young_woman.png
│   ├── middle_man.png
│   ├── middle_woman.png
│   └── soldier_man.png
├── static_ambient.wav  # Atmospheric receiver static sound loop
├── outputs/            # Exported traces
├── requirements.txt
└── README.md
```

## 🧠 How the Simulation Works

Each agent runs through a **typed state transition**:

```
Previous Agent State + Broadcast Event → Updated Agent State + Internal Monologue + Likely Actions
```

The model does NOT simply roleplay. It performs a controlled transition:

1. Interpret the event from this agent's limited perspective
2. Identify which memory or value is activated
3. Compute emotional deltas (trust, anger, fear, hope, curiosity, social_energy)
4. Update the state
5. Produce a short internal monologue
6. Produce likely private and public actions
7. State uncertainty

All outputs are **valid JSON** with structured fields — not free-form text.

## 🎨 The Radio Interface

The UI is designed to feel like an old shortwave radio or police scanner:

- **Amber/green text** on dark background
- **Frequency dial** from 87.0 to 108.0 FM
- **Signal strength indicator** — stronger when tuned closer to an agent
- **Static noise** between stations
- **Retro-futurist typography** with IBM Plex Mono and Crimson Pro

## ⚖️ Safety & Ethics

Analog Town is a **perspective-rehearsal tool**. It does not predict real people.

- Use fictional, composite, or consent-based personas
- Do not use it to manipulate, profile, or target real individuals
- Exports automatically sanitize PII patterns
- All outputs include safety notes

## 📊 Export Format

Exports create a Hugging Face-compatible dataset:

```
analog-town-export/
├── town.json              # Town configuration
├── broadcast_event.json   # The broadcast event
├── agent_traces.jsonl     # One JSON line per agent transition
└── README.md              # Dataset card
```

## ⚡ Build Small Hackathon Compliance

Analog Town has been designed from the ground up to align perfectly with the guidelines of the **Hugging Face Build Small Hackathon** (Whimsical Track):

- **Model Parameter Constraint (<32B)**: Built using the Hugging Face Inference Client configured with a strictly enforced fallback chain: `Qwen/Qwen2.5-7B-Instruct` as primary and `Qwen/Qwen2.5-14B-Instruct` as fallback. All models remain well below the **32B parameter** hackathon limit.
- **Typed State Transition Engine**: Instead of open-ended conversational roleplay, the simulation operates as a structured, deterministic state-transition engine utilizing strict Pydantic schemas, reducing model latency and compute overhead.
- **Client-Side Optimization**: Static receiver loop and audio volume-fading manager operate natively on the browser client, eliminating server-side rendering lag or unnecessary API roundtrips.
- **Interactive Map and Custom Assets**: Dynamic 2D isometric layouts with six distinct town presets and custom circular pixel-art avatars represent each mind as a signal node, bringing the retro shortwave theme to life.

## 📝 License

MIT

---

*Analog Town is not a chatbot. It is a tiny social weather station for fictional worlds.*