codemop 0.1.0__py3-none-any.whl

codemop/__init__.py

@@ -0,0 +1,3 @@
+"""CodeMop: AI code review for pull requests, with the model of your choice."""
+
+__version__ = "0.1.0"

codemop/cli.py

@@ -0,0 +1,233 @@
+"""
+The codemop command.
+
+    codemop review owner/repo#123          review a pull request
+    codemop review https://github.com/owner/repo/pull/123
+    git diff main | codemop review -       review a local diff
+
+Exit status: 0 when every part of the diff was reviewed, 1 when some of it couldn't be
+(see the report), 2 for usage errors.
+"""
+import argparse
+import asyncio
+import dataclasses
+import json
+import os
+import shutil
+import subprocess  # nosec B404
+import sys
+import textwrap
+from enum import Enum
+from pathlib import Path
+from typing import List, Optional
+
+from codemop import __version__
+from codemop.config import (
+    CONFIG_FILE, DEFAULT_MIN_CONFIDENCE, ConfigError, RepoConfig, load_config_file, parse_config,
+)
+from codemop.github.client import (
+    DEFAULT_API_URL, GitHubError, PullRequestRef, fetch_pr_diff, fetch_repo_file, parse_pr_reference,
+)
+from codemop.providers import DEFAULT_MODELS, PROVIDERS, create_model
+from codemop.providers.base import DEFAULT_CHUNK_TOKENS, Usage
+from codemop.providers.pricing import PRICES_AS_OF
+from codemop.review.chunks import DEFAULT_IGNORED_PATHS
+from codemop.review.pipeline import ReviewReport, review_diff
+
+
+def github_token() -> Optional[str]:
+    """GITHUB_TOKEN, or the token from a `gh auth login`, so private repos work without setup"""
+    token = os.environ.get("GITHUB_TOKEN") or os.environ.get("GH_TOKEN")
+    gh = shutil.which("gh")
+    if token or not gh:
+        return token
+    # Fixed arguments and no shell, so nothing from the user reaches the command
+    result = subprocess.run([gh, "auth", "token"], capture_output=True, text=True)  # nosec B603
+    if result.returncode != 0:
+        return None
+    return result.stdout.strip() or None
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(prog="codemop", description="AI code review for pull requests.")
+    parser.add_argument("--version", action="version", version=f"codemop {__version__}")
+    commands = parser.add_subparsers(dest="command", required=True)
+
+    review = commands.add_parser(
+        "review", help="review a pull request or a diff",
+        description=(
+            "Review a pull request (owner/repo#123 or a PR URL), or a diff on stdin (-). "
+            f"How the repository is reviewed comes from its {CONFIG_FILE} (on the default branch; "
+            "for stdin, the current directory), unless overridden here. Which model reviews it is "
+            "up to you: --provider/--model, or CODEMOP_PROVIDER / CODEMOP_MODEL / CODEMOP_BASE_URL."
+        ),
+    )
+    review.add_argument("target", help="owner/repo#123, a pull request URL, or - to read a diff from stdin")
+
+    who = review.add_argument_group("model (chosen by you, never by the repository)")
+    who.add_argument("--provider", choices=PROVIDERS, default=os.environ.get("CODEMOP_PROVIDER", "anthropic"),
+                     help="model provider (default: $CODEMOP_PROVIDER, or anthropic)")
+    who.add_argument("--model", default=os.environ.get("CODEMOP_MODEL"),
+                     help="model name (default: $CODEMOP_MODEL, or the provider's: "
+                          + ", ".join(f"{p}: {m}" for p, m in DEFAULT_MODELS.items()) + ")")
+    who.add_argument("--base-url", default=os.environ.get("CODEMOP_BASE_URL"),
+                     help="API base URL, for openai-compatible or a self-hosted endpoint (default: $CODEMOP_BASE_URL)")
+    who.add_argument("--api-key-env", help="environment variable holding the provider's API key")
+    who.add_argument("--effort", choices=["low", "medium", "high", "xhigh", "max"],
+                     default=os.environ.get("CODEMOP_EFFORT"),
+                     help="how hard Claude thinks: lower is cheaper and faster (default: $CODEMOP_EFFORT, or high)")
+
+    how = review.add_argument_group(f"review settings (override the repository's {CONFIG_FILE})")
+    how.add_argument("--config", type=Path, metavar="PATH",
+                     help=f"use this config file instead of the repository's {CONFIG_FILE}")
+    how.add_argument("--min-confidence", type=float,
+                     help=f"drop suggestions the model is less sure of (0-1, default: {DEFAULT_MIN_CONFIDENCE})")
+    how.add_argument("--chunk-tokens", type=int,
+                     help=f"largest piece of diff sent in one request (default: {DEFAULT_CHUNK_TOKENS:,}; 8,000 for ollama)")
+    how.add_argument("--ignore", action="append", metavar="PATTERN",
+                     help="another path pattern not to review (repeatable; added to the defaults: "
+                          + " ".join(DEFAULT_IGNORED_PATHS) + ")")
+
+    review.add_argument("--github-api-url", default=DEFAULT_API_URL, help="for GitHub Enterprise Server")
+    review.add_argument("--json", action="store_true", help="print the report as JSON")
+    return parser
+
+
+def _to_jsonable(value):
+    if hasattr(value, "model_dump"):
+        return value.model_dump(mode="json")
+    if dataclasses.is_dataclass(value):
+        return {f.name: _to_jsonable(getattr(value, f.name)) for f in dataclasses.fields(value)}
+    if isinstance(value, list):
+        return [_to_jsonable(v) for v in value]
+    if isinstance(value, Enum):
+        return value.value
+    return value
+
+
+def report_json(report: ReviewReport, target: str, config_source: str) -> str:
+    return json.dumps(
+        {"target": target, "config": config_source, "complete": report.complete, **_to_jsonable(report)},
+        indent=2,
+    )
+
+
+def format_cost(cost: Optional[float], usage: Usage) -> str:
+    if not usage.input_tokens and not usage.output_tokens:
+        return "nothing spent"
+    if cost is None:
+        return "cost unknown for this model"
+    if cost == 0:
+        return "no cost (local model)"
+    return f"about ${cost:.2f}" if cost >= 0.01 else "under $0.01"
+
+
+def report_text(report: ReviewReport, target: str, config_source: str) -> str:
+    settings = "" if config_source == "defaults" else f" (settings from {config_source})"
+    lines: List[str] = [f"CodeMop review of {target} with {report.model}{settings}", ""]
+    if not report.suggestions:
+        lines.append("No issues found." if report.complete else "No issues found in the parts that were reviewed.")
+    for s in report.suggestions:
+        location = f"{s.file_path}:{s.line}" + (f"-{s.end_line}" if s.end_line and s.end_line != s.line else "")
+        lines.append(f"{location}  [{s.severity.value}, confidence {s.confidence:.2f}]  {s.title}")
+        lines.extend(textwrap.wrap(s.explanation, width=88, initial_indent="    ", subsequent_indent="    "))
+        if s.suggested_code:
+            lines.append("    Suggested change:")
+            lines.extend("      " + code_line for code_line in s.suggested_code.splitlines())
+        lines.append("")
+
+    notes: List[str] = []
+    # The chunk that hit the fatal error, and those not started after it, share one note
+    stopped = [f for f in report.failed if report.stopped and (f.kind == "not_reviewed" or f.reason == report.stopped)]
+    if stopped:
+        paths = ", ".join(path for failed in stopped for path in failed.paths)
+        notes.append(f"Stopped early: {report.stopped} (not reviewed: {paths})")
+    for failed in report.failed:
+        if failed not in stopped:
+            notes.append(f"Not reviewed ({', '.join(failed.paths)}): {failed.reason}")
+    for skipped in report.skipped:
+        notes.append(f"Skipped {skipped.path}: {skipped.reason}")
+    if report.unplaced:
+        notes.append(f"Set aside {len(report.unplaced)} suggestion(s) that pointed at lines outside the diff")
+    if report.below_confidence:
+        notes.append(f"Dropped {report.below_confidence} suggestion(s) below the confidence threshold")
+    if notes:
+        lines += notes + [""]
+
+    u = report.usage
+    lines.append(f"{len(report.suggestions)} suggestion(s) · {report.chunks} chunk(s) · "
+                 f"{u.input_tokens:,} input / {u.output_tokens:,} output tokens · "
+                 f"{format_cost(report.cost, u)}" + ("" if not report.cost else f" (list prices as of {PRICES_AS_OF})"))
+    return "\n".join(lines)
+
+
+async def load_config(args, pr: Optional[PullRequestRef], token: Optional[str]) -> tuple[RepoConfig, str]:
+    """The review settings and where they came from: --config, the repo's file, or the defaults"""
+    if args.config:
+        config = load_config_file(args.config)
+        if config is None:
+            raise ConfigError(f"{args.config} doesn't exist")
+        return config, str(args.config)
+    if pr is None:
+        config = load_config_file(Path(CONFIG_FILE))
+        return (config, CONFIG_FILE) if config else (RepoConfig(), "defaults")
+    text = await fetch_repo_file(pr.repo, CONFIG_FILE, token=token, api_url=args.github_api_url)
+    if text is None:
+        return RepoConfig(), "defaults"
+    return parse_config(text, source=f"{pr.repo}/{CONFIG_FILE}"), f"{pr.repo}/{CONFIG_FILE}"
+
+
+async def run_review(args) -> int:
+    pr = None
+    token = None
+    if args.target != "-":
+        try:
+            pr = parse_pr_reference(args.target)
+        except ValueError as e:
+            print(f"codemop: {e}", file=sys.stderr)
+            return 2
+        token = github_token()
+
+    try:
+        config, config_source = await load_config(args, pr, token)
+    except (ConfigError, GitHubError) as e:
+        print(f"codemop: {e}", file=sys.stderr)
+        return 2 if isinstance(e, ConfigError) else 1
+
+    if pr is None:
+        diff, target = sys.stdin.read(), "stdin"
+    else:
+        target = str(pr)
+        try:
+            diff = await fetch_pr_diff(pr, token=token, api_url=args.github_api_url)
+        except GitHubError as e:
+            print(f"codemop: {e}", file=sys.stderr)
+            return 1
+
+    try:
+        model = create_model(
+            args.provider, args.model, base_url=args.base_url, api_key_env=args.api_key_env, effort=args.effort
+        )
+    except ValueError as e:
+        print(f"codemop: {e}", file=sys.stderr)
+        return 2
+
+    report = await review_diff(
+        diff, model,
+        chunk_tokens=args.chunk_tokens or config.chunk_tokens,
+        min_confidence=args.min_confidence if args.min_confidence is not None else config.min_confidence,
+        ignored_paths=[*DEFAULT_IGNORED_PATHS, *config.ignore, *(args.ignore or [])],
+    )
+    print(report_json(report, target, config_source) if args.json else report_text(report, target, config_source))
+    return 0 if report.complete else 1
+
+
+def main(argv: Optional[List[str]] = None) -> int:
+    args = build_parser().parse_args(argv)
+    if args.command == "review":
+        return asyncio.run(run_review(args))
+    return 2
+
+
+if __name__ == "__main__":
+    sys.exit(main())

