nucleus-mcp 1.0.7 → 1.2.0

package/src/mcp_server_nucleus/runtime/capabilities/web_ops.py

@@ -1,94 +0,0 @@
-from typing import List, Dict, Any
-from .base import Capability
-
-class WebOps(Capability):
-    @property
-    def name(self) -> str:
-        return "web_ops"
-
-    @property
-    def description(self) -> str:
-        return "Tools for browsing the web (simulated via requests/search)."
-
-    def get_tools(self) -> List[Dict[str, Any]]:
-        return [
-            {
-                "name": "web_search",
-                "description": "Search Google for a query.",
-                "parameters": {
-                    "type": "object", 
-                    "properties": {
-                        "query": {"type": "string"},
-                        "num_results": {"type": "integer", "default": 5}
-                    },
-                    "required": ["query"]
-                }
-            },
-            {
-                "name": "web_read_page",
-                "description": "Read text content from a URL.",
-                "parameters": {
-                    "type": "object", 
-                    "properties": {
-                        "url": {"type": "string"}
-                    },
-                    "required": ["url"]
-                }
-            }
-        ]
-
-    def execute_tool(self, tool_name: str, args: Dict) -> str:
-        """Execute web operations."""
-        if tool_name == "web_search":
-            query = args['query']
-            num_results = args.get('num_results', 5)
-            try:
-                from duckduckgo_search import DDGS
-                with DDGS() as ddgs:
-                    results = list(ddgs.text(query, max_results=num_results))
-                
-                if not results:
-                    return f"No results found for '{query}'."
-                
-                formatted = []
-                for r in results:
-                    formatted.append(f"- [{r['title']}]({r['href']})\n  {r['body']}")
-                
-                return "\n\n".join(formatted)
-            except ImportError:
-                return "Error: duckduckgo-search not installed. Please install it to use this feature."
-            except Exception as e:
-                return f"Search error: {e}"
-
-        elif tool_name == "web_read_page":
-            url = args['url']
-            try:
-                import urllib.request
-                from bs4 import BeautifulSoup
-                
-                headers = {'User-Agent': 'Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/120.0.0.0 Safari/537.36'}
-                req = urllib.request.Request(url, headers=headers)
-                
-                with urllib.request.urlopen(req, timeout=10) as response:
-                    html_content = response.read().decode('utf-8')
-                
-                soup = BeautifulSoup(html_content, 'html.parser')
-                
-                # Remove script and style elements
-                for script in soup(['script', 'style', 'nav', 'footer', 'header']):
-                    script.decompose()
-                
-                text = soup.get_text()
-                
-                # Clean up whitespace
-                lines = (line.strip() for line in text.splitlines())
-                chunks = (phrase.strip() for line in lines for phrase in line.split("  "))
-                text = '\n'.join(chunk for chunk in chunks if chunk)
-                
-                return f"URL: {url}\n\n{text[:8000]}..." # Truncate to 8k chars
-            except ImportError:
-                 return "Error: beautifulsoup4 not installed. Please install it to use this feature."
-            except Exception as e:
-                return f"Error reading {url}: {e}"
-                
-        return f"Tool {tool_name} not found in WebOps."

package/src/mcp_server_nucleus/runtime/common.py

