@neuroverseos/nv-sim 0.1.9 → 0.1.10

package/README.md

@@ -14,9 +14,96 @@ You build a multi-agent system. You run it. You get metrics — loss curves, rew
 
 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.
+Most multi-agent systems let agents do whatever emerges. NeuroVerse lets *you* decide what's allowed — and actually stops the rest.
 
-That's the gap.
+## How It Works (For Humans)
+
+You're a scientist. You have AI agents running experiments for you — testing hypotheses, searching literature, publishing findings. But they do dumb things. They publish claims with no evidence. They cite one paper and call it proof. They pile onto whatever the first agent found.
+
+You need to say: **"Here's what counts as good science in my lab."** And you need the system to actually enforce it.
+
+That's what NeuroVerse does.
+
+### Step 1: You describe what matters
+
+You open the app and fill in plain English:
+
+**What should agents explore?**
+> "Protein mutations that improve binding affinity for SSTR2"
+
+**What should never be published?**
+> "Results based on a single data source. Claims with confidence below 70%."
+
+**What makes a result valuable?**
+> "Multiple independent lines of evidence converging on the same finding."
+
+**How should agents be rewarded or penalized?**
+> IF an agent publishes without peer validation → reduce its influence for 3 rounds
+> IF two agents independently converge on the same finding → boost that finding's priority
+
+**Anything else you want to try?**
+> "Reward agents that challenge the dominant consensus."
+
+### Step 2: The system translates your words into rules
+
+When you click "Build World," your plain English becomes enforceable logic. Before anything runs, you see exactly what will be enforced:
+
+```
+BLOCK       Results with confidence below 70%
+BLOCK       Results from a single source
+PRIORITIZE  Multi-source convergence
+PENALIZE    Publishing without validation → reduce influence, 3 rounds
+REWARD      Independent convergence → boost priority, 5 rounds
+```
+
+You can remove rules, change them, add more. Nothing runs until you say so.
+
+### Step 3: Run the experiment — and see what actually happens
+
+The agents run. Some of them try to publish low-confidence findings. **Those get blocked.** Not flagged. Not warned. Blocked. The UI shows you exactly which rule stopped it and why.
+
+Some agents independently arrive at the same mutation. **Those get boosted.** Their findings move to the top. Not because they gamed the system — because they met the standard you set.
+
+An agent that keeps publishing without validation? **Its influence drops.** It still participates, but its findings carry less weight. For three rounds.
+
+You can see all of this happening:
+- A green badge means rules are being enforced
+- A yellow badge means you're just previewing (the engine isn't connected)
+- Every blocked action shows the exact rule and condition
+- Every reward and penalty shows which agent, what happened, and for how long
+
+### Step 4: Change one rule. Run again.
+
+Remove the confidence threshold. What breaks? Do agents start publishing garbage? Does it matter?
+
+Add a rule that penalizes groupthink. Do agents start exploring more diverse hypotheses?
+
+**This is the experiment.** Not the simulation — the rules themselves. You're not testing what agents do. You're testing which rules produce the science you actually want.
+
+### What's different about this
+
+Other agent systems give you emergent behavior and hope for the best.
+
+NeuroVerse gives you a control surface:
+
+| You say | The system does |
+|---|---|
+| *"Block single-source claims"* | Blocks them. Every time. With evidence. |
+| *"Penalize publishing without review"* | Reduces the agent's influence. For exactly as long as you specified. |
+| *"Reward independent convergence"* | Boosts the finding's priority. The agents don't even know — it just rises. |
+
+The agents don't need to understand the rules. They just operate within them.
+
+### Running it
+
+```bash
+npm install
+npm run dev:full
+```
+
+Opens in your browser. Everything runs on your machine. No cloud. No accounts. No cost.
+
+> **If the governance engine isn't running, nothing is enforced.** The UI always tells you: green = real, yellow = preview.
 
 ## What NV-SIM Gives You That Nothing Else Does
 
@@ -214,7 +301,7 @@ NV-SIM ships with two complete governed worlds. These are templates — starting
 
 ### `social_simulation` — Multi-Agent Social Simulation
 
-For anyone running agent-based social simulations (MiroFish, OASIS, or custom). Governs the dynamics that break realism regardless of topic.
+For anyone running agent-based social simulations. Governs the dynamics that break realism regardless of topic.
 
 | State Variable | What It Controls |
 |---|---|