superqode 0.1.5__py3-none-any.whl

superqode/guidance/config.py

@@ -0,0 +1,203 @@
+"""
+QE Guidance Configuration - YAML-driven settings for time-constrained QE.
+
+All configuration comes from superqode.yaml, aligned with PRD:
+> "SuperQode operationalizes SuperQE—where autonomous agents aggressively test software,
+>  propose fixes, prove improvements, and report findings with research-grade rigor."
+"""
+
+from dataclasses import dataclass, field
+from enum import Enum
+from pathlib import Path
+from typing import Any, Dict, List, Optional
+import logging
+
+logger = logging.getLogger(__name__)
+
+
+class GuidanceMode(Enum):
+    """QE guidance mode."""
+
+    QUICK_SCAN = "quick_scan"
+    DEEP_QE = "deep_qe"
+
+
+@dataclass
+class AntiPatternConfig:
+    """Configuration for anti-pattern detection."""
+
+    enabled: bool = True
+    patterns: List[str] = field(
+        default_factory=lambda: [
+            "skip_verification",
+            "unconditional_success",
+            "broad_exception_swallow",
+            "weaken_tests",
+            "silent_fallback",
+            "guess_expected_output",
+        ]
+    )
+
+
+@dataclass
+class ModeGuidanceConfig:
+    """Configuration for a specific QE mode."""
+
+    timeout_seconds: int = 60
+    verification_first: bool = True
+    fail_fast: bool = False
+    exploration_allowed: bool = False
+    destructive_testing: bool = False
+
+    # What the agent should focus on
+    focus_areas: List[str] = field(default_factory=list)
+
+    # What the agent should NOT do
+    forbidden_actions: List[str] = field(default_factory=list)
+
+
+@dataclass
+class GuidanceConfig:
+    """
+    Complete QE guidance configuration from superqode.yaml.
+
+    Defines:
+    - Mode-specific timeouts and constraints
+    - Verification-first workflow requirements
+    - Anti-pattern detection rules
+    """
+
+    enabled: bool = True
+
+    # Mode-specific configurations
+    quick_scan: ModeGuidanceConfig = field(
+        default_factory=lambda: ModeGuidanceConfig(
+            timeout_seconds=60,
+            verification_first=True,
+            fail_fast=True,
+            exploration_allowed=False,
+            destructive_testing=False,
+            focus_areas=[
+                "Run smoke tests first",
+                "Validate critical paths",
+                "Check for obvious errors",
+                "Verify basic functionality",
+            ],
+            forbidden_actions=[
+                "Long-running performance tests",
+                "Extensive code generation",
+                "Deep exploration without quick feedback",
+            ],
+        )
+    )
+
+    deep_qe: ModeGuidanceConfig = field(
+        default_factory=lambda: ModeGuidanceConfig(
+            timeout_seconds=1800,
+            verification_first=True,
+            fail_fast=False,
+            exploration_allowed=True,
+            destructive_testing=True,
+            focus_areas=[
+                "Comprehensive test coverage",
+                "Edge case exploration",
+                "Security vulnerability scanning",
+                "Performance and load testing",
+                "Chaos and stress testing",
+            ],
+            forbidden_actions=[
+                "Modifying production code",
+                "Committing changes to git",
+                "Accessing external networks without approval",
+            ],
+        )
+    )
+
+    # Anti-pattern detection
+    anti_patterns: AntiPatternConfig = field(default_factory=AntiPatternConfig)
+
+    # QIR (Quality Investigation Report) settings
+    qir_format: str = "markdown"  # "markdown", "json", "both"
+    require_proof: bool = True  # Must have verification before success
+
+    @classmethod
+    def from_yaml_dict(cls, data: Dict[str, Any]) -> "GuidanceConfig":
+        """Create GuidanceConfig from YAML dict (superqode.qe.guidance section)."""
+        if not data:
+            return cls()
+
+        config = cls(
+            enabled=data.get("enabled", True),
+            qir_format=data.get("qir_format", "markdown"),
+            require_proof=data.get("require_proof", True),
+        )
+
+        # Parse quick_scan config
+        if "quick_scan" in data:
+            qs = data["quick_scan"]
+            config.quick_scan = ModeGuidanceConfig(
+                timeout_seconds=qs.get("timeout_seconds", 60),
+                verification_first=qs.get("verification_first", True),
+                fail_fast=qs.get("fail_fast", True),
+                exploration_allowed=qs.get("exploration_allowed", False),
+                destructive_testing=qs.get("destructive_testing", False),
+                focus_areas=qs.get("focus_areas", config.quick_scan.focus_areas),
+                forbidden_actions=qs.get("forbidden_actions", config.quick_scan.forbidden_actions),
+            )
+
+        # Parse deep_qe config
+        if "deep_qe" in data:
+            dq = data["deep_qe"]
+            config.deep_qe = ModeGuidanceConfig(
+                timeout_seconds=dq.get("timeout_seconds", 1800),
+                verification_first=dq.get("verification_first", True),
+                fail_fast=dq.get("fail_fast", False),
+                exploration_allowed=dq.get("exploration_allowed", True),
+                destructive_testing=dq.get("destructive_testing", True),
+                focus_areas=dq.get("focus_areas", config.deep_qe.focus_areas),
+                forbidden_actions=dq.get("forbidden_actions", config.deep_qe.forbidden_actions),
+            )
+
+        # Parse anti-patterns config
+        if "anti_patterns" in data:
+            ap = data["anti_patterns"]
+            config.anti_patterns = AntiPatternConfig(
+                enabled=ap.get("enabled", True),
+                patterns=ap.get("patterns", config.anti_patterns.patterns),
+            )
+
+        return config
+
+    def get_mode_config(self, mode: GuidanceMode) -> ModeGuidanceConfig:
+        """Get configuration for a specific mode."""
+        if mode == GuidanceMode.QUICK_SCAN:
+            return self.quick_scan
+        else:
+            return self.deep_qe
+
+
+def load_guidance_config(project_root: Path) -> GuidanceConfig:
+    """
+    Load guidance configuration from superqode.yaml.
+
+    Looks for: superqode.qe.guidance section
+    """
+    import yaml
+
+    yaml_path = project_root / "superqode.yaml"
+    if not yaml_path.exists():
+        logger.debug("No superqode.yaml found, using default guidance config")
+        return GuidanceConfig()
+
+    try:
+        with open(yaml_path) as f:
+            data = yaml.safe_load(f)
+
+        # Navigate to superqode.qe.guidance
+        guidance_data = data.get("superqode", {}).get("qe", {}).get("guidance", {})
+
+        return GuidanceConfig.from_yaml_dict(guidance_data)
+
+    except Exception as e:
+        logger.warning(f"Failed to load guidance config: {e}")
+        return GuidanceConfig()

