open-code-review-toolkit 0.8.0__tar.gz → 0.8.2__tar.gz

{open_code_review_toolkit-0.8.0 → open_code_review_toolkit-0.8.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: open-code-review-toolkit
-Version: 0.8.0
+Version: 0.8.2
 Summary: Unofficial GitLab CI integration layer for Open Code Review
 Project-URL: Homepage, https://github.com/xeonvs/open-code-review-toolkit
 Project-URL: Repository, https://github.com/xeonvs/open-code-review-toolkit
@@ -249,6 +249,7 @@ ocr-ci --help
 The exact recommended OCR release and its verified asset checksums live in the [versioned compatibility manifest](compatibility/ocr-support.json). CI should pin that release and checksum before execution.
 The [versioned compatibility policy](docs/compatibility.md) records tested assets and evidence and describes the conservative Dependabot-like qualification workflow for later upstream releases.
 Review output defaults to English. `OCR_REVIEW_LANGUAGE` accepts another explicit language name when a project needs localized review output; for example, `OCR_REVIEW_LANGUAGE=Russian`.
+The current OCR 1.10.0 integration defaults `OCR_REVIEW_EFFORT` to `medium` for two review rounds. `low` and `high` are explicit one- and three-round alternatives; see the [configuration reference](docs/configuration.md#review-effort) for cost, budget, and precedence boundaries.
 
 Stable distributions are published to [PyPI](https://pypi.org/project/open-code-review-toolkit/) and mirrored as checksum-listed, provenance-attested assets in the corresponding [GitHub Release](https://github.com/xeonvs/open-code-review-toolkit/releases). Development snapshots are published only to TestPyPI.
 

{open_code_review_toolkit-0.8.0 → open_code_review_toolkit-0.8.2}/README.md

@@ -22,6 +22,7 @@ ocr-ci --help
 The exact recommended OCR release and its verified asset checksums live in the [versioned compatibility manifest](compatibility/ocr-support.json). CI should pin that release and checksum before execution.
 The [versioned compatibility policy](docs/compatibility.md) records tested assets and evidence and describes the conservative Dependabot-like qualification workflow for later upstream releases.
 Review output defaults to English. `OCR_REVIEW_LANGUAGE` accepts another explicit language name when a project needs localized review output; for example, `OCR_REVIEW_LANGUAGE=Russian`.
+The current OCR 1.10.0 integration defaults `OCR_REVIEW_EFFORT` to `medium` for two review rounds. `low` and `high` are explicit one- and three-round alternatives; see the [configuration reference](docs/configuration.md#review-effort) for cost, budget, and precedence boundaries.
 
 Stable distributions are published to [PyPI](https://pypi.org/project/open-code-review-toolkit/) and mirrored as checksum-listed, provenance-attested assets in the corresponding [GitHub Release](https://github.com/xeonvs/open-code-review-toolkit/releases). Development snapshots are published only to TestPyPI.
 

{open_code_review_toolkit-0.8.0 → open_code_review_toolkit-0.8.2}/src/ocr_toolkit/_version.py

@@ -18,7 +18,7 @@ version_tuple: tuple[int | str, ...]
 commit_id: str | None
 __commit_id__: str | None
 
-__version__ = version = '0.8.0'
-__version_tuple__ = version_tuple = (0, 8, 0)
+__version__ = version = '0.8.2'
+__version_tuple__ = version_tuple = (0, 8, 2)
 
 __commit_id__ = commit_id = None

open_code_review_toolkit-0.8.2/src/ocr_toolkit/configure.py

@@ -0,0 +1,96 @@
+"""Configure OCR runtime settings from CI environment variables."""
+
+from __future__ import annotations
+
+import os
+import sys
+from typing import Any
+
+from ocr_toolkit.common.language import resolve_review_language
+from ocr_toolkit.common.redaction import redact_sensitive
+from ocr_toolkit.config_writer import OCRConfigError, update_ocr_config
+from ocr_toolkit.provider_config import (
+    ProviderConfigError,
+    provider_config_from_environment,
+)
+
+
+class OCRRuntimeConfigError(Exception):
+    """OCR runtime config from CI env is invalid."""
+
+
+REVIEW_EFFORTS = frozenset({"low", "medium", "high"})
+
+
+def _env(name: str, default: str = "") -> str:
+    return os.environ.get(name, default).strip()
+
+
+def _bool_env(name: str) -> bool:
+    return _env(name).lower() == "true"
+
+
+def review_effort() -> str:
+    """Return the closed OCR review-effort preset, defaulting to medium."""
+
+    value = (_env("OCR_REVIEW_EFFORT") or "medium").lower()
+    if value not in REVIEW_EFFORTS:
+        raise OCRRuntimeConfigError("OCR_REVIEW_EFFORT must be one of: low, medium, high")
+    return value
+
+
+def build_config_updates() -> dict[str, Any]:
+    """Build OCR config updates from already-normalized CI environment."""
+
+    review_language = resolve_review_language()
+    try:
+        provider = provider_config_from_environment()
+        llm_url = provider.require_inference_url()
+        llm_token = provider.require_token()
+        llm_model = provider.require_model()
+    except ProviderConfigError as exc:
+        raise OCRRuntimeConfigError(str(exc)) from exc
+    request_controls = provider.request_controls
+
+    updates: dict[str, Any] = {
+        "effort": review_effort(),
+        "language": review_language,
+        "llm.url": llm_url,
+        "llm.auth_token": llm_token,
+        "llm.model": llm_model,
+        "llm.protocol": request_controls.protocol,
+        "llm.use_anthropic": request_controls.protocol == "anthropic",
+        "llm.auth_header": request_controls.auth_header,
+        "telemetry.enabled": _bool_env("OCR_TELEMETRY_ENABLED"),
+        "telemetry.content_logging": _bool_env("OCR_TELEMETRY_CONTENT_LOGGING"),
+    }
+
+    if request_controls.extra_headers:
+        updates["llm.extra_headers"] = request_controls.extra_headers
+
+    if request_controls.extra_body is not None:
+        updates["llm.extra_body"] = request_controls.extra_body
+
+    if _bool_env("OCR_TELEMETRY_ENABLED"):
+        updates["telemetry.exporter"] = _env("OCR_TELEMETRY_EXPORTER")
+        otlp_endpoint = _env("OCR_TELEMETRY_OTLP_ENDPOINT")
+        if otlp_endpoint:
+            updates["telemetry.otlp_endpoint"] = otlp_endpoint
+
+    return updates
+
+
+def main() -> int:
+    """Write OCR config and return a process exit code."""
+
+    try:
+        update_ocr_config(build_config_updates())
+    except (OCRRuntimeConfigError, OCRConfigError) as exc:
+        print(f"Failed to configure OCR runtime: {redact_sensitive(str(exc))}", file=sys.stderr)
+        return 1
+    print("OCR runtime config written")
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

{open_code_review_toolkit-0.8.0 → open_code_review_toolkit-0.8.2}/src/ocr_toolkit/posting/result.py

@@ -17,13 +17,14 @@ from ocr_toolkit.ocr_result import (
     load_ocr_result,
 )
 from ocr_toolkit.posting.comments import clean_text, compact_escaped_text
+from ocr_toolkit.provider_failure import ProviderFailureReason
 from ocr_toolkit.result_contract import ReviewOutcome
 
 __all__ = [
     "OcrResultMalformed",
     "OcrResultMissing",
     "OcrResultTooLarge",
-    "llm_billing_failure_warnings",
+    "llm_billing_failure_reason",
     "load_ocr_result",
     "normalize_coverage_diagnostics",
     "ocr_warning_text",
@@ -199,12 +200,13 @@ def ocr_warning_text(warning: Any, *, _seen: set[int] | None = None) -> str:
     return clean_text(warning)
 
 
-def llm_billing_failure_warnings(warnings: Sequence[Any]) -> list[str]:
-    """Return OCR warnings that indicate LLM provider billing/quota failure."""
+def llm_billing_failure_reason(
+    warnings: Sequence[Any],
+) -> ProviderFailureReason | None:
+    """Map a legacy OCR billing warning to the shared safe provider reason."""
 
-    matches: list[str] = []
     for warning in warnings:
         text = ocr_warning_text(warning)
         if text and LLM_BILLING_FAILURE_RE.search(text):
-            matches.append(text)
-    return matches
+            return ProviderFailureReason.RATE_OR_SPENDING_LIMIT
+    return None

{open_code_review_toolkit-0.8.0 → open_code_review_toolkit-0.8.2}/src/ocr_toolkit/posting/workflow.py

@@ -15,7 +15,6 @@ from typing import Any
 
 from ocr_toolkit.common.git import isolated_git_environment, read_only_git_prefix
 from ocr_toolkit.common.markdown import markdown_code_block, neutralize_quick_actions
-from ocr_toolkit.common.redaction import redact_sensitive
 from ocr_toolkit.evidence.artifacts import repository_artifacts
 from ocr_toolkit.ocr_result import (
     TOOLKIT_RESULT_KEY,
@@ -37,7 +36,6 @@ from ocr_toolkit.posting.comments import (
     clean_text,
     code_text,
     comment_line,
-    compact_escaped_text,
 )
 from ocr_toolkit.posting.formatting import (
     format_fallback_comment_chunks,
@@ -71,12 +69,11 @@ from ocr_toolkit.posting.markers import (
 )
 from ocr_toolkit.posting.payloads import build_marked_note_body
 from ocr_toolkit.posting.result import (
-    llm_billing_failure_warnings,
+    llm_billing_failure_reason,
     normalize_coverage_diagnostics,
 )
 from ocr_toolkit.posting.snapshot import (
     BotCommentRefs,
-    cleanup_drafts_created_by_this_run,
     collect_previous_bot_comment_refs,
     delete_previous_bot_comments_if_collected,
     delete_previous_setup_notes,
@@ -101,6 +98,10 @@ from ocr_toolkit.pre_execution import (
     PreExecutionStatusError,
     read_pre_execution_status,
 )
+from ocr_toolkit.provider_failure import (
+    ProviderFailureReason,
+    provider_failure_reason,
+)
 from ocr_toolkit.result_contract import OcrResultContractError, ReviewOutcome, parse_result_outcome
 
 # Kept as a module-level compatibility seam for tests and external monkey-patching.
@@ -662,19 +663,13 @@ def post_results(config: GitLabConfig, result: dict[str, Any]) -> int:
             token_usage_summary=token_usage_summary,
         )
 
-    billing_warnings = llm_billing_failure_warnings(warnings)
-    if billing_warnings:
+    billing_reason = llm_billing_failure_reason(warnings)
+    if billing_reason is not None:
         print(
             "OCR reported an LLM provider billing/quota failure; refusing to publish normal review notes.",
             file=sys.stderr,
         )
-        return post_llm_provider_failure(
-            config,
-            billing_warnings,
-            tool_calls_summary=tool_calls_summary,
-            mcp_usage_summary=mcp_usage_summary,
-            token_usage_summary=token_usage_summary,
-        )
+        return post_llm_provider_failure(config, billing_reason)
 
     previous_bot_comment_refs = collect_previous_bot_comment_refs(config)
     transaction = PostingTransaction()
@@ -1101,38 +1096,75 @@ def post_manifest_failure(
 
 def post_llm_provider_failure(
     config: GitLabConfig,
-    warnings: Sequence[str],
-    tool_calls_summary: str = "",
-    mcp_usage_summary: str = "",
-    token_usage_summary: str = "",
+    reason: ProviderFailureReason,
 ) -> int:
-    """Post a visible OCR provider failure and preserve previous review notes."""
+    """Render one closed provider failure without publishing private diagnostics."""
 
     transaction = PostingTransaction()
-    warning_items: list[str] = []
-    for warning in warnings[:10]:
-        safe_warning = compact_escaped_text(
-            neutralize_quick_actions(redact_sensitive(warning)),
-            1200,
-        )
-        if safe_warning:
-            warning_items.append(f"- {safe_warning}")
+    summary, remediation = {
+        ProviderFailureReason.AUTHENTICATION: (
+            "The LLM provider did not accept the configured credential.",
+            "Check the protected credential and its authentication header, then rerun the pipeline.",
+        ),
+        ProviderFailureReason.AUTHORIZATION: (
+            "The LLM provider authenticated the request but did not authorize it.",
+            "Check the credential permissions and provider access policy, then rerun the pipeline.",
+        ),
+        ProviderFailureReason.RATE_OR_SPENDING_LIMIT: (
+            "The LLM provider rejected the request under a rate or spending limit.",
+            "The cause may be ordinary throttling, an account or API-key spending limit, or cost reservation from the requested output cap. Retry later and check account limits. If short probes pass but a full review fails before generation, try an explicit `OCR_LLM_MAX_COMPLETION_TOKENS`, for example `4096`.",
+        ),
+        ProviderFailureReason.OVERLOADED: (
+            "The LLM provider reported that it was overloaded.",
+            "Retry later or use another already-qualified provider deployment.",
+        ),
+        ProviderFailureReason.TIMEOUT: (
+            "The LLM provider request timed out.",
+            "Check provider latency and the network path, then rerun the pipeline.",
+        ),
+        ProviderFailureReason.NETWORK: (
+            "The LLM provider could not be reached reliably.",
+            "Check DNS, TLS, proxy, and runner connectivity, then rerun the pipeline.",
+        ),
+        ProviderFailureReason.ENDPOINT_OR_MODEL_NOT_FOUND: (
+            "The LLM provider reported that the configured endpoint or model was not found.",
+            "Verify both the provider API root and model identifier; the safe diagnostic cannot distinguish which one was absent.",
+        ),
+        ProviderFailureReason.REQUEST_REJECTED: (
+            "The LLM provider rejected the review request.",
+            "Check the explicit protocol, endpoint shape, model contract, and request controls, then rerun the pipeline.",
+        ),
+        ProviderFailureReason.PROVIDER_UNAVAILABLE: (
+            "The LLM provider was unavailable while processing the review.",
+            "Retry later and check the provider service status.",
+        ),
+        ProviderFailureReason.INVALID_RESPONSE: (
+            "The LLM provider returned a response that could not be consumed safely.",
+            "Check protocol compatibility and provider response health, then rerun the pipeline.",
+        ),
+        ProviderFailureReason.CANCELLED: (
+            "The LLM provider request was cancelled before the review completed.",
+            "Check pipeline cancellation and deadline signals, then rerun when the job can complete.",
+        ),
+        ProviderFailureReason.MIXED: (
+            "The review encountered more than one provider failure category.",
+            "Inspect the private CI diagnostics, correct every provider-side failure, then rerun the pipeline.",
+        ),
+        ProviderFailureReason.UNKNOWN: (
+            "The LLM provider request failed for an unclassified safe reason.",
+            "Inspect the private CI diagnostics and provider health, then rerun the pipeline.",
+        ),
+    }[reason]
 
     body_parts = [
-        "OCR could not complete the review because the LLM provider reported a billing, quota, or balance failure.",
+        summary,
         "",
+        f"- Safe classification: `{reason.value}`.",
         "- Normal review comments were not published.",
         "- Previous OCR review comments were preserved.",
-        "- Refill or rotate the LLM token, then rerun the pipeline.",
+        "- Automatic approval was not attempted.",
+        f"- {remediation}",
     ]
-    if warning_items:
-        body_parts.extend(["", "**Provider warnings:**", *warning_items])
-    if tool_calls_summary:
-        body_parts.extend(["", tool_calls_summary])
-    if mcp_usage_summary:
-        body_parts.append(mcp_usage_summary)
-    if token_usage_summary:
-        body_parts.append(token_usage_summary)
 
     response = post_review_note_bounded(
         config,
@@ -1142,18 +1174,23 @@ def post_llm_provider_failure(
     )
     if response is None:
         print("Failed to create OCR provider-failure note.", file=sys.stderr)
-        cleanup_drafts_created_by_this_run(config, transaction)
-        print_posting_failure_banner()
-        return 1
+        return posting_failure_exit(config, None, transaction)
 
     if not finalize_posting(config, transaction):
         return publish_failure_exit(config, transaction)
 
-    print(
-        "Open Code Review did not complete because the LLM provider reported a billing/quota failure.",
-        file=sys.stderr,
-    )
-    return 1
+    print(f"Open Code Review provider failure: {reason.value}.", file=sys.stderr)
+    return 1 if strict_posting() else 0
+
+
+def _result_provider_failure_reason(result_path: Path) -> ProviderFailureReason | None:
+    """Hostile-read one bounded private result and return only its closed reason."""
+
+    try:
+        result = load_ocr_result(result_path)
+    except (OcrResultMalformed, OcrResultMissing, OcrResultTooLarge):
+        return None
+    return provider_failure_reason(result)
 
 
 def post_parse_error(config: GitLabConfig, stderr_path: Path) -> int:
@@ -1194,11 +1231,18 @@ def post_parse_error(config: GitLabConfig, stderr_path: Path) -> int:
     return 1 if strict_posting() else 0
 
 
-def post_ocr_failure(config: GitLabConfig, stderr_path: Path, exit_code: int) -> int:
+def post_ocr_failure(
+    config: GitLabConfig,
+    stderr_path: Path,
+    exit_code: int,
+    result_path: Path | None = None,
+) -> int:
     """Post a safe failure note when OCR exits with a non-zero status.
 
     A non-zero OCR exit code means the JSON output may be partial or misleading,
-    so this script intentionally does not publish normal review comments.
+    so this script intentionally does not publish normal review comments. A
+    bounded retry-report v1 may contribute only a closed provider-failure
+    reason; its raw diagnostics and stderr remain private.
     Previous OCR bot notes are intentionally NOT cleaned up here: the last
     valid review must remain visible until a successful run replaces it.
 
@@ -1222,6 +1266,10 @@ def post_ocr_failure(config: GitLabConfig, stderr_path: Path, exit_code: int) ->
     if status is not None:
         return post_pre_execution_status(config, status)
 
+    reason = _result_provider_failure_reason(result_path) if result_path is not None else None
+    if reason is not None:
+        return post_llm_provider_failure(config, reason)
+
     transaction = PostingTransaction()
     details_enabled = os.environ.get("OCR_POST_ERROR_DETAILS") == "1"
     details = read_stderr_excerpt(stderr_path) if details_enabled else ""
@@ -1342,7 +1390,7 @@ def main(argv: list[str] | None = None) -> int:
 
     exit_code = ocr_exit_code()
     if exit_code != 0:
-        return post_ocr_failure(config, stderr_path, exit_code)
+        return post_ocr_failure(config, stderr_path, exit_code, result_path)
 
     try:
         result = load_ocr_result(result_path)

{open_code_review_toolkit-0.8.0 → open_code_review_toolkit-0.8.2}/src/ocr_toolkit/preflight.py

@@ -15,16 +15,20 @@ import urllib.request
 from typing import Any
 
 from ocr_toolkit.common.redaction import redact_sensitive
+from ocr_toolkit.provider_config import (
+    HEADER_NAME_RE,
+    ProviderConfigError,
+    provider_config_from_environment,
+)
 
 HTTP_TIMEOUT_SECONDS = 30
 MAX_RESPONSE_BODY_BYTES = 2_000_000
 RESPONSE_READ_CHUNK_BYTES = 64 * 1024
-HEADER_NAME_RE = re.compile(r"^[!#$%&'*+.^_`|~0-9A-Za-z-]+$")
 DEFAULT_REQUEST_HEADERS = {
     "Accept": "application/json",
     "User-Agent": "open-code-review-ci-preflight/1.0",
 }
-EXPECTED_OCR_VERSION = "1.9.10"
+EXPECTED_OCR_VERSION = "1.10.0"
 
 
 class PreflightError(Exception):
@@ -209,63 +213,10 @@ def validate_ocr_binary() -> None:
 
 
 def _models_url() -> str:
-    explicit_url = _env("OCR_LLM_MODELS_URL")
-    if explicit_url:
-        return explicit_url
-
-    base = ""
-    llm_url = _env("OCR_LLM_URL")
-    if not base:
-        normalized_llm_url = llm_url.rstrip("/")
-        for endpoint in ("/chat/completions", "/responses"):
-            if normalized_llm_url.endswith(endpoint):
-                base = normalized_llm_url[: -len(endpoint)]
-                break
-        else:
-            if normalized_llm_url.endswith("/v1"):
-                base = normalized_llm_url
-
-    if not base:
-        raise PreflightError(
-            "Cannot derive LLM /models URL; set OCR_LLM_MODELS_URL or "
-            "set OCR_LLM_VALIDATE_MODEL=false"
-        )
-    return f"{base.rstrip('/')}/models"
-
-
-def _parse_extra_headers(value: str) -> dict[str, str]:
-    """Parse optional OCR LLM extra headers JSON for preflight metadata calls."""
-
-    if not value.strip():
-        return {}
     try:
-        payload = json.loads(value)
-    except json.JSONDecodeError as exc:
-        raise PreflightError("OCR_LLM_EXTRA_HEADERS must be a JSON object") from exc
-    if not isinstance(payload, dict):
-        raise PreflightError("OCR_LLM_EXTRA_HEADERS must be a JSON object")
-
-    headers: dict[str, str] = {}
-    for key, header_value in payload.items():
-        if not isinstance(key, str) or not HEADER_NAME_RE.fullmatch(key.strip()):
-            raise PreflightError("OCR_LLM_EXTRA_HEADERS contains an invalid header name")
-        if not isinstance(header_value, str):
-            raise PreflightError("OCR_LLM_EXTRA_HEADERS contains a non-string header value")
-        if "\r" in header_value or "\n" in header_value:
-            raise PreflightError("OCR_LLM_EXTRA_HEADERS contains an invalid header value")
-        headers[key.strip()] = header_value
-    return headers
-
-
-def _llm_headers(token: str) -> dict[str, str]:
-    """Build the same auth/header set used by OCR's llm.* configuration."""
-
-    auth_header = _env("OCR_LLM_AUTH_HEADER", "Authorization") or "Authorization"
-    if not HEADER_NAME_RE.fullmatch(auth_header):
-        raise PreflightError("OCR_LLM_AUTH_HEADER is not a valid HTTP header name")
-    headers = _parse_extra_headers(_env("OCR_LLM_EXTRA_HEADERS"))
-    headers[auth_header] = f"Bearer {token}"
-    return headers
+        return provider_config_from_environment().require_models_url()
+    except ProviderConfigError as exc:
+        raise PreflightError(str(exc)) from exc
 
 
 def _context_length(model: dict[str, Any]) -> int:
@@ -320,9 +271,11 @@ def _validate_allowed_model(model_id: str) -> bool:
 def validate_llm_model() -> None:
     """Verify the selected model exists in OpenAI-compatible metadata."""
 
-    model_id = _env("OCR_LLM_MODEL")
-    if not model_id:
-        raise PreflightError("OCR_LLM_MODEL is required")
+    try:
+        provider = provider_config_from_environment()
+        model_id = provider.require_model()
+    except ProviderConfigError as exc:
+        raise PreflightError(str(exc)) from exc
     allowlist_matched = _validate_allowed_model(model_id)
 
     validate_mode = _env("OCR_LLM_VALIDATE_MODEL", "false").lower()
@@ -332,15 +285,15 @@ def validate_llm_model() -> None:
     if validate_mode not in {"true", "1", "yes", "on", "auto"}:
         raise PreflightError("OCR_LLM_VALIDATE_MODEL must be true, false, or auto")
 
-    token = _env("OCR_LLM_TOKEN")
-    if not token:
-        raise PreflightError("OCR_LLM_TOKEN is required")
-    headers = _llm_headers(token)
+    try:
+        headers = provider.request_headers()
+    except ProviderConfigError as exc:
+        raise PreflightError(str(exc)) from exc
 
     print("Validating OCR model against LLM gateway metadata")
     try:
-        models_url = _models_url()
-    except PreflightError as exc:
+        models_url = provider.require_models_url()
+    except ProviderConfigError as exc:
         if validate_mode == "auto" and allowlist_matched:
             print(
                 "OCR LLM /models URL unavailable; continuing because "
@@ -348,7 +301,7 @@ def validate_llm_model() -> None:
                 file=sys.stderr,
             )
             return
-        raise
+        raise PreflightError(str(exc)) from exc
     try:
         payload = _request_json(models_url, headers)
     except PreflightError as exc: