@neuroverseos/nv-sim 0.1.4 → 0.1.5

package/README.md

@@ -2,36 +2,54 @@
 
 **Change the rules. See why the system changed.**
 
-NV-SIM doesn't predict outcomes — it shows how they change when you change the rules.
-
-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.
-
-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 visualize
 ```
 
-## What This Actually Is
+## The Problem With Agentic Simulation Today
 
-Most simulation tools answer: *"What will happen?"*
+You build a multi-agent system. You run it. You get metrics — loss curves, reward signals, completion rates. Something goes wrong, or something goes right, and you ask the only question that matters:
+
+*Why did the agents do that?*
+
+Nobody can tell you. The metrics say *what* happened. The logs say *when* it happened. But nothing tells you *why agents changed their behavior* — which rule caused it, which agents shifted first, what strategy they abandoned, and what they replaced it with.
+
+So you rerun. You tweak. You guess. You stare at dashboards full of numbers that describe the system but never explain it.
 
-NV-SIM answers: *"What changes when I change the rules?"*
+That's the gap.
 
-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:
+## What NV-SIM Gives You That Nothing Else Does
 
-- **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)
+NV-SIM doesn't predict outcomes. It shows you **why agents behaved the way they did** — and what happens when you change the rules.
+
+You change one constraint — block panic selling, cap leverage at 3x, close a shipping lane — and the system shows you:
+
+- **Before → After proof**: "80% of agents shifted from panic selling to coordinated holding"
+- **Emergent patterns**: "Panic suppression appeared — not programmed, not predicted"
+- **Causal chains**: "Agents became more cautious after early aggressive attempts failed"
+- **Quantified outcomes**: "Volatility dropped 21%, cascade avoided"
 
 ```
 Rule changed
-  → Behavior shifted
-    → Pattern emerged
+  → Agents shifted strategy
+    → New patterns emerged
       → System outcome changed
+        → You know exactly why
 ```
 
-That's the loop. Every time.
+This is behavioral evidence, not metrics. You don't get a number — you get a story you can trace, verify, and share.
+
+### For researchers
+
+You get **controlled behavioral experiments** on complex systems. Same agents, different rules, measured side by side. The output isn't a chart — it's proof of what changed and why.
+
+### For developers
+
+You get **runtime governance** for any agent system. One HTTP call between "agent decides" and "agent acts." Your agents become observable, auditable, and controllable — without rewriting your framework.
+
+### For both
+
+You get something that didn't exist before: **rule-to-behavior causation**. Not correlation. Not post-hoc analysis. Direct, traceable proof that changing rule X caused agents to shift from behavior A to behavior B.
 
 ## The Demo Moment
 
@@ -46,12 +64,17 @@ system: unstable
 
 **After:**
 ```
-80% of agents adapted
+Market stabilized as agents shifted toward safer positions
 
   panic_sell → hold
   panic_sell → hold
   panic_sell → hold
 
+  80% of agents shifted from aggressive to conservative strategies
+  Uncertainty dropped 34% as agents moved from exploration to caution
+
+  WHY: Agents became more cautious after early attempts failed
+
   Pattern: coordinated_holding
   Pattern: panic_suppression
 
