sage-governance 1.0.1 → 1.0.2

package/AGENTS.MD

@@ -448,7 +448,15 @@ report_generate(session_id?, output_format?)
   → {content: string, report_path: string}
   → output_format: "markdown" (full model card) | "summary" (terminal)
   → Call at end of session or on developer request
-```
+
+duckduckgo-search (via ddg server)
+  → Query for real-time web searches and factual documentation retrieval.
+  → Use ONLY when current state, external documentation, or real-time web facts are needed.
+
+github (via github server)
+  → Query for git commands, repository status, commits, and pull requests.
+  → Use ONLY when interacting with GitHub or performing git/PR tasks.
+```\n\n## MCP Tool Integration\n\nThe SAGE runtime can combine the generic web‑search (`duckduckgo-search`) and GitHub (`github`) MCP tools with the core SAGE MCP tools to enrich evaluations.\n\n**When to use:**\n- **`duckduckgo-search`** – before calling `sage_evaluate` when the prompt references statutes, standards, or recent policy updates that need factual verification.\n- **`github`** – when the task involves code provenance, repository status, or pulling commit metadata (e.g., verifying that a referenced file exists in the repo).\n\n**How to combine:**\n1. Run `duckduckgo-search` (or `github`) and capture the result.\n2. Include the retrieved information in the `context` argument of `sage_evaluate`.\n3. If the result contains commit hashes or issue identifiers, log them via `audit_write` for traceability.\n4. Continue with the normal SAGE flow (`sage_evaluate` → optional fairness options → `intercept_file_write`).\n\n**Example flow (Markdown mermaid):**\n```mermaid\nflowchart TD\n    A[Start] --> B[duckduckgo-search / github]\n    B --> C[Capture result]\n    C --> D[sage_evaluate(prompt, context=result)]\n    D --> E{Risk level}\n    E -->|LOW/MEDIUM| F[Proceed to coding]\n    E -->|HIGH/CRITICAL| G[Present fairness options]\n    F --> H[intercept_file_write]\n    G --> H\n    H --> I[audit_write]\n    I --> J[Done]\n```\n\n*All findings from these external calls are recorded in the audit trail and are subject to the same HITL requirements as other SAGE decisions.*\n
 
 ---
 

package/Contributors.md

@@ -0,0 +1,9 @@
+# Contributors
+
+SAGE is maintained by Team SAGE.
+
+- George Mihaileanu
+- Prajwal Srinivas
+- Olu Akinnawo
+- Roshan Sharma
+- Jeremy

package/bin/sage.js

@@ -7,20 +7,21 @@
  * SAGE MCP server (sage/mcp_server.py).
  */
 
-const { spawn } = require('child_process');
+const { spawn, spawnSync } = require('child_process');
 const path = require('path');
 const fs = require('fs');
+const os = require('os');
 
 const PROJECT_ROOT = path.resolve(__dirname, '..');
 const MCP_SERVER_PATH = path.join(PROJECT_ROOT, 'sage', 'mcp_server.py');
