AI Review Documentation

The AI Review documentation is organized into several specialized directories to help you integrate and configure the tool:

• CI/CD Integration: Templates for GitHub Actions and GitLab CI are located in ./ci.
• CLI Reference: Command usage and examples are found in ./cli.
• Hooks & Lifecycle: Information on available hooks and lifecycle events is in ./hooks.
• Configuration Examples: Full examples using .yaml, .json, and .env formats are available in ./configs.
• Prompt Templates: Templates for Python/Go (supporting light and strict modes) are in ./prompts.
• Troubleshooting: Guidance for common environment and Git-related issues is in ./troubleshooting.md.

The python/summary/light.md prompt is designed for a lightweight Python code review. It instructs the AI to act as a Python developer providing a concise (3–5 sentences) plain-text summary of merge request changes.

Focus Areas:

• Correctness: Logic errors, exceptions, and edge cases.
• Readability: Naming, structure, and clarity.
• Idiomatic Python: Proper use of f-strings, context managers, and the standard library.

Exclusions:

• Ignore minor formatting or import order (handled by automated tools).
• Ignore logging style or test coverage unless they impact correctness.

Output Requirements:

• Provide plain text only (no Markdown or JSON).
• If no issues are detected, the output must be exactly: No issues found.

The agent communicates via a TOOL_CALL/FINAL envelope protocol. When the agent decides to conclude the task, it must return a FINAL response.

Requirements for the FINAL response:

• The content field must contain the complete task output as a plain string.
• If the task output is required to be in a structured format (such as a JSON array), the agent must serialize that structure into the content string.

AI Review automatically detects configuration at runtime from several supported formats. You can combine these formats, and values will be merged according to the load priority rules.

Supported formats:

• YAML (Recommended): Use .ai-review.yaml.
• JSON: Use .ai-review.json.
• ENV: Use .env.

AI Review is designed to be a direct conduit between your environment and your LLM provider.

• No Intermediaries: The tool does not store, log, or transmit source code to any external service other than the LLM provider explicitly configured in your .ai-review.yaml.
• Direct Transmission: Data is sent directly from your CI/CD environment to the LLM API endpoint (e.g., OpenAI, Gemini, Claude, OpenRouter).
• Offline Capability: If using Ollama, requests are sent to your local or self-hosted runtime (default http://localhost:11434), allowing for completely offline reviews within your own infrastructure.

Responsibility Note: Users are responsible for managing API tokens and ensuring that configuration (such as using personal vs. enterprise keys) does not lead to accidental credential or code exposure.

AI Review provides a lightweight, asynchronous, and non-blocking hooks system. Hooks allow you to subscribe to internal lifecycle events to perform tasks like logging, collecting metrics/cost reports, or triggering external notifications.

Key Characteristics:

• Asynchronous: All hook functions must be defined using async def.
• Non-blocking: If a hook raises an exception, it is caught and logged (e.g., Error in ON_INLINE_COMMENT_COMPLETE hook: ValueError('...')), but the main review process continues uninterrupted.
• Lifecycle-driven: Hooks are triggered at specific stages of the review pipeline (Chat, Inline Review, Context Review, etc.).

@hook.on_chat_start
async def my_hook(prompt: str, prompt_system: str):
    # Your logic here
    pass

When multiple configuration sources are present, AI Review resolves values using the following priority order (highest priority first):

1. YAML: .ai-review.yaml or the path specified by AI_REVIEW_CONFIG_FILE_YAML.
2. JSON: .ai-review.json or the path specified by AI_REVIEW_CONFIG_FILE_JSON.
3. ENV: .env or the path specified by AI_REVIEW_CONFIG_FILE_ENV.
4. Environment variables: Individual variables like LLM__PROVIDER=OPENAI.
5. Initialization arguments: Arguments passed directly if using AI Review as a library.

The go/summary/light prompt is designed for a Go developer role to provide a concise, high-level summary of code quality in a merge request. It focuses on major risks, readability, and idiomatic Go improvements while ignoring minor stylistic details or micro-optimizations.

Key Review Focus Areas:

• Major Risks: Nil dereferences, index out of range, goroutine leaks, and channel misuse.
• Maintainability: Naming, structure, and complexity.
• Idiomatic Go: Proper use of defer, short variable declarations, and standard library usage.

Output Requirements:

• Must be plain text only.
• Length: 3–5 sentences.
• Tone: Constructive and factual.
• Special Case: If no issues are found, the output must be exactly: No issues found.

You can inject your own context variables into prompt templates by defining them under the prompt.context key in your configuration. These variables become available as placeholders using the <<key_name>> syntax.

Custom keys are merged with built-in variables; if a custom key shares a name with a built-in variable (e.g., labels), the custom value takes precedence.

Methods for configuration:

• YAML: Use prompt.context.
• JSON: Use prompt.context.
• ENV/ .env: Use the prefix AI_REVIEW__PROMPT__CONTEXT__ followed by the key name (e.g., AI_REVIEW__PROMPT__CONTEXT__COMPANY_NAME=ACME).

prompt:
  context:
    environment: "staging"
    company_name: "ACME Corp"