README.md

metadata

title: Ninja Code Guard
emoji: 🛡️
colorFrom: purple
colorTo: blue
sdk: docker
app_port: 7860

Ninja Code Guard

Multi-agent code review system that reviews GitHub pull requests the way a senior engineering team would.

Three specialized AI agents — Security, Performance, and Style — analyze your code in parallel, then a Synthesizer merges their findings into a single, prioritized, non-overlapping review with inline GitHub comments.

Screenshots

Screenshots available in the GitHub repository — PR review comments, dashboard home, repo detail with health trends, and PR findings table.

How It Works

PR opened on GitHub
        │
        ▼
   Webhook received ──→ HMAC-SHA256 validated
        │
        ▼
   Redis cache check ──→ Skip if already reviewed
        │
        ▼
   Fetch PR data ──→ Diff + full file contents
        │
        ▼
   RAG Context ──→ Embed files → ChromaDB → Retrieve related code
        │
        ▼
   ┌─────────────────────────────────────────┐
   │     3 Agents run IN PARALLEL            │
   │  🔒 Security  ⚡ Performance  ✏️ Style  │
   │  Bandit+LLM    Radon+LLM     Ruff+LLM  │
   └─────────────┬───────────────────────────┘
                 │
                 ▼
   Synthesizer ──→ Deduplicate → Rank → Score → Summarize
        │
        ▼
   Post to GitHub ──→ Inline comments + Summary with Health Score

What Each Agent Does

Agent	Focus	Static Tools	Example Findings
🔒 Security	Vulnerabilities, auth, secrets	Bandit, detect-secrets	SQL injection, hardcoded API keys, weak crypto
⚡ Performance	Efficiency, scalability	Radon complexity	N+1 queries, O(n²) loops, blocking I/O
✏️ Style	Readability, maintainability	Ruff linter	Unused imports, bad naming, dead code
🧠 Synthesizer	Merge & prioritize	—	Deduplication, conflict resolution, Health Score

Tech Stack

Layer	Technology	Why
LLM	Groq (Llama-3.3-70B)	500+ tokens/sec, free 14.4K req/day
Agents	LangChain + Structured Output	Typed JSON responses, prompt templates
Backend	FastAPI	Async, auto OpenAPI docs
Vector DB	ChromaDB + sentence-transformers	RAG context, semantic code search
Cache	Upstash Redis	Prevent duplicate reviews
Database	Neon Postgres	Review history, Health Score trends
Dashboard	Next.js on Vercel	Review history, trend charts
GitHub	GitHub App (webhooks)	Inline PR comments, bot identity

Quick Start

Prerequisites

• Python 3.11+
• Groq API key (free at console.groq.com)
• GitHub App (registered at github.com/settings/apps)

Setup

git clone https://github.com/ninjacode911/Project-Ninja-Code-Guard
cd Project-Ninja-Code-Guard
python -m venv .venv && source .venv/bin/activate  # Windows: .venv\Scripts\activate
pip install -r requirements.txt

cp .env.example .env
# Edit .env with your API keys

uvicorn app.main:app --reload --port 8000

Architecture

4 Layers:

• GitHub Layer — Webhooks, PR events, inline comments
• Orchestration Layer — FastAPI, agent dispatch, asyncio.gather
• Agent Layer — 3 domain agents + synthesizer (LangChain)
• Knowledge Layer — ChromaDB (RAG), Redis (cache), Postgres (history)

Key Design Patterns:

• Template Method — All agents share a base class, override only prompt + tools
• Structured Output — LLM constrained to return valid JSON (Pydantic schema)
• Fail-Open Cache — If Redis is down, proceed with analysis
• Background Tasks — Return 200 to GitHub immediately, review asynchronously
• Parallel Execution — asyncio.gather runs 3 agents concurrently

Running Tests

pytest tests/unit/ -v  # 92 tests

Project Structure

app/
  agents/          # Security, Performance, Style, Synthesizer
  tools/           # Bandit, detect-secrets, Radon, Ruff wrappers
  context/         # RAG pipeline (embedder, indexer, retriever)
  github/          # Webhook validation, API client, comment formatter
  models/          # Pydantic schemas (Finding, SynthesizedReview)
  db/              # Redis cache, Postgres queries
  services/        # Health Score calculator
dashboard/         # Next.js frontend (Vercel)
tests/             # Unit tests + evaluation harness
prompts/           # Agent system prompts (Markdown)
docs/              # Week-by-week documentation

Documentation

Detailed week-by-week documentation in docs/:

• Week 1: Foundation & Setup
• Week 2: GitHub Integration
• Week 3: Security Agent
• Week 4: Performance Agent
• Week 5: Style Agent
• Week 6: RAG & Parallel Execution
• Week 7: Synthesizer
• Week 8: Dashboard
• Week 9: Polish & Evaluation
• Week 10: Deployment & Launch

License

Apache 2.0

---

Built by ninjacode911