@@ -1,134 +0,0 @@
-"""
-Nucleus Runtime - Common Utilities
-==================================
-Shared utilities and constants for the Nucleus runtime.
-"""
-
-import os
-import json
-import logging
-import sys
-from pathlib import Path
-from datetime import datetime, timezone
-from typing import Dict, Any, Optional
-
-# ============================================================
-# STRUCTURED LOGGING SYSTEM (AG-010)
-# ============================================================
-
-class JSONFormatter(logging.Formatter):
-    """Formats log records as JSON objects for machine readability."""
-    def format(self, record):
-        log_entry = {
-            "timestamp": datetime.now(timezone.utc).isoformat().replace("+00:00", "Z"),
-            "level": record.levelname,
-            "logger": record.name,
-            "message": record.getMessage(),
-            "module": record.module,
-            "line": record.lineno
-        }
-        if record.exc_info:
-            log_entry["exception"] = self.formatException(record.exc_info)
-        return json.dumps(log_entry)
-
-def setup_nucleus_logging(name: str = "nucleus", level: int = logging.INFO):
-    """Setup structured logging for a component."""
-    logger = logging.getLogger(name)
-    logger.setLevel(level)
-    
-    # Avoid duplicate handlers
-    if not logger.handlers:
-        handler = logging.StreamHandler(sys.stdout)
-        
-        # Use JSON if specified via env
-        if os.environ.get("NUCLEUS_LOG_JSON", "false").lower() == "true":
-            handler.setFormatter(JSONFormatter())
-        else:
-            handler.setFormatter(logging.Formatter(
-                '%(asctime)s - %(name)s - %(levelname)s - %(message)s'
-            ))
-        
-        logger.addHandler(handler)
-    return logger
-
-# Common logger
-logger = setup_nucleus_logging()
-
-def get_brain_path() -> Path:
-    """Get the brain path from environment variable (read dynamically for testing)."""
-    brain_path = os.environ.get("NUCLEAR_BRAIN_PATH")
-    if not brain_path:
-        raise ValueError("NUCLEAR_BRAIN_PATH environment variable not set")
-    path = Path(brain_path)
-    if not path.exists():
-         raise ValueError(f"Brain path does not exist: {brain_path}")
-    return path
-
-def make_response(success: bool, data=None, error=None, error_code=None):
-    """Standardized API response formatter.
-    
-    Args:
-        success: Whether the operation succeeded
-        data: Successful payload (dict, list, string)
-        error: Error message if failed
-        error_code: Optional short code for error (e.g. ERR_NOT_FOUND)
-    
-    Returns:
-        JSON string matching Nucleus Standard Response Schema
-    """
-    return json.dumps({
-        "success": success,
-        "data": data,
-        "error": error,
-        "error_code": error_code,
-        "timestamp": datetime.now(timezone.utc).isoformat().replace("+00:00", "Z")
-    }, indent=2)
-
-def _get_state(path: Optional[str] = None) -> Dict:
-    """Core logic for getting state."""
-    try:
-        brain = get_brain_path()
-        state_path = brain / "ledger" / "state.json"
-        
-        if not state_path.exists():
-            return {}
-            
-        from .sync_ops import sync_lock
-        with sync_lock(brain, timeout=2):
-            with open(state_path, "r") as f:
-                state = json.load(f)
-            
-        if path:
-            keys = path.split('.')
-            val = state
-            for k in keys:
-                val = val.get(k, {})
-            return val
-            
-        return state
-    except Exception as e:
-        logger.error(f"Error reading state: {e}")
-        return {}
-
-def _update_state(updates: Dict[str, Any]) -> str:
-    """Core logic for updating state."""
-    try:
-        brain = get_brain_path()
-        state_path = brain / "ledger" / "state.json"
-        state_path.parent.mkdir(parents=True, exist_ok=True)
-        
-        from .sync_ops import sync_lock
-        with sync_lock(brain, timeout=5):
-            current_state = {}
-            if state_path.exists():
-                with open(state_path, "r") as f:
-                    current_state = json.load(f)
-            
-            current_state.update(updates)
-            
-            with open(state_path, "w") as f:
-                json.dump(current_state, f, indent=2)
-            
-        return "State updated successfully"
-    except Exception as e:
-        return f"Error updating state: {str(e)}"

package/src/mcp_server_nucleus/runtime/context_manager.py