@@ -59,13 +82,97 @@ system: unstable
   cascade: avoided
 ```
 
-You didn't predict this. You caused it — by changing one rule — and watched the system tell you why.
+You didn't predict this. You caused it — by changing one rule — and the system told you exactly why.
 
-## Worlds — Where the Power Lives
+## What This Actually Is
+
+Most simulation tools answer: *"What will happen?"*
+
+NV-SIM answers: *"What changes when I change the rules — and why?"*
+
+You're not forecasting. You're running controlled behavioral experiments. Every simulation produces:
+
+| What You Get | What It Proves |
+|---|---|
+| **Outcome statement** | System state + dominant agent behavior in one sentence |
+| **Behavioral shifts** | Before → after for every agent group, with percentages |
+| **Causal explanation** | Why agents changed — in their experience, not system jargon |
+| **Confidence rating** | How strong the evidence is, how much risk remains |
+| **Full audit trail** | Every decision, every rule, every adaptation — append-only |
+
+The output is designed to be specific, narrative, and shareable. Not "40% adjusted actions" — but "40% shifted from aggressive to conservative strategies after early attempts failed."
+
+## Design the Rules Once. Run Them Anywhere.
+
+NV-SIM is a runtime, not just a simulator. It runs in two modes:
+
+- **Simulate** — explore how agents behave under different rules
+- **Act** — govern real agents, real workflows, real decisions in production
+
+The interface is the same. The difference is where the agents come from.
+
+```
+Simulate → internal swarm engine (built-in agents, instant results)
+Act      → your system (any framework, any language, one HTTP call)
+```
+
+The same world file can simulate a crisis, govern a live system, and produce comparable outcomes across both. This means the experiments you run in simulation directly translate to the rules you deploy in production.
+
+## Behavioral Analysis — The Proof Layer
+
+Blocking actions is easy. The hard part is proving what changed and why. NV-SIM doesn't just count actions — it tracks how agents actually reorganized.
+
+Every simulation produces behavioral evidence:
+
+- **Action classification** — each agent action categorized as aggressive, defensive, cautious, cooperative, opportunistic, or neutral
+- **Agent trajectories** — each agent's behavior traced across rounds, showing when and how they shifted
+- **Behavioral shifts** — the exact moment agents changed strategy, with before → after
+- **Cross-run comparison** — same agents under different rules, measured side by side
+
+```
+BEHAVIORAL ANALYSIS
+
+  Action Distribution:
+    aggressive:    12%  (was 67%)
+    cooperative:   41%  (was 8%)
+    cautious:      31%  (was 11%)
+    defensive:     16%  (was 14%)
+
+  Shifts Detected:
+    → 80% shifted from aggressive to cooperative after round 3
+    → Panic selling replaced by coordinated holding
+    → New pattern: quality_competition (not present in baseline)
+
+  Trajectory: agent_hedge_fund_1
+    Round 1: aggressive → Round 2: aggressive → Round 3: [shifted] → Round 4: cautious → Round 5: cooperative
+```
+
+The behavioral shift is the insight. You changed a rule, and the system tells you exactly who changed, when they changed, and what they changed to.
 
-Integration is one line. Worlds are where you define what your system allows.
+## Audit Trail — Full Evidence Chain
 
-The `world` you pass to `/api/evaluate` determines how actions are judged. Change the world, change the outcome.
+Every decision is recorded in an append-only audit log. Every rule, every agent action, every adaptation — persistent and queryable.
+
+```
+AUDIT TRAIL (session: 2026-03-18T14:22:00)
+
+  agent_hedge_fund_1 → attempted panic_sell → blocked
+    rule: no_panic_selling (invariant)
+    evidence: action matches blocked pattern during high volatility
+
+  agent_hedge_fund_1 → shifted to hold
+    adapted: true (shifted from aggressive to defensive)
+
+  BEHAVIORAL SHIFT: agent_hedge_fund_1
+    before: aggressive | after: cautious
+    trigger: early aggressive attempts failed at round 3
+```
+
+Stored as JSONL — one JSON object per line, human-readable, pipeable through `jq`. No cloud, no deletion. Complete evidence chain.
+
+## Worlds — Where the Power Lives
+
+The `world` you pass controls everything. Change the world, change the outcome.
 
 ```
 verdict = evaluate(actor="agent_1", action="panic_sell", world="trading")
@@ -137,64 +244,92 @@ This opens a control surface where you can:
 - 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
+- Watch the **Outcome Panel** — not a log of what happened, but a story of what the system became and why
 - Save any experiment as a reusable variant
 
-### The System Shift Card
+### The Outcome Panel
 
