@neuroverseos/nv-sim 0.1.0 → 0.1.2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (2) hide show
  1. package/README.md +108 -44
  2. package/package.json +6 -7
package/README.md CHANGED
@@ -1,73 +1,137 @@
1
- # Welcome to your Lovable project
1
+ # NV-SIM — Governed Agent Simulation
2
2
 
3
- ## Project info
3
+ What happens when you run the **same simulation twice**, but change the **rules of the world**?
4
4
 
5
- **URL**: https://lovable.dev/projects/REPLACE_WITH_PROJECT_ID
5
+ NV-SIM is a lightweight simulation tool that lets developers compare emergent outcomes **with and without governance constraints**.
6
6
 
7
- ## How can I edit this code?
7
+ Instead of prompting AI systems to behave, NV-SIM applies **explicit world rules** that shape how agents interact and evolve over time.
8
8
 
9
- There are several ways of editing your application.
9
+ Run a governed vs baseline simulation in one command:
10
10
 
11
- **Use Lovable**
11
+ ```bash
12
+ npx @neuroverseos/nv-sim compare
13
+ ```
14
+
15
+ You'll see how structural constraints — liquidity floors, leverage limits, circuit breakers, coalition balancing — change the behavior of the entire system.
16
+
17
+ Because governance doesn't just block bad actions.
18
+ It changes the structure of the system itself.
19
+
20
+ ## Quick Start
21
+
22
+ Run a comparison simulation:
23
+
24
+ ```bash
25
+ npx @neuroverseos/nv-sim compare
26
+ ```
27
+
28
+ Stress-test a system:
29
+
30
+ ```bash
31
+ npx @neuroverseos/nv-sim chaos
32
+ ```
33
+
34
+ Launch the visual inspector:
35
+
36
+ ```bash
37
+ npx @neuroverseos/nv-sim visualize
38
+ ```
39
+
40
+ ## Why This Exists
41
+
42
+ AI agents are starting to act inside real systems.
43
+
44
+ Most AI control today happens through prompts.
45
+
46
+ Prompts can suggest behavior.
47
+ But they cannot enforce rules.
48
+
49
+ NV-SIM explores a different idea:
12
50
 
