Luvoire

LLM-based multi-agent social simulation engine for games, public safety research, and academic simulation.

Current version

0.3.0

Luvoire Bench

Luvoire Bench publishes a seven-axis public leaderboard for long-term memory, multi-layer retention, theory-of-mind, hierarchical planning, and real-time latency. See the live page at https://celovin.github.io/luvoire/bench/ or start from the submission template.

Datasets

Luvoire supports seven CC-BY-4.0 NVIDIA Nemotron-Personas countries through luvoire.personas: USA, Japan, India, Brazil, Singapore, France, and Korea. The Luvoire Persona Interface v1 (LPI v1) maps each country into a common 18-field dataclass while preserving country-specific fields in extras; install with pip install -e ".[personas]" and inspect with python -m luvoire.cli personas list.

Languages

English	한국어	日本語	简体中文	繁體中文	Deutsch	Français	Español
English	한국어	日本語	简体中文	繁體中文	Deutsch	Français	Español

Luvoire is an early MVP for modeling persistent agents with memory, relationships, emotions, environment context, and LLM-backed decisions. The same runtime can support narrative NPCs, fictional public-safety replay research, and reproducible agent-based social simulation.

All public-safety examples in this repository are fictional, synthetic, and non-identifying. They are replay and research demos, not crime prediction or suspect scoring tools.

Applications

Domain	Use	Current MVP Surface
Games	Persistent-memory NPCs and dynamic dialogue	Godot adapter scaffold and NPC notebook
Public safety research	Fictional scenario replay for prevention research	Synthetic replay notebook with milestone coverage
Academic research	Reproducible LLM-based agent simulation	Python package, notebooks, Streamlit dashboard

Core Features

• Personas with Big Five personality traits, values, goals, and prompt rendering
• Short-term memory buffers and SQLite + FAISS long-term retrieval with semantic-temporal reranking
• Relationship graph with directed trust, familiarity, and interaction weight
• Environment context for time, location, conditions, and recent events
• PAD emotion state: valence, arousal, dominance
• Opt-in hierarchical planning for multi-step agent goals
• Opt-in social learning for observational imitation and skill propagation
• Optional distributed 1000-agent execution envelope with Ray-compatible fallback
• City-scale 1K benchmark, offline msgpack replay viewer, and pedagogical archetype overlays
• Optional Nemotron-Personas-Korea seeding for the local 10K Gangnam replay
• LLM gateway with Anthropic, OpenAI, and deterministic local clients
• Prompt templates for English, Korean, Japanese, and Chinese runs
• Simulation runner with scheduled events and JSONL export
• luvoire run CLI for YAML-driven local simulations
• Scenario DSL v1 for validated YAML scenarios and ethics guardrails
• Opt-in red-team content filter and append-only safety audit log helpers
• Jupyter notebooks for MVP demo tracks and a 10-agent village scale-up
• 50-agent deterministic village experiment with committed metrics, trace sample, and PDF report
• Gradio Playground for no-key replay demos and user-supplied LLM API keys
• Opt-in OpenAI TTS voice playback for Playground timeline speak actions with per-agent voices and cache-backed WAV fallback
• Deterministic benchmark scripts with JSON, Markdown, SVG figures, and PDF reports
• Cross-framework comparison benchmark against AutoGen, CrewAI, LangGraph, Mesa, and NetLogo
• Human evaluation framework with survey templates, a static review UI, and reliability metrics
• Cloud deployment templates for AWS, GCP, and Azure production planning
• Godot 4 adapter scaffold
• Unity 2022 LTS adapter scaffold for Package Manager Git installs
• Unity SDK (preview) with FastAPI tick/memory/action contract and UPM package layout
• Game SDK facades for Python, TypeScript, and GDScript NPC integrations
• Mobile SDK scaffolds for iOS Swift Package Manager and Android Kotlin clients
• Browser-side static runtime for no-server 2-agent, 5-agent, and Sally-Anne demos
• Interactive 5-chapter tutorial website with embedded code editing and progress tracking
• VS Code Scenario DSL extension scaffold with syntax highlighting and validation
• Streamlit dashboard for inspecting simulation logs with playback and live-tail controls
• Research SaaS dashboard scaffold for experiment comparison, memory inspection, cost budget, and citation export

