notsudo

<div align="center">

# NotSudo

### Autonomous AI-Powered Cloud Agent for Code Generation, Validation & Pull Request Automation

[![Python 3.11+](https://img.shields.io/badge/python-3.11+-3776AB?style=for-the-badge&logo=python&logoColor=white)](https://www.python.org/)
[![Next.js 14](https://img.shields.io/badge/Next.js_14-000000?style=for-the-badge&logo=nextdotjs&logoColor=white)](https://nextjs.org/)
[![TypeScript](https://img.shields.io/badge/TypeScript-3178C6?style=for-the-badge&logo=typescript&logoColor=white)](https://www.typescriptlang.org/)
[![Flask](https://img.shields.io/badge/Flask-000000?style=for-the-badge&logo=flask&logoColor=white)](https://flask.palletsprojects.com/)
[![AWS](https://img.shields.io/badge/AWS-232F3E?style=for-the-badge&logo=amazonwebservices&logoColor=white)](https://aws.amazon.com/)
[![Docker](https://img.shields.io/badge/Docker-2496ED?style=for-the-badge&logo=docker&logoColor=white)](https://www.docker.com/)
[![Redis](https://img.shields.io/badge/Redis-DC382D?style=for-the-badge&logo=redis&logoColor=white)](https://redis.io/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow?style=for-the-badge)](LICENSE)

An **autonomous, LLM-powered DevOps agent** that monitors GitHub issues and pull requests, analyzes codebases with AI, generates intelligent code fixes, validates changes in isolated cloud sandboxes, and opens pull requests — all without human intervention.

**Built for developers, SREs, and platform engineers who want AI-driven automation across their software delivery lifecycle.**

[Features](#features) · [Architecture](#architecture) · [Quick Start](#quick-start) · [How It Works](#how-it-works) · [Tech Stack](#tech-stack) · [Roadmap](#roadmap)

</div>

---

## Why NotSudo?

Traditional CI/CD pipelines execute predefined steps. **NotSudo is an intelligent agent** — it reads issues, understands intent, reasons about code, generates targeted fixes, validates them in sandboxed environments, and delivers production-ready pull requests. It bridges the gap between issue tracking and code delivery with zero manual intervention.

| Traditional Automation | NotSudo |
|---|---|
| Runs pre-written scripts | Reasons about code with LLMs |
| Requires manual code changes | Generates code autonomously |
| No validation before PR | Validates in isolated sandboxes |
| Single CI provider | Multi-cloud execution (AWS Fargate, Docker) |
| One model, one provider | Multi-LLM support (Claude, GPT-4, Groq) |

---

## Features

### AI-Powered Code Intelligence
- **Multi-LLM Support** — Claude 3.5 Sonnet (via OpenRouter), GPT-4, Groq models with per-user model selection
- **Agentic Code Analysis** — Multi-turn AI reasoning with function calling for complex code changes
- **Smart File Selection** — Intelligently identifies relevant files from the entire codebase
- **Custom Rules Engine** — Define project-specific coding rules the AI follows during generation
- **Codebase Memory** — Persistent context storage per repository for improved AI decision-making

### Autonomous Code Validation & Sandboxing
- **AWS Fargate Sandbox** — Isolated serverless containers for safe code execution in production
- **Local Docker Sandbox** — Container-based validation for development environments
- **Full Stack Detection** — Auto-detects Python (pip/poetry), Node.js (npm/yarn/pnpm), Java, Go, Rust
- **Validation Pipeline** — Dependency installation, test execution, type checking (TypeScript/MyPy), linting, security scanning
- **Graceful Fallback** — Fargate → Docker → Local execution chain

### GitHub Integration & Automation
- **Webhook-Driven** — Real-time event processing for issue comments and PR feedback
- **Automated PR Creation** — Branch creation, code commits, and pull request generation
- **GitHub App Support** — OAuth-based authentication with installation tracking
- **Webhook Signature Verification** — Secure webhook validation
- **Rate Limit Handling** — Automatic backoff and retry logic

### Real-Time Dashboard & Monitoring
- **Live Job Streaming** — Socket.IO-powered real-time status updates and log streaming
- **Job History & Analytics** — Track all automation jobs with filtering and detailed views
- **Repository Management** — Connect repos, manage webhooks, view issues per repository
- **Code Diff Viewer** — Visual diff display for AI-generated changes
- **User Settings** — Per-user AI model selection, custom rules, account management

### Enterprise-Ready
- **OAuth Authentication** — GitHub and Google OAuth via Better-Auth
- **Subscription Management** — Built-in payment processing with Dodo Payments
- **PostgreSQL Support** — Production-grade database with SQLAlchemy ORM
- **Redis Job Queue** — Async task processing with Redis message queue
- **Security Scanning** — Built-in vulnerability detection for generated code

---

## Architecture

```
┌─────────────────────────────────────────────────────────────────────┐
│                          NotSudo Platform                            │
├──────────────────────────┬──────────────────────────────────────────┤
│                          │                                          │
│   Frontend (Next.js 14)  │         Backend (Flask + Python)         │
│   ┌──────────────────┐   │   ┌──────────────────────────────────┐  │
│   │ Dashboard UI      │   │   │ Webhook Handler                  │  │
│   │ Job Monitor       │   │   │ AI Service (OpenRouter / Groq)   │  │
│   │ Repo Manager      │   │   │ GitHub Service (PyGithub)        │  │
│   │ Settings Panel    │   │   │ PR Service                       │  │
│   │ Code Diff Viewer  │   │   │ Code Execution Service           │  │
│   │ OAuth Flow        │◄──┼──►│ Security Scanner                 │  │
│   └──────────────────┘   │   │ Database Layer (SQLAlchemy)       │  │
│                          │   └────────────┬─────────────────────┘  │
│   Real-time: Socket.IO   │                │                        │
│                          │   ┌────────────▼─────────────────────┐  │
│                          │   │     Execution Sandboxes           │  │
│                          │   │  ┌───────┐ ┌────────┐ ┌───────┐  │  │
│                          │   │  │AWS    │ │Docker  │ │Local  │  │  │
│                          │   │  │Fargate│ │Container│ │Exec  │  │  │
│                          │   │  └───────┘ └────────┘ └───────┘  │  │
│                          │   └──────────────────────────────────┘  │
├──────────────────────────┴──────────────────────────────────────────┤
│  External Services: GitHub API · OpenRouter · Groq · AWS (ECS/S3/  │
│  CloudWatch/ECR) · Redis · PostgreSQL · Dodo Payments              │
└─────────────────────────────────────────────────────────────────────┘
```

### Data Flow

```
GitHub Issue/PR Comment
        │
        ▼
  Webhook Handler ──► Verify Signature
        │
        ▼
  Queue Job (Redis)
        │
        ▼
  Fetch Codebase ──► Smart File Selection
        │
        ▼
  AI Analysis ──► Multi-turn LLM Reasoning (Claude / GPT-4 / Groq)
        │
        ▼
  Generate Code Changes ──► Function Calling (replace, insert, edit)
        │
        ▼
  Create Branch + Commit Changes
        │
        ▼
  Validate in Sandbox ──► AWS Fargate │ Docker │ Local
        │
        ▼
  Create Pull Request
        │
        ▼
  Stream Results ──► Socket.IO ──► Dashboard
```

---

## Quick Start

### Prerequisites

- Python 3.11+
- Node.js 18+
- Redis (optional, for production job queue)
- Docker (optional, for local sandboxing)

### 1. Clone & Install

```bash
git clone https://github.com/your-username/notsudo.git
cd notsudo

# Backend
cd backend
pip install -r requirements.txt

# Frontend
cd ../frontend
npm install
```

### 2. Configure Environment

```bash
# Backend (.env)
OPENROUTER_API_KEY=your_openrouter_key
GITHUB_TOKEN=your_github_pat
GROQ_API_KEY=your_groq_key          # Optional
REDIS_URL=redis://localhost:6379     # Optional
DATABASE_URL=postgresql://...        # Optional, defaults to SQLite

# AWS Sandbo

[truncated…]