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
| 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.
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.
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.
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.