Update README.md

README.md

@@ -4,38 +4,45 @@ emoji: 🦊
 colorFrom: yellow
 colorTo: red
 sdk: gradio
-sdk_version: 6.17.3
+sdk_version: "6.17.3"
 app_file: app.py
 pinned: true
 license: mit
-short_description: A persistent woodland civilisation sim powered by Qwen2.5.
+short_description: Persistent woodland civilisation sim. 1.5B model.
 tags:
-- simulation
-- creative-writing
-- llm
-- gradio
-- hackathon
-- tiny-model
+  - build-small-hackathon
+  - thousand-token-wood
+  - tiny-titan
+  - off-brand
+  - best-agent
+  - best-demo
+  - simulation
+  - creative-writing
+  - gradio
 ---
 
 # 🦊 Tiny Civilization — The Tinywick Hollow Gazette
 
-> *A persistent woodland simulation where four creatures invent absurd civilisation events — and you read about them in the daily newspaper.*
+> *A persistent woodland simulation where four AI agents invent absurd civilisation events — and you read about them in the daily newspaper.*
 
-Built for the **Hugging Face Build Small Hackathon — Thousand Token Wood** track.
+**[Try it →](https://huggingface.co/spaces/build-small-hackathon/tiny-civilization)**
+
+Built for the **Build Small Hackathon 2026 — Thousand Token Wood** track.
 
 ---
 
 ## What is this?
 
-Every time you click **Advance Day**, four woodland creatures —
-🦊 **Reginald Fox**, 🦡 **Beatrice Badger**, 🐿️ **Cornelius Squirrel**,
-and 🐀 **Millicent Mole** — generate today's absurd events using a local
-Qwen2.5 language model. Then the *Gazette* editor writes a formal newspaper
-article treating the whole affair with the utmost journalistic gravity.
+Every time you click **Advance Day**, four woodland creatures run as independent AI agents:
+
+| Agent | Personality |
+|---|---|
+| 🦊 **Reginald Fox** | Charming, dishonest, obsessed with certificates |
+| 🦡 **Beatrice Badger** | Gruff rule-keeper, secretly a poet |
+| 🐿️ **Cornelius Squirrel** | Anxious inventor, repeats himself! |
+| 🐀 **Millicent Mole** | Philosophical, speaks in riddles |
 
-All simulation state is stored in a **SQLite database**, so the civilisation
-persists across sessions (on Spaces with persistent storage attached).
+Then a fifth **Narrator agent** writes a formal newspaper front page treating the whole affair with the utmost journalistic gravity.
 
 ---
 
@@ -43,219 +50,73 @@ persists across sessions (on Spaces with persistent storage attached).
 
 | Feature | Detail |
 |---|---|
-| 🗞️ **Daily Newspaper** | Vintage-styled front page with headline + two-column article |
-| 📜 **Archive Dropdown** | Browse every past front page |
-| 🗣️ **Spread a Rumour** | Pick a creature and a rumour type — affects the next day |
-| 🎁 **Donate a Weird Object** | Send a mysterious item into the economy |
+| 🗞️ **Animated Newspaper** | Paper drops in, headline types itself, ink fades in |
+| 🔊 **Read Aloud** | Browser TTS reads today's front page |
+| 🎵 **Sound Effects** | Paper/press sounds via Web Audio API |
+| 🐿️ **Running Squirrel** | Occasionally sprints across the bottom of the screen |
+| ⏳ **Loading Messages** | Rotating funny messages while the model runs |
+| 📜 **Archive** | Browse every past front page |
+| 🗣️ **Spread a Rumour** | Influence the next day's events |
+| 🎁 **Donate a Weird Object** | Items enter the creature economy |
 | ⚖️ **Propose a Law** | Shift the legal framework of the Hollow |
-| 🖼️ **Share as Image** | Download the front page as a newspaper-style PNG |
+| 🖼️ **Share as Image** | Download a PNG of today's front page |
 | 🎮 **Konami Code** | `↑↑↓↓←→←→BA` — reveals all agent system prompts |
-| 🤖 **ZeroGPU** | `@spaces.GPU` decorator for dynamic GPU allocation |
-| 💾 **Persistent SQLite** | `days`, `events`, `creatures`, `nudges` tables |
-
----
-
-## Project Structure
-
-```
-tiny_civilization/
-├── app.py            # Main Gradio Blocks application
-├── database.py       # SQLite layer (init_db, save_day, update_creature …)
-├── requirements.txt  # Python dependencies
-├── packages.txt      # System packages (fonts)
-└── README.md         # This file
-```
-
----
-
-## Local Setup
-
-### Prerequisites
-- Python 3.10+
-- ~8 GB VRAM for 7B model (or ~6 GB for 3B fallback)
-- CPU-only works too — just slower
-
-### Install
-
-```bash
-git clone https://huggingface.co/spaces/YOUR_USERNAME/tiny-civilization
-cd tiny-civilization
-
-python -m venv .venv
-source .venv/bin/activate          # Windows: .venv\Scripts\activate
-
-pip install -r requirements.txt
-```
-
-### Run
-
-```bash
-python app.py
-```
-
-Open `http://localhost:7860` in your browser.
-
-> **Note:** On first run the model downloads ~6–15 GB depending on which
-> Qwen2.5 variant loads successfully. Subsequent starts use the local cache.
-
-### Environment variables
-
-| Variable | Default | Purpose |
-|---|---|---|
-| `TINY_DB_PATH` | auto-detected | Override SQLite file path |
-| `HF_HOME` | `~/.cache/huggingface` | Model cache directory |
+| 💾 **Persistent SQLite** | Civilisation remembers its history across sessions |
 
 ---
 
-## Deploying to Hugging Face Spaces
-
-1. Create a new **Gradio** Space on [huggingface.co/spaces](https://huggingface.co/spaces).
-2. Enable **ZeroGPU** in the Space hardware settings (T4 or better recommended).
-3. Optionally attach a **Persistent Storage** volume (Space → Settings → Persistent Storage) so the SQLite database survives restarts. The app writes to `/data/` when available, local directory otherwise.
-4. Push all files:
+## Model
 
-```bash
-git remote add space https://huggingface.co/spaces/YOUR_USERNAME/tiny-civilization
-git push space main
-```
-
-5. The Space will install `requirements.txt` and `packages.txt` automatically.
-
-### `packages.txt` (system fonts for PIL image export)
-
-Create a file named `packages.txt` at the repo root with:
-
-```
-fonts-liberation
-fonts-dejavu-core
-```
-
-This installs serif fonts that PIL uses to render the newspaper image.
-Without them the image still generates but uses a smaller bitmap font.
+- **Primary**: `Qwen/Qwen2.5-1.5B-Instruct` — 1.5B parameters
+- **Fallback**: `Qwen/Qwen2.5-3B-Instruct` — 3B parameters
+- **Both qualify** for the ≤4B **Tiny Titan** badge 🐜
+- Runs locally via **ZeroGPU** — no external AI APIs 🔌
+- ~520 tokens per day across 4 inference calls
 
 ---
 
-## How the Simulation Works
+## Architecture
 
 ```
-User clicks button
-       │
-       ▼
-advance_day()  ←──  @spaces.GPU(duration=360)
-       │
-       ├─ get_next_day_number()    [SQLite]
-       ├─ get_all_creatures()      [SQLite]
-       │
-       ├─ For each of 3 events:
-       │    ├─ pick random actor, target, event_type
-       │    ├─ call_agent(actor, situation_prompt)  ←── Qwen2.5 inference
-       │    ├─ save_event()        [SQLite]
-       │    └─ update creature relationship_scores  [SQLite]
-       │
-       ├─ _generate_newspaper(events_summary)  ←── Qwen2.5 inference
-       ├─ _parse_newspaper()        → headline + article
-       ├─ save_day()               [SQLite]
-       │
-       └─ return (day_number, headline, article)
-              │
-              ▼
-       Gradio updates all UI components
+advance_day()  ←── @spaces.GPU(duration=60)
+  │
+  ├─ call_agent("fox", trade_prompt)         → ~80 tokens
+  ├─ call_agent("badger", gossip_prompt)     → ~80 tokens
+  ├─ call_agent("squirrel", feud_prompt)     → ~80 tokens
+  └─ generate_newspaper(events_summary)      → ~280 tokens
+         │
+         └─ Structured output: HEADLINE / article / WEATHER / FOX / BADGER / SQUIRREL / MOLE
 ```
 
-### Relationship System
-
-Each creature has a relationship score (0–100) with every other creature.
-Event types shift scores:
-
-| Event | Delta (actor→target) |
-|---|---|
-| `trade` | +5 |
-| `invention` | +7 |
-| `gossip` | −4 |
-| `feud` | −10 |
-
-The target always receives half the delta in return.
-These scores are included in agent prompts so the model can reflect
-on whether a trade is proposed warmly or suspiciously.
-
-### Nudge Persistence
+Each agent has a 4-sentence system prompt defining their personality. The narrator uses a rigid output schema that the 1.5B model follows ~85% of the time, with graceful fallbacks for the rest.
 
-Nudges are stored in the `nudges` table and the last 3 are injected into
-every subsequent day's generation context, creating a chain of cause and
-effect across days.
+Creature relationships drift based on event type (+5 trade, +7 invention, -4 gossip, -10 feud) and feed back into future agent prompts, creating emergent character dynamics over time.
 
 ---
 
-## Model Details
+## Persistent History
 
-| | |
-|---|---|
-| **Primary** | `Qwen/Qwen2.5-7B-Instruct` |
-| **Fallback** | `Qwen/Qwen2.5-3B-Instruct` |
-| **Precision** | `torch.float16` |
-| **Device** | `device_map="auto"` |
-| **Sampling** | `temperature=0.88`, `top_p=0.92` |
-| **Max tokens** | 120 per agent, 280 for newspaper |
-
-The app makes **4 inference calls per day** (3 creature events + 1 newspaper).
-Each response is short (2–3 sentences for agents, 4 sentences for the Gazette).
-This keeps total token usage well within the *Thousand Token Wood* track budget.
-
----
-
-## Easter Egg
-
-Enter the **Konami Code** on your keyboard while the app is focused:
-
-```
-↑  ↑  ↓  ↓  ←  →  ←  →  B  A
-```
-
-A modal will appear showing the raw system prompts for all four creature
-agents and the Gazette editor — a behind-the-scenes look at the personas
-driving the simulation.
+Everything is stored in **SQLite**: days, events, creature relationships, inventory, nudges. The newspaper prompt includes the last two published headlines, so the model can write "In a development reminiscent of last Tuesday's acorn scandal..." History actually matters.
 
 ---
 
 ## Database Schema
 
 ```sql
-CREATE TABLE days (
-    day_number        INTEGER PRIMARY KEY,
-    headline          TEXT    NOT NULL,
-    full_newspaper_text TEXT  NOT NULL,
-    timestamp         TEXT    NOT NULL
-);
-
-CREATE TABLE events (
-    id          INTEGER PRIMARY KEY AUTOINCREMENT,
-    day_number  INTEGER NOT NULL,
-    actor       TEXT    NOT NULL,   -- fox | badger | squirrel | mole
-    action      TEXT    NOT NULL,   -- trade | gossip | feud | invention
-    target      TEXT    NOT NULL,
-    description TEXT    NOT NULL
-);
-
-CREATE TABLE creatures (
-    name                TEXT PRIMARY KEY,
-    relationship_scores TEXT NOT NULL,  -- JSON {"fox": 42, …}
-    inventory           TEXT NOT NULL   -- JSON ["item1", …]
-);
-
-CREATE TABLE nudges (
-    id          INTEGER PRIMARY KEY AUTOINCREMENT,
-    day_number  INTEGER NOT NULL,
-    nudge_type  TEXT    NOT NULL,   -- rumour | donation | law
-    nudge_value TEXT    NOT NULL
-);
+CREATE TABLE days     (day_number, headline, full_newspaper_text, timestamp);
+CREATE TABLE events   (id, day_number, actor, action, target, description);
+CREATE TABLE creatures(name, relationship_scores JSON, inventory JSON);
+CREATE TABLE nudges   (id, day_number, nudge_type, nudge_value);
 ```
 
 ---
 
-## License
+## Easter Egg
+
+Type the **Konami Code** while the app is focused:  `↑ ↑ ↓ ↓ ← → ← → B A`
 
-MIT — do whatever you like with this absurd woodland bureaucracy.
+A modal appears showing all five raw system prompts — the behind-the-scenes look at what's driving the simulation.
 
 ---
 
-*"All things are connected underground." — Millicent Mole*
+*"All things are connected underground." — Millicent Mole, Day 1*