Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
105 changes: 99 additions & 6 deletions .github/workflows/guardian-reusable.yml
Original file line number Diff line number Diff line change
Expand Up @@ -13,13 +13,25 @@ name: Guardian Review (reusable)
# secrets:
# ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
# GUARDIAN_APP_PRIVATE_KEY: ${{ secrets.GUARDIAN_APP_PRIVATE_KEY }}
# permissions: {contents: read, pull-requests: write, issues: write}
# permissions: {contents: read, pull-requests: write, issues: write, id-token: write}
#
# `secrets: inherit` reaches a called workflow only within one organisation or
# enterprise; any other caller passes the secrets declared below by name.
# Variables are always the caller's: GUARDIAN_PROVIDER, GUARDIAN_MODEL,
# GUARDIAN_ANTHROPIC_EFFORT, GUARDIAN_FEATURES, GUARDIAN_SKEPTIC,
# GUARDIAN_SKEPTIC_MODEL, GUARDIAN_APP_CLIENT_ID.
# GUARDIAN_OPENCODE_EFFORT, GUARDIAN_FEATURES, GUARDIAN_SKEPTIC,
# GUARDIAN_SKEPTIC_MODEL, OPENCODE_CLIENT_ID, GUARDIAN_APP_CLIENT_ID.
#
# The opencode-go finder needs no static key: the job exchanges a GitHub OIDC
# token for a short-lived inference token immediately before the review (#775).
# The caller grants `id-token: write` and sets its own OPENCODE_CLIENT_ID
# variable, and OIDC access must be enabled for GitHub Actions in the Opencode
# console. Sign-in happens only when the normalised GUARDIAN_PROVIDER is
# `opencode-go`, `opencode` or empty; an empty value still signs in because the
# minted OPENCODE_API_KEY then makes `_autodetect_provider` pick opencode. An
# explicit other provider logs that OpenCode is not selected and skips cleanly.
# The workflow declares no OPENCODE_API_KEY secret, and the review step must
# not set that variable: a step-level value overrides GITHUB_ENV and would
# discard the minted token.
#
# The caller's Actions policy must allow this workflow and the actions it uses
# (actions/*, astral-sh/setup-uv, peter-evans/create-or-update-comment).
Expand Down Expand Up @@ -59,6 +71,9 @@ on:
type: boolean
default: false
secrets:
# `ANTHROPIC_API_KEY` stays declared and passed so existing callers keep
# working; opencode-go does not require it. There is deliberately no
# OPENCODE_API_KEY secret: the token is minted from GitHub OIDC below.
ANTHROPIC_API_KEY:
required: false
GEMINI_API_KEY:
Expand All @@ -80,6 +95,9 @@ jobs:
contents: read
pull-requests: write
issues: write
# Required to request the OIDC token the OpenCode sign-in exchanges
# (#775). A reusable workflow cannot ask for more than the caller grants.
id-token: write

steps:
# Here rather than in each caller, so no caller can forget it.
Expand Down Expand Up @@ -245,17 +263,92 @@ jobs:
repositories: ${{ github.event.repository.name }}
permission-pull-requests: write

# Minted immediately before the review and only after every step that
# touches the PR checkout, exactly like the App token above (#730, #775):
# the token is short-lived and the code it reviews never sees it. The
# value goes to GITHUB_ENV, which the review step inherits.
- name: Sign in to OpenCode (OIDC)
if: vars.OPENCODE_CLIENT_ID != ''
env:
AUDIENCE: https://opencode.ai/console
CLIENT_ID: ${{ vars.OPENCODE_CLIENT_ID }}
GUARDIAN_PROVIDER: ${{ vars.GUARDIAN_PROVIDER }}
run: |
set -euo pipefail
provider=$(printf '%s' "${GUARDIAN_PROVIDER:-}" | tr '[:upper:]' '[:lower:]')
case "$provider" in
""|opencode-go|opencode) ;;
*)
echo "OpenCode is not the selected provider ($provider); skipping sign-in."
exit 0
;;
esac
# No jq: a self-hosted runner may not have it, the same reason #742
# removed the GitHub CLI dependency. `uv` is installed and the
# environment synced above, so use it rather than assuming `python3`
# is on PATH on a self-hosted runner.
missing=""
[ -n "${ACTIONS_ID_TOKEN_REQUEST_URL:-}" ] || missing="$missing ACTIONS_ID_TOKEN_REQUEST_URL"
[ -n "${ACTIONS_ID_TOKEN_REQUEST_TOKEN:-}" ] || missing="$missing ACTIONS_ID_TOKEN_REQUEST_TOKEN"
if [ -n "$missing" ]; then
echo "::error::GitHub OIDC is unavailable:$missing. Grant id-token: write to this job and to the caller's job."
exit 1
fi

