contrarian 0.2.0__tar.gz

contrarian-0.2.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Anthony Micho
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

contrarian-0.2.0/PKG-INFO

@@ -0,0 +1,143 @@
+Metadata-Version: 2.4
+Name: contrarian
+Version: 0.2.0
+Summary: MCP server adding an independent second LLM perspective (Judge B) with full project graph context
+Author-email: Anthony Micho <anthony.micho76@gmail.com>
+License-Expression: MIT
+Project-URL: Repository, https://github.com/anthonymicho/contrarian
+Keywords: mcp,llm,code-review,claude,judge
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Software Development :: Quality Assurance
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: mcp
+Requires-Dist: openai>=1.0
+Requires-Dist: python-dotenv
+Requires-Dist: networkx>=3.4
+Requires-Dist: graphifyy[leiden]
+Requires-Dist: json-repair>=0.6
+Provides-Extra: all
+Requires-Dist: graphifyy[all]; extra == "all"
+Dynamic: license-file
+
+# Contrarian
+
+MCP server that adds a second LLM perspective (Judge B) directly inside Claude Code.
+
+Claude Code is Judge A — it already has full project context. Contrarian adds Judge B, an independent model from a different lab, via a single tool call. Same rubric, different priors, no context switch.
+
+---
+
+## How it works
+
+1. Claude Code invokes `contrarian_review()` — no args for auto-detect, or pass specific files.
+2. Contrarian resolves the input: git diff, last commit, or full audit (in that order).
+3. Judge B (external model) reviews against `JUDGE.md` in the project root.
+4. Findings are returned inline and appended to `REPORT.md` for the dialogue log.
+
+Auto-detect order:
+- **diff** — any staged/unstaged changes or untracked files
+- **last-commit** — clean tree → reviews the last commit
+- **audit** — forced with `audit=true`, or nothing else found
+
+---
+
+## Installation
+
+Requires Python 3.10+. You'll need a free API key from [DeepSeek](https://platform.deepseek.com) (no credit card required).
+
+```bash
+pip install contrarian
+contrarian setup
+```
+
+`contrarian setup` prompts for your API key, then writes the MCP server config to `~/.claude/.claude.json` automatically. Restart Claude Code after running it.
+
+That's it.
+
+---
+
+### Manual config (alternative)
+
+If you prefer to configure manually, add to `~/.claude/.claude.json`:
+
+```json
+{
+  "mcpServers": {
+    "contrarian": {
+      "type": "stdio",
+      "command": "contrarian",
+      "args": [],
+      "env": {
+        "JUDGE_B_API_KEY": "sk-or-...",
+        "JUDGE_B_BASE_URL": "https://openrouter.ai/api/v1"
+      }
+    }
+  }
+}
+```
+
+Default provider is DeepSeek (`api.deepseek.com`, model `deepseek-chat`). Change `JUDGE_B_BASE_URL` and `JUDGE_B_MODEL` to use any OpenAI-compatible provider (Gemini, Groq, Ollama, OpenRouter, etc.).
+
+Anthropic models are blocked at runtime — Judge B must come from a different lab than Judge A.
+
+---
+
+## Usage
+
+Inside any Claude Code session, the tool is available as `contrarian_review`.
+
+```
+contrarian_review()                                    # auto-detect mode
+contrarian_review({ path: "src/auth.py" })             # single file, diff
+contrarian_review({ path: "src/auth.py", full: true }) # full file
+contrarian_review({ paths: ["src/a.py", "src/b.py"] }) # multi-file, reviewed as a unit
+contrarian_review({ audit: true })                     # force full repo walk
+contrarian_review({ model: "google/gemini-3.1-pro-preview" }) # one-off model override
+```
+
+---
+
+## Rubric
+
+Place a `JUDGE.md` at the project root to customize what Judge B looks for. Without it, a built-in fallback rubric applies.
+
+The built-in rubric covers four dimensions:
+
+| Dimension | What to find |
+|---|---|
+| **Exactitude** | Logic errors, wrong assumptions, incorrect implementation |
+| **Missing** | Unhandled cases, absent validation, unconsidered implications |
+| **Premises** | Assumptions that could be wrong |
+| **Alternatives** | Fundamentally different approaches |
+
+Output is always JSON:
+
+```json
+{
+  "exactitude": { "verdict": "ok|warn|fail", "findings": [] },
+  "missing": [],
+  "premises": [],
+  "alternatives": []
+}
+```
+
+---
+
+## Report log
+
+Findings are appended to `REPORT.md` at the project root under `[Judge B]` blocks. Claude Code annotates findings under `[Judge A]` blocks. Judge B reads previous exchanges before each review — closed findings (`addressed`, `won't fix`, `disagree`) are not re-raised.
+
+---
+
+## Phase roadmap
+
+- **Phase 2 (current):** MCP server + project graph context. Auto-detect mode. Python rewrite.
+- **Phase 3:** Operational hardening — token budget guard, graph latency, detached HEAD handling.
+- **Phase 4:** Agent watchdog — autonomous background review on commit.

