DebugMind AI

An AI-powered Python debugging and incident investigation workspace.

What it does

DebugMind AI helps you investigate Python failures end-to-end: ingest a project and error, explain the root cause, propose a fix with tests, and verify the fix in an isolated workspace — without modifying your original upload.

Core workflow

FIND → UNDERSTAND → FIX → VERIFY

1. Find — Upload a Python ZIP or point at a public GitHub repository, then provide the error.
2. Understand — Groq-backed analysis explains what went wrong, where, and why.
3. Fix — Generate a structured before/after patch and pytest tests.
4. Verify — Apply the patch in a temporary workspace and run tests safely.

Features

• Python project analysis (ZIP upload)
• Public GitHub repository analysis
• Error log upload or pasted traceback
• AI root-cause analysis (Groq)
• Evidence extraction and suggested fixes
• AI-generated code changes and pytest tests
• Safe fix verification in an isolated temp workspace
• Contextual DebugMind AI chatbot (incident-scoped)
• Incident history with search and filters
• Command menu (Ctrl+K / Cmd+K)

Architecture

flowchart LR
  UI[Next.js frontend] --> API[FastAPI backend]
  API --> Scan[Scanner / GitHub fetch]
  API --> Parse[Error parser]
  API --> DB[(SQLite)]
  API --> AI[Groq provider]
  API --> Verify[Verification engine]
  Verify --> Tmp[Temp workspace + pytest]

Loading

Layer	Responsibility
Frontend	Investigation UI, AI Core, chatbot, history
Backend	Thin routes, services, schemas, SQLite
AI	Groq via a provider abstraction (keys stay server-side)
Scanner	ZIP / GitHub zipball ingest without executing project code
Verification	Copy → patch → pytest in tempfile; cleanup after

Tech stack

Layer	Technologies
Backend	Python 3.12+, FastAPI, Pydantic, SQLAlchemy, SQLite, Uvicorn, httpx, pytest, Groq SDK
Frontend	Next.js 15, React 19, TypeScript, Tailwind CSS
AI	Groq API (backend only)
Database	SQLite

Setup

Requires Python 3.12+ and Node.js 20+.

1. Clone

git clone <your-repo-url>
cd DebugMind-AI

2. Environment variables

Copy examples (never commit real keys):

cp .env.example backend/.env
cp frontend/.env.example frontend/.env

Windows PowerShell:

Copy-Item .env.example backend\.env
Copy-Item frontend\.env.example frontend\.env

3. Backend

cd backend
python -m venv .venv

# Windows
.venv\Scripts\activate

# macOS / Linux
source .venv/bin/activate

pip install -r requirements.txt
uvicorn app.main:app --reload --port 8000

API docs: http://localhost:8000/docs
Health: http://localhost:8000/api/health

4. Frontend

cd frontend
npm install
npm run dev

App: http://localhost:3000

5. Database

SQLite is created automatically on backend startup (DATABASE_URL). No manual migration step is required for local use.

Environment variables

Names only — never commit real values.

Backend (backend/.env):

GROQ_API_KEY=
GROQ_MODEL=
DATABASE_URL=
VERIFICATION_TIMEOUT_SECONDS=
GITHUB_TIMEOUT_SECONDS=

Frontend (frontend/.env):

NEXT_PUBLIC_API_URL=

Never put API keys in frontend env files.

Usage

1. Open Analyze.
2. Choose Upload Project (ZIP) or GitHub Repository (public URL).
3. Provide the error via error.log upload or paste under What went wrong?
4. Click Analyze Error.
5. Review what / where / why / evidence.
6. Click Generate Fix, then Verify Fix.
7. Optionally ask the floating DebugMind AI chatbot about the current incident.
8. Browse past work under History.

Security

• Uploaded code is not executed during scanning.
• Verification uses an isolated temporary workspace and never mutates the original project.
• Patches are review-only until you explicitly verify.
• Path traversal protection on archives and patches.
• Pytest runs via subprocess with shell=False, timeout, and scrubbed environment.
• No automatic dependency installation during verification.
• Groq API keys stay on the backend; settings UI never shows secrets.

Project structure

DebugMind-AI/
├── backend/
│   ├── app/
│   │   ├── api/           HTTP routes
│   │   ├── core/          Config, DB, migrations helpers
│   │   ├── models/        SQLAlchemy models
│   │   ├── schemas/       Pydantic schemas
│   │   └── services/      Scan, AI, GitHub, verification, chat
│   ├── tests/
│   └── requirements.txt
├── frontend/
│   ├── app/               Next.js App Router pages
│   ├── components/        UI, analyze, chat, command, visual
│   └── lib/               API client and helpers
├── docker-compose.yml
├── .env.example
└── README.md

Testing

Backend (mocks Groq and GitHub — no live calls):

cd backend
python -m pytest

Frontend:

cd frontend
npm run typecheck
npm run build

Screenshots

Add product screenshots here after publishing (Analyze, Fix, Verify, History).

Docker

docker-compose.yml is a starting point. Create backend/.env and frontend/.env first, then:

docker compose up --build

License

No license file is included in this repository yet. Add one if you intend to open-source under a specific license.