Prism Reviewer – Multi-agent AI code reviewer built with LangGraph and LiteLLM

🌈 Prism Reviewer Developed by Vyoman Labs Prism Reviewer is an agentic, AI-driven multi-agent code review system developed by Vyoman Labs and orchestrated via LangGraph and LiteLLM. It acts as an autonomous gatekeeper for pull requests by performing targeted static analysis, dependency scanning, AST-based symbol inspection, and parallel LLM-guided code evaluation. 🚀 Quick Start (Minimal Workflow Snippet) & Live Demo Add this minimal workflow snippet to .github/workflows/prism-reviewer.yml: - uses: actions/checkout@v4 with: fetch-depth: 0 - uses: vyoman-labs/prism-reviewer@v1 with: llm-api-key: ${{ secrets.LLM_API_KEY }} 🔍 Live Demo PR: See real Prism Reviewer comments in action on savourly-recipes PR #35. 📖 Table of Contents 🔍 System Description 📐 Architecture and Flow 🧠 Key Intricacies and Design Decisions 🔧 Installation 📦 Packaging and Distribution 💻 CLI Usage 🔩 Configuration Guide 🔌 Running Reviews Locally via GitHub PR ID 🔗 GitHub App and Integration Setup 📝 Notes Limitations and Roadmap Why Prism Reviewer? 🌈 🔍1. System Description Prism Reviewer splits a single code changes delta (git diff) into specialized analytical spectrums using an Agent Council. Instead of sending a monolithic prompt to a single LLM, it routes structural, security, and tactical code context in parallel to three distinct agent roles. Combined with the local AST syntax trees, dependency warnings, and usage reference searches, it compiles a rigorous, context-aware code review report categorized by severity. Key Features Deterministic Evaluation: Supports zero temperature, fixed seed routing, and structured JSON output to eliminate probabilistic drift across runs. AST CodeLens Map: Leverages Tree-Sitter grammars (supporting Python, Java, TypeScript, JavaScript, C, C++, Go, and Rust) to extract class, function, and method ranges before scanning. Dependency Warnings: Scans requirements files (requirements.txt, package.json, pyproject.toml) for dependency configuration anomalies. Map-Reduce Parallelism: Orchestrated through a LangGraph StateGraph, enabling concurrent LLM agent queries. Dual-Safeguard Verification: Fact-checks and filters findings against changed lines and previous review states to ensure zero hallucinations and zero duplication. 📐2. Architecture and Flow The review execution lifecycle is modeled as a LangGraph workspace map-reduce graph, organized as follows: flowchart TD START([START]) --> FetchComments["Fetch Prior PR Comments & Discussion (Filtered: MAJOR & CRITICAL)"] FetchComments --> BuildContext[Build Context Node] BuildContext --> |Partition Diff into Regions & Fan Out| Router{_fan_out_router} Router -->|Region 1..N| Warden[👮 Warden Node Security & Compliance] Router -->|Region 1..N| Architect[📐 Architect Node Design & Performance] Router -->|Region 1..N| Inspector[🔍 Inspector Node Clean Code & Logic] Warden --> Join{Join} Architect --> Join Inspector --> Join Join --> Verifier[🛡️ Verifier Node Hallucination Guard & Deduplication] Verifier --> Aggregator[📊 Aggregator Node Severity Sorting & Report Render] Aggregator --> END([END]) Loading Flow Execution Steps: fetch_pull_request_comments (implemented in github.py): Queries previous inline review comment threads and general PR discussions via GitHub API, filtering for MAJOR and CRITICAL severity feedback (ignoring low-priority ADVISORY comments) to pass as conversation history. build_context_node (implemented in nodes.py): Gathers directory profiles, runs AST scans on modified files, scans dependencies, parses usage references, and slices large diffs into logical regions. _fan_out_router (implemented in graph.py): Routes each region to all three agent nodes concurrently. Agent Council: 👮 Warden Node: Evaluates vulnerabilities, exposed credentials, loose dependencies, data leaks, and verifies if past security feedback was addressed. 📐 Architect Node: Audits architectural design, design pattern compliance, performance traps, and checks if past structural feedback was resolved. 🔍 Inspector Node: Targets clean code compliance, readability, minor logic bugs, and validates fixes for past logic findings. verifier_node (implemented in verifier.py): Performs double-guard filtering (hallucination checks & duplicate suppression). aggregator_node (implemented in aggregator.py): Sorts findings by severity (CRITICAL → MAJOR → ADVISORY) and renders the report. 🧠3. Key Intricacies and Design Decisions 3.1 Large PR Region Partitioning Large code deltas exceed single-turn LLM context limits or result in degraded review quality. Prism Reviewer slices large diffs into localized, file-level regions based on line count constraints (configured by max_region_lines). The router fans out separate state objects per region to the agent council. LangGraph automatically gathers and aggregates the findings once all region runs complete. 3.2 The Dual-Safeguard Verifier Hallucination Guard: Generative agents may comment on files or line numbers that do not exist or were not modified. The verifier compiles a precise index of modified (filename, line_number) pairs from the raw git diff. Any finding pointing to a line outside this set is dropped. Idempotent Deduplication: Running reviews continuously on every synchronization push can overwhelm developers with duplicate warnings on unchanged code blocks. The system computes a content-hash signature for each finding based on the file path, line number, agent type, and the surrounding diff content. These signatures are stored in signatures.json. Subsequent runs skip findings with matching signatures. 3.3 Buffered Atomic Logging Standard terminal log writers interleave messages when multiple threads execute in parallel. To preserve clean CLI logs, Prism Reviewer implements NodeLogger (defined in nodes.py). This class buffers per-agent log entries in memory and flushes them as a single atomic log block on node completion. 3.4 Smart Hybrid Incremental Review Strategy Running full PR reviews on every push update can consume significant LLM API tokens. Prism Reviewer implements a Smart Hybrid Review Strategy to cut LLM token costs by up to 90% on PR updates while preserving PR-wide architectural context and avoiding review quality degradation: flowchart TD A["PR Event Triggered"] --> B{"Event Type / Diff Mode"} B -- "Initial PR / Full Sync / Manual" --> C["Full PR Review Mode"] B -- "Push Update / Incremental" --> D["Smart Incremental Review Mode"] C --> E["Diff: base_branch..HEAD"] C --> F["Full PR Context + Full LLM Scan"] D --> G["Diff: previous_commit..HEAD"] D --> H["Pass Full PR Touched Files + CodeLens AST Map + Prior PR Comments (MAJOR/CRITICAL)"] D --> I["LLM Evaluates New Diff with PR Context & Prior Discussion"] E --> J["Verifier Node & Signatures"] G --> J J --> K["Update PR Summary & Inline Comments"] Loading Full PR Review Mode (full): Used on initial PR creation (pull_request.opened), milestone reviews, or manual trigger (/prism full-review). Compares base_branch..HEAD. Smart Incremental Mode (incremental / auto): Used on push updates (pull_request.synchronize). Evaluates only the newly modified commits (previous_sha..HEAD), while maintaining full PR awareness by injecting the complete PR touched file list, CodeLens AST dependency map, and prior MAJOR/CRITICAL PR comment threads into the prompt context. 🔧4. Installation To install Prism Reviewer in editable mode for local development: pip install -e . To install with development dependencies (e.g., for running the test suite): pip install -e ".[dev]" 📦5. Packaging and Distribution Prism Reviewer is packaged using standard Python packaging utilities and setuptools (configured in pyproject.toml). 5.1 Build Prerequisites Before building your distribution packages, ensure you have the python build modules build and twine installed: pip install --upgrade build twine 5.2 Building the Distribution Packages From the root directory of the repository (where pyproject.toml is located), execute the build wrapper to compile the source distribution tarball (.tar.gz) and Python wheel binary (.whl): python -m build This command compiles and outputs the distribution assets into the dist/ directory. 5.3 Uploading to TestPyPI To verify that the package parses and installs correctly without affecting production indices, publish your packages to the TestPyPI repository: python -m twine upload --repository testpypi dist/* When prompted, log in using the username token and your corresponding TestPyPI API token as the password. 5.4 Uploading to PyPI Once testing succeeds, release the verified distribution packages directly to the production Python Package Index (PyPI): python -m twine upload dist/* Log in using the username token and your production PyPI API token as the password. 5.5 Automated TestPyPI Publishing via GitHub Actions Whenever a new GitHub release is published, the repository automatically builds and publishes the package to TestPyPI via the publish-testpypi.yml workflow. To enable publication, configure one of the following authentication methods on GitHub: PyPI Trusted Publishing (OIDC - Recommended): Configure a Trusted Publisher on test.pypi.org matching your GitHub repository (vyoman-labs/prism-reviewer), workflow file publish-testpypi.yml, and environment name testpypi. API Token Fallback: Alternatively, add a GitHub repository secret named TEST_PYPI_API_TOKEN containing your TestPyPI API token. 5.6 Automated Production PyPI Publishing via GitHub Actions Production releases to PyPI are managed via the dedicated publish-pypi.yml workflow. Explicit Release & Publishing Toggles You can toggle PyPI publishing in two convenient ways: Method 1: Standard GitHub Release Form (releases/new) Create a release as usual at https://github.com/vyoman-labs/prism-reviewer/releases/new. By default, publishing goes to TestPyPI. To enable PyPI publishing, simply include [pypi] or [publish-pypi] anywhere in the Release description / notes field. Method 2: Visual Checkbox Form (GitHub Actions Tab) (GitHub's native release page does not support custom HTML form checkboxes, so a visual UI form is available in GitHub Actions): Navigate to Actions > Publish Package to PyPI in your GitHub repository. Click Run workflow to open the visual checkbox modal: publish_testpypi: Checkbox to publish to TestPyPI (test.pypi.org) (Default: true). publish_pypi: Checkbox to publish to PyPI (pypi.org) (Default: false). tag_name: (Optional) Release version tag (e.g., v1.0.0). create_release: (Optional) Checkbox toggle to automatically create/publish the GitHub Release for you. OIDC Trusted Publishing Setup for PyPI To enable automated publication without managing API tokens: Go to your PyPI account on pypi.org > Account Settings > Publishing. Add a new GitHub publisher with the following details: Owner: vyoman-labs Repository: prism-reviewer Workflow name: publish-pypi.yml Environment name: pypi 💻6. CLI Usage You can invoke the review agent via the registered CLI executable: prism-review --pr --repo /path/to/your/repo --base main Or execute it as a Python module: python -m prism_reviewer.cli --pr --repo /path/to/your/repo --base main 6.1 CLI Command Options Argument Type Description --pr Flag Runs the core Prism Reviewer agentic process. --repo Path Path to the target repository (defaults to the current working directory). --base String Base branch or commit for git comparison (defaults to unstaged). --diff String Optional. Prints local git diff. Values: unstaged (default), staged, or specific commit. --structure Flag Displays the directory structure of tracked files in JSON format. --scan-deps Flag Scans project manifests (requirements.txt, package.json, pyproject.toml). --search String Run regex search query across files. --methods Path Extracts AST symbols (classes, functions, methods) from the target file. [truncated for AI cost control]