Install

pip install -e ".[dev]"

Dashboard dependencies are optional:

pip install -e ".[dashboard]"

Minimal Simulation

from datetime import datetime

from luvoire import Environment, LocalClient, Persona, Personality, Simulator

alice = Persona(
    agent_id="alice",
    name="Alice",
    age=17,
    background="Introverted literature student in a dormitory.",
    personality=Personality(
        openness=0.8,
        conscientiousness=0.6,
        extraversion=0.2,
        agreeableness=0.7,
        neuroticism=0.4,
    ),
    values=["privacy", "honesty"],
    goals=["finish a short story"],
)

bob = Persona(
    agent_id="bob",
    name="Bob",
    age=17,
    background="Extroverted science student in the same dormitory.",
    personality=Personality(
        openness=0.6,
        conscientiousness=0.8,
        extraversion=0.9,
        agreeableness=0.7,
        neuroticism=0.3,
    ),
    values=["curiosity", "teamwork"],
    goals=["prepare for a physics contest"],
)

environment = Environment(
    start_time=datetime(2026, 3, 2, 9, 0),
    location_path=("Korea", "Seoul", "High School Dormitory", "Room 201"),
)

sim = Simulator(
    agents=[alice, bob],
    environment=environment,
    tick_duration_minutes=30,
    llm=LocalClient(
        lambda messages: '{"action_type": "speak", "target": null, "content": "observes the room."}'
    ),
)

logs = sim.run(duration_days=1)
sim.export_logs("runs/dorm_001.jsonl")

Examples

• Two-Agent Dormitory: two students sharing a dorm room over seven simulated days
• Fictional Crime Scenario Replay: synthetic replay workflow with milestone coverage
• Game NPC Persistent Memory Demo: NPC memory retrieval and Godot-style payload
• Ten-Agent Village Simulation: deterministic 10-person village run with relationship and JSONL checks
• Ollama Local LLM Fallback: local-first gateway example with deterministic fallback
• Live Ollama Five-Agent Demo: seeded llama3.1:8b notebook run with a 30-second live cap

Run notebooks top-to-bottom after installing .[dev].

Playground

Try the browser demo at Luvoire Playground.

The Playground includes three prebuilt scenarios, a deterministic replay-only mode that needs no API key, optional OpenAI or Anthropic runs with a user-supplied per-session API key, a timeline view, an interactive relationship graph, and JSONL log download.

Quick start demos:

• Office team conflict: the default first-run demo with visible tension, negotiation, and relationship updates after one click.
• Dorm: two agents: the fastest compact demo for a two-person interaction loop.
• Village: ten agents: the best stress case for dense relationship graph movement.

Local run:

pip install -r playground/requirements.txt
python playground/app.py

Space deploy helper:

python scripts/deploy_playground_space.py

Operations panel

A separate operator-facing Gradio app surfaces the commercial / billing surface of a running deployment: live tiktoken counter (precise token billing), tenant-registry encryption-at-rest status, rate-limit health (in-memory or Redis-backed), and the inbound Stripe webhook inbox. Runs on 127.0.0.1:7861 by default with share=False enforced — this is an admin surface, never a public URL.

python -m playground.ops_app

When invoked in the same process as the API server it observes the live app.state rate-limiter and Stripe webhook handler. Run standalone to inspect the file-backed TenantRegistry. See playground/ops_panel.py for state- sharing trade-offs and the per-panel empty-state copy.

Website

cd website
npm install
npm run build
npm run dev

The website is a Next.js app for the public project surface: application tracks, SDK entry points, research reports, and launch links.

The scenario editor is available at /editor and supports drag-and-drop agents, timeline edits, live YAML preview, and Scenario DSL export.

API Server

pip install -e ".[api]"
uvicorn luvoire.api.server:app --host 127.0.0.1 --port 8000

The API server provides REST routes for simulation lifecycle management, agent inspection, event injection, and a WebSocket log stream for live tick delivery.

API references:

• REST Reference
• WebSocket Guide
• Example Notebook

Docker Compose example:

docker compose -f deploy/docker/docker-compose.yml --env-file deploy/docker/.env.example up -d
curl http://localhost:8000/healthz

