codegraph-brain 0.6.0__py3-none-any.whl

cgis/guardian/github_poster.py

@@ -0,0 +1,133 @@
+"""Posts a ReviewResult as one GitHub review with inline comments (spec §6)."""
+
+import json
+import subprocess
+
+from cgis.guardian.findings import Finding, ReviewResult
+from cgis.guardian.render import render_inline_comment, render_review_body
+from cgis.guardian.skeptic import visible_findings
+
+#: Below this length a quote is too generic to substring-match safely — short
+#: keywords/patterns (``)``, ``else:``, ``self.``, ``return``) would collide with
+#: unrelated lines (``something_else:``, ``myself.foo``). Such a quote may only
+#: anchor via an EXACT line equality, never a substring (#181 review). A real
+#: anchor is a full statement, comfortably longer than this.
+_MIN_SUBSTRING_ANCHOR = 10
+
+
+def _anchored_line(finding: Finding, content: dict[int, str] | None) -> int | None:
+    """Derive the inline line from the finding's verbatim quote, not the model's guess (#181).
+
+    Searches the file's RIGHT-side lines for the one matching the finding's
+    ``anchor`` (falling back to ``evidence``) and returns its real number:
+    - no quote or no file content → keep the model's ``line`` (legacy behaviour);
+    - an **exact** stripped-line match wins; only if there is none do we fall back
+      to a substring match (``needle in line``), and only for quotes long enough
+      that a substring is meaningful — so a ``)`` or ``else:`` can never pull a
+      comment onto an unrelated trivial line;
+    - among the candidates: the model's ``line`` if it is one, else the nearest;
+    - quote present but located nowhere → ``None``, demoting to a body comment
+      instead of a confidently-wrong inline anchor.
+
+    A finding the model marked file-level (``line is None``) with no explicit
+    ``anchor`` stays file-level: ``evidence`` is supporting text, not a
+    positional signal, so it must not promote a file-level note to an inline
+    comment at a coincidental textual match (#243 review).
+    """
+    if finding.line is None and finding.anchor is None:
+        return None
+    quote = (finding.anchor or finding.evidence or "").strip()
+    if not content or not quote:
+        return finding.line
+    needle = next((seg.strip() for seg in quote.splitlines() if seg.strip()), "")
+    if not needle:
+        return finding.line
+    matches = [n for n, text in content.items() if text.strip() == needle]
+    if not matches and len(needle) >= _MIN_SUBSTRING_ANCHOR:
+        matches = [n for n, text in content.items() if needle in text.strip()]
+    if not matches:
+        return None
+    if finding.line is None:
+        return matches[0]
+    model_line = finding.line  # bound local so the closure narrows it to int (mypy)
+    if model_line in matches:
+        return model_line
+    return min(matches, key=lambda n: (abs(n - model_line), n))
+
+
+def build_review(
+    result: ReviewResult,
+    *,
+    diff_index: dict[str, set[int]],
+    skeptic_model: str | None,
+    footer: str = "",
+    diff_content: dict[str, dict[int, str]] | None = None,
+    threshold: int = 0,
+) -> tuple[str, list[dict[str, object]]]:
+    """Split findings into inline comments vs body text (pure, spec §6.2).
+
+    A finding whose line is commentable becomes an inline comment; line=None
+    or out-of-diff findings land in the review body. Nothing is lost. The
+    footer (model/tokens/coverage) is appended to the body: before inline
+    posting existed it always reached the PR via the fallback comment, but a
+    successful inline post skips that comment — so it must travel here too.
+
+    When ``diff_content`` is supplied, each finding's line is first re-anchored
+    from its verbatim quote (#181) so the comment lands on the real line rather
+    than the model's estimate; an unlocatable quote demotes to a body comment.
+    """
+    content_by_file = diff_content if diff_content is not None else {}
+    inline: list[Finding] = []
+    outside: list[Finding] = []
+    for raw in visible_findings(result.findings, threshold):
+        line = _anchored_line(raw, content_by_file.get(raw.file))
+        finding = raw if line == raw.line else raw.model_copy(update={"line": line})
+        if finding.line is not None and finding.line in diff_index.get(finding.file, set()):
+            inline.append(finding)
+        else:
+            outside.append(finding)
+    comments: list[dict[str, object]] = [
+        {
+            "path": f.file,
+            "line": f.line,
+            "side": "RIGHT",
+            "body": render_inline_comment(f, skeptic_model=skeptic_model),
+        }
+        for f in inline
+    ]
+    return render_review_body(result, outside=outside, threshold=threshold) + footer, comments
+
+
+def post_inline_review(
+    *,
+    repo: str,
+    pr: int,
+    result: ReviewResult,
+    diff_index: dict[str, set[int]],
+    skeptic_model: str | None,
+    footer: str = "",
+    diff_content: dict[str, dict[int, str]] | None = None,
+    threshold: int = 0,
+) -> None:
+    """POST one COMMENT review via `gh api` (auto-auth in Actions, spec §6.4).
+
+    Always event=COMMENT, never REQUEST_CHANGES — guardian is an advisor,
+    not a gate. Raises CalledProcessError on API rejection; the caller
+    decides the fallback (spec §6.5).
+    """
+    body, comments = build_review(
+        result,
+        diff_index=diff_index,
+        skeptic_model=skeptic_model,
+        footer=footer,
+        diff_content=diff_content,
+        threshold=threshold,
+    )
+    payload = {"event": "COMMENT", "body": body, "comments": comments}
+    subprocess.run(
+        ["gh", "api", f"repos/{repo}/pulls/{pr}/reviews", "-X", "POST", "--input", "-"],
+        input=json.dumps(payload),
+        text=True,
+        check=True,
+        capture_output=True,
+    )

