jitcatch 0.2.0__py3-none-any.whl

jitcatch/gitutil.py

@@ -0,0 +1,231 @@
+"""Git helpers: diff extraction and disposable worktrees for the parent and child revisions."""
+from __future__ import annotations
+
+import os
+import shutil
+import subprocess
+import tempfile
+from contextlib import contextmanager
+from pathlib import Path
+from typing import Iterator
+
+from .models import ChangeContext, ChangedFile
+
+
+class GitError(RuntimeError):
+    pass
+
+
+def git(repo: Path, *args: str, check: bool = True) -> str:
+    proc = subprocess.run(
+        ["git", *args], cwd=repo, capture_output=True, text=True,
+        encoding="utf-8", errors="replace",
+    )
+    if check and proc.returncode != 0:
+        raise GitError(f"git {' '.join(args)} failed: {proc.stderr.strip()}")
+    return proc.stdout
+
+
+def repo_root(start: Path) -> Path:
+    proc = subprocess.run(["git", "rev-parse", "--show-toplevel"], cwd=start, capture_output=True, text=True)
+    if proc.returncode != 0:
+        raise GitError(f"{start} is not inside a git repository. jitcatch tests a change against an earlier "
+                       "version, so it needs git: run `git init && git add -A && git commit -m init` first")
+    return Path(proc.stdout.strip())
+
+
+# ------------------------------------------------------------------------- automatic change range
+
+_OWN_FILES = (".jitcatch.toml", "jitcatch.toml", ".jitcatch/")
+
+
+def has_commits(repo: Path) -> bool:
+    return git(repo, "rev-parse", "--verify", "-q", "HEAD^{commit}", check=False).strip() != ""
+
+
+def dirty_paths(repo: Path) -> list[str]:
+    """Changed or untracked (non-ignored) paths, excluding jitcatch's own files."""
+    out = git(repo, "status", "--porcelain=v1", "-z", "--untracked-files=all")
+    paths, parts, i = [], out.split("\0"), 0
+    while i < len(parts):
+        entry = parts[i]
+        i += 1
+        if len(entry) < 4:
+            continue
+        status, path = entry[:2], entry[3:]
+        if status[0] in "RC":
+            i += 1  # the original path follows a rename/copy entry
+        if not path.startswith(_OWN_FILES):
+            paths.append(path)
+    return paths
+
+
+def default_branch(repo: Path) -> str | None:
+    ref = git(repo, "symbolic-ref", "-q", "--short", "refs/remotes/origin/HEAD", check=False).strip()
+    if ref:
+        return ref
+    for cand in ("origin/main", "origin/master", "main", "master"):
+        if git(repo, "rev-parse", "--verify", "-q", f"{cand}^{{commit}}", check=False).strip():
+            return cand
+    return None
+
+
+def snapshot_worktree(repo: Path) -> str:
+    """Commit object for the current working tree (tracked changes + untracked, non-ignored files) on top of
+    HEAD, created with a throwaway index. No branch, ref, index or file of the user's checkout is touched."""
+    with tempfile.TemporaryDirectory(prefix="jcidx-") as d:
+        env = {**os.environ, "GIT_INDEX_FILE": str(Path(d) / "index"),
+               "GIT_AUTHOR_NAME": "jitcatch", "GIT_AUTHOR_EMAIL": "jitcatch@localhost",
+               "GIT_COMMITTER_NAME": "jitcatch", "GIT_COMMITTER_EMAIL": "jitcatch@localhost"}
+
+        def g(*args: str) -> str:
+            proc = subprocess.run(["git", *args], cwd=repo, capture_output=True, text=True, env=env)
+            if proc.returncode != 0:
+                raise GitError(f"git {' '.join(args)} failed: {proc.stderr.strip()}")
+            return proc.stdout.strip()
+
+        g("read-tree", "HEAD")
+        g("add", "-A", "--", ".", *(f":(exclude){p.rstrip('/')}" for p in _OWN_FILES))
+        tree = g("write-tree")
+        return g("commit-tree", tree, "-p", "HEAD", "-m", "Uncommitted changes")
+
+
+def auto_range(repo: Path) -> tuple[str, str, str]:
+    """Pick what to test when no --base/--head is given. Returns (base, head, human description)."""
+    if not has_commits(repo):
+        raise GitError("this repository has no commits yet. jitcatch compares a change against an earlier "
+                       "version: commit once (git add -A && git commit -m init), make a change, then run it again")
+    if dirty_paths(repo):
+        return "HEAD", snapshot_worktree(repo), "your uncommitted changes (compared with the last commit)"
+    head = rev_parse(repo, "HEAD")
+    default = default_branch(repo)
+    if default and merge_base(repo, rev_parse(repo, default), head) != head:
+        branch = git(repo, "rev-parse", "--abbrev-ref", "HEAD").strip()
+        return default, "HEAD", f"commits on {branch} that are not in {default}"
+    if git(repo, "rev-parse", "--verify", "-q", "HEAD~1^{commit}", check=False).strip():
+        return "HEAD~1", "HEAD", "the last commit"
+    raise GitError("only one commit and no uncommitted changes, so there is nothing to compare yet: "
+                   "make a change and run jitcatch again")
+
+
+def ensure_excluded(repo: Path, pattern: str = ".jitcatch/") -> None:
+    """Keep jitcatch's output out of `git status` via .git/info/exclude (a local, untracked file)."""
+    rel = git(repo, "rev-parse", "--git-path", "info/exclude").strip()
+    p = Path(rel) if Path(rel).is_absolute() else repo / rel
+    lines = p.read_text(encoding="utf-8").splitlines() if p.exists() else []
+    if pattern not in lines:
+        p.parent.mkdir(parents=True, exist_ok=True)
+        with open(p, "a", encoding="utf-8") as f:
+            f.write(("\n" if lines and lines[-1] else "") + pattern + "\n")
+
+
+def rev_parse(repo: Path, rev: str) -> str:
+    return git(repo, "rev-parse", "--verify", f"{rev}^{{commit}}").strip()
+
+
+def merge_base(repo: Path, a: str, b: str) -> str:
+    out = git(repo, "merge-base", a, b, check=False).strip()
+    return out or a
+
+
+def show_file(repo: Path, sha: str, path: str) -> str | None:
+    proc = subprocess.run(
+        ["git", "show", f"{sha}:{path}"], cwd=repo, capture_output=True,
+        text=True, encoding="utf-8", errors="replace",
+    )
+    return proc.stdout if proc.returncode == 0 else None
+
+
+def commit_messages(repo: Path, base: str, head: str) -> tuple[str, str]:
+    """Return (title, description) derived from commits in base..head."""
+    out = git(repo, "log", "--format=%s%x1f%b%x1e", f"{base}..{head}", check=False)
+    entries = [e.strip() for e in out.split("\x1e") if e.strip()]
+    if not entries:
+        return "", ""
+    subjects, bodies = [], []
+    for e in reversed(entries):  # oldest first
+        subj, _, body = e.partition("\x1f")
+        subjects.append(subj.strip())
+        if body.strip():
+            bodies.append(body.strip())
+    title = subjects[-1] if len(subjects) == 1 else subjects[0]
+    desc_parts = []
+    if len(subjects) > 1:
+        desc_parts.append("Commits:\n" + "\n".join(f"- {s}" for s in subjects))
+    desc_parts.extend(bodies)
+    return title, "\n\n".join(desc_parts)
+
+
+def change_context(repo: Path, base: str, head: str, title: str = "", description: str = "") -> ChangeContext:
+    head_sha = rev_parse(repo, head)
+    base_sha = merge_base(repo, rev_parse(repo, base), head_sha)
+    if not title and not description:
+        title, description = commit_messages(repo, base_sha, head_sha)
+    status_out = git(repo, "diff", "--name-status", "-M", base_sha, head_sha)
+    numstat_out = git(repo, "diff", "--numstat", "-M", base_sha, head_sha)
+    counts: dict[str, tuple[int, int]] = {}
+    for line in numstat_out.splitlines():
+        parts = line.split("\t")
+        if len(parts) >= 3:
+            a = int(parts[0]) if parts[0].isdigit() else 0
+            r = int(parts[1]) if parts[1].isdigit() else 0
+            counts[parts[-1]] = (a, r)
+    files: list[ChangedFile] = []
+    for line in status_out.splitlines():
+        parts = line.split("\t")
+        if not parts or not parts[0]:
+            continue
+        code = parts[0][0]
+        if code == "R" and len(parts) >= 3:
+            old, new = parts[1], parts[2]
+        else:
+            old = new = parts[-1]
+        patch = git(repo, "diff", "-M", base_sha, head_sha, "--", *({old, new}))
+        a, r = counts.get(new, counts.get(f"{old} => {new}", (0, 0)))
+        files.append(ChangedFile(path=new, old_path=old, status=code, patch=patch, added_lines=a, removed_lines=r))
+    full_patch = git(repo, "diff", "-M", base_sha, head_sha)
+    return ChangeContext(base_sha=base_sha, head_sha=head_sha, title=title, description=description,
+                         files=files, full_patch=full_patch)
+
+
+@contextmanager
+def worktree(repo: Path, sha: str, label: str, link_paths: list[str] | None = None) -> Iterator[Path]:
+    """Create a detached worktree at `sha`; symlink heavy dependency dirs from the main checkout."""
+    tmp = Path(tempfile.mkdtemp(prefix=f"jcwt-{label}-"))
+    wt = tmp / "wt"
+    git(repo, "worktree", "add", "--detach", "--force", str(wt), sha)
+    try:
+        for rel in link_paths or []:
+            _link_dependency_dirs(repo, wt, rel)
+        yield wt
+    finally:
+        git(repo, "worktree", "remove", "--force", str(wt), check=False)
+        shutil.rmtree(tmp, ignore_errors=True)
+        git(repo, "worktree", "prune", check=False)
+
+
+def _link_dependency_dirs(repo: Path, wt: Path, name: str) -> None:
+    """Symlink every `name` directory (e.g. node_modules) that exists in the main checkout,
+    including nested ones in monorepos, unless the worktree already contains it."""
+    if "/" in name or os.sep in name:
+        candidates = [repo / name]
+    else:
+        candidates = []
+        for dirpath, dirnames, _ in os.walk(repo):
+            rel = Path(dirpath).relative_to(repo)
+            if rel.parts and rel.parts[0] in (".git", ".jitcatch"):
+                dirnames[:] = []
+                continue
+            if name in dirnames:
+                candidates.append(Path(dirpath) / name)
+                dirnames.remove(name)  # don't descend into node_modules
+            # don't descend into other dependency/build dirs
+            dirnames[:] = [d for d in dirnames if d not in (".git", "node_modules", ".venv", "venv", "target", "build", "dist")]
+    for src in candidates:
+        if not src.exists():
+            continue
+        dst = wt / src.relative_to(repo)
+        if dst.exists() or dst.is_symlink():
+            continue
+        dst.parent.mkdir(parents=True, exist_ok=True)
+        os.symlink(src, dst, target_is_directory=src.is_dir())