oidc_response=$(curl -sS -w '\n%{http_code}' \
--oauth2-bearer "$ACTIONS_ID_TOKEN_REQUEST_TOKEN" \
"$ACTIONS_ID_TOKEN_REQUEST_URL&audience=$AUDIENCE")
oidc_status=$(printf '%s' "$oidc_response" | tail -n1)
oidc_body=$(printf '%s' "$oidc_response" | sed '$d')
if [ "$oidc_status" -lt 200 ] || [ "$oidc_status" -ge 300 ]; then
# The OIDC response is not printed: it carries a JWT.
echo "::error::GitHub OIDC token request failed with HTTP $oidc_status."
exit 1
fi
oidc=$(printf '%s' "$oidc_body" | uv run --frozen python -c 'import json, sys; print(json.load(sys.stdin)["value"])') || {
echo "::error::GitHub OIDC response carried no value field."
exit 1
}

token_response=$(curl -sS -w '\n%{http_code}' \
https://opencode.ai/console/auth/oauth/token \
-d grant_type=urn:ietf:params:oauth:grant-type:token-exchange \
-d subject_token_type=urn:ietf:params:oauth:token-type:jwt \
-d client_id="$CLIENT_ID" \
-d subject_token="$oidc")
token_status=$(printf '%s' "$token_response" | tail -n1)
token_body=$(printf '%s' "$token_response" | sed '$d')
if [ "$token_status" -lt 200 ] || [ "$token_status" -ge 300 ]; then
echo "::error::OpenCode token exchange failed with HTTP $token_status: ${token_body:0:400}"
exit 1
fi
token=$(printf '%s' "$token_body" | uv run --frozen python -c 'import json, sys; print(json.load(sys.stdin)["access_token"])') || {
echo "::error::OpenCode token exchange returned no access_token."
exit 1
}
if [ -z "$token" ]; then
echo "::error::OpenCode token exchange returned an empty access_token."
exit 1
fi
echo "::add-mask::$token"
echo "OPENCODE_API_KEY=$token" >> "$GITHUB_ENV"

- name: Run Guardian Review
id: guardian
env:
# OPENCODE_API_KEY is deliberately absent: the OIDC step above
# writes it to GITHUB_ENV, and a step-level value would override it.
ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
GEMINI_API_KEY: ${{ secrets.GEMINI_API_KEY }}
MISTRAL_API_KEY: ${{ secrets.MISTRAL_API_KEY }}
GUARDIAN_PROVIDER: ${{ vars.GUARDIAN_PROVIDER }}
GUARDIAN_MODEL: ${{ vars.GUARDIAN_MODEL }}
# Thinking depth for an anthropic finder or skeptic; unset = the
# provider's default ("low"). #246 J measured the finder at "medium".
GUARDIAN_ANTHROPIC_EFFORT: ${{ vars.GUARDIAN_ANTHROPIC_EFFORT }}
# Reasoning depth for an opencode-go finder; unset = the provider's
# default ("low"). A bad value fails at the gateway, loudly.
GUARDIAN_OPENCODE_EFFORT: ${{ vars.GUARDIAN_OPENCODE_EFFORT }}
# Anthropic stays selectable but is no longer the default finder, so
# GUARDIAN_ANTHROPIC_EFFORT is deliberately not passed here; an
# explicit anthropic pick runs at the provider's own default (#775).
GH_TOKEN: ${{ steps.app-token.outputs.token || github.token }}
GITHUB_REPOSITORY: ${{ github.repository }}
GUARDIAN_FEATURES: ${{ vars.GUARDIAN_FEATURES }}
Expand Down
3 changes: 3 additions & 0 deletions .github/workflows/guardian.yml
Original file line number Diff line number Diff line change
Expand Up @@ -25,6 +25,9 @@ jobs:
contents: read
pull-requests: write
issues: write
# The reusable workflow signs in to OpenCode with GitHub OIDC (#775); a
# called workflow cannot ask for more than its caller grants.
id-token: write

save-metrics:
needs: review
Expand Down
2 changes: 1 addition & 1 deletion PRIVACY.md
Original file line number Diff line number Diff line change
Expand Up @@ -24,7 +24,7 @@ We do not collect, transmit, store or have access to: your source code, the grap