cgis/guardian/metrics.py

@@ -0,0 +1,108 @@
+"""Guardian review quality metrics: append-only JSONL log with precision tracking."""
+
+import json
+from datetime import UTC, datetime
+from pathlib import Path
+from typing import Any
+
+from pydantic import BaseModel
+
+_DEFAULT_METRICS_FILE = Path("guardian_metrics.jsonl")
+
+
+class SkepticRecord(BaseModel, frozen=True):
+    """What the skeptic pass did, for one review's metrics row (#246).
+
+    Grouped rather than passed as four loose keywords: they are meaningless
+    apart — `judged`/`total` only interpret `status`, and `impact_threshold`
+    only interprets what the report then hid.
+    """
+
+    model: str | None = None
+    status: str = "off"
+    judged: int = 0
+    total: int = 0
+    impact_threshold: int = 0
+
+
+def record_review(
+    *,
+    model: str,
+    pr: int | None,
+    prompt_tokens: int,
+    completion_tokens: int,
+    findings_total: int,
+    lgtm: bool,
+    parse_failed: bool = False,
+    skeptic: SkepticRecord | None = None,
+    chunk_count: int | None = None,
+    duration_s: float | None = None,
+    metrics_path: Path = _DEFAULT_METRICS_FILE,
+) -> Path:
+    """Append one review entry to the metrics JSONL file and return the path.
+
+    Counts come from the structured ReviewResult — no text parsing.
+    Note: lgtm is False on parse_failed runs even though findings_total == 0.
+    """
+    skeptic = skeptic or SkepticRecord()
+    entry = {
+        "timestamp": datetime.now(UTC).isoformat(),
+        "pr": pr,
+        "model": model,
+        "prompt_tokens": prompt_tokens,
+        "completion_tokens": completion_tokens,
+        "total_tokens": prompt_tokens + completion_tokens,
+        "findings_total": findings_total,
+        "findings_applied": None,
+        "lgtm": lgtm,
+        "parse_failed": parse_failed,
+        "skeptic_model": skeptic.model,
+        "skeptic_status": skeptic.status,
+        "skeptic_judged": skeptic.judged,
+        "skeptic_total": skeptic.total,
+        "impact_threshold": skeptic.impact_threshold,
+        "chunk_count": chunk_count,
+        # Wall-clock of the whole LLM phase (finder + skeptic). None on entries
+        # written before #275. Completed runs only — a failing review writes no
+        # record at all, so this data is survivorship-biased by construction.
+        "duration_s": duration_s,
+    }
+    with metrics_path.open("a", encoding="utf-8") as fh:
+        fh.write(json.dumps(entry) + "\n")
+    return metrics_path
+
+
+def rate_review(pr: int, applied: int, metrics_path: Path = _DEFAULT_METRICS_FILE) -> bool:
+    """Set findings_applied for the most recent entry matching the given PR.
+
+    Returns True if an entry was updated, False if none found.
+    """
+    if not metrics_path.exists():
+        return False
+
+    lines = metrics_path.read_text(encoding="utf-8").splitlines()
+    updated = False
+    result: list[str] = []
+    for line in reversed(lines):
+        if not updated:
+            entry = json.loads(line)
+            if entry.get("pr") == pr and entry.get("findings_applied") is None:
+                entry["findings_applied"] = applied
+                line = json.dumps(entry)  # noqa: PLW2901
+                updated = True
+        result.append(line)
+
+    if updated:
+        metrics_path.write_text("\n".join(reversed(result)) + "\n", encoding="utf-8")
+    return updated
+
+
+def load_reviews(metrics_path: Path = _DEFAULT_METRICS_FILE) -> list[dict[str, Any]]:
+    """Return all review records from the metrics file, oldest first."""
+    if not metrics_path.exists():
+        return []
+    return [
+        json.loads(line)
+        for line in metrics_path.read_text(encoding="utf-8").splitlines()
+        if line.strip()
+    ]

