agent-os-kernel 1.1.0__py3-none-any.whl → 1.2.0__py3-none-any.whl

modules/cmvk/src/cross_model_verification_kernel/tools/visualizer.py

@@ -0,0 +1,312 @@
+#!/usr/bin/env python3
+"""
+Visualizer: Replay JSON traces as an adversarial debate.
+
+This tool reads JSON trace files from the TraceLogger and displays them
+as a human-readable script showing the debate between:
+- The Builder (GPT-4o): Generates solutions
+- The Prosecutor (Gemini): Finds flaws
+- The Kernel: Makes final decisions
+
+Usage:
+    python -m src.tools.visualizer <trace_file.json>
+    python -m src.tools.visualizer logs/traces/cmvk_prob_001_*.json
+    python -m src.tools.visualizer --list
+    python -m src.tools.visualizer --latest
+"""
+import argparse
+import glob
+import json
+import sys
+import time
+from pathlib import Path
+from typing import Any
+
+
+# ANSI color codes for terminal output
+class Colors:
+    HEADER = "\033[95m"
+    OKBLUE = "\033[94m"
+    OKCYAN = "\033[96m"
+    OKGREEN = "\033[92m"
+    WARNING = "\033[93m"
+    FAIL = "\033[91m"
+    ENDC = "\033[0m"
+    BOLD = "\033[1m"
+    UNDERLINE = "\033[4m"
+
+    # Role-specific colors
+    BUILDER = "\033[94m"  # Blue for GPT-4o (Builder)
+    PROSECUTOR = "\033[91m"  # Red for Gemini (Prosecutor)
+    KERNEL = "\033[93m"  # Yellow for Kernel (Arbiter)
+    SUCCESS = "\033[92m"  # Green for success
+    SYSTEM = "\033[96m"  # Cyan for system messages
+
+
+def print_separator(char="=", length=80):
+    """Print a separator line."""
+    print(char * length)
+
+
+def print_header(text: str):
+    """Print a formatted header."""
+    print_separator()
+    print(f"{Colors.BOLD}{Colors.HEADER}{text.center(80)}{Colors.ENDC}")
+    print_separator()
+
+
+def print_speaker(role: str, message: str, color: str):
+    """Print a message from a specific role/speaker."""
+    print(f"\n{color}{Colors.BOLD}>>> {role}:{Colors.ENDC} {color}{message}{Colors.ENDC}")
+
+
+def print_code_block(code: str, indent: int = 4):
+    """Print a code block with indentation."""
+    lines = code.strip().split("\n")
+    for line in lines:
+        print(f"{' ' * indent}{Colors.OKCYAN}{line}{Colors.ENDC}")
+
+
+def format_strategy(strategy: str) -> str:
+    """Format strategy name for display."""
+    if not strategy or strategy == "unknown":
+        return "Unknown Strategy"
+    return strategy.replace("_", " ").title()
+
+
+def replay_trace(trace_data: dict[str, Any], speed: float = 0.5, show_code: bool = True):
+    """
+    Replay a trace as an adversarial debate.
+
+    Args:
+        trace_data: Parsed JSON trace data
+        speed: Delay in seconds between messages (0 = instant)
+        show_code: Whether to show full code blocks
+    """
+    # Print header
+    print_header("🎭 ADVERSARIAL KERNEL REPLAY 🎭")
+
+    # Print problem statement
+    print(f"\n{Colors.BOLD}📋 Problem:{Colors.ENDC}")
+    print(f"    {trace_data['input_query']}")
+
+    # Print metadata
+    meta = trace_data.get("meta", {})
+    print(f"\n{Colors.BOLD}📊 Execution Summary:{Colors.ENDC}")
+    print(f"    Total Attempts: {meta.get('total_attempts', len(trace_data['history']))}")
+    print(f"    Final Status: {meta.get('final_status', 'unknown').upper()}")
+    print(f"    Timestamp: {meta.get('timestamp', 'N/A')}")
+
+    if trace_data.get("forbidden_strategies"):
+        print(
+            f"    Banned Strategies: {', '.join(format_strategy(s) for s in trace_data['forbidden_strategies'])}"
+        )
+
+    print_separator("-")
+    print(f"\n{Colors.SYSTEM}🎬 Beginning replay...{Colors.ENDC}\n")
+    time.sleep(speed)
+
+    # Replay each step in the history
+    history = trace_data.get("history", [])
+
+    for i, step in enumerate(history, 1):
+        print_separator("─")
+        print(f"\n{Colors.BOLD}🔄 Round {step.get('step_id', i)} of {len(history)}{Colors.ENDC}")
+        time.sleep(speed)
+
+        # Builder generates solution
+        strategy = step.get("strategy_used", "unknown")
+        print_speaker(
+            "GPT-4o (The Builder)",
+            f"I'll solve this using {format_strategy(strategy)}...",
+            Colors.BUILDER,
+        )
+        time.sleep(speed * 0.5)
+
+        if show_code:
+            code = step.get("code_generated", "")
+            if code:
+                print(f"\n{Colors.BOLD}    Generated Solution:{Colors.ENDC}")
+                print_code_block(code)
+                time.sleep(speed)
+
+        # Prosecutor reviews
+        feedback = step.get("verifier_feedback", "")
+        status = step.get("status", "unknown")
+
+        if status == "failed":
+            print_speaker("Gemini (The Prosecutor)", feedback, Colors.PROSECUTOR)
+            time.sleep(speed)
+
+            # Kernel decision
+            print_speaker(
+                "Kernel (The Arbiter)", "⚖️  Objection Sustained. Solution REJECTED.", Colors.KERNEL
+            )
+
+            # Check if strategy was banned
+            if strategy in trace_data.get("forbidden_strategies", []):
+                time.sleep(speed * 0.5)
+                print_speaker(
+                    "Kernel (The Arbiter)",
+                    f"🚫 Strategy '{format_strategy(strategy)}' is now BANNED from future attempts.",
+                    Colors.KERNEL,
+                )
+
+        elif status == "success":
+            print_speaker("Gemini (The Prosecutor)", feedback, Colors.SUCCESS)
+            time.sleep(speed)
+
+            print_speaker(
+                "Kernel (The Arbiter)", "✅ Verification PASSED. Solution ACCEPTED.", Colors.KERNEL
+            )
+
+        time.sleep(speed)
+
+    # Print final result
+    print_separator("=")
+    print(f"\n{Colors.BOLD}🏁 FINAL RESULT{Colors.ENDC}")
+    print_separator("=")
+
+    final_status = meta.get("final_status", "unknown")
+    if final_status == "solved":
+        print(
+            f"\n{Colors.SUCCESS}{Colors.BOLD}✅ SUCCESS:{Colors.ENDC} {Colors.SUCCESS}The Adversarial Kernel found a verified solution!{Colors.ENDC}"
+        )
+        print(f"\n{Colors.BOLD}Final Solution (Verified):{Colors.ENDC}")
+        if trace_data.get("current_code"):
+            print_code_block(trace_data["current_code"])
+    else:
+        print(
+            f"\n{Colors.FAIL}{Colors.BOLD}❌ FAILED:{Colors.ENDC} {Colors.FAIL}Max retries reached without finding a verified solution.{Colors.ENDC}"
+        )
+
+    # Summary statistics
+    print(f"\n{Colors.BOLD}📈 Statistics:{Colors.ENDC}")
+    failed_count = sum(1 for step in history if step.get("status") == "failed")
+    success_count = sum(1 for step in history if step.get("status") == "success")
+    print(f"    Attempts: {len(history)}")
+    print(f"    Failed: {failed_count}")
+    print(f"    Succeeded: {success_count}")
+
+    if trace_data.get("forbidden_strategies"):
+        print(f"    Banned Strategies: {len(trace_data['forbidden_strategies'])}")
+        for strategy in trace_data["forbidden_strategies"]:
+            print(f"        - {format_strategy(strategy)}")
+
+    print_separator("=")
+
+
+def list_traces(traces_dir: str = "logs/traces") -> list[Path]:
+    """List all trace files in the traces directory."""
+    trace_path = Path(traces_dir)
+    if not trace_path.exists():
+        print(f"{Colors.FAIL}Error: Traces directory '{traces_dir}' not found.{Colors.ENDC}")
+        return []
+
+    trace_files = sorted(trace_path.glob("*.json"))
+    return trace_files
+
+
+def get_latest_trace(traces_dir: str = "logs/traces") -> Path:
+    """Get the most recent trace file."""
+    trace_files = list_traces(traces_dir)
+    if not trace_files:
+        return None
+    return max(trace_files, key=lambda p: p.stat().st_mtime)
+
+
+def load_trace(filepath: str) -> dict[str, Any]:
+    """Load and parse a trace JSON file."""
+    try:
+        with open(filepath, encoding="utf-8") as f:
+            return json.load(f)
+    except FileNotFoundError:
+        print(f"{Colors.FAIL}Error: File '{filepath}' not found.{Colors.ENDC}")
+        sys.exit(1)
+    except json.JSONDecodeError as e:
+        print(f"{Colors.FAIL}Error: Invalid JSON in '{filepath}': {e}{Colors.ENDC}")
+        sys.exit(1)
+
+
+def main():
+    """Main entry point for the visualizer CLI."""
+    parser = argparse.ArgumentParser(
+        description="Replay JSON traces as adversarial debates",
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+        epilog="""
+Examples:
+  python -m src.tools.visualizer logs/traces/cmvk_prob_001.json
+  python -m src.tools.visualizer --list
+  python -m src.tools.visualizer --latest
+  python -m src.tools.visualizer trace.json --speed 1.0 --no-code
+        """,
+    )
+
+    parser.add_argument(
+        "trace_file", nargs="?", help="Path to the trace JSON file (supports wildcards)"
+    )
+    parser.add_argument("--list", action="store_true", help="List all available trace files")
+    parser.add_argument("--latest", action="store_true", help="Replay the most recent trace file")
+    parser.add_argument(
+        "--speed",
+        type=float,
+        default=0.5,
+        help="Playback speed in seconds between messages (default: 0.5, use 0 for instant)",
+    )
+    parser.add_argument("--no-code", action="store_true", help="Hide code blocks in the output")
+    parser.add_argument(
+        "--traces-dir",
+        default="logs/traces",
+        help="Directory containing trace files (default: logs/traces)",
+    )
+
+    args = parser.parse_args()
+
+    # Handle --list option
+    if args.list:
+        trace_files = list_traces(args.traces_dir)
+        if not trace_files:
+            print("No trace files found.")
+            return
+
+        print(f"\n{Colors.BOLD}Available Trace Files:{Colors.ENDC}")
+        for i, trace_file in enumerate(trace_files, 1):
+            mtime = time.strftime("%Y-%m-%d %H:%M:%S", time.localtime(trace_file.stat().st_mtime))
+            size = trace_file.stat().st_size
+            print(f"  {i}. {trace_file.name}")
+            print(f"     Modified: {mtime} | Size: {size} bytes")
+        return
+
+    # Handle --latest option
+    if args.latest:
+        latest = get_latest_trace(args.traces_dir)
+        if not latest:
+            print(f"{Colors.FAIL}No trace files found in '{args.traces_dir}'.{Colors.ENDC}")
+            return
+        trace_file = str(latest)
+        print(f"{Colors.SYSTEM}Loading latest trace: {latest.name}{Colors.ENDC}\n")
+    elif args.trace_file:
+        # Handle wildcards
+        if "*" in args.trace_file or "?" in args.trace_file:
+            matches = glob.glob(args.trace_file)
+            if not matches:
+                print(f"{Colors.FAIL}No files matching pattern '{args.trace_file}'{Colors.ENDC}")
+                return
+            trace_file = matches[0]
+            if len(matches) > 1:
+                print(
+                    f"{Colors.WARNING}Multiple files match pattern. Using: {trace_file}{Colors.ENDC}\n"
+                )
+        else:
+            trace_file = args.trace_file
+    else:
+        parser.print_help()
+        return
+
+    # Load and replay the trace
+    trace_data = load_trace(trace_file)
+    replay_trace(trace_data, speed=args.speed, show_code=not args.no_code)
+
+
+if __name__ == "__main__":
+    main()

