multi-model-debate 1.0.1__py3-none-any.whl

multi_model_debate/models/__init__.py

@@ -0,0 +1,71 @@
+"""Model backends for CLI-based AI model invocations."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from multi_model_debate.models.claude import (
+    ClaudeBackend,
+    StrategistBackend,
+    create_claude_backend,
+    create_claude_interactive_backend,  # Deprecated, kept for backwards compat
+    create_strategist_backend,
+)
+from multi_model_debate.models.cli_wrapper import CLIModelBackend
+from multi_model_debate.models.gemini import GeminiBackend, create_gemini_backend
+from multi_model_debate.models.openai import CodexBackend, create_codex_backend
+from multi_model_debate.models.protocols import ModelBackend
+
+if TYPE_CHECKING:
+    from multi_model_debate.config import CLICommandConfig, RetrySettings
+
+
+def create_cli_backend(
+    name: str,
+    cli_config: CLICommandConfig,
+    retry_config: RetrySettings,
+    min_response_length: int = 100,
+    default_timeout: int = 300,
+) -> CLIModelBackend:
+    """Create a CLI model backend for any model.
+
+    This is a generic factory that works with any CLI-based model.
+    Use this for dynamic model loading from config.
+
+    Args:
+        name: Human-readable model name (e.g., 'GPT', 'Gemini', 'Claude').
+        cli_config: CLI command configuration from config.
+        retry_config: Retry settings for exponential backoff.
+        min_response_length: Minimum chars for valid response.
+        default_timeout: Global default timeout (per-model config takes priority).
+
+    Returns:
+        A CLIModelBackend instance configured for the model.
+    """
+    return CLIModelBackend(
+        name=name.upper(),
+        cli_config=cli_config,
+        retry_config=retry_config,
+        min_response_length=min_response_length,
+        default_timeout=default_timeout,
+    )
+
+
+__all__ = [
+    # Protocols
+    "ModelBackend",
+    # Base
+    "CLIModelBackend",
+    # Implementations
+    "CodexBackend",
+    "GeminiBackend",
+    "ClaudeBackend",
+    "StrategistBackend",
+    # Factories
+    "create_cli_backend",
+    "create_codex_backend",
+    "create_gemini_backend",
+    "create_claude_backend",
+    "create_strategist_backend",
+    "create_claude_interactive_backend",  # Deprecated
+]

multi_model_debate/models/claude.py

@@ -0,0 +1,168 @@
+"""Claude CLI model backend with Strategist support."""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import TYPE_CHECKING
+
+from rich.console import Console
+
+from multi_model_debate.models.cli_wrapper import CLIModelBackend
+
+if TYPE_CHECKING:
+    from multi_model_debate.config import CLICommandConfig, RetrySettings
+
+console = Console()
+
+
+class ClaudeBackend(CLIModelBackend):
+    """Claude CLI backend for non-interactive invocations.
+
+    Used for Phase 3 (judge) where Claude makes a one-shot determination.
+    """
+
+    def __init__(
+        self,
+        cli_config: CLICommandConfig,
+        retry_config: RetrySettings,
+        min_response_length: int = 100,
+        error_log: Path | None = None,
+    ) -> None:
+        """Initialize the Claude backend.
+
+        Args:
+            cli_config: CLI command configuration.
+            retry_config: Retry settings for exponential backoff.
+            min_response_length: Minimum chars for valid response.
+            error_log: Optional path to log stderr output.
+        """
+        super().__init__(
+            name="Claude",
+            cli_config=cli_config,
+            retry_config=retry_config,
+            min_response_length=min_response_length,
+            error_log=error_log,
+        )
+
+
+class StrategistBackend(CLIModelBackend):
+    """CLI-based backend for Strategist in Phases 5-6.
+
+    The Strategist is the AI assistant with full context that authored the
+    game plan. It defends the proposal automatically using CLI invocation,
+    just like other model backends.
+
+    DESIGN: Fully automated via CLI calls, same as other model backends.
+    """
+
+    def __init__(
+        self,
+        cli_config: CLICommandConfig,
+        retry_config: RetrySettings,
+        min_response_length: int = 100,
+        error_log: Path | None = None,
+        default_timeout: int = 300,
+    ) -> None:
+        """Initialize the Strategist backend.
+
+        Args:
+            cli_config: CLI command configuration (uses claude CLI).
+            retry_config: Retry settings for exponential backoff.
+            min_response_length: Minimum chars for valid response.
+            error_log: Optional path to log stderr output.
+            default_timeout: Default timeout if not specified in cli_config.
+        """
+        super().__init__(
+            name="Strategist",
+            cli_config=cli_config,
+            retry_config=retry_config,
+            min_response_length=min_response_length,
+            error_log=error_log,
+            default_timeout=default_timeout,
+        )
+
+
+def create_claude_backend(
+    cli_config: CLICommandConfig,
+    retry_config: RetrySettings,
+    min_response_length: int = 100,
+    error_log: Path | None = None,
+) -> ClaudeBackend:
+    """Factory function to create a non-interactive Claude backend.
+
+    Args:
+        cli_config: CLI command configuration.
+        retry_config: Retry settings.
+        min_response_length: Minimum response length.
+        error_log: Optional error log path.
+
+    Returns:
+        Configured ClaudeBackend instance.
+    """
+    return ClaudeBackend(
+        cli_config=cli_config,
+        retry_config=retry_config,
+        min_response_length=min_response_length,
+        error_log=error_log,
+    )
+
+
+def create_strategist_backend(
+    cli_config: CLICommandConfig,
+    retry_config: RetrySettings,
+    min_response_length: int = 100,
+    error_log: Path | None = None,
+    default_timeout: int = 300,
+) -> StrategistBackend:
+    """Factory function to create a Strategist backend.
+
+    The Strategist uses the configured CLI for automated responses.
+    See REQUIREMENTS_V2.md Section 4 for rationale on full automation.
+
+    Args:
+        cli_config: CLI command configuration.
+        retry_config: Retry settings for exponential backoff.
+        min_response_length: Minimum response length.
+        error_log: Optional error log path.
+        default_timeout: Default timeout if not specified in cli_config.
+
+    Returns:
+        Configured StrategistBackend instance.
+    """
+    return StrategistBackend(
+        cli_config=cli_config,
+        retry_config=retry_config,
+        min_response_length=min_response_length,
+        error_log=error_log,
+        default_timeout=default_timeout,
+    )
+
+
+# Backwards compatibility alias (deprecated)
+def create_claude_interactive_backend(
+    min_response_length: int = 100,
+) -> StrategistBackend:
+    """Deprecated: Use create_strategist_backend instead.
+
+    This function is kept for backwards compatibility but will be removed.
+    It creates a StrategistBackend with default CLI config.
+    """
+    import warnings
+
+    from multi_model_debate.config import CLICommandConfig, RetrySettings
+
+    warnings.warn(
+        "create_claude_interactive_backend is deprecated, use create_strategist_backend",
+        DeprecationWarning,
+        stacklevel=2,
+    )
+    # Create with defaults - caller should use create_strategist_backend instead
+    default_cli = CLICommandConfig(
+        command="claude", input_mode="positional", flags=["-p", "--tools", "", "--"]
+    )
+    default_retry = RetrySettings(max_attempts=3, base_delay=30)
+    return StrategistBackend(
+        cli_config=default_cli,
+        retry_config=default_retry,
+        min_response_length=min_response_length,
+    )

multi_model_debate/models/cli_wrapper.py

@@ -0,0 +1,233 @@
+"""Generic CLI subprocess wrapper with retry logic."""
+
+from __future__ import annotations
+
+import subprocess
+import sys
+import time
+from dataclasses import dataclass
+from pathlib import Path
+from typing import TYPE_CHECKING
+
+from multi_model_debate.exceptions import (
+    ModelError,
+    ModelTimeoutError,
+    ModelValidationError,
+)
+from multi_model_debate.response_parser import is_valid_response
+
+if TYPE_CHECKING:
+    from multi_model_debate.config import CLICommandConfig, RetrySettings
+
+
+@dataclass
+class CLIResult:
+    """Result of a CLI invocation."""
+
+    stdout: str
+    stderr: str
+    return_code: int
+
+
+class CLIModelBackend:
+    """Generic wrapper for CLI-based model invocations.
+
+    Implements the ModelBackend protocol by invoking external CLI tools
+    via subprocess with retry logic and response validation.
+    """
+
+    def __init__(
+        self,
+        name: str,
+        cli_config: CLICommandConfig,
+        retry_config: RetrySettings,
+        min_response_length: int = 100,
+        error_log: Path | None = None,
+        default_timeout: int = 300,
+    ) -> None:
+        """Initialize the CLI model backend.
+
+        Args:
+            name: Human-readable model name (e.g., 'GPT', 'Gemini').
+            cli_config: CLI command configuration.
+            retry_config: Retry settings for exponential backoff.
+            min_response_length: Minimum chars for valid response.
+            error_log: Optional path to log stderr output.
+            default_timeout: Default timeout if not specified in cli_config or call.
+        """
+        self._name = name
+        self.cli_config = cli_config
+        self.retry_config = retry_config
+        self.min_response_length = min_response_length
+        self.error_log = error_log
+        # Per-model timeout from config, or global default
+        self.default_timeout = cli_config.timeout or default_timeout
+
+    @property
+    def name(self) -> str:
+        """Human-readable model name."""
+        return self._name
+
+    def generate(self, prompt: str, timeout: int | None = None) -> str:
+        """Execute CLI with retry logic.
+
+        Args:
+            prompt: The input prompt.
+            timeout: Maximum time per attempt in seconds. If not specified,
+                     uses the model's configured timeout.
+
+        Returns:
+            The validated response text.
+
+        Raises:
+            ModelError: If all retry attempts fail.
+            ModelTimeoutError: If timeout exceeded.
+            ModelValidationError: If response fails validation.
+        """
+        # Use per-model timeout if not explicitly provided
+        if timeout is None:
+            timeout = self.default_timeout
+
+        last_error: Exception | None = None
+
+        for attempt in range(self.retry_config.max_attempts):
+            try:
+                result = self._execute(prompt, timeout)
+                response = result.stdout
+                self._validate_response(response)
+                return response
+
+            except subprocess.TimeoutExpired as e:
+                last_error = ModelTimeoutError(f"{self.name} timed out after {timeout}s")
+                self._log_error(f"Attempt {attempt + 1}: Timeout - {e}")
+
+            except ModelError as e:
+                last_error = e
+                self._log_error(f"Attempt {attempt + 1}: {e}")
+
+            # Exponential backoff before retry
+            if attempt < self.retry_config.max_attempts - 1:
+                delay = self.retry_config.base_delay * (2**attempt)
+                time.sleep(delay)
+
+        raise ModelError(
+            f"{self.name} failed after {self.retry_config.max_attempts} attempts"
+        ) from last_error
+
+    def _execute(self, prompt: str, timeout: int) -> CLIResult:
+        """Execute the CLI command.
+
+        Args:
+            prompt: The input prompt.
+            timeout: Maximum time to wait in seconds.
+
+        Returns:
+            CLIResult with stdout, stderr, and return code.
+
+        Raises:
+            ModelError: If command returns non-zero exit code.
+            subprocess.TimeoutExpired: If timeout exceeded.
+        """
+        cmd = self._build_command(prompt)
+
+        if self.cli_config.input_mode == "stdin":
+            result = subprocess.run(
+                cmd,
+                input=prompt,
+                capture_output=True,
+                text=True,
+                timeout=timeout,
+            )
+        else:
+            result = subprocess.run(
+                cmd,
+                capture_output=True,
+                text=True,
+                timeout=timeout,
+            )
+
+        cli_result = CLIResult(
+            stdout=result.stdout,
+            stderr=result.stderr,
+            return_code=result.returncode,
+        )
+
+        # Log stderr if present
+        if result.stderr:
+            self._log_error(f"stderr: {result.stderr}")
+
+        if result.returncode != 0:
+            raise ModelError(f"{self.name} returned exit code {result.returncode}: {result.stderr}")
+
+        return cli_result
+
+    def _build_command(self, prompt: str) -> list[str]:
+        """Build the command list for subprocess.
+
+        Args:
+            prompt: The input prompt (used for positional mode).
+
+        Returns:
+            List of command arguments.
+        """
+        cmd = [self.cli_config.command]
+
+        if self.cli_config.subcommand:
+            cmd.append(self.cli_config.subcommand)
+
+        if self.cli_config.flags:
+            cmd.extend(self.cli_config.flags)
+
+        if self.cli_config.input_mode == "stdin":
+            cmd.append("-")
+        else:
+            cmd.append(prompt)
+
+        return cmd
+
+    def _validate_response(self, response: str) -> None:
+        """Validate the response meets quality criteria.
+
+        Uses JSON-aware validation that accepts:
+        - Valid JSON responses (any length)
+        - Legacy "NO NEW ISSUES" format (backwards compatibility)
+        - Non-JSON responses meeting minimum length
+
+        See REQUIREMENTS_V2.md Section 6 for structured output rationale.
+
+        Args:
+            response: The response text to validate.
+
+        Raises:
+            ModelValidationError: If validation fails.
+        """
+        if not response:
+            raise ModelValidationError(f"{self.name} returned empty response")
+
+        # Use JSON-aware validation from response_parser
+        if is_valid_response(response, self.min_response_length):
+            return
+
+        # Provide detailed error with response preview for debugging
+        preview = response[:200] + "..." if len(response) > 200 else response
+        raise ModelValidationError(
+            f"{self.name} response too short ({len(response)} chars, "
+            f"min {self.min_response_length}). Preview: {preview!r}"
+        )
+
+    def _log_error(self, message: str) -> None:
+        """Log an error message to stderr and optionally to file.
+
+        Always logs to stderr for visibility during debugging.
+        Also logs to error_log file if configured.
+
+        Args:
+            message: The error message to log.
+        """
+        # Always log to stderr for debugging visibility
+        print(f"[{self.name}] {message}", file=sys.stderr)
+
+        # Also log to file if configured
+        if self.error_log:
+            with open(self.error_log, "a") as f:
+                f.write(f"[{self.name}] {message}\n")

multi_model_debate/models/gemini.py

@@ -0,0 +1,66 @@
+"""Google Gemini CLI model backend."""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import TYPE_CHECKING
+
+from multi_model_debate.models.cli_wrapper import CLIModelBackend
+
+if TYPE_CHECKING:
+    from multi_model_debate.config import CLICommandConfig, RetrySettings
+
+
+class GeminiBackend(CLIModelBackend):
+    """Gemini CLI backend for Google model invocations.
+
+    Wraps the `gemini <prompt>` command which takes prompt as positional argument.
+    """
+
+    def __init__(
+        self,
+        cli_config: CLICommandConfig,
+        retry_config: RetrySettings,
+        min_response_length: int = 100,
+        error_log: Path | None = None,
+    ) -> None:
+        """Initialize the Gemini backend.
+
+        Args:
+            cli_config: CLI command configuration.
+            retry_config: Retry settings for exponential backoff.
+            min_response_length: Minimum chars for valid response.
+            error_log: Optional path to log stderr output.
+        """
+        super().__init__(
+            name="Gemini",
+            cli_config=cli_config,
+            retry_config=retry_config,
+            min_response_length=min_response_length,
+            error_log=error_log,
+        )
+
+
+def create_gemini_backend(
+    cli_config: CLICommandConfig,
+    retry_config: RetrySettings,
+    min_response_length: int = 100,
+    error_log: Path | None = None,
+) -> GeminiBackend:
+    """Factory function to create a Gemini backend.
+
+    Args:
+        cli_config: CLI command configuration.
+        retry_config: Retry settings.
+        min_response_length: Minimum response length.
+        error_log: Optional error log path.
+
+    Returns:
+        Configured GeminiBackend instance.
+    """
+    return GeminiBackend(
+        cli_config=cli_config,
+        retry_config=retry_config,
+        min_response_length=min_response_length,
+        error_log=error_log,
+    )

multi_model_debate/models/openai.py

@@ -0,0 +1,66 @@
+"""OpenAI/Codex CLI model backend."""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import TYPE_CHECKING
+
+from multi_model_debate.models.cli_wrapper import CLIModelBackend
+
+if TYPE_CHECKING:
+    from multi_model_debate.config import CLICommandConfig, RetrySettings
+
+
+class CodexBackend(CLIModelBackend):
+    """Codex CLI backend for GPT model invocations.
+
+    Wraps the `codex exec -` command which reads prompts from stdin.
+    """
+
+    def __init__(
+        self,
+        cli_config: CLICommandConfig,
+        retry_config: RetrySettings,
+        min_response_length: int = 100,
+        error_log: Path | None = None,
+    ) -> None:
+        """Initialize the Codex backend.
+
+        Args:
+            cli_config: CLI command configuration (typically codex exec).
+            retry_config: Retry settings for exponential backoff.
+            min_response_length: Minimum chars for valid response.
+            error_log: Optional path to log stderr output.
+        """
+        super().__init__(
+            name="GPT",
+            cli_config=cli_config,
+            retry_config=retry_config,
+            min_response_length=min_response_length,
+            error_log=error_log,
+        )
+
+
+def create_codex_backend(
+    cli_config: CLICommandConfig,
+    retry_config: RetrySettings,
+    min_response_length: int = 100,
+    error_log: Path | None = None,
+) -> CodexBackend:
+    """Factory function to create a Codex backend.
+
+    Args:
+        cli_config: CLI command configuration.
+        retry_config: Retry settings.
+        min_response_length: Minimum response length.
+        error_log: Optional error log path.
+
+    Returns:
+        Configured CodexBackend instance.
+    """
+    return CodexBackend(
+        cli_config=cli_config,
+        retry_config=retry_config,
+        min_response_length=min_response_length,
+        error_log=error_log,
+    )

multi_model_debate/models/protocols.py

@@ -0,0 +1,35 @@
+"""Protocol definitions for model backends."""
+
+from typing import Protocol, runtime_checkable
+
+
+@runtime_checkable
+class ModelBackend(Protocol):
+    """Protocol for model backends that can generate responses.
+
+    All models (including Strategist) implement this protocol using
+    CLI-based invocation. See REQUIREMENTS_V2.md Section 4.
+    """
+
+    @property
+    def name(self) -> str:
+        """Human-readable model name (e.g., 'GPT', 'Gemini', 'Strategist')."""
+        ...
+
+    def generate(self, prompt: str, timeout: int | None = None) -> str:
+        """Generate a response from the model.
+
+        Args:
+            prompt: The input prompt.
+            timeout: Maximum time to wait in seconds. If not specified,
+                     uses the model's configured default timeout.
+
+        Returns:
+            The model's response text.
+
+        Raises:
+            ModelError: If generation fails after retries.
+            ModelTimeoutError: If timeout is exceeded.
+            ModelValidationError: If response fails validation.
+        """
+        ...