cgis/guardian/prompts.py

@@ -0,0 +1,217 @@
+"""Builds system and user prompts for the Guardian LLM reviewer."""
+
+
+class PromptBuilder:
+    """Constructs the system and user prompts."""
+
+    @staticmethod
+    def build_system_prompt() -> str:
+        """Return the system prompt that establishes Guardian's reviewer persona."""
+        return (
+            "You are the CGIS Guardian finder — a Senior Software Architect hunting for "
+            "defects in a code review. You are the FIRST of two stages: a separate skeptic "
+            "verifier runs after you and removes false positives. Because of that division "
+            "of labour, your job is RECALL — surface every plausible real defect. A missed "
+            "bug is the expensive error here; a borderline finding is cheap, because the "
+            "skeptic filters it. Surface a finding whenever you can name a CONCRETE failure "
+            "scenario — a specific input, state, timing, or platform that makes the code "
+            "wrong. Do not self-censor because you are unsure: hand the uncertainty to the "
+            "skeptic with your reasoning, do not suppress it. "
+            "You prioritise: (1) Logic correctness — wrong output, crashes, data corruption; "
+            "(2) Library boundary contracts — convention mismatches at third-party API calls; "
+            "(3) Missing test coverage for real edge cases in the diff; "
+            "(4) Type safety violations that mypy strict would catch; "
+            "(5) Ontology compliance — wrong NodeType/EdgeType mappings corrupt the graph. "
+            "You still do NOT flag style preferences, naming conventions, or design "
+            "disagreements that have no concrete failure scenario. If the code is correct "
+            "and tested, say so."
+        )
+
+    @staticmethod
+    def build_user_prompt(context: dict[str, str]) -> str:
+        """Assemble the user-turn prompt from collected diff, CONTRIBUTING, ontology, and graph."""
+        diff = context.get("diff", "")
+        contributing = context.get("contributing", "")
+        ontology = context.get("ontology", "")
+        graph_context = context.get("graph_context", "")
+
+        graph_section = ""
+        if graph_context:
+            graph_section = f"""
+### 4. STRUCTURAL IMPACT GRAPHS (from graph.db)
+The following Mermaid diagrams show which modules depend on the changed files.
+Use these to identify callers that may be broken or require updates.
+
+{graph_context}
+"""
+
+        full_files = context.get("full_files", "")
+        full_files_section = ""
+        if full_files:
+            full_files_section = f"""
+### 5. FULL FILE CONTENTS (HEAD)
+Complete current text of the changed files (oversized files carry an explicit
+omission note — treat a note as missing context, not missing code).
+
+{full_files}
+"""
+
+        drift = context.get("drift", "")
+        drift_section = ""
+        if drift:
+            drift_section = f"""
+### 6. ARCHITECTURAL DRIFT (motif-basis)
+Per-domain drift vs the declared ideal pattern. A PR pushing a domain past its
+tolerance (⚠) is an `ontology`-category finding. The quotient line is
+observe-only — do NOT flag it.
+
+{drift}
+"""
+
+        contributing_section = ""
+        if contributing:
+            contributing_section = f"""### 1. ENGINEERING STANDARDS (from CONTRIBUTING.md)
+{contributing}
+
+"""
+
+        ontology_section = ""
+        if ontology:
+            ontology_section = f"""### 2. PROJECT ONTOLOGY (from docs/ontology/)
+{ontology}
+
+"""
+
+        return f"""Review the following Pull Request diff for real defects.
+
+{contributing_section}{ontology_section}### 3. CHANGES TO REVIEW (git diff)
+{diff}
+{graph_section}{full_files_section}{drift_section}
+---
+### HUNTING RULES — read before writing a single finding:
+
+1. **Evidence first.** Quote the exact line(s) from the diff that the finding sits on.
+   The quoted text MUST appear verbatim in section 3 (it positions the inline comment).
+   If you cannot find the line, do not raise it.
+
+2. **Surface on a nameable failure scenario.** Before writing a finding, ask yourself:
+   "Can I describe one concrete input, state, timing, or platform where this code
+   misbehaves?" If yes — REPORT it, and put your honest `confidence` in the field.
+   Confidence does NOT gate inclusion: a 40%-confident finding with a real failure
+   scenario is worth surfacing, because the skeptic verifier decides what to keep.
+   Only drop a candidate when you cannot construct ANY failure scenario for it.
+
+3. **No ghost issues.** If the code already handles a case, acknowledge it and move on.
+   Do not flag something as missing when it is present (this is a wrong finding, not
+   an uncertain one — the skeptic cannot rescue precision from a fabricated claim).
+
+4. **No invented rules.** Only cite standards explicitly written in CONTRIBUTING.md or the
+   ontology files provided above. Do not apply rules from outside this context.
+
+5. **No finding cap.** Report every real candidate you find — more genuine findings is
+   strictly better here, since recall is your job and the skeptic trims the list. Order
+   them most-severe first. Zero is still a valid answer when the diff is clean.
+
+6. **Reason per changed function before deciding.** For each function the diff touches,
+   briefly walk these before you write findings for it:
+   - What are its inputs and where do they come from (caller, config/YAML/JSON, env,
+     request)? Is any of them external/untrusted?
+   - What happens on the awkward inputs: empty / None / zero / a non-dict where a dict
+     is assumed / a scalar where an iterable is assumed / unsorted / duplicate / oversized?
+   - Did a deleted or changed line hold an invariant (a guard, a validation, an error
+     path)? Is it re-established?
+   Only after that walk do you decide what to surface. Skipping this walk is the main
+   reason subtle defects (unvalidated data, exact-equality, dropped guards) go unseen.
+
+---
+### WHAT TO LOOK FOR (focus areas):
+
+**Logic bugs** — inputs that produce wrong output, division by zero, off-by-one errors,
+incorrect algorithm behaviour. Think: empty collections, None values, boundary conditions.
+
+**Unvalidated external data** — a value read from config/YAML/JSON, env, or a request is
+used as a `dict`/`list`/`set`/iterable (subscripted, iterated, passed to `set()`/`dict()`,
+`.items()`, `for x in value`) without first checking its type or presence. A YAML key the
+author expects to be a mapping can legally be a scalar or a list; a `value or {{}}` idiom
+catches `None` but lets a non-dict truthy value through to operations that then misbehave
+silently rather than erroring. Flag each such use that lacks a type/shape guard.
+
+**Exact-equality on floats / money** — bare `==` or `!=` comparing floating-point or
+Decimal values, *including in test assertions* (`assert x == 0.3`). Floating-point
+rounding makes these flaky or wrong; they should use a tolerance compare. Check changed
+test files for this too.
+
+**Missing test coverage** — code paths in the diff that have no test. Focus on edge cases
+that could silently return wrong results (not just "coverage for coverage's sake").
+
+**Type safety** — implicit `Any`, missing return type annotations, unsafe casts, Pydantic
+models constructed with wrong field types.
+
+**Library boundary contracts** — for each call into a third-party library, verify that
+the data passed in matches the library's expected convention:
+  - Units and coordinate systems (e.g. center vs top-left, row/col vs x/y,
+    naive vs timezone-aware datetimes)
+  - Ordering assumptions (e.g. does array order affect rendering or sort stability?)
+  - Ownership and mutation (e.g. does the library mutate its input?)
+Trace the value from where it's produced to where it's consumed across the library call.
+If the producing code and consuming code have different assumptions, that's a bug.
+
+**Ontology compliance** — wrong NodeType/EdgeType assignments, FQNs not derived from file
+paths, unresolved calls not using `raw_call:` prefix.
+
+---
+### WORKED EXAMPLES (how the per-function walk turns into a finding):
+
+These show the kind of subtle, borderline defect that is easy to skip but worth surfacing.
+Do not look for these exact lines — learn the *pattern* and apply it to the diff above.
+
+Example A — unvalidated config value used as a mapping:
+```
+def layers_for(self, name: str) -> set[str]:
+    cfg = self._patterns.get(name)        # cfg comes from a YAML file
+    return set(cfg)                        # <-- assumes cfg is iterable-of-str
+```
+Walk: input `cfg` is external (YAML); the author assumes a list/mapping, but YAML lets
+that key be a scalar (`name: layered`) → `set("layered")` silently yields `{{'l','a',...}}`,
+not an error. → FINDING: `set(cfg)` lacks a type/shape guard on external config data.
+(confidence ~50 — borderline, but it has a concrete failure scenario, so surface it.)
+
+Example B — exact-equality on floats in a test:
+```
+def test_drift_score():
+    assert scorer.score(fp) == 0.3        # <-- bare == on a float result
+```
+Walk: `score()` returns a computed float; `== 0.3` is exact float equality → rounding can
+make this assert flaky/false. → FINDING: float compared with bare `==` in a test; use a
+tolerance (`pytest.approx` / `math.isclose`). (confidence ~55.)
+
+---
+### OUTPUT FORMAT:
+
+Return ONLY a JSON object — no prose, no markdown fences — with this exact shape:
+
+{{"findings": [{{"file": "src/path/to/file.py", "line": 123,
+  "anchor": "<the exact source line this finding sits on, copied verbatim from section 3>",
+  "severity": "critical|major|minor",
+  "category": "logic|contract|tests|types|ontology",
+  "title": "short headline",
+  "evidence": "<verbatim quote from the diff>",
+  "problem": "one sentence.", "fix": "concrete suggestion.",
+  "confidence": 85}}],
+  "summary": "2-3 most important things you checked and found correct."}}
+
+Rules:
+- "severity": exactly one of "critical", "major", "minor". "confidence" is an integer 0-100.
+- "category" maps to the focus areas: logic = Logic Bug, contract = Library Contract,
+  tests = Test Coverage, types = Type Safety, ontology = Ontology.
+- "line" is the line number in the HEAD version of the file, or null for file-level findings.
+- "anchor" is the single exact line of code the finding refers to, copied VERBATIM from the
+  diff in section 3 (no paraphrasing, no `+`/`-` marker). It is used to position the inline
+  comment deterministically — if your "line" guess is off, a correct "anchor" still lands the
+  comment on the right line. Use null only for genuinely file-level findings.
+- "confidence" is your honest 0-100 estimate; it does NOT gate inclusion — the skeptic
+  verifier uses it to prioritise, so report findings below 80 too.
+- no finding cap; report every real candidate, most-severe first; an empty list means LGTM.
+- "summary" is mandatory; for an LGTM it lists what you checked and found correct.
+
+Example LGTM response: {{"findings": [], "summary": "Checked diff for logic and types; ok."}}"""

