@neuroverseos/nv-sim 0.1.2 → 0.1.4

package/README.md

@@ -1,130 +1,346 @@
-# NV-SIM — Governed Agent Simulation
+# NV-SIM
 
-What happens when you run the **same simulation twice**, but change the **rules of the world**?
+**Change the rules. See why the system changed.**
 
-NV-SIM is a lightweight simulation tool that lets developers compare emergent outcomes **with and without governance constraints**.
+NV-SIM doesn't predict outcomes — it shows how they change when you change the rules.
 
-Instead of prompting AI systems to behave, NV-SIM applies **explicit world rules** that shape how agents interact and evolve over time.
+Define a world. Set the constraints. Run the agents. Then change one rule and watch the entire system reorganize. Not in theory. You see exactly which agents shifted, what patterns emerged, and why the outcome changed.
 
-Run a governed vs baseline simulation in one command:
+It feels a lot like a Prime Radiant — except instead of psychohistory, you're running controlled behavioral experiments on complex systems.
 
 ```bash
-npx @neuroverseos/nv-sim compare
+npx @neuroverseos/nv-sim visualize
 ```
 
-You'll see how structural constraints — liquidity floors, leverage limits, circuit breakers, coalition balancing — change the behavior of the entire system.
+## What This Actually Is
 
-Because governance doesn't just block bad actions.
-It changes the structure of the system itself.
+Most simulation tools answer: *"What will happen?"*
 
-## Quick Start
+NV-SIM answers: *"What changes when I change the rules?"*
+
+You're not forecasting. You're experimenting. You change a constraint — no panic selling, cap leverage at 3x, close a shipping lane — and the system shows you:
+
+- **How agents reorganize** (80% shifted from panic selling to coordinated holding)
+- **What patterns emerge** (panic suppression, stability shift)
+- **What the system became** (volatility dropped 21%, cascade avoided)
+
+```
+Rule changed
+  → Behavior shifted
+    → Pattern emerged
+      → System outcome changed
+```
+
+That's the loop. Every time.
+
+## The Demo Moment
+
+**Before:**
+```
+panic_sell → panic_sell → panic_sell
+pressure: 0.94
+system: unstable
+```
+
+**Rule added:** no panic selling
+
+**After:**
+```
+80% of agents adapted
+
+  panic_sell → hold
+  panic_sell → hold
+  panic_sell → hold
+
+  Pattern: coordinated_holding
+  Pattern: panic_suppression
+
+  pressure: 0.54
+  cascade: avoided
+```
+
+You didn't predict this. You caused it — by changing one rule — and watched the system tell you why.
+
+## Worlds — Where the Power Lives
 
-Run a comparison simulation:
+Integration is one line. Worlds are where you define what your system allows.
+
+The `world` you pass to `/api/evaluate` determines how actions are judged. Change the world, change the outcome.
+
+```
+verdict = evaluate(actor="agent_1", action="panic_sell", world="trading")
+                                                          ^^^^^^^^
+                                                    this controls everything
+```
+
+### Built-in Worlds
+
+| World | Domain | What You Can Change |
+|-------|--------|---------------------|
+| `trading` | Financial markets | Leverage ratio, liquidity index, volatility, circuit breakers |
+| `strait_of_hormuz` | Geopolitical energy | Oil supply disruption, military escalation, diplomatic channels |
+| `gas_price_spike` | Economic energy | Gas price, consumer sentiment, EV demand, grid capacity |
+| `ai_regulation_crisis` | Tech regulation | AI regulation impact on markets and sector alignment |
+
+### Same Agents, Different Rules
 
 ```bash
-npx @neuroverseos/nv-sim compare
+npx @neuroverseos/nv-sim worlds trading strait_of_hormuz
+```
+
+Same agents. Different rules. Different outcomes. That's the experiment.
+
+## Narrative Shocks
+
+Inject events into running simulations. Watch them propagate differently through different agents — a bank collapse hits retail investors and algorithmic traders in completely different ways.
+
+```bash
+npx @neuroverseos/nv-sim compare --inject tanker_explosion@3,sanctions@5
 ```
 
-Stress-test a system:
+The `@` syntax sets when the event hits. Events have severity, propagation speed, and directional impact.
+
+## Named Scenarios
+
+Pre-built crisis sequences — a world + ordered narrative events:
 
 ```bash
-npx @neuroverseos/nv-sim chaos
+npx @neuroverseos/nv-sim scenario taiwan_crisis
+npx @neuroverseos/nv-sim scenario bank_run --compare
+npx @neuroverseos/nv-sim scenarios              # list all
 ```
 
