Revise README for PipelineMedic project

.env.example

@@ -0,0 +1,45 @@
+# Copy to .env and fill in. Hackathon MVP: at least Groq + Telegram for the full demo.
+
+# --- MVP (recommended for judges) ---
+GROQ_API_KEY=
+GROQ_MODEL=llama-3.3-70b-versatile
+TELEGRAM_BOT_TOKEN=
+# Comma-separated: your DM id, group id (add bot to group first). Groups often use -100...
+TELEGRAM_CHAT_ID=
+TELEGRAM_ENABLED=true
+
+# --- Optional: Langfuse (LLM usage / cost in Langfuse UI) ---
+LANGFUSE_SECRET_KEY=
+LANGFUSE_PUBLIC_KEY=
+# EU cloud: https://eu.cloud.langfuse.com — self-hosted: your Langfuse URL
+LANGFUSE_HOST=https://cloud.langfuse.com
+
+# --- Optional stretch goals ---
+# GitHub autofix PR (leave blank to skip)
+GITHUB_TOKEN=
+GITHUB_DEFAULT_OWNER=
+GITHUB_BASE_BRANCH=main
+GITHUB_PR_REVIEWERS=
+
+# --- Optional: GitHub → Telegram on every push (repo Webhooks in GitHub UI) ---
+# GitHub repo: Settings → Webhooks → Add webhook
+#   Payload URL: https://YOUR_VERCEL_APP/github/webhook
+#   Content type: application/json
+#   Secret: generate one and paste the SAME value below (GitHub signs X-Hub-Signature-256)
+#   Events: "Just the push event"
+GITHUB_WEBHOOK_SECRET=
+# Comma-separated branch name prefixes to ignore (noise from autofix bots, dependabot).
+# GITHUB_PUSH_SKIP_BRANCH_PREFIXES=pipelinemedic/autofix-,dependabot/
+# GITHUB_PUSH_NOTIFY_DISABLED=1
+
+# --- Optional: Vercel Sandbox (AI self-verification before opening the PR) ---
+# When set, PipelineMedic spins up an ephemeral Firecracker microVM, runs the
+# AI-generated fix + regression test inside it with pytest, and only opens the
+# PR if the test passes. On Vercel deployments, OIDC is automatic — you only
+# need these three for LOCAL development (personal access token + team/project).
+VERCEL_TOKEN=
+VERCEL_TEAM_ID=
+VERCEL_PROJECT_ID=
+# Optional knobs (defaults are fine):
+# PM_SANDBOX_RUNTIME=python3.13
+# PM_SANDBOX_TIMEOUT_MS=240000

.gitignore

