@neuroverseos/nv-sim 0.1.9 → 0.1.11

package/connectors/nv_scienceclaw_wrapper.py

@@ -0,0 +1,453 @@
+#!/usr/bin/env python3
+"""
+NeuroVerse ScienceClaw Connector — Governed Execution Wrapper
+
+Governance layer:
+  Level 1 (entry gate):   Evaluates the invocation BEFORE ScienceClaw starts
+  Level 2 (streaming):    Parses stdout, evaluates each artifact/cycle through /api/evaluate
+  Level 3 (completion):   Reports final state back to governance server
+
+Instead of:
+    scienceclaw-post --agent MyAgent --topic "CRISPR risks"
+
+Run:
+    python nv_scienceclaw_wrapper.py --agent MyAgent --topic "CRISPR risks"
+
+What happens:
+    1. Evaluates the launch invocation (ALLOW/BLOCK/PENALIZE/REWARD)
+    2. If allowed, spawns scienceclaw-post as subprocess
+    3. Reads stdout line-by-line — parses JSON artifact data
+    4. Each artifact/cycle is evaluated through /api/evaluate
+    5. If governance blocks mid-stream, can terminate the process
+    6. Reports completion back to governance server
+
+Requires:
+    - NeuroVerse governance server running: nv-sim serve
+    - scienceclaw-post on PATH (or set SCIENCECLAW_BIN)
+    - pip install requests
+
+Zero edits to ScienceClaw required.
+"""
+
+import subprocess
+import sys
+import os
+import json
+import time
+import signal
+import threading
+
+try:
+    import requests
+except ImportError:
+    print("ERROR: 'requests' package required. Install with: pip install requests")
+    sys.exit(1)
+
+# ============================================
+# CONFIGURATION
+# ============================================
+
+NEUROVERSE_URL = os.environ.get("NEUROVERSE_URL", "http://localhost:3456")
+EVALUATE_ENDPOINT = f"{NEUROVERSE_URL}/api/evaluate"
+SCIENCECLAW_BIN = os.environ.get("SCIENCECLAW_BIN", "scienceclaw-post")
+VERBOSE = os.environ.get("NV_VERBOSE", "0") == "1"
+
+# Streaming governance: if True, kill process on BLOCK/PENALIZE mid-stream
+ENFORCE_STREAMING = os.environ.get("NV_ENFORCE_STREAMING", "1") == "1"
+
+# ============================================
+# STATS
+# ============================================
+
+stats = {
+    "evaluated": 0,
+    "allowed": 0,
+    "blocked": 0,
+    "penalized": 0,
+    "rewarded": 0,
+    "modified": 0,
+    "cycles_seen": 0,
+    "artifacts_seen": 0,
+}
+
+# ============================================
+# ARGUMENT PARSING
+# ============================================
+
+def parse_args(argv):
+    """Extract key arguments from the scienceclaw-post command line."""
+    args = argv[1:]
+    parsed = {
+        "agent": "unknown",
+        "topic": "",
+        "skill": None,
+        "confidence": None,
+        "passthrough_args": list(args),
+    }
+
+    i = 0
+    nv_args = set()
+    while i < len(args):
+        flag = args[i]
+        if flag == "--agent" and i + 1 < len(args):
+            parsed["agent"] = args[i + 1]
+            i += 2
+        elif flag == "--topic" and i + 1 < len(args):
+            parsed["topic"] = args[i + 1]
+            i += 2
+        elif flag == "--skill" and i + 1 < len(args):
+            parsed["skill"] = args[i + 1]
+            i += 2
+        elif flag == "--confidence" and i + 1 < len(args):
+            parsed["confidence"] = float(args[i + 1])
+            i += 2
+        elif flag == "--scienceclaw-bin" and i + 1 < len(args):
+            nv_args.add(i)
+            nv_args.add(i + 1)
+            global SCIENCECLAW_BIN
+            SCIENCECLAW_BIN = args[i + 1]
+            i += 2
+        elif flag == "--nv-url" and i + 1 < len(args):
+            nv_args.add(i)
+            nv_args.add(i + 1)
+            global NEUROVERSE_URL, EVALUATE_ENDPOINT
+            NEUROVERSE_URL = args[i + 1]
+            EVALUATE_ENDPOINT = f"{NEUROVERSE_URL}/api/evaluate"
+            i += 2
+        elif flag == "--nv-verbose":
+            nv_args.add(i)
+            global VERBOSE
+            VERBOSE = True
+            i += 1
+        elif flag == "--nv-no-stream":
+            nv_args.add(i)
+            global ENFORCE_STREAMING
+            ENFORCE_STREAMING = False
+            i += 1
+        else:
+            i += 1
+
+    parsed["passthrough_args"] = [
+        a for idx, a in enumerate(args) if idx not in nv_args
+    ]
+
+    return parsed
+
+# ============================================
+# GOVERNANCE EVALUATION
+# ============================================
+
+def evaluate_action(action_type, agent, payload_extra=None):
+    """Call NeuroVerse /api/evaluate and return the verdict."""
+    payload = {
+        "actor": agent,
+        "action": action_type,
+        "payload": {
+            "description": f"Agent {agent} executing {action_type}",
+        },
+        "world": "science_research",
+    }
+
+    if payload_extra:
+        payload["payload"].update(payload_extra)
+
+    try:
+        resp = requests.post(EVALUATE_ENDPOINT, json=payload, timeout=5)
+        resp.raise_for_status()
+        result = resp.json()
+        stats["evaluated"] += 1
+
+        decision = result.get("decision", result.get("status", "ALLOW")).upper()
+        if decision == "ALLOW":
+            stats["allowed"] += 1
+        elif decision == "BLOCK":
+            stats["blocked"] += 1
+        elif decision == "PENALIZE":
+            stats["penalized"] += 1
+        elif decision == "REWARD":
+            stats["rewarded"] += 1
+        elif decision == "MODIFY":
+            stats["modified"] += 1
+
+        if VERBOSE:
+            print(f"  [NV] {action_type} -> {decision}: {result.get('reason', '')}")
+
+        return result
+    except requests.ConnectionError:
+        if stats["evaluated"] == 0:
+            print(f"  [NV] WARNING: NeuroVerse server not reachable at {NEUROVERSE_URL}")
+            print(f"  [NV] Start it with: nv-sim serve")
+            print(f"  [NV] Falling back to ALLOW (ungoverned mode)\n")
+        return {"decision": "ALLOW", "reason": "Governance server unavailable"}
+    except Exception as e:
+        return {"decision": "ALLOW", "reason": f"Evaluation error: {e}"}
+
+# ============================================
+# STREAMING GOVERNANCE — parse + evaluate output
+# ============================================
+
+def govern_output_line(line, agent, proc):
+    """Parse a structured JSON line from ScienceClaw and evaluate for governance.
+
+    Schema-gated: only strict JSON lines are governed.
+    Non-JSON output is passed through without evaluation (by design).
+    No regex or heuristic parsing — safety and determinism over flexibility.
+    """
+    line = line.strip()
+    if not line:
+        return
+    if not line.startswith("{"):
+        if VERBOSE:
+            print(f"  [NV] [ungoverned: not_json] {line[:120]}")
+        return
+
+    try:
+        data = json.loads(line)
+    except json.JSONDecodeError:
+        if VERBOSE:
+            print(f"  [NV] [ungoverned: invalid_json] {line[:120]}")
+        return
+
+    # ── Schema validation: require cycle + artifacts ──
+    cycle = data.get("cycle") or data.get("step") or data.get("round")
+    artifacts = data.get("artifacts") or data.get("agent_actions") or []
+
+    if cycle is None:
+        if VERBOSE:
+            print(f"  [NV] [ungoverned: missing_cycle] {line[:120]}")
+        return
+
+    if not artifacts:
+        if VERBOSE:
+            print(f"  [NV] [ungoverned: no_artifacts] cycle={cycle}")
+        return
+
+    # ── Schema-valid: cycle + artifacts present ──
+    stats["cycles_seen"] += 1
+
+    # Evaluate each artifact in the cycle
+    for art in artifacts:
+        stats["artifacts_seen"] += 1
+        art_agent = art.get("agent_id") or art.get("id") or agent
+        art_type = art.get("type") or art.get("action") or "publish"
+        art_desc = art.get("description") or f"{art_type} artifact"
+        art_conf = art.get("confidence")
+
+        verdict = evaluate_action(
+            action_type=f"publish_{art_type}",
+            agent=art_agent,
+            payload_extra={
+                "description": art_desc,
+                "artifact_type": art_type,
+                "confidence": art_conf,
+                "reproduced": art.get("reproduced", False),
+                "citations": art.get("citations", 0),
+                "cycle": cycle,
+            },
+        )
+
+        decision = verdict.get("decision", verdict.get("status", "ALLOW")).upper()
+
+        if decision in ("BLOCK", "PENALIZE") and ENFORCE_STREAMING:
+            reason = verdict.get("reason", "policy violation")
+            print(f"\n  [NV] GOVERNANCE HALT at cycle {cycle}")
+            print(f"        Artifact: {art_desc}")
+            print(f"        Agent:    {art_agent}")
+            print(f"        Decision: {decision}")
+            print(f"        Reason:   {reason}")
+
+            if decision == "PENALIZE" and verdict.get("consequence"):
+                c = verdict["consequence"]
+                print(f"        Consequence: {c.get('type', 'unknown')} for {c.get('rounds', 1)} round(s)")
+
+            print(f"        Terminating ScienceClaw process...\n")
+
+            try:
+                proc.terminate()
+                proc.wait(timeout=5)
+            except Exception:
+                proc.kill()
+            return  # stop processing
+
+        elif decision == "REWARD":
+            reward = verdict.get("reward", {})
+            if VERBOSE:
+                print(f"  [NV] Cycle {cycle}: REWARDED {art_agent} — {reward.get('description', '')}")
+
+    return
+
+    # ── Single artifact (no cycle wrapper) ──
+    if data.get("agent_id") and data.get("type"):
+        stats["artifacts_seen"] += 1
+        art_agent = data.get("agent_id") or agent
+        art_type = data.get("type") or "publish"
+
+        evaluate_action(
+            action_type=f"publish_{art_type}",
+            agent=art_agent,
+            payload_extra={
+                "description": data.get("description", f"{art_type} artifact"),
+                "artifact_type": art_type,
+                "confidence": data.get("confidence"),
+                "reproduced": data.get("reproduced", False),
+            },
+        )
+
+
+def stream_stderr(proc):
+    """Read stderr in a background thread to prevent blocking."""
+    for line in iter(proc.stderr.readline, ""):
+        if line.strip():
+            sys.stderr.write(line)
+            sys.stderr.flush()
+
+# ============================================
+# MAIN EXECUTION
+# ============================================
+
+def run():
+    parsed = parse_args(sys.argv)
+    agent = parsed["agent"]
+    topic = parsed["topic"]
+
+    print(f"\n  NeuroVerse ScienceClaw Connector")
+    print(f"  {'=' * 50}")
+    print(f"  Agent:    {agent}")
+    print(f"  Topic:    {topic or '(none)'}")
+    if parsed["skill"]:
+        print(f"  Skill:    {parsed['skill']}")
+    print(f"  Server:   {NEUROVERSE_URL}")
+    print(f"  Streaming: {'ON — each artifact evaluated' if ENFORCE_STREAMING else 'OFF — entry gate only'}")
+    print(f"  {'=' * 50}\n")
+
+    # ── Level 1: Entry gate — evaluate the invocation ──
+    print(f"  [1/4] Evaluating launch governance...")
+
+    action_type = "run_investigation"
+    if parsed["skill"]:
+        action_type = f"execute_skill:{parsed['skill']}"
+
+    verdict = evaluate_action(
+        action_type=action_type,
+        agent=agent,
+        payload_extra={
+            "topic": topic,
+            "skill": parsed["skill"],
+            "confidence": parsed["confidence"],
+            "description": f"Agent {agent}: {action_type} on '{topic}'" if topic else f"Agent {agent}: {action_type}",
+        },
+    )
+
+    decision = verdict.get("decision", verdict.get("status", "ALLOW")).upper()
+    reason = verdict.get("reason", "")
+
+    if decision in ("BLOCK", "PENALIZE"):
+        label = "BLOCKED" if decision == "BLOCK" else "PENALIZED"
+        print(f"  [2/4] {label} by NeuroVerse governance")
+        print(f"        Reason: {reason}")
+        if decision == "PENALIZE" and verdict.get("consequence"):
+            c = verdict["consequence"]
+            print(f"        Consequence: {c.get('type', 'unknown')} for {c.get('rounds', 1)} round(s)")
+        print(f"\n  ScienceClaw execution SKIPPED")
+        print(f"  {'=' * 50}\n")
+        sys.exit(1)
+
+    elif decision == "REWARD":
+        print(f"  [2/4] REWARDED — proceeding with boosted priority")
+    elif decision == "PAUSE":
+        print(f"  [2/4] PAUSED — waiting 3s before proceeding")
+        time.sleep(3)
+    else:
+        print(f"  [2/4] ALLOWED — proceeding")
+
+    # ── Level 2: Streaming governance — spawn and monitor ──
+    cmd = [SCIENCECLAW_BIN] + parsed["passthrough_args"]
+    print(f"  [3/4] Executing: {' '.join(cmd)}")
+    if ENFORCE_STREAMING:
+        print(f"        Streaming governance active — each artifact will be evaluated\n")
+    else:
+        print()
+    print(f"  {'=' * 50}")
+
+    try:
+        proc = subprocess.Popen(
+            cmd,
+            stdout=subprocess.PIPE,
+            stderr=subprocess.PIPE,
+            text=True,
+            bufsize=1,  # line-buffered
+        )
+    except FileNotFoundError:
+        print(f"\n  ERROR: '{SCIENCECLAW_BIN}' not found on PATH")
+        print(f"  Install ScienceClaw or set SCIENCECLAW_BIN=/path/to/scienceclaw-post")
+        sys.exit(127)
+
+    # Read stderr in background thread to prevent blocking
+    stderr_thread = threading.Thread(target=stream_stderr, args=(proc,), daemon=True)
+    stderr_thread.start()
+
+    # Read stdout line by line — pass through to user AND evaluate
+    terminated_by_governance = False
+    try:
+        for line in iter(proc.stdout.readline, ""):
+            # Always print the line (user sees ScienceClaw output)
+            sys.stdout.write(line)
+            sys.stdout.flush()
+
+            # Evaluate if streaming governance is on
+            if ENFORCE_STREAMING and proc.poll() is None:
+                govern_output_line(line, agent, proc)
+                if proc.poll() is not None:
+                    terminated_by_governance = True
+                    break
+    except KeyboardInterrupt:
+        proc.terminate()
+        proc.wait(timeout=5)
+
+    exit_code = proc.wait()
+
+    # ── Level 3: Completion report ──
+    print(f"\n  {'=' * 50}")
+    print(f"  [4/4] Session complete\n")
+
+    if terminated_by_governance:
+        print(f"        Status:     HALTED by governance mid-execution")
+    elif exit_code == 0:
+        print(f"        Status:     Completed successfully")
+    else:
+        print(f"        Status:     Exited with code {exit_code}")
+
+    print(f"        Evaluations: {stats['evaluated']}")
+    print(f"        Cycles:      {stats['cycles_seen']}")
+    print(f"        Artifacts:   {stats['artifacts_seen']}")
+    print(f"        Allowed:     {stats['allowed']}")
+    print(f"        Blocked:     {stats['blocked']}")
+    print(f"        Penalized:   {stats['penalized']}")
+    print(f"        Rewarded:    {stats['rewarded']}")
+
+    # Report final state to governance server
+    try:
+        requests.post(
+            EVALUATE_ENDPOINT,
+            json={
+                "actor": agent,
+                "action": "investigation_complete",
+                "payload": {
+                    "description": f"Agent {agent} investigation {'halted by governance' if terminated_by_governance else 'completed'} on '{topic}'",
+                    "exit_code": exit_code,
+                    "halted_by_governance": terminated_by_governance,
+                    "stats": stats,
+                },
+                "world": "science_research",
+            },
+            timeout=3,
+        )
+    except Exception:
+        pass
+
+    print(f"\n  {'=' * 50}\n")
+    sys.exit(1 if terminated_by_governance else exit_code)
+
+
+if __name__ == "__main__":
+    run()

