README.md

metadata

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

# 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.