dissenter 1.0.2__py3-none-any.whl

dissent/__init__.py

@@ -0,0 +1 @@
+__version__ = "1.0.1"

dissent/cli.py

@@ -0,0 +1,274 @@
+from __future__ import annotations
+
+import asyncio
+from datetime import datetime
+from pathlib import Path
+from typing import Optional, List
+
+import typer
+from rich.console import Console
+from rich.rule import Rule
+from rich.tree import Tree
+
+from .config import DissentConfig, ModelConfig, RoundConfig, load_config
+from .detect import KNOWN_PROVIDERS, detect_api_keys, detect_clis, detect_ollama_models, infer_auth
+from .runner import run_all_rounds
+from .synthesis import synthesize
+
+app = typer.Typer(
+    help="dissenter — multi-LLM debate engine for architectural decisions.",
+    add_completion=False,
+)
+
+out = Console()
+err = Console(stderr=True)
+
+_DEFAULT_DEBATE_ROLES = ["skeptic", "contrarian", "pragmatist", "devil's advocate", "analyst"]
+
+
+# ── Config builders for inline flags ─────────────────────────────────────────
+
+def _config_from_flags(
+    models: list[str],
+    chairman: str | None,
+    output_dir: Path | None,
+) -> DissentConfig:
+    clis = detect_clis()
+    debate_models: list[ModelConfig] = []
+    for i, spec in enumerate(models):
+        # Format: model_id or model_id@role
+        if "@" in spec:
+            model_id, role = spec.rsplit("@", 1)
+        else:
+            model_id = spec
+            role = _DEFAULT_DEBATE_ROLES[i % len(_DEFAULT_DEBATE_ROLES)]
+        extra = {"api_base": "http://localhost:11434"} if model_id.startswith("ollama/") else {}
+        debate_models.append(
+            ModelConfig(id=model_id, role=role, auth=infer_auth(model_id, clis), extra=extra)
+        )
+
+    chair_id = chairman or models[0].split("@")[0]
+    chair_extra = {"api_base": "http://localhost:11434"} if chair_id.startswith("ollama/") else {}
+    chairman_model = ModelConfig(
+        id=chair_id, role="chairman",
+        auth=infer_auth(chair_id, clis), extra=chair_extra,
+    )
+    return DissentConfig(
+        output_dir=output_dir or Path("decisions"),
+        rounds=[
+            RoundConfig(name="debate", models=debate_models),
+            RoundConfig(name="final", models=[chairman_model]),
+        ],
+    )
+
+
+def _config_from_quick(output_dir: Path | None) -> DissentConfig:
+    ollama_models = detect_ollama_models()
+    if not ollama_models:
+        raise RuntimeError(
+            "--quick requires local Ollama models. "
+            "Install Ollama and run 'ollama pull mistral' first."
+        )
+    debate_models = [
+        ModelConfig(
+            id=f"ollama/{m}",
+            role=_DEFAULT_DEBATE_ROLES[i % len(_DEFAULT_DEBATE_ROLES)],
+            extra={"api_base": "http://localhost:11434"},
+        )
+        for i, m in enumerate(ollama_models)
+    ]
+    chairman = ModelConfig(
+        id=f"ollama/{ollama_models[0]}",
+        role="chairman",
+        extra={"api_base": "http://localhost:11434"},
+    )
+    return DissentConfig(
+        output_dir=output_dir or Path("decisions"),
+        rounds=[
+            RoundConfig(name="debate", models=debate_models),
+            RoundConfig(name="final", models=[chairman]),
+        ],
+    )
+
+
+# ── Commands ──────────────────────────────────────────────────────────────────
+
+@app.command()
+def ask(
+    question: str = typer.Argument(..., help="The question to debate"),
+    config: Optional[Path] = typer.Option(None, "--config", "-c", help="Config file path"),
+    output_dir: Optional[Path] = typer.Option(None, "--output", "-o", help="Output directory"),
+    model: Optional[List[str]] = typer.Option(
+        None, "--model", "-m",
+        help="model_id[@role] for the debate round — repeat for multiple models",
+    ),
+    chairman: Optional[str] = typer.Option(
+        None, "--chairman", help="Model ID for the final (synthesis) round"
+    ),
+    quick: bool = typer.Option(
+        False, "--quick", help="Auto-detect installed Ollama models and run immediately"
+    ),
+) -> None:
+    """Run the full debate pipeline and synthesize a decision.
+
+    Config priority: --quick > --model/--chairman > --config / dissenter.toml
+    """
+    try:
+        if quick:
+            cfg = _config_from_quick(output_dir)
+        elif model:
+            cfg = _config_from_flags(list(model), chairman, output_dir)
+        else:
+            cfg = load_config(config)
+            if output_dir:
+                cfg.output_dir = output_dir
+    except (FileNotFoundError, RuntimeError) as e:
+        err.print(f"[red]Error:[/red] {e}")
+        raise typer.Exit(1)
+
+    total_models = sum(len(r.active_models) for r in cfg.rounds)
+    err.print()
+    err.print(Rule("[bold]dissenter[/bold]"))
+    err.print(f"  [dim]Question:[/dim] {question}")
+    err.print(f"  [dim]Rounds  :[/dim] {len(cfg.rounds)}")
+    err.print(f"  [dim]Models  :[/dim] {total_models} across all rounds")
+    err.print()
+
+    try:
+        all_rounds, final_text, synthesis_results = asyncio.run(_main(question, cfg))
+    except RuntimeError as e:
+        err.print()
+        err.print(f"[red]Error:[/red] {e}")
+        err.print()
+        raise typer.Exit(1)
+
+    # Save outputs — everything lives under decisions/<timestamp>/
+    ts = datetime.now().strftime("%Y%m%d_%H%M%S")
+    run_dir = cfg.output_dir / ts
+    run_dir.mkdir(parents=True, exist_ok=True)
+
+    for rr in all_rounds:
+        round_dir = run_dir / f"round_{rr.round_index + 1}_{rr.round_name}"
+        round_dir.mkdir()
+        for r in rr.results:
+            safe = r.model_id.replace("/", "_").replace(":", "_")
+            role_safe = r.role.replace(" ", "_").replace("'", "")
+            fname = f"{safe}__{role_safe}"
+            (round_dir / f"{fname}.md").write_text(r.content or "")
+            if r.error:
+                (round_dir / f"{fname}.err").write_text(r.error)
+
+    final_round_dir = run_dir / f"round_{len(all_rounds)}_{cfg.rounds[-1].name or 'final'}"
+    final_round_dir.mkdir(exist_ok=True)
+    for r in synthesis_results:
+        safe = r.model_id.replace("/", "_").replace(":", "_")
+        role_safe = r.role.replace(" ", "_").replace("'", "")
+        (final_round_dir / f"{safe}__{role_safe}.md").write_text(r.content or "")
+
+    output_file = run_dir / "decision.md"
+    output_file.write_text(final_text)
+
+    abs_file = output_file.absolute()
+    abs_dir = run_dir.absolute()
+
+    err.print()
+    err.print(Rule("[bold green]Done[/bold green]"))
+    err.print(f"  [green]Decision :[/green] [link=file://{abs_file}]{abs_file}[/link]")
+    err.print(f"  [dim]Run dir  : [link=file://{abs_dir}]{abs_dir}[/link][/dim]")
+    err.print()
+
+
+@app.command()
+def init(
+    output: Path = typer.Option(Path("dissenter.toml"), "--output", "-o", help="Config file to create"),
+    force: bool = typer.Option(False, "--force", "-f", help="Overwrite without prompting"),
+) -> None:
+    """Interactively create a dissenter.toml config file."""
+    from .wizard import run_wizard
+    run_wizard(output, force, err)
+
+
+@app.command()
+def models() -> None:
+    """Show detected local models, CLI tools, and API key status."""
+    from rich.table import Table
+
+    ollama = detect_ollama_models()
+    clis = detect_clis()
+    api_keys = detect_api_keys()
+
+    out.print()
+
+    # Ollama
+    out.print("[bold]Ollama (local)[/bold]")
+    if ollama:
+        for m in ollama:
+            out.print(f"  [green]✓[/green]  {m}")
+    else:
+        out.print("  [dim]no models — is ollama running? try: ollama pull mistral[/dim]")
+
+    # CLI tools
+    out.print()
+    out.print("[bold]CLI tools[/bold]")
+    for cli, path in clis.items():
+        if path:
+            out.print(f"  [green]✓[/green]  {cli:<10} [dim]{path}[/dim]")
+        else:
+            out.print(f"  [dim]✗  {cli}   not found[/dim]")
+
+    # API providers
+    out.print()
+    out.print("[bold]API providers[/bold]")
+    for provider, env_var in KNOWN_PROVIDERS.items():
+        has_key = api_keys[provider]
+        tick = "[green]✓[/green]" if has_key else "[dim]✗[/dim]"
+        note = "[green]key set[/green]" if has_key else f"[dim]export {env_var}[/dim]"
+        out.print(f"  {tick}  {provider:<18} {note}")
+
+    out.print()
+
+
+@app.command()
+def show(
+    config: Optional[Path] = typer.Option(None, "--config", "-c", help="Config file path"),
+) -> None:
+    """Show the current configuration — rounds, models, roles."""
+    try:
+        cfg = load_config(config)
+    except FileNotFoundError as e:
+        err.print(f"[red]Error:[/red] {e}")
+        raise typer.Exit(1)
+
+    tree = Tree(f"[bold]dissenter[/bold]  [dim]{cfg.output_dir}[/dim]")
+    for i, round_cfg in enumerate(cfg.rounds):
+        label = f"Round {i+1}: [cyan]{round_cfg.name or '(unnamed)'}[/cyan]"
+        if i == len(cfg.rounds) - 1:
+            label += "  [yellow][final][/yellow]"
+        r_node = tree.add(label)
+        for m in round_cfg.models:
+            status = "[green]✓[/green]" if m.enabled else "[dim]—[/dim]"
+            r_node.add(
+                f"{status} [bold]{m.id}[/bold]  [dim]role:[/dim] {m.role}  "
+                f"[dim]auth:[/dim] {m.auth}  [dim]timeout:[/dim] {m.timeout}s"
+            )
+        if round_cfg.combine_model:
+            r_node.add(f"[dim]combine via:[/dim] {round_cfg.combine_model}")
+
+    out.print(tree)
+
+    if cfg.role_distribution:
+        out.print()
+        out.print("[dim]Role distribution:[/dim]")
+        for role, weight in cfg.role_distribution.items():
+            out.print(f"  {role}: {weight:.0%}")
+
+
+async def _main(question: str, cfg: DissentConfig):
+    err.print(Rule("[dim]beginning debate[/dim]", style="dim"))
+    all_rounds = await run_all_rounds(cfg, question)
+
+    err.print()
+    err.print(Rule("[dim]synthesizing[/dim]", style="dim"))
+
+    final_text, synthesis_results = await synthesize(question, all_rounds, cfg)
+    return all_rounds, final_text, synthesis_results

