@neuroverseos/nv-sim 0.1.4 → 0.1.7

package/README.md

@@ -2,7 +2,7 @@
 
 **Change the rules. See why the system changed.**
 
-NV-SIM doesn't predict outcomes — it shows how they change when you change the rules.
+NV-SIM doesn't predict outcomes — it shows how systems 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.
 
@@ -33,6 +33,38 @@ Rule changed
 
 That's the loop. Every time.
 
+## This Is a Runtime, Not Just a Simulator
+
+NV-SIM runs in two modes:
+
+- **Simulate** — explore how systems behave under different rules
+- **Act** — govern real agents, real workflows, and real decisions
+
+The interface is the same. The difference is where the behavior comes from.
+
+```
+Simulate → internal swarm engine
+Act      → external systems (agents, APIs, frameworks like OpenClaw)
+```
+
+In both cases:
+
+```
+Action → Governance → Decision → Behavioral Shift → System Outcome
+```
+
+You're not switching tools. You're switching the source of reality.
+
+That's what makes this a runtime.
+
+The same world file can:
+
+- simulate a crisis
+- govern a live system
+- produce comparable outcomes across both
+
+Design the rules once. Run them anywhere.
+
 ## The Demo Moment
 
 **Before:**
@@ -61,9 +93,61 @@ system: unstable
 
 You didn't predict this. You caused it — by changing one rule — and watched the system tell you why.
 
+## Behavioral Analysis — The Proof Layer
+
+Blocking actions is easy. The hard part is proving what changed and why. NV-SIM doesn't just count blocked actions — it tracks how agents actually reorganized.
+
+Every simulation produces behavioral evidence:
+
+- **Action classification** — each agent action is categorized as aggressive, defensive, cautious, cooperative, opportunistic, or neutral
+- **Agent trajectories** — traces each agent's behavior across rounds, showing when and how they shifted
+- **Behavioral shifts** — detects the moment agents change strategy in response to governance
+- **Cross-run comparison** — same agents under different rules, measured side by side
+
+```
+BEHAVIORAL ANALYSIS
+
+  Action Distribution (governed):
+    aggressive:    12%  (was 67%)
+    cooperative:   41%  (was 8%)
+    cautious:      31%  (was 11%)
+    defensive:     16%  (was 14%)
+
+  Shifts Detected:
+    → 80% of aggressive agents shifted 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: [BLOCK] → Round 4: cautious → Round 5: cooperative
+```
+
+The governance isn't the insight. 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.
+
+## Audit Trail — Full Evidence Chain
+
+Every governance decision is recorded in an append-only audit log. Every rule firing, every agent action, every verdict — persistent and queryable.
+
+```
+AUDIT TRAIL (session: 2026-03-18T14:22:00)
+
+  [GOVERNANCE] agent_hedge_fund_1 → panic_sell → BLOCK
+    rule: no_panic_selling (invariant)
+    evidence: action matches blocked pattern during high volatility
+
+  [AGENT] agent_hedge_fund_1 → hold
+    adapted: true (shifted from aggressive to defensive)
+
+  [BEHAVIORAL_SHIFT] agent_hedge_fund_1
+    before: aggressive | after: cautious
+    trigger: governance block at round 3
+```
+
+Stored as JSONL — one JSON object per line, human-readable, pipeable through `jq`. No cloud, no deletion. Complete evidence for governance accountability.
+
 ## Worlds — Where the Power Lives
 
-Integration is one line. Worlds are where you define what your system allows.
+Integration is one line. The world file controls everything.
 
 The `world` you pass to `/api/evaluate` determines how actions are judged. Change the world, change the outcome.
 
@@ -192,7 +276,35 @@ 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
+## Governance Runtime — Run It For Your Own System
+
+```bash
+npx @neuroverseos/nv-sim serve
+```
+
+This starts a local governance server. Any simulator, agent framework, or application can POST actions and get governance decisions back.
+
+```
+  Endpoint: http://localhost:3456/api/evaluate
+  Method:   POST
+  Contract: { actor, action, payload?, state?, world? }
+  Response: { decision: ALLOW|BLOCK|MODIFY, reason, evidence }
+```
+
+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 governance |
+| `GET /api/session` | Current session stats |
+| `GET /api/session/report` | Full governance report |
+| `POST /api/session/reset` | Reset session state |
+| `POST /api/session/save` | Save session as experiment |
+| `GET /api/events` | SSE stream of governance events |
+
+### Works With Anything
 
 If your system has actions, you can govern it. One API call.
 
@@ -266,6 +378,44 @@ Most systems generate behavior. This one shapes it.
 
 See [INTEGRATION.md](./INTEGRATION.md) for the full API contract and decision types.
 
+## 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
 
 ```bash
@@ -291,10 +441,104 @@ npx @neuroverseos/nv-sim chaos --runs 500
 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.
+```
+
+### 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.
+
 ## 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 |
@@ -304,21 +548,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
+5. **Behavioral analysis** — tracks how agents reorganize under governance, producing the evidence that rules actually changed the system
 
 This lets you ask compound questions:
 
@@ -333,15 +579,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     ← shift detection, trajectory tracking, cross-run comparison
+        ↓
+    audit trail             ← append-only evidence chain (JSONL)
+        ↓
+    nv-sim CLI              ← scenarios, comparison, chaos testing, governance runtime
         ↓
     control platform        ← interactive browser UI + System Shift card
         ↓
+    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