contrarian-0.2.0/README.md

@@ -0,0 +1,115 @@
+# Contrarian
+
+MCP server that adds a second LLM perspective (Judge B) directly inside Claude Code.
+
+Claude Code is Judge A — it already has full project context. Contrarian adds Judge B, an independent model from a different lab, via a single tool call. Same rubric, different priors, no context switch.
+
+---
+
+## How it works
+
+1. Claude Code invokes `contrarian_review()` — no args for auto-detect, or pass specific files.
+2. Contrarian resolves the input: git diff, last commit, or full audit (in that order).
+3. Judge B (external model) reviews against `JUDGE.md` in the project root.
+4. Findings are returned inline and appended to `REPORT.md` for the dialogue log.
+
+Auto-detect order:
+- **diff** — any staged/unstaged changes or untracked files
+- **last-commit** — clean tree → reviews the last commit
+- **audit** — forced with `audit=true`, or nothing else found
+
+---
+
+## Installation
+
+Requires Python 3.10+. You'll need a free API key from [DeepSeek](https://platform.deepseek.com) (no credit card required).
+
+```bash
+pip install contrarian
+contrarian setup
+```
+
+`contrarian setup` prompts for your API key, then writes the MCP server config to `~/.claude/.claude.json` automatically. Restart Claude Code after running it.
+
+That's it.
+
+---
+
+### Manual config (alternative)
+
+If you prefer to configure manually, add to `~/.claude/.claude.json`:
+
+```json
+{
+  "mcpServers": {
+    "contrarian": {
+      "type": "stdio",
+      "command": "contrarian",
+      "args": [],
+      "env": {
+        "JUDGE_B_API_KEY": "sk-or-...",
+        "JUDGE_B_BASE_URL": "https://openrouter.ai/api/v1"
+      }
+    }
+  }
+}
+```
+
+Default provider is DeepSeek (`api.deepseek.com`, model `deepseek-chat`). Change `JUDGE_B_BASE_URL` and `JUDGE_B_MODEL` to use any OpenAI-compatible provider (Gemini, Groq, Ollama, OpenRouter, etc.).
+
+Anthropic models are blocked at runtime — Judge B must come from a different lab than Judge A.
+
+---
+
+## Usage
+
+Inside any Claude Code session, the tool is available as `contrarian_review`.
+
+```
+contrarian_review()                                    # auto-detect mode
+contrarian_review({ path: "src/auth.py" })             # single file, diff
+contrarian_review({ path: "src/auth.py", full: true }) # full file
+contrarian_review({ paths: ["src/a.py", "src/b.py"] }) # multi-file, reviewed as a unit
+contrarian_review({ audit: true })                     # force full repo walk
+contrarian_review({ model: "google/gemini-3.1-pro-preview" }) # one-off model override
+```
+
+---
+
+## Rubric
+
+Place a `JUDGE.md` at the project root to customize what Judge B looks for. Without it, a built-in fallback rubric applies.
+
+The built-in rubric covers four dimensions:
+
+| Dimension | What to find |
+|---|---|
+| **Exactitude** | Logic errors, wrong assumptions, incorrect implementation |
+| **Missing** | Unhandled cases, absent validation, unconsidered implications |
+| **Premises** | Assumptions that could be wrong |
+| **Alternatives** | Fundamentally different approaches |
+
+Output is always JSON:
+
+```json
+{
+  "exactitude": { "verdict": "ok|warn|fail", "findings": [] },
+  "missing": [],
+  "premises": [],
+  "alternatives": []
+}
+```
+
+---
+
+## Report log
+
+Findings are appended to `REPORT.md` at the project root under `[Judge B]` blocks. Claude Code annotates findings under `[Judge A]` blocks. Judge B reads previous exchanges before each review — closed findings (`addressed`, `won't fix`, `disagree`) are not re-raised.
+
+---
+
+## Phase roadmap
+
+- **Phase 2 (current):** MCP server + project graph context. Auto-detect mode. Python rewrite.
+- **Phase 3:** Operational hardening — token budget guard, graph latency, detached HEAD handling.
+- **Phase 4:** Agent watchdog — autonomous background review on commit.

contrarian-0.2.0/pyproject.toml