Documentation Site

pip install -e ".[docs]"
mkdocs build
mkdocs serve

The MkDocs site organizes getting-started guides, API reference pages, game and research workflows, CLI reference, and community docs. Start at docs/index.md.

Dashboard

pip install -e ".[dashboard]"
streamlit run dashboard/app.py

Open http://localhost:8501, then load a JSONL file produced by Simulator.export_logs(...) or use the bundled sample.

Research SaaS

pip install -r saas/requirements.txt
streamlit run saas/app.py

The research dashboard includes six pages for simulation runs, A/B comparison, memory inspection, relationship exploration, cost budgeting, and citation export.

Benchmarks

python benchmarks/run_benchmark.py --json-output runs/benchmark.json --markdown-output runs/benchmark.md

The benchmark report records measured Luvoire throughput and transparent not-measured comparison slots for Concordia and Mesa. See benchmarks/README.md for comparison discipline.

Phase 19 scale experiment:

python experiments/50_agent_village/run.py

Classic reproductions:

python experiments/schelling_segregation/run.py
python experiments/axelrod_prisoners_dilemma/run.py

See 50-Agent Village Experiment and 50-Agent Benchmark Report.

Formal report bundle:

python benchmarks/formal_report/runner.py

See Formal Benchmark Report and Formal Report PDF.

Phase 46 scoring bundle:

python benchmarks/scoring/runner.py

See Scoring Benchmarks.

Reproducibility Guarantees

Luvoire deterministic local runs can be replayed from fixed config, seed, and JSONL artifacts. The Phase 21 test suite covers repeated same-seed runs, seed propagation, YAML config round-trip, and JSONL replay summaries.

See Reproducibility Report.

Memory Retrieval

SQLiteFaissMemoryStore.retrieve(...) keeps the simple list-of-memory API. Use retrieve_with_scores(...) when you need semantic score, temporal score, importance score, and final reranking score for analysis:

from luvoire import RetrievalWeights

results = store.retrieve_with_scores(
    "shared study routine",
    k=5,
    weights=RetrievalWeights(semantic=0.65, temporal=0.30, importance=0.05),
)

CLI

luvoire run examples/cli_dorm.yaml --json
luvoire score experiments/50_agent_village/results/sim_log.jsonl

luvoire score emits JSON summaries for Persona Consistency Score (PCS) and Relationship Coherence Score (RCS) from a committed JSONL log.

See CLI for the YAML config shape, output path rules, dry-run validation, and scoring mode.

Scenario DSL

from luvoire.dsl import load_scenario

scenario = load_scenario("examples/scenarios/01_shopkeeper_winter_crime.yaml")
logs = scenario.to_simulator().run(duration_days=scenario.duration_days)

See DSL Tutorial, DSL Reference, and Scenario JSON Schema.

The Phase 48 marketplace library includes 50 fictional Scenario DSL examples across school, workplace, family, community, and social-experiment categories:

luvoire validate scenarios/library --json

See Scenario Library.

Game SDK

Luvoire includes deterministic NPC SDK facades for installed Python packages, TypeScript tooling, and direct Godot GDScript prototypes.

from luvoire.game import GameSession

session = GameSession(game_id="demo-village")
npc = session.create_npc(
    persona_file="sdk/python/examples/personas/shopkeeper.yaml",
    initial_relationships={"player": "neighbor"},
)
response = npc.interact("asks about the lantern market", context={"location": "Harbor Village"})
print(response.text)

Run the Python example after installing the package in editable mode:

python sdk/python/examples/basic_npc.py

SDK references:

• Python Game SDK
• TypeScript Game SDK
• Godot GDScript Game SDK
• Unity SDK (preview)
• Game SDK Integration Patterns

Godot Integration

See adapters/godot/README.md for the Godot 4 scaffold, HTTP/local fallback client, and demo scene structure.

Open the actual Godot project with:

godot4 --path adapters/godot

After adding a Web export preset in the Godot editor, create a real web export with:

godot4 --headless --path adapters/godot --export-release Web build/godot-tavern/index.html

Unity Integration

Install the Unity adapter with Package Manager:

https://github.com/Celovin/luvoire.git?path=adapters/unity

