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

multi_model_debate/__init__.py

@@ -0,0 +1,4 @@
+"""Multi-Model Debate: Let AI models argue so you don't have to."""
+
+__version__ = "1.0.0"
+__all__ = ["__version__"]

multi_model_debate/__main__.py

@@ -0,0 +1,6 @@
+"""Entry point for python -m multi_model_debate."""
+
+from multi_model_debate.cli import app
+
+if __name__ == "__main__":
+    app()

multi_model_debate/cli.py

@@ -0,0 +1,290 @@
+"""CLI interface for adversarial critique."""
+
+from __future__ import annotations
+
+import sys
+from pathlib import Path
+from typing import Annotated
+
+import typer
+from rich.console import Console
+from rich.table import Table
+
+from multi_model_debate import __version__
+from multi_model_debate.config import load_config
+from multi_model_debate.exceptions import AdversarialReviewError
+from multi_model_debate.orchestrator import Orchestrator
+
+app = typer.Typer(
+    name="multi-model-debate",
+    help="Multi-model debate engine for stress-testing proposals before implementation.",
+    add_completion=False,
+)
+console = Console()
+
+
+def version_callback(value: bool) -> None:
+    """Print version and exit."""
+    if value:
+        console.print(f"multi-model-debate {__version__}")
+        raise typer.Exit()
+
+
+@app.callback()
+def main(
+    version: Annotated[
+        bool | None,
+        typer.Option(
+            "--version",
+            "-V",
+            help="Show version and exit.",
+            callback=version_callback,
+            is_eager=True,
+        ),
+    ] = None,
+) -> None:
+    """Multi-Model Debate - Multi-model debate for stress-testing proposals."""
+    pass
+
+
+@app.command()
+def start(
+    game_plan: Annotated[
+        Path | None,
+        typer.Argument(
+            help="Path to game plan file, or '-' for stdin.",
+        ),
+    ] = None,
+    stdin: Annotated[
+        bool,
+        typer.Option(
+            "--stdin",
+            help="Read game plan from stdin.",
+        ),
+    ] = False,
+    config: Annotated[
+        Path | None,
+        typer.Option(
+            "--config",
+            "-c",
+            help="Path to config file (default: auto-detect).",
+        ),
+    ] = None,
+    runs_dir: Annotated[
+        Path | None,
+        typer.Option(
+            "--runs-dir",
+            "-r",
+            help="Directory for run outputs (default: ./runs).",
+        ),
+    ] = None,
+    skip_protocol: Annotated[
+        bool,
+        typer.Option(
+            "--skip-protocol",
+            help="Skip the pre-debate protocol entirely.",
+        ),
+    ] = False,
+    verbose: Annotated[
+        bool,
+        typer.Option(
+            "--verbose",
+            "-v",
+            help="Enable verbose logging.",
+        ),
+    ] = False,
+) -> None:
+    """Start a new adversarial review.
+
+    The game plan should be a markdown document describing the proposal
+    to be stress-tested. Provide via file path or stdin:
+
+      multi-model-debate start proposal.md
+      multi-model-debate start --stdin < proposal.md
+      multi-model-debate start -              # alias for --stdin
+    """
+    # Handle '-' as alias for --stdin
+    use_stdin = stdin or (game_plan is not None and str(game_plan) == "-")
+
+    # Validate mutual exclusion
+    if use_stdin and game_plan is not None and str(game_plan) != "-":
+        console.print("[red]Error:[/red] Cannot use --stdin with a file path")
+        raise typer.Exit(1)
+
+    if not use_stdin and game_plan is None:
+        console.print("[red]Error:[/red] Provide a game plan file or use --stdin")
+        raise typer.Exit(1)
+
+    try:
+        cfg = load_config(config)
+        runs = runs_dir or Path.cwd() / "runs"
+
+        orchestrator = Orchestrator(config=cfg, runs_dir=runs)
+
+        # Create run directory FIRST so progress is tracked and resumable
+        if use_stdin:
+            content = sys.stdin.read()
+            if not content.strip():
+                console.print("[red]Error:[/red] stdin is empty")
+                raise typer.Exit(1)
+            context = orchestrator.start_from_content(content)
+        else:
+            # Type narrowing: game_plan is not None here (checked at line 114-116)
+            assert game_plan is not None
+            # Validate file exists (since we removed exists=True from Argument)
+            if not game_plan.exists():
+                console.print(f"[red]Error:[/red] File not found: {game_plan}")
+                raise typer.Exit(1)
+            if not game_plan.is_file():
+                console.print(f"[red]Error:[/red] Not a file: {game_plan}")
+                raise typer.Exit(1)
+            context = orchestrator.start(game_plan)
+
+        # Run pre-debate protocol (saved to run directory for resume)
+        orchestrator.run_pre_debate_protocol(
+            context=context,
+            skip_protocol=skip_protocol,
+        )
+
+        orchestrator.execute(context)
+
+    except AdversarialReviewError as e:
+        console.print(f"[red]Error:[/red] {e}")
+        raise typer.Exit(1) from None
+    except KeyboardInterrupt:
+        console.print("\n[yellow]Interrupted by user[/yellow]")
+        raise typer.Exit(130) from None
+
+
+@app.command()
+def resume(
+    run_dir: Annotated[
+        Path | None,
+        typer.Option(
+            "--run",
+            "-r",
+            help="Specific run directory to resume (default: latest incomplete).",
+        ),
+    ] = None,
+    config: Annotated[
+        Path | None,
+        typer.Option(
+            "--config",
+            "-c",
+            help="Path to config file (default: auto-detect).",
+        ),
+    ] = None,
+    runs_dir: Annotated[
+        Path | None,
+        typer.Option(
+            "--runs-dir",
+            help="Directory containing runs (default: ./runs).",
+        ),
+    ] = None,
+) -> None:
+    """Resume an incomplete adversarial review.
+
+    Continues from the last checkpoint, skipping already-completed phases.
+    Useful after interruptions or failures.
+    """
+    try:
+        cfg = load_config(config)
+        runs = runs_dir or Path.cwd() / "runs"
+
+        orchestrator = Orchestrator(config=cfg, runs_dir=runs)
+        context = orchestrator.resume(run_dir)
+
+        # Run pre-debate protocol if not already complete
+        # This handles runs that were interrupted during pre-debate
+        orchestrator.run_pre_debate_protocol(context=context)
+
+        orchestrator.execute(context)
+
+    except AdversarialReviewError as e:
+        console.print(f"[red]Error:[/red] {e}")
+        raise typer.Exit(1) from None
+    except KeyboardInterrupt:
+        console.print("\n[yellow]Interrupted by user[/yellow]")
+        raise typer.Exit(130) from None
+
+
+@app.command()
+def status(
+    runs_dir: Annotated[
+        Path | None,
+        typer.Option(
+            "--runs-dir",
+            "-r",
+            help="Directory containing runs (default: ./runs).",
+        ),
+    ] = None,
+    config: Annotated[
+        Path | None,
+        typer.Option(
+            "--config",
+            "-c",
+            help="Path to config file (default: auto-detect).",
+        ),
+    ] = None,
+) -> None:
+    """Show status of the most recent run.
+
+    Displays the current state, completed phases, and game plan
+    for the latest review run.
+    """
+    try:
+        cfg = load_config(config)
+        runs = runs_dir or Path.cwd() / "runs"
+
+        orchestrator = Orchestrator(config=cfg, runs_dir=runs)
+        run_status = orchestrator.status()
+
+        if run_status is None:
+            console.print("[yellow]No runs found[/yellow]")
+            raise typer.Exit(0)
+
+        # Display status
+        console.print()
+        console.print("[bold]Latest Run Status[/bold]")
+        console.print()
+
+        table = Table(show_header=False, box=None)
+        table.add_column("Key", style="cyan")
+        table.add_column("Value")
+
+        table.add_row("Run", run_status["run_dir"])
+        table.add_row("Status", _format_status(run_status["status"]))
+        table.add_row("Game Plan", run_status.get("game_plan") or "N/A")
+
+        console.print(table)
+        console.print()
+
+        # Completed phases
+        phases = run_status.get("completed_phases", [])
+        if phases:
+            console.print("[bold]Completed Phases:[/bold]")
+            for phase in phases:
+                console.print(f"  [green]\u2713[/green] {phase}")
+        else:
+            console.print("[dim]No phases completed yet[/dim]")
+
+        console.print()
+
+    except AdversarialReviewError as e:
+        console.print(f"[red]Error:[/red] {e}")
+        raise typer.Exit(1) from None
+
+
+def _format_status(status: str) -> str:
+    """Format status with color."""
+    colors = {
+        "completed": "[green]completed[/green]",
+        "in_progress": "[yellow]in progress[/yellow]",
+        "failed": "[red]failed[/red]",
+        "unknown": "[dim]unknown[/dim]",
+    }
+    return colors.get(status, status)
+
+
+if __name__ == "__main__":
+    app()

