The simulator for conversations.
conversationsimulator.com · Documentation · Download
Practice interviews, negotiations, language, and difficult social situations with AI NPCs — running 100% on your computer, no account, no cloud, no telemetry.
Scenario: The Executive Gauntlet · Job Interview Basics pack
You: "I led the data platform redesign — cut nightly processing from 4 hours to 40 minutes."
NPC: "That's a headline number. Walk me through the specific trade-off you made
to get there. What did you give up, and was it the right call in hindsight?"
State: credibility +12 · pressure_level +1 · composure 65
Every AI conversation coach on the market — interview prep, sales roleplay, speaking coaches, VR soft-skills training — runs in the cloud. But the conversations people most need to rehearse (firing someone, the salary ask, the breakup, the visa interview) are exactly the ones they least want on somebody else's server. Conversation Simulator is the missing intersection: a structured practice game (live scenario state, events, scoring, debrief) with 100% local inference (no account, no cloud, no telemetry), in the open (Apache-2.0) — heir to a sixty-year lineage that runs from ELIZA through Monkey Island's insult sword-fighting to Façade, finally buildable because local LLMs dissolved the authoring wall those earlier systems hit.
The full analysis — lineage, competitive field, and the business-model precedents from Dwarf Fortress to Shattered Pixel Dungeon: docs/landscape.md
| Screen | What you see |
|---|---|
 |
Home — all services ready |
 |
Scenario Library — browse and filter packs |
 |
Conversation — live state meters and events |
 |
Debrief — score, strengths, turning points |
 |
Creator Workbench — YAML scenario editor |
 |