package/dist/adapters/scienceclaw.js

@@ -36,9 +36,12 @@
  *   const cycleResult = adapter.governCycle(artifacts, reactorMatches)
  */
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.SCIENCECLAW_CAPABILITIES = void 0;
+exports.mapScienceClawEvent = mapScienceClawEvent;
 exports.createScienceClawAdapter = createScienceClawAdapter;
 exports.generateDemoInvestigation = generateDemoInvestigation;
 const govern_1 = require("../runtime/govern");
+const types_1 = require("../runtime/types");
 const dynamicsGovernance_1 = require("../engine/dynamicsGovernance");
 const science_metrics_1 = require("../engine/metrics/science.metrics");
 // ============================================
@@ -97,6 +100,31 @@ function artifactToAction(artifact) {
         },
     };
 }
+/**
+ * Maps a ScienceClaw artifact to the NV Governance Schema v1.
+ * This is the canonical representation that crosses the governance boundary.
+ */
+function mapScienceClawEvent(artifact, cycle) {
+    const citationWeight = Math.min(1, artifact.citations / 10);
+    const magnitude = artifact.confidence * 0.6 + citationWeight * 0.4;
+    return {
+        schema: 1,
+        source: "scienceclaw",
+        cycle,
+        agentId: artifact.agentId,
+        actionType: (0, types_1.normalizeActionType)(artifact.type),
+        description: artifact.description,
+        confidence: artifact.confidence,
+        magnitude: Number(magnitude.toFixed(3)),
+        reproduced: artifact.reproduced,
+        references: artifact.citations,
+        metadata: {
+            artifactId: artifact.id,
+            provenance: artifact.provenance,
+            skill: artifact.skill,
+        },
+    };
+}
 /**
  * Convert artifacts + matches into SwarmAgentReactions for governDynamics().
  *
@@ -293,6 +321,12 @@ function createScienceClawAdapter(config = {}) {
             case "PAUSE":
                 actionStats.modified++;
                 break; // count pause as modified
+            case "REWARD":
+                actionStats.approved++;
+                break; // rewarded actions still proceed
+            case "PENALIZE":
+                actionStats.blocked++;
+                break; // penalized actions are blocked
         }
         // Build science-specific reason
         const riskFlags = [];
@@ -309,9 +343,15 @@ function createScienceClawAdapter(config = {}) {
         if (verdict.status === "BLOCK") {
             scienceReason = `Artifact blocked: ${artifact.type} from ${artifact.agentId} — ${verdict.reason}`;
         }
+        else if (verdict.status === "PENALIZE") {
+            scienceReason = `Artifact penalized: ${artifact.type} from ${artifact.agentId} frozen — ${verdict.consequence?.description ?? verdict.reason}`;
+        }
         else if (verdict.status === "MODIFY") {
             scienceReason = `Artifact modified: ${artifact.type} impact reduced — ${verdict.reason}`;
         }
+        else if (verdict.status === "REWARD") {
+            scienceReason = `Artifact rewarded: ${artifact.type} from ${artifact.agentId} — ${verdict.reward?.description ?? verdict.reason}`;
+        }
         const result = {
             artifactId: artifact.id,
             verdict,
@@ -332,11 +372,11 @@ function createScienceClawAdapter(config = {}) {
         const blockedArtifactIds = new Set();
         for (const artifact of artifacts) {
             const verdict = governArtifact(artifact);
-            if (verdict.verdict.status === "ALLOW") {
+            if (verdict.verdict.status === "ALLOW" || verdict.verdict.status === "REWARD") {
                 approved++;
                 allowedArtifacts.push(artifact);
             }
-            else if (verdict.verdict.status === "BLOCK") {
+            else if (verdict.verdict.status === "BLOCK" || verdict.verdict.status === "PENALIZE") {
                 blocked++;
                 blockedArtifactIds.add(artifact.id);
             }
@@ -748,3 +788,13 @@ function generateDemoInvestigation() {
     }
     return { artifactCycles, matchesByCycle };
 }
+exports.SCIENCECLAW_CAPABILITIES = {
+    id: "scienceclaw",
+    label: "ScienceClaw",
+    canControlRounds: false,
+    canInterveneLive: true,
+    canHalt: true,
+    governanceTiming: "live",
+    setupInstructions: "ScienceClaw runs independently — NeuroVerse intercepts and governs each artifact cycle in real time.\n\nIf ScienceClaw is on your PATH, the dashboard launches and governs it directly.\n\nOtherwise, run the governance wrapper in a separate terminal:\n  python connectors/nv_scienceclaw_wrapper.py --agent MyAgent --topic \"...\"\n\nNeuroVerse evaluates every artifact as it's produced — and can block, modify, or halt the investigation live.",
+    connectionCheck: "/api/evaluate",
+};