Spaces:
Sleeping
Sleeping
| 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](https://github.com/ninjacode911/Project-Ninja-Code-Guard) — 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 | |
| ```bash | |
| 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 | |
| ```bash | |
| 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](docs/WEEK1_FOUNDATION_AND_SETUP.md) | |
| - [Week 2: GitHub Integration](docs/WEEK2_GITHUB_INTEGRATION.md) | |
| - [Week 3: Security Agent](docs/WEEK3_SECURITY_AGENT.md) | |
| - [Week 4: Performance Agent](docs/WEEK4_PERFORMANCE_AGENT.md) | |
| - [Week 5: Style Agent](docs/WEEK5_STYLE_AGENT.md) | |
| - [Week 6: RAG & Parallel Execution](docs/WEEK6_RAG_AND_PARALLEL.md) | |
| - [Week 7: Synthesizer](docs/WEEK7_SYNTHESIZER.md) | |
| - [Week 8: Dashboard](docs/WEEK8_DASHBOARD.md) | |
| - [Week 9: Polish & Evaluation](docs/WEEK9_POLISH_AND_EVALUATION.md) | |
| - [Week 10: Deployment & Launch](docs/WEEK10_DEPLOYMENT_AND_LAUNCH.md) | |
| ## License | |
| Apache 2.0 | |
| --- | |
| Built by [ninjacode911](https://github.com/ninjacode911) | |