dissent/config.py

@@ -0,0 +1,96 @@
+from __future__ import annotations
+
+import random
+import tomllib
+from pathlib import Path
+from typing import Any
+
+from platformdirs import user_config_dir
+from pydantic import BaseModel, Field, model_validator
+
+
+class ModelConfig(BaseModel):
+    id: str
+    role: str = "analyst"
+    enabled: bool = True
+    timeout: int = 180
+    # API auth (default): litellm reads key from env var, or use api_key to override
+    api_key: str | None = None
+    # CLI auth: shell out to the provider's CLI tool instead of the API
+    # auth = "cli" uses the CLI's stored session (e.g. a logged-in `claude` install)
+    auth: str = "api"           # "api" | "cli"
+    cli_command: str | None = None  # e.g. "claude", "gemini"; inferred from provider if None
+    extra: dict[str, Any] = Field(default_factory=dict)
+
+
+class RoundConfig(BaseModel):
+    name: str = ""
+    models: list[ModelConfig] = Field(default_factory=list)
+    combine_model: str | None = None
+    combine_timeout: int = 60
+
+    @property
+    def active_models(self) -> list[ModelConfig]:
+        return [m for m in self.models if m.enabled]
+
+
+class DissentConfig(BaseModel):
+    output_dir: Path = Path("decisions")
+    default_model: str | None = None
+    rounds: list[RoundConfig] = Field(default_factory=list)
+    role_distribution: dict[str, float] = Field(default_factory=dict)
+
+    @model_validator(mode="after")
+    def validate_rounds(self) -> "DissentConfig":
+        if not self.rounds:
+            raise ValueError("At least one [[rounds]] block must be configured")
+        last = self.rounds[-1]
+        n = len(last.active_models)
+        if n not in (1, 2):
+            raise ValueError(
+                f"Final round must have exactly 1 or 2 enabled models, got {n}. "
+                "Use 1 model with role 'chairman', or 2 models with a combine_model."
+            )
+        if n == 2 and last.combine_model is None:
+            raise ValueError(
+                "Final round with 2 models requires combine_model to be set "
+                "(the model that merges their dual recommendations side-by-side)."
+            )
+        return self
+
+    @property
+    def is_dual_final(self) -> bool:
+        return len(self.rounds[-1].active_models) == 2
+
+
+def load_config(path: Path | None = None) -> DissentConfig:
+    candidates: list[Path] = []
+    if path:
+        candidates.append(path)
+    candidates.append(Path("dissenter.toml"))
+    candidates.append(Path(user_config_dir("dissenter")) / "config.toml")
+
+    for candidate in candidates:
+        if candidate.exists():
+            data = tomllib.loads(candidate.read_text())
+            return DissentConfig.model_validate(data)
+
+    raise FileNotFoundError(
+        "No dissenter.toml found. Create one with `dissenter init` or pass --config <path>."
+    )
+
+
+def assign_random_roles(
+    model_ids: list[str],
+    distribution: dict[str, float],
+) -> list[tuple[str, str]]:
+    """Randomly assign roles from a weighted distribution to a list of model IDs.
+
+    Returns list of (model_id, role) pairs.
+    """
+    if not distribution:
+        raise ValueError("role_distribution must be non-empty for random assignment")
+    roles = list(distribution.keys())
+    weights = list(distribution.values())
+    assigned = random.choices(roles, weights=weights, k=len(model_ids))
+    return list(zip(model_ids, assigned))

