superqode 0.1.5__py3-none-any.whl

superqode/execution/modes.py

@@ -0,0 +1,347 @@
+"""
+Execution Modes for SuperQode.
+
+Defines the primary execution modes:
+- BYOK: Direct LLM API calls (user provides API keys)
+- ACP: Agent Client Protocol (full coding agent capabilities)
+- LOCAL: Local/self-hosted models (no API keys required)
+
+QE Modes (Perception & Usability):
+- Quick Scan: Time-boxed, shallow exploration, pre-commit/fast CI
+- Deep QE: Full sandbox, destructive testing, pre-release/nightly CI
+
+SECURITY PRINCIPLE:
+- BYOK: Keys read from user's environment, never stored by SuperQode
+- ACP: Agent manages its own auth, SuperQode just connects
+- LOCAL: No API keys needed, runs on local machine
+"""
+
+from dataclasses import dataclass, field
+from enum import Enum
+from typing import Any, Dict, List, Optional
+
+
+class ExecutionMode(Enum):
+    """Execution mode for a role."""
+
+    BYOK = "byok"  # Bring Your Own Key - Direct LLM API
+    ACP = "acp"  # Agent Client Protocol - Full agent
+    LOCAL = "local"  # Local/self-hosted models - No API key required
+
+
+class QEMode(Enum):
+    """QE execution mode."""
+
+    QUICK_SCAN = "quick_scan"  # Fast, shallow, time-boxed
+    DEEP_QE = "deep_qe"  # Full exploration, destructive allowed
+
+
+class GatewayType(Enum):
+    """Gateway type for BYOK mode."""
+
+    LITELLM = "litellm"  # Default: LiteLLM unified API
+    DIRECT = "direct"  # Future: Direct API calls
+
+
+@dataclass
+class BYOKConfig:
+    """Configuration for BYOK (Bring Your Own Key) mode.
+
+    In BYOK mode:
+    - SuperQode makes direct LLM API calls via a gateway (LiteLLM)
+    - User provides API keys via environment variables
+    - Capabilities: Chat completion, streaming, tool calling (if supported)
+    - No agent features (no file editing, no shell commands)
+    """
+
+    provider: str
+    model: str
+    gateway: GatewayType = GatewayType.LITELLM
+
+    # Optional overrides
+    base_url: Optional[str] = None
+    extra_headers: Dict[str, str] = field(default_factory=dict)
+
+    # Cost tracking
+    track_costs: bool = True
+
+    def get_litellm_model(self) -> str:
+        """Get the model string for LiteLLM."""
+        from ..providers.registry import PROVIDERS
+
+        provider_def = PROVIDERS.get(self.provider)
+        if provider_def and provider_def.litellm_prefix:
+            # Don't double-prefix
+            if self.model.startswith(provider_def.litellm_prefix):
+                return self.model
+            return f"{provider_def.litellm_prefix}{self.model}"
+        return self.model
+
+
+@dataclass
+class ACPConfig:
+    """Configuration for ACP (Agent Client Protocol) mode.
+
+    In ACP mode:
+    - SuperQode connects to an ACP-compatible coding agent
+    - Agent manages its own LLM authentication
+    - Capabilities: Full agent (files, shell, MCP, reasoning)
+    - Agent handles all LLM interactions internally
+    """
+
+    agent: str  # Agent ID (e.g., "opencode")
+
+    # Agent's internal LLM config (passed to agent)
+    agent_provider: Optional[str] = None
+    agent_model: Optional[str] = None
+
+    # Connection settings
+    connection_type: str = "stdio"  # "stdio" | "http"
+    command: Optional[str] = None  # Override agent command
+    host: Optional[str] = None  # For HTTP connections
+    port: Optional[int] = None
+
+
+@dataclass
+class ExecutionConfig:
+    """Complete execution configuration for a role."""
+
+    mode: ExecutionMode
+
+    # Mode-specific config (one will be set based on mode)
+    byok: Optional[BYOKConfig] = None
+    acp: Optional[ACPConfig] = None
+
+    # Common settings
+    job_description: str = ""
+    enabled: bool = True
+
+    @classmethod
+    def from_byok(
+        cls, provider: str, model: str, job_description: str = "", **kwargs
+    ) -> "ExecutionConfig":
+        """Create a BYOK execution config."""
+        return cls(
+            mode=ExecutionMode.BYOK,
+            byok=BYOKConfig(provider=provider, model=model, **kwargs),
+            job_description=job_description,
+        )
+
+    @classmethod
+    def from_acp(
+        cls,
+        agent: str,
+        agent_provider: Optional[str] = None,
+        agent_model: Optional[str] = None,
+        job_description: str = "",
+        **kwargs,
+    ) -> "ExecutionConfig":
+        """Create an ACP execution config."""
+        return cls(
+            mode=ExecutionMode.ACP,
+            acp=ACPConfig(
+                agent=agent, agent_provider=agent_provider, agent_model=agent_model, **kwargs
+            ),
+            job_description=job_description,
+        )
+
+    def get_mode_info(self) -> Dict[str, Any]:
+        """Get human-readable info about the execution mode."""
+        if self.mode == ExecutionMode.BYOK:
+            return {
+                "mode": "BYOK (Bring Your Own Key)",
+                "description": "Direct LLM API calls via gateway",
+                "provider": self.byok.provider if self.byok else None,
+                "model": self.byok.model if self.byok else None,
+                "gateway": self.byok.gateway.value if self.byok else None,
+                "capabilities": [
+                    "Chat completion",
+                    "Streaming responses",
+                    "Tool calling (if model supports)",
+                ],
+                "limitations": [
+                    "No file editing",
+                    "No shell commands",
+                    "No MCP tools",
+                ],
+                "auth_info": "API key from your environment variables",
+            }
+        else:  # ACP
+            return {
+                "mode": "ACP (Agent Client Protocol)",
+                "description": "Full coding agent capabilities",
+                "agent": self.acp.agent if self.acp else None,
+                "agent_provider": self.acp.agent_provider if self.acp else None,
+                "agent_model": self.acp.agent_model if self.acp else None,
+                "capabilities": [
+                    "File reading/writing",
+                    "Shell command execution",
+                    "MCP tool integration",
+                    "Multi-step reasoning",
+                    "Context management",
+                ],
+                "auth_info": "Managed by the agent (not SuperQode)",
+            }
+
+
+# =============================================================================
+# QE Mode Configurations
+# =============================================================================
+
+
+@dataclass
+class QuickScanConfig:
+    """
+    Quick Scan Mode Configuration.
+
+    Use cases:
+    - Pre-commit hooks
+    - Developer laptop testing
+    - Fast CI feedback
+
+    Characteristics:
+    - Time-boxed (seconds, not minutes)
+    - Shallow exploration
+    - High-risk paths only
+    - Minimal QIRs
+    """
+
+    timeout_seconds: int = 60
+    depth: str = "shallow"
+
+    # Execution constraints
+    fail_fast: bool = True
+    max_tests: int = 50  # Limit number of tests to run
+
+    # Test selection
+    run_smoke: bool = True
+    run_sanity: bool = True
+    run_regression: bool = False  # Skip full regression
+
+    # Generation constraints
+    generate_tests: bool = False
+    generate_patches: bool = False
+
+    # Destructive testing
+    destructive_allowed: bool = False
+
+    # QIR settings
+    minimal_qir: bool = True  # Short summary only
+
+    def to_dict(self) -> Dict[str, Any]:
+        return {
+            "mode": "quick_scan",
+            "timeout_seconds": self.timeout_seconds,
+            "depth": self.depth,
+            "fail_fast": self.fail_fast,
+            "max_tests": self.max_tests,
+            "run_smoke": self.run_smoke,
+            "run_sanity": self.run_sanity,
+            "run_regression": self.run_regression,
+            "generate_tests": self.generate_tests,
+            "generate_patches": self.generate_patches,
+            "destructive_allowed": self.destructive_allowed,
+            "minimal_qir": self.minimal_qir,
+        }
+
+
+@dataclass
+class DeepQEConfig:
+    """
+    Deep QE Mode Configuration.
+
+    Use cases:
+    - Pre-release validation
+    - Nightly CI runs
+    - Compliance evidence gathering
+
+    Characteristics:
+    - Full sandbox environment
+    - Destructive testing allowed
+    - Failure simulation hooks
+    - Full Investigation Reports
+    """
+
+    timeout_seconds: int = 1800  # 30 minutes
+    depth: str = "full"
+
+    # Execution constraints
+    fail_fast: bool = False
+    max_tests: int = 0  # No limit
+
+    # Test selection
+    run_smoke: bool = True
+    run_sanity: bool = True
+    run_regression: bool = True
+
+    # Generation enabled
+    generate_tests: bool = True
+    generate_patches: bool = True
+
+    # Test generation types
+    generate_unit_tests: bool = True
+    generate_integration_tests: bool = True
+    generate_api_tests: bool = True
+    generate_fuzz_tests: bool = True
+    generate_security_tests: bool = True
+
+    # Destructive testing
+    destructive_allowed: bool = True
+    simulate_failures: bool = True
+    stress_testing: bool = True
+    chaos_testing: bool = False  # Advanced - disabled by default
+
+    # QIR settings
+    minimal_qir: bool = False  # Full detailed report
+    include_evidence: bool = True
+    include_metrics: bool = True
+
+    # Flake detection
+    detect_flakes: bool = True
+    retry_count: int = 2
+
+    def to_dict(self) -> Dict[str, Any]:
+        return {
+            "mode": "deep_qe",
+            "timeout_seconds": self.timeout_seconds,
+            "depth": self.depth,
+            "fail_fast": self.fail_fast,
+            "max_tests": self.max_tests,
+            "run_smoke": self.run_smoke,
+            "run_sanity": self.run_sanity,
+            "run_regression": self.run_regression,
+            "generate_tests": self.generate_tests,
+            "generate_patches": self.generate_patches,
+            "test_generation": {
+                "unit": self.generate_unit_tests,
+                "integration": self.generate_integration_tests,
+                "api": self.generate_api_tests,
+                "fuzz": self.generate_fuzz_tests,
+                "security": self.generate_security_tests,
+            },
+            "destructive_testing": {
+                "allowed": self.destructive_allowed,
+                "simulate_failures": self.simulate_failures,
+                "stress_testing": self.stress_testing,
+                "chaos_testing": self.chaos_testing,
+            },
+            "qr": {
+                "minimal": self.minimal_qir,
+                "include_evidence": self.include_evidence,
+                "include_metrics": self.include_metrics,
+            },
+            "flake_detection": {
+                "enabled": self.detect_flakes,
+                "retry_count": self.retry_count,
+            },
+        }
+
+
+def get_qe_mode_config(mode: QEMode) -> QuickScanConfig | DeepQEConfig:
+    """Get the configuration for a QE mode."""
+    if mode == QEMode.QUICK_SCAN:
+        return QuickScanConfig()
+    elif mode == QEMode.DEEP_QE:
+        return DeepQEConfig()
+    else:
+        raise ValueError(f"Unknown QE mode: {mode}")