superqode/guidance/prompts.py

@@ -0,0 +1,71 @@
+"""
+QE Guidance Prompts - Minimal OSS guidance.
+
+This provides lightweight, non-proprietary guidance for QE agents.
+"""
+
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Optional
+
+from .config import GuidanceConfig, GuidanceMode, ModeGuidanceConfig, load_guidance_config
+
+
+@dataclass
+class QEGuidance:
+    """Minimal QE guidance for OSS."""
+
+    config: GuidanceConfig
+    mode: GuidanceMode
+
+    @property
+    def mode_config(self) -> ModeGuidanceConfig:
+        return self.config.get_mode_config(self.mode)
+
+    def get_system_prompt(self) -> str:
+        mode_name = "Quick Scan" if self.mode == GuidanceMode.QUICK_SCAN else "Deep QE"
+        timeout = self.mode_config.timeout_seconds
+        return (
+            f"SYSTEM: SuperQode {mode_name} QE Mode ({timeout}s)\n\n"
+            "Focus on finding real issues with evidence. "
+            "Prefer concrete reproduction steps and avoid speculation."
+        )
+
+    def get_review_prompt(self) -> str:
+        return (
+            "SYSTEM: SuperQode QE Review Mode\n\n"
+            "Validate that findings are evidence-backed and reproducible. "
+            "Call out any unverifiable claims."
+        )
+
+    def get_goal_suffix(self) -> str:
+        return (
+            "\n\nCOMPLETION GATE:\n"
+            "1. Run relevant checks/tests where feasible\n"
+            "2. Document evidence for findings\n"
+            "3. Report any limitations clearly\n"
+        )
+
+
+def get_qe_system_prompt(
+    project_root: Path,
+    mode: GuidanceMode = GuidanceMode.QUICK_SCAN,
+) -> str:
+    config = load_guidance_config(project_root)
+    guidance = QEGuidance(config=config, mode=mode)
+    return guidance.get_system_prompt()
+
+
+def get_qe_review_prompt(project_root: Path) -> str:
+    config = load_guidance_config(project_root)
+    guidance = QEGuidance(config=config, mode=GuidanceMode.DEEP_QE)
+    return guidance.get_review_prompt()
+
+
+def get_qe_goal_suffix(
+    project_root: Path,
+    mode: GuidanceMode = GuidanceMode.QUICK_SCAN,
+) -> str:
+    config = load_guidance_config(project_root)
+    guidance = QEGuidance(config=config, mode=mode)
+    return guidance.get_goal_suffix()