multi_model_debate/config.py

@@ -0,0 +1,271 @@
+"""Configuration management with Pydantic and TOML."""
+
+from __future__ import annotations
+
+import tomllib
+from pathlib import Path
+from typing import Any
+
+from pydantic import BaseModel, Field, model_validator
+
+from multi_model_debate.exceptions import ConfigError
+
+
+class DebateSettings(BaseModel):
+    """Settings for debate rounds."""
+
+    critic_rounds: int = Field(default=4, ge=1, le=10)
+    strategist_rounds: int = Field(default=4, ge=1, le=10)
+    # Backwards compatibility aliases
+    gpt_gemini_rounds: int | None = Field(default=None, exclude=True)
+    strategist_winner_rounds: int | None = Field(default=None, exclude=True)
+
+    def model_post_init(self, __context: Any) -> None:
+        """Handle backwards compatibility for renamed fields."""
+        if self.gpt_gemini_rounds is not None:
+            object.__setattr__(self, "critic_rounds", self.gpt_gemini_rounds)
+        if self.strategist_winner_rounds is not None:
+            object.__setattr__(self, "strategist_rounds", self.strategist_winner_rounds)
+
+
+class RetrySettings(BaseModel):
+    """Settings for retry logic with exponential backoff."""
+
+    max_attempts: int = Field(default=3, ge=1)
+    base_delay: int = Field(default=30, ge=1, description="Base delay in seconds")
+
+
+class ModelSettings(BaseModel):
+    """Settings for model invocations."""
+
+    available: list[str] = Field(
+        default_factory=lambda: ["claude", "gemini", "codex"],
+        description="Available model families for debates",
+    )
+    default_timeout: int = Field(default=300, ge=30, description="Timeout in seconds")
+    min_response_length: int = Field(default=100, ge=10)
+
+
+class CLICommandConfig(BaseModel):
+    """Configuration for a CLI command."""
+
+    command: str
+    subcommand: str | None = None
+    flags: list[str] = Field(default_factory=list)
+    input_mode: str = Field(default="positional", pattern="^(positional|stdin)$")
+    timeout: int | None = Field(
+        default=None,
+        ge=30,
+        description="Per-model timeout in seconds. If not set, uses models.default_timeout.",
+    )
+
+
+class CLISettings(BaseModel):
+    """CLI command configurations for each model.
+
+    Supports dynamic model names via __getitem__ access.
+    Default configurations provided for claude, gemini, codex.
+    """
+
+    model_config = {"extra": "allow"}  # Allow dynamic model names
+
+    codex: CLICommandConfig = Field(
+        default_factory=lambda: CLICommandConfig(
+            command="codex",
+            subcommand="exec",
+            input_mode="stdin",
+        )
+    )
+    gemini: CLICommandConfig = Field(
+        default_factory=lambda: CLICommandConfig(
+            command="gemini",
+            input_mode="positional",
+        )
+    )
+    claude: CLICommandConfig = Field(
+        default_factory=lambda: CLICommandConfig(
+            command="claude",
+            input_mode="positional",
+            flags=[
+                "-p",
+                "--tools",
+                "",
+                "--",
+            ],  # Print mode, disable built-in tools, -- terminates options
+        )
+    )
+
+    def __getitem__(self, name: str) -> CLICommandConfig:
+        """Get CLI config for a model by name."""
+        if hasattr(self, name):
+            value = getattr(self, name)
+            if isinstance(value, CLICommandConfig):
+                return value
+        # Check for extra fields (dynamic models)
+        extra = self.model_extra or {}
+        if name in extra:
+            return CLICommandConfig.model_validate(extra[name])
+        raise KeyError(f"No CLI configuration for model: {name}")
+
+    def get(self, name: str, default: CLICommandConfig | None = None) -> CLICommandConfig | None:
+        """Get CLI config for a model, with optional default."""
+        try:
+            return self[name]
+        except KeyError:
+            return default
+
+
+class NotificationSettings(BaseModel):
+    """Settings for desktop notifications."""
+
+    enabled: bool = True
+    command: str = "notify-send"
+
+
+class RolesSettings(BaseModel):
+    """Settings for dynamic role assignment.
+
+    Supports two modes:
+    - Legacy: Only `strategist` set, derive critics from models.available
+    - Explicit: `critics` list set, use explicit assignments
+
+    DESIGN DECISION: Judge defaults to Strategist's model family (isolated instance)
+
+    The Judge evaluates CRITICS, not the Strategist's plan.
+    Judge reads Critic A vs Critic B arguments and picks winner.
+    Since Judge is different family from both Critics, no bias.
+    """
+
+    strategist: str | None = Field(
+        default=None,
+        description="Override strategist model family. If not set, auto-detect from environment.",
+    )
+    critics: list[str] | None = Field(
+        default=None,
+        description="Explicit list of critic model families. If not set, derived from available.",
+    )
+    judge: str | None = Field(
+        default=None,
+        description="Judge model family. If not set, defaults to strategist.",
+    )
+
+    @model_validator(mode="after")
+    def validate_explicit_critics(self) -> RolesSettings:
+        """Validate explicit critic configuration."""
+        if self.critics is not None:
+            if len(self.critics) < 2:
+                raise ValueError("At least 2 critics required for adversarial debate")
+            if len(self.critics) != len(set(self.critics)):
+                raise ValueError("Duplicate critics not allowed")
+        return self
+
+
+class PreDebateSettings(BaseModel):
+    """Settings for the pre-debate protocol.
+
+    The pre-debate protocol injects the current date context so models
+    can assess proposal relevance against current technology.
+    """
+
+    enabled: bool = Field(
+        default=True,
+        description="Enable the pre-debate protocol.",
+    )
+
+
+class Config(BaseModel):
+    """Main configuration container."""
+
+    debate: DebateSettings = Field(default_factory=DebateSettings)
+    retry: RetrySettings = Field(default_factory=RetrySettings)
+    models: ModelSettings = Field(default_factory=ModelSettings)
+    cli: CLISettings = Field(default_factory=CLISettings)
+    notification: NotificationSettings = Field(default_factory=NotificationSettings)
+    roles: RolesSettings = Field(default_factory=RolesSettings)
+    pre_debate: PreDebateSettings = Field(default_factory=PreDebateSettings)
+
+    @classmethod
+    def from_toml(cls, path: Path) -> Config:
+        """Load configuration from a TOML file."""
+        if not path.exists():
+            raise ConfigError(f"Config file not found: {path}")
+
+        try:
+            with open(path, "rb") as f:
+                data = tomllib.load(f)
+            return cls.model_validate(data)
+        except tomllib.TOMLDecodeError as e:
+            raise ConfigError(f"Invalid TOML in {path}: {e}") from e
+        except Exception as e:
+            raise ConfigError(f"Failed to load config from {path}: {e}") from e
+
+    @classmethod
+    def from_dict(cls, data: dict[str, Any]) -> Config:
+        """Create configuration from a dictionary."""
+        return cls.model_validate(data)
+
+    @classmethod
+    def default(cls) -> Config:
+        """Create default configuration."""
+        return cls()
+
+
+def find_config_file(start_dir: Path | None = None) -> Path | None:
+    """Search for config file in current directory and parents.
+
+    Looks for:
+    - multi_model_debate.toml
+    - .multi_model_debate.toml
+    - pyproject.toml (with [tool.multi-model-debate] section)
+    """
+    if start_dir is None:
+        start_dir = Path.cwd()
+
+    current = start_dir.resolve()
+
+    while current != current.parent:
+        # Check for dedicated config files
+        for name in ["multi_model_debate.toml", ".multi_model_debate.toml"]:
+            config_path = current / name
+            if config_path.exists():
+                return config_path
+
+        # Check pyproject.toml for tool section
+        pyproject = current / "pyproject.toml"
+        if pyproject.exists():
+            try:
+                with open(pyproject, "rb") as f:
+                    data = tomllib.load(f)
+                if "tool" in data and "multi-model-debate" in data["tool"]:
+                    return pyproject
+            except tomllib.TOMLDecodeError:
+                pass
+
+        current = current.parent
+
+    return None
+
+
+def load_config(config_path: Path | None = None) -> Config:
+    """Load configuration from file or use defaults.
+
+    Args:
+        config_path: Explicit path to config file. If None, searches for config.
+
+    Returns:
+        Loaded or default configuration.
+    """
+    if config_path is None:
+        config_path = find_config_file()
+
+    if config_path is None:
+        return Config.default()
+
+    # Handle pyproject.toml specially
+    if config_path.name == "pyproject.toml":
+        with open(config_path, "rb") as f:
+            data = tomllib.load(f)
+        tool_config = data.get("tool", {}).get("multi-model-debate", {})
+        return Config.from_dict(tool_config)
+
+    return Config.from_toml(config_path)