modules/cmvk/src/cross_model_verification_kernel/tools/web_search.py

@@ -0,0 +1,86 @@
+"""
+Web search tool for fact-checking and information retrieval.
+This can be used to verify claims or gather additional context.
+"""
+
+import logging
+from typing import Any
+
+logger = logging.getLogger(__name__)
+
+
+class WebSearchTool:
+    """
+    Tool for performing web searches to fact-check generated content.
+
+    This is useful for verifying factual claims in solutions or
+    gathering additional context for complex problems.
+    """
+
+    def __init__(self, api_key: str | None = None):
+        """
+        Initialize the web search tool.
+
+        Args:
+            api_key: API key for search service (e.g., Serper, Tavily, etc.)
+        """
+        self.api_key = api_key
+        logger.info("WebSearchTool initialized")
+
+    def search(self, query: str, max_results: int = 5) -> list[dict[str, Any]]:
+        """
+        Perform a web search.
+
+        Args:
+            query: Search query
+            max_results: Maximum number of results to return
+
+        Returns:
+            List of search results with title, url, and snippet
+        """
+        logger.info(f"Searching for: {query}")
+
+        # TODO: Implement actual web search using a service like:
+        # - Serper API
+        # - Tavily API
+        # - Google Custom Search
+        # - Bing Search API
+
+        logger.warning("Web search not yet implemented, returning mock results")
+        return self._mock_search(query, max_results)
+
+    def fact_check(self, claim: str) -> dict[str, Any]:
+        """
+        Fact-check a specific claim.
+
+        Args:
+            claim: The claim to verify
+
+        Returns:
+            Dictionary with verification result
+        """
+        logger.info(f"Fact-checking: {claim}")
+
+        # Search for information about the claim
+        results = self.search(claim)
+
+        # TODO: Implement sophisticated fact-checking logic
+        # For now, return a simple result
+        return {
+            "claim": claim,
+            "confidence": 0.5,
+            "verdict": "uncertain",
+            "sources": results,
+            "explanation": "Fact-checking not yet implemented",
+        }
+
+    def _mock_search(self, query: str, max_results: int) -> list[dict[str, Any]]:
+        """Return mock search results for testing."""
+        return [
+            {
+                "title": f"Mock result {i+1} for: {query}",
+                "url": f"https://example.com/result{i+1}",
+                "snippet": f"This is a mock search result snippet {i+1}",
+            }
+            for i in range(max_results)
+        ]