The `codegraph-brain` package also contains **Guardian**, a code reviewer that sends diffs and graph context to a large language model. **Guardian is not part of the Claude Code plugin**: the plugin neither ships nor invokes it, and it does nothing unless you configure it and run it deliberately, normally in CI.

If you choose to use Guardian, you select the model provider yourself — Google Gemini, Mistral, Anthropic (Claude), OpenRouter, or a local Ollama instance — and supply your own credentials. In that case the code being reviewed is sent to whichever provider you chose, under **that provider's** privacy policy and terms, not this one. Choosing Ollama keeps it local. We never see that traffic and never receive a copy.
If you choose to use Guardian, you select the model provider yourself — Google Gemini, Mistral, Anthropic (Claude), OpenRouter, OpenCode Go (DeepSeek), or a local Ollama instance — and supply your own credentials. In that case the code being reviewed is sent to whichever provider you chose, under **that provider's** privacy policy and terms, not this one. Choosing Ollama keeps it local. We never see that traffic and never receive a copy.

Credentials for those providers are read from your environment and used only to call the provider they belong to. They are not logged, stored or transmitted anywhere else.

Expand Down
11 changes: 10 additions & 1 deletion README.md
Original file line number Diff line number Diff line change
Expand Up @@ -136,7 +136,7 @@ The details — and a pipeline graph CGIS regenerates from its own source on eve
**Guardian** is CGIS's built-in LLM reviewer — it reviews pull requests using the *graph* as context, not just the diff text. It runs in CI and posts inline comments anchored to the exact line.

* **Two-stage, recall-first:** a **finder** surfaces every plausible defect (optimised for recall), then a separate **skeptic** pass filters false positives — closer to how human reviewers work, and far more reliable than a single precision-gated prompt.
* **Local *or* cloud, no lock-in:** point it at **Ollama** (`qwen2.5-coder`, `llama3.1`, `granite-code`, …) for free local inference, or at **Mistral / Gemini / Claude** in the cloud. You can even mix them — a strong cloud finder with a free local *cross-model* skeptic.
* **Local *or* cloud, no lock-in:** point it at **Ollama** (`qwen2.5-coder`, `llama3.1`, `granite-code`, …) for free local inference, or at **Mistral / Gemini / Claude / OpenCode Go (DeepSeek)** in the cloud. You can even mix them — a strong cloud finder with a free local *cross-model* skeptic.
* **Graph-aware context:** the reviewer sees impact graphs, architectural drift, and project ontology — so it catches structural and convention defects a flat-diff reviewer can't.
* **Deterministic anchoring:** every inline comment is positioned by a verbatim quote from the diff, not the model's (often wrong) line guess.
* **Dogfooded & measured:** Guardian reviews CGIS's *own* pull requests, and a benchmark harness scores it against curated ground truth — so prompt changes are validated, not guessed.
Expand All @@ -149,13 +149,22 @@ cgis ingest ./src --output graph.db
GUARDIAN_PROVIDER=ollama GUARDIAN_MODEL=qwen2.5-coder:14b \
uv run python scripts/guardian_review.py --pr 123 --db graph.db --inline

# Or OpenCode Go / DeepSeek: deepseek-v4.1-flash unless GUARDIAN_MODEL names another.
# GUARDIAN_OPENCODE_EFFORT is low unless set (the catalog lists low|high|max; other values
# pass through to the gateway). GUARDIAN_OPENCODE_BASE_URL pins a different gateway.
# No ANTHROPIC_API_KEY is needed for this provider.
GUARDIAN_PROVIDER=opencode-go GUARDIAN_MODEL=deepseek-v4.1-flash OPENCODE_API_KEY=... \
uv run python scripts/guardian_review.py --pr 123 --db graph.db --inline