codemop/config.py

@@ -0,0 +1,66 @@
+"""
+A repository's .codemop.yml: how its pull requests are reviewed.
+
+It only controls review behaviour. Which provider and model run the review, and where
+requests (and API keys) go, are decided by whoever runs CodeMop, never by the repository
+being reviewed: otherwise reviewing someone else's PR could send your key to their server.
+"""
+from pathlib import Path
+from typing import List, Optional
+
+import yaml
+from pydantic import BaseModel, ConfigDict, Field, ValidationError
+
+CONFIG_FILE = ".codemop.yml"
+DEFAULT_MIN_CONFIDENCE = 0.5
+
+
+class ConfigError(Exception):
+    """.codemop.yml couldn't be used; the message says what's wrong with it"""
+
+
+class RepoConfig(BaseModel):
+    model_config = ConfigDict(extra="forbid")
+
+    ignore: List[str] = Field(
+        default_factory=list,
+        description="Path patterns not to review, in addition to the defaults (lock files, minified files...)",
+    )
+    min_confidence: float = Field(
+        default=DEFAULT_MIN_CONFIDENCE, ge=0, le=1,
+        description="Drop suggestions the model is less sure of than this",
+    )
+    chunk_tokens: Optional[int] = Field(
+        default=None, ge=1000,
+        description="Largest piece of diff sent in one request (default: the model's own)",
+    )
+
+
+def parse_config(text: str, source: str = CONFIG_FILE) -> RepoConfig:
+    """Read a .codemop.yml; an empty file means all defaults"""
+    try:
+        data = yaml.safe_load(text)
+    except yaml.YAMLError as e:
+        raise ConfigError(f"{source} isn't valid YAML: {e}")
+    if data is None:
+        return RepoConfig()
+    if not isinstance(data, dict):
+        raise ConfigError(f"{source} should be a mapping of settings, like `min_confidence: 0.6`")
+    try:
+        return RepoConfig.model_validate(data)
+    except ValidationError as e:
+        problems = []
+        for error in e.errors():
+            field = ".".join(str(part) for part in error["loc"]) or "(top level)"
+            if error["type"] == "extra_forbidden":
+                problems.append(f"unknown setting `{field}` (settings: {', '.join(RepoConfig.model_fields)})")
+            else:
+                problems.append(f"`{field}`: {error['msg']}")
+        raise ConfigError(f"{source}: " + "; ".join(problems))
+
+
+def load_config_file(path: Path) -> Optional[RepoConfig]:
+    """The config at `path`, or None if there's no such file"""
+    if not path.is_file():
+        return None
+    return parse_config(path.read_text(), source=str(path))