jitcatch/hook.py

@@ -0,0 +1,98 @@
+"""git pre-push hook installation and execution."""
+from __future__ import annotations
+
+import os
+import stat
+import subprocess
+import sys
+from pathlib import Path
+
+from .gitutil import git
+
+ZERO = "0" * 40
+HOOK_TAG = "# jitcatch pre-push hook"
+
+
+def hooks_dir(repo: Path) -> Path:
+    """Absolute hooks directory, honouring core.hooksPath."""
+    custom = git(repo, "config", "--get", "core.hooksPath", check=False).strip()
+    p = Path(custom) if custom else Path(git(repo, "rev-parse", "--git-path", "hooks").strip())
+    return p if p.is_absolute() else (repo / p).resolve()
+
+
+def install(repo: Path, blocking: bool, force: bool = False) -> Path:
+    d = hooks_dir(repo)
+    d.mkdir(parents=True, exist_ok=True)
+    path = d / "pre-push"
+    if path.exists() and HOOK_TAG not in path.read_text(encoding="utf-8", errors="replace") and not force:
+        raise FileExistsError(f"{path} already exists and was not installed by jitcatch (use --force to overwrite)")
+    flag = " --blocking" if blocking else ""
+    path.write_text(
+        "#!/bin/sh\n"
+        f"{HOOK_TAG}\n"
+        "# Set JITCATCH_SKIP=1 to bypass for a single push.\n"
+        '[ "$JITCATCH_SKIP" = "1" ] && exit 0\n'
+        f'exec "{sys.executable}" -m jitcatch hook-run --remote "$1"{flag}\n',
+        encoding="utf-8",
+    )
+    path.chmod(path.stat().st_mode | stat.S_IXUSR | stat.S_IXGRP | stat.S_IXOTH)
+    return path
+
+
+def uninstall(repo: Path) -> bool:
+    path = hooks_dir(repo) / "pre-push"
+    if path.exists() and HOOK_TAG in path.read_text(encoding="utf-8", errors="replace"):
+        path.unlink()
+        return True
+    return False
+
+
+def ranges_from_stdin(repo: Path, remote: str, default_branch: str | None, stdin_text: str) -> list[tuple[str, str]]:
+    """Parse pre-push stdin ("<local ref> <local sha> <remote ref> <remote sha>") into (base, head) pairs."""
+    out = []
+    for line in stdin_text.splitlines():
+        parts = line.split()
+        if len(parts) != 4:
+            continue
+        _lref, lsha, _rref, rsha = parts
+        if lsha == ZERO:          # branch deletion
+            continue
+        if rsha != ZERO and _commit_exists(repo, rsha):
+            out.append((rsha, lsha))     # updating an existing remote branch
+            continue
+        base = _default_base(repo, remote, default_branch)
+        if base:
+            out.append((base, lsha))
+    return out
+
+
+def _commit_exists(repo: Path, sha: str) -> bool:
+    return subprocess.run(["git", "cat-file", "-e", f"{sha}^{{commit}}"], cwd=repo,
+                          capture_output=True).returncode == 0
+
+
+def _default_base(repo: Path, remote: str, default_branch: str | None) -> str | None:
+    cands = []
+    if default_branch:
+        if "/" not in default_branch:
+            cands.append(f"{remote}/{default_branch}")
+        cands.append(default_branch)   # also accept a local branch / explicit ref
+    head_ref = git(repo, "symbolic-ref", "--quiet", f"refs/remotes/{remote}/HEAD", check=False).strip()
+    if head_ref:
+        cands.append(head_ref)
+    cands += [f"{remote}/main", f"{remote}/master"]
+    for c in cands:
+        if _commit_exists(repo, c):
+            return c
+    return None
+
+
+def stdin_text() -> str:
+    try:
+        return sys.stdin.read() if not sys.stdin.isatty() else ""
+    except (OSError, ValueError):
+        return ""
+
+
+def env_skip() -> bool:
+    return os.environ.get("JITCATCH_SKIP") == "1"