dissent/detect.py

@@ -0,0 +1,65 @@
+from __future__ import annotations
+
+import os
+import shutil
+import subprocess
+
+# Known providers and the env var that holds their API key
+KNOWN_PROVIDERS: dict[str, str] = {
+    "anthropic": "ANTHROPIC_API_KEY",
+    "openai": "OPENAI_API_KEY",
+    "gemini": "GEMINI_API_KEY",
+    "mistral": "MISTRAL_API_KEY",
+    "groq": "GROQ_API_KEY",
+    "cohere": "CO_API_KEY",
+    "together_ai": "TOGETHERAI_API_KEY",
+    "openrouter": "OPENROUTER_API_KEY",
+}
+
+
+def detect_ollama_models() -> list[str]:
+    """Return list of locally installed Ollama model names."""
+    try:
+        result = subprocess.run(
+            ["ollama", "list"],
+            capture_output=True,
+            text=True,
+            timeout=5,
+        )
+        if result.returncode != 0:
+            return []
+        lines = result.stdout.strip().splitlines()
+        models: list[str] = []
+        for line in lines[1:]:  # skip NAME header
+            parts = line.split()
+            if parts:
+                models.append(parts[0])
+        return models
+    except Exception:
+        return []
+
+
+def detect_clis() -> dict[str, str | None]:
+    """Return mapping of CLI name -> absolute path (None if not found)."""
+    return {
+        "claude": shutil.which("claude"),
+        "gemini": shutil.which("gemini"),
+    }
+
+
+def detect_api_keys() -> dict[str, bool]:
+    """Return mapping of provider name -> whether its env var is set."""
+    return {
+        provider: bool(os.environ.get(env_var))
+        for provider, env_var in KNOWN_PROVIDERS.items()
+    }
+
+
+def infer_auth(model_id: str, clis: dict[str, str | None]) -> str:
+    """Return 'cli' if a CLI tool is available for this model's provider, else 'api'."""
+    provider = model_id.split("/")[0]
+    if provider == "anthropic" and clis.get("claude"):
+        return "cli"
+    if provider in ("gemini", "google") and clis.get("gemini"):
+        return "cli"
+    return "api"

dissent/roles/analyst.toml

@@ -0,0 +1,3 @@
+name = "analyst"
+description = "Rigorous balanced analysis with concrete numbers"
+prompt = "Your role is balanced analyst. Be rigorous and cite specific trade-offs with concrete numbers and real-world examples where possible."

dissent/roles/chairman.toml

@@ -0,0 +1,3 @@
+name = "chairman"
+description = "Decisive synthesis after all debate"
+prompt = "Your role is chairman. You have read all the debate that preceded you. Synthesize into a decisive, actionable recommendation. Do not hedge. Make the call."

dissent/roles/conservative.toml

@@ -0,0 +1,3 @@
+name = "conservative"
+description = "Pragmatic executor — safest proven path"
+prompt = "Your role is the pragmatic executor. Given all preceding debate, recommend the safest, most proven path forward. Favor what can be shipped, maintained, and reversed if wrong. Be terse — your output will be placed side-by-side with the liberal view."

dissent/roles/contrarian.toml

@@ -0,0 +1,3 @@
+name = "contrarian"
+description = "Surface the minority expert view and missed nuance"
+prompt = "Your role is contrarian. What would the minority expert view look like? What important nuance does the mainstream consensus miss?"

dissent/roles/devils_advocate.toml

@@ -0,0 +1,3 @@
+name = "devil's advocate"
+description = "Argue against the obvious or popular choice"
+prompt = "Your role is devil's advocate. Argue against the obvious or popular choice. Find the strongest case for what most experts would dismiss."

dissent/roles/liberal.toml

@@ -0,0 +1,3 @@
+name = "liberal"
+description = "Ambitious visionary — boldest high-upside path"
+prompt = "Your role is the ambitious visionary. Given all preceding debate, recommend the boldest, highest-upside path forward. Favor what could be transformative if it works. Be terse — your output will be placed side-by-side with the conservative view."

