action.yml

name: 'Serge'
description: 'Review pull requests with any OpenAI-compatible LLM and post inline comments on the diff.'
author: 'serge'
branding:
  icon: 'message-square'
  color: 'purple'

inputs:
  llm_api_key:
    description: 'Bearer token for the chat-completion endpoint.'
    required: true
  llm_api_base:
    description: 'Base URL of an OpenAI-compatible service. Accepts either https://host or https://host/v1.'
    required: false
    default: 'https://api.openai.com/v1'
  llm_model:
    description: 'Model identifier to pass in the chat-completion request. If omitted, the action auto-discovers the first model from {llm_api_base}/models.'
    required: false
  llm_bill_to:
    description: 'Optional org slug for routing inference billing (sent as the X-HF-Bill-To header). Required when using a Hugging Face token whose Inference Providers permission is scoped to an organization rather than the user.'
    required: false
  llm_max_tokens:
    description: 'Maximum completion tokens requested from the LLM. Bump for reasoning models (e.g. Kimi-K2) that spend tokens on reasoning before emitting JSON.'
    required: false
    default: '4096'
  llm_stream:
    description: 'Set to "true" to consume the chat-completion response as a streaming SSE feed. Off by default; useful for endpoints/proxies that drop long-running non-streaming connections.'
    required: false
    default: 'false'
  mention_trigger:
    description: 'Phrase that triggers reviews. Must be the first word of the comment.'
    required: false
    default: '@askserge'
  review_event:
    description: 'One of COMMENT, REQUEST_CHANGES, APPROVE (fallback if the LLM omits one).'
    required: false
    default: 'COMMENT'
  max_diff_chars:
    description: 'Maximum diff size (characters) sent to the LLM.'
    required: false
    default: '200000'
  review_rules_path:
    description: 'Path to repo-specific review rules, read from the default branch.'
    required: false
    default: '.ai/review-rules.md'
  helper_tools_path:
    description: 'Path to a repo-specific helper-tools JSON file, read from the default branch. Helpers can expose tightly scoped CLI commands to the reviewer when a local PR checkout is available.'
    required: false
    default: '.ai/review-tools.json'
  default_review_rules:
    description: 'Fallback rules used when the repo has no review-rules file.'
    required: false
    default: 'Apply general Python correctness and security standards.'
  context_script_path:
    description: 'Path to an executable script in the target repo that, given the PR title/body and modified-file list as JSON on stdin, prints additional context to inject into the reviewer prompt. Skipped silently if the file is missing or not executable.'
    required: false
    default: '.ai/context-script'
  context_script_timeout:
    description: 'Seconds to wait for the context script before giving up.'
    required: false
    default: '30'
  repo_checkout_path:
    description: 'Path to a local checkout of the PR head ref. When set, the reviewer exposes read-only browse tools (read_file/list_dir/grep) rooted here so the LLM can fetch context beyond the diff. Defaults to GITHUB_WORKSPACE; set to an empty string to disable tools entirely. The caller workflow is responsible for checking out the PR head ref (e.g. with `actions/checkout@v4` and `ref: refs/pull/<number>/head`) before invoking this action.'
    required: false
    default: ${{ github.workspace }}
  tool_max_iterations:
    description: 'Maximum number of tool-calling rounds before forcing the model to produce a final review. Each iteration is a separate LLM call.'
    required: false
    default: '8'
  headroom_compress:
    description: 'Set to "true" to compress context with headroom-ai before each LLM call (cuts tokens on tool outputs and older turns). Requires the headroom-ai package; install reviewbot with the [headroom] extra. No-op if the package is missing.'
    required: false
    default: 'false'
  headroom_target_ratio:
    description: 'Optional headroom keep-ratio for text compression (e.g. 0.5 keeps ~50%). Leave empty to let headroom decide.'
    required: false
  headroom_compress_user_messages:
    description: 'Set to "true" to also compress user messages (the annotated diff). Off by default so cited line numbers stay intact.'
    required: false
    default: 'false'
  headroom_compress_system_messages:
    description: 'Set to "false" to leave system messages uncompressed. On by default.'
    required: false
    default: 'true'
  headroom_protect_recent:
    description: 'Number of most-recent messages never compressed.'
    required: false
    default: '4'
  headroom_min_tokens:
    description: 'Skip compressing messages shorter than this many tokens.'
    required: false
    default: '250'
  headroom_kompress_model:
    description: 'Kompress model id for ML compression, or "disabled" to skip it. Leave empty for the headroom default.'
    required: false
  headroom_model_limit:
    description: 'Model context window (tokens) used for sizing.'
    required: false
    default: '200000'
  staging:
    description: 'Set to "true" to mark this as a staging deployment. Published reviews then carry a note saying they were posted from staging.'
    required: false
    default: 'false'
  github_token:
    description: 'Token with pull-requests:write. Defaults to the job token.'
    required: false
    default: ${{ github.token }}
  python_version:
    description: 'Python version to set up for running the reviewer.'
    required: false
    default: '3.12'