jitcatch/jsonutil.py

@@ -0,0 +1,87 @@
+"""Robust extraction of JSON objects and code blocks from LLM output."""
+from __future__ import annotations
+
+import json
+import re
+from typing import Any
+
+_FENCE_RE = re.compile(r"```([a-zA-Z0-9_+\-]*)\s*\n(.*?)```", re.DOTALL)
+
+
+class LLMFormatError(ValueError):
+    pass
+
+
+def extract_json(text: str) -> Any:
+    """Return the first JSON object/array found in `text`.
+
+    Tries, in order: whole text, ```json fenced blocks, any fenced block, then the
+    first balanced {...} or [...] span (string-aware).
+    """
+    stripped = text.strip()
+    for candidate in _candidates(stripped):
+        try:
+            return json.loads(candidate)
+        except json.JSONDecodeError:
+            continue
+    raise LLMFormatError(f"No valid JSON found in model output: {text[:300]!r}")
+
+
+def _candidates(text: str):
+    yield text
+    fences = _FENCE_RE.findall(text)
+    for lang, body in fences:
+        if lang.lower() == "json":
+            yield body.strip()
+    for _lang, body in fences:
+        yield body.strip()
+    span = _first_balanced(text)
+    if span is not None:
+        yield span
+
+
+def _first_balanced(text: str) -> str | None:
+    openers = {"{": "}", "[": "]"}
+    for start, ch in enumerate(text):
+        if ch not in openers:
+            continue
+        stack = [openers[ch]]
+        in_str = False
+        esc = False
+        for i in range(start + 1, len(text)):
+            c = text[i]
+            if in_str:
+                if esc:
+                    esc = False
+                elif c == "\\":
+                    esc = True
+                elif c == '"':
+                    in_str = False
+                continue
+            if c == '"':
+                in_str = True
+            elif c in openers:
+                stack.append(openers[c])
+            elif stack and c == stack[-1]:
+                stack.pop()
+                if not stack:
+                    candidate = text[start : i + 1]
+                    try:
+                        json.loads(candidate)
+                        return candidate
+                    except json.JSONDecodeError:
+                        break
+    return None
+
+
+def extract_code(text: str, preferred_langs: tuple[str, ...] = ()) -> str:
+    """Return the largest fenced code block (preferring the given languages).
+
+    If no fence is present the whole text is returned stripped.
+    """
+    fences = _FENCE_RE.findall(text)
+    if not fences:
+        return text.strip() + "\n"
+    preferred = [b for lang, b in fences if lang.lower() in preferred_langs]
+    pool = preferred or [b for _l, b in fences]
+    return max(pool, key=len).rstrip() + "\n"