multi_model_debate/exceptions.py

@@ -0,0 +1,83 @@
+"""Exception hierarchy for adversarial critique."""
+
+
+class AdversarialReviewError(Exception):
+    """Base exception for all adversarial review errors."""
+
+    pass
+
+
+class ConfigError(AdversarialReviewError):
+    """Configuration loading or validation error."""
+
+    pass
+
+
+class ModelError(AdversarialReviewError):
+    """Model invocation failed."""
+
+    pass
+
+
+class ModelTimeoutError(ModelError):
+    """Model did not respond within timeout."""
+
+    pass
+
+
+class ModelValidationError(ModelError):
+    """Model response failed validation."""
+
+    pass
+
+
+class PhaseError(AdversarialReviewError):
+    """Phase execution error."""
+
+    pass
+
+
+class CheckpointError(AdversarialReviewError):
+    """Checkpoint loading or saving error."""
+
+    pass
+
+
+class ReviewError(AdversarialReviewError):
+    """General orchestration error."""
+
+    pass
+
+
+class InsufficientCriticsError(ConfigError):
+    """No critics available for adversarial debate.
+
+    Raised when all configured models belong to the same family as
+    the Strategist, leaving zero models to serve as critics.
+    """
+
+    def __init__(self, strategist: str, available: list[str]) -> None:
+        """Initialize with configuration details for actionable error message.
+
+        Args:
+            strategist: The strategist model name.
+            available: List of available model names from config.
+        """
+        self.strategist = strategist
+        self.available = available
+        message = self._build_message()
+        super().__init__(message)
+
+    def _build_message(self) -> str:
+        """Build actionable error message."""
+        available_str = str(self.available)
+        return (
+            "Only one model family configured.\n\n"
+            "Adversarial critique requires at least 2 different model families.\n\n"
+            f"Current config: [models].available = {available_str}\n"
+            f"Strategist: {self.strategist}\n\n"
+            'Fix: Add models from other families (e.g., "codex", "gemini")\n\n'
+            "Tip: For single-model review, skip this tool and prompt directly. For example:\n"
+            "\"Review this proposal from 3 perspectives: devil's advocate, "
+            'domain expert, and end user."'
+        )