superqode/harness/__init__.py

@@ -0,0 +1,54 @@
+"""
+SuperQode Patch Harness - Fast validation for QE artifacts.
+
+The harness runs user-defined commands on patches/changes BEFORE they're suggested in QIRs.
+This keeps OSS flexible without shipping proprietary validators.
+
+Key principle from PRD:
+> "SuperQode never edits, rewrites, or commits code."
+> "All fixes are suggested, validated, and proven, never auto-applied."
+
+The harness VALIDATES suggestions, it doesn't apply them.
+
+Configuration is driven entirely by superqode.yaml:
+
+```yaml
+superqode:
+  qe:
+    harness:
+      enabled: true
+      timeout_seconds: 30
+
+      custom_steps:
+        - name: "pytest"
+          command: "pytest -q"
+        - name: "contract-check"
+          command: "schemathesis run openapi.yaml"
+```
+"""
+
+from .validator import PatchHarness, HarnessFinding, HarnessResult
+from .config import HarnessConfig, ValidationCategory, load_harness_config
+from .accelerator import (
+    Accelerator,
+    AcceleratorConfig,
+    get_accelerator,
+    prewarm,
+    cached_system_prompt,
+)
+
+__all__ = [
+    # Validation
+    "PatchHarness",
+    "HarnessFinding",
+    "HarnessResult",
+    "ValidationCategory",
+    "HarnessConfig",
+    "load_harness_config",
+    # Performance
+    "Accelerator",
+    "AcceleratorConfig",
+    "get_accelerator",
+    "prewarm",
+    "cached_system_prompt",
+]

superqode/harness/accelerator.py

