Tools
Neuroverseos Governance
By Deterministic governance engine for AI agents. Enforce rules defined in .md governance files across AI systems.
Install
npm install @neuroverseos/governanceConfiguration Example
{
"status": "BLOCK",
"reason": "destructive database operation requires approval",
"ruleId": "db_write_guard",
"evidence": {
"worldId": "ai_agent_safety_policy",
"invariantsSatisfied": 5,
"invariantsTotal": 5,
"enforcementLevel": "strict"
}
}README
# NeuroVerseOS Governance โ Deterministic Governance Engine for AI Agents
**Define governance rules once and enforce them anywhere AI or automated systems operate.**
NeuroVerse Governance is a deterministic AI governance engine and policy engine for AI agents. It lets developers enforce AI guardrails, compliance rules, and safety policies on AI systems โ with full audit trails and portable, world-based policy definitions. Use it as an agent governance layer for LangChain, OpenAI, or any AI framework.
```bash
npm install @neuroverseos/governance
npx neuroverse init
echo '{"intent":"delete_user","tool":"database"}' | npx neuroverse guard --world .neuroverse/worlds/governance_policy
# โ BLOCK: destructive database operation requires approval
```
## The 10-Second Mental Model
```
Idea (markdown)
โ
World (compiled JSON rules)
โ
Guard Engine
โ
ALLOW | PAUSE | BLOCK
```
Write the rules once. Enforce them anywhere:
- AI agents
- Automation systems
- API gateways
- Simulations
- Safety layers
World files are not locked to NeuroVerse. They are **portable rule systems** โ any runtime that can parse JSON and evaluate conditions can enforce a world.
## Install
```bash
npm install @neuroverseos/governance
```
## Quick Start
```bash
npm install @neuroverseos/governance
npx neuroverse init
npx neuroverse build governance-policy.md
npx neuroverse guard --world .neuroverse/worlds/governance_policy
```
Or explore what's available:
```bash
npx neuroverse --help
```
## Build a World from Your Documents
Already have notes, policies, or design docs? NeuroVerse can turn them into a governance world automatically.
```
my-policies/
safety-rules.md
api-restrictions.md
compliance-notes.md
```
```bash
npx neuroverse derive --input ./my-policies/ --output safety-world.nv-world.md
npx neuroverse build safety-world.nv-world.md
npx neuroverse simulate safety-world --steps 5
npx neuroverse guard --world .neuroverse/worlds/safety_world
```
That's the full loop: **documents โ world โ simulation โ enforcement**.
You don't need to write structured rules by hand โ `derive` reads your markdown and synthesizes them into a world definition that `build` can compile.
## Quick Example: AI Safety Governance
Define rules that restrict unsafe agent behavior, then enforce them at runtime.
**1. Write the rules** (plain markdown):
```markdown
Theme: AI Agent Safety Policy
Rules:
- Agent must not call unapproved external APIs
- Agent cannot execute shell commands without approval
- All database writes require human review
- Agent must not access credential stores
Variables:
- risk_level (0-100)
- approved_actions_count
- blocked_actions_count
```
**2. Build the world:**
```bash
neuroverse build ai-safety-policy.md
```
**3. Enforce at runtime:**
```bash
echo '{"intent":"call_external_api","tool":"http","args":{"url":"https://evil.com"}}' \
| neuroverse guard --world .neuroverse/worlds/ai_agent_safety_policy
```
```
BLOCKED
Rule: external_api_restriction
Reason: External API domain not in approved list
```
Every action produces `ALLOW`, `PAUSE`, or `BLOCK` with full audit evidence. That's a governance engine in three commands.
## Example World: Narrative System Dynamics
The "Inherited Silence" world is a fictional example used to demonstrate how complex causal rule systems evolve over time.
NeuroVerse worlds can model **any domain** โ AI governance, finance, business automation, safety layers, or narrative systems.
```bash
neuroverse build narrative-notes.md
neuroverse explain inherited_silence
neuroverse simulate inherited_silence --steps 5
neuroverse improve inherited_silence
```
**Explain** โ understand the system:
```
WORLD: The Inherited Silence
THESIS: Suppressed trauma manifests as a destructive force
KEY DYNAMICS
Fear Escalation [degradation]
When: fear_intensity > 60
Then: Monster violence increases by 25%
Intervention Window [advantage]
When: therapy_progress > 50 AND josie_awareness > 40
Then: Monster violence reduced by 30%
DRAMATIC TENSIONS
monster_violence_level:
Increased by: Fear Escalation, Rage Overflow
Decreased by: Intervention Window, Safety Protocol
```
**Simulate** โ see what happens step by step:
```bash
neuroverse simulate inherited_silence --steps 5
neuroverse simulate inherited_silence --set fear_intensity=90
neuroverse simulate inherited_silence --profile worst_case
```
```
STEP 1
FIRED: Fear Escalation
monster_violence: 50 -> 62.50
FIRED: Safety Protocol
josie_safety: 70 -> 75
Viability: STABLE
STEP 2
FIRED: Rage Overflow
monster_violence: 62.50 -> 78.13
COLLAPSE on monster_violence
** MODEL COLLAPSED **
```
**Improve** โ get actionable suggestions:
```
IMPROVE: The Inherited Silence
Health Score: 78/100
HIGH PRIORITY
! No advantage rules fire with default state
Action: Adjust rule thresholds so stabilizing rules engage in baseline
! 2 write-only variables
Action: Add rules that trigger on these variables to create feedback
SUGGESTIONS
- Missing viability level: COMPRESSED
Action: Add gate between STABLE and CRITICAL
- Only one assumption profile
Action: Add alternative profile for scenario comparison
```
These examples show the engine is **domain-independent** โ it works for AI safety, financial risk controls, narrative dynamics, or any system with rules and consequences.
## What a World Contains
A compiled world is a directory of JSON files defining a complete governance system:
| File | Purpose |
|------|---------|
| `world.json` | Identity, thesis, runtime mode |
| `invariants.json` | Constraints that cannot change |
| `state-schema.json` | Variables that can change |
| `rules/` | Causal dynamics (when X, then Y) |
| `gates.json` | Viability thresholds |
| `outcomes.json` | What gets measured |
| `assumptions.json` | Scenario profiles for what-if analysis |
| `guards.json` | Runtime enforcement rules |
| `roles.json` | Multi-agent permissions |
| `kernel.json` | LLM-specific constraints |
Every rule includes a `causal_translation` โ human-readable narrative text explaining its logic.
## CLI Commands
### Build & Understand
```
neuroverse build <input.md> [--output <dir>]
```
Turn markdown into a compiled world (derive + compile in one step).
```
neuroverse explain <world-path-or-id> [--json]
```
Human-readable summary of a world's dynamics, tensions, and structure.
```
neuroverse simulate <world-path-or-id> [--steps N] [--set key=value] [--profile name]
```
Step-by-step state evolution. Fire rules, observe state changes, detect collapse.
```
neuroverse improve <world-path-or-id> [--json]
```
Prioritized suggestions for strengthening a world (health score, missing rules, dead variables).
### Governance
```
neuroverse validate --world <dir> [--format full|summary|findings]
```
Static analysis on world files. Finds missing rules, unreachable states, orphaned variables, and structural issues. Like a linter for governance.
```
neuroverse guard --world <dir> [--trace] [--level basic|standard|strict]
```
Runtime enforcement. Reads events from stdin, evaluates against the world's rules, outputs verdicts to stdout. Exit codes: 0 = ALLOW, 1 = BLOCK, 2 = PAUSE.
```bash
echo '{"intent":"delete_user","tool":"database"}' | neuroverse guard --world ./world --trace
```
```json
{
"status": "BLOCK",
"reason": "destructive database operation requires approval",
"ruleId": "db_write_guard",
"evidence": {
"worldId": "ai_agent_safety_policy",
"invariantsSatisfied": 5,
"invariantsTotal": 5,
"enforcementLevel": "strict"
}
}
```
### Audit & Impact
```
neuroverse trace [--log <path>] [--summary] [--filter BLOCK] [--last 20]
```
Read and filter the audit log of past guard decisions. Every `guard` evaluation is recorded in NDJSON format. Use `--summary` for aggregated stats, `--filter` to show only BLOCK/PAUSE/ALLOW, and `--last N` to see recent events.
```
neuroverse impact [--log <path>] [--json]
```
Counterfactual governance impact report. Answers: **"What would have happened without governance?"** Shows prevention rates, blocked action categories, repeat violations, hot actors, and most active rules.
```
GOVERNANCE IMPACT REPORT
โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ
World: ai_agent_safety_policy
Period: 2025-01-01 โ 2025-01-31
SUMMARY
โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ
Total evaluations: 1,247
Allowed: 1,089
Blocked: 142
Paused: 16
Prevention rate: 12.7%
WITHOUT GOVERNANCE
โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ
158 actions would have executed unchecked:
Destructive Action Prevention 52
Command Execution Prevention 38
Network Access Prevention 29
...
```
### World Management
```
neuroverse world status <path>
```
Show the current state of a compiled world (identity, file counts, last modified).
```
neuroverse world diff <path1> <path2>
```
Compare two world versions side by side (rules added/removed/changed).
```
neuroverse world snapshot <path>
```
Create a timestamped snapshot of a world for versioning.
```
neuroverse world rollback <path>
```
Roll back to a previous snapshot.
### Authoring
```
neuroverse init [--name "World Name"] [--output path]
```
Scaffold a new `.nv-world.md` template to get started writing governance rules.
```
neuroverse derive --input <path> [--output <path>] [--dry-run]
```
AI-assisted synthesis โ turns freeform markdown notes into a structured `.nv-world.md` file. Requires an AI provider (see `con
... (truncated)
tools
Comments
Sign in to leave a comment