sage-governance 1.0.0 → 1.0.2

package/AGENTS.MD

@@ -312,7 +312,7 @@ When the request involves cloud infrastructure, API integrations, or
 deployment configs, the Security Agent also checks:
 
 - Environment variable handling (secrets must never be in code)
-- AI provider credential hygiene (ANTHROPIC_API_KEY, OPENAI_API_KEY, etc.)
+- AI provider credential hygiene (OPENAI_API_KEY, etc.)
 - Database connection string exposure
 - Cloud misconfiguration patterns (public S3 buckets, open ports)
 - GDPR data processor agreement gaps (third-party API calls with PII)
@@ -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/README.md

@@ -84,7 +84,7 @@ Deterministic (no LLM) full-spectrum code scanner.
 
 | Severity | Category | Examples |
 |----------|----------|---------|
-| P0 | Secret exposure | Hardcoded API keys, Anthropic/OpenAI keys, DB passwords |
+| P0 | Secret exposure | Hardcoded API keys, OpenAI keys, DB passwords |
 | P0 | Critical PII | SSN, biometrics, medical data, GDPR Article 9 special categories |
 | P1 | Sensitive PII | Geolocation, passport numbers, date of birth |
 | P1 | Protected attribute direct use | `race`, `sex`, `age` as model features |
@@ -128,64 +128,144 @@ Developer asks coding agent to create classifier.py
 
 ---
 
-## Installation
+## Installation & Quick Start
 
-### Quick Start (recommended)
+### 1. Global Installation (recommended)
+
+Install SAGE globally via npm:
 
 ```bash
 npm install -g sage-governance
 ```
 
-This installs the `sage` CLI command globally. The Node.js wrapper automatically resolves `python3`, `python`, or `py` in that order.
+This installs the `sage` CLI command globally.
+
+### 2. Python Dependencies
 
-### Manual / Development
+Install the required Python packages:
 
 ```bash
-git clone https://github.com/[your-org]/sage-governance
-cd sage-governance
+pip install -r $(npm root -g)/sage-governance/requirements.txt
+```
+
+*(Alternatively, run `pip install mcp openai pydantic fairlearn diffprivlib pandas scikit-learn`)*
+
+---
+
+## Configuring SAGE in AI Clients
+
+Since SAGE is an MCP server, you must add it to the MCP configuration of your AI coding environment. Ensure the environment has access to your `OPENAI_API_KEY`.
 
-# Python dependencies
-pip install mcp anthropic pydantic fairlearn diffprivlib
+### 1. Cursor
 
-# Set your LLM provider key
-export ANTHROPIC_API_KEY=sk-ant-...
+To enable SAGE in Cursor, you can configure it globally or on a per-project basis.
 
-# Optional: override model
-export SAGE_LLM_MODEL=claude-sonnet-4-6
+#### Option A: Project-level Configuration (recommended)
+Create a `.cursor/mcp.json` file in your project root with the following content:
+
+```json
+{
+  "mcpServers": {
+    "sage-governance": {
+      "command": "sage",
+      "args": [],
+      "type": "stdio",
+      "env": {
+        "OPENAI_API_KEY": "YOUR_OPENAI_API_KEY",
+        "SAGE_LLM_MODEL": "gpt-4o-mini"
+      }
+    }
+  }
+}
 ```
 
-### Run SAGE as MCP Server
+#### Option B: Global Settings
+1. Go to **Cursor Settings** -> **Features** -> **MCP**.
+2. Click **+ Add New MCP Server**.
+3. Configure the fields:
+   - **Name**: `sage-governance`
+   - **Type**: `command`
+   - **Command**: `sage`
+   - **Args**: (leave empty)
+4. Click **Save**.
 