dissent/roles/pragmatist.toml

@@ -0,0 +1,3 @@
+name = "pragmatist"
+description = "Focus on what actually works in production at scale"
+prompt = "Your role is pragmatist. Focus on what actually works in production at scale. Ignore theoretical elegance — what does real-world deployment look like?"

dissent/roles/researcher.toml

@@ -0,0 +1,3 @@
+name = "researcher"
+description = "Find the most current information using web access"
+prompt = "Your role is researcher. Use your web access to find the most current information. Focus on recent developments, version changes, and community momentum since 2024."

dissent/roles/second_opinion.toml

@@ -0,0 +1,3 @@
+name = "second opinion"
+description = "Fresh-eyes independent review"
+prompt = "Your role is independent reviewer. Approach this with fresh eyes, question assumptions, and highlight anything the other analyses might miss."

dissent/roles/skeptic.toml

@@ -0,0 +1,3 @@
+name = "skeptic"
+description = "Find hidden failure modes and long-term risks"
+prompt = "Your role is skeptic. What are the hidden failure modes, long-term maintenance costs, and risks nobody is talking about? Assume the optimistic case is wrong."

dissent/roles.py

@@ -0,0 +1,29 @@
+from __future__ import annotations
+
+import tomllib
+from pathlib import Path
+
+_ROLES_DIR = Path(__file__).parent / "roles"
+
+_FALLBACK_PROMPT = (
+    "Your role is balanced analyst. Be rigorous and cite specific trade-offs "
+    "with concrete numbers and real-world examples where possible."
+)
+
+
+def load_roles() -> dict[str, str]:
+    """Return mapping of role name → prompt text, loaded from roles/*.toml."""
+    roles: dict[str, str] = {}
+    for path in _ROLES_DIR.glob("*.toml"):
+        data = tomllib.loads(path.read_text())
+        name = data.get("name", path.stem)
+        prompt = data.get("prompt", _FALLBACK_PROMPT)
+        roles[name] = prompt
+    return roles
+
+
+def get_prompt(role: str, roles: dict[str, str] | None = None) -> str:
+    """Return the prompt for a role, falling back to analyst if unknown."""
+    if roles is None:
+        roles = load_roles()
+    return roles.get(role, _FALLBACK_PROMPT)

dissent/runner.py