superqode/execution/resolver.py

@@ -0,0 +1,283 @@
+"""
+Execution Resolver for SuperQode.
+
+Resolves role configurations into execution configs, determining
+whether to use BYOK or ACP mode based on the configuration.
+"""
+
+import os
+from typing import Any, Dict, Optional, Tuple
+
+from .modes import (
+    ACPConfig,
+    BYOKConfig,
+    ExecutionConfig,
+    ExecutionMode,
+    GatewayType,
+)
+from ..providers.registry import PROVIDERS, ProviderDef
+from ..agents.registry import AGENTS, AgentDef, AgentStatus
+
+
+class ExecutionResolverError(Exception):
+    """Base error for execution resolver."""
+
+    pass
+
+
+class ProviderNotFoundError(ExecutionResolverError):
+    """Provider not found in registry."""
+
+    def __init__(self, provider_id: str):
+        self.provider_id = provider_id
+        super().__init__(f"Provider '{provider_id}' not found in registry")
+
+
+class AgentNotFoundError(ExecutionResolverError):
+    """Agent not found in registry."""
+
+    def __init__(self, agent_id: str):
+        self.agent_id = agent_id
+        super().__init__(f"Agent '{agent_id}' not found in registry")
+
+
+class AgentNotSupportedError(ExecutionResolverError):
+    """Agent is not yet supported."""
+
+    def __init__(self, agent_id: str, status: AgentStatus):
+        self.agent_id = agent_id
+        self.status = status
+        super().__init__(f"Agent '{agent_id}' is not yet supported (status: {status.value})")
+
+
+class MissingEnvVarError(ExecutionResolverError):
+    """Required environment variable is missing."""
+
+    def __init__(self, provider_id: str, env_vars: list, docs_url: str):
+        self.provider_id = provider_id
+        self.env_vars = env_vars
+        self.docs_url = docs_url
+        env_list = " or ".join(env_vars)
+        super().__init__(
+            f"Missing API key for provider '{provider_id}'. "
+            f"Set {env_list} environment variable. "
+            f"Get your key at: {docs_url}"
+        )
+
+
+class ExecutionResolver:
+    """Resolves role configurations into execution configs."""
+
+    def __init__(self, gateway: GatewayType = GatewayType.LITELLM):
+        self.gateway = gateway
+
+    def resolve_role(
+        self,
+        role_config: Dict[str, Any],
+        validate_env: bool = True,
+    ) -> ExecutionConfig:
+        """Resolve a role configuration into an execution config.
+
+        Args:
+            role_config: Role configuration dictionary from YAML
+            validate_env: Whether to validate environment variables
+
+        Returns:
+            ExecutionConfig with the appropriate mode
+
+        Raises:
+            ExecutionResolverError: If configuration is invalid
+        """
+        mode = role_config.get("mode", "").lower()
+
+        # Explicit mode declaration
+        if mode == "byok":
+            return self._resolve_byok(role_config, validate_env)
+        elif mode == "acp":
+            return self._resolve_acp(role_config, validate_env)
+
+        # Implicit mode detection (backward compatibility)
+        if "agent" in role_config:
+            return self._resolve_acp(role_config, validate_env)
+        elif "provider" in role_config:
+            return self._resolve_byok(role_config, validate_env)
+
+        # Default to BYOK if provider is specified
+        if role_config.get("provider"):
+            return self._resolve_byok(role_config, validate_env)
+
+        raise ExecutionResolverError(
+            "Role must specify either 'mode: byok' with 'provider' or 'mode: acp' with 'agent'"
+        )
+
+    def _resolve_byok(
+        self,
+        role_config: Dict[str, Any],
+        validate_env: bool,
+    ) -> ExecutionConfig:
+        """Resolve BYOK mode configuration."""
+        provider_id = role_config.get("provider")
+        model = role_config.get("model")
+
+        if not provider_id:
+            raise ExecutionResolverError("BYOK mode requires 'provider'")
+        if not model:
+            raise ExecutionResolverError("BYOK mode requires 'model'")
+
+        # Get provider definition
+        provider_def = PROVIDERS.get(provider_id)
+
+        # Validate environment variables if provider is known
+        if provider_def and validate_env:
+            self._validate_provider_env(provider_def)
+
+        # Build BYOK config
+        byok_config = BYOKConfig(
+            provider=provider_id,
+            model=model,
+            gateway=self.gateway,
+            base_url=role_config.get("base_url"),
+            extra_headers=role_config.get("headers", {}),
+            track_costs=role_config.get("track_costs", True),
+        )
+
+        return ExecutionConfig(
+            mode=ExecutionMode.BYOK,
+            byok=byok_config,
+            job_description=role_config.get("job_description", ""),
+            enabled=role_config.get("enabled", True),
+        )
+
+    def _resolve_acp(
+        self,
+        role_config: Dict[str, Any],
+        validate_env: bool,
+    ) -> ExecutionConfig:
+        """Resolve ACP mode configuration."""
+        agent_id = role_config.get("agent")
+
+        if not agent_id:
+            raise ExecutionResolverError("ACP mode requires 'agent'")
+
+        # Get agent definition
+        agent_def = AGENTS.get(agent_id)
+        if not agent_def:
+            raise AgentNotFoundError(agent_id)
+
+        # Check agent status
+        if agent_def.status != AgentStatus.SUPPORTED:
+            raise AgentNotSupportedError(agent_id, agent_def.status)
+
+        # Get agent config (provider/model for the agent to use)
+        agent_config = role_config.get("agent_config", {})
+
+        # Build ACP config
+        acp_config = ACPConfig(
+            agent=agent_id,
+            agent_provider=agent_config.get("provider"),
+            agent_model=agent_config.get("model"),
+            connection_type=role_config.get("connection_type", "stdio"),
+            command=role_config.get("command", agent_def.command),
+            host=role_config.get("host"),
+            port=role_config.get("port"),
+        )
+
+        return ExecutionConfig(
+            mode=ExecutionMode.ACP,
+            acp=acp_config,
+            job_description=role_config.get("job_description", ""),
+            enabled=role_config.get("enabled", True),
+        )
+
+    def _validate_provider_env(self, provider_def: ProviderDef) -> None:
+        """Validate that required environment variables are set."""
+        if not provider_def.env_vars:
+            # No env vars required (e.g., local providers)
+            return
+
+        # Check if any of the env vars are set
+        for env_var in provider_def.env_vars:
+            if os.environ.get(env_var):
+                return
+
+        # None of the env vars are set
+        raise MissingEnvVarError(
+            provider_def.id,
+            provider_def.env_vars,
+            provider_def.docs_url,
+        )
+
+    def check_provider_status(self, provider_id: str) -> Dict[str, Any]:
+        """Check the status of a provider (env vars, availability).
+
+        Returns:
+            Dictionary with status information
+        """
+        provider_def = PROVIDERS.get(provider_id)
+
+        if not provider_def:
+            return {
+                "provider_id": provider_id,
+                "found": False,
+                "configured": False,
+                "error": f"Provider '{provider_id}' not in registry",
+            }
+
+        # Check env vars
+        configured = False
+        env_var_status = {}
+
+        for env_var in provider_def.env_vars:
+            value = os.environ.get(env_var)
+            env_var_status[env_var] = bool(value)
+            if value:
+                configured = True
+
+        # For local providers with no env vars, check base URL
+        if not provider_def.env_vars:
+            base_url = os.environ.get(
+                provider_def.base_url_env or "", provider_def.default_base_url
+            )
+            configured = bool(base_url)
+
+        return {
+            "provider_id": provider_id,
+            "found": True,
+            "name": provider_def.name,
+            "tier": provider_def.tier.name,
+            "category": provider_def.category.value,
+            "configured": configured,
+            "env_vars": env_var_status,
+            "docs_url": provider_def.docs_url,
+            "notes": provider_def.notes,
+        }
+
+    def check_agent_status(self, agent_id: str) -> Dict[str, Any]:
+        """Check the status of an agent.
+
+        Returns:
+            Dictionary with status information
+        """
+        agent_def = AGENTS.get(agent_id)
+
+        if not agent_def:
+            return {
+                "agent_id": agent_id,
+                "found": False,
+                "available": False,
+                "error": f"Agent '{agent_id}' not in registry",
+            }
+
+        return {
+            "agent_id": agent_id,
+            "found": True,
+            "name": agent_def.name,
+            "protocol": agent_def.protocol.value,
+            "status": agent_def.status.value,
+            "available": agent_def.status == AgentStatus.SUPPORTED,
+            "description": agent_def.description,
+            "auth_info": agent_def.auth_info,
+            "setup_command": agent_def.setup_command,
+            "docs_url": agent_def.docs_url,
+            "capabilities": agent_def.capabilities,
+        }