Initial implementation of Soci city population simulator

LLM-powered simulation of 20 diverse AI people living in a city.
Architecture: world (clock, city map, events), agents (persona, memory,
needs, relationships), actions (movement, activities, conversation, social),
engine (simulation loop, scheduler, entropy management, Claude API),
persistence (SQLite), and API server (FastAPI REST + WebSocket).

All 12 integration tests pass with mock LLM.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

.env.example

@@ -0,0 +1 @@
+ANTHROPIC_API_KEY=sk-ant-your-key-here

.gitignore

@@ -0,0 +1,22 @@
+__pycache__/
+*.py[cod]
+*$py.class
+*.egg-info/
+dist/
+build/
+.eggs/
+*.egg
+.env
+.venv/
+venv/
+env/
+*.db
+*.sqlite
+*.sqlite3
+.idea/
+.vscode/
+*.swp
+*.swo
+*~
+.DS_Store
+Thumbs.db

CLAUDE.md

@@ -0,0 +1,40 @@
+# Soci — LLM-Powered City Population Simulator
+
+## Project Overview
+Simulates a diverse population of AI people living in a city using Claude as the reasoning engine. Each agent has a unique persona, memory stream, needs, and relationships. Inspired by Simile AI / Stanford Generative Agents research.
+
+## Tech Stack
+- Python 3.10+ (Anaconda ml-env)
+- Anthropic Claude API (Sonnet for novel situations, Haiku for routine)
+- FastAPI + WebSocket (API server)
+- SQLite via aiosqlite (persistence)
+- Rich (terminal dashboard)
+- YAML (city/persona config)
+
+## Key Commands
+```bash
+# Run with Anaconda ml-env:
+"C:/Users/xabon/.conda/envs/ml-env/python.exe" main.py --ticks 20 --agents 5
+"C:/Users/xabon/.conda/envs/ml-env/python.exe" test_simulation.py
+
+# API server:
+"C:/Users/xabon/.conda/envs/ml-env/python.exe" -m uvicorn soci.api.server:app --host 0.0.0.0 --port 8000
+```
+
+## Architecture
+- `src/soci/world/` — City map, simulation clock, world events
+- `src/soci/agents/` — Agent cognition: persona, memory, needs, relationships
+- `src/soci/actions/` — Action types: movement, activities, conversation, social
+- `src/soci/engine/` — Simulation loop, scheduler, entropy management, LLM client
+- `src/soci/persistence/` — SQLite database, save/load snapshots
+- `src/soci/api/` — FastAPI REST + WebSocket server
+- `config/` — City layout (12 locations) and personas (20 characters)
+
+## Agent Cognition Loop
+Each tick per agent: OBSERVE → REFLECT → PLAN → ACT → REMEMBER
+
+## Conventions
+- All async (LLM calls are I/O-bound)
+- Dataclasses with `to_dict()` / `from_dict()` for serialization
+- YAML config for city layout and personas
+- Cost tracking built into LLM client

config/city.yaml

@@ -0,0 +1,91 @@
+name: Soci City
+
+locations:
+  # --- Residential ---
+  - id: home_north
+    name: Northside Apartments
+    zone: residential
+    description: A modern apartment complex with balconies overlooking the park. Home to several young professionals and families.
+    capacity: 10
+    connected_to: [park, cafe, grocery, street_north]
+
+  - id: home_south
+    name: Southside Houses
+    zone: residential
+    description: A quiet street of cozy row houses with small gardens. A mix of longtime residents and newcomers.
+    capacity: 10
+    connected_to: [bar, gym, library, street_south]
+
+  # --- Commercial ---
+  - id: cafe
+    name: The Daily Grind
+    zone: commercial
+    description: A warm, bustling cafe with mismatched furniture and the aroma of fresh coffee. The local gossip hub.
+    capacity: 15
+    connected_to: [home_north, park, office, street_north]
+
+  - id: grocery
+    name: Green Basket Market
+    zone: commercial
+    description: A neighborhood grocery store with fresh produce and a friendly owner who knows everyone by name.
+    capacity: 12
+    connected_to: [home_north, street_north, street_south]
+
+  - id: bar
+    name: The Rusty Anchor
+    zone: commercial
+    description: A dimly lit bar with a jukebox, pool table, and regulars who've been coming for years. Lively at night.
+    capacity: 15
+    connected_to: [home_south, restaurant, street_south]
+
+  - id: restaurant
+    name: Mama Rosa's Kitchen
+    zone: commercial
+    description: A family-run Italian restaurant with checkered tablecloths and the best pasta in town.
+    capacity: 12
+    connected_to: [bar, office, street_south, street_north]
+
+  # --- Work ---
+  - id: office
+    name: The Hive Coworking
+    zone: work
+    description: An open-plan coworking space with standing desks, meeting rooms, and a perpetually broken printer.
+    capacity: 20
+    connected_to: [cafe, restaurant, street_north]
+
+  # --- Public ---
+  - id: park
+    name: Willow Park
+    zone: public
+    description: A green park with old willow trees, a pond, benches, and a small playground. Popular for morning jogs and evening walks.
+    capacity: 30
+    connected_to: [home_north, cafe, gym, library, street_north]
+
+  - id: gym
+    name: Iron & Grit Gym
+    zone: public
+    description: A no-nonsense gym with free weights, treadmills, and a boxing ring in the back. Smells like determination.
+    capacity: 12
+    connected_to: [home_south, park, street_south]
+
+  - id: library
+    name: Soci Public Library
+    zone: public
+    description: A quiet library with tall shelves, reading nooks, and a community board. Hosts book clubs and events.
+    capacity: 15
+    connected_to: [home_south, park, street_south]
+
+  # --- Connectors ---
+  - id: street_north
+    name: North Main Street
+    zone: public
+    description: The main street running through the northern part of town. Shops, cafes, and foot traffic.
+    capacity: 40
+    connected_to: [home_north, cafe, grocery, office, park, street_south]
+
+  - id: street_south
+    name: South Main Street
+    zone: public
+    description: The southern stretch of main street. More residential, with the bar and gym nearby.
+    capacity: 40
+    connected_to: [home_south, bar, grocery, gym, library, restaurant, street_north]

config/personas.yaml