@@ -0,0 +1,318 @@
+from __future__ import annotations
+
+import asyncio
+import time
+from dataclasses import dataclass, field
+from typing import Optional
+
+import litellm
+from rich.console import Console
+from rich.live import Live
+from rich.rule import Rule
+from rich.table import Table
+from rich.text import Text
+
+from .config import DissentConfig, ModelConfig, RoundConfig
+from .roles import get_prompt, load_roles
+
+litellm.suppress_debug_info = True
+
+console = Console(stderr=True)
+
+_SPECIALIST_PROMPT = """\
+You are a senior software architect. {role_instruction}
+
+{prior_context}Analyze this question:
+{question}
+
+Respond in this exact markdown structure:
+
+## Recommendation
+[Your clear, opinionated recommendation in 1-2 sentences]
+
+## Pros
+- [bullet]
+
+## Cons / Risks
+- [bullet]
+
+## Critical Considerations
+- [bullet]
+
+## Recent Developments (2024-2026)
+[Relevant ecosystem changes. Note if you have no web access.]
+
+Be direct, technical, and opinionated. Engineers will act on this.
+"""
+
+_PRIOR_CONTEXT_TEMPLATE = """\
+[Prior debate — Round {index}: "{name}"]
+
+{responses}
+
+[End prior debate]
+
+"""
+
+
+@dataclass
+class ModelResult:
+    model_id: str
+    role: str
+    round_name: str
+    content: str = ""
+    elapsed: float = 0.0
+    error: Optional[str] = None
+
+    @property
+    def success(self) -> bool:
+        return bool(self.content) and self.error is None
+
+    @property
+    def word_count(self) -> int:
+        return len(self.content.split())
+
+    @property
+    def short_id(self) -> str:
+        return self.model_id.split("/")[-1]
+
+
+@dataclass
+class RoundResult:
+    round_name: str
+    round_index: int
+    results: list[ModelResult] = field(default_factory=list)
+
+    @property
+    def successful(self) -> list[ModelResult]:
+        return [r for r in self.results if r.success]
+
+
+def _build_prior_context(prior_rounds: list[RoundResult]) -> str:
+    if not prior_rounds:
+        return ""
+    parts = []
+    for rr in prior_rounds:
+        responses = "\n\n".join(
+            f"**{r.short_id}** (role: {r.role}):\n{r.content}"
+            for r in rr.successful
+        )
+        parts.append(
+            _PRIOR_CONTEXT_TEMPLATE.format(
+                index=rr.round_index + 1,
+                name=rr.round_name,
+                responses=responses,
+            )
+        )
+    return "".join(parts)
+
+
+# Known provider → CLI command mappings
+_PROVIDER_CLI: dict[str, str] = {
+    "anthropic": "claude",
+    "gemini": "gemini",
+    "google": "gemini",
+}
+
+
+def _infer_cli(model_id: str) -> str | None:
+    provider = model_id.split("/")[0]
+    return _PROVIDER_CLI.get(provider)
+
+
+async def _query_model_cli(cfg: ModelConfig, prompt: str) -> str:
+    """Query a model via its CLI tool, using the CLI's stored session auth."""
+    cli = cfg.cli_command or _infer_cli(cfg.id)
+    if not cli:
+        raise ValueError(
+            f"No CLI command known for provider '{cfg.id.split('/')[0]}'. "
+            "Set cli_command in config (e.g. cli_command = \"claude\")."
+        )
+
+    # All CLIs: pass prompt via stdin with non-interactive/print flag
+    # claude: `claude --print`   gemini: `gemini`  (add more as needed)
+    cli_args: list[str] = [cli]
+    if cli == "claude":
+        cli_args += ["--print"]
+
+    proc = await asyncio.create_subprocess_exec(
+        *cli_args,
+        stdin=asyncio.subprocess.PIPE,
+        stdout=asyncio.subprocess.PIPE,
+        stderr=asyncio.subprocess.PIPE,
+    )
+    stdout, stderr = await proc.communicate(input=prompt.encode())
+    if proc.returncode != 0:
+        err_text = stderr.decode().strip()
+        raise RuntimeError(err_text or f"'{cli}' exited with code {proc.returncode}")
+    return stdout.decode().strip()
+
+
+def _classify_error(exc: Exception) -> str:
+    msg = str(exc)
+    t = type(exc).__name__
+    if "AuthenticationError" in t or "authentication" in msg.lower() or "api key" in msg.lower() or "Missing API Key" in msg:
+        provider = msg.split(":")[0].strip() if ":" in msg else "provider"
+        return f"missing/invalid API key ({provider}) — set the env var or add api_key to config"
+    if "NotFoundError" in t or "model not found" in msg.lower() or (
+        "pull" in msg.lower() and "ollama" in msg.lower()
+    ):
+        return "model not installed — run 'ollama pull <model>' first"
+    if "APIConnectionError" in t or "Connection refused" in msg or "OllamaError" in t:
+        if "not found" in msg.lower() or "try pulling" in msg.lower():
+            return "model not installed — run 'ollama pull <model>' first"
+        if "ollama" in msg.lower() or "11434" in msg:
+            return "cannot reach Ollama — is 'ollama serve' running?"
+        return f"connection failed — is the server running? ({msg[:80]})"
+    if "RateLimitError" in t:
+        return "rate limited — wait and retry, or switch models"
+    if "ContextWindowExceededError" in t or "context length" in msg.lower():
+        return "context window exceeded — debate history too long for this model"
+    return msg[:120]
+
+
+async def _query_model(
+    cfg: ModelConfig,
+    round_name: str,
+    question: str,
+    prior_context: str,
+    role_prompts: dict[str, str],
+) -> ModelResult:
+    role_instruction = get_prompt(cfg.role, role_prompts)
+    prompt = _SPECIALIST_PROMPT.format(
+        role_instruction=role_instruction,
+        prior_context=prior_context,
+        question=question,
+    )
+    start = time.monotonic()
+    result = ModelResult(model_id=cfg.id, role=cfg.role, round_name=round_name)
+
+    try:
+        if cfg.auth == "cli":
+            result.content = await asyncio.wait_for(
+                _query_model_cli(cfg, prompt),
+                timeout=cfg.timeout,
+            )
+        else:
+            kwargs: dict = {
+                "model": cfg.id,
+                "messages": [{"role": "user", "content": prompt}],
+                **cfg.extra,
+            }
+            if cfg.api_key:
+                kwargs["api_key"] = cfg.api_key
+            response = await asyncio.wait_for(
+                litellm.acompletion(**kwargs),
+                timeout=cfg.timeout,
+            )
+            result.content = response.choices[0].message.content or ""
+        result.elapsed = time.monotonic() - start
+    except asyncio.TimeoutError:
+        result.error = f"timed out after {cfg.timeout}s"
+        result.elapsed = float(cfg.timeout)
+    except Exception as exc:
+        result.error = _classify_error(exc)
+        result.elapsed = time.monotonic() - start
+
+    return result
+
+
+def _status_table(
+    round_name: str,
+    round_index: int,
+    results: dict[str, ModelResult],
+    done: set[str],
+    start_times: dict[str, float],
+) -> Table:
+    now = time.monotonic()
+    table = Table(
+        title=f"Round {round_index + 1}: {round_name}",
+        show_header=True,
+        header_style="bold",
+        box=None,
+        padding=(0, 1),
+    )
+    table.add_column("Model", min_width=26)
+    table.add_column("Role", min_width=18)
+    table.add_column("Time", justify="right", min_width=6)
+    table.add_column("Status", min_width=22)
+
+    for key, result in results.items():
+        elapsed = result.elapsed if key in done else now - start_times[key]
+        elapsed_str = f"{elapsed:.0f}s"
+
+        if key not in done:
+            status = Text("⠸ running", style="yellow")
+        elif result.error:
+            status = Text(f"✗ {result.error[:35]}", style="red")
+        else:
+            status = Text(f"✓  ~{result.word_count} words", style="green")
+
+        table.add_row(result.short_id, result.role, elapsed_str, status)
+
+    return table
+
+
+async def run_round(
+    round_cfg: RoundConfig,
+    round_index: int,
+    question: str,
+    prior_rounds: list[RoundResult],
+    role_prompts: dict[str, str],
+) -> RoundResult:
+    active = round_cfg.active_models
+    prior_context = _build_prior_context(prior_rounds)
+    round_name = round_cfg.name or f"round_{round_index + 1}"
+
+    # Use (model_id, role, index) as unique key to support same model with different roles
+    keys = [f"{m.id}::{m.role}::{i}" for i, m in enumerate(active)]
+    results: dict[str, ModelResult] = {
+        k: ModelResult(model_id=m.id, role=m.role, round_name=round_name)
+        for k, m in zip(keys, active)
+    }
+    done: set[str] = set()
+    start_times: dict[str, float] = {k: time.monotonic() for k in keys}
+
+    async def run_and_track(key: str, cfg: ModelConfig) -> None:
+        result = await _query_model(cfg, round_name, question, prior_context, role_prompts)
+        results[key] = result
+        done.add(key)
+
+    tasks = [asyncio.create_task(run_and_track(k, m)) for k, m in zip(keys, active)]
+
+    with Live(console=console, refresh_per_second=4, transient=False) as live:
+        while not all(t.done() for t in tasks):
+            live.update(_status_table(round_name, round_index, results, done, start_times))
+            await asyncio.sleep(0.25)
+        live.update(_status_table(round_name, round_index, results, done, start_times))
+
+    round_result = RoundResult(round_name=round_name, round_index=round_index)
+    round_result.results = list(results.values())
+    return round_result
+
+
+async def run_all_rounds(
+    cfg: DissentConfig,
+    question: str,
+) -> list[RoundResult]:
+    role_prompts = load_roles()
+    all_results: list[RoundResult] = []
+
+    for i, round_cfg in enumerate(cfg.rounds):
+        active = round_cfg.active_models
+        if not active:
+            console.print(f"[yellow]Round {i+1} '{round_cfg.name}' has no enabled models, skipping.[/yellow]")
+            continue
+
+        console.print()
+        console.print(Rule(f"[bold]Round {i+1} of {len(cfg.rounds)}: {round_cfg.name or ''}[/bold] ({len(active)} models)", style="dim"))
+
+        rr = await run_round(round_cfg, i, question, all_results, role_prompts)
+        all_results.append(rr)
+
+        if not rr.successful:
+            raise RuntimeError(
+                f"All models failed in round {i+1} '{round_cfg.name}'. Cannot continue."
+            )
+
+    return all_results