modules/cmvk/src/cross_model_verification_kernel/verifier.py

@@ -0,0 +1,257 @@
+"""
+Verifier Module
+
+Implements the Verifier component that performs hostile code review.
+The Verifier uses a DIFFERENT model than the Generator to reduce shared blind spots.
+"""
+
+from dataclasses import dataclass
+from enum import Enum
+from typing import Any
+
+from .models import BaseModelInterface, MockModelInterface, ModelProvider
+
+
+class Severity(Enum):
+    """Severity levels for verification issues"""
+
+    CRITICAL = "critical"
+    HIGH = "high"
+    MEDIUM = "medium"
+    LOW = "low"
+    INFO = "info"
+
+
+@dataclass
+class VerificationIssue:
+    """A single issue found during verification"""
+
+    severity: Severity
+    category: str
+    description: str
+    line_number: int | None = None
+    suggestion: str | None = None
+
+
+@dataclass
+class VerifierConfig:
+    """Configuration for the Verifier"""
+
+    model: ModelProvider
+    temperature: float = 0.2  # Lower temperature for more deterministic verification
+    max_tokens: int = 3000
+    api_key: str | None = None
+    adversarial_mode: bool = True  # Enable hostile code review by default
+
+
+@dataclass
+class VerificationReport:
+    """Complete verification report"""
+
+    passed: bool
+    issues: list[VerificationIssue]
+    summary: str
+    model_used: str
+    code_reviewed: str
+    metadata: dict[str, Any] | None = None
+
+
+class Verifier:
+    """
+    Verifier component that performs hostile code review.
+
+    This component intentionally uses a DIFFERENT model than the Generator
+    to create an adversarial relationship that reduces shared blind spots.
+    """
+
+    def __init__(self, config: VerifierConfig, model_interface: BaseModelInterface | None = None):
+        """
+        Initialize the Verifier
+
+        Args:
+            config: Verifier configuration
+            model_interface: Optional custom model interface (uses mock if not provided)
+        """
+        self.config = config
+        self.model_interface = model_interface or MockModelInterface(
+            model=config.model, api_key=config.api_key
+        )
+        self.verification_count = 0
+
+    def verify_code(
+        self, code: str, description: str, language: str = "python", **kwargs
+    ) -> VerificationReport:
+        """
+        Verify code with adversarial/hostile code review approach
+
+        Args:
+            code: The code to verify
+            description: What the code is supposed to do
+            language: Programming language
+            **kwargs: Additional verification parameters
+
+        Returns:
+            VerificationReport with all found issues
+        """
+        self.verification_count += 1
+
+        # Build adversarial verification prompt
+        prompt = self._build_adversarial_prompt(code, description, language)
+
+        # Get verification from the model
+        response = self.model_interface.generate(
+            prompt, temperature=self.config.temperature, max_tokens=self.config.max_tokens, **kwargs
+        )
+
+        # Parse issues from response
+        issues = self._parse_verification_response(response.content)
+
+        # Determine if verification passed
+        critical_or_high_issues = [
+            issue for issue in issues if issue.severity in [Severity.CRITICAL, Severity.HIGH]
+        ]
+        passed = len(critical_or_high_issues) == 0
+
+        return VerificationReport(
+            passed=passed,
+            issues=issues,
+            summary=self._generate_summary(issues, passed),
+            model_used=response.model,
+            code_reviewed=code,
+            metadata={
+                "verification_count": self.verification_count,
+                "provider": response.provider.value,
+                "adversarial_mode": self.config.adversarial_mode,
+                "response_metadata": response.metadata,
+            },
+        )
+
+    def _build_adversarial_prompt(self, code: str, description: str, language: str) -> str:
+        """Build adversarial verification prompt"""
+        adversarial_instructions = (
+            """You are a HOSTILE code reviewer. Your job is to find ALL possible issues, bugs, vulnerabilities, and problems.
+Be extremely critical and thorough. Look for:
+- Security vulnerabilities
+- Logic errors and edge cases
+- Performance issues
+- Missing error handling
+- Type safety issues
+- Resource leaks
+- Concurrency problems
+- Input validation gaps
+- Any possible way the code could fail
+
+DO NOT be cooperative or lenient. Find every flaw."""
+            if self.config.adversarial_mode
+            else ""
+        )
+
+        return f"""{adversarial_instructions}
+
+Review the following {language} code:
+
+Task Description: {description}
+
+Code:
+```{language}
+{code}
+```
+
+Provide a detailed security and quality review. For each issue found, specify:
+- SEVERITY: (CRITICAL/HIGH/MEDIUM/LOW/INFO)
+- CATEGORY: (e.g., security, performance, logic, error-handling)
+- DESCRIPTION: What is wrong
+- SUGGESTION: How to fix it (if applicable)
+
+List ALL issues found:"""
+
+    def _parse_verification_response(self, response: str) -> list[VerificationIssue]:
+        """Parse verification response into structured issues"""
+        issues = []
+
+        # Simple parsing logic - in real implementation, this would be more sophisticated
+        lines = response.split("\n")
+        current_issue = {}
+
+        for line in lines:
+            line = line.strip()
+            if not line:
+                if current_issue:
+                    issues.append(self._create_issue_from_dict(current_issue))
+                    current_issue = {}
+                continue
+
+            # Parse different fields
+            if (
+                line.startswith("SEVERITY:")
+                or line.startswith("1.")
+                or line.startswith("CRITICAL")
+                or line.startswith("HIGH")
+            ):
+                if current_issue:
+                    issues.append(self._create_issue_from_dict(current_issue))
+                    current_issue = {}
+
+                # Extract severity
+                severity_text = line.upper()
+                if "CRITICAL" in severity_text:
+                    current_issue["severity"] = Severity.CRITICAL
+                elif "HIGH" in severity_text:
+                    current_issue["severity"] = Severity.HIGH
+                elif "MEDIUM" in severity_text:
+                    current_issue["severity"] = Severity.MEDIUM
+                elif "LOW" in severity_text:
+                    current_issue["severity"] = Severity.LOW
+                else:
+                    current_issue["severity"] = Severity.INFO
+
+                # Start capturing description
+                current_issue["description"] = line
+            elif line.startswith("CATEGORY:"):
+                current_issue["category"] = line.replace("CATEGORY:", "").strip()
+            elif line.startswith("DESCRIPTION:"):
+                current_issue["description"] = line.replace("DESCRIPTION:", "").strip()
+            elif line.startswith("SUGGESTION:"):
+                current_issue["suggestion"] = line.replace("SUGGESTION:", "").strip()
+            elif current_issue and "description" in current_issue:
+                # Continue multi-line description
+                current_issue["description"] += " " + line
+
+        # Add last issue if exists
+        if current_issue:
+            issues.append(self._create_issue_from_dict(current_issue))
+
+        return issues
+
+    def _create_issue_from_dict(self, issue_dict: dict[str, Any]) -> VerificationIssue:
+        """Create a VerificationIssue from parsed dictionary"""
+        return VerificationIssue(
+            severity=issue_dict.get("severity", Severity.INFO),
+            category=issue_dict.get("category", "general"),
+            description=issue_dict.get("description", "Issue found"),
+            suggestion=issue_dict.get("suggestion"),
+        )
+
+    def _generate_summary(self, issues: list[VerificationIssue], passed: bool) -> str:
+        """Generate a summary of the verification"""
+        if passed:
+            return f"Verification PASSED. Found {len(issues)} minor issues (no critical or high severity)."
+
+        critical = sum(1 for i in issues if i.severity == Severity.CRITICAL)
+        high = sum(1 for i in issues if i.severity == Severity.HIGH)
+        medium = sum(1 for i in issues if i.severity == Severity.MEDIUM)
+        low = sum(1 for i in issues if i.severity == Severity.LOW)
+
+        return (
+            f"Verification FAILED. Found {len(issues)} total issues: "
+            f"{critical} critical, {high} high, {medium} medium, {low} low severity."
+        )
+
+    def get_stats(self) -> dict[str, Any]:
+        """Get verifier statistics"""
+        return {
+            "model": self.config.model.value,
+            "verification_count": self.verification_count,
+            "temperature": self.config.temperature,
+            "adversarial_mode": self.config.adversarial_mode,
+        }

modules/cmvk/tests/__init__.py

@@ -0,0 +1,3 @@
+"""
+Tests for the Cross-Model Verification Kernel.
+"""