-When rules reshape behavior, you don't get a log. You get this:
+When rules reshape behavior, you don't get a dashboard of metrics. You get this:
 
 ```
-◆ SYSTEM SHIFT
+◆ OUTCOME
+
+  Market stabilized as agents shifted toward safer positions
+
+  Confidence: Strong | Evidence: Solid | Risk: Low
+
+  ┌─ What Agents Did ────────────────┐
+  │ 80% shifted from aggressive to   │
+  │ conservative strategies           │
+  │ 12% reduced position size after  │
+  │ initial attempts failed           │
+  │ 8% maintained original strategy  │
+  └──────────────────────────────────┘
+
+  ┌─ Why This Happened ──────────────┐
+  │ Early aggressive attempts failed,│
+  │ forcing agents to rethink.       │
+  │ Uncertainty dropped as agents    │
+  │ stopped experimenting.           │
+  └──────────────────────────────────┘
+
+  ┌─ What Emerged ───────────────────┐
+  │ Coordinated Holding              │
+  │ Panic Suppression                │
+  └──────────────────────────────────┘
+
+  ┌─ System Outcome ─────────────────┐
+  │ Volatility   47% → 26%          │
+  │ Stability    58% → 79%          │
+  │ Cascade      Avoided             │
+  └──────────────────────────────────┘
+
+  ▶ View audit trail
+```
 
-  No panic selling allowed
-  437 actions reshaped out of 1,247 total
+Every line is specific. Every line is shareable. No system jargon.
 
-  Rule → Behavioral Shift → What Emerged → System Outcome
+### World Variants
 
-  ┌─ Behavioral Shift ─────────────────┐
-  │ 80%                                │
-  │ adaptation across 1,247 agents     │
-  │ → BLOCK: hold (312 agents)         │
-  │ → MODIFY: sell_slowly (87 agents)  │
-  └────────────────────────────────────┘
+Save any experiment as a named variant:
 
-  ┌─ What Emerged ─────────────────────┐
-  │ Coordinated Holding                │
-  │ Panic Suppression                  │
-  └────────────────────────────────────┘
+```
+Adjust rules → Inject events → Run → See what changed → Save as variant
+```
 
-  ┌─ System Outcome ───────────────────┐
-  │ Volatility   47% → 26%            │
-  │ Stability    58% → 79%            │
-  │ Cascade      Avoided              │
-  └────────────────────────────────────┘
+Variants capture the base world, state overrides, narrative events, and results. Store them in git. Share them. Replay them. This turns experiments into assets.
 
-  ┌─ What Actually Happened ───────────┐
-  │ No panic selling allowed. 437 of   │
-  │ 1,247 agents reorganized — most    │
-  │ shifted to hold. Volatility        │
-  │ dropped 21%.                       │
-  └────────────────────────────────────┘
+## Governance Runtime — Plug Into Your Own System
 
-  ▶ View raw detail
+```bash
+npx @neuroverseos/nv-sim serve
 ```
 
-We don't show you what every agent did. We show you what the system became.
-
-### World Variants
-
-Save any experiment as a named variant:
+This starts a local server. Any simulator, agent framework, or application can POST actions and get decisions back.
 
 ```
-Adjust rules → Inject events → Run → See the shift → Save as variant
+  Endpoint: http://localhost:3456/api/evaluate
+  Method:   POST
+  Contract: { actor, action, payload?, state?, world? }
+  Response: { decision: ALLOW|BLOCK|MODIFY, reason, evidence }
 ```
 
-Variants capture the base world, state overrides, narrative events, and results. Store them in git. Share them. Replay them. This turns experiments into assets.
+Your agents call localhost. The world file decides what's allowed. No cloud. No cost.
+
+Additional endpoints:
+
+| Endpoint | What It Does |
+|----------|-------------|
+| `POST /api/evaluate` | Submit an action for evaluation |
+| `GET /api/session` | Current session stats |
+| `GET /api/session/report` | Full session report |
+| `POST /api/session/reset` | Reset session state |
+| `POST /api/session/save` | Save session as experiment |
+| `GET /api/events` | SSE stream of live events |
 
-## Works With Anything
+### Works With Anything
 