-```bash
-# Via CLI (after npm install -g)
-sage
+---
 
-# Directly via Python
-python sage/mcp_server.py
+### 2. OpenCode
+
+Add the following configuration to `opencode.json` in your project root directory:
+
+```json
+{
+  "mcp": {
+    "sage-governance": {
+      "type": "local",
+      "command": ["sage"],
+      "enabled": true,
+      "environment": {
+        "OPENAI_API_KEY": "(env:OPENAI_API_KEY)",
+        "SAGE_LLM_MODEL": "gpt-4o-mini"
+      }
+    }
+  }
+}
 ```
 
 ---
 
-## OpenCode Configuration (`opencode.json`)
+### 3. Claude Desktop
+
+Add SAGE to your global Claude Desktop configuration file:
+- **macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
+- **Windows**: `%APPDATA%\Claude\claude_desktop_config.json`
+
+Add this entry under the `mcpServers` object:
 
 ```json
 {
-  "$schema": "https://opencode.ai/config.schema.json",
   "mcpServers": {
     "sage-governance": {
-      "type": "local",
       "command": "sage",
       "args": [],
       "env": {
-        "ANTHROPIC_API_KEY": "${ANTHROPIC_API_KEY}",
-        "SAGE_LLM_MODEL": "claude-sonnet-4-6"
+        "OPENAI_API_KEY": "YOUR_OPENAI_API_KEY",
+        "SAGE_LLM_MODEL": "gpt-4o-mini"
       }
     }
   }
 }
 ```
 
-For Cline, Claude Code, or Continue, use the equivalent MCP server configuration for stdio transport.
+---
+
+### 4. Claude Code
+
+Run this single command in your terminal to automatically register SAGE with Claude Code:
+
+```bash
+claude mcp add sage-governance sage -- sage
+```
+
+---
+
+### 5. VS Code (Cline / Continue)
+
+Add the server to your Cline/Continue MCP configuration settings JSON:
+
+```json
+{
+  "mcpServers": {
+    "sage-governance": {
+      "command": "sage",
+      "args": [],
+      "env": {
+        "OPENAI_API_KEY": "YOUR_OPENAI_API_KEY",
+        "SAGE_LLM_MODEL": "gpt-4o-mini"
+      }
+    }
+  }
+}
+```
 
 ---
 
@@ -299,7 +379,7 @@ When base rates differ across groups, Demographic Parity, Equalized Odds, and Pr
 | George | Ethics & regulatory policy files, project management |
 | Jeremy | Data science validation, security pipeline, presentation |
 
-**Built with:** FastMCP · Python · Pydantic · Fairlearn · Anthropic API  
+**Built with:** FastMCP · Python · Pydantic · Fairlearn · OpenAI API  
 **Built by:** Oluwagbemisola, Prajwal, Roshan, Jeremy, George
 **License:** MIT
 
@@ -316,4 +396,4 @@ When base rates differ across groups, Demographic Parity, Equalized Odds, and Pr
 - ProPublica (2016). "Machine Bias." COMPAS audit.
 - Ali et al. (2019). "Discrimination through Optimization." ACM FAccT.
 - Beunec Technologies Inc Agentic Annotation Protocol - github.com/beunec
-- Anthropic Model Context Protocol — modelcontextprotocol.io
+- Model Context Protocol — modelcontextprotocol.io

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,17 +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;
+}
+
+/**
+ * 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.');
+}
+
+// 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 (isHelp) {
+    // Show the user‑facing guide (same as before) and exit.
+    printSetupGuide();
+    process.exit(0);
+}
+
+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.');
-    console.error('       Please install Python 3 (https://python.org) and try again.');
+    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);
 }
 
-const child = spawn(pythonExe, [MCP_SERVER_PATH, ...process.argv.slice(2)], {
+// Launch the MCP server ----------------------------------------------------
+const child = spawn(pythonExe, [MCP_SERVER_PATH, ...args], {
     stdio: 'inherit',
-    env: process.env
+    env: process.env,
 });
 
 child.on('error', (err) => {
@@ -53,3 +105,41 @@ child.on('error', (err) => {
 child.on('exit', (code) => {
     process.exit(code);
 });
+
+function printSetupGuide() {
+    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
+
+\x1b[1;33m────────────────────────────────────────────────────────────────────────────\x1b[0m
+\x1b[1;32m4. CLAUDE CODE CONFIGURATION\x1b[0m
+\x1b[1;33m────────────────────────────────────────────────────────────────────────────\x1b[0m
+Run the following command in your terminal:
+
+  \x1b[1;35mclaude mcp add sage-governance sage -- sage\x1b[0m
+
+\x1b[1;33m────────────────────────────────────────────────────────────────────────────\x1b[0m
+\x1b[1;32m5. VS CODE (CLINE / CONTINUE) CONFIGURATION\x1b[0m
+\x1b[1;33m────────────────────────────────────────────────────────────────────────────\x1b[0m
+Add the following to your Cline/Continue MCP settings json file:
+
+\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[1mNOTE:\x1b[0m Make sure you have python dependencies installed:
+  \x1b[35mpip install mcp openai pydantic fairlearn diffprivlib pandas scikit-learn\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

@@ -0,0 +1,39 @@
+{
+  "_note": "Kimi Code MCP configuration. Copy this file or add the sage-governance block to your Kimi Code MCP server settings.",
+  "_docs": "https://kimi.moonshot.cn",
+  "_compatible_with": "Kimi Code",
+  "mcpServers": {
+    "sage-governance": {
+      "command": "sage",
+      "args": [],
+      "type": "stdio",
+      "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

@@ -1,14 +1,37 @@
 {
-  "$schema": "https://opencode.ai/config.schema.json",
-  "model": "anthropic/claude-sonnet-4-6",
-  "mcpServers": {
+  "$schema": "https://opencode.ai/config.json",
+  "model": "openai/gpt-4o-mini",
+  "mcp": {
     "sage-governance": {
       "type": "local",
-      "command": "sage",
-      "args": [],
-      "env": {
-        "OPENAI_API_KEY": "${OPENAI_API_KEY}",
+      "command": ["sage"],
+      "enabled": true,
+      "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.0",
+  "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": {
@@ -8,8 +8,8 @@
   },
   "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')\""
+    "prepublishOnly": "find . -path './.git' -prune -o -name '__pycache__' -type d -print -exec rm -rf {} + 2>/dev/null; echo 'pycache cleaned'",
+    "postinstall": "node scripts/bootstrap-python.js"
   },
   "files": [
     "bin/",
@@ -23,7 +23,13 @@
     "opencode.json",
     "claude.json",
     "cursor.json",
-    "codex.json"
+    "codex.json",
+    "windsurf.json",
+    "trae.json",
+    "kimicode.json",
+    "Contributors.md",
+    "security.md",
+    "scripts/"
   ],
   "keywords": [
     "mcp",
@@ -41,7 +47,7 @@
     "responsible-ai",
     "model-card"
   ],
-  "author": "SAGE Team <team@olustar.io>",
+  "author": "SAGE Team",
   "license": "MIT",
   "repository": {
     "type": "git",
@@ -55,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/security_agent.py

@@ -80,7 +80,7 @@ class SecurityReport:
 # (regex, description, severity)
 _SECRET_PATTERNS: list[tuple[str, str, Severity]] = [
     # AI provider keys
-    (r"sk-ant-[A-Za-z0-9\-_]{40,}", "Anthropic API key hardcoded", "P0"),
+    (r"sk-ant-[A-Za-z0-9\-_]{40,}", "AI Provider API key hardcoded", "P0"),
     (r"sk-[A-Za-z0-9]{48}", "OpenAI API key hardcoded", "P0"),
     (r"AIza[0-9A-Za-z\-_]{35}", "Google API key hardcoded", "P0"),
     # Generic credentials

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

@@ -0,0 +1,39 @@
+{
+  "_note": "Trae MCP configuration. Copy this file or add the sage-governance block to your Trae MCP server settings.",
+  "_docs": "https://trae.sh",
+  "_compatible_with": "Trae",
+  "mcpServers": {
+    "sage-governance": {
+      "command": "sage",
+      "args": [],
+      "type": "stdio",
+      "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/windsurf.json

@@ -0,0 +1,38 @@
+{
+  "_note": "Windsurf MCP configuration. Copy this file or add the sage-governance block to ~/.codeium/windsurf/mcp_config.json",
+  "_docs": "https://codeium.com/windsurf",
+  "_compatible_with": "Windsurf",
+  "mcpServers": {
+    "sage-governance": {
+      "command": "sage",
+      "args": [],
+      "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
+    }
+  }
+}