🌈 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.

📖 Table of Contents

1. 🔍 System Description
2. 📐 Architecture and Flow
3. 🧠 Key Intricacies and Design Decisions
4. 🔧 Installation
5. 📦 Packaging and Distribution
6. 💻 CLI Usage
7. 🔩 Configuration Guide
8. 🔌 Running Reviews Locally via GitHub PR ID
9. 🔗 GitHub App and Integration Setup
10. 📝 Notes Limitations and Roadmap
11. 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<br/>(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<br/>Security & Compliance]
    Router -->|Region 1..N| Architect[📐 Architect Node<br/>Design & Performance]
    Router -->|Region 1..N| Inspector[🔍 Inspector Node<br/>Clean Code & Logic]
    Warden --> Join{Join}
    Architect --> Join
    Inspector --> Join
    Join --> Verifier[🛡️ Verifier Node<br/>Hallucination Guard & Deduplication]
    Verifier --> Aggregator[📊 Aggregator Node<br/>Severity Sorting & Report Render]
    Aggregator --> END([END])

Flow Execution Steps:

1. 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.
2. 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.
3. _fan_out_router (implemented in graph.py): Routes each region to all three agent nodes concurrently.
4. 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.
5. verifier_node (implemented in verifier.py): Performs double-guard filtering (hallucination checks & duplicate suppression).
6. 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"]

• 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)

1. Create a release as usual at https://github.com/vyoman-labs/prism-reviewer/releases/new.
2. By default, publishing goes to TestPyPI.
3. 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):

1. Navigate to Actions > Publish Package to PyPI in your GitHub repository.
2. 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:

1. Go to your PyPI account on pypi.org > Account Settings > Publishing.
2. 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

🔩7. Configuration Guide

Prism Reviewer uses a centralized config system driven by src/prism_reviewer/prism_reviewer.toml. Placing a prism_reviewer.toml in your repository root is optional—if omitted, Prism Reviewer automatically loads built-in package defaults. Numeric parameters are dynamically cast, and environment variable overrides are supported using the ${VAR_NAME|-default_value} format. You can define environment variables in a .env file (see .env.example) in your project root or pass them via shell environment variables.

7.1 Configuration Properties

7.1.1 GitHub Configuration [github]

7.1.2 Core LLM Configuration [llm]

7.1.3 Throttling and Resilience [llm.thresholds]

7.1.4 Agent Execution Options [agents]

7.1.5 Cognitive Reasoning Settings [agents.reasoning_effort]

7.1.6 Per-Agent Model Overrides [agents.models]

7.1.7 Code Lens Analysis [codelens]

7.1.8 Test File Classification [test_files]

7.1.9 LLM Token Monitoring & Observability [monitoring]

Observability Callbacks Setup (Langfuse & OpenTelemetry)

• Langfuse (Recommended for LLM Tracing): Set PRISM_MONITORING_LITELLM_CALLBACKS="langfuse" and configure standard Langfuse credentials (LANGFUSE_PUBLIC_KEY, LANGFUSE_SECRET_KEY, LANGFUSE_HOST). Automatically tracks generation traces, prompt/completion text, token breakdowns, and model costs.
• OpenTelemetry (Enterprise APM): Set PRISM_MONITORING_LITELLM_CALLBACKS="otel" (or PRISM_MONITORING_LITELLM_CALLBACKS="langfuse,otel" to run both concurrently) to emit standard OpenTelemetry spans and metrics to your OTel Collector or APM backend (Datadog, Honeycomb, Grafana Tempo).

7.1.10 Git Diff & Incremental Review Configuration [git]

7.2 Project Context & Custom Review Rules (.prism_reviewer/)

Prism Reviewer allows repository maintainers to significantly improve review quality, domain accuracy, and signal-to-noise ratio by supplying optional Project Context (context.md) and Custom Review Rules (rules.md).

