Sentinel AI

AI-powered code review agent that finds real bugs in your pull requests

---

Sentinel AI watches your GitHub repositories and reviews every pull request with 4 specialized AI agents running in parallel. It catches security vulnerabilities, code quality issues, missing tests, and documentation gaps — then posts inline comments directly on the code.

What makes it different: Each finding gets routed to the right specialist, deduplicated across agents, and flagged for human review when confidence is low. No noise, no false positives drowning real bugs.

---

How It Works

  GitHub PR opened/synchronized
          │
          ▼
  ┌──────────────────────────────────────────┐
  │  Webhook Receiver                        │
  │  HMAC verification → Idempotency check   │
  └──────────────┬───────────────────────────┘
                 │
                 ▼
  ┌──────────────────────────────────────────┐
  │  LangGraph Orchestrator                  │
  │  Fan-out → 4 specialists in parallel     │
  │  Checkpoint/resume on every node         │
  └───┬──────┬──────┬──────┬────────────────┘
      │      │      │      │
      ▼      ▼      ▼      ▼
  ┌──────┐┌──────┐┌──────┐┌──────┐
  │Secur-││Qual- ││Tests ││ Docs │
  │ity   ││ity   ││      ││      │
  └──┬───┘└──┬───┘└──┬───┘└──┬───┘
     │       │       │       │
     └───────┴───────┴───────┘
               │
               ▼
  ┌──────────────────────────────────────────┐
  │  Aggregator                              │
  │  Dedup → Severity ranking → HITL gate    │
  └──────────────┬───────────────────────────┘
                 │
                 ▼
  ┌──────────────────────────────────────────┐
  │  GitHub Review                           │
  │  Inline comments on specific lines       │
  │  REQUEST_CHANGES for critical findings   │
  └──────────────────────────────────────────┘

---

Quick Start

Prerequisites

• Python 3.11+
• uv (package manager)
• Ollama (local LLM — no API key needed)

1. Install

git clone https://github.com/Abhii-07/Sentinel-AI.git
cd Sentinel-AI
uv sync

2. Pull the model

ollama pull qwen2.5-coder:7b

This uses ~5.8 GB VRAM. Runs on any GPU with 6+ GB, or on CPU (slower).

3. Run a real PR review

# Review a PR from any public repo
uv run python -m scripts.test_real_pr --repo "owner/repo" --pr 123

# Post inline comments on GitHub (requires GitHub App or PAT)
uv run python -m scripts.test_real_pr --repo "owner/repo" --pr 123 --comment

4. Run the test suite

uv run pytest tests/ -v

---

Tech Stack

Component	Technology	Purpose
Orchestrator	LangGraph	Parallel specialist fan-out with checkpoint/resume
API	FastAPI	Webhook receiver, health probes, HITL endpoints
LLM	Ollama / OpenAI / Anthropic	Code analysis (switchable via config)
Queue	ARQ + Redis	Async job processing for webhook events
Memory	Tiger Cloud (TimescaleDB + pgvector)	Code embeddings, hybrid retrieval
Auth	GitHub App (JWT)	Bot identity for posting reviews
Frontend	Next.js 14	Dashboard for review history and HITL
Deploy	Docker Compose	5 services: API, worker, Postgres, Redis, Nginx

---

Project Structure

Sentinel-AI/
├── api/                    # FastAPI routes + middleware
├── agents/                 # 4 specialist agents (security, quality, tests, docs)
├── core/                   # Config, OTel, BudgetGuard, audit, security, chaos
├── data/                   # Ingestion pipeline
├── docs/                   # ADRs, failure modes, threat model
├── evaluation/             # Golden dataset, recall gate, adversarial tests
├── frontend/               # Next.js 14 dashboard
├── hitl/                   # Human-in-the-loop queue + API
├── job_queue/              # ARQ worker (PR review jobs)
├── memory/                 # Tiger Cloud client, embedder, retrieval
├── models/                 # Pydantic schemas
├── nginx/                  # Reverse proxy config
├── orchestrator/           # LangGraph StateGraph + specialist nodes
├── prompts/                # Versioned YAML prompt templates
├── scripts/                # Demo commands, test tools
├── tests/                  # Unit + integration tests
├── tools/                  # LLM client, model router, GitHub client
├── webhook_receiver/       # GitHub webhook parsing + idempotency
├── docker-compose.yml      # Full stack orchestration
├── Dockerfile              # Multi-stage production build
└── pyproject.toml          # Python dependencies (uv)

---

Configuration

Variable	Default	Description
LLM_PROVIDER	stub	ollama, openai, anthropic, or stub
OLLAMA_BASE_URL	http://localhost:11434	Ollama server URL
GITHUB_WEBHOOK_SECRET	—	HMAC secret for webhook verification
GITHUB_PAT	—	GitHub Personal Access Token (fallback)
GITHUB_APP_ID	—	GitHub App ID (production bot)
OPENAI_API_KEY	—	OpenAI API key
ANTHROPIC_API_KEY	—	Anthropic API key
BUDGET_DAILY_CAP_USD	10.0	Daily LLM spend limit
POSTGRES_PASSWORD	sentinel_dev	Database password

See SETUP.md for full reference.

---

Testing

# Run all tests
uv run pytest tests/ -v

# Demo: LangGraph fan-out
uv run python -m orchestrator.test_fanout

# Demo: Full review pipeline
uv run python -m agents.test_full_review

# Demo: Observability + budget guard
uv run python -m scripts.test_observability

# Demo: Chaos + HITL
uv run python -m scripts.test_reliability

---

Deployment

# Start full stack (API + worker + Postgres + Redis + Nginx)
docker compose up --build -d

# Check status
docker compose ps

# View logs
docker compose logs -f worker

Services:

Service	Port	Purpose
api	8000	FastAPI backend
worker	—	ARQ job processor
postgres	5432	TimescaleDB + pgvector
redis	6379	Cache + job queue
nginx	80	Reverse proxy

---

License

MIT

---

Built with LangGraph + FastAPI + Tiger Cloud