Model Manager — install and manage local models |
Screenshots are SVG placeholders matching the current UI. They will be replaced with real recordings at Milestone 1 launch. See docs/screenshots.md for the replacement checklist and alt-text for each image.
git clone https://github.com/outrightmental/ConversationSimulator
cd ConversationSimulator
./scripts/setup.sh # check env, install packages, create ~/.convsim/
./scripts/dev.sh # start all servicesThen open http://127.0.0.1:7354 in your browser.
Windows: use scripts\setup.ps1 and scripts\dev.ps1 instead.
On first launch you will be prompted to download a local model. The recommended starter is Qwen3 4B Instruct Q4_K_M (~2.5 GB, Apache-2.0). No model is bundled — you decide what to install and when.
Full install guide: docs/install.md · Troubleshooting: docs/troubleshooting.md
- Complete the quickstart above.
- In the browser, pick Job Interview Basics → The Executive Gauntlet.
- Read the player brief, then start typing.
- When the conversation ends, open the debrief — scores, turning points, and coaching notes are all generated locally.
- Adjust difficulty or edit the scenario YAML and run it again.
| Pack | Scenarios |
|---|---|
| Job Interview Basics | Behavioral, hostile executive, blue-collar trade, stretch role |
| Everyday Negotiation | Used car, apartment lease, freelance scope, customer service refund |
| Language Café | Spanish coffee shop, French hotel check-in, Japanese convenience store, English small talk |
| Difficult Conversations | Coworker feedback, missed-deadline apology, boundary with a friend, ask for a raise |
All official packs are CC BY 4.0. Fork them, remix them, or create your own from scratch.
A pack is a folder of YAML files — no code, no build step, no compilation.
packs/
my-pack/
manifest.yaml # pack id, title, author, content rating
scenarios/
my_scenario.yaml # opening line, goals, state variables, events
npcs/
my_npc.yaml # persona, tone, backstory, goals
rubrics/
my_rubric.yaml # scoring dimensions and weights for the debrief
safety/
my_policy.yaml # content categories and per-category actions
scenes/
my_scene.yaml # visual and atmospheric context
The fastest way to build a pack is the Creator Workbench (in the app
navigation). Copy an official pack, edit the YAML files, validate with one
click, quick-test in the browser, and export a shareable .zip — all
without leaving the browser.
New to pack authoring? packs/sample/hello-conversation/ is a
minimal one-scenario sample pack (CC0-1.0, public domain) with every
required file type and inline comments explaining each field. Copy it into
packs/local-dev/ and start editing — or import its zip in the Creator
Workbench.
Minimal scenarios/my_scenario.yaml:
schema_version: "0.1"
scenario_id: my_scenario
title: My First Scenario
summary: A one-line description of the situation the player faces.
player_role:
label: Your Role
brief: What the player is trying to accomplish in this conversation.
npc:
ref: ../npcs/my_npc.yaml
rubric:
ref: ../rubrics/my_rubric.yaml
duration:
max_turns: 12
opening:
npc_says: "Let's begin."
goals:
player_visible:
- "Reach a clear agreement without giving up your core need"
state:
variables:
rapport:
min: 0
max: 100
default: 50
visibility: visible
max_delta_per_turn: 15Add events, endings, difficulty modifiers, and extra rubric dimensions as you go.
The JSON Schema in schemas/ validates everything at import time.
Sample pack: packs/sample/hello-conversation/ · Creator workbench tutorial: docs/scenario-authoring.md · Pack validation: docs/pack-validation.md · Official quality bar: docs/official-pack-quality-bar.md
Conversation Simulator does not send your conversations, audio, prompts, transcripts, or model outputs to any server during play.
| What | Where it runs |
|---|---|
| LLM inference | Local model via llama.cpp — stays on your machine |
| Speech-to-text | whisper.cpp — local, no audio uploads |
| Text-to-speech | Kokoro / sherpa-onnx — local, TTS audio cached on disk |
| Transcripts | SQLite at ~/.convsim/db/ — never uploaded |
| Telemetry | None — telemetry_enabled defaults off and the MVP ships no telemetry subsystem |
| Model downloads | Only when you explicitly request them; license shown before every download |
All services bind to 127.0.0.1. Nothing is reachable from other machines by default.
Verify the offline guarantee at any time:
npx convsim offline-smoke-test packs/official/job-interview-basicThe command runs a scripted conversation with a fake runtime and confirms no outbound TCP connection was made. It exits nonzero with an actionable error if any subsystem attempts to reach an external host.
Full data policy: docs/privacy.md · Network security: docs/network-security.md
Five services, all on localhost. The browser never talks to the internet.
┌──────────────────────────────────────────────────────────────┐
│ Your machine │
│ │
│ Browser (React / Vite) │
│ convsim-ui :7354 │
│ │ HTTP REST + WebSocket (localhost only) │
│ ▼ │
│ convsim-core :7355 (Python / FastAPI) │
│ │ SQLite ~/.convsim/db/ │
│ ┌───┼──────────┐ │
│ ▼ ▼ ▼ │
│ :7356 :7357 :7358 │
│ LLM STT TTS │
│ llama whisper Kokoro / sherpa-onnx │
└──────────────────────────────────────────────────────────────┘
| Service | Port | Responsibility |
|---|---|---|
| convsim-ui | 7354 | Browser UI (Vite dev server) |
| convsim-core | 7355 | Scenario engine, REST API, WebSocket |
| convsim-llm | 7356 | Local LLM (llama-server) |
| convsim-stt | 7357 | Speech-to-text (whisper.cpp) |
| convsim-tts | 7358 | Text-to-speech (Kokoro / sherpa-onnx) |
Architecture deep-dive: docs/architecture.md · Runtime adapters: docs/runtime-adapters.md
No model is bundled. The app shows license information and size before each download.
| Model | Size | VRAM | License | Role |
|---|---|---|---|---|
| Qwen3 4B Instruct Q4_K_M | 2.5 GB | 4 GB+ | Apache-2.0 | Starter (lower-spec machines) |
| Qwen3 8B Instruct Q4_K_M | 5.0 GB | 6 GB+ | Apache-2.0 | Standard (recommended for most) |
| Qwen3 14B Instruct Q4_K_M | 9.0 GB | 10 GB+ | Apache-2.0 | High quality |
| Mistral Small 3.1 24B Q4_K_M | 14.3 GB | 16 GB+ | Apache-2.0 | High quality, long context |
You can also load any llama.cpp-compatible GGUF file from your own filesystem.
The full model registry with checksums is in model-registry/registry.yaml.
Local models guide: docs/local-models.md
Every session runs through a layered safety system before and after the model is called.
- Two categories are global and cannot be disabled by any pack: content involving minors in a romantic or sexual context always stops the session; self-harm crisis language always stops the session and surfaces real crisis resources.
- Input is checked deterministically before the NPC runtime is invoked.
- Packs are declarative YAML only — no executable code. The validator blocks scripts, binary files, symlink attacks, and prompt-injection patterns at import time.
- Community packs can tighten safety rules for their scenario; they cannot weaken the global non-overridable rules.
- Content cap: the platform supports G, PG, and PG-13 ratings. Nothing above PG-13 is permitted in any pack.
Full safety policy: docs/safety-policy.md
| Milestone | Goal | Status |
|---|---|---|
| 0 | Monorepo skeleton, dev setup, official scenario packs | Complete |
| 1 | Text-only local simulator (browser UI + Python backend + local LLM) | In progress |
| 2 | Scenario pack system (import, validate, browse community packs) | Planned |
| 3 | Local voice input (Whisper speech-to-text) | Planned |
| 4 | Local voice output (TTS with Kokoro / sherpa-onnx) | Planned |
| 5 | Polished playable alpha | Planned |
ROADMAP.md — MVP acceptance criteria, build order, what is deliberately out of scope, and links to the acceptance criteria and docs.
Delivery board — every issue ever shipped, in phases · GitHub Milestones · Full specification · Post-alpha issues
Conversation Simulator is free and open source, and fairly priced:
- GitHub — free. Clone this repository, build it with the quickstart above, and run it at no cost. The engine is Apache-2.0 and the four official packs are CC BY 4.0.
- Steam — $9.99. The Steam edition is the same software, packaged: signed, notarized, auto-updating, Steam Deck–verified. The price funds continued development; it does not unlock anything the source build lacks. The Steam edition makes the same local-first guarantee as the open-source build.
- Premium scenario-pack DLC — Steam only. First-party expansion packs beyond the four free official ones are developed in a separate private repository and sold as paid Steam DLC. Their content is never in this public repository. See docs/DLC_MODEL.md for the private-repo → Steam-DLC contract. The open core never shrinks: nothing that ships free is relocked as DLC.
This free-on-GitHub, fairly-priced-on-Steam pattern has a strong track record — Dwarf Fortress, Shattered Pixel Dungeon, Mindustry, Aseprite — and the reasoning behind it is laid out in docs/landscape.md.
The Steam release documents:
| Document | Purpose |
|---|---|
| docs/STEAM_ROADMAP.md | Release principles and release train (Stages 1–5) |
| publishing/STEAM_STORE_AND_OPERATIONS.md | Store page operations, launch runbook, support triage |
| publishing/STEAM_PUBLISHING_AND_DEPLOYMENT.md | SteamPipe concepts, CI deploy, manual upload, branch promotion, troubleshooting |
| docs/STEAM_INTEGRATION.md | Steam API bridge, Steam Cloud exclusions, achievements, stats, rich presence |
| publishing/MACOS_SIGNING_AND_NOTARIZATION.md | macOS Apple Developer ID signing and notarisation |
| publishing/WINDOWS_CODE_SIGNING.md | Windows Authenticode signing |
Running a pre-release build? Use Support → Report a problem in the app to assemble a redacted diagnostics bundle and open a pre-filled GitHub issue — all in under a minute, nothing uploaded automatically.
docs/beta-testing.md — how to join, where to report, what a good report looks like
All contributions are welcome — new scenario packs, bug fixes, documentation improvements, or new runtime adapters. Scenario packs are the friendliest entry point — you can ship one without touching engine code.
Start here:
good first issue ·
help wanted ·
Delivery board ·
How the project is run
CONTRIBUTING.md · CODE_OF_CONDUCT.md · SECURITY.md · RELEASE_NOTES.md
apps/
web/ React / TypeScript browser UI
desktop/ Tauri desktop wrapper (future milestone)
packages/
ui/ Shared UI component library
scenario-schema/ TypeScript types for scenario packs
shared-types/ Shared TypeScript types across apps and services
services/
convsim-core/ Python / FastAPI — scenario engine, REST API, WebSocket
runtimes/
llama_cpp/ llama.cpp integration and binary management
whisper_cpp/ whisper.cpp speech-to-text integration
packs/
official/ First-party scenario packs (CC BY 4.0)
job-interview-basic/
everyday-negotiation/
language-cafe/
difficult-conversations/
schemas/ JSON Schema definitions for packs, scenarios, NPCs, rubrics
model-registry/ Curated registry of supported local models with checksums
docs/ Documentation (CC BY 4.0)
scripts/ Developer setup and launch scripts
| Content | License |
|---|---|
| Application code | Apache-2.0 |
| Official scenario packs | CC BY 4.0 |
| Documentation | CC BY 4.0 |
| Placeholder assets | CC0-1.0 |
| Model weights | Not bundled — user-installed with full license disclosure |
| Premium scenario-pack DLC | Proprietary — not in this repository; sold on Steam |
Everything in this repository is open source: the code is Apache-2.0, the four official packs and the docs are CC BY 4.0. The paid Steam build is a packaging of this same open code — buying it funds development, not access. Premium expansion packs are the only proprietary content; they live in a separate private repository and are never included here.
LICENSE contains the full Apache-2.0 text.
NOTICE lists copyright notices and per-artifact license details.