@@ -1,342 +0,0 @@
-"""
-v0.6.0 DSoR: Context Manager
-
-Provides stateless hashing of the current world-state for decision provenance.
-This module enables verification of state before/after agent turns to ensure
-integrity and detect unauthorized mutations.
-
-Part of the Decision System of Record (DSoR) initiative.
-"""
-
-import hashlib
-import json
-import os
-from datetime import datetime, timezone
-from pathlib import Path
-from typing import Dict, Any, List, Optional, Tuple
-from dataclasses import dataclass, field, asdict
-
-
-def get_brain_path() -> Path:
-    """Get the brain path from environment."""
-    return Path(os.getenv("NUCLEAR_BRAIN_PATH", "/Users/lokeshgarg/ai-mvp-backend/.brain"))
-
-
-@dataclass
-class ContextSnapshot:
-    """
-    Immutable snapshot of world-state at a point in time.
-    Used for before/after comparisons in agent turns.
-    """
-    snapshot_id: str
-    timestamp: str
-    state_hash: str
-    component_hashes: Dict[str, str] = field(default_factory=dict)
-    metadata: Dict[str, Any] = field(default_factory=dict)
-    
-    def to_dict(self) -> Dict[str, Any]:
-        return asdict(self)
-    
-    @classmethod
-    def from_dict(cls, data: Dict[str, Any]) -> "ContextSnapshot":
-        return cls(**data)
-
-
-@dataclass
-class StateVerificationResult:
-    """Result of comparing two context snapshots."""
-    is_valid: bool
-    before_hash: str
-    after_hash: str
-    mutations_detected: List[str] = field(default_factory=list)
-    drift_components: Dict[str, Tuple[str, str]] = field(default_factory=dict)
-    verification_timestamp: str = field(default_factory=lambda: datetime.now(timezone.utc).isoformat())
-
-
-class ContextManager:
-    """
-    v0.6.0 DSoR: Manages context state hashing and verification.
-    
-    Provides:
-    1. Stateless hashing of current world-state
-    2. Before/after verification for agent turns
-    3. Drift detection for unauthorized mutations
-    """
-    
-    def __init__(self, brain_path: Optional[Path] = None):
-        self.brain_path = brain_path or get_brain_path()
-        self._snapshot_counter = 0
-    
-    def _hash_file(self, file_path: Path) -> Optional[str]:
-        """Compute SHA-256 hash of a file's contents."""
-        try:
-            if file_path.exists() and file_path.is_file():
-                content = file_path.read_bytes()
-                return hashlib.sha256(content).hexdigest()[:16]
-        except Exception:
-            pass
-        return None
-    
-    def _hash_dict(self, data: Dict[str, Any]) -> str:
-        """Compute deterministic hash of a dictionary."""
-        serialized = json.dumps(data, sort_keys=True, default=str)
-        return hashlib.sha256(serialized.encode()).hexdigest()[:16]
-    
-    def _collect_ledger_state(self) -> Dict[str, Any]:
-        """Collect state from the ledger directory."""
-        ledger_path = self.brain_path / "ledger"
-        state = {
-            "engrams_hash": None,
-            "events_hash": None,
-            "tasks_hash": None,
-            "decisions_hash": None,
-        }
-        
-        if ledger_path.exists():
-            # Hash key ledger files
-            engrams_file = ledger_path / "engrams.jsonl"
-            events_file = ledger_path / "events.jsonl"
-            tasks_file = ledger_path / "tasks.json"
-            decisions_dir = ledger_path / "decisions"
-            
-            state["engrams_hash"] = self._hash_file(engrams_file)
-            state["events_hash"] = self._hash_file(events_file)
-            state["tasks_hash"] = self._hash_file(tasks_file)
-            
-            if decisions_dir.exists():
-                decisions_file = decisions_dir / "decisions.jsonl"
-                state["decisions_hash"] = self._hash_file(decisions_file)
-        
-        return state
-    
-    def _collect_slots_state(self) -> Dict[str, Any]:
-        """Collect state from the slots directory."""
-        slots_path = self.brain_path / "slots"
-        state = {"registry_hash": None, "slot_count": 0}
-        
-        if slots_path.exists():
-            registry_file = slots_path / "registry.json"
-            state["registry_hash"] = self._hash_file(registry_file)
-            state["slot_count"] = len(list(slots_path.glob("slot_*.json")))
-        
-        return state
-    
-    def _collect_mounts_state(self) -> Dict[str, Any]:
-        """Collect state from mounted servers."""
-        mounts_file = self.brain_path / "ledger" / "mounts.json"
-        state = {"mounts_hash": None, "mount_count": 0}
-        
-        if mounts_file.exists():
-            state["mounts_hash"] = self._hash_file(mounts_file)
-            try:
-                with open(mounts_file) as f:
-                    mounts = json.load(f)
-                    state["mount_count"] = len(mounts.get("servers", []))
-            except Exception:
-                pass
-        
-        return state
-    
-    def compute_world_state_hash(self, include_docs: bool = False, 
-                                  recent_events: Optional[List[str]] = None) -> Tuple[str, Dict[str, str]]:
-        """
-        Compute a comprehensive hash of the current world-state.
-        
-        Args:
-            include_docs: Whether to include document checksums
-            recent_events: Optional list of recent event strings to include
-            
-        Returns:
-            Tuple of (overall_hash, component_hashes)
-        """
-        components = {}
-        
-        # 1. Ledger state
-        ledger_state = self._collect_ledger_state()
-        components["ledger"] = self._hash_dict(ledger_state)
-        
-        # 2. Slots state
-        slots_state = self._collect_slots_state()
-        components["slots"] = self._hash_dict(slots_state)
-        
-        # 3. Mounts state
-        mounts_state = self._collect_mounts_state()
-        components["mounts"] = self._hash_dict(mounts_state)
-        
-        # 4. Recent events (if provided)
-        if recent_events:
-            events_blob = json.dumps(recent_events[-10:], sort_keys=True)
-            components["recent_events"] = hashlib.sha256(events_blob.encode()).hexdigest()[:16]
-        
-        # 5. Optional: Include docs checksums
-        if include_docs:
-            docs_path = self.brain_path / "artifacts"
-            if docs_path.exists():
-                doc_hashes = []
-                for md_file in docs_path.rglob("*.md"):
-                    h = self._hash_file(md_file)
-                    if h:
-                        doc_hashes.append(f"{md_file.name}:{h}")
-                if doc_hashes:
-                    components["docs"] = hashlib.sha256(
-                        "|".join(sorted(doc_hashes)).encode()
-                    ).hexdigest()[:16]
-        
-        # Compute overall hash from components
-        overall = self._hash_dict(components)
-        
-        return overall, components
-    
-    def take_snapshot(self, include_docs: bool = False,
-                      recent_events: Optional[List[str]] = None,
-                      metadata: Optional[Dict[str, Any]] = None) -> ContextSnapshot:
-        """
-        Take an immutable snapshot of the current world-state.
-        
-        Args:
-            include_docs: Whether to include document checksums
-            recent_events: Optional list of recent event strings
-            metadata: Optional metadata to attach to snapshot
-            
-        Returns:
-            ContextSnapshot instance
-        """
-        self._snapshot_counter += 1
-        state_hash, component_hashes = self.compute_world_state_hash(
-            include_docs=include_docs,
-            recent_events=recent_events
-        )
-        
-        snapshot = ContextSnapshot(
-            snapshot_id=f"snap-{self._snapshot_counter:06d}",
-            timestamp=datetime.now(timezone.utc).isoformat(),
-            state_hash=state_hash,
-            component_hashes=component_hashes,
-            metadata=metadata or {}
-        )
-        
-        return snapshot
-    
-    def verify_state_integrity(self, before: ContextSnapshot, 
-                                after: ContextSnapshot,
-                                allowed_mutations: Optional[List[str]] = None) -> StateVerificationResult:
-        """
-        Verify state integrity by comparing before/after snapshots.
-        
-        Args:
-            before: Snapshot taken before agent turn
-            after: Snapshot taken after agent turn
-            allowed_mutations: List of component names that are allowed to change
-            
-        Returns:
-            StateVerificationResult with drift analysis
-        """
-        allowed = set(allowed_mutations or [])
-        mutations = []
-        drift_components = {}
-        
-        # Compare component hashes
-        all_components = set(before.component_hashes.keys()) | set(after.component_hashes.keys())
-        
-        for component in all_components:
-            before_hash = before.component_hashes.get(component)
-            after_hash = after.component_hashes.get(component)
-            
-            if before_hash != after_hash:
-                mutations.append(component)
-                drift_components[component] = (before_hash or "none", after_hash or "none")
-        
-        # Check if mutations are within allowed set
-        unauthorized_mutations = [m for m in mutations if m not in allowed]
-        is_valid = len(unauthorized_mutations) == 0
-        
-        return StateVerificationResult(
-            is_valid=is_valid,
-            before_hash=before.state_hash,
-            after_hash=after.state_hash,
-            mutations_detected=mutations,
-            drift_components=drift_components
-        )
-    
-    def persist_snapshot(self, snapshot: ContextSnapshot) -> Path:
-        """
-        Persist a snapshot to the ledger for audit purposes.
-        
-        Args:
-            snapshot: The snapshot to persist
-            
-        Returns:
-            Path to the persisted snapshot file
-        """
-        snapshots_dir = self.brain_path / "ledger" / "snapshots"
-        snapshots_dir.mkdir(parents=True, exist_ok=True)
-        
-        snapshot_file = snapshots_dir / f"{snapshot.snapshot_id}.json"
-        snapshot_file.write_text(json.dumps(snapshot.to_dict(), indent=2))
-        
-        return snapshot_file
-    
-    def load_snapshot(self, snapshot_id: str) -> Optional[ContextSnapshot]:
-        """
-        Load a previously persisted snapshot.
-        
-        Args:
-            snapshot_id: The ID of the snapshot to load
-            
-        Returns:
-            ContextSnapshot if found, None otherwise
-        """
-        snapshots_dir = self.brain_path / "ledger" / "snapshots"
-        snapshot_file = snapshots_dir / f"{snapshot_id}.json"
-        
-        if snapshot_file.exists():
-            try:
-                data = json.loads(snapshot_file.read_text())
-                return ContextSnapshot.from_dict(data)
-            except Exception:
-                pass
-        
-        return None
-
-
-# Singleton instance for convenience
-_context_manager: Optional[ContextManager] = None
-
-
-def get_context_manager() -> ContextManager:
-    """Get or create the singleton ContextManager instance."""
-    global _context_manager
-    if _context_manager is None:
-        _context_manager = ContextManager()
-    return _context_manager
-
-
-def compute_context_hash(recent_events: Optional[List[str]] = None) -> str:
-    """
-    Convenience function to compute the current context hash.
-    
-    Args:
-        recent_events: Optional list of recent event strings
-        
-    Returns:
-        SHA-256 hash (truncated to 16 chars) of current world-state
-    """
-    cm = get_context_manager()
-    state_hash, _ = cm.compute_world_state_hash(recent_events=recent_events)
-    return state_hash
-
-
-def verify_turn_integrity(before_hash: str, after_hash: str,
-                          allowed_drift: float = 0.0) -> bool:
-    """
-    Simple verification that state hasn't drifted unexpectedly.
-    
-    Args:
-        before_hash: Hash from before agent turn
-        after_hash: Hash from after agent turn
-        allowed_drift: Currently unused, reserved for fuzzy matching
-        
-    Returns:
-        True if hashes match (no drift), False otherwise
-    """
-    return before_hash == after_hash