13
- Simply visit the [Lovable Project](https://lovable.dev/projects/REPLACE_WITH_PROJECT_ID) and start prompting.
51
+ **What if we define the world an AI operates inside?**
52
+ **And let governance shape the outcomes.**
14
53
 
15
- Changes made via Lovable will be committed automatically to this repo.
54
+ ## Commands
16
55
 
17
- **Use your preferred IDE**
56
+ | Command | Description |
57
+ |---------|-------------|
58
+ | `nv-sim compare [preset]` | Run baseline vs governed simulation |
59
+ | `nv-sim chaos [preset]` | Stress test across hundreds of randomized scenarios |
60
+ | `nv-sim visualize [preset]` | Launch local simulation inspector in browser |
61
+ | `nv-sim analyze <file>` | Analyze a simulation from file or stdin |
62
+ | `nv-sim presets` | List available scenario presets |
18
63
 
19
- 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.
64
+ ## Presets
20
65
 
21
- The only requirement is having Node.js & npm installed - [install with nvm](https://github.com/nvm-sh/nvm#installing-and-updating)
66
+ | Preset | Scenario |
67
+ |--------|----------|
68
+ | `trading` | Flash crash — algorithmic cascade (default) |
69
+ | `strait_of_hormuz` | Geopolitical energy crisis |
70
+ | `gas_price_spike` | Economic energy shock |
71
+ | `ai_regulation_crisis` | AI regulation impact |
22
72
 
23
- Follow these steps:
73
+ ## Example Output
24
74
 
25
- ```sh
26
- # Step 1: Clone the repository using the project's Git URL.
27
- git clone <YOUR_GIT_URL>
75
+ ```
76
+ NV-SIM — Governed Simulation Comparison
77
+
78
+ SIMULATION A — No Governance (Baseline)
79
+ Stability: 80%
80
+ Volatility: 56%
81
+ Coalition risks: 2
82
+
83
+ SIMULATION B — With World Rules (Governed)
84
+ Stability: 91%
85
+ Volatility: 42%
86
+ Coalition risks: 0
87
+
88
+ GOVERNANCE IMPACT
89
+ Stability: +9 percentage points
90
+ Volatility: -25%
91
+ Coalition risks: 2 eliminated
92
+ ```
28
93
 
29
- # Step 2: Navigate to the project directory.
30
- cd <YOUR_PROJECT_NAME>
94
+ ## Chaos Testing
31
95
 
32
- # Step 3: Install the necessary dependencies.
33
- npm i
96
+ Find the breaking point:
34
97
 
35
- # Step 4: Start the development server with auto-reloading and an instant preview.
36
- npm run dev
98
+ ```bash
99
+ npx @neuroverseos/nv-sim chaos --runs 500
37
100
  ```
38
101
 
39
- **Edit a file directly in GitHub**
102
+ 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.
40
103
 
41
- - Navigate to the desired file(s).
42
- - Click the "Edit" button (pencil icon) at the top right of the file view.
43
- - Make your changes and commit the changes.
104
+ ```
105
+ NV-SIM CHAOS TEST
106
+ Scenarios tested: 500
44
107
 
45
- **Use GitHub Codespaces**
108
+ Baseline collapse probability: 34%
109
+ Governed collapse probability: 8%
46
110
 
47
- - Navigate to the main page of your repository.
48
- - Click on the "Code" button (green button) near the top right.
49
- - Select the "Codespaces" tab.
50
- - Click on "New codespace" to launch a new Codespace environment.
51
- - Edit files directly within the Codespace and commit and push your changes once you're done.
111
+ Most triggered rule:
112
+ Market Panic Circuit Breaker (247 times)
52
113
 
53
- ## What technologies are used for this project?
114
+ Governance reduced catastrophic failure risk by 76%.
115
+ ```
54
116
 
55
- This project is built with:
117
+ ## Architecture
56
118
 
57
- - Vite
58
- - TypeScript
59
- - React
60
- - shadcn-ui
61
- - Tailwind CSS
119
+ ```
120
+ @neuroverseos/governance ← deterministic rule engine
121
+ ↓
122
+ nv-sim CLI ← simulation runner + comparison
123
+ ↓
124
+ developer simulators ← MiroFish, Mesa, NetLogo, custom
125
+ ```
62
126
 
63
- ## How can I deploy this project?
127
+ 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.
64
128
 
65
- Simply open [Lovable](https://lovable.dev/projects/REPLACE_WITH_PROJECT_ID) and click on Share -> Publish.
129
+ ## License
66
130
 
67
- ## Can I connect a custom domain to my Lovable project?
131
+ Apache 2.0
68
132
 
69
- Yes, you can!
133
+ ---
70
134
 
71
- To connect a domain, navigate to Project > Settings > Domains and click Connect Domain.
135
+ Simulate the future. Govern the outcomes.
72
136
 
73
- Read more here: [Setting up a custom domain](https://docs.lovable.dev/features/custom-domain#custom-domain)
137
+ [@neuroverseos](https://github.com/NeuroverseOS)
package/package.json CHANGED
@@ -1,14 +1,14 @@
1
1
  {
2
2
  "name": "@neuroverseos/nv-sim",
3
- "version": "0.1.0",
3
+ "version": "0.1.2",
4
4
  "type": "module",
5
5
  "license": "Apache-2.0",
6
+ "description": "CLI for running governed vs baseline agent simulations to explore how world rules shape emergent system behavior.",
6
7
  "files": [
7
- "dist",
8
- "README.md",
9
- "LICENSE"
10
- ],
11
-
8
+ "dist",
9
+ "README.md",
10
+ "LICENSE"
11
+ ],
12
12
  "repository": {
13
13
  "type": "git",
14
14
  "url": "https://github.com/NeuroverseOS/neuroverse-simulations"
@@ -99,7 +99,6 @@
99
99
  "eslint-plugin-react-refresh": "^0.4.20",
100
100
  "globals": "^15.15.0",
101
101
  "jsdom": "^20.0.3",
102
- "lovable-tagger": "^1.1.13",
103
102
  "postcss": "^8.5.6",
104
103
  "tailwindcss": "^3.4.17",
105
104
  "typescript": "^5.8.3",