xai-review 0.3.0__tar.gz

xai_review-0.3.0/PKG-INFO

@@ -0,0 +1,11 @@
+Metadata-Version: 2.4
+Name: xai-review
+Version: 0.3.0
+Requires-Dist: typer
+Requires-Dist: httpx
+Requires-Dist: pyyaml
+Requires-Dist: pytest
+Requires-Dist: loguru
+Requires-Dist: aiofiles
+Requires-Dist: pydantic
+Requires-Dist: pydantic-settings

xai_review-0.3.0/README.md

@@ -0,0 +1,260 @@
+# AI Review
+
+AI-powered code review tool.
+
+_Made with ❤️ by [@NikitaFilonov](https://t.me/sound_right)_
+
+---
+
+## 📑 Table of Contents
+
+- 🚀 [Quick Start](#-quick-start)
+- ⚙️ [Configuration](#-configuration)
+- 🛠 [Advanced usage](#-advanced-usage)
+- 📂 [Examples](#-examples)
+
+---
+
+## 🚀 Quick Start
+
+Install via **pip**:
+
+```bash
+pip install ai-review
+```
+
+Or run directly via Docker:
+
+```bash
+docker run --rm -v $(pwd):/app nikitafilonov/ai-review:latest run-summary
+```
+
+👉 Before running, create a basic configuration file [.ai-review.yaml](./docs/configs/.ai-review.yaml) in the root of
+your project:
+
+```yaml
+llm:
+  provider: OPENAI
+
+  meta:
+    model: gpt-4o-mini
+    max_tokens: 1200
+    temperature: 0.3
+
+  http_client:
+    timeout: 120
+    api_url: https://api.openai.com/v1
+    api_token: ${OPENAI_API_KEY}
+
+vcs:
+  provider: GITLAB
+
+  pipeline:
+    project_id: 1
+    merge_request_id: 100
+
+  http_client:
+    timeout: 120
+    api_url: https://gitlab.com
+    api_token: ${GITLAB_API_TOKEN}
+```
+
+👉 This will:
+
+- Run AI Review against your codebase.
+- Generate inline and/or summary comments (depending on the selected mode).
+- Use your chosen LLM provider (e.g., OpenAI GPT-4o-mini by default in this example).
+
+> **Note:** Running `ai-review run` executes the full review (inline + summary).
+> To run only one mode, use the dedicated subcommands:
+> - ai-review run-inline
+> - ai-review run-summary
+> - ai-review run-context
+
+---
+
+AI Review can be configured via `.ai-review.yaml`, `.ai-review.json`, or `.env`. See [./docs/configs](./docs/configs)
+for complete, ready-to-use examples.
+
+Key things you can customize:
+
+- **LLM provider** — OpenAI, Gemini, or Claude
+- **Model settings** — model name, temperature, max tokens
+- **VCS integration** — GitLab (currently supported) with project/MR context
+- **Review policy** — which files to include/exclude, review modes
+- **Prompts** — inline/context/summary prompt templates
+
+👉 Minimal configuration is enough to get started. Use the full reference configs if you want fine-grained control (
+timeouts, artifacts, logging, etc.).
+
+---
+
+## 🛠 Advanced usage
+
+Below is the **full configuration reference** with all available options. Most projects only need a
+minimal `.ai-review.yaml`, but you can use these templates as a starting point for advanced setups:
+
+- [docs/configs/.ai-review.yaml](./docs/configs/.ai-review.yaml) — YAML configuration (with comments)
+- [docs/configs/.ai-review.json](./docs/configs/.ai-review.json) — JSON configuration
+- [docs/configs/.env.example](./docs/configs/.env.example) — environment variables example
+
+👉 The YAML file includes comments for every option, making it the best place to explore the complete set of settings.
+
+Below is an **example GitLab CI job** showing how to run AI Review with these variables:
+
+```yaml
+ai-review:
+  tags: [ build ]
+  when: manual
+  stage: checks
+  image: nikitafilonov/ai-review:latest
+  rules:
+    - if: '$CI_MERGE_REQUEST_IID'
+  script:
+    - ai-review run
+  variables:
+    # ===============================
+    # LLM provider & model
+    # ===============================
+    # Which LLM to use.
+    # Options: OPENAI | GEMINI | CLAUDE
+    LLM__PROVIDER: "OPENAI"
+
+    # --- Model metadata ---
+    # For OpenAI: gpt-4o, gpt-4o-mini, gpt-3.5-turbo
+    # For Gemini: gemini-2.0-pro, gemini-2.0-flash
+    # For Claude: claude-3-opus, claude-3-sonnet, claude-3-haiku
+    LLM__META__MODEL: "gpt-4o-mini"
+
+    # Max tokens for completion.
+    LLM__META__MAX_TOKENS: "1200"
+
+    # Creativity of responses (0 = deterministic, >0 = more creative).
+    LLM__META__TEMPERATURE: "0.3"
+
+    # --- HTTP client configuration ---
+    # API endpoint + token (must be set as CI/CD variables).
+    LLM__HTTP_CLIENT__API_URL: "https://api.openai.com/v1"
+    LLM__HTTP_CLIENT__API_TOKEN: "$OPENAI_API_KEY"
+
+    # Example for Gemini:
+    # LLM__HTTP_CLIENT__API_URL: "https://generativelanguage.googleapis.com"
+    # LLM__HTTP_CLIENT__API_TOKEN: "$GEMINI_API_KEY"
+
+    # Example for Claude:
+    # LLM__HTTP_CLIENT__API_URL: "https://api.anthropic.com"
+    # LLM__HTTP_CLIENT__API_TOKEN: "$CLAUDE_API_KEY"
+    # LLM__HTTP_CLIENT__API_VERSION: "2023-06-01"
+
+    # ===============================
+    # VCS (GitLab integration)
+    # ===============================
+    VCS__PROVIDER: "GITLAB"
+
+    # Context of the current pipeline (auto-populated by GitLab).
+    VCS__PIPELINE__PROJECT_ID: "$CI_PROJECT_ID"
+    VCS__PIPELINE__MERGE_REQUEST_ID: "$CI_MERGE_REQUEST_IID"
+
+    # GitLab API access.
+    VCS__HTTP_CLIENT__API_URL: "$CI_SERVER_URL"
+    VCS__HTTP_CLIENT__API_TOKEN: "$CI_JOB_TOKEN"
+
+    # ===============================
+    # Prompts (optional overrides)
+    # ===============================
+    # Inline prompts (joined in order, local review instructions).
+    # PROMPT__INLINE_PROMPT_FILES__0: "./prompts/inline.md"
+
+    # Inline system prompts (format/contract rules).
+    # PROMPT__SYSTEM_INLINE_PROMPT_FILES__0: "./prompts/system_inline.md"
+    # PROMPT__INCLUDE_INLINE_SYSTEM_PROMPTS: "true"
+
+    # Context prompts (joined in order, broader analysis instructions).
+    # PROMPT__CONTEXT_PROMPT_FILES__0: "./prompts/context.md"
+
+    # Context system prompts (format/contract rules).
+    # PROMPT__SYSTEM_CONTEXT_PROMPT_FILES__0: "./prompts/system_context.md"
+    # PROMPT__INCLUDE_CONTEXT_SYSTEM_PROMPTS: "true"
+
+    # Summary prompts (joined in order, local review instructions).
+    # PROMPT__SUMMARY_PROMPT_FILES__0: "./prompts/summary.md"
+
+    # Summary system prompts (format/contract rules).
+    # PROMPT__SYSTEM_SUMMARY_PROMPT_FILES__0: "./prompts/system_summary.md"
+    # PROMPT__INCLUDE_SUMMARY_SYSTEM_PROMPTS: "true"
+
+    # ===============================
+    # Custom context variables
+    # ===============================
+    # You can inject custom variables into prompts via PROMPT__CONTEXT__*.
+    # These will be available as placeholders {var} in all templates.
+    #
+    # Example usage in prompt templates:
+    #   Project: {company_name}
+    #   Env: {environment}
+    #   Pipeline: {ci_pipeline_url}
+    #
+    # Values override built-in variables if names collide.
+    # To avoid clashes, prefer namespaced keys (ci_pipeline_url, org_notify_handle, env_name).
+    #
+    # PROMPT__CONTEXT__ENVIRONMENT: "staging"
+    # PROMPT__CONTEXT__COMPANY_NAME: "ACME Corp"
+    # PROMPT__CONTEXT__CI_PIPELINE_URL: "https://gitlab.com/pipelines/123"
+
+    # ===============================
+    # Review options
+    # ===============================
+    # Available modes:
+    #   FULL_FILE_DIFF
+    #   FULL_FILE_CURRENT
+    #   FULL_FILE_PREVIOUS
+    #   ONLY_ADDED
+    #   ONLY_REMOVED
+    #   ADDED_AND_REMOVED
+    #   ONLY_ADDED_WITH_CONTEXT
+    #   ONLY_REMOVED_WITH_CONTEXT
+    #   ADDED_AND_REMOVED_WITH_CONTEXT
+    REVIEW__MODE: "FULL_FILE_DIFF"
+
+    # Tags used to mark AI-generated comments in MR.
+    REVIEW__INLINE_TAG: "#ai-review-inline"
+    REVIEW__SUMMARY_TAG: "#ai-review-summary"
+
+    # Context lines (only for *_WITH_CONTEXT modes).
+    REVIEW__CONTEXT_LINES: "10"
+
+    # Markers for changes in output.
+    REVIEW__REVIEW_ADDED_MARKER: " # added"
+    REVIEW__REVIEW_REMOVED_MARKER: " # removed"
+
+    # Optional filters:
+    # REVIEW__ALLOW_CHANGES: "src/*,lib/*"
+    # REVIEW__IGNORE_CHANGES: "docs/*,README.md"
+
+    # Optional limits for number of AI comments:
+    # REVIEW__MAX_INLINE_COMMENTS: "20"   # Max inline comments per file (default: unlimited)
+    # REVIEW__MAX_CONTEXT_COMMENTS: "50"  # Max context comments per MR (default: unlimited)
+
+    # ===============================
+    # Logger (optional)
+    # ===============================
+    LOGGER__LEVEL: "INFO"
+    LOGGER__FORMAT: "{time:YYYY-MM-DD HH:mm:ss} | {level} | {extra[logger_name]} | {message}"
+
+    # ===============================
+    # Artifacts (optional)
+    # ===============================
+    ARTIFACTS__LLM_DIR: "./artifacts/llm"
+    ARTIFACTS__LLM_ENABLED: "false"
+
+  allow_failure: true
+
+```
+
+---
+
+## 📂 Examples
+
+- [./docs/ci/gitlab.yaml](./docs/ci/gitlab.yaml) — ready-to-use CI snippet
+- [./docs/configs](./docs/configs) — sample `.yaml`, `.json`, `.env` configs
+- [./docs/prompts](./docs/prompts) — prompt templates for Python/Go (light & strict modes)

xai_review-0.3.0/ai_review/cli/commands/run_context_review.py

@@ -0,0 +1,7 @@
+from ai_review.services.review.service import ReviewService
+
+
+async def run_context_review_command():
+    review_service = ReviewService()
+    await review_service.run_context_review()
+    review_service.report_total_cost()

xai_review-0.3.0/ai_review/cli/commands/run_inline_review.py

@@ -0,0 +1,7 @@
+from ai_review.services.review.service import ReviewService
+
+
+async def run_inline_review_command():
+    review_service = ReviewService()
+    await review_service.run_inline_review()
+    review_service.report_total_cost()

xai_review-0.3.0/ai_review/cli/commands/run_review.py

@@ -0,0 +1,8 @@
+from ai_review.services.review.service import ReviewService
+
+
+async def run_review_command():
+    review_service = ReviewService()
+    await review_service.run_inline_review()
+    await review_service.run_summary_review()
+    review_service.report_total_cost()

xai_review-0.3.0/ai_review/cli/commands/run_summary_review.py

@@ -0,0 +1,7 @@
+from ai_review.services.review.service import ReviewService
+
+
+async def run_summary_review_command():
+    review_service = ReviewService()
+    await review_service.run_summary_review()
+    review_service.report_total_cost()

xai_review-0.3.0/ai_review/cli/main.py

@@ -0,0 +1,54 @@
+import asyncio
+
+import typer
+
+from ai_review.cli.commands.run_context_review import run_context_review_command
+from ai_review.cli.commands.run_inline_review import run_inline_review_command
+from ai_review.cli.commands.run_review import run_review_command
+from ai_review.cli.commands.run_summary_review import run_summary_review_command
+from ai_review.config import settings
+
+app = typer.Typer(help="AI Review CLI")
+
+
+@app.command("run")
+def run():
+    """Run the full AI review pipeline"""
+    typer.secho("Starting full AI review...", fg=typer.colors.CYAN, bold=True)
+    asyncio.run(run_review_command())
+    typer.secho("AI review completed successfully!", fg=typer.colors.GREEN, bold=True)
+
+
+@app.command("run-inline")
+def run_inline():
+    """Run only the inline review"""
+    typer.secho("Starting inline AI review...", fg=typer.colors.CYAN)
+    asyncio.run(run_inline_review_command())
+    typer.secho("AI review completed successfully!", fg=typer.colors.GREEN, bold=True)
+
+
+@app.command("run-context")
+def run_context():
+    """Run only the context review"""
+    typer.secho("Starting context AI review...", fg=typer.colors.CYAN)
+    asyncio.run(run_context_review_command())
+    typer.secho("AI review completed successfully!", fg=typer.colors.GREEN, bold=True)
+
+
+@app.command("run-summary")
+def run_summary():
+    """Run only the summary review"""
+    typer.secho("Starting summary AI review...", fg=typer.colors.CYAN)
+    asyncio.run(run_summary_review_command())
+    typer.secho("AI review completed successfully!", fg=typer.colors.GREEN, bold=True)
+
+
+@app.command("show-config")
+def show_config():
+    """Show the current resolved configuration"""
+    typer.secho("Loaded AI Review configuration:", fg=typer.colors.CYAN, bold=True)
+    typer.echo(settings.model_dump_json(indent=2, exclude_none=True))
+
+
+if __name__ == "__main__":
+    app()

xai_review-0.3.0/ai_review/clients/claude/client.py

@@ -0,0 +1,44 @@
+from httpx import AsyncClient, Response, AsyncHTTPTransport
+
+from ai_review.clients.claude.schema import ClaudeChatRequestSchema, ClaudeChatResponseSchema
+from ai_review.config import settings
+from ai_review.libs.http.client import HTTPClient
+from ai_review.libs.http.event_hooks.logger import LoggerEventHook
+from ai_review.libs.http.handlers import HTTPClientError, handle_http_error
+from ai_review.libs.http.transports.retry import RetryTransport
+from ai_review.libs.logger import get_logger
+
+
+class ClaudeHTTPClientError(HTTPClientError):
+    pass
+
+
+class ClaudeHTTPClient(HTTPClient):
+    @handle_http_error(client="ClaudeHTTPClient", exception=ClaudeHTTPClientError)
+    async def chat_api(self, request: ClaudeChatRequestSchema) -> Response:
+        return await self.post("/v1/messages", json=request.model_dump())
+
+    async def chat(self, request: ClaudeChatRequestSchema) -> ClaudeChatResponseSchema:
+        response = await self.chat_api(request)
+        return ClaudeChatResponseSchema.model_validate_json(response.text)
+
+
+def get_claude_http_client() -> ClaudeHTTPClient:
+    logger = get_logger("CLAUDE_HTTP_CLIENT")
+    logger_event_hook = LoggerEventHook(logger=logger)
+    retry_transport = RetryTransport(transport=AsyncHTTPTransport())
+
+    client = AsyncClient(
+        timeout=settings.llm.http_client.timeout,
+        headers={
+            "x-api-key": settings.llm.http_client.api_key,
+            "anthropic-version": settings.llm.http_client.api_version,
+        },
+        base_url=settings.llm.http_client.base_url,
+        transport=retry_transport,
+        event_hooks={
+            "request": [logger_event_hook.request],
+            "response": [logger_event_hook.response],
+        },
+    )
+    return ClaudeHTTPClient(client=client)

xai_review-0.3.0/ai_review/clients/claude/schema.py

@@ -0,0 +1,44 @@
+from typing import Literal
+
+from pydantic import BaseModel
+
+
+class ClaudeMessageSchema(BaseModel):
+    role: Literal["user", "assistant", "system"]
+    content: str
+
+
+class ClaudeChatRequestSchema(BaseModel):
+    model: str
+    system: str | None = None
+    messages: list[ClaudeMessageSchema]
+    max_tokens: int
+    temperature: float
+
+
+class ClaudeContentSchema(BaseModel):
+    type: Literal["text"]
+    text: str
+
+
+class ClaudeUsageSchema(BaseModel):
+    input_tokens: int
+    output_tokens: int
+
+    @property
+    def total_tokens(self) -> int:
+        return self.input_tokens + self.output_tokens
+
+
+class ClaudeChatResponseSchema(BaseModel):
+    id: str
+    role: str
+    usage: ClaudeUsageSchema
+    content: list[ClaudeContentSchema]
+
+    @property
+    def first_text(self) -> str:
+        if not self.content:
+            return ""
+
+        return self.content[0].text.strip()

xai_review-0.3.0/ai_review/clients/gemini/client.py

@@ -0,0 +1,45 @@
+from httpx import Response, AsyncHTTPTransport, AsyncClient
+
+from ai_review.clients.gemini.schema import GeminiChatRequestSchema, GeminiChatResponseSchema
+from ai_review.config import settings
+from ai_review.libs.http.client import HTTPClient
+from ai_review.libs.http.event_hooks.logger import LoggerEventHook
+from ai_review.libs.http.handlers import HTTPClientError, handle_http_error
+from ai_review.libs.http.transports.retry import RetryTransport
+from ai_review.libs.logger import get_logger
+
+
+class GeminiHTTPClientError(HTTPClientError):
+    pass
+
+
+class GeminiHTTPClient(HTTPClient):
+    @handle_http_error(client="GeminiHTTPClient", exception=GeminiHTTPClientError)
+    async def chat_api(self, request: GeminiChatRequestSchema) -> Response:
+        meta = settings.llm.meta
+        return await self.post(
+            f"/v1beta/models/{meta.model}:generateContent", json=request.model_dump()
+        )
+
+    async def chat(self, request: GeminiChatRequestSchema) -> GeminiChatResponseSchema:
+        response = await self.chat_api(request)
+        return GeminiChatResponseSchema.model_validate_json(response.text)
+
+
+def get_gemini_http_client() -> GeminiHTTPClient:
+    logger = get_logger("GEMINI_HTTP_CLIENT")
+    logger_event_hook = LoggerEventHook(logger=logger)
+    retry_transport = RetryTransport(transport=AsyncHTTPTransport())
+
+    client = AsyncClient(
+        timeout=settings.llm.http_client.timeout,
+        headers={"x-goog-api-key": settings.llm.http_client.api_key},
+        base_url=settings.llm.http_client.base_url,
+        transport=retry_transport,
+        event_hooks={
+            "request": [logger_event_hook.request],
+            "response": [logger_event_hook.response],
+        },
+    )
+
+    return GeminiHTTPClient(client=client)

xai_review-0.3.0/ai_review/clients/gemini/schema.py

@@ -0,0 +1,78 @@
+from pydantic import BaseModel, Field, ConfigDict
+
+
+class GeminiPartSchema(BaseModel):
+    text: str
+
+
+class GeminiUsageSchema(BaseModel):
+    model_config = ConfigDict(populate_by_name=True)
+
+    prompt_token_count: int = Field(alias="promptTokenCount")
+    total_tokens_count: int | None = Field(default=None, alias="totalTokenCount")
+    candidates_token_count: int | None = Field(default=None, alias="candidatesTokenCount")
+    output_thoughts_token_count: int | None = Field(default=None, alias="outputThoughtsTokenCount")
+
+    @property
+    def total_tokens(self) -> int:
+        if self.total_tokens_count is not None:
+            return self.total_tokens_count
+
+        return (
+                (self.prompt_token_count or 0)
+                + (self.candidates_token_count or 0)
+                + (self.output_thoughts_token_count or 0)
+        )
+
+    @property
+    def prompt_tokens(self) -> int:
+        return self.prompt_token_count
+
+    @property
+    def completion_tokens(self) -> int | None:
+        return self.candidates_token_count or self.output_thoughts_token_count
+
+
+class GeminiContentSchema(BaseModel):
+    role: str = "user"
+    parts: list[GeminiPartSchema] | None = None
+
+
+class GeminiCandidateSchema(BaseModel):
+    content: GeminiContentSchema
+
+
+class GeminiGenerationConfigSchema(BaseModel):
+    model_config = ConfigDict(populate_by_name=True)
+
+    temperature: float
+    max_output_tokens: int = Field(alias="maxOutputTokens")
+
+
+class GeminiChatRequestSchema(BaseModel):
+    model_config = ConfigDict(populate_by_name=True)
+
+    contents: list[GeminiContentSchema]
+    generation_config: GeminiGenerationConfigSchema | None = Field(
+        alias="generationConfig",
+        default=None
+    )
+    system_instruction: GeminiContentSchema | None = Field(
+        alias="systemInstruction",
+        default=None
+    )
+
+
+class GeminiChatResponseSchema(BaseModel):
+    model_config = ConfigDict(populate_by_name=True)
+
+    usage: GeminiUsageSchema = Field(alias="usageMetadata")
+    candidates: list[GeminiCandidateSchema]
+
+    @property
+    def first_text(self) -> str:
+        if not self.candidates:
+            return ""
+
+        parts = self.candidates[0].content.parts or []
+        return (parts[0].text if parts else "").strip()

xai_review-0.3.0/ai_review/clients/gitlab/client.py

@@ -0,0 +1,31 @@
+from httpx import AsyncClient, AsyncHTTPTransport
+
+from ai_review.clients.gitlab.mr.client import GitLabMergeRequestsHTTPClient
+from ai_review.config import settings
+from ai_review.libs.http.event_hooks.logger import LoggerEventHook
+from ai_review.libs.http.transports.retry import RetryTransport
+from ai_review.libs.logger import get_logger
+
+
+class GitLabHTTPClient:
+    def __init__(self, client: AsyncClient):
+        self.mr = GitLabMergeRequestsHTTPClient(client)
+
+
+def get_gitlab_http_client() -> GitLabHTTPClient:
+    logger = get_logger("GITLAB_MERGE_REQUESTS_HTTP_CLIENT")
+    logger_event_hook = LoggerEventHook(logger=logger)
+    retry_transport = RetryTransport(transport=AsyncHTTPTransport())
+
+    client = AsyncClient(
+        timeout=settings.llm.http_client.timeout,
+        headers={"Authorization": f"Bearer {settings.vcs.http_client.bearer_token}"},
+        base_url=settings.vcs.http_client.base_url,
+        transport=retry_transport,
+        event_hooks={
+            'request': [logger_event_hook.request],
+            'response': [logger_event_hook.response]
+        }
+    )
+
+    return GitLabHTTPClient(client=client)