codemop/github/__init__.py

@@ -0,0 +1 @@
+"""Talking to GitHub: fetching PR diffs and (later) posting reviews."""

codemop/github/client.py

@@ -0,0 +1,106 @@
+"""
+Fetching pull request diffs from the GitHub REST API.
+
+Uses a token when one is given, which private repositories need (and which raises the
+rate limit from 60 to 5,000 requests an hour for public ones).
+"""
+import re
+from dataclasses import dataclass
+from typing import Optional
+
+import httpx
+
+DEFAULT_API_URL = "https://api.github.com"
+
+_PR_REFERENCE = re.compile(r"^(?P<repo>[\w.-]+/[\w.-]+)#(?P<number>\d+)$")
+_PR_URL = re.compile(r"^https?://[^/]+/(?P<repo>[\w.-]+/[\w.-]+)/pull/(?P<number>\d+)(?:[/?#].*)?$")
+
+
+class GitHubError(Exception):
+    """A GitHub request failed; the message says what to do about it"""
+
+
+@dataclass(frozen=True)
+class PullRequestRef:
+    repo: str  # owner/name
+    number: int
+
+    def __str__(self) -> str:
+        return f"{self.repo}#{self.number}"
+
+
+def parse_pr_reference(text: str) -> PullRequestRef:
+    """owner/repo#123, or a PR URL like https://github.com/owner/repo/pull/123"""
+    match = _PR_REFERENCE.match(text.strip()) or _PR_URL.match(text.strip())
+    if not match:
+        raise ValueError(f"Not a pull request: {text!r} (use owner/repo#123 or a PR URL)")
+    return PullRequestRef(match.group("repo"), int(match.group("number")))
+
+
+def _error_message(status: int, body: str, pr: PullRequestRef, has_token: bool) -> str:
+    if status == 401:
+        return f"GitHub rejected the token while fetching {pr}; check it's valid and hasn't expired"
+    if status == 403 and "rate limit" in body.lower():
+        hint = "" if has_token else "; set GITHUB_TOKEN (or log in with `gh auth login`) for a higher limit"
+        return f"GitHub API rate limit reached while fetching {pr}{hint}"
+    if status in (403, 404):
+        if has_token:
+            return (f"GitHub returned {status} for {pr}: the token needs read access to this "
+                    "repository's pull requests and contents")
+        return (f"GitHub returned {status} for {pr}: if the repository is private, set "
+                "GITHUB_TOKEN (or log in with `gh auth login`)")
+    if status == 406:
+        return f"The diff for {pr} is too large for the GitHub API to return"
+    return f"GitHub returned {status} while fetching the diff for {pr}"
+
+
+async def _get(
+    url: str, accept: str, token: Optional[str], transport: Optional[httpx.AsyncBaseTransport]
+) -> httpx.Response:
+    headers = {"Accept": accept, "X-GitHub-Api-Version": "2022-11-28"}
+    if token:
+        headers["Authorization"] = f"Bearer {token}"
+    async with httpx.AsyncClient(headers=headers, timeout=60.0, transport=transport) as client:
+        try:
+            return await client.get(url)
+        except httpx.TransportError:
+            raise GitHubError(f"Couldn't connect to {url.split('/repos/')[0]}; check the network")
+
+
+async def fetch_pr_diff(
+    pr: PullRequestRef,
+    *,
+    token: Optional[str] = None,
+    api_url: str = DEFAULT_API_URL,
+    transport: Optional[httpx.AsyncBaseTransport] = None,
+) -> str:
+    """The PR's diff, from GET /repos/{owner}/{repo}/pulls/{number} as application/vnd.github.diff"""
+    url = f"{api_url.rstrip('/')}/repos/{pr.repo}/pulls/{pr.number}"
+    response = await _get(url, "application/vnd.github.diff", token, transport)
+    if response.status_code != 200:
+        raise GitHubError(_error_message(response.status_code, response.text, pr, bool(token)))
+    return response.text
+
+
+async def fetch_repo_file(
+    repo: str,
+    path: str,
+    *,
+    token: Optional[str] = None,
+    api_url: str = DEFAULT_API_URL,
+    transport: Optional[httpx.AsyncBaseTransport] = None,
+) -> Optional[str]:
+    """
+    A file's contents on the repository's default branch, or None if there's no such file.
+
+    (The default branch, not the PR's: a pull request mustn't be able to change how it's
+    reviewed.) A 404 also covers a private repository read without access; fetching its diff
+    reports that properly.
+    """
+    url = f"{api_url.rstrip('/')}/repos/{repo}/contents/{path}"
+    response = await _get(url, "application/vnd.github.raw+json", token, transport)
+    if response.status_code == 404:
+        return None
+    if response.status_code != 200:
+        raise GitHubError(f"GitHub returned {response.status_code} reading {path} from {repo}")
+    return response.text

