@neuroverseos/nv-sim 0.1.2 → 0.1.6

package/README.md

@@ -1,130 +1,440 @@
-# 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
 
-Run a comparison simulation:
+  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
+
+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:
+
+```
+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"}'
+```
 
-## Presets
+**Python:**
 
-| 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 |
+```python
+import requests
 
-## Example Output
+verdict = requests.post("http://localhost:3456/api/evaluate", json={
+    "actor": "agent_1",
+    "action": "panic_sell",
+    "world": "trading"
+}).json()
 
+if verdict["decision"] == "BLOCK":
+    action = "hold"
 ```
-NV-SIM — Governed Simulation Comparison
 
-SIMULATION A — No Governance (Baseline)
-  Stability:      80%
-  Volatility:     56%
-  Coalition risks: 2
+**JavaScript:**
 
-SIMULATION B — With World Rules (Governed)
-  Stability:      91%
-  Volatility:     42%
-  Coalition risks: 0
+```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());
 
-GOVERNANCE IMPACT
-  Stability:        +9 percentage points
-  Volatility:       -25%
-  Coalition risks:  2 eliminated
+if (verdict.decision === "BLOCK") action = "hold";
 ```
 
-## Chaos Testing
+**Any agent loop:**
 
-Find the breaking point:
+```python
+for agent in agents:
+    action = agent.decide()
+
+    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)
+```
+
+If your system can make an HTTP request, it can be governed.
+
+Most systems generate behavior. This one shapes it.
+
+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
+```
+
+## Policy Enforcement — The Product Loop
+
+Write rules in plain English. Run the same scenario. See what changes. Adjust and repeat.
+
+### Step 1: See it work (zero config)
+
+```bash
+npx nv-sim enforce
+```
+
+Runs three iterations automatically: no rules → light rules → full rules. You see divergence immediately.
+
+### Step 2: Write your own rules
+
+Create a text file. That's it.
+
+```
+# my-rules.txt
+
+Block panic selling during high volatility
+Limit leverage to 5x
+Maintain minimum liquidity floor
+Slow down algorithmic trading when contagion spreads
+```
+
+### Step 3: Run it
+
+```bash
+npx nv-sim enforce trading my-rules.txt
+```
+
+The engine parses your plain English into governance rules, runs the scenario, and shows what changed.
+
+### Step 4: Change a rule. Run again.
+
+Remove "Limit leverage to 5x". Run again. Did stability drop? That rule was load-bearing.
+
+Add "Require transparency for all large trades". Run again. Did effectiveness improve?
+
+The report tracks every change:
+
+```
+RULE CHANGES
+  Run 2:
+    + Block panic selling during high volatility
+    + Slow down algorithmic trading when contagion spreads
+    - Limit leverage to 5x
+
+DIVERGENCE ANALYSIS
+  Stability trend:     79% → 98%
+  Effectiveness trend: 11% → 32%
+
+KEY INSIGHT
+  Enforcement gates are the key differentiator. Rules alone: 11%. Rules + gates: 32%.
+
+TRY THIS EXPERIMENT
+  Remove this rule and see what happens:
+    Remove "Block panic selling during high volatility" from your rules file, then run again.
+  If stability drops, that rule was load-bearing. If nothing changes, it was noise.
 ```
 
-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.
+### Step 5: Compare two rule sets side by side
 
+```bash
+npx nv-sim enforce trading light-rules.txt strict-rules.txt
 ```
-NV-SIM CHAOS TEST
-  Scenarios tested: 500
 
-  Baseline collapse probability:  34%
-  Governed collapse probability:   8%
+### Rule patterns
 
-  Most triggered rule:
-    Market Panic Circuit Breaker (247 times)
+The engine understands these patterns in plain English:
 
-  Governance reduced catastrophic failure risk by 76%.
+| Pattern | What it does | Example |
+|---------|-------------|---------|
+| `Block X` | Hard suppression of matching actions | `Block panic selling` |
+| `Limit X` / `Cap X` | Caps extreme positions | `Limit leverage to 5x` |
+| `Slow X` / `Dampen X` | Reduces large movements | `Slow down algorithmic trading` |
+| `Maintain X` / `Floor X` | Enforces minimum thresholds | `Maintain minimum liquidity` |
+| `Rebalance X` | Pulls extremes toward equilibrium | `Rebalance correlated positions` |
+| `Require X` | Enforceable structural constraint | `Require transparency for large trades` |
+| `Monitor X` | Generates a circuit breaker gate | `Monitor contagion spread` |
+
+### Other scenarios
+
+```bash
+npx nv-sim enforce strait_of_hormuz my-rules.txt    # Same rules, different scenario
+npx nv-sim enforce ai_regulation_crisis              # Default progressive run
+npx nv-sim enforce trading --output=report.json      # Save as JSON
 ```
 
+### Advanced: JSON world files
+
+For full control over gates, state variables, and thesis, use JSON world files. See `examples/worlds/` for templates. Enforce accepts both `.txt` and `.json` — mix and match.
+
+## Commands
+
+| Command | What It Does |
+|---------|-------------|
+| `nv-sim enforce [preset]` | Policy enforcement lab — iterative rule testing |
+| `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
+
+```
+event → narrative propagation → belief shift → agent action → governance → outcome
+```
+
+Four forces shape every simulation:
+
+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
+
+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 +442,6 @@ Apache 2.0
 
 ---
 
-Simulate the future. Govern the outcomes.
+Change the rules. See why the system changed.
 
 [@neuroverseos](https://github.com/NeuroverseOS)