When reviewing pull requests, the multi-agent council (Warden, Architect, Inspector) loads these files into prompt memory to evaluate code changes against your team's exact architectural standards, domain concepts, and coding policies.

7.2.1 Directory Structure

Place these markdown files inside a .prism_reviewer/ directory at the root of your target repository:

my-repository/
├── .prism_reviewer/
│   ├── context.md   # Project architecture, tech stack & domain background
│   └── rules.md     # Custom coding rules, security requirements & constraints
├── prism_reviewer.toml  # (Optional) Custom configuration overrides
└── ...

[!TIP] Both .prism_reviewer/context.md and .prism_reviewer/rules.md are automatically auto-detected by the CLI (prism-review) and local execution script (run_local.py). You can also specify custom file locations using the --context and --rules flags.

7.2.2 Project Context (.prism_reviewer/context.md)

Providing high-level background information helps agents understand design intentions, domain models, and system boundaries rather than flagging intentional design decisions.

Recommended Contents:

• System Overview & Architecture: Core purpose, key subsystems, database layers, and external service dependencies.
• Tech Stack & Libraries: Framework versions, state management tools, ORMs, and async models.
• Design Conventions: Preferred design patterns (e.g., repository pattern, dependency injection), immutability rules, or concurrency patterns.

Example context.md:

# Project Context: Payment Processing Service

## Architecture
- Microservice built with FastAPI, PostgreSQL, and Celery worker queues.
- Uses SQLAlchemy 2.0 with async sessions.

## Key Invariants
- All monetary values must be represented using integer cents or Decimal to avoid floating-point errors.
- Payment gateway API calls must be wrapped in idempotent retry blocks.

7.2.3 Custom Review Rules (.prism_reviewer/rules.md)

Repository-specific rules allow you to enforce team coding standards, security boundaries, and strict review constraints.

Recommended Contents:

• Security Constraints: Forbidden functions (e.g., eval, un-sanitized SQL formatting), credential leakage checks, CORS policies.
• Performance & Scaling Rules: N+1 query prevention, missing database index warnings, memory leak checks.
• Code Style & Maintainability: Maximum function length guidelines, docstring requirements, error handling requirements (e.g., no bare except: clauses).

Example rules.md:

# Repository Review Rules

## Security & Reliability
- NEVER execute raw SQL queries constructed via string formatting or f-strings. Use parameterized queries.
- Ensure all public API endpoints handle exceptions explicitly and return structured JSON error models.

## Code Quality & Performance
- Do not make database calls inside loops (N+1 query anti-pattern). Use batch loading or eager joins.
- All newly added functions must include static type annotations for arguments and return values.

🔌8. Running Reviews Locally via GitHub PR ID

To execute pull request reviews locally using a GitHub Pull Request ID, Prism Reviewer provides a pre-configured utility script: run_local.py. This script fetches the diff, title, and description for a remote PR, executes the Agent Council review locally, and writes the output report.

8.1 Execution Command

python scripts/run_local/run_local.py --repo "owner/repository" --pr 42 --token "YOUR_GITHUB_TOKEN"

8.2 Command Options

• --repo: The full name of the repository on GitHub (e.g., octocat/Hello-World).
• --pr: The numeric ID of the Pull Request.
• --token: Your GitHub Personal Access Token (PAT). If not provided, it falls back to the GITHUB_TOKEN environment variable.
• --output: Filepath to write the Markdown report (defaults to prism_review_report.md).

🔗9. GitHub Integration & GitHub Action Setup

Prism Reviewer can be integrated into any GitHub repository using our official GitHub Action or as a GitHub App integration.

9.1 External Repository Quickstart (Using GitHub Action)

External repositories can run automated AI code reviews on Pull Requests in 3 simple steps using our GitHub Action (vyoman-labs/prism-reviewer@v1).

Step 1: Add your LLM Provider API Key Secret

In your repository, go to Settings > Secrets and variables > Actions > New repository secret and add:

• LLM_PROVIDER_API_KEY: Your API key for Gemini, OpenRouter, OpenAI, Anthropic, or any LiteLLM-supported provider.