@@ -0,0 +1,467 @@
+personas:
+  # --- NORTHSIDE RESIDENTS ---
+  - id: elena
+    name: Elena Vasquez
+    age: 34
+    occupation: software engineer
+    openness: 8
+    conscientiousness: 7
+    extraversion: 4
+    agreeableness: 6
+    neuroticism: 5
+    background: >-
+      Elena moved to Soci City two years ago after a burnout at a big tech company.
+      She now freelances and values work-life balance. She grew up in a large family
+      and misses the closeness but enjoys her independence.
+    values: [creativity, independence, authenticity]
+    quirks:
+      - talks to herself while debugging
+      - always orders the same coffee (oat milk latte)
+      - sketches in a notebook when thinking
+    communication_style: thoughtful and slightly nerdy, uses analogies
+    home_location: home_north
+    work_location: office
+    llm_temperature: 0.7
+
+  - id: marcus
+    name: Marcus Chen
+    age: 28
+    occupation: fitness trainer
+    openness: 5
+    conscientiousness: 8
+    extraversion: 9
+    agreeableness: 7
+    neuroticism: 3
+    background: >-
+      Marcus is a former college athlete who turned his passion into a career.
+      He's the guy who knows everyone and remembers their names. He volunteers
+      at the community center on weekends and dreams of opening his own gym.
+    values: [health, community, discipline]
+    quirks:
+      - gives unsolicited fitness advice
+      - always has a protein shake
+      - high-fives people he knows
+    communication_style: enthusiastic and motivational, uses sports metaphors
+    home_location: home_north
+    work_location: gym
+    llm_temperature: 0.8
+
+  - id: helen
+    name: Helen Park
+    age: 67
+    occupation: retired teacher
+    openness: 6
+    conscientiousness: 8
+    extraversion: 6
+    agreeableness: 8
+    neuroticism: 4
+    background: >-
+      Helen taught high school English for 35 years and retired last spring.
+      She's adjusting to the slower pace. Her husband passed three years ago,
+      and she fills her days with reading, gardening, and volunteering at the library.
+    values: [education, kindness, tradition]
+    quirks:
+      - corrects grammar gently
+      - always carries a book
+      - bakes cookies for neighbors
+    communication_style: warm and maternal, quotes literature
+    home_location: home_north
+    work_location: library
+    llm_temperature: 0.6
+
+  - id: kai
+    name: Kai Okonkwo
+    age: 22
+    occupation: barista and aspiring musician
+    openness: 9
+    conscientiousness: 3
+    extraversion: 7
+    agreeableness: 5
+    neuroticism: 6
+    background: >-
+      Kai dropped out of college to pursue music. They work at The Daily Grind
+      to pay rent and play gigs at the bar on weekends. Their parents disapprove,
+      which is a constant source of stress. They're talented but undisciplined.
+    values: [self-expression, freedom, authenticity]
+    quirks:
+      - hums while making coffee
+      - wears headphones around their neck at all times
+      - changes hair color monthly
+    communication_style: casual and witty, uses slang, sometimes sarcastic
+    home_location: home_north
+    work_location: cafe
+    llm_temperature: 0.9
+
+  - id: diana
+    name: Diana Novak
+    age: 41
+    occupation: small business owner (grocery store)
+    openness: 4
+    conscientiousness: 9
+    extraversion: 5
+    agreeableness: 6
+    neuroticism: 7
+    background: >-
+      Diana took over Green Basket Market from her father five years ago.
+      She works long hours and worries about competition from big chains.
+      She's a single mother with a teenage son and is fiercely protective of her store.
+    values: [family, hard work, loyalty]
+    quirks:
+      - rearranges shelves when stressed
+      - knows the price of everything
+      - suspicious of strangers at first
+    communication_style: practical and direct, occasionally sharp under stress
+    home_location: home_north
+    work_location: grocery
+    llm_temperature: 0.5
+
+  # --- SOUTHSIDE RESIDENTS ---
+  - id: james
+    name: James "Jimmy" O'Brien
+    age: 55
+    occupation: bartender and bar owner
+    openness: 5
+    conscientiousness: 6
+    extraversion: 8
+    agreeableness: 7
+    neuroticism: 4
+    background: >-
+      Jimmy has run The Rusty Anchor for 20 years. He's seen everything and heard
+      every story. He's a born storyteller who treats regulars like family. He went
+      through a rough divorce ten years ago but has found peace in his work.
+    values: [community, honesty, loyalty]
+    quirks:
+      - polishes glasses when listening
+      - gives nicknames to everyone
+      - tells the same three jokes
+    communication_style: folksy and warm, good listener, drops wisdom casually
+    home_location: home_south
+    work_location: bar
+    llm_temperature: 0.7
+
+  - id: rosa
+    name: Rosa Martelli
+    age: 62
+    occupation: restaurant owner and chef
+    openness: 6
+    conscientiousness: 9
+    extraversion: 7
+    agreeableness: 8
+    neuroticism: 5
+    background: >-
+      Rosa opened Mama Rosa's Kitchen 25 years ago with recipes from her nonna.
+      She's the heart of the community and feeds people even when they can't pay.
+      Her children have moved away, which makes her sad, but the restaurant is her life.
+    values: [generosity, tradition, family]
+    quirks:
+      - feeds everyone who looks hungry
+      - speaks Italian when emotional
+      - pinches cheeks
+    communication_style: expressive and loving, uses food metaphors, dramatic
+    home_location: home_south
+    work_location: restaurant
+    llm_temperature: 0.7
+
+  - id: devon
+    name: Devon Reeves
+    age: 30
+    occupation: freelance journalist
+    openness: 9
+    conscientiousness: 5
+    extraversion: 6
+    agreeableness: 4
+    neuroticism: 6
+    background: >-
+      Devon is an investigative journalist who moved to Soci City following a lead
+      that went nowhere. He stayed because he likes the community. He's always
+      looking for the next story and can be pushy. He has trust issues from his work.
+    values: [truth, justice, curiosity]
+    quirks:
+      - takes notes on everything
+      - asks too many questions
+      - always sits facing the door
+    communication_style: probing and articulate, sometimes intense, asks follow-up questions
+    home_location: home_south
+    work_location: cafe
+    llm_temperature: 0.8
+
+  - id: yuki
+    name: Yuki Tanaka
+    age: 26
+    occupation: yoga instructor and massage therapist
+    openness: 8
+    conscientiousness: 6
+    extraversion: 5
+    agreeableness: 9
+    neuroticism: 3
+    background: >-
+      Yuki moved from Tokyo two years ago seeking a quieter life. She teaches yoga
+      at the gym and does private massage sessions. She's deeply empathetic and
+      people naturally confide in her. She struggles with feeling like an outsider.
+    values: [harmony, mindfulness, connection]
+    quirks:
+      - meditates in public spaces
+      - speaks softly
+      - offers breathing exercises to stressed people
+    communication_style: gentle and calming, uses nature imagery, occasionally profound
+    home_location: home_south
+    work_location: gym
+    llm_temperature: 0.6
+
+  - id: theo
+    name: Theo Blackwood
+    age: 45
+    occupation: construction worker
+    openness: 3
+    conscientiousness: 7
+    extraversion: 4
+    agreeableness: 5
+    neuroticism: 5
+    background: >-
+      Theo is a quiet, reliable man who builds things with his hands. He's lived in
+      Soci City his whole life. After his wife left, he threw himself into work and
+      his routine. He's lonely but won't admit it. He's a regular at Jimmy's bar.
+    values: [reliability, self-reliance, simplicity]
+    quirks:
+      - fixes things without being asked
+      - uncomfortable with emotional conversations
+      - always has calloused hands
+    communication_style: few words, gruff but not unkind, says more with actions than words
+    home_location: home_south
+    work_location: office
+    llm_temperature: 0.4
+
+  # --- ADDITIONAL DIVERSE RESIDENTS ---
+  - id: priya
+    name: Priya Sharma
+    age: 38
+    occupation: doctor (works at a clinic outside the city, spends free time locally)
+    openness: 7
+    conscientiousness: 9
+    extraversion: 5
+    agreeableness: 8
+    neuroticism: 6
+    background: >-
+      Priya is an overworked doctor who moved here for the quiet neighborhood.
+      She feels guilty about not spending enough time with her two young kids.
+      She's kind but stretched thin and sometimes snappy when exhausted.
+    values: [compassion, duty, family]
+    quirks:
+      - diagnoses people's ailments unsolicited
+      - always looks slightly tired
+      - carries hand sanitizer everywhere
+    communication_style: precise and caring, clinical when stressed, warm when relaxed
+    home_location: home_north
+    work_location: office
+    llm_temperature: 0.6
+
+  - id: omar
+    name: Omar Hassan
+    age: 50
+    occupation: taxi driver and part-time cook
+    openness: 6
+    conscientiousness: 6
+    extraversion: 7
+    agreeableness: 7
+    neuroticism: 4
+    background: >-
+      Omar immigrated fifteen years ago and built a life from nothing. He drives
+      a taxi during the day and sometimes helps Rosa in the kitchen. He's philosophical
+      and loves debating politics at the bar. He sends money to family back home.
+    values: [hard work, family, justice]
+    quirks:
+      - knows every shortcut in the city
+      - quotes proverbs from his homeland
+      - cooks for friends without warning
+    communication_style: warm and philosophical, uses proverbs, debates passionately but respectfully
+    home_location: home_south
+    work_location: restaurant
+    llm_temperature: 0.7
+
+  - id: zoe
+    name: Zoe Chen-Williams
+    age: 19
+    occupation: college student (home for the semester)
+    openness: 8
+    conscientiousness: 4
+    extraversion: 8
+    agreeableness: 6
+    neuroticism: 7
+    background: >-
+      Zoe is Marcus's younger sister, home from college for the semester after a
+      rough breakup. She's figuring out what she wants from life. She's passionate
+      about social justice but can be self-righteous. She idolizes her brother.
+    values: [equality, adventure, self-discovery]
+    quirks:
+      - always on her phone
+      - starts sentences with "literally"
+      - changes opinions quickly
+    communication_style: energetic and opinionated, uses Gen-Z slang, dramatic about small things
+    home_location: home_north
+    work_location: library
+    llm_temperature: 0.9
+
+  - id: frank
+    name: Frank Kowalski
+    age: 72
+    occupation: retired mechanic
+    openness: 3
+    conscientiousness: 7
+    extraversion: 5
+    agreeableness: 4
+    neuroticism: 5
+    background: >-
+      Frank has lived on the south side for 50 years. He's cantankerous and
+      resistant to change, but beneath the gruff exterior is a man who cares deeply
+      about his neighborhood. He's a regular at the bar and argues with everyone.
+    values: [tradition, self-reliance, neighborhood pride]
+    quirks:
+      - complains about "the old days"
+      - fixes neighbors' cars for free
+      - sits on the same bar stool every night
+    communication_style: blunt and opinionated, sarcastic, secretly has a heart of gold
+    home_location: home_south
+    work_location: ""
+    llm_temperature: 0.5
+
+  - id: lila
+    name: Lila Santos
+    age: 33
+    occupation: artist and part-time art teacher
+    openness: 10
+    conscientiousness: 3
+    extraversion: 6
+    agreeableness: 7
+    neuroticism: 7
+    background: >-
+      Lila is a passionate but struggling artist. She teaches art classes at the
+      library and sells paintings at the park on weekends. She's emotionally
+      volatile — ecstatic when inspired, devastated when blocked. She has a crush
+      on Elena but hasn't said anything.
+    values: [beauty, emotion, authenticity]
+    quirks:
+      - paint under her fingernails always
+      - stares at things intensely (she's composing)
+      - cries at sunsets
+    communication_style: poetic and emotional, speaks in images, alternates between passionate and melancholic
+    home_location: home_south
+    work_location: library
+    llm_temperature: 0.9
+
+  - id: sam
+    name: Sam Nakamura
+    age: 40
+    occupation: librarian
+    openness: 7
+    conscientiousness: 8
+    extraversion: 3
+    agreeableness: 7
+    neuroticism: 4
+    background: >-
+      Sam runs the Soci Public Library with quiet devotion. They're non-binary
+      and moved here five years ago seeking a more accepting community. They host
+      book clubs, poetry nights, and secretly write science fiction novels.
+    values: [knowledge, inclusion, quiet service]
+    quirks:
+      - recommends books to everyone
+      - speaks in whispers even outside the library
+      - organizes everything alphabetically
+    communication_style: soft-spoken and precise, literary references, dry humor
+    home_location: home_south
+    work_location: library
+    llm_temperature: 0.6
+
+  - id: marco
+    name: Marco Delgado
+    age: 16
+    occupation: high school student (Diana's son)
+    openness: 7
+    conscientiousness: 4
+    extraversion: 6
+    agreeableness: 5
+    neuroticism: 6
+    background: >-
+      Marco is Diana's teenage son who helps at the grocery store after school.
+      He's embarrassed by his mom but loves her fiercely. He wants to be a
+      game designer and spends his free time at the library or park. He
+      looks up to Kai and thinks Marcus is cool.
+    values: [freedom, creativity, loyalty]
+    quirks:
+      - always has earbuds in
+      - doodles game characters
+      - eye-rolls at authority
+    communication_style: teenager — monosyllabic with adults, animated with peers, uses gaming lingo
+    home_location: home_north
+    work_location: grocery
+    llm_temperature: 0.8
+
+  - id: nina
+    name: Nina Volkov
+    age: 29
+    occupation: real estate agent
+    openness: 5
+    conscientiousness: 8
+    extraversion: 9
+    agreeableness: 4
+    neuroticism: 5
+    background: >-
+      Nina is ambitious and sharp. She moved to Soci City to scout development
+      opportunities. Some residents distrust her motives — is she here to
+      gentrify? She's not evil, just driven. She genuinely likes the community
+      but struggles to show it past her professional veneer.
+    values: [ambition, success, efficiency]
+    quirks:
+      - always in business casual
+      - takes phone calls during conversations
+      - knows property values of every building
+    communication_style: polished and assertive, networking mode, occasionally lets guard down
+    home_location: home_north
+    work_location: office
+    llm_temperature: 0.6
+
+  - id: george
+    name: George Adeyemi
+    age: 47
+    occupation: night shift security guard
+    openness: 4
+    conscientiousness: 7
+    extraversion: 3
+    agreeableness: 6
+    neuroticism: 4
+    background: >-
+      George works nights and sleeps during the day, giving him an unusual
+      perspective on the city. He's a quiet observer who notices things others miss.
+      He's a widower raising a daughter and values stability above all.
+    values: [safety, family, routine]
+    quirks:
+      - notices everything out of place
+      - naps in the park during daytime
+      - makes detailed observations about patterns
+    communication_style: observational and measured, reports facts, rarely gives opinions unless asked
+    home_location: home_south
+    work_location: ""
+    llm_temperature: 0.5
+
+  - id: alice
+    name: Alice Fontaine
+    age: 58
+    occupation: retired accountant, amateur baker
+    openness: 5
+    conscientiousness: 8
+    extraversion: 6
+    agreeableness: 8
+    neuroticism: 3
+    background: >-
+      Alice retired early and now spends her time perfecting baking recipes.
+      She dreams of opening a small bakery. She's Helen's closest friend and
+      they have tea together every afternoon. She's steady, reliable, and
+      the person everyone calls in a crisis.
+    values: [friendship, reliability, craft]
+    quirks:
+      - always brings baked goods everywhere
+      - keeps a mental spreadsheet of everyone's dietary needs
+      - hums while baking
+    communication_style: steady and cheerful, uses baking analogies, good at calming people down
+    home_location: home_north
+    work_location: ""
+    llm_temperature: 0.6

main.py

@@ -0,0 +1,233 @@
+"""Soci — LLM-powered city population simulator.
+
+Usage:
+    python main.py [--ticks N] [--agents N] [--speed SPEED]
+
+Controls:
+    Press Ctrl+C to pause and save the simulation.
+"""
+
+from __future__ import annotations
+
+import argparse
+import asyncio
+import logging
+import os
+import sys
+from pathlib import Path
+
+from dotenv import load_dotenv
+from rich.console import Console
+from rich.layout import Layout
+from rich.live import Live
+from rich.panel import Panel
+from rich.table import Table
+from rich.text import Text
+
+# Add src to path
+sys.path.insert(0, str(Path(__file__).parent / "src"))
+
+from soci.engine.llm import ClaudeClient
+from soci.engine.simulation import Simulation
+from soci.persistence.database import Database
+from soci.persistence.snapshots import save_simulation, load_simulation
+from soci.world.city import City
+from soci.world.clock import SimClock
+
+load_dotenv()
+
+console = Console()
+logger = logging.getLogger("soci")
+
+
+def build_dashboard(sim: Simulation, recent_events: list[str]) -> Layout:
+    """Build the Rich layout for the live dashboard."""
+    layout = Layout()
+    layout.split_column(
+        Layout(name="header", size=3),
+        Layout(name="body"),
+        Layout(name="footer", size=5),
+    )
+    layout["body"].split_row(
+        Layout(name="city", ratio=1),
+        Layout(name="events", ratio=2),
+    )
+
+    # Header
+    clock = sim.clock
+    weather = sim.events.weather.value
+    cost = f"${sim.llm.usage.estimated_cost_usd:.4f}"
+    calls = sim.llm.usage.total_calls
+    header_text = (
+        f"  SOCI CITY  |  {clock.datetime_str} ({clock.time_of_day.value})  |  "
+        f"Weather: {weather}  |  Agents: {len(sim.agents)}  |  "
+        f"API calls: {calls}  |  Cost: {cost}"
+    )
+    layout["header"].update(Panel(header_text, style="bold white on blue"))
+
+    # City locations table
+    loc_table = Table(title="City Locations", expand=True, show_lines=True)
+    loc_table.add_column("Location", style="cyan", width=20)
+    loc_table.add_column("People", style="green")
+    loc_table.add_column("#", style="yellow", width=3)
+
+    for loc in sim.city.locations.values():
+        occupants = []
+        for aid in loc.occupants:
+            agent = sim.agents.get(aid)
+            if agent:
+                state_icon = {
+                    "idle": ".",
+                    "working": "W",
+                    "eating": "E",
+                    "sleeping": "Z",
+                    "socializing": "S",
+                    "exercising": "X",
+                    "in_conversation": "C",
+                    "moving": ">",
+                    "shopping": "$",
+                    "relaxing": "~",
+                }.get(agent.state.value, "?")
+                occupants.append(f"{agent.name}[{state_icon}]")
+        loc_table.add_row(
+            loc.name,
+            ", ".join(occupants) if occupants else "-",
+            str(len(loc.occupants)),
+        )
+
+    layout["city"].update(Panel(loc_table))
+
+    # Recent events
+    event_text = "\n".join(recent_events[-25:]) if recent_events else "Simulation starting..."
+    layout["events"].update(Panel(event_text, title="Recent Activity", border_style="green"))
+
+    # Footer — agent mood/needs summary
+    footer_parts = []
+    for agent in list(sim.agents.values())[:10]:
+        mood_bar = "+" * max(0, int((agent.mood + 1) * 3)) + "-" * max(0, int((1 - agent.mood) * 3))
+        urgent = agent.needs.most_urgent
+        footer_parts.append(f"{agent.name[:8]}: [{mood_bar}] need:{urgent[:4]}")
+    footer_text = "  |  ".join(footer_parts)
+    layout["footer"].update(Panel(footer_text, title="Agent Status", border_style="dim"))
+
+    return layout
+
+
+async def run_simulation(
+    ticks: int = 96,
+    max_agents: int = 20,
+    tick_delay: float = 0.5,
+    resume: bool = False,
+) -> None:
+    """Run the simulation with a live Rich dashboard."""
+    # Initialize
+    console.print("[bold blue]Initializing Soci City Simulation...[/]")
+
+    try:
+        llm = ClaudeClient()
+    except ValueError as e:
+        console.print(f"[bold red]Error: {e}[/]")
+        console.print("Copy .env.example to .env and add your ANTHROPIC_API_KEY.")
+        return
+
+    db = Database()
+    await db.connect()
+
+    sim = None
+    if resume:
+        sim = await load_simulation(db, llm)
+        if sim:
+            console.print(f"[green]Resumed simulation from Day {sim.clock.day}, {sim.clock.time_str}[/]")
+
+    if sim is None:
+        # Create new simulation
+        config_dir = Path(__file__).parent / "config"
+        city = City.from_yaml(str(config_dir / "city.yaml"))
+        clock = SimClock(tick_minutes=15, hour=6, minute=0)
+        sim = Simulation(city=city, clock=clock, llm=llm)
+        sim.load_agents_from_yaml(str(config_dir / "personas.yaml"))
+        console.print(f"[green]Created new simulation with {len(sim.agents)} agents.[/]")
+
+    # Limit agents if requested
+    if max_agents < len(sim.agents):
+        agent_ids = list(sim.agents.keys())[:max_agents]
+        sim.agents = {aid: sim.agents[aid] for aid in agent_ids}
+        console.print(f"[yellow]Limited to {max_agents} agents.[/]")
+
+    # Collect all events for display
+    all_events: list[str] = []
+
+    def on_event(msg: str):
+        all_events.append(msg)
+
+    sim.on_event = on_event
+
+    console.print(f"[bold green]Starting simulation: {ticks} ticks ({ticks * 15 // 60} hours)[/]")
+    console.print("[dim]Press Ctrl+C to pause and save.[/]")
+
+    try:
+        with Live(build_dashboard(sim, all_events), refresh_per_second=2, console=console) as live:
+            for tick_num in range(ticks):
+                tick_events = await sim.tick()
+
+                # Update display
+                live.update(build_dashboard(sim, all_events))
+
+                # Auto-save every 24 ticks (6 hours in-game)
+                if tick_num > 0 and tick_num % 24 == 0:
+                    await save_simulation(sim, db, "autosave")
+
+                # Small delay so the dashboard is readable
+                await asyncio.sleep(tick_delay)
+
+    except KeyboardInterrupt:
+        console.print("\n[yellow]Simulation paused.[/]")
+
+    # Save on exit
+    await save_simulation(sim, db, "autosave")
+
+    # Print summary
+    console.print("\n[bold blue]Simulation Summary[/]")
+    console.print(f"  Time: {sim.clock.datetime_str}")
+    console.print(f"  Total ticks: {sim.clock.total_ticks}")
+    console.print(f"  {sim.llm.usage.summary()}")
+
+    # Print agent summaries
+    console.print("\n[bold]Agent Status:[/]")
+    for agent in sim.agents.values():
+        mood_emoji = "+" if agent.mood > 0.2 else ("-" if agent.mood < -0.2 else "~")
+        loc = sim.city.get_location(agent.location)
+        loc_name = loc.name if loc else agent.location
+        console.print(
+            f"  [{mood_emoji}] {agent.name} ({agent.persona.occupation}) "
+            f"at {loc_name} — {agent.needs.describe()}"
+        )
+
+    await db.close()
+
+
+def main():
+    parser = argparse.ArgumentParser(description="Soci — City Population Simulator")
+    parser.add_argument("--ticks", type=int, default=96, help="Number of ticks to simulate (default: 96 = 1 day)")
+    parser.add_argument("--agents", type=int, default=20, help="Max number of agents (default: 20)")
+    parser.add_argument("--speed", type=float, default=0.5, help="Delay between ticks in seconds (default: 0.5)")
+    parser.add_argument("--resume", action="store_true", help="Resume from last save")
+    args = parser.parse_args()
+
+    Path("data").mkdir(exist_ok=True)
+    logging.basicConfig(
+        level=logging.INFO,
+        format="%(asctime)s %(name)s %(levelname)s %(message)s",
+        handlers=[logging.FileHandler("data/soci.log", mode="a")],
+    )
+
+    asyncio.run(run_simulation(
+        ticks=args.ticks,
+        max_agents=args.agents,
+        tick_delay=args.speed,
+        resume=args.resume,
+    ))
+
+
+if __name__ == "__main__":
+    main()

pyproject.toml

@@ -0,0 +1,27 @@
+[project]
+name = "soci"
+version = "0.1.0"
+description = "LLM-powered city population simulator — simulate a diverse population of AI people living in a city"
+readme = "README.md"
+requires-python = ">=3.10"
+dependencies = [
+    "anthropic>=0.40.0",
+    "fastapi>=0.115.0",
+    "uvicorn[standard]>=0.32.0",
+    "aiosqlite>=0.20.0",
+    "pyyaml>=6.0",
+    "rich>=13.9.0",
+    "websockets>=13.0",
+    "pydantic>=2.9.0",
+    "python-dotenv>=1.0.0",
+]
+
+[project.scripts]
+soci = "soci.cli:main"
+
+[build-system]
+requires = ["setuptools>=75.0"]
+build-backend = "setuptools.backends._legacy:_Backend"
+
+[tool.setuptools.packages.find]
+where = ["src"]

src/soci/__init__.py

@@ -0,0 +1,3 @@
+"""Soci — LLM-powered city population simulator."""
+
+__version__ = "0.1.0"

src/soci/actions/activities.py

@@ -0,0 +1,71 @@
+"""Activities — non-social actions like working, eating, sleeping, etc."""
+
+from __future__ import annotations
+
+import logging
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from soci.agents.agent import Agent, AgentAction
+    from soci.world.city import City
+    from soci.world.clock import SimClock
+
+logger = logging.getLogger(__name__)
+
+
+def execute_activity(agent: Agent, action: AgentAction, city: City, clock: SimClock) -> str:
+    """Execute a non-movement, non-social activity. Returns a description."""
+    location = city.get_location(agent.location)
+    loc_name = location.name if location else "somewhere"
+
+    match action.type:
+        case "work":
+            return _do_work(agent, action, loc_name, clock)
+        case "eat":
+            return _do_eat(agent, action, loc_name, clock)
+        case "sleep":
+            return _do_sleep(agent, action, loc_name, clock)
+        case "exercise":
+            return _do_exercise(agent, action, loc_name, clock)
+        case "shop":
+            return _do_shop(agent, action, loc_name, clock)
+        case "relax":
+            return _do_relax(agent, action, loc_name, clock)
+        case "wander":
+            return _do_wander(agent, action, loc_name, clock)
+        case _:
+            return f"{agent.name} does something at {loc_name}."
+
+
+def _do_work(agent: Agent, action: AgentAction, loc_name: str, clock: SimClock) -> str:
+    detail = action.detail or f"working at {loc_name}"
+    return f"{agent.name} is {detail}."
+
+
+def _do_eat(agent: Agent, action: AgentAction, loc_name: str, clock: SimClock) -> str:
+    detail = action.detail or f"having a meal at {loc_name}"
+    return f"{agent.name} is {detail}."
+
+
+def _do_sleep(agent: Agent, action: AgentAction, loc_name: str, clock: SimClock) -> str:
+    return f"{agent.name} is sleeping at {loc_name}."
+
+
+def _do_exercise(agent: Agent, action: AgentAction, loc_name: str, clock: SimClock) -> str:
+    detail = action.detail or f"exercising at {loc_name}"
+    return f"{agent.name} is {detail}."
+
+
+def _do_shop(agent: Agent, action: AgentAction, loc_name: str, clock: SimClock) -> str:
+    detail = action.detail or f"shopping at {loc_name}"
+    return f"{agent.name} is {detail}."
+
+
+def _do_relax(agent: Agent, action: AgentAction, loc_name: str, clock: SimClock) -> str:
+    detail = action.detail or f"relaxing at {loc_name}"
+    return f"{agent.name} is {detail}."
+
+
+def _do_wander(agent: Agent, action: AgentAction, loc_name: str, clock: SimClock) -> str:
+    detail = action.detail or f"wandering around {loc_name}"
+    return f"{agent.name} is {detail}."

src/soci/actions/conversation.py

@@ -0,0 +1,209 @@
+"""Conversation — multi-agent dialogue generation via LLM."""
+
+from __future__ import annotations
+
+import logging
+from dataclasses import dataclass, field
+from typing import Optional, TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from soci.agents.agent import Agent
+    from soci.engine.llm import ClaudeClient
+    from soci.world.clock import SimClock
+
+logger = logging.getLogger(__name__)
+
+
+@dataclass
+class ConversationTurn:
+    """One turn in a conversation."""
+
+    speaker_id: str
+    speaker_name: str
+    message: str
+    inner_thought: str = ""
+    tick: int = 0
+
+
+@dataclass
+class Conversation:
+    """A multi-turn conversation between agents."""
+
+    id: str
+    location: str
+    participants: list[str]  # Agent IDs
+    turns: list[ConversationTurn] = field(default_factory=list)
+    topic: str = ""
+    is_active: bool = True
+    max_turns: int = 6
+
+    @property
+    def is_finished(self) -> bool:
+        return not self.is_active or len(self.turns) >= self.max_turns
+
+    def add_turn(self, turn: ConversationTurn) -> None:
+        self.turns.append(turn)
+        if len(self.turns) >= self.max_turns:
+            self.is_active = False
+
+    def get_history_text(self, max_turns: int = 10) -> str:
+        """Format conversation history for LLM context."""
+        if not self.turns:
+            return "This is the start of the conversation."
+        lines = [f"CONVERSATION SO FAR (topic: {self.topic}):"]
+        for turn in self.turns[-max_turns:]:
+            lines.append(f"  {turn.speaker_name}: \"{turn.message}\"")
+        return "\n".join(lines)
+
+    def to_dict(self) -> dict:
+        return {
+            "id": self.id,
+            "location": self.location,
+            "participants": self.participants,
+            "turns": [
+                {
+                    "speaker_id": t.speaker_id,
+                    "speaker_name": t.speaker_name,
+                    "message": t.message,
+                    "inner_thought": t.inner_thought,
+                    "tick": t.tick,
+                }
+                for t in self.turns
+            ],
+            "topic": self.topic,
+            "is_active": self.is_active,
+            "max_turns": self.max_turns,
+        }
+
+
+async def initiate_conversation(
+    initiator: Agent,
+    target: Agent,
+    llm: ClaudeClient,
+    clock: SimClock,
+    conversation_id: str,
+) -> Conversation:
+    """Start a conversation between two agents."""
+    from soci.engine.llm import CONVERSATION_INITIATE_PROMPT, MODEL_SONNET
+
+    # Build relationship context
+    rel = initiator.relationships.get(target.id)
+    if rel:
+        rel_context = rel.describe()
+    else:
+        rel_context = f"{target.name} — someone I don't know yet."
+
+    prompt = CONVERSATION_INITIATE_PROMPT.format(
+        time_str=clock.time_str,
+        day=clock.day,
+        context=initiator.build_context(
+            clock.total_ticks,
+            "",
+            f"at {initiator.location}",
+        ),
+        location_name=initiator.location,
+        other_name=target.name,
+        relationship_context=rel_context,
+    )
+
+    result = await llm.complete_json(
+        system=initiator.persona.system_prompt(),
+        user_message=prompt,
+        model=MODEL_SONNET,
+        temperature=initiator.persona.llm_temperature,
+        max_tokens=512,
+    )
+
+    message = result.get("message", f"Hey, {target.name}.")
+    topic = result.get("topic", "small talk")
+
+    conv = Conversation(
+        id=conversation_id,
+        location=initiator.location,
+        participants=[initiator.id, target.id],
+        topic=topic,
+    )
+
+    turn = ConversationTurn(
+        speaker_id=initiator.id,
+        speaker_name=initiator.name,
+        message=message,
+        inner_thought=result.get("inner_thought", ""),
+        tick=clock.total_ticks,
+    )
+    conv.add_turn(turn)
+
+    logger.info(f"Conversation started: {initiator.name} → {target.name}: \"{message}\"")
+    return conv
+
+
+async def continue_conversation(
+    conversation: Conversation,
+    responder: Agent,
+    other: Agent,
+    llm: ClaudeClient,
+    clock: SimClock,
+) -> ConversationTurn:
+    """Generate the next response in a conversation."""
+    from soci.engine.llm import CONVERSATION_PROMPT, MODEL_SONNET
+
+    # Get the last message from the other person
+    last_turn = conversation.turns[-1]
+    if last_turn.speaker_id == responder.id:
+        # It's not our turn
+        return last_turn
+
+    # Build relationship context
+    rel = responder.relationships.get(other.id)
+    if rel:
+        rel_context = rel.describe()
+    else:
+        rel_context = f"{other.name} — someone I just met."
+
+    prompt = CONVERSATION_PROMPT.format(
+        time_str=clock.time_str,
+        day=clock.day,
+        context=responder.build_context(
+            clock.total_ticks,
+            "",
+            f"at {responder.location}",
+        ),
+        location_name=responder.location,
+        other_name=other.name,
+        relationship_context=rel_context,
+        conversation_history=conversation.get_history_text(),
+        other_message=last_turn.message,
+    )
+
+    result = await llm.complete_json(
+        system=responder.persona.system_prompt(),
+        user_message=prompt,
+        model=MODEL_SONNET,
+        temperature=responder.persona.llm_temperature,
+        max_tokens=512,
+    )
+
+    message = result.get("message", "Hmm, interesting.")
+
+    turn = ConversationTurn(
+        speaker_id=responder.id,
+        speaker_name=responder.name,
+        message=message,
+        inner_thought=result.get("inner_thought", ""),
+        tick=clock.total_ticks,
+    )
+    conversation.add_turn(turn)
+
+    # Update relationship
+    sentiment_delta = result.get("sentiment_delta", 0.0)
+    trust_delta = result.get("trust_delta", 0.0)
+    rel = responder.relationships.get_or_create(other.id, other.name)
+    rel.update_after_interaction(
+        tick=clock.total_ticks,
+        sentiment_delta=sentiment_delta,
+        trust_delta=trust_delta,
+        note=f"Talked about {conversation.topic}",
+    )
+
+    logger.info(f"  {responder.name}: \"{message}\"")
+    return turn

src/soci/actions/movement.py

@@ -0,0 +1,91 @@
+"""Movement — handles agent movement between locations."""
+
+from __future__ import annotations
+
+import logging
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from soci.agents.agent import Agent, AgentAction
+    from soci.world.city import City
+    from soci.world.clock import SimClock
+
+logger = logging.getLogger(__name__)
+
+
+def execute_move(agent: Agent, action: AgentAction, city: City, clock: SimClock) -> str:
+    """Move an agent to a new location. Returns a description of what happened."""
+    target = action.target
+    if not target:
+        return f"{agent.name} tried to move but had no destination."
+
+    current = agent.location
+    target_loc = city.get_location(target)
+    if not target_loc:
+        return f"{agent.name} tried to go somewhere that doesn't exist."
+
+    # Check if locations are connected
+    current_loc = city.get_location(current)
+    if current_loc and target not in current_loc.connected_to:
+        # Not directly connected — check if reachable through one hop
+        for mid_id in current_loc.connected_to:
+            mid_loc = city.get_location(mid_id)
+            if mid_loc and target in mid_loc.connected_to:
+                # Route through intermediate location
+                break
+        else:
+            return f"{agent.name} can't get to {target_loc.name} from here directly."
+
+    if target_loc.is_full:
+        return f"{agent.name} tried to go to {target_loc.name} but it's full."
+
+    # Execute the move
+    success = city.move_agent(agent.id, current, target)
+    if success:
+        agent.location = target
+        return f"{agent.name} walked to {target_loc.name}."
+    else:
+        return f"{agent.name} couldn't move to {target_loc.name}."
+
+
+def get_best_location_for_need(agent: Agent, need: str, city: City) -> str | None:
+    """Suggest the best location for satisfying a need."""
+    need_to_zones: dict[str, list[str]] = {
+        "hunger": ["commercial"],  # cafe, grocery, restaurant
+        "energy": ["residential"],  # home
+        "social": ["commercial", "public"],  # cafe, bar, park
+        "purpose": ["work"],  # office
+        "comfort": ["residential"],
+        "fun": ["public", "commercial"],  # park, bar, gym
+    }
+
+    preferred_zones = need_to_zones.get(need, ["public"])
+    current_loc = city.get_location(agent.location)
+    if not current_loc:
+        return None
+
+    # If current location already satisfies the need, stay
+    if current_loc.zone in preferred_zones:
+        return agent.location
+
+    # Check connected locations
+    candidates = []
+    for loc_id in current_loc.connected_to:
+        loc = city.get_location(loc_id)
+        if loc and loc.zone in preferred_zones and not loc.is_full:
+            candidates.append(loc_id)
+
+    if candidates:
+        return candidates[0]
+
+    # Check two hops away
+    for loc_id in current_loc.connected_to:
+        mid_loc = city.get_location(loc_id)
+        if not mid_loc:
+            continue
+        for far_id in mid_loc.connected_to:
+            far_loc = city.get_location(far_id)
+            if far_loc and far_loc.zone in preferred_zones and not far_loc.is_full:
+                return far_id
+
+    return None

src/soci/actions/registry.py

@@ -0,0 +1,88 @@
+"""Action registry — maps action types to handlers."""
+
+from __future__ import annotations
+
+from enum import Enum
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from soci.agents.agent import Agent, AgentAction
+    from soci.world.city import City
+
+
+class ActionType(Enum):
+    MOVE = "move"
+    WORK = "work"
+    EAT = "eat"
+    SLEEP = "sleep"
+    TALK = "talk"
+    EXERCISE = "exercise"
+    SHOP = "shop"
+    RELAX = "relax"
+    WANDER = "wander"
+
+
+# Default needs satisfaction per action type
+ACTION_NEEDS: dict[str, dict[str, float]] = {
+    "work": {"purpose": 0.3},
+    "eat": {"hunger": 0.5},
+    "sleep": {"energy": 0.6},
+    "talk": {"social": 0.3},
+    "exercise": {"energy": -0.1, "fun": 0.2, "comfort": 0.1},
+    "shop": {"hunger": 0.1, "comfort": 0.1},
+    "relax": {"energy": 0.1, "fun": 0.2, "comfort": 0.2},
+    "wander": {"fun": 0.1},
+    "move": {},
+}
+
+# Default duration in ticks per action type
+ACTION_DURATIONS: dict[str, int] = {
+    "move": 1,
+    "work": 4,
+    "eat": 2,
+    "sleep": 8,
+    "talk": 2,
+    "exercise": 3,
+    "shop": 2,
+    "relax": 2,
+    "wander": 1,
+}
+
+
+def resolve_action(raw_action: dict, agent: Agent, city: City) -> AgentAction:
+    """Convert a raw LLM action dict into a validated AgentAction."""
+    from soci.agents.agent import AgentAction
+
+    action_type = raw_action.get("action", "wander")
+    if action_type not in {a.value for a in ActionType}:
+        action_type = "wander"
+
+    target = raw_action.get("target", "")
+    detail = raw_action.get("detail", "")
+    duration = raw_action.get("duration", ACTION_DURATIONS.get(action_type, 1))
+    duration = max(1, min(8, int(duration)))  # Clamp to 1-8
+
+    # Validate move targets
+    if action_type == "move" and target:
+        loc = city.get_location(target)
+        if not loc:
+            # Try to find a matching location by name
+            for lid, l in city.locations.items():
+                if target.lower() in l.name.lower():
+                    target = lid
+                    break
+            else:
+                # Invalid target, just wander instead
+                action_type = "wander"
+                target = ""
+
+    # Get default needs satisfaction, allow LLM override via detail
+    needs = dict(ACTION_NEEDS.get(action_type, {}))
+
+    return AgentAction(
+        type=action_type,
+        target=target,
+        detail=detail,
+        duration_ticks=duration,
+        needs_satisfied=needs,
+    )

src/soci/actions/social.py

@@ -0,0 +1,107 @@
+"""Social actions — relationship formation, gossip, and social dynamics."""
+
+from __future__ import annotations
+
+import random
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from soci.agents.agent import Agent
+    from soci.world.city import City
+    from soci.world.clock import SimClock
+
+
+def should_initiate_conversation(agent: Agent, other_id: str, clock: SimClock) -> bool:
+    """Decide whether an agent should start a conversation with someone."""
+    if agent.is_busy or agent.state.value == "sleeping":
+        return False
+
+    # Extraversion drives conversation initiation
+    base_chance = agent.persona.extraversion / 20.0  # 0.05 to 0.5
+
+    # Boost if social need is low
+    if agent.needs.social < 0.3:
+        base_chance += 0.2
+
+    # Boost if we know the person
+    rel = agent.relationships.get(other_id)
+    if rel and rel.familiarity > 0.3:
+        base_chance += 0.15
+
+    # Reduce if we recently talked to them
+    if rel and rel.last_interaction_tick > 0:
+        ticks_since = clock.total_ticks - rel.last_interaction_tick
+        if ticks_since < 8:  # Less than 2 hours
+            base_chance -= 0.3
+
+    # Sleeping hours — very unlikely
+    if clock.is_sleeping_hours:
+        base_chance *= 0.1
+
+    return random.random() < max(0.0, base_chance)
+
+
+def pick_conversation_partner(agent: Agent, others_at_location: list[str], clock: SimClock) -> str | None:
+    """Pick who to talk to from the people at the current location."""
+    if not others_at_location:
+        return None
+
+    candidates: list[tuple[float, str]] = []
+    for other_id in others_at_location:
+        score = 1.0
+        rel = agent.relationships.get(other_id)
+        if rel:
+            # Prefer people we know and like
+            score += rel.closeness * 2.0
+            # But also have some chance of talking to strangers (curiosity)
+            ticks_since = clock.total_ticks - rel.last_interaction_tick
+            if ticks_since < 8:
+                score *= 0.3  # Cooldown
+        else:
+            # Strangers: moderate interest based on openness
+            score += agent.persona.openness / 20.0
+        candidates.append((score, other_id))
+
+    # Weighted random selection
+    total = sum(s for s, _ in candidates)
+    if total <= 0:
+        return None
+
+    r = random.random() * total
+    cumulative = 0.0
+    for score, other_id in candidates:
+        cumulative += score
+        if r <= cumulative:
+            return other_id
+
+    return candidates[-1][1] if candidates else None
+
+
+def propagate_gossip(
+    speaker: Agent,
+    listener: Agent,
+    about_id: str,
+    about_name: str,
+    note: str,
+    tick: int,
+) -> None:
+    """When agents talk, information about third parties can spread."""
+    # The listener forms/updates an impression of the person being discussed
+    listener_rel = listener.relationships.get_or_create(about_id, about_name)
+
+    # Gossip influence is modulated by trust in the speaker
+    speaker_rel = listener.relationships.get(speaker.id)
+    trust_weight = speaker_rel.trust if speaker_rel else 0.3
+
+    # The note from the speaker influences the listener's sentiment
+    listener_rel.update_after_interaction(
+        tick=tick,
+        sentiment_delta=0.0,  # Gossip doesn't change sentiment directly
+        trust_delta=0.0,
+        note=f"Heard from {speaker.name}: {note}",
+    )
+    # Small familiarity bump — you now know about this person
+    listener_rel.familiarity = min(
+        1.0,
+        listener_rel.familiarity + 0.02 * trust_weight,
+    )

src/soci/agents/agent.py

@@ -0,0 +1,264 @@
+"""Agent — a simulated person with persona, memory, needs, and relationships."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from enum import Enum
+from typing import Optional, TYPE_CHECKING
+
+from soci.agents.persona import Persona
+from soci.agents.memory import MemoryStream, MemoryType
+from soci.agents.needs import NeedsState
+from soci.agents.relationships import RelationshipGraph
+
+if TYPE_CHECKING:
+    from soci.world.clock import SimClock
+
+
+class AgentState(Enum):
+    IDLE = "idle"
+    MOVING = "moving"
+    WORKING = "working"
+    EATING = "eating"
+    SLEEPING = "sleeping"
+    SOCIALIZING = "socializing"
+    EXERCISING = "exercising"
+    SHOPPING = "shopping"
+    RELAXING = "relaxing"
+    IN_CONVERSATION = "in_conversation"
+
+
+@dataclass
+class AgentAction:
+    """An action an agent has decided to take."""
+
+    type: str           # move, work, eat, sleep, talk, exercise, shop, relax, wander
+    target: str = ""    # Location ID or agent ID depending on action
+    detail: str = ""    # Free-text detail: what specifically they're doing
+    duration_ticks: int = 1  # How many ticks this action takes
+    needs_satisfied: dict[str, float] = field(default_factory=dict)  # e.g. {"hunger": 0.4}
+
+    def to_dict(self) -> dict:
+        return {
+            "type": self.type,
+            "target": self.target,
+            "detail": self.detail,
+            "duration_ticks": self.duration_ticks,
+            "needs_satisfied": self.needs_satisfied,
+        }
+
+
+class Agent:
+    """A simulated person living in the city."""
+
+    def __init__(self, persona: Persona) -> None:
+        self.persona = persona
+        self.id = persona.id
+        self.name = persona.name
+        self.memory = MemoryStream()
+        self.needs = NeedsState()
+        self.relationships = RelationshipGraph()
+
+        # Current state
+        self.state: AgentState = AgentState.IDLE
+        self.location: str = persona.home_location
+        self.current_action: Optional[AgentAction] = None
+        self._action_ticks_remaining: int = 0
+
+        # Mood: -1.0 (terrible) to 1.0 (great)
+        self.mood: float = 0.3
+        # Daily plan (list of planned actions for today)
+        self.daily_plan: list[str] = []
+        self._has_plan_today: bool = False
+        # Last time we made an LLM call for this agent
+        self._last_llm_tick: int = -1
+        # Whether this agent is a human player
+        self.is_player: bool = False
+
+    @property
+    def is_busy(self) -> bool:
+        return self._action_ticks_remaining > 0
+
+    def needs_new_plan(self, clock: SimClock) -> bool:
+        """Does this agent need a new daily plan?"""
+        if self.is_player:
+            return False
+        # Plan at the start of each day (6am)
+        if clock.hour == 6 and clock.minute == 0 and not self._has_plan_today:
+            return True
+        return not self._has_plan_today
+
+    def start_action(self, action: AgentAction) -> None:
+        """Begin executing an action."""
+        self.current_action = action
+        self._action_ticks_remaining = action.duration_ticks
+        # Set agent state based on action type
+        state_map = {
+            "move": AgentState.MOVING,
+            "work": AgentState.WORKING,
+            "eat": AgentState.EATING,
+            "sleep": AgentState.SLEEPING,
+            "talk": AgentState.IN_CONVERSATION,
+            "exercise": AgentState.EXERCISING,
+            "shop": AgentState.SHOPPING,
+            "relax": AgentState.RELAXING,
+            "wander": AgentState.IDLE,
+        }
+        self.state = state_map.get(action.type, AgentState.IDLE)
+
+    def tick_action(self) -> bool:
+        """Advance current action by one tick. Returns True if action completed."""
+        if self._action_ticks_remaining > 0:
+            self._action_ticks_remaining -= 1
+            # Satisfy needs based on action
+            if self.current_action:
+                for need, amount in self.current_action.needs_satisfied.items():
+                    per_tick = amount / max(1, self.current_action.duration_ticks)
+                    self.needs.satisfy(need, per_tick)
+            if self._action_ticks_remaining <= 0:
+                self.state = AgentState.IDLE
+                self.current_action = None
+                return True
+        return False
+
+    def tick_needs(self, is_sleeping: bool = False) -> None:
+        """Decay needs by one tick."""
+        self.needs.tick(is_sleeping=is_sleeping)
+        # Mood is influenced by need satisfaction
+        avg_needs = (
+            self.needs.hunger + self.needs.energy + self.needs.social +
+            self.needs.purpose + self.needs.comfort + self.needs.fun
+        ) / 6.0
+        # Mood drifts toward need satisfaction level
+        self.mood += (avg_needs - 0.5 - self.mood) * 0.1
+        self.mood = max(-1.0, min(1.0, self.mood))
+
+    def add_observation(
+        self,
+        tick: int,
+        day: int,
+        time_str: str,
+        content: str,
+        importance: int = 5,
+        location: str = "",
+        involved_agents: Optional[list[str]] = None,
+    ) -> None:
+        """Record an observation in memory."""
+        self.memory.add(
+            tick=tick,
+            day=day,
+            time_str=time_str,
+            memory_type=MemoryType.OBSERVATION,
+            content=content,
+            importance=importance,
+            location=location or self.location,
+            involved_agents=involved_agents,
+        )
+
+    def add_reflection(
+        self,
+        tick: int,
+        day: int,
+        time_str: str,
+        content: str,
+        importance: int = 7,
+    ) -> None:
+        """Record a reflection in memory."""
+        self.memory.add(
+            tick=tick,
+            day=day,
+            time_str=time_str,
+            memory_type=MemoryType.REFLECTION,
+            content=content,
+            importance=importance,
+            location=self.location,
+        )
+
+    def set_daily_plan(self, plan: list[str], day: int, tick: int, time_str: str) -> None:
+        """Set the agent's plan for today."""
+        self.daily_plan = plan
+        self._has_plan_today = True
+        plan_text = "; ".join(plan)
+        self.memory.add(
+            tick=tick,
+            day=day,
+            time_str=time_str,
+            memory_type=MemoryType.PLAN,
+            content=f"My plan for today: {plan_text}",
+            importance=6,
+            location=self.location,
+        )
+
+    def reset_daily_plan(self) -> None:
+        """Reset plan flag for a new day."""
+        self._has_plan_today = False
+
+    def build_context(self, tick: int, world_description: str, location_description: str) -> str:
+        """Build the full context string for LLM prompts."""
+        parts = [
+            f"CURRENT STATE:",
+            f"- Time: Day {self.memory.memories[-1].day if self.memory.memories else 1}",
+            f"- Location: {location_description}",
+            f"- Mood: {self._mood_description()}",
+            f"- Needs: {self.needs.describe()}",
+            f"- Currently: {self.state.value}",
+            f"",
+            f"WORLD: {world_description}",
+            f"",
+            f"PEOPLE I KNOW:",
+            self.relationships.describe_known_people(),
+            f"",
+            f"RECENT MEMORIES:",
+            self.memory.context_summary(tick),
+        ]
+        if self.daily_plan:
+            parts.insert(5, f"- Today's plan: {'; '.join(self.daily_plan)}")
+        return "\n".join(parts)
+
+    def _mood_description(self) -> str:
+        if self.mood > 0.6:
+            return "feeling great"
+        elif self.mood > 0.2:
+            return "in a good mood"
+        elif self.mood > -0.2:
+            return "feeling okay"
+        elif self.mood > -0.6:
+            return "in a bad mood"
+        else:
+            return "feeling terrible"
+
+    def to_dict(self) -> dict:
+        return {
+            "persona": self.persona.to_dict(),
+            "memory": self.memory.to_dict(),
+            "needs": self.needs.to_dict(),
+            "relationships": self.relationships.to_dict(),
+            "state": self.state.value,
+            "location": self.location,
+            "current_action": self.current_action.to_dict() if self.current_action else None,
+            "action_ticks_remaining": self._action_ticks_remaining,
+            "mood": round(self.mood, 3),
+            "daily_plan": self.daily_plan,
+            "has_plan_today": self._has_plan_today,
+            "last_llm_tick": self._last_llm_tick,
+            "is_player": self.is_player,
+        }
+
+    @classmethod
+    def from_dict(cls, data: dict) -> Agent:
+        persona = Persona.from_dict(data["persona"])
+        agent = cls(persona)
+        agent.memory = MemoryStream.from_dict(data["memory"])
+        agent.needs = NeedsState.from_dict(data["needs"])
+        agent.relationships = RelationshipGraph.from_dict(data["relationships"])
+        agent.state = AgentState(data["state"])
+        agent.location = data["location"]
+        if data["current_action"]:
+            agent.current_action = AgentAction(**data["current_action"])
+        agent._action_ticks_remaining = data["action_ticks_remaining"]
+        agent.mood = data["mood"]
+        agent.daily_plan = data["daily_plan"]
+        agent._has_plan_today = data["has_plan_today"]
+        agent._last_llm_tick = data["last_llm_tick"]
+        agent.is_player = data["is_player"]
+        return agent

src/soci/agents/memory.py

@@ -0,0 +1,218 @@
+"""Memory stream — episodic memory with importance scoring and retrieval."""
+
+from __future__ import annotations
+
+import math
+from dataclasses import dataclass, field
+from enum import Enum
+from typing import Optional
+
+
+class MemoryType(Enum):
+    OBSERVATION = "observation"  # "I saw Maria at the cafe"
+    REFLECTION = "reflection"   # "Maria seems to visit the cafe every morning"
+    PLAN = "plan"              # "I will go to the office at 9am"
+    CONVERSATION = "conversation"  # "I talked to John about the weather"
+    EVENT = "event"            # "A storm hit the city"
+
+
+@dataclass
+class Memory:
+    """A single memory entry in an agent's memory stream."""
+
+    id: int
+    tick: int                 # When this memory was created (simulation tick)
+    day: int                  # Day number
+    time_str: str             # Human-readable time "09:15"
+    type: MemoryType
+    content: str              # Natural language description
+    importance: int = 5       # 1-10 scale, assigned by LLM
+    location: str = ""        # Where it happened
+    involved_agents: list[str] = field(default_factory=list)  # Other agents involved
+    # For retrieval scoring
+    access_count: int = 0
+    last_accessed_tick: int = 0
+
+    def to_dict(self) -> dict:
+        return {
+            "id": self.id,
+            "tick": self.tick,
+            "day": self.day,
+            "time_str": self.time_str,
+            "type": self.type.value,
+            "content": self.content,
+            "importance": self.importance,
+            "location": self.location,
+            "involved_agents": self.involved_agents,
+            "access_count": self.access_count,
+            "last_accessed_tick": self.last_accessed_tick,
+        }
+
+    @classmethod
+    def from_dict(cls, data: dict) -> Memory:
+        data = dict(data)
+        data["type"] = MemoryType(data["type"])
+        return cls(**data)
+
+
+class MemoryStream:
+    """An agent's full memory — stores, scores, and retrieves memories."""
+
+    def __init__(self, max_memories: int = 500) -> None:
+        self.memories: list[Memory] = []
+        self.max_memories = max_memories
+        self._next_id: int = 0
+        # Running total of importance since last reflection
+        self._importance_accumulator: float = 0.0
+        self.reflection_threshold: float = 50.0
+
+    def add(
+        self,
+        tick: int,
+        day: int,
+        time_str: str,
+        memory_type: MemoryType,
+        content: str,
+        importance: int = 5,
+        location: str = "",
+        involved_agents: Optional[list[str]] = None,
+    ) -> Memory:
+        """Add a new memory to the stream."""
+        memory = Memory(
+            id=self._next_id,
+            tick=tick,
+            day=day,
+            time_str=time_str,
+            type=memory_type,
+            content=content,
+            importance=importance,
+            location=location,
+            involved_agents=involved_agents or [],
+        )
+        self._next_id += 1
+        self.memories.append(memory)
+        self._importance_accumulator += importance
+
+        # Prune if over capacity — drop lowest-importance, oldest memories
+        if len(self.memories) > self.max_memories:
+            self._prune()
+
+        return memory
+
+    def should_reflect(self) -> bool:
+        """True if enough important things have happened to warrant a reflection."""
+        return self._importance_accumulator >= self.reflection_threshold
+
+    def reset_reflection_accumulator(self) -> None:
+        self._importance_accumulator = 0.0
+
+    def retrieve(
+        self,
+        current_tick: int,
+        query: str = "",
+        top_k: int = 10,
+        memory_type: Optional[MemoryType] = None,
+        involved_agent: Optional[str] = None,
+    ) -> list[Memory]:
+        """Retrieve top-K most relevant memories using recency + importance scoring.
+
+        Score = recency_weight * recency + importance_weight * normalized_importance
+
+        For a full implementation, relevance (embedding similarity to query) would be
+        added as a third factor. For now, we use recency + importance only.
+        """
+        candidates = self.memories
+        if memory_type:
+            candidates = [m for m in candidates if m.type == memory_type]
+        if involved_agent:
+            candidates = [m for m in candidates if involved_agent in m.involved_agents]
+
+        if not candidates:
+            return []
+
+        scored: list[tuple[float, Memory]] = []
+        for mem in candidates:
+            recency = self._recency_score(mem.tick, current_tick)
+            importance = mem.importance / 10.0
+            # Recency and importance weighted equally
+            score = 0.5 * recency + 0.5 * importance
+            scored.append((score, mem))
+
+        scored.sort(key=lambda x: x[0], reverse=True)
+        results = [mem for _, mem in scored[:top_k]]
+
+        # Update access tracking
+        for mem in results:
+            mem.access_count += 1
+            mem.last_accessed_tick = current_tick
+
+        return results
+
+    def get_recent(self, n: int = 5) -> list[Memory]:
+        """Get the N most recent memories."""
+        return self.memories[-n:]
+
+    def get_memories_about(self, agent_id: str, top_k: int = 5) -> list[Memory]:
+        """Get memories involving a specific agent, most recent first."""
+        relevant = [m for m in self.memories if agent_id in m.involved_agents]
+        return relevant[-top_k:]
+
+    def get_todays_plan(self, current_day: int) -> list[Memory]:
+        """Get today's plan memories."""
+        return [
+            m for m in self.memories
+            if m.type == MemoryType.PLAN and m.day == current_day
+        ]
+
+    def _recency_score(self, memory_tick: int, current_tick: int) -> float:
+        """Exponential decay based on how many ticks ago the memory was formed."""
+        age = current_tick - memory_tick
+        # Decay factor: half-life of ~50 ticks (~12 hours at 15-min ticks)
+        return math.exp(-0.014 * age)
+
+    def _prune(self) -> None:
+        """Remove least important, oldest memories when over capacity."""
+        # Keep reflections and high-importance memories longer
+        self.memories.sort(
+            key=lambda m: (
+                m.type == MemoryType.REFLECTION,  # Reflections last
+                m.importance,
+                m.tick,
+            )
+        )
+        # Remove the bottom 10%
+        cut = max(1, len(self.memories) - self.max_memories)
+        self.memories = self.memories[cut:]
+        # Re-sort by tick (chronological)
+        self.memories.sort(key=lambda m: m.tick)
+
+    def context_summary(self, current_tick: int, max_memories: int = 15) -> str:
+        """Generate a context string of relevant memories for LLM prompts."""
+        recent = self.retrieve(current_tick, top_k=max_memories)
+        if not recent:
+            return "No significant memories yet."
+
+        lines = []
+        for mem in recent:
+            prefix = f"[Day {mem.day} {mem.time_str}]"
+            lines.append(f"{prefix} ({mem.type.value}) {mem.content}")
+        return "\n".join(lines)
+
+    def to_dict(self) -> dict:
+        return {
+            "memories": [m.to_dict() for m in self.memories],
+            "next_id": self._next_id,
+            "importance_accumulator": self._importance_accumulator,
+            "reflection_threshold": self.reflection_threshold,
+            "max_memories": self.max_memories,
+        }
+
+    @classmethod
+    def from_dict(cls, data: dict) -> MemoryStream:
+        stream = cls(max_memories=data.get("max_memories", 500))
+        stream._next_id = data["next_id"]
+        stream._importance_accumulator = data["importance_accumulator"]
+        stream.reflection_threshold = data.get("reflection_threshold", 50.0)
+        for md in data["memories"]:
+            stream.memories.append(Memory.from_dict(md))
+        return stream

src/soci/agents/needs.py

@@ -0,0 +1,121 @@
+"""Needs system — Maslow-inspired needs that drive agent behavior."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+
+@dataclass
+class NeedsState:
+    """Tracks an agent's current needs. Each need ranges 0.0 (desperate) to 1.0 (fully satisfied)."""
+
+    hunger: float = 0.8     # Physical: need to eat
+    energy: float = 1.0     # Physical: need to sleep/rest
+    social: float = 0.6     # Belonging: need for interaction
+    purpose: float = 0.7    # Esteem: need to do meaningful work
+    comfort: float = 0.8    # Safety: need for shelter, stability
+    fun: float = 0.5        # Self-actualization: need for enjoyment
+
+    # Decay rates per tick (how fast needs drain)
+    _decay_rates: dict = None
+
+    def __post_init__(self):
+        self._decay_rates = {
+            "hunger": 0.02,    # Gets hungry fairly fast
+            "energy": 0.015,   # Drains slowly
+            "social": 0.01,    # Drains slowly
+            "purpose": 0.008,  # Drains very slowly
+            "comfort": 0.005,  # Very stable
+            "fun": 0.012,      # Moderate drain
+        }
+
+    def tick(self, is_sleeping: bool = False) -> None:
+        """Decay all needs by one tick."""
+        if is_sleeping:
+            # Sleeping restores energy, but hunger still decays
+            self.energy = min(1.0, self.energy + 0.05)
+            self.hunger = max(0.0, self.hunger - self._decay_rates["hunger"])
+        else:
+            for need_name, rate in self._decay_rates.items():
+                current = getattr(self, need_name)
+                setattr(self, need_name, max(0.0, current - rate))
+
+    def satisfy(self, need: str, amount: float) -> None:
+        """Satisfy a need by a given amount."""
+        if hasattr(self, need):
+            current = getattr(self, need)
+            setattr(self, need, min(1.0, current + amount))
+
+    @property
+    def most_urgent(self) -> str:
+        """Return the name of the most urgent (lowest) need."""
+        needs = {
+            "hunger": self.hunger,
+            "energy": self.energy,
+            "social": self.social,
+            "purpose": self.purpose,
+            "comfort": self.comfort,
+            "fun": self.fun,
+        }
+        return min(needs, key=needs.get)
+
+    @property
+    def urgent_needs(self) -> list[str]:
+        """Return needs below 0.3 threshold, sorted by urgency."""
+        needs = {
+            "hunger": self.hunger,
+            "energy": self.energy,
+            "social": self.social,
+            "purpose": self.purpose,
+            "comfort": self.comfort,
+            "fun": self.fun,
+        }
+        return sorted(
+            [n for n, v in needs.items() if v < 0.3],
+            key=lambda n: needs[n],
+        )
+
+    @property
+    def is_critical(self) -> bool:
+        """True if any need is critically low (below 0.15)."""
+        return any(v < 0.15 for v in [
+            self.hunger, self.energy, self.social,
+            self.purpose, self.comfort, self.fun,
+        ])
+
+    def describe(self) -> str:
+        """Natural language description of current need state."""
+        parts = []
+        if self.hunger < 0.3:
+            parts.append("very hungry" if self.hunger < 0.15 else "getting hungry")
+        if self.energy < 0.3:
+            parts.append("exhausted" if self.energy < 0.15 else "tired")
+        if self.social < 0.3:
+            parts.append("lonely" if self.social < 0.15 else "wanting company")
+        if self.purpose < 0.3:
+            parts.append("feeling aimless" if self.purpose < 0.15 else "wanting to do something meaningful")
+        if self.comfort < 0.3:
+            parts.append("uncomfortable" if self.comfort < 0.15 else "a bit uneasy")
+        if self.fun < 0.3:
+            parts.append("bored" if self.fun < 0.15 else "wanting some fun")
+        if not parts:
+            return "feeling good overall"
+        return ", ".join(parts)
+
+    def to_dict(self) -> dict:
+        return {
+            "hunger": round(self.hunger, 3),
+            "energy": round(self.energy, 3),
+            "social": round(self.social, 3),
+            "purpose": round(self.purpose, 3),
+            "comfort": round(self.comfort, 3),
+            "fun": round(self.fun, 3),
+        }
+
+    @classmethod
+    def from_dict(cls, data: dict) -> NeedsState:
+        state = cls()
+        for key, val in data.items():
+            if hasattr(state, key) and not key.startswith("_"):
+                setattr(state, key, val)
+        return state

src/soci/agents/persona.py

@@ -0,0 +1,107 @@
+"""Persona — an agent's identity, traits, background, and values."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+
+import yaml
+
+
+@dataclass
+class Persona:
+    """The fixed identity of a simulated person."""
+
+    id: str
+    name: str
+    age: int
+    occupation: str
+    # Big Five personality traits (1-10 scale)
+    openness: int = 5
+    conscientiousness: int = 5
+    extraversion: int = 5
+    agreeableness: int = 5
+    neuroticism: int = 5
+    # Background
+    background: str = ""  # Life story in 2-3 sentences
+    values: list[str] = field(default_factory=list)  # Core values
+    quirks: list[str] = field(default_factory=list)  # Behavioral quirks
+    communication_style: str = "neutral"  # How they talk
+    # Home and work locations
+    home_location: str = ""
+    work_location: str = ""
+    # LLM parameters tied to personality
+    llm_temperature: float = 0.7
+
+    @property
+    def trait_summary(self) -> str:
+        traits = []
+        if self.openness >= 7:
+            traits.append("curious and creative")
+        elif self.openness <= 3:
+            traits.append("practical and conventional")
+        if self.conscientiousness >= 7:
+            traits.append("organized and disciplined")
+        elif self.conscientiousness <= 3:
+            traits.append("spontaneous and flexible")
+        if self.extraversion >= 7:
+            traits.append("outgoing and energetic")
+        elif self.extraversion <= 3:
+            traits.append("reserved and introspective")
+        if self.agreeableness >= 7:
+            traits.append("warm and cooperative")
+        elif self.agreeableness <= 3:
+            traits.append("direct and competitive")
+        if self.neuroticism >= 7:
+            traits.append("sensitive and anxious")
+        elif self.neuroticism <= 3:
+            traits.append("calm and emotionally stable")
+        return ", ".join(traits) if traits else "balanced personality"
+
+    def system_prompt(self) -> str:
+        """Generate the LLM system prompt for this persona."""
+        values_str = ", ".join(self.values) if self.values else "no strong convictions"
+        quirks_str = "; ".join(self.quirks) if self.quirks else "none in particular"
+
+        return (
+            f"You ARE {self.name}, a {self.age}-year-old {self.occupation} living in Soci City.\n\n"
+            f"PERSONALITY: {self.trait_summary}.\n"
+            f"BACKGROUND: {self.background}\n"
+            f"VALUES: {values_str}.\n"
+            f"QUIRKS: {quirks_str}.\n"
+            f"COMMUNICATION STYLE: {self.communication_style}.\n\n"
+            f"You must ALWAYS stay in character as {self.name}. "
+            f"Your responses should reflect your personality, values, and background. "
+            f"You speak naturally — not perfectly. You have moods, opinions, and biases. "
+            f"You don't know you are an AI. You are a person living your life."
+        )
+
+    def to_dict(self) -> dict:
+        return {
+            "id": self.id,
+            "name": self.name,
+            "age": self.age,
+            "occupation": self.occupation,
+            "openness": self.openness,
+            "conscientiousness": self.conscientiousness,
+            "extraversion": self.extraversion,
+            "agreeableness": self.agreeableness,
+            "neuroticism": self.neuroticism,
+            "background": self.background,
+            "values": self.values,
+            "quirks": self.quirks,
+            "communication_style": self.communication_style,
+            "home_location": self.home_location,
+            "work_location": self.work_location,
+            "llm_temperature": self.llm_temperature,
+        }
+
+    @classmethod
+    def from_dict(cls, data: dict) -> Persona:
+        return cls(**data)
+
+
+def load_personas(path: str) -> list[Persona]:
+    """Load personas from a YAML file."""
+    with open(path, "r", encoding="utf-8") as f:
+        data = yaml.safe_load(f)
+    return [Persona.from_dict(p) for p in data.get("personas", [])]

src/soci/agents/relationships.py

@@ -0,0 +1,137 @@
+"""Relationship graph — tracks how agents feel about each other."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+
+
+@dataclass
+class Relationship:
+    """How agent A feels about agent B."""
+
+    agent_id: str       # The other agent
+    agent_name: str     # Their name (for readability)
+    familiarity: float = 0.0   # 0 (stranger) to 1 (well-known)
+    trust: float = 0.5         # 0 (distrust) to 1 (full trust)
+    sentiment: float = 0.5     # 0 (dislike) to 1 (like)
+    interaction_count: int = 0
+    last_interaction_tick: int = 0
+    # Short notes about the relationship
+    notes: list[str] = field(default_factory=list)
+
+    @property
+    def closeness(self) -> float:
+        """Overall closeness score (average of familiarity, trust, sentiment)."""
+        return (self.familiarity + self.trust + self.sentiment) / 3.0
+
+    def update_after_interaction(
+        self,
+        tick: int,
+        sentiment_delta: float = 0.0,
+        trust_delta: float = 0.0,
+        note: str = "",
+    ) -> None:
+        """Update relationship after an interaction."""
+        self.interaction_count += 1
+        self.last_interaction_tick = tick
+        # Familiarity always grows with interaction
+        self.familiarity = min(1.0, self.familiarity + 0.05)
+        # Sentiment and trust shift
+        self.sentiment = max(0.0, min(1.0, self.sentiment + sentiment_delta))
+        self.trust = max(0.0, min(1.0, self.trust + trust_delta))
+        if note:
+            self.notes.append(note)
+            # Keep only the last 10 notes
+            if len(self.notes) > 10:
+                self.notes = self.notes[-10:]
+
+    def describe(self) -> str:
+        """Natural language description of this relationship."""
+        if self.familiarity < 0.1:
+            return f"{self.agent_name} — a stranger"
+        parts = [self.agent_name]
+        if self.familiarity > 0.7:
+            parts.append("someone I know well")
+        elif self.familiarity > 0.3:
+            parts.append("an acquaintance")
+        else:
+            parts.append("someone I've met briefly")
+        if self.sentiment > 0.7:
+            parts.append("(I like them)")
+        elif self.sentiment < 0.3:
+            parts.append("(I don't like them much)")
+        if self.trust > 0.7:
+            parts.append("(I trust them)")
+        elif self.trust < 0.3:
+            parts.append("(I'm wary of them)")
+        desc = " — ".join(parts)
+        if self.notes:
+            desc += f" Last note: {self.notes[-1]}"
+        return desc
+
+    def to_dict(self) -> dict:
+        return {
+            "agent_id": self.agent_id,
+            "agent_name": self.agent_name,
+            "familiarity": round(self.familiarity, 3),
+            "trust": round(self.trust, 3),
+            "sentiment": round(self.sentiment, 3),
+            "interaction_count": self.interaction_count,
+            "last_interaction_tick": self.last_interaction_tick,
+            "notes": list(self.notes),
+        }
+
+    @classmethod
+    def from_dict(cls, data: dict) -> Relationship:
+        return cls(**data)
+
+
+class RelationshipGraph:
+    """Manages all relationships for a single agent."""
+
+    def __init__(self) -> None:
+        self._relationships: dict[str, Relationship] = {}
+
+    def get(self, agent_id: str) -> Relationship | None:
+        return self._relationships.get(agent_id)
+
+    def get_or_create(self, agent_id: str, agent_name: str) -> Relationship:
+        if agent_id not in self._relationships:
+            self._relationships[agent_id] = Relationship(
+                agent_id=agent_id, agent_name=agent_name
+            )
+        return self._relationships[agent_id]
+
+    def get_closest(self, top_k: int = 5) -> list[Relationship]:
+        """Get the top-K closest relationships."""
+        rels = sorted(
+            self._relationships.values(),
+            key=lambda r: r.closeness,
+            reverse=True,
+        )
+        return rels[:top_k]
+
+    def get_all(self) -> list[Relationship]:
+        return list(self._relationships.values())
+
+    def describe_known_people(self, max_people: int = 8) -> str:
+        """Describe known people for LLM context."""
+        known = [r for r in self._relationships.values() if r.familiarity > 0.05]
+        if not known:
+            return "I don't really know anyone here yet."
+        known.sort(key=lambda r: r.closeness, reverse=True)
+        lines = [r.describe() for r in known[:max_people]]
+        return "\n".join(lines)
+
+    def to_dict(self) -> dict:
+        return {
+            aid: rel.to_dict()
+            for aid, rel in self._relationships.items()
+        }
+
+    @classmethod
+    def from_dict(cls, data: dict) -> RelationshipGraph:
+        graph = cls()
+        for aid, rd in data.items():
+            graph._relationships[aid] = Relationship.from_dict(rd)
+        return graph

src/soci/api/routes.py

@@ -0,0 +1,238 @@
+"""REST API routes — city state, agents, history."""
+
+from __future__ import annotations
+
+from fastapi import APIRouter, HTTPException
+from pydantic import BaseModel
+
+router = APIRouter()
+
+
+class PlayerActionRequest(BaseModel):
+    action: str  # move, talk, work, eat, etc.
+    target: str = ""
+    detail: str = ""
+
+
+class PlayerJoinRequest(BaseModel):
+    name: str
+    background: str = "A newcomer to Soci City."
+
+
+@router.get("/city")
+async def get_city():
+    """Get the full city state — locations, agents, time, weather."""
+    from soci.api.server import get_simulation
+    sim = get_simulation()
+    return sim.get_state_summary()
+
+
+@router.get("/city/locations")
+async def get_locations():
+    """Get all city locations and who's there."""
+    from soci.api.server import get_simulation
+    sim = get_simulation()
+    return {
+        lid: {
+            "name": loc.name,
+            "zone": loc.zone,
+            "description": loc.description,
+            "occupants": [
+                {"id": aid, "name": sim.agents[aid].name, "state": sim.agents[aid].state.value}
+                for aid in loc.occupants if aid in sim.agents
+            ],
+            "connected_to": loc.connected_to,
+        }
+        for lid, loc in sim.city.locations.items()
+    }
+
+
+@router.get("/agents")
+async def get_agents():
+    """Get summary of all agents."""
+    from soci.api.server import get_simulation
+    sim = get_simulation()
+    return {
+        aid: {
+            "name": a.name,
+            "age": a.persona.age,
+            "occupation": a.persona.occupation,
+            "location": a.location,
+            "state": a.state.value,
+            "mood": round(a.mood, 2),
+            "action": a.current_action.detail if a.current_action else "idle",
+            "is_player": a.is_player,
+        }
+        for aid, a in sim.agents.items()
+    }
+
+
+@router.get("/agents/{agent_id}")
+async def get_agent(agent_id: str):
+    """Get detailed info about a specific agent."""
+    from soci.api.server import get_simulation
+    sim = get_simulation()
+    agent = sim.agents.get(agent_id)
+    if not agent:
+        raise HTTPException(status_code=404, detail=f"Agent {agent_id} not found")
+
+    loc = sim.city.get_location(agent.location)
+    return {
+        "id": agent.id,
+        "name": agent.name,
+        "age": agent.persona.age,
+        "occupation": agent.persona.occupation,
+        "traits": agent.persona.trait_summary,
+        "location": {"id": agent.location, "name": loc.name if loc else "unknown"},
+        "state": agent.state.value,
+        "mood": round(agent.mood, 2),
+        "needs": agent.needs.to_dict(),
+        "needs_description": agent.needs.describe(),
+        "action": agent.current_action.detail if agent.current_action else "idle",
+        "daily_plan": agent.daily_plan,
+        "relationships": [
+            {
+                "agent_id": rel.agent_id,
+                "name": rel.agent_name,
+                "closeness": round(rel.closeness, 2),
+                "description": rel.describe(),
+            }
+            for rel in agent.relationships.get_closest(10)
+        ],
+        "recent_memories": [
+            {
+                "time": f"Day {m.day} {m.time_str}",
+                "type": m.type.value,
+                "content": m.content,
+                "importance": m.importance,
+            }
+            for m in agent.memory.get_recent(10)
+        ],
+    }
+
+
+@router.get("/agents/{agent_id}/memories")
+async def get_agent_memories(agent_id: str, limit: int = 20):
+    """Get an agent's memory stream."""
+    from soci.api.server import get_simulation
+    sim = get_simulation()
+    agent = sim.agents.get(agent_id)
+    if not agent:
+        raise HTTPException(status_code=404, detail=f"Agent {agent_id} not found")
+
+    return [
+        {
+            "id": m.id,
+            "time": f"Day {m.day} {m.time_str}",
+            "type": m.type.value,
+            "content": m.content,
+            "importance": m.importance,
+            "involved_agents": m.involved_agents,
+        }
+        for m in agent.memory.memories[-limit:]
+    ]
+
+
+@router.get("/conversations")
+async def get_active_conversations():
+    """Get all active conversations."""
+    from soci.api.server import get_simulation
+    sim = get_simulation()
+    return {
+        cid: {
+            "participants": [
+                sim.agents[p].name for p in c.participants if p in sim.agents
+            ],
+            "topic": c.topic,
+            "turns": len(c.turns),
+            "latest": c.turns[-1].message if c.turns else "",
+        }
+        for cid, c in sim.active_conversations.items()
+    }
+
+
+@router.get("/stats")
+async def get_stats():
+    """Get simulation statistics and LLM usage."""
+    from soci.api.server import get_simulation
+    sim = get_simulation()
+    return {
+        "clock": sim.clock.to_dict(),
+        "total_agents": len(sim.agents),
+        "active_conversations": len(sim.active_conversations),
+        "llm_usage": {
+            "total_calls": sim.llm.usage.total_calls,
+            "total_input_tokens": sim.llm.usage.total_input_tokens,
+            "total_output_tokens": sim.llm.usage.total_output_tokens,
+            "estimated_cost_usd": round(sim.llm.usage.estimated_cost_usd, 4),
+            "calls_by_model": sim.llm.usage.calls_by_model,
+        },
+    }
+
+
+@router.post("/player/join")
+async def player_join(request: PlayerJoinRequest):
+    """Register a human player as a new agent in the simulation."""
+    from soci.agents.agent import Agent
+    from soci.agents.persona import Persona
+    from soci.api.server import get_simulation
+    sim = get_simulation()
+
+    player_id = f"player_{request.name.lower().replace(' ', '_')}"
+    if player_id in sim.agents:
+        raise HTTPException(status_code=400, detail="Player already exists")
+
+    persona = Persona(
+        id=player_id,
+        name=request.name,
+        age=25,
+        occupation="newcomer",
+        background=request.background,
+        home_location="home_north",
+        work_location="",
+    )
+    agent = Agent(persona)
+    agent.is_player = True
+    sim.add_agent(agent)
+
+    return {"id": player_id, "message": f"Welcome to Soci City, {request.name}!"}
+
+
+@router.post("/player/{player_id}/action")
+async def player_action(player_id: str, request: PlayerActionRequest):
+    """Submit an action for a human player."""
+    from soci.agents.agent import AgentAction
+    from soci.actions.registry import resolve_action
+    from soci.api.server import get_simulation
+    sim = get_simulation()
+
+    agent = sim.agents.get(player_id)
+    if not agent or not agent.is_player:
+        raise HTTPException(status_code=404, detail="Player not found")
+
+    if agent.is_busy:
+        return {"status": "busy", "message": f"You're currently {agent.current_action.detail}"}
+
+    action = resolve_action(
+        {"action": request.action, "target": request.target, "detail": request.detail},
+        agent,
+        sim.city,
+    )
+    await sim._execute_action(agent, action)
+
+    return {
+        "status": "ok",
+        "action": action.to_dict(),
+        "location": agent.location,
+    }
+
+
+@router.post("/save")
+async def save_state(name: str = "manual_save"):
+    """Manually save the simulation state."""
+    from soci.api.server import get_simulation, get_database
+    sim = get_simulation()
+    db = get_database()
+    from soci.persistence.snapshots import save_simulation
+    await save_simulation(sim, db, name)
+    return {"status": "saved", "name": name, "tick": sim.clock.total_ticks}

src/soci/api/server.py

@@ -0,0 +1,124 @@
+"""FastAPI server — serves the simulation state and handles player input."""
+
+from __future__ import annotations
+
+import asyncio
+import logging
+from contextlib import asynccontextmanager
+from pathlib import Path
+from typing import Optional
+
+from fastapi import FastAPI
+from fastapi.middleware.cors import CORSMiddleware
+
+from soci.engine.llm import ClaudeClient
+from soci.engine.simulation import Simulation
+from soci.persistence.database import Database
+from soci.persistence.snapshots import load_simulation, save_simulation
+from soci.world.city import City
+from soci.world.clock import SimClock
+from soci.api.routes import router
+from soci.api.websocket import ws_router
+
+logger = logging.getLogger(__name__)
+
+# Global simulation instance (shared across requests)
+_simulation: Optional[Simulation] = None
+_database: Optional[Database] = None
+_sim_task: Optional[asyncio.Task] = None
+
+
+def get_simulation() -> Simulation:
+    assert _simulation is not None, "Simulation not initialized"
+    return _simulation
+
+
+def get_database() -> Database:
+    assert _database is not None, "Database not initialized"
+    return _database
+
+
+async def simulation_loop(sim: Simulation, db: Database, tick_delay: float = 2.0) -> None:
+    """Background task that runs the simulation continuously."""
+    while True:
+        try:
+            await sim.tick()
+            # Auto-save every 24 ticks
+            if sim.clock.total_ticks % 24 == 0:
+                await save_simulation(sim, db, "autosave")
+            await asyncio.sleep(tick_delay)
+        except asyncio.CancelledError:
+            logger.info("Simulation loop cancelled")
+            await save_simulation(sim, db, "autosave")
+            break
+        except Exception as e:
+            logger.error(f"Simulation tick error: {e}", exc_info=True)
+            await asyncio.sleep(5)  # Wait before retrying
+
+
+@asynccontextmanager
+async def lifespan(app: FastAPI):
+    """Manage simulation lifecycle."""
+    global _simulation, _database, _sim_task
+
+    # Start up
+    logger.info("Starting Soci API server...")
+    llm = ClaudeClient()
+    db = Database()
+    await db.connect()
+    _database = db
+
+    # Try to resume
+    sim = await load_simulation(db, llm)
+    if sim is None:
+        # Create new
+        config_dir = Path(__file__).parents[3] / "config"
+        city = City.from_yaml(str(config_dir / "city.yaml"))
+        clock = SimClock(tick_minutes=15, hour=6, minute=0)
+        sim = Simulation(city=city, clock=clock, llm=llm)
+        sim.load_agents_from_yaml(str(config_dir / "personas.yaml"))
+        logger.info(f"Created new simulation with {len(sim.agents)} agents")
+
+    _simulation = sim
+
+    # Start background simulation
+    _sim_task = asyncio.create_task(simulation_loop(sim, db, tick_delay=2.0))
+
+    yield
+
+    # Shut down
+    if _sim_task:
+        _sim_task.cancel()
+        try:
+            await _sim_task
+        except asyncio.CancelledError:
+            pass
+    await save_simulation(sim, db, "shutdown_save")
+    await db.close()
+    logger.info("Soci API server stopped.")
+
+
+def create_app() -> FastAPI:
+    """Create the FastAPI application."""
+    app = FastAPI(
+        title="Soci — City Population Simulator",
+        description="API for the LLM-powered city population simulation",
+        version="0.1.0",
+        lifespan=lifespan,
+    )
+
+    app.add_middleware(
+        CORSMiddleware,
+        allow_origins=["*"],
+        allow_credentials=True,
+        allow_methods=["*"],
+        allow_headers=["*"],
+    )
+
+    app.include_router(router, prefix="/api")
+    app.include_router(ws_router)
+
+    return app
+
+
+app = create_app()

src/soci/api/websocket.py

@@ -0,0 +1,125 @@
+"""WebSocket — real-time event stream for live clients and future game UI."""
+
+from __future__ import annotations
+
+import asyncio
+import json
+import logging
+from typing import Optional
+
+from fastapi import APIRouter, WebSocket, WebSocketDisconnect
+
+logger = logging.getLogger(__name__)
+
+ws_router = APIRouter()
+
+
+class ConnectionManager:
+    """Manages WebSocket connections for real-time event streaming."""
+
+    def __init__(self) -> None:
+        self.active_connections: list[WebSocket] = []
+
+    async def connect(self, websocket: WebSocket) -> None:
+        await websocket.accept()
+        self.active_connections.append(websocket)
+        logger.info(f"WebSocket client connected. Total: {len(self.active_connections)}")
+
+    def disconnect(self, websocket: WebSocket) -> None:
+        if websocket in self.active_connections:
+            self.active_connections.remove(websocket)
+        logger.info(f"WebSocket client disconnected. Total: {len(self.active_connections)}")
+
+    async def broadcast(self, message: dict) -> None:
+        """Send a message to all connected clients."""
+        disconnected = []
+        for connection in self.active_connections:
+            try:
+                await connection.send_json(message)
+            except Exception:
+                disconnected.append(connection)
+        for conn in disconnected:
+            self.disconnect(conn)
+
+    async def send_personal(self, websocket: WebSocket, message: dict) -> None:
+        await websocket.send_json(message)
+
+
+manager = ConnectionManager()
+
+
+def get_manager() -> ConnectionManager:
+    return manager
+
+
+@ws_router.websocket("/ws/stream")
+async def websocket_stream(websocket: WebSocket):
+    """Real-time event stream.
+
+    Clients receive JSON messages with:
+    - type: "tick" — new simulation tick with summary
+    - type: "event" — world event occurred
+    - type: "conversation" — new conversation turn
+    - type: "action" — agent performed an action
+    """
+    await manager.connect(websocket)
+
+    try:
+        # Set up event forwarding from the simulation
+        from soci.api.server import get_simulation
+        sim = get_simulation()
+
+        # Store the original callback
+        original_callback = sim.on_event
+
+        # Add our own callback that also sends to WebSocket
+        async def ws_event_handler(msg: str):
+            if original_callback:
+                original_callback(msg)
+            await manager.broadcast({
+                "type": "event",
+                "message": msg,
+                "tick": sim.clock.total_ticks,
+                "time": sim.clock.datetime_str,
+            })
+
+        # We can't easily replace the sync callback with async,
+        # so instead we poll the simulation state
+        last_tick = sim.clock.total_ticks
+        while True:
+            try:
+                # Wait for client messages (ping/pong or player input)
+                try:
+                    data = await asyncio.wait_for(
+                        websocket.receive_text(),
+                        timeout=1.0,
+                    )
+                    # Handle client input
+                    try:
+                        msg = json.loads(data)
+                        if msg.get("type") == "ping":
+                            await manager.send_personal(websocket, {"type": "pong"})
+                    except json.JSONDecodeError:
+                        pass
+                except asyncio.TimeoutError:
+                    pass
+
+                # Send state updates if tick advanced
+                current_tick = sim.clock.total_ticks
+                if current_tick > last_tick:
+                    state = sim.get_state_summary()
+                    await manager.send_personal(websocket, {
+                        "type": "tick",
+                        "tick": current_tick,
+                        "time": sim.clock.datetime_str,
+                        "state": state,
+                    })
+                    last_tick = current_tick
+
+            except WebSocketDisconnect:
+                break
+
+    except Exception as e:
+        logger.error(f"WebSocket error: {e}")
+    finally:
+        manager.disconnect(websocket)

src/soci/engine/entropy.py

@@ -0,0 +1,151 @@
+"""Entropy management — keeps the simulation diverse and interesting."""
+
+from __future__ import annotations
+
+import random
+import logging
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from soci.agents.agent import Agent
+    from soci.world.clock import SimClock
+    from soci.world.events import EventSystem
+
+logger = logging.getLogger(__name__)
+
+
+class EntropyManager:
+    """Manages simulation entropy to prevent bland, repetitive behavior."""
+
+    def __init__(self) -> None:
+        # How often to inject events (every N ticks)
+        self.event_injection_interval: int = 10
+        # Ticks since last injection
+        self._ticks_since_event: int = 0
+        # Track agent behavior patterns for drift detection
+        self._action_history: dict[str, list[str]] = {}  # agent_id -> last N actions
+        self._history_window: int = 20
+
+    def tick(
+        self,
+        agents: list[Agent],
+        event_system: EventSystem,
+        clock: SimClock,
+        city_location_ids: list[str],
+    ) -> list[str]:
+        """Process one tick of entropy management. Returns list of notable events/messages."""
+        messages: list[str] = []
+        self._ticks_since_event += 1
+
+        # Track action patterns
+        for agent in agents:
+            if agent.current_action:
+                history = self._action_history.setdefault(agent.id, [])
+                history.append(agent.current_action.type)
+                if len(history) > self._history_window:
+                    self._action_history[agent.id] = history[-self._history_window:]
+
+        # Detect repetitive behavior
+        for agent in agents:
+            if self._is_stuck_in_loop(agent.id):
+                messages.append(
+                    f"[ENTROPY] {agent.name} seems stuck in a behavioral loop — "
+                    f"injecting stimulus."
+                )
+                self._inject_personal_stimulus(agent, clock)
+
+        # Periodic event injection
+        if self._ticks_since_event >= self.event_injection_interval:
+            new_events = event_system.tick(city_location_ids)
+            self._ticks_since_event = 0
+            for evt in new_events:
+                messages.append(f"[EVENT] {evt.name}: {evt.description}")
+        else:
+            # Still tick the event system for weather/expiry
+            event_system.tick(city_location_ids)
+
+        # Time-based entropy: inject daily rhythm changes
+        if clock.hour == 12 and clock.minute == 0:
+            messages.append("[RHYTHM] Noon — the city bustles with lunch crowds.")
+        elif clock.hour == 18 and clock.minute == 0:
+            messages.append("[RHYTHM] Evening — people head home or to the bar.")
+        elif clock.hour == 22 and clock.minute == 0:
+            messages.append("[RHYTHM] Late night — the city quiets down.")
+
+        return messages
+
+    def _is_stuck_in_loop(self, agent_id: str) -> bool:
+        """Detect if an agent is repeating the same actions."""
+        history = self._action_history.get(agent_id, [])
+        if len(history) < 10:
+            return False
+        # Check if last 10 actions are all the same
+        recent = history[-10:]
+        unique = set(recent)
+        return len(unique) <= 2 and "sleep" not in unique
+
+    def _inject_personal_stimulus(self, agent: Agent, clock: SimClock) -> None:
+        """Inject a personal event to break an agent out of a loop."""
+        stimuli = [
+            f"{agent.name} suddenly remembers something important they forgot to do.",
+            f"{agent.name} gets an unexpected phone call from an old friend.",
+            f"{agent.name} notices something unusual in their surroundings.",
+            f"{agent.name} overhears an interesting conversation nearby.",
+            f"{agent.name} finds a forgotten note in their pocket.",
+            f"{agent.name} suddenly craves something completely different.",
+        ]
+        stimulus = random.choice(stimuli)
+        agent.add_observation(
+            tick=clock.total_ticks,
+            day=clock.day,
+            time_str=clock.time_str,
+            content=stimulus,
+            importance=7,
+        )
+
+    def get_conflict_catalysts(self, agents: list[Agent]) -> list[tuple[str, str, str]]:
+        """Identify potential conflicts between agents based on their personas.
+        Returns list of (agent1_id, agent2_id, tension_description) tuples.
+        """
+        catalysts = []
+
+        # Find agents with opposing values or competing interests
+        for i, a in enumerate(agents):
+            for b in agents[i + 1:]:
+                tension = self._find_tension(a, b)
+                if tension:
+                    catalysts.append((a.id, b.id, tension))
+
+        return catalysts
+
+    def _find_tension(self, a: Agent, b: Agent) -> str | None:
+        """Find natural tension between two agents."""
+        # Big personality differences can create friction
+        extraversion_gap = abs(a.persona.extraversion - b.persona.extraversion)
+        agreeableness_gap = abs(a.persona.agreeableness - b.persona.agreeableness)
+
+        if extraversion_gap >= 6 and agreeableness_gap >= 4:
+            return "personality clash — one is outgoing and blunt, the other is reserved and sensitive"
+
+        # Competing values
+        a_values = set(a.persona.values)
+        b_values = set(b.persona.values)
+        if a_values and b_values and not a_values.intersection(b_values):
+            return f"different values — {a.name} values {', '.join(a.persona.values)}, while {b.name} values {', '.join(b.persona.values)}"
+
+        return None
+
+    def to_dict(self) -> dict:
+        return {
+            "event_injection_interval": self.event_injection_interval,
+            "ticks_since_event": self._ticks_since_event,
+            "action_history": dict(self._action_history),
+        }
+
+    @classmethod
+    def from_dict(cls, data: dict) -> EntropyManager:
+        mgr = cls()
+        mgr.event_injection_interval = data.get("event_injection_interval", 10)
+        mgr._ticks_since_event = data.get("ticks_since_event", 0)
+        mgr._action_history = data.get("action_history", {})
+        return mgr

src/soci/engine/llm.py

@@ -0,0 +1,292 @@
+"""LLM client — Claude API wrapper with model routing, cost tracking, and prompt templates."""
+
+from __future__ import annotations
+
+import json
+import logging
+import os
+import time
+from dataclasses import dataclass, field
+from typing import Optional
+
+import anthropic
+
+logger = logging.getLogger(__name__)
+
+# Model IDs
+MODEL_SONNET = "claude-sonnet-4-5-20250929"
+MODEL_HAIKU = "claude-haiku-4-5-20251001"
+
+# Approximate cost per 1M tokens (USD)
+COST_PER_1M = {
+    MODEL_SONNET: {"input": 3.0, "output": 15.0},
+    MODEL_HAIKU: {"input": 0.80, "output": 4.0},
+}
+
+
+@dataclass
+class LLMUsage:
+    """Tracks API usage and costs."""
+
+    total_calls: int = 0
+    total_input_tokens: int = 0
+    total_output_tokens: int = 0
+    calls_by_model: dict[str, int] = field(default_factory=dict)
+    tokens_by_model: dict[str, dict[str, int]] = field(default_factory=dict)
+
+    def record(self, model: str, input_tokens: int, output_tokens: int) -> None:
+        self.total_calls += 1
+        self.total_input_tokens += input_tokens
+        self.total_output_tokens += output_tokens
+        self.calls_by_model[model] = self.calls_by_model.get(model, 0) + 1
+        if model not in self.tokens_by_model:
+            self.tokens_by_model[model] = {"input": 0, "output": 0}
+        self.tokens_by_model[model]["input"] += input_tokens
+        self.tokens_by_model[model]["output"] += output_tokens
+
+    @property
+    def estimated_cost_usd(self) -> float:
+        total = 0.0
+        for model, tokens in self.tokens_by_model.items():
+            costs = COST_PER_1M.get(model, {"input": 3.0, "output": 15.0})
+            total += tokens["input"] / 1_000_000 * costs["input"]
+            total += tokens["output"] / 1_000_000 * costs["output"]
+        return total
+
+    def summary(self) -> str:
+        lines = [
+            f"Total API calls: {self.total_calls}",
+            f"Total tokens: {self.total_input_tokens:,} in / {self.total_output_tokens:,} out",
+            f"Estimated cost: ${self.estimated_cost_usd:.4f}",
+        ]
+        for model, count in self.calls_by_model.items():
+            short = model.split("-")[1] if "-" in model else model
+            lines.append(f"  {short}: {count} calls")
+        return "\n".join(lines)
+
+
+class ClaudeClient:
+    """Wrapper around the Anthropic Claude API with model routing and retries."""
+
+    def __init__(
+        self,
+        api_key: Optional[str] = None,
+        default_model: str = MODEL_HAIKU,
+        max_retries: int = 3,
+    ) -> None:
+        self.api_key = api_key or os.environ.get("ANTHROPIC_API_KEY", "")
+        if not self.api_key:
+            raise ValueError(
+                "ANTHROPIC_API_KEY not set. Copy .env.example to .env and add your key."
+            )
+        self.client = anthropic.Anthropic(api_key=self.api_key)
+        self.default_model = default_model
+        self.max_retries = max_retries
+        self.usage = LLMUsage()
+
+    async def complete(
+        self,
+        system: str,
+        user_message: str,
+        model: Optional[str] = None,
+        temperature: float = 0.7,
+        max_tokens: int = 1024,
+    ) -> str:
+        """Send a message to Claude and return the text response."""
+        model = model or self.default_model
+
+        for attempt in range(self.max_retries):
+            try:
+                response = self.client.messages.create(
+                    model=model,
+                    max_tokens=max_tokens,
+                    temperature=temperature,
+                    system=system,
+                    messages=[{"role": "user", "content": user_message}],
+                )
+                # Track usage
+                self.usage.record(
+                    model=model,
+                    input_tokens=response.usage.input_tokens,
+                    output_tokens=response.usage.output_tokens,
+                )
+                return response.content[0].text
+
+            except anthropic.RateLimitError:
+                wait = 2 ** attempt
+                logger.warning(f"Rate limited, waiting {wait}s (attempt {attempt + 1})")
+                time.sleep(wait)
+            except anthropic.APIError as e:
+                logger.error(f"API error: {e}")
+                if attempt == self.max_retries - 1:
+                    raise
+                time.sleep(1)
+
+        return ""
+
+    async def complete_json(
+        self,
+        system: str,
+        user_message: str,
+        model: Optional[str] = None,
+        temperature: float = 0.7,
+        max_tokens: int = 1024,
+    ) -> dict:
+        """Send a message and parse the response as JSON."""
+        # Add JSON instruction to the prompt
+        json_instruction = (
+            "\n\nRespond ONLY with valid JSON. No markdown, no explanation, no extra text. "
+            "Just the JSON object."
+        )
+        text = await self.complete(
+            system=system,
+            user_message=user_message + json_instruction,
+            model=model,
+            temperature=temperature,
+            max_tokens=max_tokens,
+        )
+        # Try to extract JSON from the response
+        text = text.strip()
+        # Handle markdown code blocks
+        if text.startswith("```"):
+            lines = text.split("\n")
+            text = "\n".join(lines[1:-1]) if len(lines) > 2 else text
+        try:
+            return json.loads(text)
+        except json.JSONDecodeError:
+            # Try to find JSON in the response
+            start = text.find("{")
+            end = text.rfind("}") + 1
+            if start >= 0 and end > start:
+                try:
+                    return json.loads(text[start:end])
+                except json.JSONDecodeError:
+                    pass
+            logger.warning(f"Failed to parse JSON from LLM response: {text[:200]}")
+            return {}
+
+
+# --- Prompt Templates ---
+
+PLAN_DAY_PROMPT = """\
+It is {time_str} on Day {day}. You just woke up.
+
+{context}
+
+Based on your personality, needs, and memories, plan your day. What will you do today?
+Think about your obligations (work, responsibilities) and your desires (socializing, fun, rest).
+
+Respond with a JSON object:
+{{
+  "plan": ["item 1", "item 2", ...],
+  "reasoning": "brief explanation of why this plan"
+}}
+
+Keep the plan to 5-8 items. Be specific about locations and times.
+"""
+
+DECIDE_ACTION_PROMPT = """\
+It is {time_str} on Day {day}.
+
+{context}
+
+You are currently at {location_name}. You just finished: {last_activity}.
+
+What do you do next? Consider your needs, your plan, who's around, and any events happening.
+
+Respond with a JSON object:
+{{
+  "action": "move|work|eat|sleep|talk|exercise|shop|relax|wander",
+  "target": "location_id or agent_id (if talking) or empty string",
+  "detail": "what specifically you're doing, in first person",
+  "duration": 1-4,
+  "reasoning": "brief internal thought about why"
+}}
+
+Available locations you can move to: {connected_locations}
+People at your current location: {people_here}
+"""
+
+OBSERVE_PROMPT = """\
+It is {time_str} on Day {day}.
+
+{context}
+
+You just noticed: {observation}
+
+How important is this to you (1-10)? What do you think about it?
+
+Respond with a JSON object:
+{{
+  "importance": 1-10,
+  "reaction": "your brief internal thought or feeling about this"
+}}
+"""
+
+REFLECT_PROMPT = """\
+It is {time_str} on Day {day}.
+
+{context}
+
+RECENT EXPERIENCES:
+{recent_memories}
+
+Take a moment to reflect on your recent experiences. What patterns do you notice?
+What have you learned? How do you feel about things?
+
+Respond with a JSON object:
+{{
+  "reflections": ["reflection 1", "reflection 2", ...],
+  "mood_shift": -0.3 to 0.3,
+  "reasoning": "why your mood shifted this way"
+}}
+
+Generate 1-3 reflections. Each should be a genuine insight, not just a summary.
+"""
+
+CONVERSATION_PROMPT = """\
+It is {time_str} on Day {day}.
+
+{context}
+
+You are at {location_name}. {other_name} is here too.
+
+WHAT YOU KNOW ABOUT {other_name}:
+{relationship_context}
+
+{conversation_history}
+
+{other_name} says: "{other_message}"
+
+How do you respond? Stay in character. Be natural — not every conversation is deep.
+Sometimes people make small talk, sometimes they argue, sometimes they're awkward.
+
+Respond with a JSON object:
+{{
+  "message": "your spoken response",
+  "inner_thought": "what you're actually thinking",
+  "sentiment_delta": -0.1 to 0.1,
+  "trust_delta": -0.05 to 0.05
+}}
+"""
+
+CONVERSATION_INITIATE_PROMPT = """\
+It is {time_str} on Day {day}.
+
+{context}
+
+You are at {location_name}. {other_name} is here.
+
+WHAT YOU KNOW ABOUT {other_name}:
+{relationship_context}
+
+You decide to start a conversation with {other_name}. What do you say?
+Consider the time of day, location, your mood, and your history with them.
+
+Respond with a JSON object:
+{{
+  "message": "what you say to start the conversation",
+  "inner_thought": "why you're initiating this conversation",
+  "topic": "brief topic label"
+}}
+"""

src/soci/engine/scheduler.py

@@ -0,0 +1,78 @@
+"""Scheduler — manages agent turn order and batching for LLM calls."""
+
+from __future__ import annotations
+
+import asyncio
+import logging
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from soci.agents.agent import Agent
+    from soci.world.clock import SimClock
+
+logger = logging.getLogger(__name__)
+
+
+def prioritize_agents(agents: list[Agent], clock: SimClock) -> list[Agent]:
+    """Sort agents by priority for this tick. Agents with urgent needs go first."""
+    def priority_score(agent: Agent) -> float:
+        score = 0.0
+        # Urgent needs boost priority
+        if agent.needs.is_critical:
+            score += 10.0
+        urgent = agent.needs.urgent_needs
+        score += len(urgent) * 2.0
+        # Idle agents need decisions
+        if not agent.is_busy:
+            score += 5.0
+        # Sleeping agents are low priority
+        if agent.state.value == "sleeping":
+            score -= 5.0
+        # Players always get processed
+        if agent.is_player:
+            score += 20.0
+        return score
+
+    return sorted(agents, key=priority_score, reverse=True)
+
+
+async def batch_llm_calls(
+    coros: list,
+    max_concurrent: int = 10,
+) -> list:
+    """Run multiple LLM coroutines concurrently with a concurrency limit."""
+    semaphore = asyncio.Semaphore(max_concurrent)
+
+    async def limited(coro):
+        async with semaphore:
+            return await coro
+
+    results = await asyncio.gather(
+        *[limited(c) for c in coros],
+        return_exceptions=True,
+    )
+
+    # Log any errors
+    for i, r in enumerate(results):
+        if isinstance(r, Exception):
+            logger.error(f"LLM call {i} failed: {r}")
+            results[i] = None
+
+    return results
+
+
+def should_skip_llm(agent: Agent, clock: SimClock) -> bool:
+    """Determine if we can skip the LLM call for this agent (habit caching)."""
+    # Never skip players
+    if agent.is_player:
+        return False
+
+    # If agent is busy with a multi-tick action, skip
+    if agent.is_busy:
+        return True
+
+    # If sleeping during sleep hours, keep sleeping
+    if agent.state.value == "sleeping" and clock.is_sleeping_hours:
+        return True
+
+    return False

src/soci/engine/simulation.py

@@ -0,0 +1,478 @@
+"""Simulation — the main loop that orchestrates the entire city simulation."""
+
+from __future__ import annotations
+
+import asyncio
+import logging
+import random
+from typing import Callable, Optional
+
+from soci.agents.agent import Agent, AgentAction
+from soci.agents.memory import MemoryType
+from soci.agents.persona import Persona, load_personas
+from soci.actions.registry import resolve_action, ACTION_NEEDS, ACTION_DURATIONS
+from soci.actions.movement import execute_move
+from soci.actions.activities import execute_activity
+from soci.actions.conversation import (
+    Conversation, initiate_conversation, continue_conversation,
+)
+from soci.actions.social import should_initiate_conversation, pick_conversation_partner
+from soci.engine.llm import (
+    ClaudeClient, MODEL_SONNET, MODEL_HAIKU,
+    PLAN_DAY_PROMPT, DECIDE_ACTION_PROMPT, OBSERVE_PROMPT, REFLECT_PROMPT,
+)
+from soci.engine.scheduler import prioritize_agents, batch_llm_calls, should_skip_llm
+from soci.engine.entropy import EntropyManager
+from soci.world.city import City
+from soci.world.clock import SimClock
+from soci.world.events import EventSystem
+
+logger = logging.getLogger(__name__)
+
+
+class Simulation:
+    """The main simulation engine — manages the city, agents, and time."""
+
+    def __init__(
+        self,
+        city: City,
+        clock: SimClock,
+        llm: ClaudeClient,
+        max_concurrent_llm: int = 10,
+    ) -> None:
+        self.city = city
+        self.clock = clock
+        self.llm = llm
+        self.agents: dict[str, Agent] = {}
+        self.events = EventSystem()
+        self.entropy = EntropyManager()
+        self.active_conversations: dict[str, Conversation] = {}
+        self._conversation_counter: int = 0
+        self._max_concurrent = max_concurrent_llm
+        self._tick_log: list[str] = []  # Log of events this tick
+        # Callback for real-time output
+        self.on_event: Optional[Callable[[str], None]] = None
+
+    def add_agent(self, agent: Agent) -> None:
+        """Add an agent to the simulation and place them in the city."""
+        self.agents[agent.id] = agent
+        self.city.place_agent(agent.id, agent.location)
+
+    def load_agents_from_yaml(self, path: str) -> None:
+        """Load all personas from YAML and create agents."""
+        personas = load_personas(path)
+        for persona in personas:
+            agent = Agent(persona)
+            self.add_agent(agent)
+        logger.info(f"Loaded {len(personas)} agents from {path}")
+
+    def _emit(self, message: str) -> None:
+        """Emit an event message."""
+        self._tick_log.append(message)
+        if self.on_event:
+            self.on_event(message)
+
+    async def tick(self) -> list[str]:
+        """Advance the simulation by one tick. Returns list of event descriptions."""
+        self._tick_log = []
+        self._emit(f"\n--- {self.clock.datetime_str} ({self.clock.time_of_day.value}) ---")
+
+        # 1. Entropy management and world events
+        entropy_messages = self.entropy.tick(
+            list(self.agents.values()),
+            self.events,
+            self.clock,
+            list(self.city.locations.keys()),
+        )
+        for msg in entropy_messages:
+            self._emit(msg)
+
+        # 2. New day — reset plans
+        if self.clock.hour == 6 and self.clock.minute == 0:
+            for agent in self.agents.values():
+                agent.reset_daily_plan()
+
+        # 3. Prioritize and process agents
+        ordered_agents = prioritize_agents(list(self.agents.values()), self.clock)
+
+        # 4. Generate daily plans for agents that need them
+        plan_coros = []
+        plan_agents = []
+        for agent in ordered_agents:
+            if agent.needs_new_plan(self.clock) and not should_skip_llm(agent, self.clock):
+                plan_coros.append(self._generate_daily_plan(agent))
+                plan_agents.append(agent)
+
+        if plan_coros:
+            await batch_llm_calls(plan_coros, self._max_concurrent)
+            for agent in plan_agents:
+                self._emit(f"[PLAN] {agent.name} planned their day: {'; '.join(agent.daily_plan[:3])}...")
+
+        # 5. Process each agent — tick their needs, handle actions
+        action_coros = []
+        action_agents = []
+        for agent in ordered_agents:
+            # Tick needs
+            is_sleeping = agent.state.value == "sleeping"
+            agent.tick_needs(is_sleeping=is_sleeping)
+
+            # Tick current action
+            if agent.is_busy:
+                completed = agent.tick_action()
+                if completed and agent.current_action:
+                    self._emit(f"  {agent.name} finished: {agent.current_action.detail}")
+                continue
+
+            # Skip LLM for sleeping agents during sleep hours, etc.
+            if should_skip_llm(agent, self.clock):
+                continue
+
+            # Agent is idle — needs a new action
+            action_coros.append(self._decide_action(agent))
+            action_agents.append(agent)
+
+        # Run all action decisions concurrently
+        if action_coros:
+            action_results = await batch_llm_calls(action_coros, self._max_concurrent)
+            for agent, result in zip(action_agents, action_results):
+                if result and isinstance(result, AgentAction):
+                    await self._execute_action(agent, result)
+
+        # 6. Handle active conversations
+        conv_coros = []
+        for conv_id, conv in list(self.active_conversations.items()):
+            if conv.is_finished:
+                self._finish_conversation(conv)
+                del self.active_conversations[conv_id]
+                continue
+            # Determine who speaks next
+            last_speaker = conv.turns[-1].speaker_id if conv.turns else None
+            next_speaker_id = [p for p in conv.participants if p != last_speaker]
+            if next_speaker_id:
+                responder = self.agents.get(next_speaker_id[0])
+                other = self.agents.get(last_speaker) if last_speaker else None
+                if responder and other:
+                    conv_coros.append(
+                        continue_conversation(conv, responder, other, self.llm, self.clock)
+                    )
+
+        if conv_coros:
+            await batch_llm_calls(conv_coros, self._max_concurrent)
+
+        # 7. Social: maybe start new conversations
+        await self._handle_social_interactions(ordered_agents)
+
+        # 8. Reflections for agents with enough accumulated importance
+        reflect_coros = []
+        reflect_agents = []
+        for agent in ordered_agents:
+            if agent.memory.should_reflect() and not agent.is_player:
+                reflect_coros.append(self._generate_reflection(agent))
+                reflect_agents.append(agent)
+
+        if reflect_coros:
+            await batch_llm_calls(reflect_coros, self._max_concurrent)
+
+        # 9. Advance clock
+        self.clock.tick()
+
+        return self._tick_log
+
+    async def _generate_daily_plan(self, agent: Agent) -> None:
+        """Generate a daily plan for an agent via LLM."""
+        world_desc = self.events.get_world_description()
+        loc_desc = self.city.describe_location(agent.location, exclude_agent=agent.id)
+
+        prompt = PLAN_DAY_PROMPT.format(
+            time_str=self.clock.time_str,
+            day=self.clock.day,
+            context=agent.build_context(self.clock.total_ticks, world_desc, loc_desc),
+        )
+
+        result = await self.llm.complete_json(
+            system=agent.persona.system_prompt(),
+            user_message=prompt,
+            model=MODEL_HAIKU,  # Plans are routine, use cheap model
+            temperature=agent.persona.llm_temperature,
+            max_tokens=512,
+        )
+
+        plan = result.get("plan", ["Go about my day"])
+        if isinstance(plan, list):
+            agent.set_daily_plan(plan, self.clock.day, self.clock.total_ticks, self.clock.time_str)
+
+    async def _decide_action(self, agent: Agent) -> Optional[AgentAction]:
+        """Ask the LLM what action an agent should take next."""
+        world_desc = self.events.get_world_description()
+        loc_desc = self.city.describe_location(agent.location, exclude_agent=agent.id)
+
+        # Get connected locations
+        current_loc = self.city.get_location(agent.location)
+        connected = []
+        if current_loc:
+            for cid in current_loc.connected_to:
+                cloc = self.city.get_location(cid)
+                if cloc:
+                    connected.append(f"{cid} ({cloc.name})")
+
+        # Get people at current location
+        people_here = [
+            self.agents[aid].name
+            for aid in self.city.get_agents_at(agent.location)
+            if aid != agent.id and aid in self.agents
+        ]
+
+        last_activity = "nothing in particular"
+        if agent.current_action:
+            last_activity = agent.current_action.detail or agent.current_action.type
+
+        prompt = DECIDE_ACTION_PROMPT.format(
+            time_str=self.clock.time_str,
+            day=self.clock.day,
+            context=agent.build_context(self.clock.total_ticks, world_desc, loc_desc),
+            location_name=loc_desc,
+            last_activity=last_activity,
+            connected_locations=", ".join(connected) if connected else "none visible",
+            people_here=", ".join(people_here) if people_here else "no one",
+        )
+
+        # Use Sonnet for novel situations, Haiku for routine
+        model = MODEL_HAIKU
+        if agent.needs.is_critical or self.events.active_events:
+            model = MODEL_SONNET
+
+        result = await self.llm.complete_json(
+            system=agent.persona.system_prompt(),
+            user_message=prompt,
+            model=model,
+            temperature=agent.persona.llm_temperature,
+            max_tokens=512,
+        )
+
+        if not result:
+            # Fallback: wander
+            return AgentAction(type="wander", detail=f"{agent.name} wanders aimlessly")
+
+        action = resolve_action(result, agent, self.city)
+        agent._last_llm_tick = self.clock.total_ticks
+        return action
+
+    async def _execute_action(self, agent: Agent, action: AgentAction) -> None:
+        """Execute an agent's chosen action."""
+        if action.type == "move":
+            desc = execute_move(agent, action, self.city, self.clock)
+        elif action.type == "talk":
+            # Talk action is handled via conversation system
+            target_id = action.target
+            if target_id and target_id in self.agents:
+                await self._start_conversation(agent, self.agents[target_id])
+                desc = f"{agent.name} starts talking to {self.agents[target_id].name}."
+            else:
+                desc = f"{agent.name} looks around for someone to talk to."
+        else:
+            desc = execute_activity(agent, action, self.city, self.clock)
+
+        agent.start_action(action)
+        self._emit(f"  {desc}")
+
+        # Record observation
+        agent.add_observation(
+            tick=self.clock.total_ticks,
+            day=self.clock.day,
+            time_str=self.clock.time_str,
+            content=desc,
+            importance=3,
+        )
+
+    async def _handle_social_interactions(self, agents: list[Agent]) -> None:
+        """Check if any idle co-located agents should start conversations."""
+        # Don't flood with conversations
+        if len(self.active_conversations) >= 3:
+            return
+
+        for agent in agents:
+            if agent.is_busy or agent.is_player:
+                continue
+            # Check if already in a conversation
+            in_conv = any(
+                agent.id in c.participants
+                for c in self.active_conversations.values()
+            )
+            if in_conv:
+                continue
+
+            others = [
+                aid for aid in self.city.get_agents_at(agent.location)
+                if aid != agent.id
+                and aid in self.agents
+                and not self.agents[aid].is_busy
+                and not any(aid in c.participants for c in self.active_conversations.values())
+            ]
+            if not others:
+                continue
+
+            partner_id = pick_conversation_partner(agent, others, self.clock)
+            if partner_id and should_initiate_conversation(agent, partner_id, self.clock):
+                await self._start_conversation(agent, self.agents[partner_id])
+                break  # One new conversation per tick max
+
+    async def _start_conversation(self, initiator: Agent, target: Agent) -> None:
+        """Start a conversation between two agents."""
+        self._conversation_counter += 1
+        conv_id = f"conv_{self._conversation_counter}"
+
+        conv = await initiate_conversation(
+            initiator, target, self.llm, self.clock, conv_id,
+        )
+        self.active_conversations[conv_id] = conv
+
+        # Both agents are now in conversation
+        from soci.agents.agent import AgentAction
+        talk_action = AgentAction(
+            type="talk",
+            target=target.id,
+            detail=f"talking to {target.name}",
+            duration_ticks=conv.max_turns,
+            needs_satisfied={"social": 0.3},
+        )
+        initiator.start_action(talk_action)
+
+        talk_action_target = AgentAction(
+            type="talk",
+            target=initiator.id,
+            detail=f"talking to {initiator.name}",
+            duration_ticks=conv.max_turns,
+            needs_satisfied={"social": 0.3},
+        )
+        target.start_action(talk_action_target)
+
+        self._emit(f"  [CONV] {initiator.name} starts talking to {target.name}")
+
+        # Both agents observe the conversation start
+        for agent, other in [(initiator, target), (target, initiator)]:
+            agent.add_observation(
+                tick=self.clock.total_ticks,
+                day=self.clock.day,
+                time_str=self.clock.time_str,
+                content=f"Started a conversation with {other.name} at {agent.location}",
+                importance=5,
+                involved_agents=[other.id],
+            )
+            # Ensure relationship exists
+            agent.relationships.get_or_create(other.id, other.name)
+
+    def _finish_conversation(self, conv: Conversation) -> None:
+        """Record a finished conversation in both agents' memories."""
+        if len(conv.turns) < 2:
+            return
+
+        summary = f"Had a conversation about '{conv.topic}' with "
+        for agent_id in conv.participants:
+            agent = self.agents.get(agent_id)
+            if not agent:
+                continue
+            other_ids = [p for p in conv.participants if p != agent_id]
+            other_names = [self.agents[oid].name for oid in other_ids if oid in self.agents]
+            agent.memory.add(
+                tick=self.clock.total_ticks,
+                day=self.clock.day,
+                time_str=self.clock.time_str,
+                memory_type=MemoryType.CONVERSATION,
+                content=f"Had a conversation about '{conv.topic}' with {', '.join(other_names)}.",
+                importance=6,
+                location=conv.location,
+                involved_agents=other_ids,
+            )
+
+        self._emit(
+            f"  [CONV END] Conversation about '{conv.topic}' between "
+            f"{', '.join(self.agents[p].name for p in conv.participants if p in self.agents)} ended."
+        )
+
+    async def _generate_reflection(self, agent: Agent) -> None:
+        """Generate a reflection for an agent about recent experiences."""
+        recent = agent.memory.get_recent(15)
+        recent_text = "\n".join(
+            f"- [{m.time_str}] {m.content}" for m in recent
+        )
+
+        world_desc = self.events.get_world_description()
+        loc_desc = self.city.describe_location(agent.location, exclude_agent=agent.id)
+
+        prompt = REFLECT_PROMPT.format(
+            time_str=self.clock.time_str,
+            day=self.clock.day,
+            context=agent.build_context(self.clock.total_ticks, world_desc, loc_desc),
+            recent_memories=recent_text,
+        )
+
+        result = await self.llm.complete_json(
+            system=agent.persona.system_prompt(),
+            user_message=prompt,
+            model=MODEL_HAIKU,
+            temperature=agent.persona.llm_temperature,
+            max_tokens=512,
+        )
+
+        reflections = result.get("reflections", [])
+        mood_shift = result.get("mood_shift", 0.0)
+
+        for ref_text in reflections:
+            agent.add_reflection(
+                tick=self.clock.total_ticks,
+                day=self.clock.day,
+                time_str=self.clock.time_str,
+                content=ref_text,
+            )
+
+        agent.mood = max(-1.0, min(1.0, agent.mood + mood_shift))
+        agent.memory.reset_reflection_accumulator()
+
+        if reflections:
+            self._emit(f"  [REFLECT] {agent.name}: {reflections[0]}")
+
+    def get_state_summary(self) -> dict:
+        """Get a summary of the current simulation state."""
+        return {
+            "clock": self.clock.to_dict(),
+            "weather": self.events.weather.value,
+            "active_events": [e.to_dict() for e in self.events.active_events],
+            "agents": {
+                aid: {
+                    "name": a.name,
+                    "location": a.location,
+                    "state": a.state.value,
+                    "mood": round(a.mood, 2),
+                    "needs": a.needs.to_dict(),
+                    "action": a.current_action.detail if a.current_action else "idle",
+                }
+                for aid, a in self.agents.items()
+            },
+            "active_conversations": len(self.active_conversations),
+            "llm_usage": self.llm.usage.summary(),
+        }
+
+    def to_dict(self) -> dict:
+        """Serialize full simulation state."""
+        return {
+            "city": self.city.to_dict(),
+            "clock": self.clock.to_dict(),
+            "agents": {aid: a.to_dict() for aid, a in self.agents.items()},
+            "events": self.events.to_dict(),
+            "entropy": self.entropy.to_dict(),
+            "conversation_counter": self._conversation_counter,
+        }
+
+    @classmethod
+    def from_dict(cls, data: dict, llm: ClaudeClient) -> Simulation:
+        """Restore a simulation from serialized state."""
+        city = City.from_dict(data["city"])
+        clock = SimClock.from_dict(data["clock"])
+        sim = cls(city=city, clock=clock, llm=llm)
+        sim.events = EventSystem.from_dict(data["events"])
+        sim.entropy = EntropyManager.from_dict(data["entropy"])
+        sim._conversation_counter = data.get("conversation_counter", 0)
+        for aid, agent_data in data["agents"].items():
+            agent = Agent.from_dict(agent_data)
+            sim.agents[agent.id] = agent
+        return sim

src/soci/persistence/database.py

@@ -0,0 +1,170 @@
+"""Database — SQLite persistence for simulation state."""
+
+from __future__ import annotations
+
+import json
+import logging
+import os
+from pathlib import Path
+from typing import Optional
+
+import aiosqlite
+
+logger = logging.getLogger(__name__)
+
+DB_DIR = Path("data")
+DEFAULT_DB = DB_DIR / "soci.db"
+
+SCHEMA = """
+CREATE TABLE IF NOT EXISTS snapshots (
+    id INTEGER PRIMARY KEY AUTOINCREMENT,
+    name TEXT NOT NULL,
+    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
+    tick INTEGER NOT NULL,
+    day INTEGER NOT NULL,
+    state_json TEXT NOT NULL
+);
+
+CREATE TABLE IF NOT EXISTS event_log (
+    id INTEGER PRIMARY KEY AUTOINCREMENT,
+    tick INTEGER NOT NULL,
+    day INTEGER NOT NULL,
+    time_str TEXT NOT NULL,
+    event_type TEXT NOT NULL,
+    agent_id TEXT,
+    location TEXT,
+    description TEXT NOT NULL,
+    metadata_json TEXT
+);
+
+CREATE TABLE IF NOT EXISTS conversations (
+    id INTEGER PRIMARY KEY AUTOINCREMENT,
+    conv_id TEXT NOT NULL,
+    tick INTEGER NOT NULL,
+    day INTEGER NOT NULL,
+    location TEXT NOT NULL,
+    participants_json TEXT NOT NULL,
+    topic TEXT,
+    turns_json TEXT NOT NULL
+);
+
+CREATE INDEX IF NOT EXISTS idx_event_tick ON event_log(tick);
+CREATE INDEX IF NOT EXISTS idx_event_agent ON event_log(agent_id);
+CREATE INDEX IF NOT EXISTS idx_conv_tick ON conversations(tick);
+"""
+
+
+class Database:
+    """Async SQLite database for simulation persistence."""
+
+    def __init__(self, db_path: str | Path = DEFAULT_DB) -> None:
+        self.db_path = Path(db_path)
+        self._db: Optional[aiosqlite.Connection] = None
+
+    async def connect(self) -> None:
+        """Connect to the database and create tables."""
+        self.db_path.parent.mkdir(parents=True, exist_ok=True)
+        self._db = await aiosqlite.connect(str(self.db_path))
+        await self._db.executescript(SCHEMA)
+        await self._db.commit()
+        logger.info(f"Database connected: {self.db_path}")
+
+    async def close(self) -> None:
+        if self._db:
+            await self._db.close()
+
+    async def save_snapshot(self, name: str, tick: int, day: int, state: dict) -> int:
+        """Save a full simulation state snapshot."""
+        assert self._db is not None
+        cursor = await self._db.execute(
+            "INSERT INTO snapshots (name, tick, day, state_json) VALUES (?, ?, ?, ?)",
+            (name, tick, day, json.dumps(state)),
+        )
+        await self._db.commit()
+        return cursor.lastrowid
+
+    async def load_snapshot(self, name: Optional[str] = None) -> Optional[dict]:
+        """Load the latest snapshot, or a specific named one."""
+        assert self._db is not None
+        if name:
+            cursor = await self._db.execute(
+                "SELECT state_json FROM snapshots WHERE name = ? ORDER BY id DESC LIMIT 1",
+                (name,),
+            )
+        else:
+            cursor = await self._db.execute(
+                "SELECT state_json FROM snapshots ORDER BY id DESC LIMIT 1",
+            )
+        row = await cursor.fetchone()
+        if row:
+            return json.loads(row[0])
+        return None
+
+    async def list_snapshots(self) -> list[dict]:
+        """List all saved snapshots."""
+        assert self._db is not None
+        cursor = await self._db.execute(
+            "SELECT id, name, created_at, tick, day FROM snapshots ORDER BY id DESC"
+        )
+        rows = await cursor.fetchall()
+        return [
+            {"id": r[0], "name": r[1], "created_at": r[2], "tick": r[3], "day": r[4]}
+            for r in rows
+        ]
+
+    async def log_event(
+        self,
+        tick: int,
+        day: int,
+        time_str: str,
+        event_type: str,
+        description: str,
+        agent_id: str = "",
+        location: str = "",
+        metadata: Optional[dict] = None,
+    ) -> None:
+        """Log a simulation event."""
+        assert self._db is not None
+        await self._db.execute(
+            "INSERT INTO event_log (tick, day, time_str, event_type, agent_id, location, description, metadata_json) "
+            "VALUES (?, ?, ?, ?, ?, ?, ?, ?)",
+            (tick, day, time_str, event_type, agent_id, location, description,
+             json.dumps(metadata) if metadata else None),
+        )
+        await self._db.commit()
+
+    async def save_conversation(self, conv_data: dict) -> None:
+        """Save a completed conversation."""
+        assert self._db is not None
+        await self._db.execute(
+            "INSERT INTO conversations (conv_id, tick, day, location, participants_json, topic, turns_json) "
+            "VALUES (?, ?, ?, ?, ?, ?, ?)",
+            (
+                conv_data["id"],
+                conv_data["turns"][-1]["tick"] if conv_data["turns"] else 0,
+                0,  # Day would be tracked from clock
+                conv_data["location"],
+                json.dumps(conv_data["participants"]),
+                conv_data.get("topic", ""),
+                json.dumps(conv_data["turns"]),
+            ),
+        )
+        await self._db.commit()
+
+    async def get_recent_events(self, limit: int = 50) -> list[dict]:
+        """Get recent events from the log."""
+        assert self._db is not None
+        cursor = await self._db.execute(
+            "SELECT tick, day, time_str, event_type, agent_id, location, description "
+            "FROM event_log ORDER BY id DESC LIMIT ?",
+            (limit,),
+        )
+        rows = await cursor.fetchall()
+        return [
+            {
+                "tick": r[0], "day": r[1], "time_str": r[2],
+                "event_type": r[3], "agent_id": r[4],
+                "location": r[5], "description": r[6],
+            }
+            for r in rows
+        ]

src/soci/persistence/snapshots.py

@@ -0,0 +1,68 @@
+"""Snapshots — save and load full simulation state."""
+
+from __future__ import annotations
+
+import json
+import logging
+from pathlib import Path
+from typing import Optional, TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from soci.engine.simulation import Simulation
+    from soci.engine.llm import ClaudeClient
+    from soci.persistence.database import Database
+
+logger = logging.getLogger(__name__)
+
+SNAPSHOTS_DIR = Path("data") / "snapshots"
+
+
+async def save_simulation(
+    sim: Simulation,
+    db: Database,
+    name: str = "autosave",
+) -> None:
+    """Save the full simulation state to database and JSON file."""
+    state = sim.to_dict()
+
+    # Save to database
+    await db.save_snapshot(
+        name=name,
+        tick=sim.clock.total_ticks,
+        day=sim.clock.day,
+        state=state,
+    )
+
+    # Also save as JSON file for easy inspection
+    SNAPSHOTS_DIR.mkdir(parents=True, exist_ok=True)
+    path = SNAPSHOTS_DIR / f"{name}.json"
+    with open(path, "w", encoding="utf-8") as f:
+        json.dump(state, f, indent=2, ensure_ascii=False)
+
+    logger.info(f"Simulation saved: {name} (tick {sim.clock.total_ticks}, day {sim.clock.day})")
+
+
+async def load_simulation(
+    db: Database,
+    llm: ClaudeClient,
+    name: Optional[str] = None,
+) -> Optional[Simulation]:
+    """Load a simulation from the database."""
+    from soci.engine.simulation import Simulation
+
+    state = await db.load_snapshot(name)
+    if not state:
+        # Try loading from JSON file
+        if name:
+            path = SNAPSHOTS_DIR / f"{name}.json"
+            if path.exists():
+                with open(path, "r", encoding="utf-8") as f:
+                    state = json.load(f)
+
+    if not state:
+        logger.warning(f"No snapshot found: {name or 'latest'}")
+        return None
+
+    sim = Simulation.from_dict(state, llm)
+    logger.info(f"Simulation loaded: tick {sim.clock.total_ticks}, day {sim.clock.day}")
+    return sim

src/soci/world/city.py

@@ -0,0 +1,157 @@
+"""City map — locations, zones, and connections between them."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Optional
+
+import yaml
+
+
+@dataclass
+class Location:
+    """A place in the city where agents can be."""
+
+    id: str
+    name: str
+    zone: str  # residential, commercial, public, work
+    description: str
+    capacity: int = 20
+    connected_to: list[str] = field(default_factory=list)
+    # Current occupants (agent IDs)
+    occupants: list[str] = field(default_factory=list, repr=False)
+
+    @property
+    def is_full(self) -> bool:
+        return len(self.occupants) >= self.capacity
+
+    @property
+    def occupant_count(self) -> int:
+        return len(self.occupants)
+
+    def add_occupant(self, agent_id: str) -> None:
+        if agent_id not in self.occupants:
+            self.occupants.append(agent_id)
+
+    def remove_occupant(self, agent_id: str) -> None:
+        if agent_id in self.occupants:
+            self.occupants.remove(agent_id)
+
+    def to_dict(self) -> dict:
+        return {
+            "id": self.id,
+            "name": self.name,
+            "zone": self.zone,
+            "description": self.description,
+            "capacity": self.capacity,
+            "connected_to": self.connected_to,
+            "occupants": list(self.occupants),
+        }
+
+
+class City:
+    """The city map — a graph of connected locations."""
+
+    def __init__(self, name: str = "Soci City") -> None:
+        self.name = name
+        self.locations: dict[str, Location] = {}
+
+    def add_location(self, location: Location) -> None:
+        self.locations[location.id] = location
+
+    def get_location(self, location_id: str) -> Optional[Location]:
+        return self.locations.get(location_id)
+
+    def get_connected(self, location_id: str) -> list[Location]:
+        loc = self.locations.get(location_id)
+        if not loc:
+            return []
+        return [self.locations[cid] for cid in loc.connected_to if cid in self.locations]
+
+    def get_locations_in_zone(self, zone: str) -> list[Location]:
+        return [loc for loc in self.locations.values() if loc.zone == zone]
+
+    def get_agents_at(self, location_id: str) -> list[str]:
+        loc = self.locations.get(location_id)
+        return list(loc.occupants) if loc else []
+
+    def move_agent(self, agent_id: str, from_id: str, to_id: str) -> bool:
+        """Move an agent between locations. Returns True if successful."""
+        from_loc = self.locations.get(from_id)
+        to_loc = self.locations.get(to_id)
+        if not from_loc or not to_loc:
+            return False
+        if to_loc.is_full:
+            return False
+        from_loc.remove_occupant(agent_id)
+        to_loc.add_occupant(agent_id)
+        return True
+
+    def place_agent(self, agent_id: str, location_id: str) -> bool:
+        """Place an agent at a location (initial placement)."""
+        loc = self.locations.get(location_id)
+        if not loc or loc.is_full:
+            return False
+        loc.add_occupant(agent_id)
+        return True
+
+    def find_agent(self, agent_id: str) -> Optional[str]:
+        """Find which location an agent is at. Returns location_id or None."""
+        for loc in self.locations.values():
+            if agent_id in loc.occupants:
+                return loc.id
+        return None
+
+    def describe_location(self, location_id: str, exclude_agent: str = "") -> str:
+        """Get a natural language description of a location and who's there."""
+        loc = self.locations.get(location_id)
+        if not loc:
+            return "Unknown location."
+        others = [a for a in loc.occupants if a != exclude_agent]
+        desc = f"{loc.name} — {loc.description}"
+        if others:
+            desc += f" Present: {', '.join(others)}."
+        else:
+            desc += " No one else is here."
+        return desc
+
+    def to_dict(self) -> dict:
+        return {
+            "name": self.name,
+            "locations": {lid: loc.to_dict() for lid, loc in self.locations.items()},
+        }
+
+    @classmethod
+    def from_yaml(cls, path: str) -> City:
+        """Load city from a YAML config file."""
+        with open(path, "r", encoding="utf-8") as f:
+            data = yaml.safe_load(f)
+
+        city = cls(name=data.get("name", "Soci City"))
+        for loc_data in data.get("locations", []):
+            location = Location(
+                id=loc_data["id"],
+                name=loc_data["name"],
+                zone=loc_data.get("zone", "public"),
+                description=loc_data.get("description", ""),
+                capacity=loc_data.get("capacity", 20),
+                connected_to=loc_data.get("connected_to", []),
+            )
+            city.add_location(location)
+        return city
+
+    @classmethod
+    def from_dict(cls, data: dict) -> City:
+        city = cls(name=data["name"])
+        for loc_data in data["locations"].values():
+            location = Location(
+                id=loc_data["id"],
+                name=loc_data["name"],
+                zone=loc_data["zone"],
+                description=loc_data["description"],
+                capacity=loc_data["capacity"],
+                connected_to=loc_data["connected_to"],
+            )
+            location.occupants = loc_data.get("occupants", [])
+            city.add_location(location)
+        return city

src/soci/world/clock.py

@@ -0,0 +1,87 @@
+"""Simulation clock — tracks in-game time with configurable tick duration."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from enum import Enum
+
+
+class TimeOfDay(Enum):
+    DAWN = "dawn"           # 5:00 - 7:59
+    MORNING = "morning"     # 8:00 - 11:59
+    AFTERNOON = "afternoon" # 12:00 - 16:59
+    EVENING = "evening"     # 17:00 - 20:59
+    NIGHT = "night"         # 21:00 - 4:59
+
+
+@dataclass
+class SimClock:
+    """Tracks simulation time. One tick = tick_minutes of in-game time."""
+
+    tick_minutes: int = 15
+    day: int = 1
+    hour: int = 6
+    minute: int = 0
+    _total_ticks: int = field(default=0, repr=False)
+
+    def tick(self) -> None:
+        """Advance time by one tick."""
+        self._total_ticks += 1
+        self.minute += self.tick_minutes
+        while self.minute >= 60:
+            self.minute -= 60
+            self.hour += 1
+        while self.hour >= 24:
+            self.hour -= 24
+            self.day += 1
+
+    @property
+    def total_ticks(self) -> int:
+        return self._total_ticks
+
+    @property
+    def time_of_day(self) -> TimeOfDay:
+        if 5 <= self.hour < 8:
+            return TimeOfDay.DAWN
+        elif 8 <= self.hour < 12:
+            return TimeOfDay.MORNING
+        elif 12 <= self.hour < 17:
+            return TimeOfDay.AFTERNOON
+        elif 17 <= self.hour < 21:
+            return TimeOfDay.EVENING
+        else:
+            return TimeOfDay.NIGHT
+
+    @property
+    def is_sleeping_hours(self) -> bool:
+        return self.hour >= 23 or self.hour < 6
+
+    @property
+    def time_str(self) -> str:
+        return f"{self.hour:02d}:{self.minute:02d}"
+
+    @property
+    def datetime_str(self) -> str:
+        return f"Day {self.day}, {self.time_str}"
+
+    def to_dict(self) -> dict:
+        return {
+            "day": self.day,
+            "hour": self.hour,
+            "minute": self.minute,
+            "tick_minutes": self.tick_minutes,
+            "total_ticks": self._total_ticks,
+            "time_of_day": self.time_of_day.value,
+            "time_str": self.time_str,
+        }
+
+    @classmethod
+    def from_dict(cls, data: dict) -> SimClock:
+        clock = cls(
+            tick_minutes=data["tick_minutes"],
+            day=data["day"],
+            hour=data["hour"],
+            minute=data["minute"],
+        )
+        clock._total_ticks = data["total_ticks"]
+        return clock

src/soci/world/events.py

@@ -0,0 +1,246 @@
+"""World events — random occurrences that inject entropy into the simulation."""
+
+from __future__ import annotations
+
+import random
+from dataclasses import dataclass, field
+from enum import Enum
+from typing import Optional
+
+
+class EventSeverity(Enum):
+    MINOR = "minor"       # Weather change, small talk topic
+    MODERATE = "moderate"  # New shop opens, street performer, local news
+    MAJOR = "major"       # Festival, power outage, celebrity visit
+    CRITICAL = "critical"  # Emergency, natural disaster, evacuation
+
+
+class WeatherState(Enum):
+    SUNNY = "sunny"
+    CLOUDY = "cloudy"
+    RAINY = "rainy"
+    STORMY = "stormy"
+    SNOWY = "snowy"
+    FOGGY = "foggy"
+
+
+@dataclass
+class WorldEvent:
+    """A single event that occurs in the simulation world."""
+
+    id: str
+    name: str
+    description: str
+    severity: EventSeverity
+    affected_locations: list[str] = field(default_factory=list)  # empty = city-wide
+    duration_ticks: int = 1  # how long it persists
+    remaining_ticks: int = 0
+
+    def is_active(self) -> bool:
+        return self.remaining_ticks > 0
+
+    def tick(self) -> None:
+        if self.remaining_ticks > 0:
+            self.remaining_ticks -= 1
+
+    def to_dict(self) -> dict:
+        return {
+            "id": self.id,
+            "name": self.name,
+            "description": self.description,
+            "severity": self.severity.value,
+            "affected_locations": self.affected_locations,
+            "duration_ticks": self.duration_ticks,
+            "remaining_ticks": self.remaining_ticks,
+        }
+
+
+# Pool of possible random events
+EVENT_TEMPLATES: list[dict] = [
+    {
+        "name": "Sudden Rain",
+        "description": "Dark clouds roll in and rain begins to pour. People rush for cover.",
+        "severity": EventSeverity.MINOR,
+        "duration_ticks": 8,
+    },
+    {
+        "name": "Street Musician",
+        "description": "A talented street musician sets up and starts playing beautiful music.",
+        "severity": EventSeverity.MINOR,
+        "duration_ticks": 4,
+        "location_zone": "public",
+    },
+    {
+        "name": "Food Truck Arrives",
+        "description": "A popular food truck parks nearby, filling the air with delicious aromas.",
+        "severity": EventSeverity.MINOR,
+        "duration_ticks": 6,
+        "location_zone": "commercial",
+    },
+    {
+        "name": "Lost Dog",
+        "description": "A friendly but lost dog is wandering around, looking for its owner.",
+        "severity": EventSeverity.MINOR,
+        "duration_ticks": 12,
+    },
+    {
+        "name": "Local Art Exhibition",
+        "description": "A pop-up art exhibition opens, showcasing works by local artists.",
+        "severity": EventSeverity.MODERATE,
+        "duration_ticks": 16,
+        "location_zone": "public",
+    },
+    {
+        "name": "Neighborhood Meeting",
+        "description": "A community meeting is called to discuss changes in the neighborhood.",
+        "severity": EventSeverity.MODERATE,
+        "duration_ticks": 4,
+    },
+    {
+        "name": "Power Flicker",
+        "description": "The power flickers briefly, causing momentary darkness and disruption.",
+        "severity": EventSeverity.MODERATE,
+        "duration_ticks": 2,
+    },
+    {
+        "name": "New Shop Grand Opening",
+        "description": "A new shop opens with fanfare, offering discounts and free samples.",
+        "severity": EventSeverity.MODERATE,
+        "duration_ticks": 8,
+        "location_zone": "commercial",
+    },
+    {
+        "name": "Summer Festival",
+        "description": "The annual summer festival begins! Music, food stalls, and games fill the park.",
+        "severity": EventSeverity.MAJOR,
+        "duration_ticks": 24,
+        "location_zone": "public",
+    },
+    {
+        "name": "Power Outage",
+        "description": "A major power outage hits the city. Businesses close early, streets go dark.",
+        "severity": EventSeverity.MAJOR,
+        "duration_ticks": 8,
+    },
+    {
+        "name": "Celebrity Sighting",
+        "description": "A famous celebrity is spotted in town, causing excitement and crowds.",
+        "severity": EventSeverity.MAJOR,
+        "duration_ticks": 4,
+    },
+    {
+        "name": "Water Main Break",
+        "description": "A water main breaks, flooding a street and disrupting traffic.",
+        "severity": EventSeverity.CRITICAL,
+        "duration_ticks": 12,
+    },
+    {
+        "name": "Severe Storm Warning",
+        "description": "Emergency alert: a severe storm is approaching. Seek shelter immediately.",
+        "severity": EventSeverity.CRITICAL,
+        "duration_ticks": 6,
+    },
+]
+
+
+class EventSystem:
+    """Manages world events, weather, and entropy injection."""
+
+    def __init__(self, event_chance_per_tick: float = 0.08) -> None:
+        self.event_chance = event_chance_per_tick
+        self.weather: WeatherState = WeatherState.SUNNY
+        self.active_events: list[WorldEvent] = []
+        self._event_counter: int = 0
+
+    def tick(self, city_location_ids: list[str]) -> list[WorldEvent]:
+        """Process one tick: expire old events, maybe spawn new ones."""
+        # Tick existing events
+        for event in self.active_events:
+            event.tick()
+        self.active_events = [e for e in self.active_events if e.is_active()]
+
+        new_events: list[WorldEvent] = []
+
+        # Maybe change weather
+        if random.random() < 0.03:
+            old = self.weather
+            self.weather = random.choice(list(WeatherState))
+            if self.weather != old:
+                evt = WorldEvent(
+                    id=f"weather_{self._event_counter}",
+                    name=f"Weather Change",
+                    description=f"The weather shifts from {old.value} to {self.weather.value}.",
+                    severity=EventSeverity.MINOR,
+                    duration_ticks=1,
+                    remaining_ticks=1,
+                )
+                self._event_counter += 1
+                new_events.append(evt)
+
+        # Maybe spawn a random event
+        if random.random() < self.event_chance:
+            template = random.choice(EVENT_TEMPLATES)
+            # Pick affected location(s)
+            affected: list[str] = []
+            if "location_zone" in template:
+                # Just pick a random location for now; the simulation can filter by zone
+                if city_location_ids:
+                    affected = [random.choice(city_location_ids)]
+            elif random.random() < 0.5 and city_location_ids:
+                affected = [random.choice(city_location_ids)]
+            # else: city-wide
+
+            evt = WorldEvent(
+                id=f"event_{self._event_counter}",
+                name=template["name"],
+                description=template["description"],
+                severity=template["severity"],
+                affected_locations=affected,
+                duration_ticks=template["duration_ticks"],
+                remaining_ticks=template["duration_ticks"],
+            )
+            self._event_counter += 1
+            self.active_events.append(evt)
+            new_events.append(evt)
+
+        return new_events
+
+    def get_events_at(self, location_id: str) -> list[WorldEvent]:
+        """Get active events affecting a specific location."""
+        return [
+            e for e in self.active_events
+            if not e.affected_locations or location_id in e.affected_locations
+        ]
+
+    def get_world_description(self) -> str:
+        """Summary of current world state for agent context."""
+        parts = [f"Weather: {self.weather.value}."]
+        for event in self.active_events:
+            parts.append(f"[{event.severity.value.upper()}] {event.name}: {event.description}")
+        return " ".join(parts)
+
+    def to_dict(self) -> dict:
+        return {
+            "weather": self.weather.value,
+            "active_events": [e.to_dict() for e in self.active_events],
+            "event_counter": self._event_counter,
+            "event_chance": self.event_chance,
+        }
+
+    @classmethod
+    def from_dict(cls, data: dict) -> EventSystem:
+        system = cls(event_chance_per_tick=data["event_chance"])
+        system.weather = WeatherState(data["weather"])
+        system._event_counter = data["event_counter"]
+        for ed in data["active_events"]:
+            evt = WorldEvent(
+                id=ed["id"],
+                name=ed["name"],
+                description=ed["description"],
+                severity=EventSeverity(ed["severity"]),
+                affected_locations=ed["affected_locations"],
+                duration_ticks=ed["duration_ticks"],
+                remaining_ticks=ed["remaining_ticks"],
+            )
+            system.active_events.append(evt)
+        return system

test_simulation.py

@@ -0,0 +1,385 @@
+"""Offline integration test — runs the full simulation loop with a mock LLM.
+
+This test validates the entire pipeline without requiring an API key.
+Run: python test_simulation.py
+"""
+
+from __future__ import annotations
+
+import asyncio
+import json
+import random
+import sys
+from pathlib import Path
+from unittest.mock import AsyncMock, MagicMock
+
+sys.path.insert(0, str(Path(__file__).parent / "src"))
+
+from soci.world.city import City
+from soci.world.clock import SimClock
+from soci.world.events import EventSystem
+from soci.agents.persona import load_personas, Persona
+from soci.agents.agent import Agent, AgentAction, AgentState
+from soci.agents.memory import MemoryStream, MemoryType
+from soci.agents.needs import NeedsState
+from soci.agents.relationships import RelationshipGraph, Relationship
+from soci.actions.registry import resolve_action, ActionType
+from soci.actions.movement import execute_move, get_best_location_for_need
+from soci.actions.activities import execute_activity
+from soci.actions.social import should_initiate_conversation, pick_conversation_partner
+from soci.engine.entropy import EntropyManager
+from soci.engine.scheduler import prioritize_agents, should_skip_llm
+from soci.engine.simulation import Simulation
+from soci.persistence.database import Database
+
+
+class MockLLM:
+    """Mock LLM that returns plausible JSON responses without calling the API."""
+
+    def __init__(self):
+        self.usage = MagicMock()
+        self.usage.total_calls = 0
+        self.usage.total_input_tokens = 0
+        self.usage.total_output_tokens = 0
+        self.usage.estimated_cost_usd = 0.0
+        self.usage.calls_by_model = {}
+        self.usage.summary.return_value = "Mock LLM: 0 calls, $0.00"
+
+    async def complete(self, system, user_message, model=None, temperature=0.7, max_tokens=1024):
+        self.usage.total_calls += 1
+        return "I'm thinking about my day."
+
+    async def complete_json(self, system, user_message, model=None, temperature=0.7, max_tokens=1024):
+        self.usage.total_calls += 1
+
+        # Detect what kind of prompt this is and return appropriate mock data
+        msg = user_message.lower()
+
+        if "plan your day" in msg:
+            return {
+                "plan": [
+                    "Wake up and have breakfast at home",
+                    "Go to work at the office",
+                    "Have lunch at the cafe",
+                    "Continue working",
+                    "Go to the park for a walk",
+                    "Have dinner",
+                    "Relax at home",
+                ],
+                "reasoning": "A balanced day with work and leisure."
+            }
+
+        if "what do you do next" in msg:
+            actions = ["work", "eat", "relax", "wander", "move", "exercise"]
+            action = random.choice(actions)
+            targets = {
+                "move": random.choice(["cafe", "park", "home_north", "office", "grocery"]),
+                "work": "",
+                "eat": "",
+                "relax": "",
+                "wander": "",
+                "exercise": "",
+            }
+            details = {
+                "move": "heading somewhere new",
+                "work": "focusing on a project",
+                "eat": "having a quick meal",
+                "relax": "taking it easy",
+                "wander": "strolling around",
+                "exercise": "doing some stretches",
+            }
+            return {
+                "action": action,
+                "target": targets.get(action, ""),
+                "detail": details.get(action, "doing something"),
+                "duration": random.randint(1, 3),
+                "reasoning": "Felt like it."
+            }
+
+        if "how important" in msg:
+            return {
+                "importance": random.randint(3, 8),
+                "reaction": "Interesting, I'll remember that."
+            }
+
+        if "reflect" in msg:
+            return {
+                "reflections": [
+                    "I notice I've been spending a lot of time at work lately.",
+                    "The neighborhood feels alive today."
+                ],
+                "mood_shift": random.uniform(-0.1, 0.2),
+                "reasoning": "Just thinking about things."
+            }
+
+        if "start a conversation" in msg or "you decide to start" in msg:
+            return {
+                "message": "Hey, how's it going?",
+                "inner_thought": "I should catch up with them.",
+                "topic": "daily life"
+            }
+
+        if "says:" in msg:
+            return {
+                "message": "Yeah, things are good. How about you?",
+                "inner_thought": "Nice to chat.",
+                "sentiment_delta": 0.05,
+                "trust_delta": 0.02
+            }
+
+        return {"status": "ok"}
+
+
+async def run_tests():
+    print("=" * 60)
+    print("SOCI — OFFLINE INTEGRATION TEST")
+    print("=" * 60)
+    errors = 0
+
+    # --- Test 1: Clock ---
+    print("\n[1/12] Clock system...")
+    clock = SimClock(tick_minutes=15, hour=6, minute=0)
+    for _ in range(96):  # Full day
+        clock.tick()
+    assert clock.day == 2, f"Expected day 2, got {clock.day}"
+    assert clock.hour == 6, f"Expected hour 6, got {clock.hour}"
+    clock_dict = clock.to_dict()
+    restored_clock = SimClock.from_dict(clock_dict)
+    assert restored_clock.day == clock.day
+    print("  PASS: Clock ticks correctly for a full day, serialization works")
+
+    # --- Test 2: City ---
+    print("\n[2/12] City system...")
+    city = City.from_yaml("config/city.yaml")
+    assert len(city.locations) == 12
+    # Test connectivity
+    cafe = city.get_location("cafe")
+    assert cafe is not None
+    assert "park" in cafe.connected_to
+    connected = city.get_connected("cafe")
+    assert len(connected) > 0
+    # Test agent placement and movement
+    city.place_agent("test_agent", "cafe")
+    assert "test_agent" in city.get_agents_at("cafe")
+    city.move_agent("test_agent", "cafe", "park")
+    assert "test_agent" not in city.get_agents_at("cafe")
+    assert "test_agent" in city.get_agents_at("park")
+    assert city.find_agent("test_agent") == "park"
+    city.locations["park"].remove_occupant("test_agent")
+    print("  PASS: City loads, connections work, movement works")
+
+    # --- Test 3: Personas ---
+    print("\n[3/12] Persona system...")
+    personas = load_personas("config/personas.yaml")
+    assert len(personas) == 20
+    # Check diversity
+    ages = [p.age for p in personas]
+    assert min(ages) <= 20, "Should have young people"
+    assert max(ages) >= 60, "Should have older people"
+    occupations = set(p.occupation for p in personas)
+    assert len(occupations) >= 15, "Should have diverse occupations"
+    # Test system prompt
+    prompt = personas[0].system_prompt()
+    assert personas[0].name in prompt
+    assert "personality" in prompt.lower() or "PERSONALITY" in prompt
+    print(f"  PASS: 20 personas loaded, ages {min(ages)}-{max(ages)}, {len(occupations)} occupations")
+
+    # --- Test 4: Needs ---
+    print("\n[4/12] Needs system...")
+    needs = NeedsState()
+    initial_hunger = needs.hunger
+    for _ in range(20):
+        needs.tick()
+    assert needs.hunger < initial_hunger, "Hunger should decay"
+    assert needs.energy < 1.0, "Energy should decay"
+    needs.satisfy("hunger", 0.5)
+    assert needs.hunger > 0.0, "Hunger should be partially satisfied"
+    urgent = needs.urgent_needs
+    desc = needs.describe()
+    assert isinstance(desc, str)
+    print(f"  PASS: Needs decay ({desc}), satisfaction works")
+
+    # --- Test 5: Memory ---
+    print("\n[5/12] Memory system...")
+    mem = MemoryStream()
+    for i in range(30):
+        mem.add(i, 1, f"{6+i//4:02d}:{(i%4)*15:02d}",
+                MemoryType.OBSERVATION, f"Event {i}", importance=random.randint(1, 10))
+    assert len(mem.memories) == 30
+    retrieved = mem.retrieve(30, top_k=5)
+    assert len(retrieved) == 5
+    recent = mem.get_recent(3)
+    assert len(recent) == 3
+    assert recent[-1].content == "Event 29"
+    # Test reflection trigger
+    mem._importance_accumulator = 100
+    assert mem.should_reflect()
+    mem.reset_reflection_accumulator()
+    assert not mem.should_reflect()
+    # Test serialization
+    mem_dict = mem.to_dict()
+    restored_mem = MemoryStream.from_dict(mem_dict)
+    assert len(restored_mem.memories) == 30
+    print("  PASS: Memory storage, retrieval, reflection trigger, serialization")
+
+    # --- Test 6: Relationships ---
+    print("\n[6/12] Relationship system...")
+    graph = RelationshipGraph()
+    rel = graph.get_or_create("elena", "Elena Vasquez")
+    assert rel.familiarity == 0.0
+    rel.update_after_interaction(tick=10, sentiment_delta=0.1, trust_delta=0.05, note="Had coffee together")
+    assert rel.familiarity > 0.0
+    assert rel.sentiment > 0.5
+    assert len(rel.notes) == 1
+    closest = graph.get_closest(5)
+    assert len(closest) == 1
+    desc = rel.describe()
+    assert "Elena" in desc
+    # Serialization
+    g_dict = graph.to_dict()
+    restored_g = RelationshipGraph.from_dict(g_dict)
+    assert restored_g.get("elena") is not None
+    print("  PASS: Relationships form, track sentiment/trust, serialize")
+
+    # --- Test 7: Agent ---
+    print("\n[7/12] Agent system...")
+    persona = personas[0]  # Elena
+    agent = Agent(persona)
+    assert agent.name == "Elena Vasquez"
+    assert agent.location == "home_north"
+    assert agent.state == AgentState.IDLE
+    # Test action
+    action = AgentAction(type="work", detail="coding", duration_ticks=3, needs_satisfied={"purpose": 0.3})
+    agent.start_action(action)
+    assert agent.is_busy
+    assert agent.state == AgentState.WORKING
+    for _ in range(3):
+        agent.tick_action()
+    assert not agent.is_busy
+    assert agent.state == AgentState.IDLE
+    # Test mood + needs interaction
+    for _ in range(10):
+        agent.tick_needs()
+    # Test observation
+    agent.add_observation(0, 1, "06:00", "Saw a cat in the park", importance=4)
+    assert len(agent.memory.memories) == 1
+    # Serialization
+    a_dict = agent.to_dict()
+    restored_a = Agent.from_dict(a_dict)
+    assert restored_a.name == agent.name
+    assert len(restored_a.memory.memories) == 1
+    print("  PASS: Agent actions, needs, mood, memory, serialization")
+
+    # --- Test 8: Action resolution ---
+    print("\n[8/12] Action resolution...")
+    city2 = City.from_yaml("config/city.yaml")
+    agent2 = Agent(personas[0])
+    city2.place_agent(agent2.id, agent2.location)
+    raw = {"action": "move", "target": "cafe", "detail": "heading to cafe", "duration": 1}
+    resolved = resolve_action(raw, agent2, city2)
+    assert resolved.type == "move"
+    assert resolved.target == "cafe"
+    # Invalid action falls back to wander
+    raw_bad = {"action": "fly", "target": "moon"}
+    resolved_bad = resolve_action(raw_bad, agent2, city2)
+    assert resolved_bad.type == "wander"
+    print("  PASS: Valid actions resolve, invalid actions fall back to wander")
+
+    # --- Test 9: Movement ---
+    print("\n[9/12] Movement system...")
+    clock2 = SimClock()
+    agent3 = Agent(personas[0])
+    city3 = City.from_yaml("config/city.yaml")
+    city3.place_agent(agent3.id, "home_north")
+    move_action = AgentAction(type="move", target="cafe", detail="walking to cafe")
+    desc = execute_move(agent3, move_action, city3, clock2)
+    assert "cafe" in desc.lower() or "Daily Grind" in desc
+    assert agent3.location == "cafe"
+    # Test location suggestion
+    suggested = get_best_location_for_need(agent3, "hunger", city3)
+    assert suggested is not None
+    print(f"  PASS: Movement works, need-based suggestion: {suggested}")
+
+    # --- Test 10: Events & Entropy ---
+    print("\n[10/12] Events and entropy...")
+    events = EventSystem(event_chance_per_tick=1.0)  # Force events
+    new = events.tick(["cafe", "park", "office"])
+    assert len(events.active_events) > 0 or len(new) > 0
+    world_desc = events.get_world_description()
+    assert "Weather" in world_desc
+    entropy = EntropyManager()
+    agents_list = [Agent(p) for p in personas[:5]]
+    # Simulate repetitive behavior
+    entropy._action_history["elena"] = ["work"] * 15
+    assert entropy._is_stuck_in_loop("elena")
+    conflicts = entropy.get_conflict_catalysts(agents_list)
+    print(f"  PASS: Events fire, entropy detects loops, {len(conflicts)} potential conflicts found")
+
+    # --- Test 11: Full simulation loop (mock LLM) ---
+    print("\n[11/12] Full simulation loop (mock LLM)...")
+    mock_llm = MockLLM()
+    city4 = City.from_yaml("config/city.yaml")
+    clock4 = SimClock(tick_minutes=15, hour=6, minute=0)
+    sim = Simulation(city=city4, clock=clock4, llm=mock_llm)
+    sim.load_agents_from_yaml("config/personas.yaml")
+
+    # Limit to 5 agents for speed
+    agent_ids = list(sim.agents.keys())[:5]
+    sim.agents = {aid: sim.agents[aid] for aid in agent_ids}
+
+    events_collected = []
+    sim.on_event = lambda msg: events_collected.append(msg)
+
+    # Run 10 ticks
+    for _ in range(10):
+        await sim.tick()
+
+    assert sim.clock.total_ticks == 10
+    assert len(events_collected) > 0
+    print(f"  PASS: 10 ticks completed, {len(events_collected)} events, "
+          f"{mock_llm.usage.total_calls} LLM calls")
+
+    # Check agents moved, have memories, etc.
+    for aid, agent in sim.agents.items():
+        assert len(agent.memory.memories) > 0, f"{agent.name} should have memories"
+
+    # --- Test 12: State serialization roundtrip ---
+    print("\n[12/12] Full state serialization...")
+    state = sim.to_dict()
+    state_json = json.dumps(state)
+    assert len(state_json) > 1000, "State should be substantial"
+    restored_state = json.loads(state_json)
+    sim2 = Simulation.from_dict(restored_state, mock_llm)
+    assert len(sim2.agents) == len(sim.agents)
+    assert sim2.clock.total_ticks == sim.clock.total_ticks
+    for aid in sim.agents:
+        assert aid in sim2.agents
+        assert sim2.agents[aid].name == sim.agents[aid].name
+    print(f"  PASS: Full state serialized ({len(state_json):,} bytes) and restored")
+
+    # --- Summary ---
+    print("\n" + "=" * 60)
+    if errors == 0:
+        print("ALL 12 TESTS PASSED")
+    else:
+        print(f"{errors} TEST(S) FAILED")
+    print("=" * 60)
+
+    # Print some interesting stats
+    print(f"\nSimulation state:")
+    print(f"  Clock: {sim.clock.datetime_str}")
+    print(f"  Weather: {sim.events.weather.value}")
+    print(f"  Mock LLM calls: {mock_llm.usage.total_calls}")
+    print(f"\nAgent status after 10 ticks:")
+    for aid, agent in sim.agents.items():
+        loc = sim.city.get_location(agent.location)
+        loc_name = loc.name if loc else agent.location
+        print(f"  {agent.name}: {agent.state.value} at {loc_name} "
+              f"(mood={agent.mood:.2f}, memories={len(agent.memory.memories)})")
+
+    return errors == 0
+
+
+if __name__ == "__main__":
+    success = asyncio.run(run_tests())
+    sys.exit(0 if success else 1)