dissent/synthesis.py

@@ -0,0 +1,232 @@
+from __future__ import annotations
+
+import asyncio
+from datetime import date
+
+import litellm
+
+from .config import DissentConfig, ModelConfig, RoundConfig
+from .roles import get_prompt, load_roles
+from .runner import ModelResult, RoundResult, _query_model_cli
+
+_SYNTHESIS_PROMPT = """\
+You are a principal architect writing a formal Architectural Decision Record (ADR).
+
+Multiple AI models debated across {n_rounds} round(s). Here are all their outputs:
+
+{all_round_outputs}
+
+---
+
+Synthesize into an ADR using this EXACT structure (do not deviate):
+
+# ADR: [derive a concise title]
+
+**Date:** {date}
+**Status:** Proposed
+**Debate rounds:** {n_rounds} | **Models consulted:** {n_models_total}
+
+## Context
+[2-3 sentences on the problem and why this decision matters]
+
+## Consensus
+[What most/all models agreed on — high-confidence signals]
+
+## Disagreements
+[Where models diverged. For each: what was the disagreement, why it matters, what context would resolve it]
+
+## Options Considered
+
+| Option | Pros | Cons | Risk Level |
+|--------|------|------|------------|
+
+## Decision
+**[The recommendation in one clear sentence.]**
+
+[2-3 paragraphs of rationale: draw on consensus, resolve disagreements, be explicit about what assumptions this decision rests on]
+
+## Consequences
+
+### Positive
+- [bullet]
+
+### Risks
+- [bullet]
+
+### Mitigations
+- [bullet]
+
+## Open Questions
+[Points that require your specific context — team size, existing stack, constraints — that no model could know]
+
+---
+*Synthesized by dissenter from {n_models_total} model responses across {n_rounds} round(s)*
+
+Be ruthlessly clear, technically precise, and opinionated. No filler.
+"""
+
+_DUAL_ARBITER_PROMPT = """\
+You are a senior architect. Your role: {role_instruction}
+
+All preceding debate is below. Read it carefully, then write your recommendation.
+
+{all_round_outputs}
+
+---
+
+Question: {question}
+
+Write a terse, opinionated recommendation. Your output will be shown side-by-side with another architect's view.
+
+## Your Recommendation
+[1 clear sentence]
+
+## Why
+[2-3 bullet points max]
+
+## Risks
+[1-2 bullet points max]
+
+## What would change your answer
+[1 sentence]
+"""
+
+_COMBINE_PROMPT = """\
+Two senior architects reviewed the same debate and provided their recommendations.
+Format them side by side for the human to compare and decide.
+
+CONSERVATIVE view (pragmatic executor — safest proven path):
+{conservative_output}
+
+LIBERAL view (ambitious visionary — boldest high-upside path):
+{liberal_output}
+
+Format as this EXACT structure:
+
+# Dual Recommendation: {title}
+
+**Date:** {date}
+**Question:** {question}
+
+---
+
+## Conservative View — Ship It
+{conservative_output}
+
+---
+
+## Liberal View — Go Bold
+{liberal_output}
+
+---
+
+## Key Divergence
+[2-3 sentences: what is the core difference between these two views, and what specific context (team size, risk tolerance, timeline, existing stack) would make one more appropriate than the other]
+"""
+
+
+def _format_all_rounds(all_rounds: list[RoundResult]) -> str:
+    parts = []
+    for rr in all_rounds:
+        header = f"### Round {rr.round_index + 1}: {rr.round_name}"
+        parts.append(header)
+        for r in rr.successful:
+            parts.append(f"\n**{r.short_id}** (role: *{r.role}*)\n\n{r.content}")
+            parts.append("\n---")
+    return "\n".join(parts)
+
+
+async def _call_model(cfg: ModelConfig, prompt: str) -> str:
+    if cfg.auth == "cli":
+        return await asyncio.wait_for(
+            _query_model_cli(cfg, prompt),
+            timeout=float(cfg.timeout),
+        )
+    kwargs: dict = {
+        "model": cfg.id,
+        "messages": [{"role": "user", "content": prompt}],
+        **(cfg.extra or {}),
+    }
+    if cfg.api_key:
+        kwargs["api_key"] = cfg.api_key
+    response = await asyncio.wait_for(
+        litellm.acompletion(**kwargs),
+        timeout=float(cfg.timeout),
+    )
+    return response.choices[0].message.content or ""
+
+
+async def synthesize(
+    question: str,
+    all_rounds: list[RoundResult],
+    cfg: DissentConfig,
+) -> tuple[str, list[ModelResult]]:
+    """
+    Returns (final_text, final_model_results).
+    final_model_results contains the synthesis model outputs for saving to debug dir.
+    """
+    role_prompts = load_roles()
+    final_round = cfg.rounds[-1]
+    active = final_round.active_models
+    all_round_outputs = _format_all_rounds(all_rounds[:-1] if len(all_rounds) == len(cfg.rounds) else all_rounds)
+
+    # Count total models consulted across all debate rounds (not final)
+    debate_rounds = all_rounds[:-1] if len(all_rounds) >= len(cfg.rounds) else all_rounds
+    n_models_total = sum(len(rr.successful) for rr in all_rounds)
+
+    if len(active) == 1:
+        # Single chairman/arbiter
+        arbiter = active[0]
+        prompt = _SYNTHESIS_PROMPT.format(
+            question=question,
+            all_round_outputs=_format_all_rounds(all_rounds),
+            date=date.today().isoformat(),
+            n_rounds=len(all_rounds),
+            n_models_total=n_models_total,
+        )
+        content = await _call_model(arbiter, prompt)
+        result = ModelResult(
+            model_id=arbiter.id, role=arbiter.role, round_name=final_round.name or "final",
+            content=content, elapsed=0.0,
+        )
+        return content, [result]
+
+    else:
+        # Dual arbiter: conservative + liberal
+        debate_context = _format_all_rounds(all_rounds)
+
+        async def call_arbiter(m) -> ModelResult:
+            role_instruction = get_prompt(m.role, role_prompts)
+            prompt = _DUAL_ARBITER_PROMPT.format(
+                role_instruction=role_instruction,
+                all_round_outputs=debate_context,
+                question=question,
+            )
+            content = await _call_model(m, prompt)
+            return ModelResult(
+                model_id=m.id, role=m.role, round_name=final_round.name or "final",
+                content=content, elapsed=0.0,
+            )
+
+        results = await asyncio.gather(*[call_arbiter(m) for m in active])
+
+        # Identify conservative vs liberal
+        conservative_result = next((r for r in results if r.role == "conservative"), results[0])
+        liberal_result = next((r for r in results if r.role == "liberal"), results[1])
+
+        # Combine side-by-side
+        title = question[:60] + ("..." if len(question) > 60 else "")
+        combine_prompt = _COMBINE_PROMPT.format(
+            conservative_output=conservative_result.content,
+            liberal_output=liberal_result.content,
+            title=title,
+            date=date.today().isoformat(),
+            question=question,
+        )
+        combine_cfg = ModelConfig(
+            id=final_round.combine_model,
+            role="combiner",
+            timeout=final_round.combine_timeout,
+        )
+        combined = await _call_model(combine_cfg, combine_prompt)
+        return combined, list(results)