@@ -0,0 +1,20 @@
+.env
+.env.*
+!.env.example
+__pycache__/
+*.py[cod]
+.pytest_cache/
+.venv/
+venv/
+data/
+*.egg-info/
+.DS_Store
+
+# Vercel CLI (keep project.json for team link; ignore local cache)
+.vercel/*
+!.vercel/project.json
+
+# Next.js frontend (web/)
+web/node_modules/
+web/.next/
+web/out/

.vercel/project.json

@@ -0,0 +1,7 @@
+{
+  "projectId": "prj_QEqf9UX8AVaZxfTr0w6b9GmK67uG",
+  "orgId": "team_t5qpFfhJ6TN3SQwvz4CQG5HO",
+  "settings": {
+    "framework": null
+  }
+}

README.md

@@ -1,86 +1,219 @@
-# HackToFuture 4.0 — Template
+# PipelineMedic
 
-Welcome to your official HackToFuture 4 repository.
-
-This repository template will be used for development, tracking progress, and final submission of your project. Ensure that all work is committed here within the allowed hackathon duration.
+> Push → CI fails → POST log to this API → Groq/LLM explains the failure → Auto-fix PR + Telegram alert to your team.
 
 ---
 
-### Instructions for the teams:
+## Problem Statement / Idea
+
+**What is the problem?**
+Every modern software team relies on CI/CD pipelines (GitHub Actions, GitLab CI, Jenkins, etc.) to test and ship code. When a pipeline fails, developers have to manually dig through hundreds of lines of raw logs to figure out:
 
-- Fork the Repository and name the forked repo in this convention: hacktofuture4-team_id (for eg: hacktofuture4-A01)
+- What actually broke (a missing dependency? a flaky test? a config typo? an import error?)
+- Where to fix it (which file, which line)
+- How to fix it safely without breaking anything else
 
----
+This manual log triage is slow, repetitive, and a massive drain on engineering time — especially for small teams and during late-night on-call incidents.
 
-## Rules
+**Why is it important?**
+- A single broken build can block an entire team from merging or deploying.
+- Most CI failures fall into a small number of well-known patterns (missing packages, off-by-one test failures, typos, import errors) that are *mechanically* fixable.
+- Developer focus time is the most expensive resource in any engineering org. Context-switching into a log-dump destroys flow.
 
-- Work must be done ONLY in the forked repository
-- Only Four Contributors are allowed.
-- After 36 hours, Please make PR to the Main Repository. A Form will be sent to fill the required information.
-- Do not copy code from other teams
-- All commits must be from individual GitHub accounts
-- Please provide meaningful commits for tracking.
-- Do not share your repository with other teams
-- Final submission must be pushed before the deadline
-- Any violation may lead to disqualification
+**Who are the target users?**
+- Solo developers and indie hackers shipping fast on GitHub.
+- Hackathon and student teams who can't afford dedicated DevOps.
+- Small-to-mid engineering teams who want an "AI on-call engineer" for their CI pipeline.
+- Any team that already uses **GitHub Actions + Telegram/Slack** and wants zero-friction failure triage.
 
 ---
 
-# The Final README Template 
+## Proposed Solution
 
-## Problem Statement / Idea
+**What are we building?**
+**PipelineMedic** is an AI-powered CI/CD failure doctor. When your GitHub Actions workflow fails, it automatically:
 
-Clearly describe the problem you are solving.
+1. **Ingests** the failed build log via a simple webhook (`POST /webhook`).
+2. **Diagnoses** the root cause using **Groq (LLaMA 3.3 70B)**, with a deterministic rule-based fallback for offline demos.
+3. **Auto-patches** the code when the fix is small, surgical, and high-confidence (missing deps, clear logic bugs, imports, typos).
+4. **Verifies the fix in a sandbox** — optionally spins up a **Vercel Sandbox** (ephemeral Firecracker microVM) and re-runs the failing test before opening any PR, so we never push broken fixes.
+5. **Opens a GitHub Pull Request** with the patch, reviewers, and a human-readable explanation.
+6. **Notifies the team on Telegram** with the diagnosis, confidence, risk, and a direct link to the PR.
 
-- What is the problem?
-- Why is it important?
-- Who are the target users?
+**How does it solve the problem?**
+Instead of a developer reading logs at 11 PM, PipelineMedic turns *"your build failed"* into *"your build failed, here's exactly why, here's the fix, and by the way — here's the PR already opened and sandbox-verified."* The human stays in the loop (they review and merge), but the grunt work is gone.
+
+**What makes our solution unique?**
+- **Sandbox-verified autofixes** — we don't just suggest a patch, we *run it* inside an isolated Vercel Sandbox microVM with pytest before opening a PR. No more "AI suggested a fix that didn't actually work."
+- **LLM + rules hybrid** — works fully offline via a deterministic fallback when Groq isn't available (great for demos, air-gapped envs, and cost control).
+- **Full LLM observability** — every Groq generation is traced via **Langfuse** with token usage and cost tracking baked in.
+- **Zero-infra deploy** — one-click deploy to **Vercel** as a serverless webhook. No Kubernetes, no Docker, no babysitting.
+- **Tight Telegram loop** — alerts land where your team already lives, with the PR link attached.
 
 ---
 
-## Proposed Solution
+## Features
+
+- **`POST /webhook` CI ingest** — accepts `{ repository, log | log_text }` and returns JSON with `root_cause`, `fix`, `confidence`, `risk`, and `fixable`.
+- **Groq-powered diagnosis** (LLaMA 3.3 70B Versatile) with a strict JSON contract.
+- **Rule-based fallback** — deterministic pattern matcher for missing deps, imports, common pytest/jest failures; used whenever `GROQ_API_KEY` is absent.
+- **Automatic GitHub PR creation** — when the fix is fixable and `confidence > 0.7`, PipelineMedic commits a patch to a new branch and opens a PR via the GitHub REST API.
+- **Vercel Sandbox self-verification** — optional Firecracker microVM that runs the AI-generated fix + regression test with pytest; PR is only opened on green.
+- **Telegram alerts** — structured, human-readable message with diagnosis, confidence, risk, and PR link (when created).
+- **Langfuse observability** — automatic tracing of every LLM call with prompt/completion tokens and cost.
+- **Next.js dashboard** (`/web`) — a modern React 19 + TanStack Query frontend to browse past incidents and diagnoses.
+- **Demo-ready** — `demo.sh` and a sample failing repo under `examples/demo-repo/` for end-to-end judge demos.
 
-Explain your approach:
+---
 
-- What are you building?
-- How does it solve the problem?
-- What makes your solution unique?
+## Tech Stack
+
+**Frontend**
+- [Next.js 15](https://nextjs.org/) (App Router, Turbopack)
+- [React 19](https://react.dev/)
+- [TanStack Query v5](https://tanstack.com/query)
+- [Tailwind CSS v4](https://tailwindcss.com/)
+- [TypeScript 5](https://www.typescriptlang.org/)
+
+**Backend**
+- [Python 3.13](https://www.python.org/)
+- [FastAPI](https://fastapi.tiangolo.com/) + [Uvicorn](https://www.uvicorn.org/)
+- Pure REST webhook — no framework lock-in.
+
+**Database / Storage**
+- Lightweight JSON memory under `data/` for demos.
+- (Pluggable — can be swapped for Vercel Postgres / Neon / Upstash in production.)
+
+**APIs / Services**
+- [Groq API](https://groq.com/) — LLaMA 3.3 70B Versatile inference.
+- [GitHub REST API](https://docs.github.com/en/rest) — branch, commit, and PR creation.
+- [Telegram Bot API](https://core.telegram.org/bots/api) — team alerts.
+- [Vercel Sandbox](https://vercel.com/docs/vercel-sandbox) — ephemeral microVM fix verification.
+- [Langfuse](https://langfuse.com/) — LLM tracing, token usage, and cost analytics.
+
+**Tools / Libraries**
+- `requests` — HTTP client for Groq, GitHub, Telegram.
+- `python-dotenv` — environment management.
+- `langfuse` — LLM observability SDK.
+- `@tanstack/react-query` — server-state management on the dashboard.
+- **Vercel** — hosting for the serverless webhook and the Next.js dashboard.
 
 ---
 
-## Features
+## Project Setup Instructions
 
-List the core features of your project:
+### Prerequisites
+- Python **3.11+** (3.13 recommended)
+- Node.js **20+** (only if running the dashboard under `/web`)
+- A [Groq API key](https://console.groq.com/keys) (free tier works)
+- A Telegram bot token + chat id ([guide](https://core.telegram.org/bots#how-do-i-create-a-bot))
+- *(Optional)* A GitHub PAT with `Contents` + `Pull Requests` scope for real auto-PRs.
 
-- Feature 1
-- Feature 2
-- Feature 3
+### 1. Clone the repository
 
----
+```bash
+git clone https://github.com/Aqib053/hacktofuture4-D01.git
+cd hacktofuture4-D01
+```
 
-## Tech Stack
+### 2. Install backend dependencies
 
-Mention all technologies used:
+```bash
+python3 -m venv .venv
+source .venv/bin/activate       # Windows: .venv\Scripts\activate
+pip install -r requirements.txt
+```
 
-- Frontend:
-- Backend:
-- Database:
-- APIs / Services:
-- Tools / Libraries:
+### 3. Configure environment variables
 
----
+```bash
+cp .env.example .env
+```
 
-## Project Setup Instructions
+Then edit `.env` and fill in **at least**:
+
+```env
+GROQ_API_KEY=gsk_...
+TELEGRAM_BOT_TOKEN=123456:ABC...
+TELEGRAM_CHAT_ID=your_chat_id
+```
+
+Optional for auto-PRs and sandbox verification:
+
+```env
+GITHUB_TOKEN=ghp_...
+VERCEL_TOKEN=...
+VERCEL_TEAM_ID=...
+VERCEL_PROJECT_ID=...
+```
 
-Provide clear steps to run your project:
+### 4. Run the backend
 
 ```bash
-# Clone the repository
-git clone <repo-link>
+python main.py
+# API running at http://127.0.0.1:8000
+```
+
+Health check: `GET http://127.0.0.1:8000/` should return `{"status":"ok", ...}`.
+
+### 5. Try the demo
 
-# Install dependencies
-...
+In another terminal:
 
-# Run the project
-...
+```bash
+chmod +x demo.sh
+./demo.sh
 ```
+
+This POSTs a sample failing CI log to `/webhook` and you should see:
+- A JSON diagnosis in the terminal
+- A Telegram alert (if configured)
+- A PR opened against your target repo (if `GITHUB_TOKEN` is set)
+
+### 6. *(Optional)* Run the Next.js dashboard
+
+```bash
+cd web
+npm install
+npm run dev
+# Dashboard at http://localhost:3000
+```
+
+### 7. Deploy to Vercel (public webhook)
+
+```bash
+npm i -g vercel
+vercel --prod
+```
+
+Set the same env vars in the Vercel project dashboard, then point your GitHub Actions workflow at:
+
+```
+https://<your-project>.vercel.app/webhook
+```
+
+Store that URL as a repo secret named `PIPELINEMEDIC_WEBHOOK_URL`.
+
+---
+
+## Repository Structure
+
+```
+PipeLinMedic2.0/
+├── main.py                 # FastAPI webhook + Groq + GitHub PR + Telegram + Sandbox
+├── app.py                  # Vercel entrypoint
+├── requirements.txt
+├── vercel.json
+├── demo.sh                 # End-to-end local demo script
+├── .env.example
+├── examples/
+│   └── demo-repo/          # Sample failing repo for judge demos
+├── web/                    # Next.js 15 dashboard (App Router)
+└── data/                   # JSON incident memory
+```
+
+---
+
+## License
+
+MIT — use it, fork it, ship it.

app.py

@@ -0,0 +1,5 @@
+"""Vercel entrypoint — re-exports ASGI app."""
+
+from main import app
+
+__all__ = ["app"]

demo.sh

@@ -0,0 +1,31 @@
+#!/usr/bin/env bash
+# Hackathon demo: POST a sample failing CI log to the local webhook.
+# Usage: ./demo.sh [webhook_url]
+#   PIPELINEMEDIC_URL=http://127.0.0.1:8000 ./demo.sh
+
+set -euo pipefail
+URL="${1:-${PIPELINEMEDIC_URL:-http://127.0.0.1:8000}/webhook}"
+
+exec python3 - "$URL" <<'PY'
+import json, sys, urllib.request
+
+url = sys.argv[1]
+body = json.dumps(
+    {
+        "repository": "demo/hackathon",
+        "log": "ModuleNotFoundError: No module named 'requests'",
+    }
+).encode("utf-8")
+req = urllib.request.Request(
+    url,
+    data=body,
+    headers={"Content-Type": "application/json"},
+    method="POST",
+)
+with urllib.request.urlopen(req, timeout=30) as resp:
+    raw = resp.read().decode("utf-8", errors="replace")
+try:
+    print(json.dumps(json.loads(raw), indent=2))
+except json.JSONDecodeError:
+    print(raw)
+PY