codemop/providers/__init__.py

@@ -0,0 +1,59 @@
+"""
+Model providers, one module each, behind the interface in providers.base.
+
+create_model() is the one place that knows which providers exist.
+"""
+import os
+from typing import Optional
+
+from codemop.providers.base import ReviewModel
+
+PROVIDERS = ("anthropic", "mistral", "openai", "openrouter", "ollama", "openai-compatible")
+
+# Providers with a sensible default model; the rest need one named
+DEFAULT_MODELS = {
+    "anthropic": "claude-opus-5-5",
+    "mistral": "codestral-latest",
+}
+
+
+def key_env(provider: str) -> Optional[str]:
+    """The environment variable a provider's API key is read from by default (None: no key needed)"""
+    if provider == "anthropic":
+        return "ANTHROPIC_API_KEY"
+    from codemop.providers.openai_compatible import PRESETS
+    preset = PRESETS.get(provider)
+    return preset.key_env if preset else None
+
+
+def create_model(
+    provider: str = "anthropic",
+    model: Optional[str] = None,
+    *,
+    base_url: Optional[str] = None,
+    api_key: Optional[str] = None,
+    api_key_env: Optional[str] = None,
+    effort: Optional[str] = None,
+) -> ReviewModel:
+    """
+    The ReviewModel for a provider name (anthropic, mistral, openai, openrouter, ollama,
+    openai-compatible). The API key is `api_key` if given, else read from `api_key_env`, else
+    the provider's own variable (see key_env). `effort` (low, medium, high, xhigh, max) applies
+    to Claude models that support it; None keeps the adapter's default (high).
+    """
+    if provider not in PROVIDERS:
+        raise ValueError(f"Unknown provider {provider!r}; choose one of: {', '.join(PROVIDERS)}")
+    model = model or DEFAULT_MODELS.get(provider)
+    if not model:
+        raise ValueError(f"Name a model for {provider} (e.g. --model ...)")
+
+    if provider == "anthropic":
+        from codemop.providers.anthropic import AnthropicModel
+        if not api_key and api_key_env:
+            api_key = os.environ.get(api_key_env)
+        return AnthropicModel(model, api_key=api_key, **({"effort": effort} if effort else {}))
+
+    from codemop.providers.openai_compatible import OpenAICompatibleModel
+    if provider == "openai-compatible" and not base_url:
+        raise ValueError("openai-compatible needs a base URL (e.g. --base-url http://localhost:8000/v1)")
+    return OpenAICompatibleModel(model, provider=provider, base_url=base_url, api_key=api_key, key_env=api_key_env)