-If your system has actions, you can govern it. One API call.
+If your system has actions, you can govern them. One API call.
 
 ```
 Agent decides → POST /api/evaluate → verdict → agent adapts
@@ -264,7 +399,139 @@ 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.
+See [INTEGRATION.md](./INTEGRATION.md) for the full API contract, framework guides, and decision types.
+
+## Policy Enforcement — The Experiment 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 rules, runs the scenario, and shows what changed — with before → after behavioral proof.
+
+### 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 agents shift strategy?
+
+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
+  Removing the leverage cap caused agents to take larger positions — but the
+  panic selling block forced them to hold through volatility instead of exiting.
+  Net effect: more risk-taking, but more stability.
+
+TRY THIS EXPERIMENT
+  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.
+```
+
+### Step 5: Compare two rule sets side by side
+
+```bash
+npx nv-sim enforce trading light-rules.txt strict-rules.txt
+```
+
+### Rule patterns
+
+The engine understands these patterns in plain English:
+
+| 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.
+
+## AI Providers — Bring Your Own Model
+
+AI is optional. AI is governed. AI is pluggable.
+
+NV-SIM works without any AI — the deterministic engine runs on math, not tokens. But when you bring your own model, AI becomes a governed actor inside the system — subject to the same rules as every other agent.
+
+### How AI fits in
+
+AI plays two governed roles:
+
+| Role | What It Does | Constraints |
+|------|-------------|-------------|
+| `ai_translator` | Converts unstructured input into normalized events | Must output valid schema, no invention of events, must include confidence |
+| `ai_analyst` | Generates reports from simulation traces | Must reference trace data, must include blocked actions, no unverifiable claims |
+
+Both roles go through `/api/evaluate` like any other actor. The AI doesn't control the system — the system controls the AI.
+
+### Supported providers
+
+NV-SIM auto-detects the best available provider from your environment:
+
+| Provider | Env Var | What It Connects To |
+|----------|---------|---------------------|
+| Anthropic (Claude) | `ANTHROPIC_API_KEY` | Claude Sonnet, Opus, Haiku |
+| OpenAI | `OPENAI_API_KEY` | GPT-4, GPT-4o, o1 |
+| Groq | `GROQ_API_KEY` | Llama 3 70B |
+| Together | `TOGETHER_API_KEY` | Llama, Mixtral |
+| Mistral | `MISTRAL_API_KEY` | Mistral Large |
+| Deepseek | `DEEPSEEK_API_KEY` | Deepseek Chat |
+| Fireworks | `FIREWORKS_API_KEY` | Llama, custom models |
+| Ollama | `OLLAMA_BASE_URL` | Any local model |
+| Local LLM | `LOCAL_LLM_URL` | LM Studio, vLLM, llama.cpp |
+| (none) | — | Deterministic fallback (no AI, no cost) |
+
+Set the env var and run. No configuration files. No provider lock-in.
+
+Any endpoint that speaks the OpenAI chat completions format (`POST /v1/chat/completions`) works out of the box.
 
 ## Quick Start
 
@@ -295,6 +562,7 @@ npx @neuroverseos/nv-sim serve
 
 | 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 |
@@ -304,21 +572,23 @@ npx @neuroverseos/nv-sim serve
 | `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 run <simulator>` | Connect external simulator to governance |
 | `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
+event → narrative propagation → belief shift → agent action → governance → behavioral analysis → outcome
 ```
 
-Four forces shape every simulation:
+Five 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
+1. **Agent behavior** — traders, voters, regulators, media — each with different risk profiles and strategies
+2. **World rules** — leverage caps, circuit breakers, chokepoints — the constraints that shape what agents can do
+3. **Narrative events** — information shocks that propagate through the system at different speeds
+4. **Perception propagation** — different agents react differently to the same event based on their role and exposure
+5. **Behavioral analysis** — tracks how agents reorganize, producing the before → after evidence that proves rules actually changed the system
 
 This lets you ask compound questions:
 
@@ -333,15 +603,23 @@ That combination produces very different outcomes than any single factor alone.
         ↓
     nv-sim engine           ← world rules + narrative injection + swarm simulation
         ↓
-    nv-sim CLI              ← scenarios, comparison, chaos testing
+    behavioral analysis     ← before→after shift detection, trajectory tracking, cross-run comparison
+        ↓
+    audit trail             ← append-only evidence chain (JSONL)
         ↓
-    control platform        ← interactive browser UI + System Shift card
+    nv-sim CLI              ← scenarios, comparison, chaos testing, governance runtime
+        ↓
+    control platform        ← interactive browser UI + outcome panels
+        ↓
+    AI providers (optional) ← BYOM: Anthropic, OpenAI, Groq, local LLMs, or none
         ↓
     world variants          ← saved experiments as shareable assets
 ```
 
 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.
 
+AI is optional. When present, it's governed — subject to the same rules as any other actor in the system.
+
 ## License
 
 Apache 2.0