cgis/guardian/providers/__init__.py

@@ -0,0 +1 @@
+"""LLM provider implementations for Guardian."""

cgis/guardian/providers/base.py

@@ -0,0 +1,112 @@
+"""Abstract base class for LLM provider implementations."""
+
+import abc
+import asyncio
+from collections.abc import Awaitable, Callable
+
+import httpx
+import structlog
+from pydantic import BaseModel, computed_field
+
+log = structlog.getLogger(__name__)
+
+#: Request timeout in SECONDS. Mistral and Gemini take milliseconds and Ollama
+#: takes seconds, so each provider converts at its own call site — the unit is
+#: visible where the conversion happens rather than buried in a constant's name.
+DEFAULT_REQUEST_TIMEOUT = 180.0
+
+#: Total attempts per call, including the first.
+MAX_ATTEMPTS = 3
+
+#: Backoff base: sleeps are BACKOFF_BASE ** attempt — 2 s, then 4 s.
+BACKOFF_BASE = 2.0
+
+#: Retried transport failures. Deliberately the same set the Mistral SDK itself
+#: retries (mistralai/client/utils/retries.py) rather than a list invented here.
+#: google-genai reraises httpx exceptions too, and httpx.NetworkError is the
+#: parent of ConnectError, so this covers every provider.
+RETRYABLE_EXCEPTIONS: tuple[type[Exception], ...] = (
+    httpx.TimeoutException,
+    httpx.NetworkError,
+)
+
+
+class ProviderUsage(BaseModel, frozen=True):
+    """Token usage reported by the LLM after a single generate_content call."""
+
+    prompt_tokens: int = 0
+    completion_tokens: int = 0
+
+    @computed_field  # type: ignore[prop-decorator]
+    @property
+    def total_tokens(self) -> int:
+        """Total tokens consumed by this LLM request, used for cost tracking."""
+        return self.prompt_tokens + self.completion_tokens
+
+
+class BaseProvider(abc.ABC):
+    """Abstract base class for LLM providers."""
+
+    def __init__(self) -> None:
+        """Initialise usage counters to zero.
+
+        last_usage reflects the most recent LLM call; cumulative_usage sums
+        every call this provider instance has made (a chunked review makes
+        N finder calls — and even a single-pass review makes 2 on a parse
+        retry, whose first call last_usage used to silently drop).
+        """
+        self.last_usage: ProviderUsage = ProviderUsage()
+        self.cumulative_usage: ProviderUsage = ProviderUsage()
+
+    def _record_usage(self, usage: ProviderUsage) -> None:
+        """Record one call's token usage: set last_usage, add to cumulative."""
+        self.last_usage = usage
+        self.cumulative_usage = ProviderUsage(
+            prompt_tokens=self.cumulative_usage.prompt_tokens + usage.prompt_tokens,
+            completion_tokens=self.cumulative_usage.completion_tokens + usage.completion_tokens,
+        )
+
+    async def _sleep(self, seconds: float) -> None:
+        """Wait between retries. Overridden in tests so they do not actually wait."""
+        await asyncio.sleep(seconds)
+
+    async def _retry(self, call: Callable[[], Awaitable[str]]) -> str:
+        """Run call, retrying transient transport failures with exponential backoff.
+
+        Retries only RETRYABLE_EXCEPTIONS: an auth or validation failure must
+        fail on the first attempt rather than burn MAX_ATTEMPTS calls. The final
+        exception propagates unchanged so callers' existing degradation paths
+        still see a real error (#275).
+        """
+        for attempt in range(1, MAX_ATTEMPTS + 1):
+            try:
+                return await call()
+            except RETRYABLE_EXCEPTIONS as exc:
+                if attempt == MAX_ATTEMPTS:
+                    log.warning(
+                        "Provider call failed; retries exhausted.",
+                        attempts=MAX_ATTEMPTS,
+                        error=repr(exc),
+                    )
+                    raise
+                delay = BACKOFF_BASE**attempt
+                log.warning(
+                    "Provider call failed; retrying.",
+                    attempt=attempt,
+                    of=MAX_ATTEMPTS,
+                    delay_s=delay,
+                    error=repr(exc),
+                )
+                await self._sleep(delay)
+        # Unreachable: the loop either returns or raises on the last attempt.
+        raise AssertionError
+
+    @abc.abstractmethod
+    async def generate_content(self, system_prompt: str, user_prompt: str) -> str:
+        """Send a prompt to the LLM and return the text response."""
+
+    @abc.abstractmethod
+    async def generate_structured(
+        self, system_prompt: str, user_prompt: str, schema: type[BaseModel]
+    ) -> str:
+        """Send a prompt requesting JSON conforming to schema; return raw JSON text."""