Step 2: Create Workflow File

Create a file named .github/workflows/prism-reviewer.yml in your repository (or copy docs/examples/prism-reviewer-external.yml):

name: Prism Reviewer AI Code Review

on:
  pull_request:
    types: [opened, synchronize, reopened]

permissions:
  contents: read
  pull-requests: write

jobs:
  review:
    name: Run AI Code Review
    runs-on: ubuntu-latest
    steps:
      - name: Checkout Codebase
        uses: actions/checkout@v4
        with:
          fetch-depth: 0 # Fetch all history for git diff comparison

      - name: Run Prism Reviewer AI
        uses: vyoman-labs/prism-reviewer@v1
        with:
          llm-api-key: ${{ secrets.LLM_PROVIDER_API_KEY }}

Step 3: Open a Pull Request

Open or update any Pull Request. Prism Reviewer will automatically analyze your code changes and post a structured review report directly to the PR comments!

9.2 Action Inputs Reference

9.3 Customizing Bot Comment Identity

By default, comments are posted under the standard github-actions[bot] identity with a prominent 🌌 Vyoman Labs | 🌈 Prism Reviewer AI report header inside the comment body.

If you prefer comments to be posted under a dedicated GitHub App Bot Name (e.g. Prism Reviewer AI[bot]):

      - name: Generate App Token
        id: app-token
        uses: actions/create-github-app-token@v1
        with:
          app-id: ${{ secrets.PRISM_REVIEWER_APP_ID }}
          private-key: ${{ secrets.PRISM_REVIEWER_PRIVATE_KEY }}

      - name: Run Prism Reviewer AI
        uses: vyoman-labs/prism-reviewer@v1
        with:
          github-token: ${{ steps.app-token.outputs.token }}
          llm-api-key: ${{ secrets.LLM_PROVIDER_API_KEY }}

9.4 GitHub App & Webhook Setup

To configure a dedicated GitHub App registration, webhooks, or LLM observability monitoring for Prism Reviewer, see the detailed documentation:

• LLM Observability & Token Usage Monitoring Guide
• GitHub App Setup Guide
• GitHub Integration Overview

📝10. Notes Limitations and Roadmap

10.1 Limitations

• Syntax Boundaries: AST CodeLens mappings support Python (.py), Java (.java), TypeScript (.ts, .tsx), JavaScript (.js, .jsx), C (.c), C++ (.cpp, .cc, .cxx, .h, .hpp), Go (.go), and Rust (.rs) via tree-sitter. Other file types fall back to plain-text indexing.
• Git Dependency: The core analysis tool relies on local system execution of the git executable (specifically git diff and git ls-files).
• LLM Rate Limits: Parallel map-reduce execution can exceed rate limits on standard API tiers. Throttling is managed via LiteLLM configurations in prism_reviewer.toml.

10.2 Project Roadmap

• Expand AST grammar coverage to additional languages as needed.
• Integrate directly with GitHub Check Runs API to highlight warnings inline inside the GitHub "Files changed" diff viewer.
• Create an interactive CLI review wizard allowing developer queries directly in the terminal.
• Provide a Dockerized workspace image for zero-dependency CI installations.

🌈11. Why Prism Reviewer?

In optics, a prism separates white light into a colorful spectrum of wavelengths.

Prism Reviewer applies the same optical concept to code review:

1. Splitting the Spectrum: It takes a single unified Pull Request delta and refracts it into three distinct analytical bands: Warden (Security), Architect (Structure & Performance), and Inspector (Clean Code & Logic).
2. Filtering the Wavelengths: The verification layer filters these individual bands, blocking noise (hallucinations) and redundant repeats (deduplication).
3. Recomposing the Light: The aggregator recombines these analyzed results back into a single clear, actionable markdown review report.

By decomposing and refocusing the code review process, Prism Reviewer ensures that every angle of your codebase receives the specialized focus it deserves.