@@ -0,0 +1,291 @@
+"""
+Harness Accelerator - Performance Optimizations for QE.
+
+Centralized performance optimizations for the SuperQode harness:
+- Pre-computed tool definitions (compute once, reuse)
+- Message format caching (don't rebuild identical messages)
+- Background prewarming for slow imports
+- Parallel execution utilities
+
+Usage:
+    from superqode.harness.accelerator import Accelerator
+
+    # Initialize once during startup
+    accel = Accelerator()
+    accel.prewarm()
+
+    # Use cached tool definitions
+    tools = accel.get_tool_definitions(tool_registry)
+"""
+
+import asyncio
+import concurrent.futures
+import hashlib
+import threading
+from dataclasses import dataclass
+from functools import lru_cache
+from typing import Any, Callable, Dict, List, Optional, TypeVar
+
+T = TypeVar("T")
+
+
+@dataclass
+class AcceleratorConfig:
+    """Configuration for the accelerator."""
+
+    prewarm_litellm: bool = True
+    cache_tool_defs: bool = True
+    cache_messages: bool = True
+    max_cache_size: int = 1000
+
+
+class Accelerator:
+    """Centralized performance optimizations for SuperQode.
+
+    Provides caching, prewarming, and parallel execution utilities
+    to minimize latency during QE sessions.
+    """
+
+    _instance: Optional["Accelerator"] = None
+    _lock = threading.Lock()
+
+    def __new__(cls, *args, **kwargs):
+        """Singleton pattern - only one accelerator instance."""
+        if cls._instance is None:
+            with cls._lock:
+                if cls._instance is None:
+                    cls._instance = super().__new__(cls)
+        return cls._instance
+
+    def __init__(self, config: Optional[AcceleratorConfig] = None):
+        if hasattr(self, "_initialized"):
+            return
+
+        self._initialized = True
+        self.config = config or AcceleratorConfig()
+
+        # Thread pool for background tasks
+        self._executor = concurrent.futures.ThreadPoolExecutor(max_workers=4)
+
+        # Caches
+        self._tool_def_cache: Dict[str, List[Dict]] = {}
+        self._message_cache: Dict[str, Any] = {}
+
+        # Prewarm state
+        self._prewarm_complete = threading.Event()
+        self._prewarm_started = False
+
+    def prewarm(self) -> None:
+        """Start prewarming in background (non-blocking).
+
+        Call this during app startup for faster first operations.
+        """
+        if self._prewarm_started:
+            return
+
+        self._prewarm_started = True
+
+        def do_prewarm():
+            # Prewarm LiteLLM
+            if self.config.prewarm_litellm:
+                try:
+                    from superqode.providers.gateway.litellm_gateway import LiteLLMGateway
+
+                    LiteLLMGateway.prewarm()
+                except ImportError:
+                    pass
+
+            # Prewarm other heavy imports
+            try:
+                import rich
+                import textual
+            except ImportError:
+                pass
+
+            self._prewarm_complete.set()
+
+        self._executor.submit(do_prewarm)
+
+    async def prewarm_async(self) -> None:
+        """Async version - await to ensure prewarming is complete."""
+        if self._prewarm_complete.is_set():
+            return
+
+        loop = asyncio.get_event_loop()
+        await loop.run_in_executor(self._executor, self._wait_for_prewarm)
+
+    def _wait_for_prewarm(self) -> None:
+        """Wait for prewarming to complete."""
+        self.prewarm()  # Start if not started
+        self._prewarm_complete.wait(timeout=10.0)
+
+    def is_ready(self) -> bool:
+        """Check if prewarming is complete."""
+        return self._prewarm_complete.is_set()
+
+    def get_tool_definitions(self, registry) -> List[Dict]:
+        """Get cached tool definitions for a registry.
+
+        Args:
+            registry: A ToolRegistry instance
+
+        Returns:
+            List of tool definitions in OpenAI format
+        """
+        if not self.config.cache_tool_defs:
+            return self._compute_tool_definitions(registry)
+
+        # Use registry id as cache key
+        cache_key = str(id(registry))
+
+        if cache_key not in self._tool_def_cache:
+            self._tool_def_cache[cache_key] = self._compute_tool_definitions(registry)
+
+        return self._tool_def_cache[cache_key]
+
+    def _compute_tool_definitions(self, registry) -> List[Dict]:
+        """Compute tool definitions from a registry."""
+        definitions = []
+        for tool in registry.list():
+            definitions.append(
+                {
+                    "type": "function",
+                    "function": {
+                        "name": tool.name,
+                        "description": tool.description,
+                        "parameters": tool.parameters,
+                    },
+                }
+            )
+        return definitions
+
+    def cache_message(self, key: str, message: Any) -> None:
+        """Cache a message for later retrieval.
+
+        Args:
+            key: Cache key (e.g., message hash)
+            message: The message object to cache
+        """
+        if not self.config.cache_messages:
+            return
+
+        # Limit cache size
+        if len(self._message_cache) >= self.config.max_cache_size:
+            # Simple eviction - clear half the cache
+            keys = list(self._message_cache.keys())[: self.config.max_cache_size // 2]
+            for k in keys:
+                self._message_cache.pop(k, None)
+
+        self._message_cache[key] = message
+
+    def get_cached_message(self, key: str) -> Optional[Any]:
+        """Get a cached message.
+
+        Args:
+            key: Cache key
+
+        Returns:
+            Cached message or None if not found
+        """
+        return self._message_cache.get(key)
+
+    def message_hash(self, content: str, role: str = "user") -> str:
+        """Compute a hash for a message.
+
+        Args:
+            content: Message content
+            role: Message role
+
+        Returns:
+            Hash string for caching
+        """
+        data = f"{role}:{content}".encode("utf-8")
+        return hashlib.md5(data).hexdigest()
+
+    def invalidate_tool_cache(self) -> None:
+        """Invalidate all cached tool definitions."""
+        self._tool_def_cache.clear()
+
+    def invalidate_message_cache(self) -> None:
+        """Invalidate all cached messages."""
+        self._message_cache.clear()
+
+    def clear_all_caches(self) -> None:
+        """Clear all caches."""
+        self.invalidate_tool_cache()
+        self.invalidate_message_cache()
+
+    async def run_parallel(
+        self,
+        tasks: List[Callable[[], T]],
+        max_concurrent: int = 10,
+    ) -> List[T]:
+        """Run multiple async tasks in parallel.
+
+        Args:
+            tasks: List of async callables
+            max_concurrent: Maximum concurrent tasks
+
+        Returns:
+            List of results in same order as tasks
+        """
+        semaphore = asyncio.Semaphore(max_concurrent)
+
+        async def limited_task(task):
+            async with semaphore:
+                if asyncio.iscoroutinefunction(task):
+                    return await task()
+                else:
+                    return task()
+
+        return await asyncio.gather(*[limited_task(t) for t in tasks])
+
+    def shutdown(self) -> None:
+        """Shutdown the accelerator and release resources."""
+        self._executor.shutdown(wait=False)
+        self.clear_all_caches()
+
+
+# Module-level convenience functions
+_accelerator: Optional[Accelerator] = None
+
+
+def get_accelerator() -> Accelerator:
+    """Get the global accelerator instance."""
+    global _accelerator
+    if _accelerator is None:
+        _accelerator = Accelerator()
+    return _accelerator
+
+
+def prewarm() -> None:
+    """Prewarm the accelerator (call during startup)."""
+    get_accelerator().prewarm()
+
+
+@lru_cache(maxsize=32)
+def cached_system_prompt(
+    prompt_type: str,
+    working_dir: str,
+    custom_prompt: str = "",
+) -> str:
+    """Get a cached system prompt.
+
+    Args:
+        prompt_type: Type of prompt (e.g., "minimal", "standard")
+        working_dir: Working directory path
+        custom_prompt: Optional custom prompt to append
+
+    Returns:
+        Cached system prompt string
+    """
+    from superqode.agent.system_prompts import get_system_prompt, SystemPromptLevel
+    from pathlib import Path
+
+    level = getattr(SystemPromptLevel, prompt_type.upper(), SystemPromptLevel.MINIMAL)
+    prompt = get_system_prompt(level=level, working_directory=Path(working_dir))
+
+    if custom_prompt:
+        prompt += f"\n\n{custom_prompt}"
+
+    return prompt