Spaces:
Sleeping
Sleeping
| 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.* | |