cgis/guardian/providers/gemini.py

@@ -0,0 +1,83 @@
+"""Google Gemini LLM provider for Guardian."""
+
+from pydantic import BaseModel
+
+from cgis.guardian.providers.base import DEFAULT_REQUEST_TIMEOUT, BaseProvider, ProviderUsage
+
+
+class GeminiProvider(BaseProvider):
+    """Google Gemini provider. Requires: uv sync --group guardian"""
+
+    def __init__(
+        self,
+        api_key: str,
+        model_name: str = "gemini-2.5-flash",
+        timeout: float = DEFAULT_REQUEST_TIMEOUT,
+    ) -> None:
+        """Store credentials and the request timeout; google-genai is imported lazily.
+
+        HttpOptions.timeout is documented in MILLISECONDS — the same unit trap
+        as Mistral, and the opposite of Ollama's seconds.
+        """
+        super().__init__()
+        self._api_key = api_key
+        self._model_name = model_name
+        self._timeout_ms = int(timeout * 1000)
+
+    async def _generate(
+        self, system_prompt: str, user_prompt: str, schema: type[BaseModel] | None
+    ) -> str:
+        """Shared transport: one generate_content call, optional JSON mode."""
+        _install_hint = "google-genai is required. Install with: uv sync --group guardian"
+        try:
+            from google import genai  # noqa: PLC0415
+            from google.genai import types  # noqa: PLC0415
+        except ImportError as exc:
+            raise ImportError(_install_hint) from exc
+        config_kwargs: dict[str, object] = {"system_instruction": system_prompt}
+        if schema is not None:
+            config_kwargs["response_mime_type"] = "application/json"
+            config_kwargs["response_schema"] = schema
+        client = genai.Client(
+            api_key=self._api_key,
+            http_options=types.HttpOptions(timeout=self._timeout_ms),
+        )
+        try:
+            response = await client.aio.models.generate_content(
+                model=self._model_name,
+                contents=user_prompt,
+                config=types.GenerateContentConfig(**config_kwargs),
+            )
+            meta = getattr(response, "usage_metadata", None)
+            if meta is not None:
+                self._record_usage(
+                    ProviderUsage(
+                        prompt_tokens=getattr(meta, "prompt_token_count", 0),
+                        completion_tokens=getattr(meta, "candidates_token_count", 0),
+                    )
+                )
+            return str(response.text)
+        finally:
+            # genai.Client opens BOTH a sync and an async httpx pool on
+            # construction, and each close covers only its own half — the SDK
+            # docstrings say so explicitly in both directions. Mistral and Ollama
+            # get this from `async with`; Gemini's client is not an async context
+            # manager, so it is spelled out here (#283). With the retry from #275
+            # calling this up to MAX_ATTEMPTS times, leaking would compound.
+            try:
+                await client.aio.aclose()
+            finally:
+                # Nested so the sync pool is released even if the async teardown
+                # itself throws — two flat statements would skip it, which is the
+                # exact class of leak this change exists to remove (found in review).
+                client.close()
+
+    async def generate_content(self, system_prompt: str, user_prompt: str) -> str:
+        """Send prompts to Gemini and return the text response."""
+        return await self._retry(lambda: self._generate(system_prompt, user_prompt, None))
+
+    async def generate_structured(
+        self, system_prompt: str, user_prompt: str, schema: type[BaseModel]
+    ) -> str:
+        """Send prompts in native JSON mode constrained by schema."""
+        return await self._retry(lambda: self._generate(system_prompt, user_prompt, schema))