codemop/providers/anthropic.py

@@ -0,0 +1,114 @@
+"""
+Claude, through the official Anthropic SDK.
+
+Uses structured output (messages.parse with the review schema), so Claude's answer is
+constrained to the schema and validated on the way back.
+"""
+from typing import Optional
+
+import anthropic
+import pydantic
+
+from codemop.providers import DEFAULT_MODELS
+from codemop.providers.base import DEFAULT_CHUNK_TOKENS, NoReview, Usage
+from codemop.providers.pricing import ANTHROPIC_PRICES
+from codemop.review.schema import ModelReview
+
+# Models that accept fallbacks="default": if the model declines a request, the API re-runs it
+# on Anthropic's recommended model for that refusal category instead of returning a refusal
+_FALLBACK_BETA = "server-side-fallback-2026-07-01"
+_DEFAULT_FALLBACK_MODELS = {"claude-fable-5-1", "claude-opus-5-5", "claude-opus-5", "claude-sonnet-5-5"}
+
+# Older models reject the effort setting
+_NO_EFFORT_PREFIXES = ("claude-haiku-", "claude-sonnet-4-5", "claude-3")
+
+KEY_HINT = "check ANTHROPIC_API_KEY is set to a valid key"
+
+
+class AnthropicModel:
+    """A ReviewModel backed by Claude"""
+
+    def __init__(
+        self,
+        model: str = DEFAULT_MODELS["anthropic"],
+        *,
+        api_key: Optional[str] = None,
+        effort: Optional[str] = "high",
+        max_output_tokens: int = 16000,
+        chunk_tokens: int = DEFAULT_CHUNK_TOKENS,
+        client: Optional[anthropic.AsyncAnthropic] = None,
+    ):
+        self.model = model
+        self.chunk_tokens = chunk_tokens
+        # Models that actually answered: with refusal fallbacks, another model can answer
+        self.served_models: set[str] = set()
+        self.effort = None if model.startswith(_NO_EFFORT_PREFIXES) else effort
+        self.max_output_tokens = max_output_tokens
+        # With no api_key the SDK finds credentials itself (ANTHROPIC_API_KEY, `ant auth login`...)
+        self._client = client or anthropic.AsyncAnthropic(api_key=api_key)
+
+    @property
+    def name(self) -> str:
+        return f"anthropic/{self.model}"
+
+    def cost(self, usage: Usage) -> Optional[float]:
+        price = ANTHROPIC_PRICES.get(self.model)
+        return price.cost(usage) if price else None
+
+    async def review(self, instructions: str, diff_text: str) -> tuple[ModelReview, Usage]:
+        request = dict(
+            model=self.model,
+            max_tokens=self.max_output_tokens,
+            system=instructions,
+            messages=[{"role": "user", "content": diff_text}],
+            output_format=ModelReview,
+        )
+        if self.effort:
+            request["output_config"] = {"effort": self.effort}
+
+        try:
+            if self.model in _DEFAULT_FALLBACK_MODELS:
+                response = await self._client.beta.messages.parse(
+                    betas=[_FALLBACK_BETA], fallbacks="default", **request
+                )
+            else:
+                response = await self._client.messages.parse(**request)
+        except pydantic.ValidationError:
+            raise NoReview(f"{self.name} returned a review that doesn't match the schema")
+        except TypeError as e:
+            # The SDK raises TypeError, before sending anything, when it finds no credentials
+            if "Could not resolve authentication method" not in str(e):
+                raise
+            raise NoReview("No Anthropic API key found: set ANTHROPIC_API_KEY", fatal=True)
+        except anthropic.AuthenticationError:
+            raise NoReview(f"Anthropic rejected the API key: {KEY_HINT}", fatal=True)
+        except anthropic.PermissionDeniedError:
+            raise NoReview(f"The Anthropic API key isn't allowed to use {self.model}", fatal=True)
+        except anthropic.NotFoundError:
+            raise NoReview(f"Model {self.model} wasn't found, or isn't available to this API key", fatal=True)
+        except anthropic.RateLimitError:
+            raise NoReview("Anthropic rate limit reached (after retries); try again later")
+        except anthropic.BadRequestError as e:
+            raise NoReview(f"Anthropic rejected the request: {e.message}")
+        except anthropic.APIStatusError as e:
+            raise NoReview(f"Anthropic returned an error ({e.status_code}); try again later")
+        except anthropic.APIConnectionError:
+            raise NoReview("Couldn't connect to the Anthropic API; check the network")
+
+        if getattr(response, "model", None):
+            self.served_models.add(response.model)
+        usage = Usage(
+            input_tokens=response.usage.input_tokens or 0,
+            output_tokens=response.usage.output_tokens or 0,
+            cache_read_tokens=response.usage.cache_read_input_tokens or 0,
+            cache_write_tokens=response.usage.cache_creation_input_tokens or 0,
+        )
+        if response.stop_reason == "refusal":
+            category = getattr(response.stop_details, "category", None)
+            detail = f" ({category})" if category else ""
+            raise NoReview.refused(self.name, usage, detail)
+        if response.stop_reason == "max_tokens":
+            raise NoReview.cut_off(self.name, self.max_output_tokens, usage)
+        if response.parsed_output is None:
+            raise NoReview(f"{self.name} returned no review", usage=usage)
+        return response.parsed_output, usage

