@neuroverseos/nv-sim 0.1.0 → 0.1.4

package/README.md

@@ -1,73 +1,353 @@
-# Welcome to your Lovable project
+# NV-SIM
 
-## Project info
+**Change the rules. See why the system changed.**
 
-**URL**: https://lovable.dev/projects/REPLACE_WITH_PROJECT_ID
+NV-SIM doesn't predict outcomes — it shows how they change when you change the rules.
 
-## How can I edit this code?
+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.
 
-There are several ways of editing your application.
+It feels a lot like a Prime Radiant — except instead of psychohistory, you're running controlled behavioral experiments on complex systems.
 
-**Use Lovable**
+```bash
+npx @neuroverseos/nv-sim visualize
+```
+
+## What This Actually Is
+
+Most simulation tools answer: *"What will happen?"*
+
+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
+
+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 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
+```
+
+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 scenario taiwan_crisis
+npx @neuroverseos/nv-sim scenario bank_run --compare
+npx @neuroverseos/nv-sim scenarios              # list all
+```
+
+| 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
+```
+
+This opens a control surface where you can:
+
+- 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
+
+### The System Shift Card
+
+When rules reshape behavior, you don't get a log. You get this:
+
+```
+◆ 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)  │
+  └────────────────────────────────────┘
 
-Simply visit the [Lovable Project](https://lovable.dev/projects/REPLACE_WITH_PROJECT_ID) and start prompting.
+  ┌─ What Emerged ─────────────────────┐
+  │ Coordinated Holding                │
+  │ Panic Suppression                  │
+  └────────────────────────────────────┘
 
-Changes made via Lovable will be committed automatically to this repo.
+  ┌─ 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
+```
 
-**Use your preferred IDE**
+We don't show you what every agent did. We show you what the system became.
 
-If you want to work locally using your own IDE, you can clone this repo and push changes. Pushed changes will also be reflected in Lovable.
+### World Variants
 
-The only requirement is having Node.js & npm installed - [install with nvm](https://github.com/nvm-sh/nvm#installing-and-updating)
+Save any experiment as a named variant:
 
-Follow these steps:
+```
+Adjust rules → Inject events → Run → See the shift → Save as variant
+```
 
-```sh
-# Step 1: Clone the repository using the project's Git URL.
-git clone <YOUR_GIT_URL>
+Variants capture the base world, state overrides, narrative events, and results. Store them in git. Share them. Replay them. This turns experiments into assets.
 
-# Step 2: Navigate to the project directory.
-cd <YOUR_PROJECT_NAME>
+## Works With Anything
 
-# Step 3: Install the necessary dependencies.
-npm i
+If your system has actions, you can govern it. One API call.
 
-# Step 4: Start the development server with auto-reloading and an instant preview.
-npm run dev
+```
+Agent decides → POST /api/evaluate → verdict → agent adapts
 ```
 
-**Edit a file directly in GitHub**
+The entire integration:
 
-- Navigate to the desired file(s).
-- Click the "Edit" button (pencil icon) at the top right of the file view.
-- Make your changes and commit the changes.
+```
+Before:   action = agent.decide()
+After:    action = govern(agent.decide())
+```
+
+No SDK required. No framework required. Just an HTTP call.
 
-**Use GitHub Codespaces**
+**curl** (zero dependencies):
 
-- Navigate to the main page of your repository.
-- Click on the "Code" button (green button) near the top right.
-- Select the "Codespaces" tab.
-- Click on "New codespace" to launch a new Codespace environment.
-- Edit files directly within the Codespace and commit and push your changes once you're done.
+```bash
+curl -X POST http://localhost:3456/api/evaluate \
+  -H "Content-Type: application/json" \
+  -d '{"actor":"agent_1","action":"panic_sell","world":"trading"}'
+```
 
-## What technologies are used for this project?
+**Python:**
 
-This project is built with:
+```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"
+```
+
+**JavaScript:**
+
+```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";
+```
+
+**Any agent loop:**
+
+```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)
+```
 
-- Vite
-- TypeScript
-- React
-- shadcn-ui
-- Tailwind CSS
+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
+```
+
+## 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
+
+```
+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 engine           ← world rules + narrative injection + swarm simulation
+        ↓
+    nv-sim CLI              ← scenarios, comparison, chaos testing
+        ↓
+    control platform        ← interactive browser UI + System Shift card
+        ↓
+    world variants          ← saved experiments as shareable assets
+```
 
-## How can I deploy this project?
+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.
 
-Simply open [Lovable](https://lovable.dev/projects/REPLACE_WITH_PROJECT_ID) and click on Share -> Publish.
+## License
 
-## Can I connect a custom domain to my Lovable project?
+Apache 2.0
 
-Yes, you can!
+---
 
-To connect a domain, navigate to Project > Settings > Domains and click Connect Domain.
+Change the rules. See why the system changed.
 
-Read more here: [Setting up a custom domain](https://docs.lovable.dev/features/custom-domain#custom-domain)
+[@neuroverseos](https://github.com/NeuroverseOS)