package/src/mcp_server_nucleus/runtime/context_rules.json

@@ -1,86 +0,0 @@
-[
-    {
-        "keywords": [
-            "deploy",
-            "cloud run",
-            "build",
-            "ship",
-            "production"
-        ],
-        "inject": [
-            "cloudbuild.yaml",
-            "docs/infra/DEPLOYMENT.md",
-            "docs/infra/RELEASE_PROTOCOL.md"
-        ],
-        "description": "Deployment and Infrastructure Context"
-    },
-    {
-        "keywords": [
-            "database",
-            "schema",
-            "sql",
-            "postgres",
-            "migration"
-        ],
-        "inject": [
-            "docs/architecture/DATABASE_SCHEMA.md",
-            "alembic.ini"
-        ],
-        "description": "Database and Storage Context"
-    },
-    {
-        "keywords": [
-            "brain",
-            "memory",
-            "context",
-            "recall",
-            "store"
-        ],
-        "inject": [
-            "mcp-server-nucleus/src/mcp_server_nucleus/runtime/factory.py",
-            "docs/architecture/BRAIN_DESIGN.md"
-        ],
-        "description": "Nucleus Brain Architecture Context"
-    },
-    {
-        "keywords": [
-            "api",
-            "endpoint",
-            "route",
-            "http",
-            "rest"
-        ],
-        "inject": [
-            "docs/api/OPENAPI_SPEC.md",
-            "app.py"
-        ],
-        "description": "API Surface Area Context"
-    },
-    {
-        "keywords": [
-            "ui",
-            "frontend",
-            "component",
-            "react",
-            "tailwind"
-        ],
-        "inject": [
-            "tools/nucleus-hud/tailwind.config.ts",
-            "tools/nucleus-hud/app/globals.css"
-        ],
-        "description": "Frontend Design System Context"
-    },
-    {
-        "keywords": [
-            "test",
-            "verify",
-            "qa",
-            "check"
-        ],
-        "inject": [
-            "tests/README.md",
-            "NUCLEUS_GRAND_VERIFICATION_PLAN.md"
-        ],
-        "description": "Testing and Verification Context"
-    }
-]