codemop/providers/base.py

@@ -0,0 +1,84 @@
+"""
+The interface every model provider implements.
+
+The review code only talks to a ReviewModel; provider SDKs and HTTP details stay inside
+their adapter modules.
+"""
+from dataclasses import dataclass
+from typing import Literal, Optional, Protocol
+
+from codemop.review.schema import ModelReview
+
+
+@dataclass(frozen=True)
+class Usage:
+    """Tokens used by one or more requests"""
+    input_tokens: int = 0
+    output_tokens: int = 0
+    cache_read_tokens: int = 0
+    cache_write_tokens: int = 0
+
+    def __add__(self, other: "Usage") -> "Usage":
+        return Usage(
+            self.input_tokens + other.input_tokens,
+            self.output_tokens + other.output_tokens,
+            self.cache_read_tokens + other.cache_read_tokens,
+            self.cache_write_tokens + other.cache_write_tokens,
+        )
+
+
+# Why a chunk got no review: the model declined, its answer hit the output limit, or
+# something else went wrong (the reason says what)
+NoReviewKind = Literal["refused", "cut_off", "error"]
+
+
+class NoReview(Exception):
+    """
+    The model gave no usable review. The message says why, and what to do about it.
+
+    `fatal` means every request would fail the same way (a rejected key, an unknown model),
+    so the rest of the review should stop rather than repeat it.
+    """
+
+    def __init__(self, reason: str, *, fatal: bool = False, usage: Usage = Usage(), kind: NoReviewKind = "error"):
+        super().__init__(reason)
+        self.reason = reason
+        self.fatal = fatal
+        self.usage = usage
+        self.kind = kind
+
+    @classmethod
+    def refused(cls, model_name: str, usage: Usage, detail: str = "") -> "NoReview":
+        return cls(f"{model_name} declined to review this part of the diff{detail}", usage=usage, kind="refused")
+
+    @classmethod
+    def cut_off(cls, model_name: str, max_output_tokens: int, usage: Usage) -> "NoReview":
+        return cls(
+            f"{model_name}'s review was cut off at {max_output_tokens} output tokens; "
+            "raise the output limit or use smaller chunks",
+            usage=usage, kind="cut_off",
+        )
+
+
+# Largest piece of diff to send in one request, unless a model says otherwise
+DEFAULT_CHUNK_TOKENS = 40_000
+
+
+class ReviewModel(Protocol):
+    """A model that can review one chunk of a diff"""
+
+    #: The largest piece of diff this model should be sent at once, in tokens
+    chunk_tokens: int
+
+    @property
+    def name(self) -> str:
+        """provider/model, e.g. anthropic/claude-opus-5-5"""
+        ...
+
+    async def review(self, instructions: str, diff_text: str) -> tuple[ModelReview, Usage]:
+        """Review `diff_text` following `instructions`; raises NoReview if there's no usable answer"""
+        ...
+
+    def cost(self, usage: Usage) -> Optional[float]:
+        """Estimated US dollars for `usage` at list prices, or None if the price isn't known"""
+        ...