-Launch the visual inspector:
+| Scenario | Events | What It Tests |
+|----------|--------|---------------|
+| `taiwan_crisis` | 4 | Military escalation + sanctions + shipping disruption |
+| `hormuz_blockade` | 3 | Tanker attack escalates to full shipping disruption |
+| `bank_run` | 4 | Bank insolvency triggers contagion cascade |
+| `flash_cascade` | 3 | Algorithmic failure chain reaction |
+| `oil_shock` | 4 | Tanker attack + sanctions compound crisis |
+| `energy_transition_shock` | 3 | Grid failure during rapid transition |
+| `election_shock` | 4 | Political shock cascades into markets |
+| `ai_crackdown` | 3 | Overnight AI regulation triggers panic |
+| `perfect_storm` | 6 | Geopolitical + financial + energy convergence |
+| `black_swan` | 5 | Extreme low-probability events in succession |
+
+The `--compare` flag runs the same scenario across multiple worlds — which rule environment is more resilient?
+
+## Interactive Control Platform
 
 ```bash
 npx @neuroverseos/nv-sim visualize
 ```
 
-## Why This Exists
+This opens a control surface where you can:
 
-AI agents are starting to act inside real systems.
+- Switch between rule environments
+- Adjust state variables with auto-generated controls
+- Inject narrative events at specific rounds
+- Load crisis scenarios with one click
+- Watch the **System Shift card** — not a log of what happened, but a story of what the system became
+- Save any experiment as a reusable variant
 
-Most AI control today happens through prompts.
+### The System Shift Card
 
-Prompts can suggest behavior.
-But they cannot enforce rules.
+When rules reshape behavior, you don't get a log. You get this:
 
-NV-SIM explores a different idea:
+```
+◆ SYSTEM SHIFT
+
+  No panic selling allowed
+  437 actions reshaped out of 1,247 total
+
+  Rule → Behavioral Shift → What Emerged → System Outcome
+
+  ┌─ Behavioral Shift ─────────────────┐
+  │ 80%                                │
+  │ adaptation across 1,247 agents     │
+  │ → BLOCK: hold (312 agents)         │
+  │ → MODIFY: sell_slowly (87 agents)  │
+  └────────────────────────────────────┘
+
+  ┌─ What Emerged ─────────────────────┐
+  │ Coordinated Holding                │
+  │ Panic Suppression                  │
+  └────────────────────────────────────┘
+
+  ┌─ System Outcome ───────────────────┐
+  │ Volatility   47% → 26%            │
+  │ Stability    58% → 79%            │
+  │ Cascade      Avoided              │
+  └────────────────────────────────────┘
+
+  ┌─ What Actually Happened ───────────┐
+  │ No panic selling allowed. 437 of   │
+  │ 1,247 agents reorganized — most    │
+  │ shifted to hold. Volatility        │
+  │ dropped 21%.                       │
+  └────────────────────────────────────┘
+
+  ▶ View raw detail
+```
 
-**What if we define the world an AI operates inside?**
-**And let governance shape the outcomes.**
+We don't show you what every agent did. We show you what the system became.
 
-## Commands
+### World Variants
 
-| Command | Description |
-|---------|-------------|
-| `nv-sim compare [preset]` | Run baseline vs governed simulation |
-| `nv-sim chaos [preset]` | Stress test across hundreds of randomized scenarios |
-| `nv-sim visualize [preset]` | Launch local simulation inspector in browser |
-| `nv-sim analyze <file>` | Analyze a simulation from file or stdin |
-| `nv-sim presets` | List available scenario presets |
+Save any experiment as a named variant:
 
-## Presets
+```
+Adjust rules → Inject events → Run → See the shift → Save as variant
+```
+
+Variants capture the base world, state overrides, narrative events, and results. Store them in git. Share them. Replay them. This turns experiments into assets.
+
+## Works With Anything
+
+If your system has actions, you can govern it. One API call.
+
+```
+Agent decides → POST /api/evaluate → verdict → agent adapts
+```
+
+The entire integration:
+
+```
+Before:   action = agent.decide()
+After:    action = govern(agent.decide())
+```
+
+No SDK required. No framework required. Just an HTTP call.
+
+**curl** (zero dependencies):
+
+```bash
+curl -X POST http://localhost:3456/api/evaluate \
+  -H "Content-Type: application/json" \
+  -d '{"actor":"agent_1","action":"panic_sell","world":"trading"}'
+```
+
+**Python:**
+
+```python
+import requests
+
+verdict = requests.post("http://localhost:3456/api/evaluate", json={
+    "actor": "agent_1",
+    "action": "panic_sell",
+    "world": "trading"
+}).json()
+
+if verdict["decision"] == "BLOCK":
+    action = "hold"
+```
 
-| Preset | Scenario |
-|--------|----------|
-| `trading` | Flash crash — algorithmic cascade (default) |
-| `strait_of_hormuz` | Geopolitical energy crisis |
-| `gas_price_spike` | Economic energy shock |
-| `ai_regulation_crisis` | AI regulation impact |
+**JavaScript:**
 
-## Example Output
+```js
+const verdict = await fetch("http://localhost:3456/api/evaluate", {
+  method: "POST",
+  headers: { "Content-Type": "application/json" },
+  body: JSON.stringify({ actor: "agent_1", action: "panic_sell", world: "trading" })
+}).then(r => r.json());
 
+if (verdict.decision === "BLOCK") action = "hold";
 ```
-NV-SIM — Governed Simulation Comparison
 