jitcatch/llm/__init__.py

@@ -0,0 +1,21 @@
+from __future__ import annotations
+
+from ..config import ProviderConfig
+from .base import LLMClient, LLMError, LLMResponse, TokenLogprob
+from .providers import AnthropicClient, OpenAIChatClient, OpenAIResponsesClient
+
+_TYPES = {
+    "anthropic": AnthropicClient,
+    "openai_chat": OpenAIChatClient,
+    "openai_responses": OpenAIResponsesClient,
+}
+
+
+def build_client(cfg: ProviderConfig) -> LLMClient:
+    try:
+        return _TYPES[cfg.type](cfg)
+    except KeyError:
+        raise LLMError(f"unknown provider type {cfg.type!r}") from None
+
+
+__all__ = ["LLMClient", "LLMError", "LLMResponse", "TokenLogprob", "build_client"]

jitcatch/llm/base.py

@@ -0,0 +1,100 @@
+"""Provider-agnostic LLM interface."""
+from __future__ import annotations
+
+import json
+import random
+import time
+import urllib.error
+import urllib.request
+from dataclasses import dataclass, field
+from typing import Any
+
+from ..config import ProviderConfig
+
+
+class LLMError(RuntimeError):
+    pass
+
+
+@dataclass
+class TokenLogprob:
+    token: str
+    logprob: float
+    top: dict[str, float] = field(default_factory=dict)   # alternative token -> logprob
+
+
+@dataclass
+class LLMResponse:
+    text: str
+    model: str
+    provider: str
+    logprobs: list[TokenLogprob] | None = None
+    usage: dict[str, Any] = field(default_factory=dict)
+
+
+class LLMClient:
+    """Base class. Subclasses implement `_complete`."""
+
+    def __init__(self, cfg: ProviderConfig):
+        self.cfg = cfg
+        self.name = cfg.name
+
+    def complete(self, system: str, user: str, *, max_tokens: int | None = None,
+                 want_logprobs: bool = False) -> LLMResponse:
+        # Per-call budgets are minimums; the provider's configured max_tokens wins when larger. Thinking
+        # models (e.g. GLM-5.3, which always reasons) spend part of the budget on reasoning tokens, so a
+        # small hard-coded budget can end before any answer is produced. Logprob probes keep their exact
+        # budget: they only read the first answer token.
+        if want_logprobs and max_tokens:
+            budget = max_tokens
+        else:
+            budget = max(max_tokens or 0, self.cfg.max_tokens)
+        return self._complete(system, user, budget, want_logprobs)
+
+    def _complete(self, system: str, user: str, max_tokens: int, want_logprobs: bool) -> LLMResponse:
+        raise NotImplementedError
+
+    def _finalize(self, body: dict[str, Any], default_max_field: str) -> dict[str, Any]:
+        field_name = self.cfg.max_tokens_field or default_max_field
+        if field_name != default_max_field and default_max_field in body:
+            body[field_name] = body.pop(default_max_field)
+        body.update(self.cfg.extra_body)
+        for k in self.cfg.omit_params:
+            body.pop(k, None)
+        return body
+
+    # -- HTTP --------------------------------------------------------------------------
+    def _post_json(self, url: str, body: dict[str, Any], headers: dict[str, str]) -> dict[str, Any]:
+        data = json.dumps(body).encode("utf-8")
+        all_headers = {"Content-Type": "application/json", **headers, **self.cfg.extra_headers}
+        last_err: Exception | None = None
+        for attempt in range(self.cfg.max_retries + 1):
+            req = urllib.request.Request(url, data=data, headers=all_headers, method="POST")
+            try:
+                with urllib.request.urlopen(req, timeout=self.cfg.timeout_s) as resp:
+                    return json.loads(resp.read().decode("utf-8"))
+            except urllib.error.HTTPError as e:
+                payload = e.read().decode("utf-8", errors="replace")[:2000]
+                last_err = LLMError(f"{self.name}: HTTP {e.code} from {url}: {payload}")
+                if e.code not in (408, 409, 429, 500, 502, 503, 504, 529):
+                    raise last_err from None
+                retry_after = e.headers.get("retry-after") if e.headers else None
+                delay = _parse_retry_after(retry_after)
+            except (urllib.error.URLError, TimeoutError, ConnectionError) as e:
+                last_err = LLMError(f"{self.name}: request to {url} failed: {e}")
+                delay = None
+            except json.JSONDecodeError as e:
+                raise LLMError(f"{self.name}: non-JSON response from {url}: {e}") from None
+            if attempt < self.cfg.max_retries:
+                time.sleep(delay if delay is not None else min(60.0, (2 ** attempt) + random.random()))
+        assert last_err is not None
+        raise last_err
+
+
+def _parse_retry_after(v: str | None) -> float | None:
+    if not v:
+        return None
+    try:
+        return min(120.0, float(v))
+    except ValueError:
+        return None