runs:
  using: 'composite'
  steps:
    - name: Set up Python
      uses: actions/setup-python@v6.3.0
      with:
        python-version: ${{ inputs.python_version }}

    - name: Install reviewbot
      shell: bash
      env:
        HEADROOM_COMPRESS: ${{ inputs.headroom_compress }}
      run: |
        # Pull in the (heavy) headroom-ai extra only when compression is on.
        if [ "${HEADROOM_COMPRESS,,}" = "true" ] || [ "$HEADROOM_COMPRESS" = "1" ]; then
          pip install --disable-pip-version-check "${{ github.action_path }}[headroom]"
        else
          pip install --disable-pip-version-check "${{ github.action_path }}"
        fi

    - name: Run AI reviewer
      shell: bash
      env:
        GITHUB_TOKEN: ${{ inputs.github_token }}
        LLM_API_BASE: ${{ inputs.llm_api_base }}
        LLM_API_KEY: ${{ inputs.llm_api_key }}
        LLM_MODEL: ${{ inputs.llm_model }}
        LLM_BILL_TO: ${{ inputs.llm_bill_to }}
        LLM_MAX_TOKENS: ${{ inputs.llm_max_tokens }}
        LLM_STREAM: ${{ inputs.llm_stream }}
        MENTION_TRIGGER: ${{ inputs.mention_trigger }}
        REVIEW_EVENT: ${{ inputs.review_event }}
        MAX_DIFF_CHARS: ${{ inputs.max_diff_chars }}
        REVIEW_RULES_PATH: ${{ inputs.review_rules_path }}
        HELPER_TOOLS_PATH: ${{ inputs.helper_tools_path }}
        DEFAULT_REVIEW_RULES: ${{ inputs.default_review_rules }}
        CONTEXT_SCRIPT_PATH: ${{ inputs.context_script_path }}
        CONTEXT_SCRIPT_TIMEOUT: ${{ inputs.context_script_timeout }}
        REPO_CHECKOUT_PATH: ${{ inputs.repo_checkout_path }}
        TOOL_MAX_ITERATIONS: ${{ inputs.tool_max_iterations }}
        STAGING: ${{ inputs.staging }}
        HEADROOM_COMPRESS: ${{ inputs.headroom_compress }}
        HEADROOM_TARGET_RATIO: ${{ inputs.headroom_target_ratio }}
        HEADROOM_COMPRESS_USER_MESSAGES: ${{ inputs.headroom_compress_user_messages }}
        HEADROOM_COMPRESS_SYSTEM_MESSAGES: ${{ inputs.headroom_compress_system_messages }}
        HEADROOM_PROTECT_RECENT: ${{ inputs.headroom_protect_recent }}
        HEADROOM_MIN_TOKENS: ${{ inputs.headroom_min_tokens }}
        HEADROOM_KOMPRESS_MODEL: ${{ inputs.headroom_kompress_model }}
        HEADROOM_MODEL_LIMIT: ${{ inputs.headroom_model_limit }}
      run: reviewbot-action