@@ -0,0 +1,42 @@
+[build-system]
+requires = ["setuptools>=68"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "contrarian"
+version = "0.2.0"
+description = "MCP server adding an independent second LLM perspective (Judge B) with full project graph context"
+readme = "README.md"
+requires-python = ">=3.10"
+license = "MIT"
+authors = [{ name = "Anthony Micho", email = "anthony.micho76@gmail.com" }]
+keywords = ["mcp", "llm", "code-review", "claude", "judge"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Topic :: Software Development :: Quality Assurance",
+]
+dependencies = [
+    "mcp",
+    "openai>=1.0",
+    "python-dotenv",
+    "networkx>=3.4",
+    "graphifyy[leiden]",
+    "json-repair>=0.6",
+]
+
+[project.urls]
+Repository = "https://github.com/anthonymicho/contrarian"
+
+[project.optional-dependencies]
+all = ["graphifyy[all]"]
+
+[project.scripts]
+contrarian = "contrarian.server:main"
+
+[tool.setuptools.packages.find]
+where = ["src"]

contrarian-0.2.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

contrarian-0.2.0/src/contrarian/graph_context.py

@@ -0,0 +1,240 @@
+"""Build and query contrarian-out/graph.json for context about reviewed files.
+
+Graph is built automatically on first call, cached until any project file changes.
+Stale rebuilds run in a background thread — the existing graph is used immediately
+and the fresh one is ready for the next call. Only the very first build blocks.
+"""
+from __future__ import annotations
+import json
+import threading
+from pathlib import Path
+
+_rebuild_lock = threading.Lock()
+_rebuild_thread: threading.Thread | None = None
+_rebuild_failed = False  # set by background thread on error; cleared on next successful build
+
+_GRAPH_SUBDIR = "contrarian-out"
+_GRAPH_FILE = "graph.json"
+_HEAD_FILE = "HEAD.sha"
+
+
+def _graph_path(project_root: str) -> Path:
+    return Path(project_root) / _GRAPH_SUBDIR / _GRAPH_FILE
+
+
+def _head_path(project_root: str) -> Path:
+    return Path(project_root) / _GRAPH_SUBDIR / _HEAD_FILE
+
+
+def _current_head(project_root: str) -> str | None:
+    import subprocess
+    result = subprocess.run(
+        ["git", "rev-parse", "HEAD"],
+        cwd=project_root, capture_output=True, text=True,
+    )
+    return result.stdout.strip() if result.returncode == 0 else None
+
+
+def _saved_head(project_root: str) -> str | None:
+    hp = _head_path(project_root)
+    return hp.read_text(encoding="utf-8").strip() if hp.exists() else None
+
+
+def _is_stale(project_root: str) -> bool:
+    gp = _graph_path(project_root)
+    if not gp.exists():
+        return True
+    import subprocess
+    # Check HEAD SHA first — catches branch switches and resets that leave a clean tree
+    current = _current_head(project_root)
+    if current and current != _saved_head(project_root):
+        return True
+    result = subprocess.run(
+        ["git", "status", "--porcelain"],
+        cwd=project_root, capture_output=True, text=True,
+    )
+    # Any uncommitted change means potentially stale
+    if result.returncode == 0:
+        return bool(result.stdout.strip())
+    # Not a git repo — check mtimes of files the graph already tracks.
+    # Covers nested paths that a shallow iterdir() would miss.
+    graph_mtime = gp.stat().st_mtime
+    try:
+        graph_data = json.loads(gp.read_text(encoding="utf-8"))
+    except Exception:
+        return True
+    for node in graph_data.get("nodes", []):
+        src = node.get("source_file", "")
+        if not src:
+            continue
+        try:
+            if (Path(project_root) / src).stat().st_mtime > graph_mtime:
+                return True
+        except OSError:
+            pass
+    return False
+
+
+def _log(msg: str) -> None:
+    import sys
+    print(f"[contrarian] {msg}", file=sys.stderr)
+
+
+def _build_graph(project_root: str) -> bool:
+    try:
+        from graphify.detect import detect
+        from graphify.extract import extract
+        from graphify.build import build
+        from graphify.cluster import cluster
+        from graphify.export import to_json
+    except ImportError as e:
+        _log(f"Graph build skipped — graphifyy not installed: {e}")
+        return False
+
+    root = Path(project_root)
+    out_dir = root / _GRAPH_SUBDIR
+    out_dir.mkdir(exist_ok=True)
+
+    gitignore = root / ".gitignore"
+    entry = f"{_GRAPH_SUBDIR}/"
+    if not gitignore.exists() or entry not in gitignore.read_text(encoding="utf-8"):
+        with gitignore.open("a", encoding="utf-8") as f:
+            f.write(f"\n{entry}\n")
+
+    manifest = detect(root)
+    files = manifest.get("files", [])
+    if not files:
+        _log("Graph build skipped — no source files detected by graphifyy")
+        return False
+
+    extractions_dict = extract(files, cache_root=out_dir)
+    raw = list(extractions_dict.values()) if isinstance(extractions_dict, dict) else extractions_dict
+    extractions = []
+    for e in raw:
+        try:
+            if e:
+                extractions.append(e)
+        except Exception:
+            pass
+    if not extractions:
+        _log("Graph build skipped — all extractions were empty")
+        return False
+
+    G = build(extractions, directed=True)
+    communities = cluster(G)
+    # Write to a temp file then rename atomically so concurrent reads never see a partial write
+    tmp = out_dir / (_GRAPH_FILE + ".tmp")
+    to_json(G, communities, str(tmp), force=True)
+    tmp.rename(out_dir / _GRAPH_FILE)
+    # Persist HEAD SHA so branch switches are detected next time
+    head = _current_head(project_root)
+    if head:
+        _head_path(project_root).write_text(head + "\n", encoding="utf-8")
+    return True
+
+
+def _load_graph(project_root: str) -> dict | None:
+    gp = _graph_path(project_root)
+    if not gp.exists():
+        return None
+    try:
+        return json.loads(gp.read_text(encoding="utf-8"))
+    except Exception:
+        return None
+
+
+def _nodes_for_files(graph: dict, paths: list[str]) -> list[str]:
+    path_set = set(paths)
+    basenames = {Path(p).name for p in paths}
+    result = []
+    for n in graph.get("nodes", []):
+        src = n.get("source_file", "")
+        if not src:
+            continue
+        src_path = Path(src)
+        # Prefer exact relative-path match; fall back to basename only when the
+        # graph node stores a bare filename (no directory component), to avoid
+        # false matches between files with identical names in different directories.
+        if src in path_set or (src_path.parent == Path(".") and src_path.name in basenames):
+            result.append(n["id"])
+    return result
+
+
+def _one_hop_summary(graph: dict, node_ids: list[str]) -> str:
+    id_set = set(node_ids)
+    node_map = {n["id"]: n for n in graph.get("nodes", [])}
+
+    node_lines = [
+        f"- {node_map[nid].get('label', nid)} ({node_map[nid].get('source_file', '')})"
+        for nid in node_ids if nid in node_map
+    ]
+
+    rel_lines: list[str] = []
+    neighbour_ids: set[str] = set()
+    for edge in graph.get("links", graph.get("edges", [])):
+        src, tgt = edge.get("source", ""), edge.get("target", "")
+        if src in id_set or tgt in id_set:
+            other = tgt if src in id_set else src
+            neighbour_ids.add(other)
+            rel = edge.get("relation", "relates_to")
+            src_label = node_map.get(src, {}).get("label", src)
+            tgt_label = node_map.get(tgt, {}).get("label", tgt)
+            rel_lines.append(f"  {src_label} --{rel}--> {tgt_label}")
+
+    parts: list[str] = []
+    if node_lines:
+        parts.append("Reviewed nodes:\n" + "\n".join(node_lines))
+    if rel_lines:
+        parts.append("Relationships:\n" + "\n".join(rel_lines[:40]))
+    if neighbour_ids:
+        labels = [node_map.get(n, {}).get("label", n) for n in list(neighbour_ids)[:20]]
+        parts.append("Neighbours: " + ", ".join(labels))
+
+    return "\n\n".join(parts)
+
+
+def _rebuild_background(project_root: str) -> None:
+    global _rebuild_thread
+
+    if _rebuild_thread and _rebuild_thread.is_alive():
+        return
+
+    def _worker():
+        global _rebuild_failed
+        try:
+            with _rebuild_lock:
+                _build_graph(project_root)
+            _rebuild_failed = False
+        except Exception as exc:
+            _rebuild_failed = True
+            _log(f"Background graph rebuild failed: {exc}")
+
+    _rebuild_thread = threading.Thread(target=_worker, daemon=True, name="contrarian-graph-rebuild")
+    _rebuild_thread.start()
+
+
+def get_graph_context(project_root: str, paths: list[str]) -> str:
+    global _rebuild_failed
+    graph_exists = _graph_path(project_root).exists()
+    stale = _is_stale(project_root)
+
+    if stale or _rebuild_failed:
+        if graph_exists and not _rebuild_failed:
+            # Serve existing graph; rebuild in background for next call
+            _rebuild_background(project_root)
+        else:
+            # First build, or last background rebuild failed — block and retry.
+            # Propagates on failure so the caller sees the error instead of silent stale data.
+            _rebuild_failed = False
+            with _rebuild_lock:
+                _build_graph(project_root)
+
+    graph = _load_graph(project_root)
+    if not graph:
+        return ""
+
+    node_ids = _nodes_for_files(graph, paths)
+    if not node_ids:
+        return ""
+
+    return _one_hop_summary(graph, node_ids)