See adapters/unity/README.md for the Unity 2022.3 LTS package scaffold, HTTP/local fallback client, NPCAgent component, and Basic NPC sample.

The new preview Unity SDK package lives under unity-sdk and targets the FastAPI /simulate/tick, /agent/{id}/memory, and /agent/{id}/action contract.

Open the host Unity project with:

"C:\Program Files\Unity\Hub\Editor\2022.3.xx\Editor\Unity.exe" -projectPath <your-project>

For a real WebGL build, add a small Editor build method in the host project and call it with:

"C:\Program Files\Unity\Hub\Editor\2022.3.xx\Editor\Unity.exe" -batchmode -projectPath <your-project> -executeMethod TavernDemoBuild.BuildWebGL -quit -logFile Logs\unity-webgl-build.log

Unreal Integration

Copy adapters/unreal into either your project Plugins folder or the UE 5.3 engine Marketplace plugins folder, then enable the Luvoire Unreal plugin in the editor.

See adapters/unreal/README.md for the UE5 source plugin scaffold, REST API client, NPCAgentComponent, and BP_BasicNPC placeholder flow.

Architecture

flowchart TD
    Persona --> DecisionEngine
    ShortTermMemory --> DecisionEngine
    LongTermMemory --> DecisionEngine
    RelationshipGraph --> DecisionEngine
    Environment --> DecisionEngine
    EmotionState --> DecisionEngine
    DecisionEngine --> LLMGateway
    LLMGateway --> Anthropic
    LLMGateway --> OpenAI
    LLMGateway --> LocalClient
    DecisionEngine --> Action
    Action --> Simulator
    Simulator --> JSONL
    JSONL --> Dashboard
    Action --> GodotAdapter

Loading

Detailed notes:

• Architecture
• Research Positioning
• Competitor Matrix
• 50-Agent Village Experiment
• 50-Agent Benchmark Report
• Formal Benchmark Report
• Formal Report PDF
• Reproducibility Report
• DSL Tutorial
• DSL Reference
• KNOT Episode 1 Integration Case Study
• Korean University Pilot Case Study
• Indie Studio Adoption Case Study
• Scenario Marketplace Beta
• Python Game SDK
• TypeScript Game SDK
• Godot GDScript Game SDK
• Game SDK Integration Patterns
• Research SaaS App
• Security Policy and Phase 34 Security Audit
• Privacy
• CLI
• Prompt Templates
• Local vs Cloud LLM Fallback Notes
• Tutorial Blog Draft
• Korean Technical Blog Drafts
• Discord Community Launch Kit
• Demo Video Scripts
• YouTube Tutorial Scripts
• Hugging Face Playground Guide
• Website App
• Technical Report Draft and PDF Preview
• arXiv v2 Preprint Source, Appendix, and 80+ References
• Papers with Code Submission Packet and machine-readable packet
• Academic Indexing Packet, Citation Metadata, and Zenodo Metadata

Roadmap

Version	Target	Milestones
v0.1	2026 Q2	Core MVP, notebooks, Godot scaffold, dashboard
v0.5	2027 Q2	Domain adapters, hosted dashboard, research pilots
v1.0	2027 Q4	Production SDK, commercial game integration, SaaS release

Development

pytest
ruff check .
mypy src

See CONTRIBUTING.md.

Release Prep

Local package and Docker release checks are documented in RELEASE.md. CI and release automation are documented in CI and Release Automation. The repository includes Release Please version PRs and a tag-triggered GitHub Release workflow with PyPI Trusted Publishing gated by the pypi environment. Use python scripts/external_activation_status.py before external activation steps to confirm release and deployment blockers plus suggested next actions in one JSON snapshot, python scripts/deploy_playground_space.py once Hugging Face auth is ready, or python scripts/pre_release_check.py --version 0.3.0 to combine activation status with a local release dry run.

License

MIT License. Copyright (c) 2026 Celovin.

Civilian Use Policy

Luvoire is for civilian research and commercial multi-agent simulation. The public policy declines defense, predictive policing, PSYOP/influence optimization, non-consenting real-person twinning, and minors-in-synthetic-pipelines use categories regardless of payment; see POLICIES/civilian_use.md.