-SIMULATION A — No Governance (Baseline)
-  Stability:      80%
-  Volatility:     56%
-  Coalition risks: 2
+**Any agent loop:**
 
-SIMULATION B — With World Rules (Governed)
-  Stability:      91%
-  Volatility:     42%
-  Coalition risks: 0
+```python
+for agent in agents:
+    action = agent.decide()
 
-GOVERNANCE IMPACT
-  Stability:        +9 percentage points
-  Volatility:       -25%
-  Coalition risks:  2 eliminated
+    verdict = evaluate(actor=agent.id, action=action, world="trading")
+
+    if verdict["decision"] == "BLOCK":
+        action = "hold"
+    elif verdict["decision"] == "MODIFY":
+        action = verdict["modified_action"]
+
+    environment.apply(agent, action)
 ```
 
-## Chaos Testing
+If your system can make an HTTP request, it can be governed.
+
+Most systems generate behavior. This one shapes it.
 
-Find the breaking point:
+See [INTEGRATION.md](./INTEGRATION.md) for the full API contract and decision types.
+
+## Quick Start
 
 ```bash
+# See it
+npx @neuroverseos/nv-sim visualize
+
+# Compare governed vs ungoverned
+npx @neuroverseos/nv-sim compare
+
+# Run a crisis
+npx @neuroverseos/nv-sim scenario taiwan_crisis
+
+# Same crisis, different worlds — which rules hold?
+npx @neuroverseos/nv-sim scenario bank_run --compare
+
+# Inject shocks
+npx @neuroverseos/nv-sim compare --inject tanker_explosion@3,sanctions@5
+
+# Stress test (500 randomized runs)
 npx @neuroverseos/nv-sim chaos --runs 500
+
+# Run local governance runtime for your own simulator
+npx @neuroverseos/nv-sim serve
 ```
 
-Runs hundreds of randomized simulations with perturbed agent behavior, market shocks, and coalition dynamics. Outputs aggregate collapse probability, worst-case scenarios, and most triggered governance rules.
+## Commands
+
+| Command | What It Does |
+|---------|-------------|
+| `nv-sim visualize` | Interactive control platform |
+| `nv-sim compare [preset]` | Baseline vs governed simulation |
+| `nv-sim compare --inject event@round,...` | With narrative shocks |
+| `nv-sim scenario <id>` | Run a named stress scenario |
+| `nv-sim scenario <id> --compare` | Cross-world scenario comparison |
+| `nv-sim scenarios` | List all available scenarios |
+| `nv-sim worlds <a> <b>` | Compare two rule environments |
+| `nv-sim chaos [preset] --runs N` | Stress test across randomized scenarios |
+| `nv-sim serve --port N` | Local governance runtime for any simulator |
+| `nv-sim analyze <file>` | Analyze simulation from file or stdin |
+| `nv-sim presets` | List available world presets |
+
+## How It Works
 
 ```
-NV-SIM CHAOS TEST
-  Scenarios tested: 500
+event → narrative propagation → belief shift → agent action → governance → outcome
+```
 
-  Baseline collapse probability:  34%
-  Governed collapse probability:   8%
+Four forces shape every simulation:
 
-  Most triggered rule:
-    Market Panic Circuit Breaker (247 times)
+1. **Agent behavior** — traders, voters, regulators, media
+2. **World rules** — leverage caps, circuit breakers, chokepoints
+3. **Narrative events** — information shocks that propagate through the system
+4. **Perception propagation** — different agents react differently to the same event
 
-  Governance reduced catastrophic failure risk by 76%.
-```
+This lets you ask compound questions:
+
+> What happens if a tanker explodes while Hormuz is closed and leverage is capped at 3x?
+
+That combination produces very different outcomes than any single factor alone. And when you change one rule — uncap leverage, open a diplomatic channel, add a circuit breaker — you see exactly why the outcome changed.
 
 ## Architecture
 
 ```
 @neuroverseos/governance    ← deterministic rule engine
         ↓
-    nv-sim CLI              ← simulation runner + comparison
+    nv-sim engine           ← world rules + narrative injection + swarm simulation
+        ↓
+    nv-sim CLI              ← scenarios, comparison, chaos testing
+        ↓
+    control platform        ← interactive browser UI + System Shift card
         ↓
-  developer simulators      ← MiroFish, Mesa, NetLogo, custom
+    world variants          ← saved experiments as shareable assets
 ```
 
-NV-SIM uses [`@neuroverseos/governance`](https://www.npmjs.com/package/@neuroverseos/governance) for deterministic guard evaluation. Every agent action is evaluated against world rules — no LLM in the loop.
+Everything runs locally. NV-SIM uses [`@neuroverseos/governance`](https://www.npmjs.com/package/@neuroverseos/governance) for deterministic guard evaluation — no LLM, no cloud, no cost. Your agents call `localhost`, and the world file decides what's allowed.
 
 ## License
 
@@ -132,6 +348,6 @@ Apache 2.0
 
 ---
 
-Simulate the future. Govern the outcomes.
+Change the rules. See why the system changed.
 
 [@neuroverseos](https://github.com/NeuroverseOS)