# Or a Claude skeptic over a Mistral finder: Claude Haiku 5.5 unless GUARDIAN_SKEPTIC_MODEL names
# another, at GUARDIAN_ANTHROPIC_EFFORT=low unless set (low|medium|high|xhigh|max). Claude models
# reject a sampling temperature, so GUARDIAN_TEMPERATURE must be unset.
GUARDIAN_SKEPTIC=anthropic ANTHROPIC_API_KEY=... MISTRAL_API_KEY=... \
uv run python scripts/guardian_review.py --pr 123 --db graph.db --inline
```

In GitHub Actions, opencode-go needs no static key: the reusable workflow exchanges a short-lived GitHub OIDC token for inference access immediately before the review. Enable OIDC for GitHub Actions in the Opencode console, set the calling repository's `OPENCODE_CLIENT_ID` variable, and grant the review job `id-token: write`. `OPENCODE_API_KEY` is then minted at run time and never stored as a secret. Sign-in happens when `GUARDIAN_PROVIDER` is `opencode-go`, `opencode`, or unset (unset means the minted key makes opencode the auto-detected provider); an explicit other provider skips it.

No GPU on hand? **[Benchmark it on a notebook GPU →](https://github.com/zaebee/codegraph-brain/blob/main/docs/GUARDIAN_LOCAL_BENCH.md)** — free end to end, since the fixtures score without an LLM judge. Or **[point Guardian at a remote Ollama →](https://github.com/zaebee/codegraph-brain/blob/main/docs/GUARDIAN_REMOTE_OLLAMA.md)** — over an frp stcp tunnel, no public port, and a guard that refuses a review of a silently truncated prompt.

---
Expand Down
2 changes: 1 addition & 1 deletion src/cgis/guardian/providers/base.py
Original file line number Diff line number Diff line change
Expand Up @@ -87,7 +87,7 @@ def __init_subclass__(cls, **kwargs: object) -> None:
_msg = (
f"{cls.__name__} must declare `name: ClassVar[str]` — one of the "
'GUARDIAN_PROVIDER values: "gemini", "mistral", "ollama", "openrouter", '
'"anthropic". Add '
'"opencode", "anthropic". Add '
f'`name: ClassVar[str] = "..."` as the first line of '
f"{cls.__name__}'s class body."
)
Expand Down
88 changes: 88 additions & 0 deletions src/cgis/guardian/providers/openai_compatible.py
Original file line number Diff line number Diff line change
@@ -0,0 +1,88 @@
"""Shared request plumbing for OpenAI-compatible providers (#246, #775).

OpenRouter and OpenCode Go speak the same chat-completions shape, so the
prompt, budget, temperature and schema handling live here once. A change to
that contract moves both providers; only the endpoint, headers, error handling
and the reasoning knob remain provider-specific.
"""

from abc import ABC, abstractmethod
from typing import Any, ClassVar

from pydantic import BaseModel

from cgis.guardian.providers.base import BaseProvider


class OpenAICompatibleProvider(BaseProvider, ABC):
"""A model reached through an OpenAI-shaped chat-completions API."""

#: Concrete subclasses declare their own `name`; this intermediate stays
#: abstract (`_post` and `_reasoning_payload` are still unimplemented), so
#: `BaseProvider.__init_subclass__` does not demand one here.
name: ClassVar[str]

def __init__(
self,
api_key: str,
model_name: str,
timeout: float,
max_tokens: int,
temperature: float | None,
) -> None:
"""Store the settings every OpenAI-compatible provider sends.

`temperature` is None by default and then not sent at all, leaving the
model's own value in place — the rule every sampled provider here
follows, so an unset knob never becomes a value this project invented
and could not describe afterwards.
"""
super().__init__()
self._api_key = api_key
self._model_name = model_name
self._timeout = timeout
self._max_tokens = max_tokens
self._temperature = temperature

@abstractmethod
async def _post(self, payload: dict[str, Any]) -> str:
"""Send one completion; return the message content or raise."""

@abstractmethod
def _payload(self, system_prompt: str, user_prompt: str) -> dict[str, Any]:
"""The full request body; each provider adds its own reasoning knob."""

def _shared_payload(self, system_prompt: str, user_prompt: str) -> dict[str, Any]:
"""The fields both providers send: model, prompt, budget, temperature."""
payload: dict[str, Any] = {
"model": self._model_name,
"messages": [
{"role": "system", "content": system_prompt},
{"role": "user", "content": user_prompt},
],
"max_tokens": self._max_tokens,
}
# `is not None`, not truthiness: 0.0 is the one temperature that states
# something, and a falsy test would drop exactly that value.
if self._temperature is not None:
payload["temperature"] = self._temperature
return payload

async def generate_content(self, system_prompt: str, user_prompt: str) -> str:
"""Free-text generation."""
return await self._retry(lambda: self._post(self._payload(system_prompt, user_prompt)))

async def generate_structured(
self, system_prompt: str, user_prompt: str, schema: type[BaseModel]
) -> str:
"""Generation asked to conform to `schema`; returns raw JSON text."""
payload = self._payload(system_prompt, user_prompt)
payload["response_format"] = {
"type": "json_schema",
"json_schema": {
"name": schema.__name__,
"strict": True,
"schema": schema.model_json_schema(),
},
}
return await self._retry(lambda: self._post(payload))
Loading
Loading