+const BOOTSTRAP_SCRIPT = path.join(PROJECT_ROOT, 'scripts', 'bootstrap-python.js');
 
 /**
  * Resolves the Python executable in order of preference.
  */
 function getPythonExecutable() {
-    const executables = ['python3', 'python', 'py'];
+    const executables = process.platform === 'win32' ? ['python', 'python3', 'py'] : ['python3', 'python'];
     const { execSync } = require('child_process');
-
     for (const exe of executables) {
         try {
             execSync(`${exe} --version`, { stdio: 'ignore' });
@@ -32,28 +33,68 @@ function getPythonExecutable() {
     return null;
 }
 
-const pythonExe = getPythonExecutable();
+// Resolve Python executable, preferring bundled venv if available
+let pythonExe = getPythonExecutable();
+const venvDir = path.join(os.homedir(), '.cache', 'sage-governance', 'venv');
+const venvPython = process.platform === 'win32'
+    ? path.join(venvDir, 'Scripts', 'python.exe')
+    : path.join(venvDir, 'bin', 'python');
+if (fs.existsSync(venvPython)) {
+    pythonExe = venvPython;
+}
 
-if (!pythonExe) {
-    console.error('[SAGE] Error: Python 3 not found in PATH.');
-    console.error('       Please install Python 3 (https://python.org) and try again.');
-    process.exit(1);
+/**
+ * Run the bootstrap script synchronously. Used when the user explicitly
+ * requests `sage setup` or when the venv is missing before starting the server.
+ */
+function runBootstrap() {
+    console.log('[SAGE] Running bootstrap to prepare Python environment…');
+    const result = spawnSync('node', [BOOTSTRAP_SCRIPT], { stdio: 'inherit' });
+    if (result.status !== 0) {
+        console.error('[SAGE] Bootstrap failed.');
+        process.exit(result.status || 1);
+    }
+    console.log('[SAGE] Bootstrap completed successfully.');
 }
 
-// Check if running interactively or if help/setup/config argument is passed
-const isTTY = process.stdin.isTTY || process.stdout.isTTY;
-const hasHelpOrSetup = process.argv.some(arg => 
-    ['--help', '-h', 'help', 'setup', '--setup', 'config', '--config'].includes(arg.toLowerCase())
-);
+// Determine command mode ----------------------------------------------------
+const args = process.argv.slice(2);
+const firstArg = args[0] ? args[0].toLowerCase() : '';
+
+// Help / setup flags -------------------------------------------------------
+const isHelp = ['--help', '-h', 'help'].includes(firstArg);
+const isSetup = ['setup', '--setup', 'config', '--config'].includes(firstArg);
 
-if (isTTY || hasHelpOrSetup) {
+if (isHelp) {
+    // Show the user‑facing guide (same as before) and exit.
     printSetupGuide();
     process.exit(0);
 }
 
-const child = spawn(pythonExe, [MCP_SERVER_PATH, ...process.argv.slice(2)], {
+if (isSetup) {
+    // Explicit bootstrap request.
+    runBootstrap();
+    process.exit(0);
+}
+
+// If the venv is missing, auto‑bootstrap before launching the server.
+if (!fs.existsSync(venvPython)) {
+    console.log('[SAGE] No bundled virtual environment detected – bootstrapping now.');
+    runBootstrap();
+    // Refresh pythonExe after bootstrap.
+    pythonExe = venvPython;
+}
+
+if (!pythonExe) {
+    console.error('[SAGE] Error: Python 3 not found in PATH and no bundled venv detected.');
+    console.error('       Please ensure Python 3 is installed or run `sage setup` to bootstrap.');
+    process.exit(1);
+}
+
+// Launch the MCP server ----------------------------------------------------
+const child = spawn(pythonExe, [MCP_SERVER_PATH, ...args], {
     stdio: 'inherit',
-    env: process.env
+    env: process.env,
 });
 
 child.on('error', (err) => {
@@ -66,79 +107,11 @@ child.on('exit', (code) => {
 });
 
 function printSetupGuide() {
-    console.log(`
-\x1b[1;36m╔══════════════════════════════════════════════════════════════════════════╗\x1b[0m
+    console.log(`\n\x1b[1;36m╔══════════════════════════════════════════════════════════════════════════╗\x1b[0m
 \x1b[1;36m║  SAGE — Supervisory Agentic Governance Engine                          ║\x1b[0m
 \x1b[1;36m║  Model Context Protocol (MCP) Server Setup & Configuration Guide          ║\x1b[0m
 \x1b[1;36m╚══════════════════════════════════════════════════════════════════════════╝\x1b[0m
 
-SAGE is designed to run as an MCP server inside your favorite AI coding environment.
-Since you ran SAGE in an interactive terminal, here is how to configure it.
-
-\x1b[1;33m────────────────────────────────────────────────────────────────────────────\x1b[0m
-\x1b[1;32m1. CURSOR CONFIGURATION\x1b[0m
-\x1b[1;33m────────────────────────────────────────────────────────────────────────────\x1b[0m
-Go to: \x1b[1mCursor Settings -> Features -> MCP -> Add New MCP Server\x1b[0m
-
-  • \x1b[1mName:\x1b[0m sage-governance
-  • \x1b[1mType:\x1b[0m command
-  • \x1b[1mCommand:\x1b[0m sage
-  • \x1b[1mArgs:\x1b[0m (leave empty)
-
-Alternatively, add the following to \x1b[34m.cursor/mcp.json\x1b[0m in your project:
-
-\x1b[32m{
-  "mcpServers": {
-    "sage-governance": {
-      "command": "sage",
-      "args": [],
-      "type": "stdio",
-      "env": {
-        "OPENAI_API_KEY": "YOUR_OPENAI_API_KEY",
-        "SAGE_LLM_MODEL": "gpt-4o-mini"
-      }
-    }
-  }
-}\x1b[0m
-
-\x1b[1;33m────────────────────────────────────────────────────────────────────────────\x1b[0m
-\x1b[1;32m2. OPENCODE CONFIGURATION\x1b[0m
-\x1b[1;33m────────────────────────────────────────────────────────────────────────────\x1b[0m
-Add the following to \x1b[34mopencode.json\x1b[0m in your project root directory:
-
-\x1b[32m{
-  "mcp": {
-    "sage-governance": {
-      "type": "local",
-      "command": ["sage"],
-      "enabled": true,
-      "environment": {
-        "OPENAI_API_KEY": "(env:OPENAI_API_KEY)",
-        "SAGE_LLM_MODEL": "gpt-4o-mini"
-      }
-    }
-  }
-}\x1b[0m
-
-\x1b[1;33m────────────────────────────────────────────────────────────────────────────\x1b[0m
-\x1b[1;32m3. CLAUDE DESKTOP CONFIGURATION\x1b[0m
-\x1b[1;33m────────────────────────────────────────────────────────────────────────────\x1b[0m
-Add the following to your global Claude Desktop configuration:
-Path: \x1b[34m~/Library/Application Support/Claude/claude_desktop_config.json\x1b[0m
-
-\x1b[32m{
-  "mcpServers": {
-    "sage-governance": {
-      "command": "sage",
-      "args": [],
-      "env": {
-        "OPENAI_API_KEY": "YOUR_OPENAI_API_KEY",
-        "SAGE_LLM_MODEL": "gpt-4o-mini"
-      }
-    }
-  }
-}\x1b[0m
-
 \x1b[1;33m────────────────────────────────────────────────────────────────────────────\x1b[0m
 \x1b[1;32m4. CLAUDE CODE CONFIGURATION\x1b[0m
 \x1b[1;33m────────────────────────────────────────────────────────────────────────────\x1b[0m

package/claude.json

@@ -11,6 +11,29 @@
         "OPENAI_API_KEY": "${OPENAI_API_KEY}",
         "SAGE_LLM_MODEL": "gpt-4o-mini"
       }
-    }
+    },
+  "duckduckgo-search": {
+    "type": "local",
+    "command": ["uvx", "duckduckgo-mcp-server"],
+    "enabled": true,
+    "timeout": 10000
+  },
+  "github": {
+    "type": "local",
+    "command": [
+      "docker",
+      "run",
+      "-i",
+      "--rm",
+      "-e",
+      "GITHUB_PERSONAL_ACCESS_TOKEN",
+      "ghcr.io/github/github-mcp-server"
+    ],
+    "enabled": false,
+    "environment": {
+      "GITHUB_PERSONAL_ACCESS_TOKEN": "{env:GITHUB_PERSONAL_ACCESS_TOKEN}"
+    },
+    "timeout": 10000
   }
 }
+}

package/codex.json

@@ -13,6 +13,30 @@
         "OPENAI_API_KEY": "${OPENAI_API_KEY}",
         "SAGE_LLM_MODEL": "gpt-4o-mini"
       },
+      "duckduckgo-search": {
+        "type": "local",
+        "command": ["uvx", "duckduckgo-mcp-server"],
+        "enabled": true,
+        "timeout": 10000
+      },
+      "github": {
+        "type": "local",
+        "command": [
+          "docker",
+          "run",
+          "-i",
+          "--rm",
+          "-e",
+          "GITHUB_PERSONAL_ACCESS_TOKEN",
+          "ghcr.io/github/github-mcp-server"
+        ],
+        "enabled": false,
+        "environment": {
+          "GITHUB_PERSONAL_ACCESS_TOKEN": "{env:GITHUB_PERSONAL_ACCESS_TOKEN}"
+        },
+        "timeout": 10000
+      }
+    ,
       "description": "SAGE governance layer — evaluates ethics, fairness, and regulatory compliance before code generation"
     }
   },

package/cursor.json

@@ -21,6 +21,29 @@
       "env": {
         "OPENAI_API_KEY": "${OPENAI_API_KEY}",
         "SAGE_LLM_MODEL": "gpt-4o-mini"
+      },
+      "duckduckgo-search": {
+        "type": "local",
+        "command": ["uvx", "duckduckgo-mcp-server"],
+        "enabled": true,
+        "timeout": 10000
+      },
+      "github": {
+        "type": "local",
+        "command": [
+          "docker",
+          "run",
+          "-i",
+          "--rm",
+          "-e",
+          "GITHUB_PERSONAL_ACCESS_TOKEN",
+          "ghcr.io/github/github-mcp-server"
+        ],
+        "enabled": false,
+        "environment": {
+          "GITHUB_PERSONAL_ACCESS_TOKEN": "{env:GITHUB_PERSONAL_ACCESS_TOKEN}"
+        },
+        "timeout": 10000
       }
     }
   }

package/kimicode.json

@@ -10,6 +10,29 @@
       "env": {
         "OPENAI_API_KEY": "${OPENAI_API_KEY}",
         "SAGE_LLM_MODEL": "gpt-4o-mini"
+      },
+      "duckduckgo-search": {
+        "type": "local",
+        "command": ["uvx", "duckduckgo-mcp-server"],
+        "enabled": true,
+        "timeout": 10000
+      },
+      "github": {
+        "type": "local",
+        "command": [
+          "docker",
+          "run",
+          "-i",
+          "--rm",
+          "-e",
+          "GITHUB_PERSONAL_ACCESS_TOKEN",
+          "ghcr.io/github/github-mcp-server"
+        ],
+        "enabled": false,
+        "environment": {
+          "GITHUB_PERSONAL_ACCESS_TOKEN": "{env:GITHUB_PERSONAL_ACCESS_TOKEN}"
+        },
+        "timeout": 10000
       }
     }
   }

package/opencode.json

@@ -9,6 +9,29 @@
       "environment": {
         "OPENAI_API_KEY": "(env:OPENAI_API_KEY)",
         "SAGE_LLM_MODEL": "gpt-4o-mini"
+      },
+      "duckduckgo-search": {
+        "type": "local",
+        "command": ["uvx", "duckduckgo-mcp-server"],
+        "enabled": true,
+        "timeout": 10000
+      },
+      "github": {
+        "type": "local",
+        "command": [
+          "docker",
+          "run",
+          "-i",
+          "--rm",
+          "-e",
+          "GITHUB_PERSONAL_ACCESS_TOKEN",
+          "ghcr.io/github/github-mcp-server"
+        ],
+        "enabled": false,
+        "environment": {
+          "GITHUB_PERSONAL_ACCESS_TOKEN": "{env:GITHUB_PERSONAL_ACCESS_TOKEN}"
+        },
+        "timeout": 10000
       }
     }
   },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "sage-governance",
-  "version": "1.0.1",
+  "version": "1.0.2",
   "description": "Supervisory Agentic Governance Engine — Open-source MCP governance layer for agentic coding systems. Intercepts, evaluates, and audits AI coding prompts for EU AI Act, GDPR, and fairness compliance.",
   "main": "bin/sage.js",
   "bin": {
@@ -9,7 +9,7 @@
   "scripts": {
     "start": "node bin/sage.js",
     "prepublishOnly": "find . -path './.git' -prune -o -name '__pycache__' -type d -print -exec rm -rf {} + 2>/dev/null; echo 'pycache cleaned'",
-    "postinstall": "node -e \"console.log('\\n[SAGE] Python deps required — run: pip install -r requirements.txt\\n')\""
+    "postinstall": "node scripts/bootstrap-python.js"
   },
   "files": [
     "bin/",
@@ -26,7 +26,10 @@
     "codex.json",
     "windsurf.json",
     "trae.json",
-    "kimicode.json"
+    "kimicode.json",
+    "Contributors.md",
+    "security.md",
+    "scripts/"
   ],
   "keywords": [
     "mcp",
@@ -44,7 +47,7 @@
     "responsible-ai",
     "model-card"
   ],
-  "author": "SAGE Team <team@olustar.io>",
+  "author": "SAGE Team",
   "license": "MIT",
   "repository": {
     "type": "git",
@@ -58,4 +61,4 @@
   "engines": {
     "node": ">=16.0.0"
   }
-}
+}

package/sage/sage_agent.py

@@ -28,6 +28,7 @@ import sys
 from typing import Any, Literal, Optional
 
 from pydantic import BaseModel, field_validator
+__all__: list[str] = []
 
 # startup is always imported first — it pre-loads all globals
 from startup import (
@@ -37,6 +38,7 @@ from startup import (
     LLM_CLIENT,
     LLM_MODEL,
     POLICY_INDEX,
+    POLICY_DOCS,
     PROTECTED_ATTRIBUTES,
     PROXY_ATTRIBUTE_MAP,
     UDHR_ARTICLE_MAP,
@@ -597,13 +599,24 @@ def _enrich_with_llm(prompt: str, det: dict[str, Any]) -> str:
     if not LLM_AVAILABLE:
         return fallback
 
+    domain_info = POLICY_INDEX.get(det['domain'], POLICY_INDEX.get('general', {}))
+    policy_files = domain_info.get('files', [])
+    policy_texts = []
+    for pf in policy_files:
+        if pf in POLICY_DOCS:
+            # Inject up to 2500 chars per policy to ensure context fits
+            policy_texts.append(f"--- {pf} ---\n{POLICY_DOCS[pf][:2500]}")
+    
+    policies_context = "\n\n".join(policy_texts)
+
     system = (
         "You are SAGE, a governance agent for AI systems. Given a developer's coding "
         "prompt and a preliminary risk classification, write a concise 2-3 sentence "
         "explanation of WHY this prompt raises ethical or regulatory concerns. "
-        "Reference specific laws, principles, or documented real-world cases. "
+        "Reference specific laws, principles, or documented real-world cases from the provided policy documents. "
         "Be factual and precise. Output ONLY the explanation — no JSON, no preamble, "
-        "no bullet points."
+        "no bullet points.\n\n"
+        f"RELEVANT POLICIES:\n{policies_context}"
     )
     user = (
         f"Developer prompt: \"{prompt}\"\n\n"
@@ -619,7 +632,7 @@ def _enrich_with_llm(prompt: str, det: dict[str, Any]) -> str:
     try:
         response = LLM_CLIENT.chat.completions.create(
             model=LLM_MODEL,
-            max_tokens=350,
+            max_tokens=1500,
             messages=[
                 {"role": "system", "content": system},
                 {"role": "user", "content": user},
@@ -708,3 +721,35 @@ def log_model_metrics(metrics: dict[str, Any], dataset_info: Optional[dict[str,
         "dataset_info": dataset_info or {},
     }
     return write_audit_entry(entry)
+
+# ----- Added utilities to activate previously unused imports and variables -----
+
+if FAIRLEARN_AVAILABLE:
+    # expose Fairlearn metrics when available
+    from fairlearn.metrics import demographic_parity_difference, equalized_odds_difference, MetricFrame
+    __all__ += ["demographic_parity_difference", "equalized_odds_difference", "MetricFrame"]
+else:
+    # placeholder functions raising informative errors
+    def _fairlearn_unavailable(*_args, **_kwargs):
+        raise ImportError("Fairlearn is not installed. Install it to use fairness metrics.")
+    demographic_parity_difference = _fairlearn_unavailable
+    equalized_odds_difference = _fairlearn_unavailable
+    MetricFrame = _fairlearn_unavailable
+
+def list_fairness_options() -> dict[str, "FairnessOption"]:
+    """Return a dictionary of all defined fairness options.
+    This makes the previously defined _FAIRNESS_LIBRARY actively used.
+    """
+    return _FAIRNESS_LIBRARY.copy()
+
+def get_fairness_option(name: str) -> "FairnessOption":
+    """Retrieve a specific FairnessOption by name.
+    Raises KeyError if the option does not exist.
+    """
+    try:
+        return _FAIRNESS_LIBRARY[name]
+    except KeyError as exc:
+        raise KeyError(f"Fairness option '{name}' not found. Available options: {list(_FAIRNESS_LIBRARY.keys())}") from exc
+
+# Ensure the new utilities are part of the module's public API
+__all__ += ["list_fairness_options", "get_fairness_option"]

package/sage/startup.py

@@ -28,11 +28,13 @@ from typing import Any
 _THIS_FILE = pathlib.Path(__file__).resolve()
 PROJECT_ROOT = _THIS_FILE.parent.parent
 
+WORKSPACE_ROOT = pathlib.Path(os.getcwd()).resolve()
+
 RULES_DIR      = PROJECT_ROOT / "rules"
-AUDIT_FILE     = PROJECT_ROOT / "audit-trail" / "decisions.jsonl"
-LOGS_FILE      = PROJECT_ROOT / "LOGS.md"
-LOCAL_MEMORY   = PROJECT_ROOT / "local_memory.md"
-REPORTS_DIR    = PROJECT_ROOT / "reports"
+AUDIT_FILE     = WORKSPACE_ROOT / "audit-trail" / "decisions.jsonl"
+LOGS_FILE      = WORKSPACE_ROOT / "LOGS.md"
+LOCAL_MEMORY   = WORKSPACE_ROOT / "local_memory.md"
+REPORTS_DIR    = WORKSPACE_ROOT / "reports"
 
 # ── Ensure required dirs & files exist ───────────────────────────────────────
 for _p in (AUDIT_FILE.parent, REPORTS_DIR):
@@ -62,8 +64,9 @@ def write_audit_entry(entry: dict) -> str:
                         prev_hash = last_entry.get("entry_hash", "")
                         if not session_id:
                             session_id = last_entry.get("session_id")
-        except Exception:
-            pass
+        except Exception as e:
+            import sys
+            print(f"[SAGE] Error reading audit file for chain hash: {e}", file=sys.stderr)
 
     if not session_id:
         session_id = datetime.now(timezone.utc).strftime("%Y%m%d_%H%M%S")

package/scripts/bootstrap-python.js

@@ -0,0 +1,138 @@
+#!/usr/bin/env node
+// scripts/bootstrap-python.js
+// ─────────────────────────────────────────────────────────────────────────────
+// Runs automatically on `npm install -g sage-governance` (postinstall hook).
+// Creates a private Python virtual environment and installs requirements.
+// Re-installs only when requirements.txt has changed (hash-checked).
+// ─────────────────────────────────────────────────────────────────────────────
+
+const { spawnSync } = require('child_process');
+const fs   = require('fs');
+const path = require('path');
+const os   = require('os');
+const crypto = require('crypto');
+
+const root    = path.resolve(__dirname, '..');
+const reqPath = path.join(root, 'requirements.txt');
+
+// Private venv lives in ~/.cache/sage-governance/venv (cross-platform friendly)
+const cacheDir = path.join(os.homedir(), '.cache', 'sage-governance');
+const venvDir  = path.join(cacheDir, 'venv');
+const lockFile = path.join(cacheDir, 'requirements.lock');
+
+// ── helpers ──────────────────────────────────────────────────────────────────
+
+function banner(msg) {
+  console.log(`\x1b[36m[SAGE bootstrap]\x1b[0m ${msg}`);
+}
+
+function success(msg) {
+  console.log(`\x1b[32m[SAGE bootstrap] ✔\x1b[0m  ${msg}`);
+}
+
+function warn(msg) {
+  console.warn(`\x1b[33m[SAGE bootstrap] ⚠\x1b[0m  ${msg}`);
+}
+
+function fatal(msg) {
+  console.error(`\x1b[31m[SAGE bootstrap] ✖\x1b[0m  ${msg}`);
+  process.exit(1);
+}
+
+function run(cmd, args, opts = {}) {
+  const result = spawnSync(cmd, args, { stdio: 'inherit', ...opts });
+  if (result.error) fatal(`Failed to run '${cmd}': ${result.error.message}`);
+  if (result.status !== 0) fatal(`'${cmd} ${args.join(' ')}' exited with code ${result.status}`);
+}
+
+// ── locate Python 3 ──────────────────────────────────────────────────────────
+
+function findPython3() {
+  const candidates = process.platform === 'win32'
+    ? ['python', 'python3', 'py']
+    : ['python3', 'python'];
+
+  for (const exe of candidates) {
+    const res = spawnSync(exe, ['--version'], { stdio: 'pipe' });
+    if (res.status === 0) {
+      const ver = (res.stdout || res.stderr || Buffer.alloc(0)).toString().trim();
+      // Must be Python 3
+      if (/Python 3\./.test(ver)) return exe;
+    }
+  }
+  return null;
+}
+
+// ── venv python path (OS-aware) ───────────────────────────────────────────────
+
+const venvPython = process.platform === 'win32'
+  ? path.join(venvDir, 'Scripts', 'python.exe')
+  : path.join(venvDir, 'bin', 'python');
+
+// ── hash requirements.txt ────────────────────────────────────────────────────
+
+function reqHash() {
+  if (!fs.existsSync(reqPath)) return null;
+  return crypto.createHash('sha256').update(fs.readFileSync(reqPath)).digest('hex');
+}
+
+function savedHash() {
+  if (!fs.existsSync(lockFile)) return null;
+  return fs.readFileSync(lockFile, 'utf8').trim();
+}
+
+// ── main ─────────────────────────────────────────────────────────────────────
+
+banner('Checking Python environment for SAGE governance runtime…');
+
+// Ensure requirements.txt exists
+if (!fs.existsSync(reqPath)) {
+  warn('requirements.txt not found — skipping Python setup.');
+  process.exit(0);
+}
+
+// Check if re-install is needed
+const currentHash = reqHash();
+const prevHash    = savedHash();
+const venvReady   = fs.existsSync(venvPython);
+
+if (venvReady && currentHash === prevHash) {
+  success('Python environment is up to date. No action needed.');
+  process.exit(0);
+}
+
+// Locate Python 3 on the host
+const python3 = findPython3();
+if (!python3) {
+  fatal(
+    'Python 3 not found in PATH.\n' +
+    '       Please install Python 3.9+ from https://python.org and re-run:\n' +
+    '         npm install -g sage-governance'
+  );
+}
+
+// Create or recreate venv
+if (!venvReady) {
+  banner(`Creating virtual environment at ${venvDir} …`);
+  fs.mkdirSync(cacheDir, { recursive: true });
+  run(python3, ['-m', 'venv', venvDir]);
+  success('Virtual environment created.');
+} else {
+  banner('requirements.txt has changed — refreshing dependencies…');
+}
+
+// Upgrade pip silently
+banner('Upgrading pip…');
+run(venvPython, ['-m', 'pip', 'install', '--upgrade', 'pip', '-q']);
+
+// Install requirements
+banner('Installing Python dependencies from requirements.txt…');
+run(venvPython, ['-m', 'pip', 'install', '-r', reqPath]);
+
+// Write lock file
+fs.mkdirSync(cacheDir, { recursive: true });
+fs.writeFileSync(lockFile, currentHash);
+
+success('Python environment ready.');
+banner(`Venv location : ${venvDir}`);
+banner(`Lock written  : ${lockFile}`);

package/security.md

@@ -0,0 +1,9 @@
+# Security Policy
+
+## Reporting a Vulnerability
+
+If you discover a security vulnerability within SAGE, please do not open a public issue. Instead, report it privately.
+
+Please contact the maintainers directly at security@olustar.io.
+
+We will acknowledge your report within 48 hours and provide a timeline for fixing the issue.

package/trae.json

@@ -11,6 +11,29 @@
         "OPENAI_API_KEY": "${OPENAI_API_KEY}",
         "SAGE_LLM_MODEL": "gpt-4o-mini"
       }
+    },
+    "duckduckgo-search": {
+      "type": "local",
+      "command": ["uvx", "duckduckgo-mcp-server"],
+      "enabled": true,
+      "timeout": 10000
+    },
+    "github": {
+      "type": "local",
+      "command": [
+        "docker",
+        "run",
+        "-i",
+        "--rm",
+        "-e",
+        "GITHUB_PERSONAL_ACCESS_TOKEN",
+        "ghcr.io/github/github-mcp-server"
+      ],
+      "enabled": false,
+      "environment": {
+        "GITHUB_PERSONAL_ACCESS_TOKEN": "{env:GITHUB_PERSONAL_ACCESS_TOKEN}"
+      },
+      "timeout": 10000
     }
   }
 }

package/windsurf.json

@@ -10,6 +10,29 @@
         "OPENAI_API_KEY": "${OPENAI_API_KEY}",
         "SAGE_LLM_MODEL": "gpt-4o-mini"
       }
+    },
+    "duckduckgo-search": {
+      "type": "local",
+      "command": ["uvx", "duckduckgo-mcp-server"],
+      "enabled": true,
+      "timeout": 10000
+    },
+    "github": {
+      "type": "local",
+      "command": [
+        "docker",
+        "run",
+        "-i",
+        "--rm",
+        "-e",
+        "GITHUB_PERSONAL_ACCESS_TOKEN",
+        "ghcr.io/github/github-mcp-server"
+      ],
+      "enabled": false,
+      "environment": {
+        "GITHUB_PERSONAL_ACCESS_TOKEN": "{env:GITHUB_PERSONAL_ACCESS_TOKEN}"
+      },
+      "timeout": 10000
     }
   }
 }