dissent/wizard.py

@@ -0,0 +1,143 @@
+from __future__ import annotations
+
+from pathlib import Path
+
+import typer
+from rich.console import Console
+from rich.panel import Panel
+
+from .detect import detect_clis, detect_ollama_models, infer_auth
+
+_DEBATE_ROLES = [
+    "skeptic",
+    "contrarian",
+    "pragmatist",
+    "devil's advocate",
+    "analyst",
+    "researcher",
+]
+
+
+def _collect_model(
+    label: str,
+    clis: dict[str, str | None],
+    default_role: str,
+    console: Console,
+) -> dict:
+    console.print(f"\n  [bold]{label}[/bold]")
+    model_id = typer.prompt("    ID (e.g. ollama/mistral, anthropic/claude-sonnet-4-6)")
+    role = typer.prompt("    Role", default=default_role)
+    auth = typer.prompt("    Auth (api/cli)", default=infer_auth(model_id, clis))
+    timeout = int(typer.prompt("    Timeout (s)", default="180"))
+    m: dict = {"id": model_id, "role": role, "auth": auth, "timeout": timeout}
+    if model_id.startswith("ollama/"):
+        api_base = typer.prompt("    Ollama API base", default="http://localhost:11434")
+        m["extra"] = {"api_base": api_base}
+    return m
+
+
+def _render_toml(rounds_data: list[dict], output_dir: str) -> str:
+    lines = [
+        "# dissenter — multi-LLM debate engine",
+        f'output_dir = "{output_dir}"',
+        "",
+    ]
+    for i, rd in enumerate(rounds_data):
+        is_final = i == len(rounds_data) - 1
+        label = f"Final round: {rd['name']}" if is_final else f"Round {i + 1}: {rd['name']}"
+        fill = "─" * max(4, 52 - len(label))
+        lines.append(f"# ── {label} {fill}")
+        lines.append("[[rounds]]")
+        lines.append(f'name = "{rd["name"]}"')
+        if rd.get("combine_model"):
+            lines.append(f'combine_model   = "{rd["combine_model"]}"')
+            lines.append(f'combine_timeout = {rd.get("combine_timeout", 60)}')
+        lines.append("")
+        for m in rd["models"]:
+            lines.append("[[rounds.models]]")
+            lines.append(f'id      = "{m["id"]}"')
+            lines.append(f'role    = "{m["role"]}"')
+            if m.get("auth") == "cli":
+                lines.append(f'auth    = "cli"')
+            lines.append(f'timeout = {m["timeout"]}')
+            if m.get("extra"):
+                kv = ", ".join(f'{k} = "{v}"' for k, v in m["extra"].items())
+                lines.append(f'extra   = {{ {kv} }}')
+            lines.append("")
+    return "\n".join(lines).rstrip() + "\n"
+
+
+def run_wizard(output_path: Path, force: bool, console: Console) -> None:
+    """Interactive config wizard. Writes a dissent.toml to output_path."""
+    clis = detect_clis()
+    ollama_models = detect_ollama_models()
+
+    env_lines: list[str] = []
+    for cli, path in clis.items():
+        if path:
+            env_lines.append(f"  [green]✓[/green] {cli} CLI   [dim]{path}[/dim]")
+        else:
+            env_lines.append(f"  [dim]✗ {cli} CLI   not found[/dim]")
+    if ollama_models:
+        env_lines.append(
+            f"  [green]✓[/green] Ollama   [dim]{', '.join(ollama_models)}[/dim]"
+        )
+    else:
+        env_lines.append("  [dim]✗ Ollama   not found or no models installed[/dim]")
+
+    console.print(Panel("\n".join(env_lines), title="[bold]dissenter init[/bold]", expand=False))
+    console.print()
+
+    if output_path.exists() and not force:
+        if not typer.confirm(f"{output_path} already exists. Overwrite?", default=False):
+            raise typer.Exit(0)
+
+    output_dir = typer.prompt("Output directory", default="decisions")
+    n_debate = int(typer.prompt("Debate rounds (not counting final)", default="1"))
+
+    rounds_data: list[dict] = []
+
+    for ri in range(n_debate):
+        console.print(f"\n[bold]── Round {ri + 1} ──[/bold]")
+        name = typer.prompt("  Name", default="debate" if ri == 0 else f"round_{ri + 1}")
+        n_models = int(typer.prompt("  Models", default="2"))
+        models = [
+            _collect_model(
+                f"Model {mi + 1}", clis, _DEBATE_ROLES[mi % len(_DEBATE_ROLES)], console
+            )
+            for mi in range(n_models)
+        ]
+        rounds_data.append({"name": name, "models": models})
+
+    console.print("\n[bold]── Final Round ──[/bold]")
+    final_type = typer.prompt("  Type (chairman/dual)", default="chairman")
+    final_name = typer.prompt("  Name", default="final")
+
+    if final_type == "dual":
+        con = _collect_model("Conservative model", clis, "conservative", console)
+        con["role"] = "conservative"
+        lib = _collect_model("Liberal model", clis, "liberal", console)
+        lib["role"] = "liberal"
+        combine = typer.prompt("  Combine model ID")
+        combine_timeout = int(typer.prompt("  Combine timeout (s)", default="60"))
+        rounds_data.append({
+            "name": final_name,
+            "models": [con, lib],
+            "combine_model": combine,
+            "combine_timeout": combine_timeout,
+        })
+    else:
+        chair = _collect_model("Chairman model", clis, "chairman", console)
+        chair["role"] = "chairman"
+        rounds_data.append({"name": final_name, "models": [chair]})
+
+    toml_content = _render_toml(rounds_data, output_dir)
+    console.print("\n[bold]── Preview ──[/bold]\n")
+    console.print(toml_content)
+
+    if typer.confirm(f"Save to {output_path}?", default=True):
+        output_path.write_text(toml_content)
+        console.print(f"\n[green]✓[/green] Saved [bold]{output_path}[/bold]")
+        console.print(f"  Run [bold]dissenter ask \"your question\"[/bold] to get started.")
+    else:
+        console.print("[dim]Cancelled.[/dim]")

