Feature/root cause grouping

[KolaSailaja]

Summary

Implements Issue #144: AI-Powered Root Cause Grouping for Security Findings.

This contribution introduces a Root Cause Grouping system that analyzes related security findings, clusters them based on shared characteristics, and identifies likely root causes responsible for multiple vulnerabilities. The feature helps users prioritize high-impact fixes by addressing the underlying source rather than resolving findings individually.

Changes Made

Backend

• Added analyze_root_cause() to process findings and generate root-cause groupings.

• Created a dedicated Root Cause Grouping API endpoint:

  • GET /jobs/{job_id}/root-cause-groups

• Added root-cause grouping exports through the ML package.

• Registered the new router in main.py.

Evidence Pack Integration

• Extended Evidence Pack generation to include root-cause analysis results.

• Added:

  • rca.json

• Ensured root-cause information is packaged alongside existing audit artifacts.

Root Cause Analysis Features

• Groups related findings into clusters.

• Identifies likely source locations responsible for multiple findings.

• Returns structured grouping information including:

  • Group ID
  • Root Cause
  • Findings Count
  • Associated Findings

Example Output

{
  "job_id": "123",
  "groups": [
    {
      "group_id": "RCG-001",
      "root_cause": "database_helper.py",
      "findings_count": 15
    }
  ]
}

Verification

• Existing test suite passes successfully.
• New endpoint returns grouped findings for supported jobs.
• Evidence Pack generation includes root-cause analysis output.
• No external APIs or paid services were introduced.
• Implementation follows PatchPilot's local-first and offline architecture.

Related Issue

Closes #144

[github-actions]

⚠️ Automated Check: This PR does not strictly follow the required template. Please ensure you have not deleted any checkboxes or mandatory headings, and that you have written explanations under What this PR does and How did you test this?.

Correct PR Template

Please copy and paste the raw template below into your PR description and fill it out:

> **Before opening:** make sure there is an issue tracking this work, and link it below. PRs without a linked issue may be closed without review.

## Linked issue

Closes #

## What this PR does



## Type of change

- [ ] Bug fix
- [ ] New feature
- [ ] ML model / training pipeline
- [ ] Refactor (no behaviour change)
- [ ] Documentation
- [ ] Tests only

## ML tier (if applicable)

- [ ] Tier 1 — Triage
- [ ] Tier 2 — Predictive
- [ ] Tier 3 — Autonomous
- [ ] Not ML-related

## Stack affected

- [ ] Backend
- [ ] Frontend
- [ ] Both

---

## Changes

### Backend



-

### Frontend



-

### New dependencies



-

### Database / schema changes



-

---

## Testing

**How did you test this?**



**Checklist**

- [ ] Tested locally end-to-end (upload ZIP or GitHub URL → scan → findings returned correctly)
- [ ] New ML model falls back gracefully when model file is absent
- [ ] No new `console.error` or unhandled Python exceptions introduced
- [ ] Added or updated tests where applicable
- [ ] `requirements.txt` / `package.json` updated if new dependencies added
- [ ] New model files (`.pkl`, `.pt`, etc.) are gitignored, not committed

---

## Anything reviewers should focus on



## Screenshots (if UI changed)