jitcatch/llm/providers.py

@@ -0,0 +1,127 @@
+"""Concrete clients: Anthropic Messages, OpenAI Chat Completions, OpenAI Responses.
+
+Each also works with API-compatible servers (Z.ai Coding Plan, Ollama, LM Studio, vLLM, proxies)
+by changing `base_url`.
+"""
+from __future__ import annotations
+
+from typing import Any
+
+from .base import LLMClient, LLMError, LLMResponse, TokenLogprob
+
+
+def _join(base: str, path: str) -> str:
+    return base.rstrip("/") + "/" + path.lstrip("/")
+
+
+class AnthropicClient(LLMClient):
+    """POST {base_url}/v1/messages."""
+
+    def _complete(self, system: str, user: str, max_tokens: int, want_logprobs: bool) -> LLMResponse:
+        if want_logprobs:
+            raise LLMError(f"{self.name}: the Anthropic Messages API does not return token log-probabilities")
+        headers = {"anthropic-version": "2023-06-01"}
+        key = self.cfg.resolve_api_key()
+        if key:
+            if self.cfg.auth == "x-api-key":
+                headers["x-api-key"] = key
+            else:
+                headers["Authorization"] = f"Bearer {key}"
+        body: dict[str, Any] = {
+            "model": self.cfg.model,
+            "max_tokens": max_tokens,
+            "system": system,
+            "messages": [{"role": "user", "content": user}],
+        }
+        if self.cfg.temperature is not None:
+            body["temperature"] = self.cfg.temperature
+        body = self._finalize(body, "max_tokens")
+        data = self._post_json(_join(self.cfg.base_url, "v1/messages"), body, headers)
+        parts = [b.get("text", "") for b in data.get("content", []) if b.get("type") == "text"]
+        if not parts:
+            raise LLMError(f"{self.name}: response had no text content: {str(data)[:500]}")
+        return LLMResponse(text="".join(parts), model=data.get("model", self.cfg.model),
+                           provider=self.name, usage=data.get("usage", {}))
+
+
+class OpenAIChatClient(LLMClient):
+    """POST {base_url}/chat/completions (OpenAI-compatible /v1 servers)."""
+
+    def _complete(self, system: str, user: str, max_tokens: int, want_logprobs: bool) -> LLMResponse:
+        headers = {}
+        key = self.cfg.resolve_api_key()
+        if key:
+            headers["Authorization"] = f"Bearer {key}"
+        body: dict[str, Any] = {
+            "model": self.cfg.model,
+            "messages": [
+                {"role": "system", "content": system},
+                {"role": "user", "content": user},
+            ],
+            "max_tokens": max_tokens,
+        }
+        if self.cfg.temperature is not None:
+            body["temperature"] = self.cfg.temperature
+        if want_logprobs:
+            if not self.cfg.logprobs:
+                raise LLMError(f"{self.name}: logprobs requested but provider has logprobs = false")
+            body["logprobs"] = True
+            body["top_logprobs"] = 5
+        body = self._finalize(body, "max_tokens")
+        data = self._post_json(_join(self.cfg.base_url, "chat/completions"), body, headers)
+        choices = data.get("choices") or []
+        if not choices:
+            raise LLMError(f"{self.name}: response had no choices: {str(data)[:500]}")
+        msg = choices[0].get("message") or {}
+        text = msg.get("content") or ""
+        if isinstance(text, list):  # some servers return content parts
+            text = "".join(p.get("text", "") for p in text if isinstance(p, dict))
+        lps = None
+        lp_block = choices[0].get("logprobs")
+        if want_logprobs and lp_block and lp_block.get("content"):
+            lps = [
+                TokenLogprob(
+                    token=t.get("token", ""),
+                    logprob=float(t.get("logprob", 0.0)),
+                    top={a.get("token", ""): float(a.get("logprob", 0.0)) for a in (t.get("top_logprobs") or [])},
+                )
+                for t in lp_block["content"]
+            ]
+        return LLMResponse(text=text, model=data.get("model", self.cfg.model), provider=self.name,
+                           logprobs=lps, usage=data.get("usage", {}))
+
+
+class OpenAIResponsesClient(LLMClient):
+    """POST {base_url}/responses."""
+
+    def _complete(self, system: str, user: str, max_tokens: int, want_logprobs: bool) -> LLMResponse:
+        if want_logprobs:
+            raise LLMError(f"{self.name}: logprob judging is only supported via openai_chat providers")
+        headers = {}
+        key = self.cfg.resolve_api_key()
+        if key:
+            headers["Authorization"] = f"Bearer {key}"
+        body: dict[str, Any] = {
+            "model": self.cfg.model,
+            "instructions": system,
+            "input": user,
+            "max_output_tokens": max_tokens,
+        }
+        if self.cfg.temperature is not None:
+            body["temperature"] = self.cfg.temperature
+        body = self._finalize(body, "max_output_tokens")
+        data = self._post_json(_join(self.cfg.base_url, "responses"), body, headers)
+        text = data.get("output_text")
+        if not text:
+            chunks = []
+            for item in data.get("output") or []:
+                if item.get("type") != "message":
+                    continue
+                for c in item.get("content") or []:
+                    if c.get("type") == "output_text":
+                        chunks.append(c.get("text", ""))
+            text = "".join(chunks)
+        if not text:
+            raise LLMError(f"{self.name}: response had no output_text: {str(data)[:500]}")
+        return LLMResponse(text=text, model=data.get("model", self.cfg.model), provider=self.name,
+                           usage=data.get("usage", {}))