dissenter-1.0.2.dist-info/METADATA

@@ -0,0 +1,13 @@
+Metadata-Version: 2.4
+Name: dissenter
+Version: 1.0.2
+Summary: Multi-LLM debate engine for architectural decisions
+Requires-Python: >=3.11
+Requires-Dist: litellm>=1.62.0
+Requires-Dist: platformdirs>=4.3.0
+Requires-Dist: pydantic>=2.9.0
+Requires-Dist: rich>=13.9.0
+Requires-Dist: typer>=0.12.0
+Provides-Extra: dev
+Requires-Dist: pytest-asyncio>=0.24; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'

dissenter-1.0.2.dist-info/RECORD

@@ -0,0 +1,22 @@
+dissent/__init__.py,sha256=d4QHYmS_30j0hPN8NmNPnQ_Z0TphDRbu4MtQj9cT9e8,22
+dissent/cli.py,sha256=MNK6ubB3Ra_pKkIbMDxUUbgRb4fTlt1-gvN4K_c1-BI,9869
+dissent/config.py,sha256=5s4bGKAAB2xdQUGmLgFNYCxhtd1176YyJifNLT-aFQQ,3341
+dissent/detect.py,sha256=M13r9v5GddSB-AgXtDtbHPXMAXw3jjY6XRuLD2_0x74,1904
+dissent/roles.py,sha256=HOkeB8Rpw5-ykq1E7W2V9Kk0XK6Hdi9IrDVq58suXpM,921
+dissent/runner.py,sha256=HAJ2KoygHCseZoAdbLRNhow5fxzPM3az5Y52nXV_y04,9969
+dissent/synthesis.py,sha256=3e2SixvIuiPUq89-3BiX3BKBtBJQacsW3ZhcTM2060k,6858
+dissent/wizard.py,sha256=6GYl8GgDPGIbY2AnWXcIM1BaD_b8a0YBZ6j-DIbkWFg,5538
+dissent/roles/analyst.toml,sha256=5GovW6THlT_BG016C_MmCQLIX0DVrdpcgWtnumwOC9A,227
+dissent/roles/chairman.toml,sha256=6L-ZAo3fvbHODBEem3qmRzelhYL4-dQ5n4J7Rd1JWH0,236
+dissent/roles/conservative.toml,sha256=RMyy-AQuwFW_skck3c_5OF8yrOupymb2xL4vnmCkluw,342
+dissent/roles/contrarian.toml,sha256=OiDYiD4bgwjB9SeupVp_rGXuSrrIeN3WVKxPgDLlHvw,228
+dissent/roles/devils_advocate.toml,sha256=vaJnhVtNXBdAlyX8IlF_IO4TNQvqjQsvdr5zPd0VliU,234
+dissent/roles/liberal.toml,sha256=rP5PsRLPgEF2_5W8sJc_lCwo09x51GRQe52lVlTbrCg,340
+dissent/roles/pragmatist.toml,sha256=4hTm4mHVMo9Re6399qiz-WVBLr5D9iGyHD3LDSLDNRU,252
+dissent/roles/researcher.toml,sha256=H7GQhwJXyhtwLeQKGfmLQ_-pzQ4C7V2onhtXCkEWAFU,263
+dissent/roles/second_opinion.toml,sha256=BZu-Dw6Z1FJpzFjPR_Cqn0qAuRfATQeq7Y3wR0dvfuA,223
+dissent/roles/skeptic.toml,sha256=p9lUoeH8FbmtYlEqVHBUVzfmLMzmcpDSAMW7lDXCzVU,248
+dissenter-1.0.2.dist-info/METADATA,sha256=KN8V_NSxEo85Boan0yyWG-dI2VIp2LVQ4Ij_Y1wC34Y,407
+dissenter-1.0.2.dist-info/WHEEL,sha256=QccIxa26bgl1E6uMy58deGWi-0aeIkkangHcxk2kWfw,87
+dissenter-1.0.2.dist-info/entry_points.txt,sha256=UnjlVR-sazqqILOfWbfpO8XeJN9UgikeRNOUb8HgZiI,46
+dissenter-1.0.2.dist-info/RECORD,,

dissenter-1.0.2.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.29.0
+Root-Is-Purelib: true
+Tag: py3-none-any

dissenter-1.0.2.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+dissenter = dissent.cli:app